Files
clean-architecture-frontend…/scripts/lib/repository-layout.ts
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

173 lines
6.6 KiB
TypeScript

import { readFileSync } from "node:fs";
/**
* The repository root registry, config/repository-layout.json (R1 in
* docs/manual/03-outside-feature-folder.md). Every tracked root item has an
* entry, and every list of root paths is a named set chosen from it (R2).
* Seven places used to keep their own literal lists of root paths, each a
* different subset, so moving one root item meant editing all seven
* (design-docs repo-structure/04-frontend-layout.md §2.4); about twenty more
* lists followed on 2026-11-11. An untracked item (node_modules, dist, other
* worktrees) has an entry only when a set names it, such as the items a copy
* of the checkout skips.
*/
export const REPOSITORY_LAYOUT_SETS = Object.freeze([
"fixture-copy",
"fixture-documents",
"secret-scan",
"history-free",
"scale-source",
"vite-build",
"typescript-only",
"checkout-copy-skip",
"provider-fixture-skip",
"supply-chain-fixture-skip",
"fixture-code",
"package-manifest",
"playwright-configs",
"visual-evidence",
"documentation-inputs",
"agent-harness",
"feature-typecheck",
"product-typecheck",
"app-typecheck",
] as const);
export type RepositoryLayoutSet = (typeof REPOSITORY_LAYOUT_SETS)[number];
export const REPOSITORY_LAYOUT_KINDS = Object.freeze([
"source",
"tool-convention",
"gate-input",
"document",
"history",
"output",
"untracked",
] as const);
export type RepositoryLayoutKind = (typeof REPOSITORY_LAYOUT_KINDS)[number];
export type RepositoryLayoutEntry = Readonly<{
/** A root item name: one path segment, no slash. */
path: string;
kind: RepositoryLayoutKind;
role: string;
readBy: string;
/** A removal drill or a product copy may not have it; a selection skips it when absent. */
optional: boolean;
/** The sets that select the whole item. */
sets: readonly RepositoryLayoutSet[];
/** The sets that select only these paths inside the item. */
setPaths: Readonly<Partial<Record<RepositoryLayoutSet, readonly string[]>>>;
}>;
export const REPOSITORY_LAYOUT_FILE = "config/repository-layout.json";
export function parseRepositoryLayout(value: unknown): readonly RepositoryLayoutEntry[] {
const document = record(value, "layout");
if (document["schemaVersion"] !== 1) throw new Error("layout: schemaVersion must be 1");
// Each kind and set the code knows is described once in the file, and the file names no other.
for (const [field, known] of [
["kinds", REPOSITORY_LAYOUT_KINDS],
["sets", REPOSITORY_LAYOUT_SETS],
] as const) {
if (!(field in document)) continue;
const described = Object.keys(record(document[field], `layout.${field}`)).sort();
const expected = [...known].sort();
if (described.join() !== expected.join()) {
throw new Error(`layout.${field} must describe exactly ${expected.join(", ")}; it has ${described.join(", ")}`);
}
}
const entries = document["entries"];
if (!Array.isArray(entries) || entries.length === 0) {
throw new Error("layout: entries must be a non-empty array");
}
const seen = new Set<string>();
return Object.freeze(
entries.map((raw, index) => {
const entry = record(raw, `entries[${index}]`);
const at = `entries[${index}]`;
const itemPath = text(entry["path"], `${at}.path`);
if (itemPath.includes("/")) throw new Error(`${at}.path: a root item has no slash: ${itemPath}`);
if (seen.has(itemPath)) throw new Error(`${at}.path: duplicate root item ${itemPath}`);
seen.add(itemPath);
const kind = text(entry["kind"], `${at}.kind`);
if (!(REPOSITORY_LAYOUT_KINDS as readonly string[]).includes(kind)) {
throw new Error(`${at}.kind: unknown kind ${kind}`);
}
if (kind === "untracked" && entry["optional"] !== true) {
throw new Error(`${at}: an untracked item may be absent, so it is optional`);
}
const sets = (entry["sets"] ?? []) as unknown;
if (!Array.isArray(sets)) throw new Error(`${at}.sets must be an array`);
const setPaths = record(entry["setPaths"] ?? {}, `${at}.setPaths`);
for (const set of [...sets, ...Object.keys(setPaths)]) {
if (!(REPOSITORY_LAYOUT_SETS as readonly string[]).includes(set as string)) {
throw new Error(`${at}: unknown set ${String(set)}`);
}
}
for (const [set, paths] of Object.entries(setPaths)) {
if (!Array.isArray(paths) || paths.length === 0) {
throw new Error(`${at}.setPaths.${set} must be a non-empty array`);
}
for (const inner of paths) {
if (typeof inner !== "string" || !inner.startsWith(`${itemPath}/`)) {
throw new Error(`${at}.setPaths.${set}: ${String(inner)} is not inside ${itemPath}`);
}
}
if (sets.includes(set)) throw new Error(`${at}: ${set} selects the whole item and paths in it`);
}
return Object.freeze({
path: itemPath,
kind: kind as RepositoryLayoutKind,
role: text(entry["role"], `${at}.role`),
readBy: text(entry["readBy"], `${at}.readBy`),
optional: entry["optional"] === true,
sets: Object.freeze([...sets] as RepositoryLayoutSet[]),
setPaths: Object.freeze(setPaths as Partial<Record<RepositoryLayoutSet, readonly string[]>>),
});
}),
);
}
export const REPOSITORY_LAYOUT: readonly RepositoryLayoutEntry[] = parseRepositoryLayout(
JSON.parse(readFileSync(new URL(`../../${REPOSITORY_LAYOUT_FILE}`, import.meta.url), "utf8")),
);
/** The paths a set selects, in registry order. */
export function selectRepositoryPaths(
set: RepositoryLayoutSet,
layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT,
): readonly string[] {
return Object.freeze(
layout.flatMap((entry) =>
entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])],
),
);
}
/** Like selectRepositoryPaths, with whether a drill or a copy may lack each path. */
export function selectRepositoryEntries(
set: RepositoryLayoutSet,
layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT,
): readonly Readonly<{ path: string; optional: boolean }>[] {
return Object.freeze(
layout.flatMap((entry) =>
(entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])]).map(
(selected) => Object.freeze({ path: selected, optional: entry.optional }),
),
),
);
}
function record(value: unknown, at: string): Record<string, unknown> {
if (typeof value !== "object" || value === null || Array.isArray(value)) {
throw new Error(`${at} must be an object`);
}
return value as Record<string, unknown>;
}
function text(value: unknown, at: string): string {
if (typeof value !== "string" || value.trim() === "") throw new Error(`${at} must be a non-empty string`);
return value;
}