문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.
고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
README, starter-experience, static-delivery, compatibility,
backend-api-and-server-state-contract, manual-checklist,
adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
and scripts only where verify:documentation checks them"을 더했다. 검사기가
읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
검사기와 같은 규칙을 두 곳에 두게 된다.
위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal
Refs: 1105/14-03
157 lines
7.3 KiB
TypeScript
157 lines
7.3 KiB
TypeScript
import { spawnSync } from "node:child_process";
|
|
import { existsSync } from "node:fs";
|
|
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
|
import { tmpdir } from "node:os";
|
|
import path from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
|
|
import {
|
|
REMOVABLE_TEMPLATE_FEATURES,
|
|
removableTemplateFeaturePaths,
|
|
} from "../../scripts/lib/removable-template-features.ts";
|
|
import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts";
|
|
|
|
/**
|
|
* 1105/14-01. The CHANGELOG tells a product (tech-log) to delete the example
|
|
* screens' feature, and the template's own documents name that feature's
|
|
* folders. A copy that deleted them failed verify:documentation and the
|
|
* FE-GATE-005 copy of it ("passes the documents as they are"), and only the
|
|
* reference sample's removal was ever tried. The features come from
|
|
* scripts/lib/removable-template-features.ts, so no feature ID is written
|
|
* here: the removal drills refuse a test that still names the removed one.
|
|
*/
|
|
const CHECKER = "scripts/verify-documentation-readiness.ts";
|
|
/** What verify:documentation reads besides the code. */
|
|
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "artifacts/tests/a11y-manual"]);
|
|
|
|
/**
|
|
* Runs verify:documentation in a copy of the repository without `removed`,
|
|
* as a product that deleted it has it. The code facts are the copy's:
|
|
* tests/unit/documentation-readiness.test.ts copies only the documents and
|
|
* looks paths up in this repository, where nothing is deleted. The feature
|
|
* index is generated again, as the product does after the deletion.
|
|
*/
|
|
async function verifyWithout(removed: readonly string[]) {
|
|
const parent = await mkdtemp(path.join(tmpdir(), "template-feature-removal-"));
|
|
const root = path.join(parent, "frontend");
|
|
try {
|
|
for (const entry of [...REMOVAL_FIXTURE_COPY_TARGETS, ...DOCUMENTS]) {
|
|
// A drill runs this test in a copy that has already lost some of them.
|
|
if (!existsSync(entry)) continue;
|
|
await cp(entry, path.join(root, entry), {
|
|
recursive: true,
|
|
filter: (source) => !source.includes(`${path.sep}.generated`),
|
|
});
|
|
}
|
|
await linkFixtureNodeModules(root);
|
|
for (const entry of removed) await rm(path.join(root, entry), { recursive: true, force: true });
|
|
const generated = spawnSync(
|
|
process.execPath,
|
|
[path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`],
|
|
{ encoding: "utf8" },
|
|
);
|
|
expect(generated.status, generated.stderr).toBe(0);
|
|
return spawnSync(process.execPath, [path.join(root, CHECKER)], { cwd: root, encoding: "utf8" });
|
|
} finally {
|
|
await rm(parent, { recursive: true, force: true });
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Runs this repository's verify:documentation on a copy of the documents
|
|
* with `mutate` applied to `document`; the code facts are this repository's.
|
|
* `documents` are the ones it checked (docs/README.md §1 and what it links).
|
|
*/
|
|
async function verifyDocuments(document: string, mutate: (text: string) => string = (text) => text) {
|
|
const parent = await mkdtemp(path.join(tmpdir(), "template-feature-documents-"));
|
|
const root = path.join(parent, "frontend");
|
|
try {
|
|
// The pin says which commit of the paired backend the documents describe.
|
|
const inputs = ["README.md", "docs", "artifacts/tests/a11y-manual", "config/contracts/backend-contract-pin.json"];
|
|
for (const entry of inputs) await cp(entry, path.join(root, entry), { recursive: true });
|
|
const target = path.join(root, document);
|
|
await writeFile(target, mutate(await readFile(target, "utf8")));
|
|
const result = spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" });
|
|
const report = JSON.parse(
|
|
await readFile(path.join(root, "artifacts/quality/documentation-review.json"), "utf8"),
|
|
) as { documentReferences: { path: string }[] };
|
|
return { ...result, documents: report.documentReferences.map((entry) => entry.path) };
|
|
} finally {
|
|
await rm(parent, { recursive: true, force: true });
|
|
}
|
|
}
|
|
|
|
describe("verify:documentation after a template feature is deleted (1105/14-01)", () => {
|
|
it.each(REMOVABLE_TEMPLATE_FEATURES.map((feature) => [feature.featureId, feature] as const))(
|
|
"passes in a copy without %s",
|
|
async (_featureId, feature) => {
|
|
const result = await verifyWithout(removableTemplateFeaturePaths(feature));
|
|
expect(result.status, result.stderr).toBe(0);
|
|
},
|
|
120_000,
|
|
);
|
|
|
|
// Only a deleted feature's paths are let through. While a feature is
|
|
// installed a missing path under it fails, and so does a feature folder
|
|
// that is not on the list (a misspelt one).
|
|
it("still fails on a missing path under an installed template feature or an unknown folder", async () => {
|
|
const document = "docs/architecture/starter-experience.md";
|
|
const missing = [
|
|
...REMOVABLE_TEMPLATE_FEATURES.filter((feature) =>
|
|
existsSync(`src/features/${feature.featureId}/feature-module.ts`),
|
|
).map((feature) => `src/features/${feature.featureId}/no-such-module.ts`),
|
|
"src/features/no-such-template-feature/feature-module.ts",
|
|
];
|
|
const result = await verifyDocuments(
|
|
document,
|
|
(text) => `${text}\n${missing.map((file) => `- \`${file}\``).join("\n")}\n`,
|
|
);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain(`${document} names paths that do not exist:`);
|
|
for (const file of missing) expect(result.stderr).toContain(file);
|
|
}, 60_000);
|
|
});
|
|
|
|
/** Fenced blocks whose command lines verify:documentation reads. */
|
|
const SHELL_FENCE = /^(?:bash|sh|shell|console|zsh)?$/u;
|
|
|
|
/**
|
|
* 1105/14-03. The fix for 1103/14-04 wrote the reference sample's paths
|
|
* without backticks so that a copy without the sample passed, which also took
|
|
* 26 lines out of the check while the sample is installed: renaming one of
|
|
* its files left the manual pointing at nothing. Deleted features' paths are
|
|
* accepted now (above), so a current contract document names a removable
|
|
* template feature's path or script only where verify:documentation reads
|
|
* it: in an inline code span, a link target or a shell code block.
|
|
*/
|
|
describe("removable template features in the current contract documents (1105/14-03)", () => {
|
|
it("names their paths and scripts only where verify:documentation checks them", async () => {
|
|
const { documents } = await verifyDocuments("docs/README.md");
|
|
const owned = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => [
|
|
...removableTemplateFeaturePaths(feature),
|
|
...feature.scripts,
|
|
]);
|
|
const unchecked: string[] = [];
|
|
for (const document of documents) {
|
|
const lines = (await readFile(document, "utf8")).split("\n");
|
|
let fence: string | null = null;
|
|
for (const [index, line] of lines.entries()) {
|
|
const marker = /^\s*```(\w*)/u.exec(line);
|
|
if (marker) {
|
|
fence = fence === null ? (marker[1] ?? "") : null;
|
|
continue;
|
|
}
|
|
if (fence !== null && SHELL_FENCE.test(fence)) continue;
|
|
const prose = line.replace(/`[^`\n]+`/gu, "").replace(/\]\([^)\s]+\)/gu, "]");
|
|
for (const entry of owned) {
|
|
if (prose.includes(entry)) unchecked.push(`${document}:${index + 1}: ${entry}`);
|
|
}
|
|
}
|
|
}
|
|
expect(documents).toContain("docs/manual/01-add-a-feature.md");
|
|
expect(unchecked).toEqual([]);
|
|
}, 60_000);
|
|
});
|