mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-19 00:12:18 +00:00
walkSourceFiles now lists each indexed folder (src, e2e, prisma) once per worker and filters it by prefix, readSource and readSourceFolder read through the same memoised file cache, and readSourceText is the cached read for guards that read files themselves. The guards project shares a module graph per worker, so a file is read once however many guards ask for it. sourcesContaining adds the substring pre-filter for sweeps that look for a few markers. Every guard over 1.5 s now reads through it; anything outside the indexed folders is read from disk as before.
188 lines
7.7 KiB
TypeScript
188 lines
7.7 KiB
TypeScript
/**
|
|
* Every idempotent route says so in the contract, and only those do.
|
|
*
|
|
* `withIdempotency` has wrapped writes since v1.5.x. `Idempotency-Key` appeared
|
|
* in a dozen route comments and in no published schema, so an app generated
|
|
* against `docs/api/openapi.yaml` could not tell that a retry was safe — which
|
|
* is exactly what the iOS side asked for. Publishing it once is easy; keeping
|
|
* it published as routes come and go is what this guard is for.
|
|
*
|
|
* Both directions matter, and for different reasons:
|
|
*
|
|
* - A route that gains `withIdempotency` and forgets to publish it leaves the
|
|
* capability invisible, which is today's defect repeating itself.
|
|
* - A route that publishes the parameter and drops the wrapper is worse: the
|
|
* contract then promises a retry is safe when it is not, and a client that
|
|
* believes it writes twice.
|
|
*
|
|
* The wrapper is the source of truth here, not this file. Nothing is
|
|
* hand-listed: the expected set is read out of the route tree on every run, so
|
|
* the guard cannot fall behind the code it watches.
|
|
*/
|
|
import { readdirSync } from "node:fs";
|
|
import { join, relative, sep } from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import { buildOpenApiDocument } from "@/lib/openapi/registry";
|
|
import { readSourceText } from "./helpers/source-files";
|
|
|
|
const API_ROOT = join(process.cwd(), "src", "app", "api");
|
|
|
|
/** Every `route.ts` under `src/app/api`, tests excluded. */
|
|
function routeFiles(dir: string): string[] {
|
|
const found: string[] = [];
|
|
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
const full = join(dir, entry.name);
|
|
if (entry.isDirectory()) {
|
|
if (entry.name === "__tests__") continue;
|
|
found.push(...routeFiles(full));
|
|
continue;
|
|
}
|
|
if (entry.name === "route.ts") found.push(full);
|
|
}
|
|
return found;
|
|
}
|
|
|
|
/** `src/app/api/medications/[id]/intake/route.ts` -> `/api/medications/{id}/intake` */
|
|
function toOpenApiPath(file: string): string {
|
|
const rel = relative(API_ROOT, file).split(sep).slice(0, -1);
|
|
const segments = rel.map((s) =>
|
|
s.startsWith("[") && s.endsWith("]") ? `{${s.slice(1, -1)}}` : s,
|
|
);
|
|
return `/api/${segments.join("/")}`;
|
|
}
|
|
|
|
/**
|
|
* Method-level, not path-level, and the difference is the whole point.
|
|
*
|
|
* `/api/measurements` exports GET, POST, PUT and DELETE, and only POST is
|
|
* wrapped:
|
|
*
|
|
* export const POST = apiHandler(withIdempotency<[NextRequest]>(postMeasurement));
|
|
* export const PUT = apiHandler(putMeasurement);
|
|
*
|
|
* A path-level check would go green on that path the moment ANY operation
|
|
* declared the header, and publishing it on PUT as well would promise a safe
|
|
* retry the server does not honour. So the unit here is `POST /api/x`, and the
|
|
* matcher requires the wrapper in the same assignment as the export.
|
|
*/
|
|
function idempotentOperationsFromSource(): Set<string> {
|
|
const found = new Set<string>();
|
|
// `export const POST = ...withIdempotency...` up to the end of that
|
|
// statement. Non-greedy to the next top-level `export const`, so a wrapped
|
|
// POST cannot lend its wrapper to the PUT declared below it.
|
|
const pattern =
|
|
/export\s+const\s+(POST|PUT|PATCH|DELETE)\s*=\s*([\s\S]*?)(?=\n(?:export\s+const|export\s+async\s+function|$))/g;
|
|
for (const file of routeFiles(API_ROOT)) {
|
|
const source = readSourceText(file);
|
|
if (!source.includes("withIdempotency")) continue;
|
|
for (const match of source.matchAll(pattern)) {
|
|
if (!/\bwithIdempotency\s*[(<]/.test(match[2])) continue;
|
|
found.add(`${match[1].toLowerCase()} ${toOpenApiPath(file)}`);
|
|
}
|
|
}
|
|
return found;
|
|
}
|
|
|
|
/** Operations in the emitted document that declare the `Idempotency-Key`. */
|
|
function idempotentOperationsFromContract(): Set<string> {
|
|
const doc = buildOpenApiDocument() as {
|
|
paths?: Record<string, Record<string, unknown>>;
|
|
};
|
|
const found = new Set<string>();
|
|
for (const [path, item] of Object.entries(doc.paths ?? {})) {
|
|
for (const [method, operation] of Object.entries(item)) {
|
|
const parameters = (operation as { parameters?: unknown })?.parameters;
|
|
if (!Array.isArray(parameters)) continue;
|
|
const declares = parameters.some(
|
|
(p) => (p as { name?: string })?.name === "Idempotency-Key",
|
|
);
|
|
if (declares) found.add(`${method.toLowerCase()} ${path}`);
|
|
}
|
|
}
|
|
return found;
|
|
}
|
|
|
|
/**
|
|
* Idempotent operations that cannot be published, because the PATH is not in
|
|
* the document at all. A header cannot hang on a path that does not exist.
|
|
*
|
|
* One entry, and the list was four until the test below refused it. The first
|
|
* draft claimed the whole `/api/medications` family was missing, on the
|
|
* strength of a grep for path literals in `src/lib/openapi/routes/` that came
|
|
* back empty. It came back empty because those paths are not written as
|
|
* searchable literals there — the emitted document carries them, including
|
|
* every one the iOS client actually argues about. Measure the artefact, not
|
|
* the source that builds it.
|
|
*
|
|
* `/api/insights/feedback` left this list when the route joined the route
|
|
* table, and the leg below is what made that a diff rather than a permanent
|
|
* exemption: the moment the path appeared in the document, the entry claiming
|
|
* it could not be published became false and the run went red. An exemption
|
|
* nobody removes is how a gap becomes furniture.
|
|
*
|
|
* Listed rather than filtered silently, so the exclusion stays visible in the
|
|
* file that would otherwise claim full coverage.
|
|
*/
|
|
const UNPUBLISHED_PATHS: Readonly<Record<string, string>> = {};
|
|
|
|
describe("idempotency — the contract matches the wrapper", () => {
|
|
it("finds idempotent operations in the source tree at all", () => {
|
|
// Without this the two comparisons below could both pass on empty sets,
|
|
// which is the failure mode this whole file exists to prevent elsewhere.
|
|
const fromSource = idempotentOperationsFromSource();
|
|
expect(fromSource.size).toBeGreaterThan(20);
|
|
});
|
|
|
|
it("publishes the header on every route that wraps withIdempotency", () => {
|
|
const fromSource = idempotentOperationsFromSource();
|
|
const fromContract = idempotentOperationsFromContract();
|
|
|
|
const unpublished = [...fromSource]
|
|
.filter((p) => !fromContract.has(p))
|
|
.filter((p) => !(p.split(" ")[1] in UNPUBLISHED_PATHS))
|
|
.sort();
|
|
|
|
expect(
|
|
unpublished,
|
|
`These routes accept an Idempotency-Key and do not say so in the ` +
|
|
`contract, so a generated client cannot know a retry is safe. Add ` +
|
|
`\`idempotencyKeyParameter\` to the write operation and ` +
|
|
`\`...idempotentWrite()\` to its responses.`,
|
|
).toEqual([]);
|
|
});
|
|
|
|
it("keeps the unpublished list honest — every entry is still absent", () => {
|
|
const doc = buildOpenApiDocument() as { paths?: Record<string, unknown> };
|
|
const present = Object.keys(doc.paths ?? {});
|
|
|
|
const nowPublished = Object.keys(UNPUBLISHED_PATHS)
|
|
.filter((p) => present.includes(p))
|
|
.sort();
|
|
|
|
expect(
|
|
nowPublished,
|
|
`These paths are in the contract now, so their exemption above is stale. ` +
|
|
`Delete the entry and add \`idempotencyKeyParameter\` to the operation ` +
|
|
`— an exemption nobody removes is how a gap becomes permanent.`,
|
|
).toEqual([]);
|
|
});
|
|
|
|
it("does not promise idempotency on a route that dropped the wrapper", () => {
|
|
const fromSource = idempotentOperationsFromSource();
|
|
const fromContract = idempotentOperationsFromContract();
|
|
|
|
const overclaimed = [...fromContract]
|
|
.filter((p) => !fromSource.has(p))
|
|
.sort();
|
|
|
|
expect(
|
|
overclaimed,
|
|
`The contract offers an Idempotency-Key on these paths and no handler ` +
|
|
`honours it. A client that trusts this writes twice on a retry — the ` +
|
|
`more dangerous of the two directions.`,
|
|
).toEqual([]);
|
|
});
|
|
});
|