diff --git a/scripts/lib/docs-system.ts b/scripts/lib/docs-system.ts index 4f7b4148..c341a610 100644 --- a/scripts/lib/docs-system.ts +++ b/scripts/lib/docs-system.ts @@ -726,8 +726,6 @@ export function checkDocsSystem(documentsRoot: string, repositoryRoot: string): /** Living documents under `root` whose references verify:documentation checks. */ export function livingDocuments(root: string): string[] { - return readDocuments(root) - .map(({ path }) => path) - .filter(checkedForDrift); + return treeFiles(root).filter((path) => path.endsWith(".md") && !NOT_DOCUMENT.test(path) && checkedForDrift(path)); } diff --git a/tests/unit/documentation-readiness.test.ts b/tests/unit/documentation-readiness.test.ts index a281e44c..e5241f4e 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -50,6 +50,13 @@ async function verify( } } +/** + * Each case spawns verify:documentation, which reads every document. On a + * loaded host (the FE-GATE-020 drills run this file inside their copies) one + * run took more than the 10 s default. + */ +const VERIFY_TIMEOUT = 60_000; + function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") { return verify({ [document]: mutate }); } @@ -66,7 +73,7 @@ describe("verify:documentation on this repository", () => { encoding: "utf8", }); expect(result.status, `${result.stderr}${result.stdout}`).toBe(0); - }, 60_000); + }, VERIFY_TIMEOUT); }); const gitEnvironment = { @@ -133,7 +140,7 @@ describe("verify:documentation failure output (1101/14-06)", () => { it("passes the documents as they are", async () => { const result = await verifyWithReadme((readme) => readme); expect(result.status, result.stderr).toBe(0); - }); + }, VERIFY_TIMEOUT); it("names the route ID that has no manual review record", async () => { const result = await verify({}, ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"]); @@ -141,7 +148,7 @@ describe("verify:documentation failure output (1101/14-06)", () => { expect(result.stderr).toContain("artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_PLATFORM"); expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u); expect(result.stderr).not.toContain("scoped-review evidence"); - }); + }, VERIFY_TIMEOUT); it("names every failed check", async () => { const result = await verify( @@ -150,7 +157,7 @@ describe("verify:documentation failure output (1101/14-06)", () => { ); expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET"); expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u); - }); + }, VERIFY_TIMEOUT); }); // 1101/14-05. README and the manual checklist listed every route ID, so each @@ -168,7 +175,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => { "docs/accessibility/manual-checklist.md": (checklist) => checklist.replaceAll(ROUTE_IDS, ""), }); expect(result.status, result.stderr).toBe(0); - }); + }, VERIFY_TIMEOUT); it.each([ ["README.md", "scripts/verify-documentation-readiness.ts", "scripts/verify-documentation-readyness.ts"], @@ -180,7 +187,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => { expect(result.status).toBe(1); expect(result.stderr).toContain(`${document} names paths that do not exist: ${after}`); expect(result.stderr).toMatch(/\(failed: document references\)/u); - }); + }, VERIFY_TIMEOUT); it("fails when docs/README.md links a document that does not exist", async () => { const result = await verifyWithReadme( @@ -189,7 +196,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => { ); expect(result.status).toBe(1); expect(result.stderr).toContain("docs/README.md names paths that do not exist: docs/architecture/layer.md"); - }); + }, VERIFY_TIMEOUT); it("fails when a document names a package script or a gate ID that does not exist", async () => { const result = await verify({ @@ -199,12 +206,12 @@ describe("verify:documentation current contract documents (1101/14-05)", () => { expect(result.status).toBe(1); expect(result.stderr).toContain("README.md names package scripts that do not exist: verify:documentaton"); expect(result.stderr).toContain("docs/README.md names gate IDs that config/ci/gates.json does not define: FE-GATE-099"); - }); + }, VERIFY_TIMEOUT); it("does not ask generated output to exist", async () => { const result = await verifyWithReadme((readme) => `${readme}\nSee \`artifacts/quality/not-generated-yet.json\`.\n`); expect(result.status, result.stderr).toBe(0); - }); + }, VERIFY_TIMEOUT); it("accepts a path under history a copy deleted, and only that", async () => { const naming = (readme: string) => `${readme}\nSee \`docs/retired-notes/plan.md\`.\n`; @@ -216,7 +223,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => { const missing = await verifyWithReadme(naming); expect(missing.status).toBe(1); expect(missing.stderr).toContain("README.md names paths that do not exist: docs/retired-notes/plan.md"); - }); + }, VERIFY_TIMEOUT); }); // 1103/12-05. Paths inside a command and links into the paired repositories @@ -233,7 +240,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { const result = await verify({ [CI_DOC]: (text) => `${text}\n${line}\n` }); expect(result.status).toBe(1); expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: tests/integration/no-such-client.test.ts`); - }); + }, VERIFY_TIMEOUT); it("looks up a command's existing arguments and leaves placeholders alone", async () => { const result = await verify({ @@ -242,7 +249,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { "Any script is run as `node scripts/…`.\n", }); expect(result.status, result.stderr).toBe(0); - }); + }, VERIFY_TIMEOUT); it("checks a link or a path into a paired repository checked out beside this one", async () => { const naming = (target: string) => (text: string) => @@ -267,7 +274,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { expect(broken.stderr).toContain( `${CI_DOC} names paths that do not exist: ../clean-architecture-backend-template/docs/web/no-such.md`, ); - }); + }, VERIFY_TIMEOUT); it("reports a link into a paired repository that is not checked out as unverified", async () => { const result = await verify({ @@ -277,7 +284,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { expect(result.stdout).toContain("not verified"); expect(result.report?.documentReferences.find((entry) => entry.path === CI_DOC)?.unverifiedLinks) .toEqual(["../clean-architecture-backend-template/docs/web/no-such.md"]); - }); + }, VERIFY_TIMEOUT); }); // 1105/12-02. Paired references were looked up in the working tree of the @@ -322,7 +329,7 @@ describe("verify:documentation paired references at the pinned commit (1105/12-0 ]); expect(entryOf(result)?.unverifiedLinks).toEqual([]); expect(result.stderr).toContain("at the pinned commit (looked up in clean-architecture-backend-template "); - }); + }, VERIFY_TIMEOUT); it("reports the references as not verified when the checkout does not have the pinned commit", async () => { // The desktop case: a sibling whose history stops before the pin, with @@ -336,14 +343,14 @@ describe("verify:documentation paired references at the pinned commit (1105/12-0 expect(entryOf(result)?.unverifiedLinks).toEqual([`../${PAIRED_BACKEND}/docs/web/no-such.md`]); expect(result.stdout).toContain("not verified"); expect(result.stdout).toContain("does not have the pinned commit"); - }); + }, VERIFY_TIMEOUT); it("fails a link out of the repository into a repository that is not paired", async () => { const misspelled = "clean-architecture-backend-templat/docs/web/http-contract.md"; const result = await verify({ [CI_DOC]: (text) => `${text}\n[contract](../../../${misspelled})\n` }); expect(result.status).toBe(1); expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: ../${misspelled}`); - }); + }, VERIFY_TIMEOUT); }); // 1101/14-03. The entry documents drew a top-level domain layer that does not @@ -360,7 +367,7 @@ describe("verify:documentation source structure (1101/14-03)", () => { "docs/architecture/layers.md does not name .dependency-cruiser.json rules: platform-kernel-is-product-neutral", ); expect(result.stderr).toMatch(/\(failed: source structure\)/u); - }); + }, VERIFY_TIMEOUT); it("fails when a document names a top-level src folder that does not exist", async () => { const result = await verifyWithReadme((readme) => @@ -368,7 +375,7 @@ describe("verify:documentation source structure (1101/14-03)", () => { ); expect(result.status).toBe(1); expect(result.stderr).toContain("README.md names src folders that do not exist: domain"); - }); + }, VERIFY_TIMEOUT); it("fails when a document describes a folder differently from layers.md", async () => { const result = await verifyWithReadme( @@ -379,5 +386,5 @@ describe("verify:documentation source structure (1101/14-03)", () => { expect(result.stderr).toContain( "docs/architecture/overview.md does not describe src folders as the layers.md table does: platform", ); - }); + }, VERIFY_TIMEOUT); });