main이 받은 PR #15의 tests/unit/docs-system.test.ts는 문서 검사기 시험을 위해 메모리 안에 가상 저장소를 만든다. 그 knownPaths 배열(docs, docs/architecture, docs/architecture/layers.md, src, src/platform)을 R2 검사가 루트 경로 목록으로 잡아, main을 이 브랜치에 합치면 test:unit이 실패한다. 이 목록은 실제 루트 항목을 옮겨도 바뀌지 않으니 등록부 집합으로 고를 것이 아니다. R2 시험에 MADE_UP_REPOSITORY_LISTS를 두고 파일·목록·이유를 적는다. - 그 파일의 그 목록만 건너뛰고, 같은 파일의 다른 목록은 그대로 본다. - 적힌 목록이 그 파일에 더 없으면 실패한다. 그래서 낡은 예외가 뒤에 새 목록을 덮지 못한다. 제거 drill 사본처럼 그 파일이 검사 대상에 없으면 보지 않는다. - 이 커밋에는 아직 그 파일이 없다. 다음 merge 커밋이 main을 합쳐도 모든 커밋이 시험을 통과하도록 merge 앞에 둔다. 매뉴얼 03 E절 R2 칸과 CHANGELOG 먼저 할 일 15에 이 예외를 적는다. 버린 것: - docs-system 시험의 배열을 둘로 나누기: 검사를 피하려고 코드 모양을 바꾸는 것이다. - 가상 경로를 다른 이름으로 바꾸기: 문서 검사기가 docs/ 경로를 규칙으로 보므로 시험의 뜻이 바뀐다. - 집합을 고르게 하기: 가상 저장소가 실제 저장소 배치에 묶인다. 위험: 다운스트림이 같은 꼴의 fixture를 두면 이 목록에 적어야 한다. 검증(desktop): 이 커밋과 다음 merge 커밋에서 test:unit, check:types, check:ci, lint, verify:documentation. merge 커밋에서 변이 셋을 넣었다. 예외를 지우면 R2 시험이 docs-system 목록을 대며 실패한다. 목록 내용을 바꾸면 바뀐 목록을 대며 실패한다. 목록이 파일에서 없어지면 낡은 예외로 실패한다.
285 lines
14 KiB
TypeScript
285 lines
14 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,
|
|
REPOSITORY_LAYOUT_SETS,
|
|
selectRepositoryEntries,
|
|
selectRepositoryPaths,
|
|
} from "../../scripts/lib/repository-layout.ts";
|
|
import { REMOVAL_FIXTURE_DOCUMENT_TESTS } from "../../scripts/lib/removal-fixture.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));
|
|
/** Tracked items: the ones a list in code can go stale on when one moves. */
|
|
const trackedRootNames = new Set(
|
|
REPOSITORY_LAYOUT.filter(({ kind }) => kind !== "untracked").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("lists untracked items that have no tracked file", () => {
|
|
const tracked = new Set(trackedFiles().map((file) => file.split("/")[0]!));
|
|
const untracked = REPOSITORY_LAYOUT.filter(({ kind }) => kind === "untracked");
|
|
expect(untracked.length).toBeGreaterThan(0);
|
|
expect(untracked.filter(({ path: item }) => tracked.has(item)).map(({ path: item }) => item)).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,
|
|
);
|
|
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, kind: "untracked" }] })).toThrow(
|
|
/optional/u,
|
|
);
|
|
expect(() =>
|
|
parseRepositoryLayout({ schemaVersion: 1, sets: { "fixture-copy": "copied" }, entries: [entry] }),
|
|
).toThrow(/must describe exactly/u);
|
|
});
|
|
|
|
it("selects whole items and paths inside items in registry order", () => {
|
|
const layout = parseRepositoryLayout({
|
|
schemaVersion: 1,
|
|
entries: [
|
|
{ path: ".ci", kind: "tool-convention", role: "ci", readBy: "ci", setPaths: { "secret-scan": [".ci/workflows/a.yml"] } },
|
|
{ path: "extras", kind: "source", role: "extras", readBy: "tsc", optional: true, sets: ["secret-scan"] },
|
|
{ path: "app", kind: "source", role: "app", readBy: "build", sets: ["secret-scan", "vite-build"] },
|
|
],
|
|
});
|
|
expect(selectRepositoryPaths("secret-scan", layout)).toEqual([".ci/workflows/a.yml", "extras", "app"]);
|
|
expect(selectRepositoryPaths("vite-build", layout)).toEqual(["app"]);
|
|
expect(selectRepositoryEntries("secret-scan", layout).filter(({ optional }) => optional)).toEqual([
|
|
{ path: "extras", 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; about
|
|
* twenty more were found on 2026-11-11. Every tracked code file is checked, so
|
|
* a new list fails here instead of waiting for a review to find it.
|
|
*/
|
|
const CODE_FILE = /\.(?:[cm]?ts|tsx|[cm]?js)$/u;
|
|
|
|
/** The sets that only tests in REMOVAL_FIXTURE_DOCUMENT_TESTS read, sorted. */
|
|
const DOCUMENT_TEST_SETS = ["agent-harness", "documentation-inputs", "feature-typecheck"];
|
|
|
|
/**
|
|
* Lists that look like root path lists but describe a made-up repository a
|
|
* test builds in memory: moving a root item never changes them. Only the exact
|
|
* list in that file is excused, and an entry that no longer matches fails, so
|
|
* it cannot hide a later list.
|
|
*/
|
|
const MADE_UP_REPOSITORY_LISTS: readonly Readonly<{ file: string; list: string; reason: string }>[] = [
|
|
{
|
|
file: "tests/unit/docs-system.test.ts",
|
|
list: "docs, docs/architecture, docs/architecture/layers.md, src, src/platform",
|
|
reason: "knownPaths of the in-memory repository the docs-system checker test builds",
|
|
},
|
|
];
|
|
|
|
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 string literals that are all root items or paths inside
|
|
* one, two or more of them tracked. In an argument vector only the paths after
|
|
* `--` count, so `git grep … -- <paths>` is a list and a list of subcommand
|
|
* names that happen to include `docs` is not.
|
|
*/
|
|
function literalRootLists(
|
|
source: string,
|
|
tracked: ReadonlySet<string> = trackedRootNames,
|
|
roots: ReadonlySet<string> = rootItemNames,
|
|
): string[] {
|
|
const code = source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/^\s*\/\/.*$/gmu, "");
|
|
const isRootPath = (value: string) => roots.has(value) || (value.includes("/") && roots.has(value.split("/")[0]!));
|
|
return [...code.matchAll(STRING_ARRAY)]
|
|
.map(([literal]) => [...literal.matchAll(new RegExp(STRING, "gu"))].map(([value]) => value.slice(1, -1)))
|
|
.map((values) => (values.includes("--") ? values.slice(values.lastIndexOf("--") + 1) : values))
|
|
.filter((values) => values.every(isRootPath) && new Set(values.filter((value) => tracked.has(value))).size >= 2)
|
|
.map((values) => values.join(", "));
|
|
}
|
|
|
|
describe("root path lists (R2)", () => {
|
|
it("are chosen from the registry everywhere in the code", () => {
|
|
const files = trackedFiles().filter((file) => CODE_FILE.test(file) && existsSync(file));
|
|
expect(files.length).toBeGreaterThan(100);
|
|
const found = files.flatMap((file) => literalRootLists(readFileSync(file, "utf8")).map((list) => ({ file, list })));
|
|
const excused = (file: string, list: string) =>
|
|
MADE_UP_REPOSITORY_LISTS.some((entry) => entry.file === file && entry.list === list);
|
|
expect(
|
|
found.filter(({ file, list }) => !excused(file, list)).map(({ file, list }) => `${file}: [${list}]`),
|
|
`choose a set from ${REPOSITORY_LAYOUT_FILE} with selectRepositoryPaths`,
|
|
).toEqual([]);
|
|
// A removal drill copy may lack the excused file; an excuse is stale only where the file is checked.
|
|
expect(
|
|
MADE_UP_REPOSITORY_LISTS.filter(
|
|
(entry) => files.includes(entry.file) && !found.some(({ file, list }) => entry.file === file && entry.list === list),
|
|
),
|
|
"MADE_UP_REPOSITORY_LISTS entries that match no list any more",
|
|
).toEqual([]);
|
|
});
|
|
|
|
it("finds a literal root list, also after -- in an argument vector, and nothing else", () => {
|
|
const tracked = new Set(["alpha", "beta"]);
|
|
const roots = new Set(["alpha", "beta", "gamma"]);
|
|
expect(literalRootLists(`const ROOTS = ["alpha", "beta/x.ts", "gamma"];`, tracked, roots)).toEqual([]);
|
|
expect(literalRootLists(`const ROOTS = ["alpha", "beta", "gamma"];`, tracked, roots)).toEqual([
|
|
"alpha, beta, gamma",
|
|
]);
|
|
expect(literalRootLists(`spawn("git", ["grep", "-l", "x", "--", "alpha", "beta"]);`, tracked, roots)).toEqual([
|
|
"alpha, beta",
|
|
]);
|
|
// A command list that names two items among other words is not a list of paths.
|
|
expect(literalRootLists(`const COMMANDS = ["alpha", "beta", "help"];`, tracked, roots)).toEqual([]);
|
|
// Untracked items alone never move with the code, as in a list of build output folders.
|
|
expect(literalRootLists(`const SKIP = ["alpha", "gamma"];`, tracked, roots)).toEqual([]);
|
|
expect(literalRootLists(`/** ["alpha", "beta"] */\n// ["alpha", "beta"]`, tracked, roots)).toEqual([]);
|
|
});
|
|
|
|
it("has a reader for every set", () => {
|
|
// A reader calls the registry with the set's name; naming it is not enough.
|
|
// This file reads secret-scan, which its policy test keeps equal.
|
|
const readers = trackedFiles()
|
|
.filter((file) => CODE_FILE.test(file) && existsSync(file) && file !== "scripts/lib/repository-layout.ts")
|
|
.map((file) => ({ file, source: readFileSync(file, "utf8") }));
|
|
const reads = (source: string, set: string) =>
|
|
new RegExp(String.raw`selectRepository(?:Paths|Entries)\(\s*"${set}"`, "u").test(source);
|
|
const unreadBy = (files: readonly { source: string }[]) =>
|
|
REPOSITORY_LAYOUT_SETS.filter((set) => !files.some(({ source }) => reads(source, set))).sort();
|
|
// A removal drill that copies no documents deletes the tests that read them
|
|
// (removalFixtureExcludedTests in scripts/lib/removal-fixture.ts), and with
|
|
// them the only readers of DOCUMENT_TEST_SETS; FE-GATE-020 failed on that.
|
|
const documentTestsDeleted = REMOVAL_FIXTURE_DOCUMENT_TESTS.some((file) => !existsSync(file));
|
|
expect(unreadBy(readers), "sets no code selects").toEqual(documentTestsDeleted ? DOCUMENT_TEST_SETS : []);
|
|
const documentTests = new Set<string>(REMOVAL_FIXTURE_DOCUMENT_TESTS);
|
|
expect(
|
|
unreadBy(readers.filter(({ file }) => !documentTests.has(file))),
|
|
"sets only REMOVAL_FIXTURE_DOCUMENT_TESTS select (DOCUMENT_TEST_SETS)",
|
|
).toEqual(DOCUMENT_TEST_SETS);
|
|
});
|
|
|
|
// 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([]);
|
|
});
|
|
});
|