Files
clean-architecture-frontend…/tests/unit/repository-layout.test.ts
DongHyeonka 91962e24e3 test(setup): 자식 프로세스를 띄우는 시험이 잰 시간으로 timeout을 정한다
자식 프로세스를 띄우는 Vitest 시험 91개(24파일)가 기본 timeout 10초에
기대고 있었다. 셋은 FE-GATE-013에서만 도는 tests/system 시험이다.
기본값은 프로세스 안에서 도는 시험에 맞춘 값이다. 부하가 높은
desktop에서는 자식 프로세스 시험이 평소보다 크게 느려진다.
FE-GATE-020 drill 사본에서 평소 0.4~1.2초인 문서 시험이 10.6초 걸려
실패했다(2026-11-12). 가장 위험한 것은 tests/architecture/app-build-input
.test.ts로, desktop에서 이미 5.7초까지 걸렸다.

무엇을 고칠지는 desktop 계측으로 정했다.
- test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다. 시험마다
  띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은
  JSON reporter로 받았다.
- 시험마다 실제 timeout은 task.timeout으로 기록했다.
- 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다. tests/system은
  그 묶음에 없어서, 아래 검사가 잡은 셋을 따로 세 번 쟀다.

고친 것:
- tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대
  ms>)는 그 15배를 30초 단위로 올린 값이다. 15배는 위 0.7초 → 10.6초에서
  왔다. 시험마다 자기가 잰 최대값을 인자로 적어 근거가 호출 자리에 남는다.
- describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에,
  일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게
  잡지 않으려는 것이다.
- tests/setup.ts가 child_process 함수를 감싼다. 기본 timeout인 시험이
  자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
  helper나 시험이 import한 스크립트가 띄워도 잡는다. util.promisify가
  읽는 속성은 원래 함수에서 옮긴다.
- docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.

버린 것:
- 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
- 시험마다 손으로 정한 숫자: 근거가 남지 않고, 이미 있는 값도
  60_000·120_000처럼 근거가 없었다.
- 자식 프로세스를 띄우지 않게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는
  것이 이 시험들의 목적이라 범위가 커진다.
- 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와
  같은 파일의 다른 시험을 놓친다.

위험:
- hook(beforeAll 등)에서 띄우는 프로세스는 검사하지 않는다. 계측에서
  hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
- 같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의
  timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
- 다운스트림 시험이 기본값으로 자식 프로세스를 띄우면 test:unit 등이
  실패한다. 메시지가 helper를 알린다.

검증(desktop):
- 다섯 검사(test:unit·check:types·check:ci·lint·verify:documentation)
  rc=0.
- 자식 프로세스를 띄우는 시험 파일 40개와 tests/scale: rc=0, 검사 위반 0.
- tests/system: 115개 중 18개 실패. 모두 bwrap 호스트 제약이고 검사
  위반은 0이다.
- 변이: 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
  tracked-artifacts describe의 timeout을 지우면 그 시험이 검사 메시지로
  실패한다.
- 재현: CPU 10% 제한에서 app-build-input·registry-governance·hosting-probe
  ·design-system-rules를 돌렸다. main 650d22fa는 11개가 10초 timeout으로
  실패했다. 이 커밋은 71개 모두 통과했고, 가장 긴 시험은 17.7초였다.
2026-11-12 11:22:59 +09:00

286 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";
import { childProcessTimeout } from "../helpers/child-process-timeout.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([]);
}, childProcessTimeout(31));
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([]);
}, childProcessTimeout(20));
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([]);
}, childProcessTimeout(177));
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);
}, childProcessTimeout(310));
// 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([]);
}, childProcessTimeout(11));
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)", { timeout: childProcessTimeout(29) }, () => {
// 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([]);
});
});