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")) {