From 7b09c215f0da7736cb90fb53bc900381fa9f8d32 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 23:25:51 +0900 Subject: [PATCH] =?UTF-8?q?test(docs):=20verify:documentation=EC=9D=84=20?= =?UTF-8?q?=EB=9D=84=EC=9A=B0=EB=8A=94=20=EC=8B=9C=ED=97=98=EC=97=90=20?= =?UTF-8?q?=EB=84=89=EB=84=89=ED=95=9C=20=EC=8B=9C=EA=B0=84=EC=9D=84=20?= =?UTF-8?q?=EC=A4=80=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: tests/unit/documentation-readiness.test.ts의 사례마다 verify:documentation을 새 프로세스로 띄운다. 이 브랜치에서 그 검사가 살아 있는 문서 전부를 읽게 돼 한 번 도는 시간이 늘었고, 부하가 큰 desktop(load 25)에서 FE-GATE-020의 기능 생성 드릴이 사본 안에서 이 파일을 돌릴 때 세 사례가 기본 시간 10초를 넘겨 실패했다. 같은 사례는 부하가 낮을 때 1~8초다. 고른 방법: 이 파일의 사례에 저장소 관례대로 시간 한도 60초를 준다 (`VERIFY_TIMEOUT`). 그리고 livingDocuments가 문서 내용을 읽지 않고 경로만 고르게 해 한 번 도는 일을 줄인다. 버린 안: vitest 전역 testTimeout을 올리는 것(다른 시험의 멈춤을 늦게 알게 된다). 위험: 진짜로 멈춘 검사를 60초 뒤에야 알게 된다. 검증: desktop에서 이 파일과 FE-GATE-005·FE-GATE-020을 다시 돌린다. --- scripts/lib/docs-system.ts | 4 +- tests/unit/documentation-readiness.test.ts | 47 +++++++++++++--------- 2 files changed, 28 insertions(+), 23 deletions(-) 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); });