fix(test): 문서를 읽는 테스트만 제거 드릴의 문서 테스트 목록에 둔다

문제: 문서를 복사하지 않는 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
This commit is contained in:
DongHyeonka
2026-11-06 05:31:57 +09:00
parent a135fa8a09
commit b8535f8ce7
8 changed files with 183 additions and 64 deletions
@@ -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를 더하면 그 목록도 같은 변경에서 고친다.
+9 -3
View File
@@ -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",
+2 -1
View File
@@ -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([
@@ -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<string> {
const text = readFileSync(pin.frontend.contractDocument, "utf8");
const section = text.split("### 6.1 ")[1]?.split(/\n#{2,3} /u)[0] ?? "";
const codes = new Set<string>();
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(),
);
});
});
+4 -50
View File
@@ -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<string> {
const text = readFileSync(pin.frontend.contractDocument, "utf8");
const section = text.split("### 6.1 ")[1]?.split(/\n#{2,3} /u)[0] ?? "";
const codes = new Set<string>();
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(),
);
});
});
@@ -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",
]);
});
});
+5 -7
View File
@@ -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"),
+73 -2
View File
@@ -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<Parameters<typeof parseAsync>[1]>;
type BabelParserPlugin = NonNullable<NonNullable<BabelOptions["parserOpts"]>["plugins"]>[number];
type SyntaxNode = { type: string } & Record<string, unknown>;
/**
* 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<string[]> {
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")) {