test(layout): 저장소 배치 규칙 R3~R9를 검사로 두고 매뉴얼에 적는다

소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
  목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
  포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
  gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
  목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
  샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
  `kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
  보지 않는다. 산출물 `documentation-review.json`에
  `layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
  nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
  추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
  `check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
  기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
  「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.

위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.

검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
This commit is contained in:
2026-11-08 17:41:27 +09:00
parent 79dc945a67
commit e902e657d1
5 changed files with 305 additions and 4 deletions
+14 -1
View File
@@ -1472,6 +1472,18 @@ export const documentationReviewArtifactSchema = z
})
.strict(),
).min(1),
// R6·R7 of docs/manual/03-outside-feature-folder.md: a manual example that
// points at a deletable sample feature, or infrastructure configuration
// copied into a current document.
layoutRuleViolations: z.array(
z
.object({
path: nonEmptyString,
rule: z.enum(["R6", "R7"]),
detail: nonEmptyString,
})
.strict(),
),
results: z.array(
z
.object({
@@ -1523,9 +1535,10 @@ export const documentationReviewArtifactSchema = z
entry.missingScripts.length === 0 &&
entry.unknownGateIds.length === 0,
) &&
artifact.layoutRuleViolations.length === 0 &&
artifact.results.every(({ passed }) => passed))
) {
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references and review results" });
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references, layout rules and review results" });
}
});
+49
View File
@@ -409,6 +409,48 @@ const documentReferencesValid = documentReferences.every(
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
);
// Repository layout rules of docs/manual/03-outside-feature-folder.md.
// R6: the manual's examples point at generator output or at code blocks in
// the manual, never at a sample feature a copy is meant to delete (the
// template's own sample took the manual's examples with it on 2026-11-07).
// R7: host, cluster and infrastructure configuration (nginx, Kubernetes,
// Helm, Terraform) lives in the infrastructure repository; a current document
// links to it and states the host contract (config/hosting/, FE-GATE-019)
// instead of carrying a copy. The history folders are records and keep what
// they recorded.
// Built from pieces: tests/unit/deletable-history-documents.test.ts fails on
// code that names a history folder, and this names them to skip them.
const HISTORY_DOCUMENT_FOLDERS = ["history", "reviews", "superpowers"].map((folder) => `docs/${folder}/`);
const INFRASTRUCTURE_FENCE = /^\s*```\s*(nginx|hcl|terraform|helm)\b/iu;
const INFRASTRUCTURE_MANIFEST =
/^\s*kind:\s*(Deployment|StatefulSet|DaemonSet|Ingress|Service|ConfigMap|CronJob|HelmRelease|Kustomization)\s*$/u;
const sampleFeaturePaths = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => removableTemplateFeaturePaths(feature));
const currentDocuments = [
"README.md",
...((await readdir("docs", { recursive: true }).catch(() => [])) as string[])
.filter((name) => name.endsWith(".md"))
.map((name) => `docs/${name}`)
.filter((name) => !HISTORY_DOCUMENT_FOLDERS.some((folder) => name.startsWith(folder))),
].sort();
const layoutRuleViolations: { path: string; rule: "R6" | "R7"; detail: string }[] = [];
for (const document of currentDocuments) {
const text = await readFile(document, "utf8").catch(() => null);
if (text === null) continue;
let fenced = false;
text.split("\n").forEach((line, index) => {
if (/^\s*```/u.test(line)) fenced = !fenced;
if (INFRASTRUCTURE_FENCE.test(line) || (fenced && INFRASTRUCTURE_MANIFEST.test(line))) {
layoutRuleViolations.push({ path: document, rule: "R7", detail: `line ${index + 1}: ${line.trim()}` });
}
if (!document.startsWith("docs/manual/")) return;
for (const samplePath of sampleFeaturePaths) {
if (line.includes(samplePath)) {
layoutRuleViolations.push({ path: document, rule: "R6", detail: `line ${index + 1}: ${samplePath}` });
}
}
});
}
// 1101/14-06. Each failed check is named, so the stderr points at the file to
// fix rather than at the diagram review whatever failed. 1101/14-05: the last
// two only compare the two hand-kept copies of the 2026-07-18 diagram review;
@@ -419,6 +461,7 @@ const failedChecks = [
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
...(sourceStructureDocumented ? [] : ["source structure"]),
...(documentReferencesValid ? [] : ["document references"]),
...(layoutRuleViolations.length === 0 ? [] : ["repository layout rules"]),
...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]),
...(results.length === 2 && results.every((result) => result.passed)
? []
@@ -442,6 +485,7 @@ await writeValidatedJsonArtifact({
missingRuntimeVariables,
sourceStructure,
documentReferences,
layoutRuleViolations,
results,
passed,
},
@@ -479,6 +523,11 @@ if (!passed) {
);
}
}
for (const violation of layoutRuleViolations) {
process.stderr.write(
`${violation.path} breaks ${violation.rule} of docs/manual/03-outside-feature-folder.md: ${violation.detail}\n`,
);
}
if (documentReferences.some((entry) => entry.missingPaths.some((file) => file.startsWith("../")))) {
const checked = [...pairedTrees]
.filter(([, tree]) => "paths" in tree)