1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240import { test } from "node:test";
import assert from "node:assert/strict";
import express from "express";
import type { AddressInfo } from "node:net";
import type { QualityStats, Store } from "../src/store/db.ts";
import { qualityRouter } from "../src/routes/quality.ts";
// The route half of `GET /v1/quality`. test/quality.test.ts covers what
// the numbers mean; this covers the two things only the route decides — who is let in,
// and whether a window's answer can be served for a different window.
//
// The guard is the part worth pinning. The auth middleware is never attached to this route
// (src/index.ts), and it is one of four that are not, so its own shared secret is the ONLY
// thing standing between a deployment-wide quality report and anyone who guesses the path.
// That is deliberate: the caller is a CI job that must reach the tally on a gated deployment
// while holding no `server.api_token`. A regression here is invisible — the endpoint keeps
// answering correctly for the workflow either way.
const TOKEN = "s3cret-quality-token";
function fakeStore(): { store: Store; state: { calls: number; days: number[] } } {
const state = { calls: 0, days: [] as number[] };
const store = {
qualityStats({ days }: { days?: number } = {}) {
state.calls++;
// The route is expected to have clamped already, so this mirror of the clamp
// should be a no-op on everything it receives — which is exactly what makes
// `state.days` worth asserting: it records the window the query RAN under, and
// the cache is required to be keyed on that same value.
const w = Math.min(365, Math.max(1, Math.floor(Number(days)) || 30));
state.days.push(w);
return {
window_days: w,
documents: 10,
since: "2026-01-01T00:00:00.000Z",
mean_rounds: 1.5,
unresolved_rate: 0.1,
first_read: { documents: 10, mean_issues: 1.4, unread_documents: 0 },
unresolved_severity: [
{ severity: "high", documents: 0 },
{ severity: "medium", documents: 0 },
{ severity: "low", documents: 1 },
{ severity: "unrated", documents: 0 },
],
review_stopped: [
{ where: "clean", documents: 9 },
{ where: "unread", documents: 0 },
{ where: "converged", documents: 1 },
{ where: "truncated", documents: 0 },
{ where: "cap", documents: 0 },
],
links_dropped_rate: 0,
links_unresolved_rate: 0,
markup_unbalanced_rate: 0,
table_no_body_rate: 0,
structural_defect_rate: 0,
lint_error_rate: 0,
lint_error_where: [
{ where: "parse", documents: 0 },
{ where: "inject", documents: 0 },
{ where: "run", documents: 0 },
],
documents_linted: 10,
editor_truncated_rate: 0,
editor_truncated_lost_rate: 0,
editor_headings_gated_rate: 0,
review_unread_rate: 0,
unfinished_page_rate: 0,
rules: [{ id: "heading-order", impact: "moderate", documents: 4, share: 0.4, nodes: 9 }],
} satisfies QualityStats;
},
} as unknown as Store;
return { store, state };
}
async function serve(router: express.Router): Promise<{
get: (query?: string, init?: RequestInit) => Promise<Response>;
close: () => void;
}> {
const app = express();
app.use("/v1/quality", router);
const server = app.listen(0);
await new Promise((r) => server.once("listening", r));
const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}/v1/quality`;
return { get: (query = "", init) => fetch(base + query, init), close: () => server.close() };
}
const auth = { headers: { authorization: `Bearer ${TOKEN}` } };
test("an unconfigured deployment does not acknowledge the endpoint", async () => {
const { store, state } = fakeStore();
const srv = await serve(qualityRouter(store, {}));
try {
// 404 rather than 401 or 503, deliberately: a deployment that has not opted in
// reveals nothing about whether the operator merely forgot a token. And a 404 with
// no token configured must not be reachable by guessing one.
for (const init of [undefined, auth]) {
const res = await srv.get("", init);
assert.equal(res.status, 404);
}
assert.equal(state.calls, 0, "and the table is never scanned for a caller that cannot read it");
} finally {
srv.close();
}
});
test("a missing, malformed or wrong token is rejected without touching the store", async () => {
const { store, state } = fakeStore();
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }));
try {
const rejected: (RequestInit | undefined)[] = [
undefined,
{ headers: { authorization: "" } },
{ headers: { authorization: TOKEN } }, // no Bearer prefix
{ headers: { authorization: `Bearer ${TOKEN}x` } }, // right prefix, wrong token
{ headers: { authorization: `Bearer ${TOKEN.slice(0, -1)}` } }, // one char short
{ headers: { authorization: "Bearer " } },
];
for (const init of rejected) {
const res = await srv.get("", init);
assert.equal(res.status, 401, `expected 401 for ${JSON.stringify(init ?? null)}`);
}
// The cost matters as much as the status: an unauthenticated caller must not be
// able to make this deployment scan its signals table.
assert.equal(state.calls, 0);
} finally {
srv.close();
}
});
test("a valid token gets the tally, and the response is never shared-cached", async () => {
const { store } = fakeStore();
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }));
try {
const res = await srv.get("", auth);
assert.equal(res.status, 200);
// no-store, unlike /v1/stats' public max-age: this response is gated by a secret,
// and a proxy that cached it would hand it to a request presenting none.
assert.equal(res.headers.get("cache-control"), "no-store");
const body = (await res.json()) as QualityStats;
assert.equal(body.documents, 10);
assert.equal(body.rules[0].id, "heading-order");
} finally {
srv.close();
}
});
test("the bearer prefix is matched case-insensitively, as the header spec allows", async () => {
const { store } = fakeStore();
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }));
try {
const res = await srv.get("", { headers: { authorization: `bearer ${TOKEN}` } });
assert.equal(res.status, 200);
} finally {
srv.close();
}
});
test("each window is cached separately, so one window's answer is never served for another", async () => {
const { store, state } = fakeStore();
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }, { ttlMs: 60_000 }));
try {
const a = (await (await srv.get("?days=30", auth)).json()) as QualityStats;
const b = (await (await srv.get("?days=90", auth)).json()) as QualityStats;
assert.equal(a.window_days, 30);
// The bug a single-slot cache would produce: 90 days answered with 30-day numbers,
// wrong in a way nothing in the response reveals — which is why the window is
// echoed back at all.
assert.equal(b.window_days, 90);
assert.equal(state.calls, 2);
// ...and each is then genuinely cached.
await srv.get("?days=30", auth);
await srv.get("?days=90", auth);
assert.equal(state.calls, 2, "a second read inside the TTL reuses the first answer");
} finally {
srv.close();
}
});
test("windows that clamp to the same number share one cache entry", async () => {
const { store, state } = fakeStore();
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }, { ttlMs: 60_000 }));
try {
// `days=0` and an absent `days` both mean 30 (the codebase's normalizer idiom), so
// recomputing identical numbers under two keys would be pure waste.
await srv.get("?days=0", auth);
await srv.get("", auth);
await srv.get("?days=30", auth);
assert.equal(state.calls, 1);
assert.deepEqual(state.days, [30]);
} finally {
srv.close();
}
});
test("the cache cannot be grown past one entry per legal window", async () => {
const { store, state } = fakeStore();
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }, { ttlMs: 60_000 }));
try {
// Every one of these is the same 365-day answer. Keying the cache on what was
// ASKED for rather than what was served would add a permanent entry per distinct
// query string, none of which is ever hit again — a caller holding the token could
// grow the map without limit, and would recompute the tally every time while doing
// it. Nothing evicts, so "bounded by the clamp" has to be true rather than stated.
for (const q of ["?days=1000", "?days=1001", "?days=99999", "?days=365"]) {
const body = (await (await srv.get(q, auth)).json()) as QualityStats;
assert.equal(body.window_days, 365, `${q} should be answered with the maximum window`);
}
assert.equal(state.calls, 1, "one query for four requests that mean the same window");
assert.deepEqual(state.days, [365]);
// Same on the other end, including the garbled and negative cases the route is
// deliberately lenient about.
for (const q of ["?days=-5", "?days=nonsense", "?days=", "?days=0.4"]) {
const body = (await (await srv.get(q, auth)).json()) as QualityStats;
assert.ok(body.window_days === 1 || body.window_days === 30, `${q} gave ${body.window_days}`);
}
assert.ok(state.calls <= 3, `expected at most one entry per clamped window, got ${state.calls}`);
} finally {
srv.close();
}
});
test("an expired entry is recomputed", async () => {
const { store, state } = fakeStore();
// ttlMs is why the cache is injectable: the production default is five minutes, and
// the claim that a stuck workflow cannot scan the table per request has to be
// asserted rather than assumed.
const srv = await serve(qualityRouter(store, { quality_token: TOKEN }, { ttlMs: 1 }));
try {
await srv.get("", auth);
await new Promise((r) => setTimeout(r, 5));
await srv.get("", auth);
assert.equal(state.calls, 2);
} finally {
srv.close();
}
});