정리 4단계의 R2 검사는 등록부를 쓰는 7곳만 봤다. 그 밖에 루트 이름을 담은 목록이 코드 15파일에 19개 따로 있어, 루트 항목 하나를 옮기면 여전히 여러 곳을 같이 고쳐야 했다. - 등록부에 집합 12개를 더했다. 사본 복사에서 건너뛰는 항목 셋 (checkout·provider·공급망 fixture), fixture 코드 범위, pnpm 매니페스트, Playwright 설정, visual 증거, 문서 입력, 에이전트 하네스, tsconfig 묶음 셋. 각 집합 설명에 읽는 파일을 적었다. - 사본이 건너뛰는 node_modules·dist·.tmp 같은 추적 안 하는 항목은 종류 untracked(optional)로 적는다. 추적 파일이 있으면 시험이 실패한다. - 19개 목록이 모두 집합을 고른다. 집합의 원소는 전과 같아 동작은 바뀌지 않는다. - R2 시험이 추적되는 코드 파일 전체를 본다. 루트 항목(이나 그 안 경로)만 담은 문자열 배열에 추적되는 루트 이름이 둘 이상이면 실패. 인자 목록은 `--` 뒤만 본다. main의 옛 목록 18개를 이 검사가 잡는 것을 확인했다. - 집합마다 selectRepositoryPaths·selectRepositoryEntries로 고르는 코드가 있는지 본다. 문서를 복사하지 않는 제거 drill(FE-GATE-020)은 문서 시험(REMOVAL_FIXTURE_DOCUMENT_TESTS)을 지우는데, 집합 셋 (agent-harness·documentation-inputs·feature-typecheck)은 그 시험만 읽는다. 시험이 이 셋을 적어 두고, 문서 시험이 지워진 사본에서만 셋이 비는 것을 허용한다. 셋이 바뀌면 전체 checkout에서 실패한다. - 파서가 kinds·sets 설명과 코드의 목록이 같은지 본다. - .gitignore 주석이 a11y 기록을 아직 artifacts/ 아래라고 적던 것을 고쳤다(정리 3단계에서 docs/로 옮김). 검증(desktop): test:unit, check:types, check:ci, lint, verify:documentation. repository-layout 시험을 문서 없는 제거 사본과 feature-scaffold 사본에서도 돌렸고, 집합 하나의 읽는 곳을 지우면 두 곳 모두 실패한다.
261 lines
13 KiB
TypeScript
261 lines
13 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"];
|
|
|
|
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);
|
|
expect(
|
|
files.flatMap((file) => literalRootLists(readFileSync(file, "utf8")).map((list) => `${file}: [${list}]`)),
|
|
`choose a set from ${REPOSITORY_LAYOUT_FILE} with selectRepositoryPaths`,
|
|
).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([]);
|
|
});
|
|
});
|