Files
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
2026-11-08 17:41:07 +09:00

331 lines
12 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
import { arch, platform, userInfo } from "node:os";
import path from "node:path";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
/**
* Executable evidence for the extreme-scale acceptance matrix.
*
* Runs every gate the acceptance rows cite, in order, under the *current*
* Node, and writes one machine-readable record:
* artifacts/quality/extreme-scale-gates.json
* artifacts/quality/extreme-scale-gates/<gate>.log
*
* On an unsupported Node the gates are not run at all and the record says
* `not-executed`; it is never reported as a failure of the code or as a pass.
* In an environment whose default Node is too old, put a supported binary
* first on PATH (for example a repository-local `.tmp/node24/bin`).
*/
export const EXTREME_SCALE_GATES = Object.freeze([
"check:feature-index",
"check:types:app",
"check:types:test",
"check:types",
"lint",
"check:architecture",
"check:app-build-input",
"check:request-fanout",
"check:registries",
"check:diagnostics",
"test:extreme-scale:focused",
"check:topology",
"check:traffic",
"check:observability",
"check:release-coherence",
"test:platform",
"check:scale:pr",
"check:scale:main",
"check:scale:baseline",
// The soak needs a build of the current source, never a stale dist/.
"build",
// The production bundle closure of the built app contains only its features.
"check:app-build-input:bundle",
"check:scale:nightly",
"check:scale:release",
] as const);
/** Inputs whose content defines "the current code": the scale-source set of config/repository-layout.json (R2). */
const SOURCE_PATHS = selectRepositoryPaths("scale-source");
async function listFiles(directory: string): Promise<string[]> {
const found: string[] = [];
let entries;
try {
entries = await readdir(directory, { withFileTypes: true });
} catch {
return found;
}
for (const entry of entries) {
const target = path.join(directory, entry.name);
if (entry.isDirectory()) found.push(...(await listFiles(target)));
else if (entry.isFile()) found.push(target);
}
return found;
}
/** sha256 over every source input (path + content), in a stable order. */
export async function sourceDigest(root: string): Promise<Readonly<{ digest: string; files: number }>> {
const files = [
...(
await Promise.all(
SOURCE_PATHS.map((entry) => path.join(root, entry)).map(async (target) =>
(await stat(target).catch(() => null))?.isDirectory()
? listFiles(target)
: existsSync(target)
? [target]
: [],
),
)
).flat(),
]
.map((file) => path.relative(root, file))
.sort();
const hash = createHash("sha256");
for (const file of files) {
hash.update(file).update("\0").update(await readFile(path.join(root, file))).update("\0");
}
return { digest: hash.digest("hex"), files: files.length };
}
/** Sums vitest `Tests N passed` / `N failed` lines from a gate log. */
export function vitestCounts(log: string): Readonly<{ passed: number; failed: number; skipped: number; files: number }> {
const escape = String.fromCharCode(27);
const plain = log.split(escape).map((part, index) => (index === 0 ? part : part.replace(/^\[[0-9;]*m/u, ""))).join("");
let passed = 0;
let failed = 0;
let skipped = 0;
let files = 0;
for (const line of plain.split("\n")) {
const tests = /^\s*Tests\s+(.*)$/u.exec(line);
if (tests) {
passed += Number(/(\d+) passed/u.exec(tests[1] as string)?.[1] ?? 0);
failed += Number(/(\d+) failed/u.exec(tests[1] as string)?.[1] ?? 0);
skipped += Number(/(\d+) skipped/u.exec(tests[1] as string)?.[1] ?? 0);
}
const fileLine = /^\s*Test Files\s+.*?(\d+) passed/u.exec(line);
if (fileLine) files += Number(fileLine[1]);
}
return { passed, failed, skipped, files };
}
type Version = readonly [number, number, number];
function parseVersion(value: string): Version {
const [major = 0, minor = 0, patch = 0] = value.replace(/^v/u, "").split(".").map(Number);
return [major, minor, patch];
}
function compare(left: Version, right: Version): number {
for (let index = 0; index < 3; index += 1) {
const difference = (left[index] ?? 0) - (right[index] ?? 0);
if (difference !== 0) return difference;
}
return 0;
}
/** Supports the `>=a.b.c <x.y.z` form this repository declares. */
export function satisfiesEngine(version: string, range: string): boolean {
const current = parseVersion(version);
for (const clause of range.trim().split(/\s+/u)) {
const match = /^(>=|<=|>|<|=)?(\d+(?:\.\d+){0,2})$/u.exec(clause);
if (!match) return false;
const order = compare(current, parseVersion(match[2] as string));
const operator = match[1] ?? "=";
const ok =
operator === ">=" ? order >= 0
: operator === "<=" ? order <= 0
: operator === ">" ? order > 0
: operator === "<" ? order < 0
: order === 0;
if (!ok) return false;
}
return true;
}
async function main(): Promise<void> {
const root = process.cwd();
const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")) as {
engines?: { node?: string };
};
const engine = pkg.engines?.node ?? "";
const directory = path.join(root, "artifacts/quality/extreme-scale-gates");
const artifact = path.join(root, "artifacts/quality/extreme-scale-gates.json");
await mkdir(directory, { recursive: true });
const startedAt = new Date();
const pnpmVersion =
spawnSync("corepack", ["pnpm", "--version"], { cwd: root, encoding: "utf8" }).stdout?.trim() ?? "";
const identity = {
node: process.version,
nodeMajor: Number(process.versions.node.split(".")[0]),
pnpm: pnpmVersion,
engine,
platform: platform(),
arch: arch(),
user: (() => {
try {
return userInfo().username;
} catch {
return "unknown";
}
})(),
};
if (!satisfiesEngine(process.version, engine)) {
await writeFile(
artifact,
`${JSON.stringify(
{
schemaVersion: 1,
generatedAt: new Date().toISOString(),
...identity,
status: "not-executed",
reason: `Node ${process.version} does not satisfy engines.node "${engine}"`,
gates: [],
},
null,
2,
)}\n`,
);
process.stderr.write(
`not executed: Node ${process.version} does not satisfy "${engine}". Put a supported node first on PATH.\n`,
);
process.exit(2);
}
const browsers = path.join(root, ".tmp/ms-playwright");
const env = {
...process.env,
pnpm_config_verify_deps_before_run: "false",
...(process.env["PLAYWRIGHT_BROWSERS_PATH"] === undefined && existsSync(browsers)
? { PLAYWRIGHT_BROWSERS_PATH: browsers }
: {}),
};
const only = process.argv.find((argument) => argument.startsWith("--only="))?.slice(7).split(",");
const gates = only ? EXTREME_SCALE_GATES.filter((gate) => only.includes(gate)) : EXTREME_SCALE_GATES;
const sourceBefore = await sourceDigest(root);
const results: {
gate: string;
status: "passed" | "failed";
exitCode: number | null;
durationMs: number;
tests: ReturnType<typeof vitestCounts>;
log: string;
}[] = [];
for (const gate of gates) {
const gateStartedAt = Date.now();
const run = spawnSync("corepack", ["pnpm", "run", gate], {
cwd: root,
env,
encoding: "utf8",
maxBuffer: 256 * 1024 * 1024,
});
const log = path.join(directory, `${gate.replaceAll(":", "-")}.log`);
await writeFile(log, `${run.stdout ?? ""}${run.stderr ?? ""}`);
const status = run.status === 0 ? "passed" : "failed";
const tests = vitestCounts(`${run.stdout ?? ""}${run.stderr ?? ""}`);
results.push({
gate,
status,
exitCode: run.status,
durationMs: Date.now() - gateStartedAt,
tests,
log: path.relative(root, log),
});
process.stdout.write(
`${status.toUpperCase()} ${gate} (${Date.now() - gateStartedAt}ms${tests.passed + tests.failed > 0 ? `, ${tests.passed} tests passed, ${tests.failed} failed` : ""})\n`,
);
}
const sourceAfter = await sourceDigest(root);
const readJson = async (relative: string) => {
const file = path.join(root, relative);
if (!existsSync(file)) return null;
const fresh = (await stat(file)).mtimeMs >= startedAt.getTime();
return { fresh, value: JSON.parse(await readFile(file, "utf8")) as Record<string, unknown> };
};
// Machine-readable artifacts the acceptance depends on must be produced by
// this run, on this Node, and say passed. An old PASS is not evidence.
const evidenceChecks: { artifact: string; check: string; passed: boolean }[] = [];
const expect = (artifact: string, check: string, passed: boolean) =>
evidenceChecks.push({ artifact, check, passed });
const ran = new Set(gates);
for (const tier of ["nightly", "release"] as const) {
if (!ran.has(`check:scale:${tier}`)) continue;
const relative = `artifacts/scale/${tier}/summary.json`;
const summary = await readJson(relative);
expect(relative, "regenerated during this run", summary?.fresh === true);
expect(relative, "status passed with no skipped step", summary?.value["status"] === "passed" && Array.isArray(summary.value["skipped"]) && summary.value["skipped"].length === 0);
const environment = summary?.value["environment"] as { nodeMajor?: number } | undefined;
expect(relative, `environment.nodeMajor == ${identity.nodeMajor}`, environment?.nodeMajor === identity.nodeMajor);
}
const soakRecord = ran.has("check:scale:nightly")
? await readJson("artifacts/scale/nightly/browser-soak.json")
: null;
if (ran.has("check:scale:nightly")) {
expect("artifacts/scale/nightly/browser-soak.json", "regenerated during this run", soakRecord?.fresh === true);
expect("artifacts/scale/nightly/browser-soak.json", "status passed (not skipped)", soakRecord?.value["status"] === "passed");
}
if (ran.has("check:scale:baseline")) {
const comparison = await readJson("artifacts/scale/baseline-comparison.json");
expect("artifacts/scale/baseline-comparison.json", "regenerated during this run", comparison?.fresh === true);
expect("artifacts/scale/baseline-comparison.json", "status passed on all axes (timing compatible)", comparison?.value["status"] === "passed");
}
if (ran.has("check:app-build-input:bundle")) {
const inventory = await readJson("artifacts/quality/vite-module-inventory.json");
expect(
"artifacts/quality/vite-module-inventory.json",
"produced by this run's build (bundle isolation checked on current code)",
inventory?.fresh === true,
);
}
expect("source tree", "unchanged while the gates ran", sourceBefore.digest === sourceAfter.digest);
const soak = soakRecord?.value ?? null;
const status =
results.every((result) => result.status === "passed") && evidenceChecks.every((check) => check.passed)
? "passed"
: "failed";
await writeFile(
artifact,
`${JSON.stringify(
{
schemaVersion: 1,
generatedAt: new Date().toISOString(),
startedAt: startedAt.toISOString(),
...identity,
source: { digest: sourceAfter.digest, files: sourceAfter.files },
status,
gates: results,
totals: {
gates: results.length,
passedGates: results.filter((result) => result.status === "passed").length,
testsPassed: results.reduce((sum, result) => sum + result.tests.passed, 0),
testsFailed: results.reduce((sum, result) => sum + result.tests.failed, 0),
},
evidenceChecks,
browserSoak: soak
? {
status: soak["status"],
classification: soak["classification"],
samples: Array.isArray(soak["samples"]) ? soak["samples"].length : 0,
summary: soak["summary"],
browser: soak["browser"],
build: soak["build"],
}
: null,
},
null,
2,
)}\n`,
);
process.stdout.write(`extreme-scale gates: ${status.toUpperCase()} on Node ${process.version} (${path.relative(root, artifact)})\n`);
if (status !== "passed") process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}