정리 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 사본에서도 돌렸고, 집합 하나의 읽는 곳을 지우면 두 곳 모두 실패한다.
173 lines
6.6 KiB
TypeScript
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;
|
|
}
|