문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와 입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는 문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를 보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한 문서의 경로만 본다. 고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number, map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨 scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이 부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는 문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation 단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의 documentation-readiness 시험이 이 repo를 그대로 두고 verify:documentation을 한 번 돌린다. - 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리 3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다. - 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와 도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는 이미 TS에 있다. - 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다 FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤 번역 커밋들이 지운다. - docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록· 검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수 절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와 글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다. - README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는 테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록 폴더 이름을 적지만 지운 사본에서도 통과하므로 deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를 테스트와 검사기 시험에 적었다). 위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때 verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다. review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자 검사에서 뺐다(HISTORY_HOLDERS). 검증: tests/unit/docs-system.test.ts(조건마다 실패 입력), documentation-readiness·template-feature-removal-documents· deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
100 lines
3.7 KiB
TypeScript
100 lines
3.7 KiB
TypeScript
import { readdir, readFile } from "node:fs/promises";
|
|
import path from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
/**
|
|
* README.md, 「복사한 뒤 지워도 되는 것」, tells a new project that
|
|
* the build and the gates read none of the history documents except
|
|
* `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same
|
|
* promise: they do not copy `docs/`. A test that opens a review document broke
|
|
* all three removal checks (fix of 11-04), so the promise is checked here.
|
|
*/
|
|
const CODE_ROOTS = ["src", "tests", "scripts", "config", "recipes", "schemas", ".gitea"];
|
|
const ROOT_FILES = [
|
|
"package.json",
|
|
"vite.config.ts",
|
|
"vitest.config.ts",
|
|
"eslint.config.ts",
|
|
"playwright.config.ts",
|
|
".dependency-cruiser.json",
|
|
];
|
|
|
|
// Built from pieces so that this file does not match itself.
|
|
const REVIEWS = ["docs", "reviews", ""].join("/");
|
|
const KEPT = `${REVIEWS}adapters/INVENTORY.md`;
|
|
// The 2026-09-25 round's task folder moved into the history folder on
|
|
// 2026-11-07 (docs/README.md §3), so the history pattern covers it. A pattern
|
|
// for the old root folder would now only catch a product's own route or
|
|
// folder of that name.
|
|
const DELETABLE = [
|
|
new RegExp(`${REVIEWS}(?!adapters/INVENTORY\\.md)`, "u"),
|
|
new RegExp(["docs", "superpowers"].join("/"), "u"),
|
|
new RegExp(["docs", "history"].join("/"), "u"),
|
|
new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"),
|
|
new RegExp(`\\b${"CLAUDE"}\\.md\\b`, "u"),
|
|
];
|
|
/**
|
|
* 1101/14-01. A section number without a document name cannot be followed,
|
|
* and the scale design it meant used to live only in the history bundle a
|
|
* copy deletes. Cite it as `scale-architecture.md §N`
|
|
* (docs/architecture/scale-architecture.md, a current contract).
|
|
*/
|
|
const UNNAMED_SECTION = new RegExp(`\\b${"spec"} ?§`, "iu");
|
|
|
|
async function codeFiles(directory: string): Promise<string[]> {
|
|
const entries = await readdir(directory, { withFileTypes: true }).catch(
|
|
() => [],
|
|
);
|
|
const files = await Promise.all(
|
|
entries.map(async (entry) => {
|
|
const target = path.join(directory, entry.name);
|
|
if (entry.isDirectory())
|
|
return entry.name === "node_modules" ? [] : codeFiles(target);
|
|
return /\.(?:[cm]?[jt]sx?|json|ya?ml)$/u.test(entry.name) ? [target] : [];
|
|
}),
|
|
);
|
|
return files.flat();
|
|
}
|
|
|
|
/**
|
|
* The document checker (docs/README.md 「5. 문서 검사」) names the record
|
|
* folders to read the head block of whatever records are there and nothing
|
|
* else of them. A copy that deleted them passes it ("passes a copy that
|
|
* deleted its history" in its test), so it is not a reader this promise is
|
|
* about.
|
|
*/
|
|
const RECORD_FOLDER_CHECKERS: ReadonlySet<string> = new Set([
|
|
"scripts/lib/docs-system.ts",
|
|
"tests/unit/docs-system.test.ts",
|
|
]);
|
|
|
|
async function linesMatching(patterns: readonly RegExp[]): Promise<string[]> {
|
|
const files = [
|
|
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat().filter((file) => !RECORD_FOLDER_CHECKERS.has(file)),
|
|
...ROOT_FILES,
|
|
];
|
|
const matches: string[] = [];
|
|
for (const file of files) {
|
|
const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
|
|
lines.forEach((line, index) => {
|
|
if (patterns.some((pattern) => pattern.test(line)))
|
|
matches.push(`${file}:${index + 1}`);
|
|
});
|
|
}
|
|
return matches;
|
|
}
|
|
|
|
describe("deletable history documents", () => {
|
|
it("are read by no code, test, script or configuration", async () => {
|
|
expect(await linesMatching(DELETABLE), `only ${KEPT} may be read`).toEqual([]);
|
|
});
|
|
|
|
it("are not cited as an unnamed design section", async () => {
|
|
expect(
|
|
await linesMatching([UNNAMED_SECTION]),
|
|
"name the document: scale-architecture.md §N",
|
|
).toEqual([]);
|
|
});
|
|
});
|