From b8535f8ce7f7afbc1046e45accce91f30da30cb9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:31:57 +0900 Subject: [PATCH] =?UTF-8?q?fix(test):=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20?= =?UTF-8?q?=EC=9D=BD=EB=8A=94=20=ED=85=8C=EC=8A=A4=ED=8A=B8=EB=A7=8C=20?= =?UTF-8?q?=EC=A0=9C=EA=B1=B0=20=EB=93=9C=EB=A6=B4=EC=9D=98=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=ED=85=8C=EC=8A=A4=ED=8A=B8=20=EB=AA=A9=EB=A1=9D?= =?UTF-8?q?=EC=97=90=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 문서를 복사하지 않는 capability 드릴 셋은 `REMOVAL_FIXTURE_DOCUMENT_TESTS` 의 파일을 통째로 지운다. 문서를 읽는 테스트 하나 때문에 `backend-contract-pin.test.ts`가 목록에 들어가, config와 코드만 보는 나머지 14건(pin 커밋, 답 표 사본, 생성기 사실, Envelope 판정 대조)도 그 드릴에서 돌지 않는다. `feature-tracked-files.test.ts`의 생성기 목록 검사 1건도 같다. 목록을 지키는 검사는 파일 글자에 `README.md|CHANGELOG.md|docs/`가 있는지만 봐서, `backend-contract-pin.test.ts`는 주석 한 줄로 통과했다. 고른 방법(리뷰 문서 ⓐ+ⓑ): - 6.1 표를 읽는 테스트를 `backend-contract-pin-document.test.ts`로 옮기고 목록에는 그 파일을 둔다. pin 파일은 목록에서 빠져 모든 드릴에서 돈다. 새 파일은 pin에서 문서 경로만 읽고, 그 경로가 `docs/` 아래인지 확인한다. - `feature-tracked-files.test.ts`의 문서와 무관한 1건을 `feature-tracked-file-rewrites.test.ts`로 옮긴다. 남은 두 건은 모두 문서를 읽어 그 파일은 목록에 남는다(`create-feature.ts`의 참조도 그대로 맞다). - 목록 검사는 Babel로 파일을 파싱해 코드의 문자열·템플릿 리터럴에 문서 경로가 있는지 본다. 주석은 세지 않는다. 주석만 있는 소스를 거절하는지 자체 테스트를 더했다. - 6.1 대조를 가리키던 `external-contract-runtime.ts` 주석과 계약 문서 한 줄을 새 파일 이름으로 고쳤다. 버린 대안: capability 드릴이 계약 문서 하나만 복사하기. 문서 테스트가 늘 때마다 복사 목록이 늘고, 그 드릴이 "문서 없이"를 증명한다는 전제가 흐려진다. 목록 검사만 고치기는 빠지는 범위가 그대로다. 위험·한계: - 목록 검사는 파일 단위다. 파일 안의 모든 테스트가 문서를 읽는지는 기계로 보지 않는다. 목록 주석에 규칙을 적었다. - 검사는 코드에 문서 경로 문자열이 있는지 본다. 그 문자열로 실제로 읽는지는 보지 않는다. - 이 노트북에서는 실행하지 못했다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/removal-fixture.test.ts tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-pin-document.test.ts tests/unit/feature-tracked-files.test.ts tests/unit/feature-tracked-file-rewrites.test.ts check:types, lint, verify:documentation, ci:gate FE-GATE-020(capability 드릴 셋의 unit 실행에 pin 14건이 나오는지) Refs: 1106/12-01 --- .../backend-api-and-server-state-contract.md | 2 +- scripts/lib/removal-fixture.ts | 12 ++- src/contracts/external-contract-runtime.ts | 3 +- .../backend-contract-pin-document.test.ts | 67 +++++++++++++++++ tests/unit/backend-contract-pin.test.ts | 54 +------------ .../feature-tracked-file-rewrites.test.ts | 22 ++++++ tests/unit/feature-tracked-files.test.ts | 12 ++- tests/unit/removal-fixture.test.ts | 75 ++++++++++++++++++- 8 files changed, 183 insertions(+), 64 deletions(-) create mode 100644 tests/unit/backend-contract-pin-document.test.ts create mode 100644 tests/unit/feature-tracked-file-rewrites.test.ts diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 200015ea..b66ba820 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -389,7 +389,7 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 - 위 표에서 "쓰기 뒤 가능"인 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, fileserver code)도 적을 수 없다(1105/03-01). 계약 조립이 거절하고 실행기도 무시한다. 목록은 `src/contracts/external-contract-runtime.ts`의 - `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`이고, `tests/unit/backend-contract-pin.test.ts`가 + `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`이고, `tests/unit/backend-contract-pin-document.test.ts`가 이 표의 "쓰기 뒤 가능" 행과 대조한다. 참조 도메인 code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 그 엔드포인트를 확인한 기능 작성자가 적을 수 있다. 이 표에 "쓰기 뒤 가능" 플랫폼 code를 더하면 그 목록도 같은 변경에서 고친다. diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index 2eee70cf..0fd8afe2 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -66,13 +66,19 @@ export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([ * CHANGELOG.md, whatever the removal did. prepareRemovalFixture deletes them * from such a fixture, and the repository's own test:unit keeps running them. * This is the only list; the sample drill used to keep the exclusion to itself. + * + * 1106/12-01. The unit is a file, so every test in a listed file reads the + * documents. A test that reads none goes in another file: listing a file for + * one document test took the file's other tests out of those drills too. */ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([ "tests/unit/changelog-review-ids.test.ts", "tests/unit/documentation-readiness.test.ts", - // 1105/03-01. Reads the 6.1 table of the frontend contract document. - "tests/unit/backend-contract-pin.test.ts", - // 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md. + // 1105/03-01. Reads the 6.1 table of the frontend contract document; the + // pin checks that read none are in backend-contract-pin.test.ts. + "tests/unit/backend-contract-pin-document.test.ts", + // 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md; + // the generator's list is checked in feature-tracked-file-rewrites.test.ts. "tests/unit/feature-tracked-files.test.ts", // 1105/14-01 "tests/unit/template-feature-removal-documents.test.ts", diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 55bdd490..4cf0f738 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -633,7 +633,8 @@ const IDEMPOTENCY_CODE = /^IDEMPOTEN(?:T|CY)_/; * fileserver module. Their stage is the template's knowledge, not the * feature's, so no operation may declare them as refused before its write. * Business codes stay the feature author's to declare. - * tests/unit/backend-contract-pin.test.ts holds this list to the 6.1 table. + * tests/unit/backend-contract-pin-document.test.ts holds this list to the 6.1 + * table. */ export const PLATFORM_CODES_POSSIBLY_AFTER_WRITE: readonly string[] = Object.freeze([ diff --git a/tests/unit/backend-contract-pin-document.test.ts b/tests/unit/backend-contract-pin-document.test.ts new file mode 100644 index 00000000..28543d43 --- /dev/null +++ b/tests/unit/backend-contract-pin-document.test.ts @@ -0,0 +1,67 @@ +import { readFileSync } from "node:fs"; + +import { describe, expect, it } from "vitest"; +import { z } from "zod"; + +import { PLATFORM_CODES_POSSIBLY_AFTER_WRITE } from "../../src/contracts/external-contract-runtime.ts"; + +/** + * 1106/12-01. The one paired-backend pin check that reads a document. It has + * its own file because the removal drills that copy no documents leave whole + * files out (REMOVAL_FIXTURE_DOCUMENT_TESTS in scripts/lib/removal-fixture.ts): + * in tests/unit/backend-contract-pin.test.ts it took that file's fourteen + * checks of config and code out of those drills with it. The pin names the + * document; it is a repository document (`docs/`), which is why this file is + * on that list. + */ +const pin = z + .object({ + frontend: z.object({ contractDocument: z.string().startsWith("docs/") }), + }) + .parse(JSON.parse(readFileSync("config/contracts/backend-contract-pin.json", "utf8"))); + +/** + * 1105/03-01. The codes of the contract 6.1 table rows whose stage is "쓰기 뒤 + * 가능" (possibly after the write), read from the document the pin names. + */ +function codesPossiblyAfterWrite(): ReadonlySet { + const text = readFileSync(pin.frontend.contractDocument, "utf8"); + const section = text.split("### 6.1 ")[1]?.split(/\n#{2,3} /u)[0] ?? ""; + const codes = new Set(); + for (const line of section.split("\n")) { + const cells = line.split("|").map((cell) => cell.trim()); + if (!line.startsWith("|") || cells[3] !== "쓰기 뒤 가능") continue; + for (const [, code = ""] of (cells[1] ?? "").matchAll(/`([A-Z0-9_]+)`/gu)) { + codes.add(code); + } + } + return codes; +} + +/** + * Rows of that table whose stage the endpoint decides: the reference domain's + * codes and web-advanced's patch codes ("부르는 코드가 단계를 정한다"). A + * feature author who checked the endpoint may declare them. + */ +const FEATURE_DECIDED_CODES: readonly string[] = [ + "WORKLOG_INVALID", + "POSTER_INVALID_STATE", + "POSTER_IMAGE_REQUIRED", + "WORKLOG_CONFLICT", + "POSTER_ALREADY_EXISTS", + "POSTER_IMAGE_ALREADY_PUBLISHED", + "PATCH_REJECTED", + "PATCH_TEST_FAILED", +]; + +describe("platform codes no operation may declare as refused before its write", () => { + it("are the 6.1 table's possibly-after-write codes outside the feature-decided rows", () => { + const table61 = codesPossiblyAfterWrite(); + for (const code of FEATURE_DECIDED_CODES) { + expect(table61.has(code), code).toBe(true); + } + expect([...PLATFORM_CODES_POSSIBLY_AFTER_WRITE].sort()).toEqual( + [...table61].filter((code) => !FEATURE_DECIDED_CODES.includes(code)).sort(), + ); + }); +}); diff --git a/tests/unit/backend-contract-pin.test.ts b/tests/unit/backend-contract-pin.test.ts index f219960c..71a9d39d 100644 --- a/tests/unit/backend-contract-pin.test.ts +++ b/tests/unit/backend-contract-pin.test.ts @@ -13,7 +13,6 @@ import { maybeAppliedAnswerRows, refusedBeforeWriteRows, } from "../../src/adapters/http/backend-envelope.ts"; -import { PLATFORM_CODES_POSSIBLY_AFTER_WRITE } from "../../src/contracts/external-contract-runtime.ts"; /** * 1103/12-06. The paired backend's contract is pinned in a file a machine @@ -27,6 +26,10 @@ import { PLATFORM_CODES_POSSIBLY_AFTER_WRITE } from "../../src/contracts/externa * copied word for word at the pin (`tables.backendExcerpt`), so a mistyped * status or a row left out fails here without a backend checkout. * `check:backend-contract-drift` holds that copy to the backend document. + * + * 1106/12-01. This file reads config and code only, so every removal drill + * runs it. The check of the contract 6.1 table reads a document and is in + * tests/unit/backend-contract-pin-document.test.ts. */ const COMMIT = /^[0-9a-f]{40}$/u; @@ -252,52 +255,3 @@ describe("paired backend contract pin", () => { } }); }); - -/** - * 1105/03-01. The codes of the contract 6.1 table rows whose stage is "쓰기 뒤 - * 가능" (possibly after the write), read from the document the pin names - * (docs/architecture/backend-api-and-server-state-contract.md). Because this - * file reads that document, the removal drills that copy no documents leave - * it out (REMOVAL_FIXTURE_DOCUMENT_TESTS in scripts/lib/removal-fixture.ts). - */ -function codesPossiblyAfterWrite(): ReadonlySet { - const text = readFileSync(pin.frontend.contractDocument, "utf8"); - const section = text.split("### 6.1 ")[1]?.split(/\n#{2,3} /u)[0] ?? ""; - const codes = new Set(); - for (const line of section.split("\n")) { - const cells = line.split("|").map((cell) => cell.trim()); - if (!line.startsWith("|") || cells[3] !== "쓰기 뒤 가능") continue; - for (const [, code = ""] of (cells[1] ?? "").matchAll(/`([A-Z0-9_]+)`/gu)) { - codes.add(code); - } - } - return codes; -} - -/** - * Rows of that table whose stage the endpoint decides: the reference domain's - * codes and web-advanced's patch codes ("부르는 코드가 단계를 정한다"). A - * feature author who checked the endpoint may declare them. - */ -const FEATURE_DECIDED_CODES: readonly string[] = [ - "WORKLOG_INVALID", - "POSTER_INVALID_STATE", - "POSTER_IMAGE_REQUIRED", - "WORKLOG_CONFLICT", - "POSTER_ALREADY_EXISTS", - "POSTER_IMAGE_ALREADY_PUBLISHED", - "PATCH_REJECTED", - "PATCH_TEST_FAILED", -]; - -describe("platform codes no operation may declare as refused before its write", () => { - it("are the 6.1 table's possibly-after-write codes outside the feature-decided rows", () => { - const table61 = codesPossiblyAfterWrite(); - for (const code of FEATURE_DECIDED_CODES) { - expect(table61.has(code), code).toBe(true); - } - expect([...PLATFORM_CODES_POSSIBLY_AFTER_WRITE].sort()).toEqual( - [...table61].filter((code) => !FEATURE_DECIDED_CODES.includes(code)).sort(), - ); - }); -}); diff --git a/tests/unit/feature-tracked-file-rewrites.test.ts b/tests/unit/feature-tracked-file-rewrites.test.ts new file mode 100644 index 00000000..f6507a58 --- /dev/null +++ b/tests/unit/feature-tracked-file-rewrites.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from "vitest"; + +import { FEATURE_TRACKED_FILE_REWRITES } from "../../scripts/create-feature.ts"; + +/** + * 1105/16-01. The tracked template files every added feature changes, each + * with the command that rewrites it. tests/unit/feature-tracked-files.test.ts + * holds the documents to this list. + * + * 1106/12-01. This check reads no document, so it is not in that file: the + * removal drills that copy no documents leave that file out + * (REMOVAL_FIXTURE_DOCUMENT_TESTS in scripts/lib/removal-fixture.ts) and run + * this one. + */ +describe("tracked files a feature changes (1105/16-01)", () => { + it("lists the generator's tracked rewrites", () => { + expect(FEATURE_TRACKED_FILE_REWRITES.map((file) => file.path)).toEqual([ + "public/release-manifest.json", + "config/scale/feature-shape-ceilings.json", + ]); + }); +}); diff --git a/tests/unit/feature-tracked-files.test.ts b/tests/unit/feature-tracked-files.test.ts index c9e3ba33..3a7eaa1f 100644 --- a/tests/unit/feature-tracked-files.test.ts +++ b/tests/unit/feature-tracked-files.test.ts @@ -13,6 +13,11 @@ import { FEATURE_TRACKED_FILE_REWRITES } from "../../scripts/create-feature.ts"; * had neither, and nothing said what to do when two feature branches change * the same `setDigest` line. The documents name each file with the command * that rewrites it, which is also how a merge conflict on it is resolved. + * + * 1106/12-01. Every test here reads a document, so the removal drills that + * copy no documents leave this file out (REMOVAL_FIXTURE_DOCUMENT_TESTS in + * scripts/lib/removal-fixture.ts). The generator's own list is checked in + * tests/unit/feature-tracked-file-rewrites.test.ts, which every drill runs. */ function between(text: string, start: string, end: string): string { const from = text.indexOf(start); @@ -22,13 +27,6 @@ function between(text: string, start: string, end: string): string { } describe("tracked files a feature changes (1105/16-01)", () => { - it("lists the generator's tracked rewrites", () => { - expect(FEATURE_TRACKED_FILE_REWRITES.map((file) => file.path)).toEqual([ - "public/release-manifest.json", - "config/scale/feature-shape-ceilings.json", - ]); - }); - it("names each file and its rewrite command in the 03 manual's section A", async () => { const section = between( await readFile("docs/manual/03-outside-feature-folder.md", "utf8"), diff --git a/tests/unit/removal-fixture.test.ts b/tests/unit/removal-fixture.test.ts index 017aa20e..0901a824 100644 --- a/tests/unit/removal-fixture.test.ts +++ b/tests/unit/removal-fixture.test.ts @@ -3,6 +3,7 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promis import { tmpdir } from "node:os"; import path from "node:path"; +import { parseAsync } from "@babel/core"; import { afterEach, describe, expect, it } from "vitest"; import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts"; @@ -137,6 +138,50 @@ it("rejects pruning that leaves a reduced gate without commands", async () => { })).rejects.toThrow(/commandIds|too small|at least 1/i); }); +type BabelOptions = NonNullable[1]>; +type BabelParserPlugin = NonNullable["plugins"]>[number]; +type SyntaxNode = { type: string } & Record; + +/** + * 1106/12-01. The document paths the code of `source` spells out: string and + * template literal parts that are a document target (README.md, CHANGELOG.md, + * docs) or a path under one. Comments are not code. + */ +async function documentsNamedInCode(file: string, source: string): Promise { + const plugins: BabelParserPlugin[] = [["typescript", { dts: false }]]; + const tree = (await parseAsync(source, { + filename: file, + babelrc: false, + configFile: false, + sourceType: "module", + parserOpts: { plugins }, + })) as unknown as SyntaxNode | null; + if (!tree) throw new Error(`cannot parse ${file}`); + const strings: string[] = []; + const visit = (node: SyntaxNode): void => { + const literal = node["value"]; + if (node.type === "StringLiteral" && typeof literal === "string") strings.push(literal); + if (node.type === "TemplateElement") { + const cooked = (literal as { cooked?: unknown } | undefined)?.cooked; + if (typeof cooked === "string") strings.push(cooked); + } + for (const [key, value] of Object.entries(node)) { + if (key === "comments" || key.endsWith("Comments")) continue; + for (const child of Array.isArray(value) ? value : [value]) { + if (child && typeof child === "object" && typeof (child as SyntaxNode).type === "string") { + visit(child as SyntaxNode); + } + } + } + }; + visit(tree); + return strings.filter((value) => + REMOVAL_FIXTURE_DOCUMENT_TARGETS.some( + (target) => value === target || value.startsWith(`${target}/`), + ), + ); +} + // 1103/02-06. Three FE-GATE-020 drills copied the repository without its // documents and still ran the tests that read them, so each failed its `test` // check on ENOENT whatever it removed. Only the sample drill excluded them. @@ -157,12 +202,38 @@ describe("document tests in a removal fixture", () => { for (const test of REMOVAL_FIXTURE_DOCUMENT_TESTS) { expect(existsSync(test), test).toBe(documentsPresent); if (documentsPresent) { - // 1105/14-02. docs/ is one of the document targets too. - await expect(readFile(test, "utf8")).resolves.toMatch(/README\.md|CHANGELOG\.md|docs\//u); + // 1106/12-01. Named in its code, not in a comment. A comment naming + // the contract document let backend-contract-pin.test.ts on the list, + // and its fourteen checks of config and code left those drills with + // the one that read the document. + expect(await documentsNamedInCode(test, await readFile(test, "utf8")), test).not.toEqual([]); } } }); + it("counts a document named in code, not one named in a comment", async () => { + const commentOnly = [ + "// Reads docs/architecture/a.md (README.md, CHANGELOG.md).", + "/** docs/manual/b.md */", + 'const pin = JSON.parse(readFileSync("config/pin.json", "utf8"));', + "readFileSync(pin.document);", + ].join("\n"); + expect(await documentsNamedInCode("comment-only.test.ts", commentOnly)).toEqual([]); + + const reads = [ + 'readFileSync("CHANGELOG.md", "utf8");', + "const name: string = 'a';", + "readFileSync(`docs/manual/${name}.md`, 'utf8');", + 'z.string().startsWith("docs/");', + 'const notADocument = "src/docs/x.ts";', + ].join("\n"); + expect((await documentsNamedInCode("reads.test.ts", reads)).sort()).toEqual([ + "CHANGELOG.md", + "docs/", + "docs/manual/", + ]); + }); + it("is the only exclusion list: every drill prepares its fixture through it", async () => { const drills: string[] = []; for (const name of await readdir("scripts")) {