소유자가 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절
203 lines
9.0 KiB
TypeScript
203 lines
9.0 KiB
TypeScript
import { spawnSync } from "node:child_process";
|
|
import { existsSync, readFileSync } from "node:fs";
|
|
import path from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import {
|
|
parseRepositoryLayout,
|
|
REPOSITORY_LAYOUT,
|
|
REPOSITORY_LAYOUT_FILE,
|
|
selectRepositoryEntries,
|
|
selectRepositoryPaths,
|
|
} from "../../scripts/lib/repository-layout.ts";
|
|
|
|
/**
|
|
* The repository layout rules of docs/manual/03-outside-feature-folder.md
|
|
* that a file listing can check: R1 (every root item is registered), R2 (root
|
|
* path lists are chosen from the registry), R7 for files (no infrastructure
|
|
* configuration in this repository) and R9 (a tsconfig differs in its
|
|
* options, not only in its files). R3 is tests/unit/tracked-artifacts.test.ts.
|
|
*/
|
|
|
|
function trackedFiles(): string[] {
|
|
const listed = spawnSync("git", ["ls-files", "-z"], { encoding: "utf8" });
|
|
if (listed.error || listed.status !== 0) {
|
|
throw new Error(`git ls-files failed: ${listed.error?.message ?? listed.stderr}`);
|
|
}
|
|
return listed.stdout.split("\0").filter((file) => file !== "");
|
|
}
|
|
|
|
const rootItemNames = new Set(REPOSITORY_LAYOUT.map((entry) => entry.path));
|
|
|
|
describe("repository layout registry (R1)", () => {
|
|
// A removal fixture copies part of the repository, so the claim is one way:
|
|
// whatever is tracked at the root is registered. A registered path that is
|
|
// gone fails where a set uses it (a copy or the secret scan cannot find it).
|
|
it("has an entry for every tracked root item", () => {
|
|
const roots = new Set(trackedFiles().map((file) => file.split("/")[0]!));
|
|
expect(
|
|
[...roots].filter((root) => !rootItemNames.has(root)).sort(),
|
|
`add an entry with its role to ${REPOSITORY_LAYOUT_FILE}`,
|
|
).toEqual([]);
|
|
});
|
|
|
|
it("rejects an entry that is not a root item, a duplicate and a path outside its item", () => {
|
|
const entry = { path: "src", kind: "source", role: "app", readBy: "build" };
|
|
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, path: "src/app" }] })).toThrow(
|
|
/no slash/u,
|
|
);
|
|
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [entry, entry] })).toThrow(/duplicate/u);
|
|
expect(() =>
|
|
parseRepositoryLayout({
|
|
schemaVersion: 1,
|
|
entries: [{ ...entry, setPaths: { "vite-build": ["scripts/lib/run-isolation.ts"] } }],
|
|
}),
|
|
).toThrow(/not inside src/u);
|
|
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, kind: "misc" }] })).toThrow(
|
|
/unknown kind/u,
|
|
);
|
|
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, sets: ["everything"] }] })).toThrow(
|
|
/unknown set/u,
|
|
);
|
|
});
|
|
|
|
it("selects whole items and paths inside items in registry order", () => {
|
|
const layout = parseRepositoryLayout({
|
|
schemaVersion: 1,
|
|
entries: [
|
|
{ path: ".gitea", kind: "tool-convention", role: "ci", readBy: "gitea", setPaths: { "secret-scan": [".gitea/workflows/a.yml"] } },
|
|
{ path: "recipes", kind: "source", role: "recipes", readBy: "tsc", optional: true, sets: ["secret-scan"] },
|
|
{ path: "src", kind: "source", role: "app", readBy: "build", sets: ["secret-scan", "vite-build"] },
|
|
],
|
|
});
|
|
expect(selectRepositoryPaths("secret-scan", layout)).toEqual([".gitea/workflows/a.yml", "recipes", "src"]);
|
|
expect(selectRepositoryPaths("vite-build", layout)).toEqual(["src"]);
|
|
expect(selectRepositoryEntries("secret-scan", layout).filter(({ optional }) => optional)).toEqual([
|
|
{ path: "recipes", optional: true },
|
|
]);
|
|
});
|
|
});
|
|
|
|
/**
|
|
* design-docs repo-structure/04-frontend-layout.md §2.4: seven places kept
|
|
* their own literal lists of root paths, each a different subset. Six are
|
|
* code; the seventh is the secret scan policy, a JSON document the release
|
|
* candidate carries, which keeps a copy of its set held equal here.
|
|
*/
|
|
const LAYOUT_CONSUMERS = Object.freeze([
|
|
"scripts/lib/removal-fixture.ts",
|
|
"scripts/lib/vite-build-inputs.ts",
|
|
"scripts/verify-extreme-scale.ts",
|
|
"scripts/check-architecture.ts",
|
|
"tests/unit/deletable-history-documents.test.ts",
|
|
]);
|
|
/** It checked the policy against a list of its own; the copy check below replaces it. */
|
|
const FORMER_CONSUMERS = Object.freeze(["tests/unit/supply-chain.test.ts"]);
|
|
|
|
const STRING = String.raw`(?:"[^"\n]*"|'[^'\n]*'|` + "`[^`\\n]*`)";
|
|
const STRING_ARRAY = new RegExp(String.raw`\[\s*${STRING}(?:\s*,\s*${STRING})+\s*,?\s*\]`, "gu");
|
|
|
|
/** Array literals of two or more string literals that are root item names. */
|
|
function literalRootLists(source: string, roots: ReadonlySet<string>): string[] {
|
|
const code = source.replace(/^\s*\/\/.*$/gmu, "");
|
|
return [...code.matchAll(STRING_ARRAY)]
|
|
.map(([literal]) => [...literal.matchAll(new RegExp(STRING, "gu"))].map(([value]) => value.slice(1, -1)))
|
|
.filter((values) => new Set(values.filter((value) => roots.has(value))).size >= 2)
|
|
.map((values) => values.join(", "));
|
|
}
|
|
|
|
describe("root path lists (R2)", () => {
|
|
it.each(LAYOUT_CONSUMERS)("%s chooses a set from the registry", (consumer) => {
|
|
const source = readFileSync(consumer, "utf8");
|
|
expect(source).toMatch(/repository-layout\.ts/u);
|
|
expect(literalRootLists(source, rootItemNames)).toEqual([]);
|
|
});
|
|
|
|
it.each(FORMER_CONSUMERS)("%s keeps no list of root paths", (consumer) => {
|
|
expect(literalRootLists(readFileSync(consumer, "utf8"), rootItemNames)).toEqual([]);
|
|
});
|
|
|
|
it("finds a literal root list", () => {
|
|
expect(literalRootLists(`const ROOTS = ["src", "tests", "other"];`, rootItemNames)).toEqual(["src, tests, other"]);
|
|
expect(literalRootLists(`const ROOTS = ["src"];\nconst X = ["a", "b"];`, rootItemNames)).toEqual([]);
|
|
});
|
|
|
|
// A removal fixture deletes some of these inputs on purpose — removing the
|
|
// browser file/storage capability takes the whole browser-capability harness
|
|
// with it — and prunes the policy to match. The claim is about the inputs
|
|
// this checkout has.
|
|
it("keeps the secret scan policy's roots equal to the secret-scan set", () => {
|
|
const policy = JSON.parse(readFileSync("config/security/secret-scan-policy.json", "utf8")) as {
|
|
trackedRoots: string[];
|
|
};
|
|
expect([...policy.trackedRoots].sort()).toEqual(
|
|
[...selectRepositoryPaths("secret-scan").filter((input) => existsSync(input))].sort(),
|
|
);
|
|
});
|
|
});
|
|
|
|
/** R7. Development compose files and Dockerfiles may live here; host and cluster configuration may not. */
|
|
const INFRASTRUCTURE_FILE =
|
|
/(?:^|\/)(?:nginx[^/]*|[^/]+\.tf|[^/]+\.tfvars|Chart\.ya?ml|kustomization\.ya?ml|helmfile\.ya?ml)$/iu;
|
|
const KUBERNETES_MANIFEST = /^apiVersion:\s*\S+\s*$[\s\S]*^kind:\s*\S+\s*$/mu;
|
|
|
|
describe("infrastructure configuration (R7)", () => {
|
|
it("is not tracked in this repository", () => {
|
|
const files = trackedFiles();
|
|
const manifests = files
|
|
.filter((file) => /\.ya?ml$/u.test(file) && existsSync(file))
|
|
.filter((file) => KUBERNETES_MANIFEST.test(readFileSync(file, "utf8")));
|
|
expect([...files.filter((file) => INFRASTRUCTURE_FILE.test(file)), ...manifests]).toEqual([]);
|
|
});
|
|
|
|
it("recognises the file kinds the rule names", () => {
|
|
expect(["deploy/nginx.conf", "infra/main.tf", "chart/Chart.yaml", "kustomization.yml"].filter((file) =>
|
|
INFRASTRUCTURE_FILE.test(file),
|
|
)).toHaveLength(4);
|
|
expect(KUBERNETES_MANIFEST.test("apiVersion: apps/v1\nkind: Deployment\n")).toBe(true);
|
|
expect(INFRASTRUCTURE_FILE.test("compose.yaml")).toBe(false);
|
|
});
|
|
});
|
|
|
|
type TsconfigDocument = Readonly<{
|
|
extends?: string;
|
|
compilerOptions?: Record<string, unknown>;
|
|
files?: readonly string[];
|
|
references?: readonly unknown[];
|
|
}>;
|
|
|
|
function effectiveCompilerOptions(file: string): Record<string, unknown> {
|
|
const document = JSON.parse(readFileSync(file, "utf8")) as TsconfigDocument;
|
|
const inherited = document.extends?.startsWith(".")
|
|
? effectiveCompilerOptions(path.join(path.dirname(file), document.extends))
|
|
: {};
|
|
return { ...inherited, ...document.compilerOptions };
|
|
}
|
|
|
|
/** Pairs of tsconfig files whose options are the same; a solution tsconfig (references only) has none. */
|
|
function sameOptionTsconfigs(files: readonly string[]): string[] {
|
|
const options = files
|
|
.filter((file) => {
|
|
const document = JSON.parse(readFileSync(file, "utf8")) as TsconfigDocument;
|
|
return !(document.references && document.files?.length === 0);
|
|
})
|
|
.map((file) => ({
|
|
file,
|
|
options: JSON.stringify(Object.entries(effectiveCompilerOptions(file)).sort(([a], [b]) => a.localeCompare(b))),
|
|
}));
|
|
return options.flatMap((left, index) =>
|
|
options.slice(index + 1).filter((right) => right.options === left.options).map((right) => `${left.file} = ${right.file}`),
|
|
);
|
|
}
|
|
|
|
describe("tsconfig files (R9)", () => {
|
|
// tests/fixtures/typecheck had 23 one-file tsconfigs with one set of
|
|
// options until 2026-11-08; scripts/check-type-fixtures.ts runs them now.
|
|
it("differ in lib, types or module resolution, not only in their files", () => {
|
|
const tsconfigs = trackedFiles().filter((file) => /(?:^|\/)tsconfig[^/]*\.json$/u.test(file) && existsSync(file));
|
|
expect(tsconfigs.length).toBeGreaterThan(1);
|
|
expect(sameOptionTsconfigs(tsconfigs)).toEqual([]);
|
|
});
|
|
});
|