Files
clean-architecture-frontend…/tests/unit/repository-layout.test.ts
T
DongHyeonka 3f64c68991 refactor(layout): 남은 루트 경로 목록도 등록부 집합에서 고른다
정리 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 사본에서도
돌렸고, 집합 하나의 읽는 곳을 지우면 두 곳 모두 실패한다.
2026-11-12 01:17:55 +09:00

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([]);
});
});