Merge branch 'main' into claude/fe-b-docs-korean-645f55

정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
This commit is contained in:
DongHyeonka
2026-11-12 04:53:06 +09:00
141 changed files with 2113 additions and 1169 deletions
+6 -2
View File
@@ -9,6 +9,7 @@ import { ESLint } from "eslint";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { checkArchitectureLintFixtures } from "./lib/architecture-lint-fixtures.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { selectRepositoryEntries } from "./lib/repository-layout.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
@@ -1044,8 +1045,11 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
}
async function inspectTypeScriptOnlyPolicy(): Promise<TypeScriptOnlyPolicy> {
const requiredRoots = ["src", "scripts", "tests", ".storybook"] as const;
const optionalRoots = ["recipes"] as const;
// The typescript-only set of config/repository-layout.json (R2). An optional
// root (recipes/) may be gone after a removal drill.
const selected = selectRepositoryEntries("typescript-only");
const requiredRoots = selected.filter(({ optional }) => !optional).map(({ path }) => path);
const optionalRoots = selected.filter(({ optional }) => optional).map(({ path }) => path);
const checkedRoots = [...requiredRoots, ...optionalRoots];
const files = (
await Promise.all(
+5 -51
View File
@@ -1,5 +1,4 @@
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import {
@@ -25,25 +24,12 @@ import {
validateInstallScriptPolicy,
validatePackageScriptGraph,
} from "./lib/package-script-graph.ts";
import {
gatedTestPaths,
listTestFiles,
parseUngatedTestExclusions,
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
// 1103/12-07. The product's merge gates are entry scripts of CI as well.
// 1103/12-07. The product's merge gates run in the generated workflow too.
const { mergeGates: productGates } = await loadProductCiOverlay(process.cwd());
const productGateScripts = productGates.map(({ script }) => script);
const [packageDocument, nodeVersion] = await Promise.all([
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
readFile(".nvmrc", "utf8").then((value) => value.trim()),
@@ -82,42 +68,10 @@ failures.push(
),
);
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
try {
failures.push(
...ungatedTestFailures({
testFiles: await listTestFiles(process.cwd()),
gatedPaths: gatedTestPaths(
packageScripts,
[...contract.commands.map(({ script }) => script), ...productGateScripts],
(file) => readFileSync(file, "utf8"),
),
exclusions: parseUngatedTestExclusions(
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04. Whether every test file and verification script is reached by a
// gate is checked by check:ci:gating (scripts/check-ci-gating.ts) in the main
// stage (FE-GATE-029), not on every pull request (design-docs
// repo-structure/03-ci.md F2).
const immutable = index.gates.get("FE-GATE-015");
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
+77
View File
@@ -0,0 +1,77 @@
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { loadCiGateContract } from "./contracts/ci-gates.ts";
import { loadProductCiOverlay } from "./contracts/product-ci-overlay.ts";
import {
gatedTestPaths,
listTestFiles,
parseUngatedTestExclusions,
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
/**
* 12-04. Every test file and every verification package script is reached by
* a gate command of any stage, or config/ci/ungated-tests.json and
* config/ci/ungated-scripts.json say why not. It checks how the gates are
* wired, not the change, so it runs in the main stage (FE-GATE-029) after a
* merge (design-docs repo-structure/03-ci.md F2); check:ci keeps the contract
* and workflow checks on every pull request.
*/
const contract = await loadCiGateContract(process.cwd());
// 1103/12-07. The product's merge gates are entry scripts of CI as well.
const { mergeGates: productGates } = await loadProductCiOverlay(process.cwd());
const productGateScripts = productGates.map(({ script }) => script);
const packageScripts =
(JSON.parse(await readFile("package.json", "utf8")) as { scripts?: Record<string, string> }).scripts ?? {};
const failures: string[] = [];
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
try {
failures.push(
...ungatedTestFailures({
testFiles: await listTestFiles(process.cwd()),
gatedPaths: gatedTestPaths(
packageScripts,
[...contract.commands.map(({ script }) => script), ...productGateScripts],
(file) => readFileSync(file, "utf8"),
),
exclusions: parseUngatedTestExclusions(
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
if (failures.length > 0) {
process.stderr.write(`CI gating failed:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write("CI gating: every test file and verification script is gated or excluded with a reason PASS\n");
-62
View File
@@ -1,62 +0,0 @@
import { spawnSync } from "node:child_process";
import { readdir } from "node:fs/promises";
import { extname, resolve } from "node:path";
const recipeRoot = resolve("recipes");
const pnpmCli = requireEnvironment("npm_execpath");
if (!(await containsTypeScriptSource(recipeRoot))) {
process.stdout.write(
"Optional recipe typecheck: SKIP (no recipe TypeScript sources installed)\n",
);
} else {
const result = spawnSync(
process.execPath,
[pnpmCli, "exec", "tsc", "--project", "tsconfig.recipes.json"],
{ stdio: "inherit" },
);
if (result.error) {
throw result.error;
}
process.exitCode = result.status ?? 1;
}
function requireEnvironment(name: string): string {
const value = process.env[name];
if (!value) {
throw new Error(`${name} is required to typecheck optional recipes`);
}
return value;
}
async function containsTypeScriptSource(directory: string): Promise<boolean> {
let entries;
try {
entries = await readdir(directory, { withFileTypes: true });
} catch (error) {
if (hasErrorCode(error, "ENOENT")) {
return false;
}
throw error;
}
for (const entry of entries) {
const target = resolve(directory, entry.name);
if (entry.isDirectory() && (await containsTypeScriptSource(target))) {
return true;
}
if (entry.isFile() && [".ts", ".tsx", ".mts", ".cts"].includes(extname(entry.name))) {
return true;
}
}
return false;
}
function hasErrorCode(error: unknown, code: string): boolean {
return (
typeof error === "object" &&
error !== null &&
"code" in error &&
error.code === code
);
}
+1 -1
View File
@@ -54,7 +54,7 @@ try {
assertMatchesJsonSchema(
JSON.parse(
await readFile(
"schemas/config/frontend-capability-recipes.schema.json",
"config/schemas/recipes/frontend-capability-recipes.schema.json",
"utf8",
),
),
+1 -1
View File
@@ -748,7 +748,7 @@ if (usesRepositoryBaseline && failures.length === 0) {
assertMatchesJsonSchema(
JSON.parse(
await readFile(
"schemas/artifacts/registry-snapshot.schema.json",
"config/schemas/artifacts/registry-snapshot.schema.json",
"utf8",
),
),
+141
View File
@@ -0,0 +1,141 @@
import { spawn } from "node:child_process";
import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
/**
* The negative type fixtures (FE-GATE-003). Each fixture under
* tests/fixtures/typecheck states on its first line what tsc must say about
* it: `// expect: TS2322` (compilation fails and reports TS2322) or
* `// expect: pass` (it compiles; tests/fixtures/typecheck/invalid-diagnostics-port.ts
* holds one `@ts-expect-error` per violation). Every fixture compiles alone
* with tests/fixtures/typecheck/tsconfig.base.json, as the 23 one-file
* tsconfigs and package scripts this runner replaces did (design-docs
* repo-structure/04-frontend-layout.md §5.3 (가)).
*
* The check is the one run-ci-gate.ts applied to each of those commands:
* tsc exits 1 and its output contains `error TS<code>:`. A fixture without an
* expectation line fails, and so does a directory with no fixtures, so a new
* fixture cannot be skipped and an empty run cannot pass (R8).
*/
export const TYPE_FIXTURE_ROOT = "tests/fixtures/typecheck";
const BASE_CONFIG = `${TYPE_FIXTURE_ROOT}/tsconfig.base.json`;
/**
* tsc resolves `types` from the tsconfig's directory upwards, so the one-file
* tsconfigs are written inside the repository, in the ignored `.tmp/`.
*/
const CONFIG_ROOT = ".tmp/type-fixtures";
const EXPECTATION = /^\/\/ expect: (pass|TS\d{4,5})$/u;
/** Helpers that fixtures import are not fixtures. */
const FIXTURE_FILE = /^invalid-[\w-]+\.tsx?$/u;
const CONCURRENCY = 4;
export type TypeFixtureExpectation = { kind: "pass" } | { kind: "fail"; code: string };
export interface TypeFixtureResult {
file: string;
expectation: TypeFixtureExpectation | undefined;
passed: boolean;
/** The diagnostic lines that met the expectation, or all output on failure. */
evidence: string[];
}
export function parseTypeFixtureExpectation(source: string): TypeFixtureExpectation | undefined {
const match = EXPECTATION.exec(source.split("\n", 1)[0]?.trimEnd() ?? "");
if (!match?.[1]) return undefined;
return match[1] === "pass" ? { kind: "pass" } : { kind: "fail", code: match[1] };
}
export async function listTypeFixtures(root: string): Promise<string[]> {
return (await readdir(path.join(root, TYPE_FIXTURE_ROOT)))
.filter((name) => FIXTURE_FILE.test(name))
.sort()
.map((name) => `${TYPE_FIXTURE_ROOT}/${name}`);
}
export function judgeTypeFixture(
expectation: TypeFixtureExpectation,
exitCode: number | null,
output: string,
): Pick<TypeFixtureResult, "passed" | "evidence"> {
const lines = output.split("\n").filter((line) => line.trim().length > 0);
if (expectation.kind === "pass") {
return { passed: exitCode === 0, evidence: lines };
}
const matching = lines.filter((line) => line.includes(`error ${expectation.code}:`));
return exitCode === 1 && matching.length > 0
? { passed: true, evidence: matching }
: { passed: false, evidence: [`tsc exit ${exitCode}`, ...lines] };
}
function runTsc(root: string, config: string): Promise<{ exitCode: number | null; output: string }> {
return new Promise((resolve, reject) => {
const child = spawn(path.join(root, "node_modules/.bin/tsc"), ["--project", config, "--pretty", "false"], {
cwd: root,
stdio: ["ignore", "pipe", "pipe"],
});
let output = "";
child.stdout.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
child.stderr.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
child.on("error", reject);
child.on("close", (exitCode) => resolve({ exitCode, output }));
});
}
async function checkTypeFixture(root: string, file: string): Promise<TypeFixtureResult> {
const expectation = parseTypeFixtureExpectation(await readFile(path.join(root, file), "utf8"));
if (!expectation) {
return { file, expectation, passed: false, evidence: ["missing `// expect:` first line"] };
}
const config = path.join(CONFIG_ROOT, `tsconfig.${path.basename(file).replace(/\.tsx?$/u, "")}.json`);
const fromConfig = (target: string) => path.relative(path.dirname(config), target);
await writeFile(
path.join(root, config),
`${JSON.stringify({ extends: fromConfig(BASE_CONFIG), files: [fromConfig(file)] }, null, 2)}\n`,
);
const { exitCode, output } = await runTsc(root, config);
return { file, expectation, ...judgeTypeFixture(expectation, exitCode, output) };
}
export async function checkTypeFixtures(root: string): Promise<TypeFixtureResult[]> {
const fixtures = await listTypeFixtures(root);
await rm(path.join(root, CONFIG_ROOT), { recursive: true, force: true });
await mkdir(path.join(root, CONFIG_ROOT), { recursive: true });
const results: TypeFixtureResult[] = new Array(fixtures.length);
let next = 0;
await Promise.all(
Array.from({ length: Math.min(CONCURRENCY, fixtures.length) }, async () => {
while (next < fixtures.length) {
const index = next++;
results[index] = await checkTypeFixture(root, fixtures[index]!);
}
}),
);
return results;
}
function describeExpectation(expectation: TypeFixtureExpectation | undefined): string {
if (!expectation) return "no expectation";
return expectation.kind === "pass" ? "expect pass" : `expect ${expectation.code}`;
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const results = await checkTypeFixtures(process.cwd());
for (const result of results) {
process.stdout.write(
`${result.passed ? "PASS" : "FAIL"} ${result.file} (${describeExpectation(result.expectation)})\n`,
);
for (const line of result.evidence) process.stdout.write(` ${line}\n`);
}
const failed = results.filter(({ passed }) => !passed);
if (results.length === 0) {
process.stderr.write(`Type fixtures: FAIL (no fixtures under ${TYPE_FIXTURE_ROOT})\n`);
process.exitCode = 1;
} else if (failed.length > 0) {
process.stderr.write(`Type fixtures: FAIL (${failed.length} of ${results.length})\n`);
process.exitCode = 1;
} else {
process.stdout.write(`Type fixtures: PASS (${results.length} fixtures)\n`);
}
}
+55
View File
@@ -0,0 +1,55 @@
import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
/**
* R8 of docs/manual/03-outside-feature-folder.md: a check with nothing to
* check fails. tsc passes a tsconfig whose `files` is empty when it extends
* another one, so `check:types:web-worker` compiled zero files and passed
* FE-GATE-003 from 2026-09-25 until it was deleted on 2026-11-08. Every
* tsconfig a package script hands to tsc must list at least one file of this
* repository (lib and node_modules declarations do not count).
*/
const TSC_PROJECT = /\btsc\s+(?:--project|-p)\s+(\S+)/gu;
export function typecheckProjects(scripts: Readonly<Record<string, string>>): string[] {
const projects = new Set<string>();
for (const command of Object.values(scripts)) {
for (const match of command.matchAll(TSC_PROJECT)) projects.add(match[1]!);
}
return [...projects].sort();
}
export function ownInputFiles(listed: string): string[] {
return listed
.split("\n")
.map((line) => line.trim())
.filter((line) => line.length > 0 && !line.split(path.sep).includes("node_modules"));
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const scripts = (JSON.parse(readFileSync("package.json", "utf8")) as { scripts: Record<string, string> }).scripts;
const projects = typecheckProjects(scripts);
const counts = projects.map((project) => {
const result = spawnSync(path.resolve("node_modules/.bin/tsc"), ["--project", project, "--listFilesOnly"], {
encoding: "utf8",
});
if (result.error) throw result.error;
return { project, files: ownInputFiles(result.stdout).length };
});
const empty = counts.filter(({ files }) => files === 0);
if (projects.length === 0 || empty.length > 0) {
process.stderr.write(
projects.length === 0
? "Typecheck inputs: FAIL (no package script runs tsc --project)\n"
: `Typecheck inputs: FAIL (no input files: ${empty.map(({ project }) => project).join(", ")})\n`,
);
process.exitCode = 1;
} else {
process.stdout.write(
`Typecheck inputs: PASS (${counts.map(({ project, files }) => `${project} ${files}`).join(", ")})\n`,
);
}
}
+31 -109
View File
@@ -1,5 +1,4 @@
import { readFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import path from "node:path";
import { z } from "zod";
@@ -312,6 +311,7 @@ const stageSchema = z
"PROD_PROMOTION_READY",
"FIELD_SLO_READY",
"DOCUMENTATION_READY",
"MAIN_READY",
]),
needs: z.array(id).max(16),
gateIds: z.array(id).min(1).max(64),
@@ -405,9 +405,9 @@ const jobSchema = z
.object({
id,
displayName: workflowValue,
kind: z.enum(["gate-matrix", "gate-single", "immutable", "provider", "promotion", "deployment"]),
kind: z.enum(["gate-matrix", "gate-sequence", "gate-single", "immutable", "provider", "promotion", "deployment"]),
needs: z.array(id).max(32),
condition: z.enum(["always", "needs-success", "merge", "release", "production", "field", "documentation"]),
condition: z.enum(["always", "needs-success", "merge", "main", "release", "production", "field", "documentation"]),
timeoutMinutes: z.number().int().positive(),
gateIds: z.array(id).max(64),
browserGateIds: z.array(id).max(64),
@@ -467,106 +467,10 @@ export type CiGateContractIndex = Readonly<{
export const RETIRED_GATE_IDS: readonly string[] = Object.freeze(["FE-GATE-016"]);
export const CANONICAL_GATE_IDS: readonly string[] = Object.freeze(
Array.from({ length: 28 }, (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`)
Array.from({ length: 29 }, (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`)
.filter((gateId) => !RETIRED_GATE_IDS.includes(gateId)),
);
/**
* D-13. The contract's size and gate shape are a reviewed baseline, not code
* constants: a project that removes a sample or adds a gate records the new
* shape with `update:ci-contract-baseline` (owner and reason required) and the
* diff of this file is what review sees.
*/
export const CI_CONTRACT_BASELINE_PATH = "config/ci/contract-baseline.json";
const ciContractBaselineSchema = z
.object({
schemaVersion: z.literal(1),
owner: nonEmpty,
reason: nonEmpty,
gates: z.number().int().nonnegative(),
commands: z.number().int().nonnegative(),
commandReferences: z.number().int().nonnegative(),
artifacts: z.number().int().nonnegative(),
stages: z.number().int().nonnegative(),
gateShapeSha256: z.string().regex(/^[0-9a-f]{64}$/u),
})
.strict();
export type CiContractBaseline = z.infer<typeof ciContractBaselineSchema>;
function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
const normalized = gates.map(
({
id,
name,
commandIds,
logArtifactId,
evidenceArtifactIds,
retentionClassId,
requiresEnvironment,
hostRequirements,
}) => ({
id,
name,
commandIds,
logArtifactId,
evidenceArtifactIds,
retentionClassId,
requiresEnvironment: requiresEnvironment ?? [],
// Only gates that declare runner requirements carry the key, so the
// digest of every other gate stays what it was.
...(hostRequirements === undefined ? {} : { hostRequirements }),
}),
);
return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
}
export function measureCiContractBaseline(
contract: CiGateContract,
): Omit<CiContractBaseline, "schemaVersion" | "owner" | "reason"> {
return {
gates: contract.gates.length,
commands: contract.commands.length,
commandReferences: contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
),
artifacts: contract.artifacts.length,
stages: contract.stages.length,
gateShapeSha256: canonicalGateShapeSha256(contract.gates),
};
}
async function assertCiContractBaseline(
root: string,
contract: CiGateContract,
): Promise<void> {
const parsed = ciContractBaselineSchema.safeParse(
JSON.parse(await readFile(path.join(root, CI_CONTRACT_BASELINE_PATH), "utf8")),
);
if (!parsed.success) {
throw new TypeError(
`${CI_CONTRACT_BASELINE_PATH} invalid:\n${parsed.error.issues
.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
.join("\n")}`,
);
}
const baseline = parsed.data;
const drift = Object.entries(measureCiContractBaseline(contract))
.filter(([key, value]) => baseline[key as keyof CiContractBaseline] !== value)
.map(([key, value]) =>
`${key}: baseline ${String(baseline[key as keyof CiContractBaseline])}, contract ${String(value)}`
);
if (drift.length > 0) {
throw new TypeError(
`CI gate contract does not match ${CI_CONTRACT_BASELINE_PATH}:\n${drift.join("\n")}\n` +
"If the change is intended, review it and run " +
"CI_CONTRACT_BASELINE_OWNER=<team> CI_CONTRACT_BASELINE_REASON=<why> corepack pnpm update:ci-contract-baseline",
);
}
}
function retentionRegistryFailures(contract: CiGateContract): string[] {
const expectedRetentionClasses = [
{ id: "merge-cycle", policy: "at least through pull-request readiness decision" },
@@ -668,8 +572,6 @@ export async function loadCiGateContract(
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
);
}
// The baseline describes the template contract; the overlay is the product's.
await assertCiContractBaseline(root, template);
return contract;
}
@@ -843,7 +745,7 @@ function validateContractSemantics(
const expectedGateIds = CANONICAL_GATE_IDS;
if (JSON.stringify(contract.gates.map(({ id }) => id)) !== JSON.stringify(expectedGateIds)) {
issue(`gate registry must contain FE-GATE-001..028 without retired ${RETIRED_GATE_IDS.join(", ")} in canonical order`);
issue(`gate registry must contain FE-GATE-001..029 without retired ${RETIRED_GATE_IDS.join(", ")} in canonical order`);
}
const expectedStages: ReadonlyArray<readonly [string, string, readonly string[], readonly string[]]> = [
["merge", "MERGE_READY", [], PROMOTION_FORMULA.MERGE_READY],
@@ -851,6 +753,7 @@ function validateContractSemantics(
["production", "PROD_PROMOTION_READY", ["release"], PROMOTION_FORMULA.PROD_PROMOTION_READY],
["field", "FIELD_SLO_READY", ["production"], PROMOTION_FORMULA.FIELD_SLO_READY],
["documentation", "DOCUMENTATION_READY", [], PROMOTION_FORMULA.DOCUMENTATION_READY],
["main", "MAIN_READY", [], PROMOTION_FORMULA.MAIN_READY],
];
const stageShape = contract.stages.map(({ id, readiness, needs, gateIds }) => [id, readiness, needs, gateIds]);
if (JSON.stringify(stageShape) !== JSON.stringify(expectedStages)) {
@@ -912,10 +815,16 @@ function validateContractSemantics(
if (gateOwners.length > 1) issue(`multiply owned gate: ${gate.id} by ${gateOwners.join(", ")}`);
}
const expectedJobOwnership: Readonly<Record<string, readonly string[]>> = {
// The merge stage runs as three jobs, one install each (design-docs
// repo-structure/03-ci.md F1): checks that read the source and build it,
// tests, and the gates that need browsers. Each runs its gates one after
// another in this order; a failed gate does not skip the next.
// 15-01. The bundle budget (FE-GATE-012) runs on every PR: a feature that
// pushes initial JavaScript over budget fails before it merges, not at the
// next tagged release.
merge_gate: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-008", "FE-GATE-009", "FE-GATE-010", "FE-GATE-011", "FE-GATE-012", "FE-GATE-013", "FE-GATE-020"],
merge_static: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-010", "FE-GATE-011", "FE-GATE-012"],
merge_test: ["FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-013", "FE-GATE-020"],
merge_browser: ["FE-GATE-008", "FE-GATE-009"],
release_gate: ["FE-GATE-014", "FE-GATE-026", "FE-GATE-028"],
immutable_build: ["FE-GATE-015", "FE-GATE-027"],
vulnerability_provider: [],
@@ -927,9 +836,12 @@ function validateContractSemantics(
production_gate: ["FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
field_gate: ["FE-GATE-018"],
documentation_gate: ["FE-GATE-017"],
// F2. The checkers' own negative fixtures and the gating coverage check
// run after a merge to main, not on every pull request.
main_gate: ["FE-GATE-029"],
};
if (JSON.stringify(contract.jobs.map(({ id }) => id)) !== JSON.stringify(Object.keys(expectedJobOwnership))) {
issue("job registry must contain the exact ten canonical jobs in semantic order");
issue("job registry must contain the exact thirteen canonical jobs in semantic order");
}
for (const [jobId, gateIds] of Object.entries(expectedJobOwnership)) {
const job = contract.jobs.find(({ id }) => id === jobId);
@@ -938,8 +850,10 @@ function validateContractSemantics(
}
}
const expectedJobGraph: Readonly<Record<string, readonly [CiWorkflowJob["kind"], readonly string[], CiWorkflowJob["condition"]]>> = {
merge_gate: ["gate-matrix", [], "merge"],
release_gate: ["gate-matrix", ["merge_gate"], "release"],
merge_static: ["gate-sequence", [], "merge"],
merge_test: ["gate-sequence", [], "merge"],
merge_browser: ["gate-sequence", [], "merge"],
release_gate: ["gate-matrix", ["merge_static", "merge_test", "merge_browser"], "release"],
immutable_build: ["immutable", ["release_gate"], "release"],
vulnerability_provider: ["provider", ["immutable_build"], "always"],
provenance_provider: ["provider", ["immutable_build"], "always"],
@@ -948,6 +862,7 @@ function validateContractSemantics(
production_gate: ["gate-matrix", ["immutable_build", "promotion", "deployment"], "production"],
field_gate: ["gate-single", ["production_gate"], "field"],
documentation_gate: ["gate-single", [], "documentation"],
main_gate: ["gate-sequence", [], "main"],
};
for (const [jobId, [kind, needs, condition]] of Object.entries(expectedJobGraph)) {
const job = contract.jobs.find(({ id }) => id === jobId);
@@ -956,7 +871,9 @@ function validateContractSemantics(
}
}
const expectedStepKinds: Readonly<Record<string, readonly CiWorkflowStep["kind"][]>> = {
merge_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
merge_static: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
merge_test: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
merge_browser: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
release_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload", "upload"],
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
@@ -966,6 +883,7 @@ function validateContractSemantics(
production_gate: ["checkout", "setup-node", "frozen-install", "download", "extract", "run-gate", "upload"],
field_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
documentation_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
main_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
};
for (const [jobId, expected] of Object.entries(expectedStepKinds)) {
const actual = contract.jobs.find(({ id }) => id === jobId)?.steps.map(({ kind }) => kind);
@@ -974,7 +892,9 @@ function validateContractSemantics(
}
}
const expectedEnvironmentBindings: Readonly<Record<string, readonly Readonly<{ name: string; value: string }> []>> = {
merge_gate: [],
merge_static: [],
merge_test: [],
merge_browser: [],
release_gate: [],
immutable_build: [
// FE-GATE-027 admits the built artifact to a named environment, so both
@@ -1037,6 +957,7 @@ function validateContractSemantics(
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
],
documentation_gate: [],
main_gate: [],
};
for (const job of contract.jobs) {
const environmentNames = job.environment.map(({ name }) => name);
@@ -1361,6 +1282,7 @@ function validateJobStepKinds(
): void {
const allowed: Readonly<Record<z.infer<typeof jobSchema>["kind"], ReadonlySet<string>>> = {
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "run-gate", "upload"]),
"gate-sequence": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]),
"gate-single": new Set(["checkout", "setup-node", "frozen-install", "run-gate", "upload"]),
immutable: new Set(["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"]),
provider: new Set(["checkout", "setup-node", "frozen-install", "download", "extract", "run-provider", "validate-provider-evidence", "upload"]),
+16 -3
View File
@@ -880,7 +880,7 @@ const manualA11yResultSchema = z
})
.strict()
.superRefine((result, context) => {
if (result.path !== `artifacts/tests/a11y-manual/${result.routeId}.md`) {
if (result.path !== `docs/accessibility/route-reviews/${result.routeId}.md`) {
context.addIssue({ code: "custom", path: ["path"], message: "path must match routeId" });
}
const hasIdentity = Boolean(
@@ -1429,7 +1429,7 @@ export const documentationReviewArtifactSchema = z
reportDigestValid: z.boolean(),
/**
* The manual accessibility review scope: the installed routes that have no
* record file under artifacts/tests/a11y-manual/. It is derived from the
* record file under docs/accessibility/route-reviews/. It is derived from the
* route registry, not read off a document (1101/14-05).
*/
routeScope: z.array(
@@ -1472,6 +1472,18 @@ export const documentationReviewArtifactSchema = z
})
.strict(),
).min(1),
// R6·R7 of docs/manual/03-outside-feature-folder.md: a manual example that
// points at a deletable sample feature, or infrastructure configuration
// copied into a current document.
layoutRuleViolations: z.array(
z
.object({
path: nonEmptyString,
rule: z.enum(["R6", "R7"]),
detail: nonEmptyString,
})
.strict(),
),
results: z.array(
z
.object({
@@ -1523,9 +1535,10 @@ export const documentationReviewArtifactSchema = z
entry.missingScripts.length === 0 &&
entry.unknownGateIds.length === 0,
) &&
artifact.layoutRuleViolations.length === 0 &&
artifact.results.every(({ passed }) => passed))
) {
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references and review results" });
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references, layout rules and review results" });
}
});
+2 -2
View File
@@ -375,7 +375,7 @@ export function planFeature(
: []),
...planned.map(
(route) =>
[`artifacts/tests/a11y-manual/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
[`docs/accessibility/route-reviews/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
),
]);
return Object.freeze({
@@ -1767,7 +1767,7 @@ function report(plan: FeaturePlan): string {
"",
"Next:",
` 1. Before a release, have a person review and sign ${plan.routes
.map((route) => `artifacts/tests/a11y-manual/${route.routeId}.md`)
.map((route) => `docs/accessibility/route-reviews/${route.routeId}.md`)
.join(", ")} (FE-GATE-028). The merge gates check only their format.`,
" 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage in config/ci/gates.json (README lists the loop). test:feature-scaffold runs them on a generated feature except the browser gates FE-GATE-008/009 and test:system.",
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
+4 -4
View File
@@ -15,22 +15,22 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const ARTIFACT_SCHEMA_DEFINITIONS = Object.freeze([
{
relativePath: "schemas/artifacts/build-manifest.schema.json",
relativePath: "config/schemas/artifacts/build-manifest.schema.json",
id: undefined,
schema: buildManifestArtifactSchema,
},
{
relativePath: "schemas/artifacts/dependency-inventory.schema.json",
relativePath: "config/schemas/artifacts/dependency-inventory.schema.json",
id: "https://clean-architecture-frontend.local/schemas/dependency-inventory.schema.json",
schema: dependencyInventoryArtifactSchema,
},
{
relativePath: "schemas/artifacts/registry-snapshot.schema.json",
relativePath: "config/schemas/artifacts/registry-snapshot.schema.json",
id: undefined,
schema: registrySnapshotArtifactSchema,
},
{
relativePath: "schemas/artifacts/supply-chain-verification.schema.json",
relativePath: "config/schemas/artifacts/supply-chain-verification.schema.json",
id: "https://clean-architecture-frontend.local/schemas/supply-chain-verification.schema.json",
schema: supplyChainVerificationArtifactSchema,
},
+18 -3
View File
@@ -71,7 +71,7 @@ const PRODUCT_GATE_JOB = "product_merge_gate";
* gate stopped nothing but a PR merge: the same run went on to release, build,
* promote and deploy, and the fixed job graph left a product no way to link
* them. release_gate is the first release-stage job, and every later one
* depends on it as it depends on merge_gate. The link is rendered from the
* depends on it as it depends on the merge jobs. The link is rendered from the
* overlay, so the template contract's job graph (and its check) stays the
* template's, and without product gates the workflow bytes do not change.
*/
@@ -108,6 +108,7 @@ export function renderCiWorkflow(
" type: choice",
" options:",
" - merge",
" - main",
" - release",
" - production",
" - field",
@@ -231,7 +232,7 @@ function renderJob(
}
}
lines.push(" steps:");
for (const step of job.steps) lines.push(...renderStep(job, step, transfers));
for (const step of job.steps) lines.push(...renderStep(job, step, transfers, index));
return lines;
}
@@ -257,6 +258,7 @@ function renderStep(
job: CiWorkflowJob,
step: CiWorkflowStep,
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
index: ReturnType<typeof indexCiGateContract>,
): string[] {
switch (step.kind) {
case "checkout":
@@ -294,6 +296,16 @@ function renderStep(
return [" - name: Run blocking gate", " run: corepack pnpm ci:gate -- ${{ matrix.gate }}"];
}
if (job.gateIds.length === 0) throw new TypeError(`run-gate step lacks ownership: ${job.id}`);
// F2·F1 (design-docs repo-structure/03-ci.md). A job of several gates
// shares one install; each gate is a step named by its id, and a failed
// gate does not skip the ones after it, as the matrix entries did not.
if (job.kind === "gate-sequence") {
return job.gateIds.flatMap((gateId) => [
` - name: ${yamlScalar(`${gateId} / ${index.gates.get(gateId)?.name ?? ""}`)}`,
" if: ${{ !cancelled() }}",
` run: corepack pnpm ci:gate -- ${gateId}`,
]);
}
// 12-02: every gate the job owns runs, in order. Rendering only the first
// left FE-GATE-027 (release admission) out of the workflow.
return job.gateIds.flatMap((gateId) => [
@@ -426,7 +438,10 @@ function renderCondition(condition: CiWorkflowJob["condition"]): string | null {
const expressions: Record<CiWorkflowJob["condition"], string | null> = {
always: null,
"needs-success": null,
merge: "${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}",
merge: "${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}",
// A push to a branch (main, develop) or a dispatch that asks for it; never
// a pull request or a tag.
main: "${{ (gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/heads/')) || (gitea.event_name == 'workflow_dispatch' && inputs.stage == 'main') }}",
release: "${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}",
production: "${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}",
field: "${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'field' }}",
+4 -3
View File
@@ -4,11 +4,11 @@ export const ciContractReportSchema = z
.object({
schemaVersion: z.literal(2),
nodeVersion: z.string().regex(/^\d+\.\d+\.\d+$/u),
gateCount: z.literal(27),
gateCount: z.literal(28),
commandDefinitionCount: z.number().int().positive(),
commandReferenceCount: z.number().int().positive(),
artifactCount: z.number().int().positive(),
jobCount: z.literal(10),
jobCount: z.literal(13),
workflowSha256: z.string().regex(/^[a-f0-9]{64}$/u),
durationStatus: z.string().min(1),
negativeFixtures: z.array(
@@ -20,6 +20,7 @@ export const ciContractReportSchema = z
"PROD_PROMOTION_READY",
"FIELD_SLO_READY",
"DOCUMENTATION_READY",
"MAIN_READY",
]),
failedGate: z.string().regex(/^FE-GATE-\d{3}$/u),
passed: z.boolean(),
@@ -37,7 +38,7 @@ export const ciContractReportSchema = z
fail(["passed"], "passed must agree with failures");
}
if (
report.negativeFixtures.length !== 5 ||
report.negativeFixtures.length !== 6 ||
report.negativeFixtures.some((fixture) => !fixture.passed)
) {
fail(["negativeFixtures"], "every readiness negative fixture must pass");
+1 -1
View File
@@ -93,7 +93,7 @@ export const HISTORY_HOLDERS: ReadonlySet<string> = new Set([
// Not documents: the manual accessibility records are gate input in a fixed
// English key format (scripts/lib/manual-a11y-evidence.ts), like the backend's
// test resources.
const NOT_DOCUMENT = /^artifacts\/tests\/a11y-manual\//u;
const NOT_DOCUMENT = /^docs\/accessibility\/route-reviews\//u;
const IGNORED_FOLDERS: ReadonlySet<string> = new Set(["node_modules", ".git"]);
const STATUS: Readonly<Record<RecordKind, readonly string[]>> = Object.freeze({
+1 -1
View File
@@ -17,7 +17,7 @@ import type { RemovalCheck } from "./removal-fixture.ts";
*/
const BROWSER =
"needs Playwright browsers. FE-GATE-020 runs in a merge job without them " +
"(merge_gate matrix browser: false). The generated routes in the browser " +
"(merge_test installs none). The generated routes in the browser " +
"gates are reviewed as 1103/12-01 and 12-03.";
const DRILL =
"a removal drill copies the repository again. The drill runs the generated " +
+3 -3
View File
@@ -122,12 +122,12 @@ export async function verifyLocalSupplyChainEvidence(
for (const [schemaPath, artifact, label] of [
[
"schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
inventory,
"dependency inventory",
],
[
"schemas/artifacts/supply-chain-verification.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
verification,
"supply-chain verification",
],
@@ -1020,7 +1020,7 @@ export async function assessLocalEvidenceForProducer(input: Readonly<{
assertMatchesJsonSchema(
await readJson(
repositoryRoot,
"schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/build-manifest.schema.json",
),
buildManifest,
"build manifest",
+6
View File
@@ -40,6 +40,10 @@ export const PROMOTION_FORMULA = Object.freeze({
]),
FIELD_SLO_READY: Object.freeze(["FE-GATE-018"]),
DOCUMENTATION_READY: Object.freeze(["FE-GATE-017"]),
// F2 (design-docs repo-structure/03-ci.md 7.3). The checkers' negative
// fixtures and the gating coverage check run after a merge to main. They
// test the checkers, not the change, so they hold no promotion.
MAIN_READY: Object.freeze(["FE-GATE-029"]),
});
export type GateResult = "PASS" | "FAIL" | "UNVERIFIED";
@@ -58,6 +62,7 @@ export function evaluatePromotionReadiness(
const fieldReady =
productionReady && allPass(PROMOTION_FORMULA.FIELD_SLO_READY);
const documentationReady = allPass(PROMOTION_FORMULA.DOCUMENTATION_READY);
const mainReady = allPass(PROMOTION_FORMULA.MAIN_READY);
return Object.freeze({
MERGE_READY: mergeReady,
@@ -65,5 +70,6 @@ export function evaluatePromotionReadiness(
PROD_PROMOTION_READY: productionReady,
FIELD_SLO_READY: fieldReady,
DOCUMENTATION_READY: documentationReady,
MAIN_READY: mainReady,
});
}
+3 -3
View File
@@ -58,6 +58,9 @@ export const LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS = Object.freeze([
] as const);
export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
"config/schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
"config/security/dependency-baseline.approval.json",
"config/security/dependency-baseline.json",
"config/security/dependency-change-evidence.json",
@@ -65,9 +68,6 @@ export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
"config/security/secret-scan-policy.json",
"config/security/vulnerability-exceptions.json",
"config/security/vulnerability-policy.json",
"schemas/artifacts/build-manifest.schema.json",
"schemas/artifacts/dependency-inventory.schema.json",
"schemas/artifacts/supply-chain-verification.schema.json",
...LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS,
] as const);
+13 -36
View File
@@ -20,23 +20,19 @@ import {
linkFixtureNodeModules,
} from "./fixture-node-modules.ts";
import { generateCiWorkflow } from "../generate-ci-workflow.ts";
import { updateCiContractBaseline } from "../update-ci-contract-baseline.ts";
import { selectRepositoryPaths } from "./repository-layout.ts";
export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
"src", "tests", "recipes", "scripts", "schemas", "config", "public",
".gitea", ".storybook", "index.html", "package.json", "tsconfig.base.json",
"tsconfig.json", "tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json",
"tsconfig.recipes.json", "tsconfig.web-worker.json", "tsconfig.service-worker.json",
"vite.service-worker.config.ts", "vite.config.ts", "vitest.config.ts",
"playwright.config.ts", "playwright.capabilities.config.ts", "playwright.dev.config.ts",
"playwright.storybook.config.ts", "playwright.visual.config.ts", "eslint.config.ts",
".dependency-cruiser.json", ".nvmrc", ".gitignore",
// Install and workspace identity. Without these the fixture is not the same
// project: `corepack pnpm` resolves a different store, and the provider
// suites — which build a release candidate containing `pnpm-lock.yaml` —
// cannot assemble their fixture at all.
".npmrc", "pnpm-lock.yaml", "pnpm-workspace.yaml",
] as const);
/**
* The fixture-copy set of config/repository-layout.json (R2). It includes the
* install and workspace identity (`.npmrc`, `pnpm-lock.yaml`,
* `pnpm-workspace.yaml`): without them the fixture is not the same project,
* `corepack pnpm` resolves a different store, and the provider suites — which
* build a release candidate containing `pnpm-lock.yaml` — cannot assemble
* their fixture at all. It also carries the manual a11y review records
* (docs/accessibility/route-reviews), which unit tests read, without the rest
* of `docs/`.
*/
export const REMOVAL_FIXTURE_COPY_TARGETS = selectRepositoryPaths("fixture-copy");
/**
* This is the only copy-target list. Each removal script used to keep its own,
@@ -53,14 +49,7 @@ export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
* the documents describe the capability they delete, and what those drills
* prove is that the code still builds and tests without it.
*/
export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([
"README.md",
"CHANGELOG.md",
"docs",
// The root rule book. docs/README.md section 1 links it, so verify:documentation
// in the fixture reads it as a current contract document.
"AGENTS.md",
] as const);
export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = selectRepositoryPaths("fixture-documents");
/**
* 1103/02-06. Tests that read REMOVAL_FIXTURE_DOCUMENT_TARGETS. A fixture
@@ -522,16 +511,4 @@ export async function pruneRemovalFixtureCiContract(options: Readonly<{
writeFile(packagePath, `${JSON.stringify(packageDocument, null, 2)}\n`),
writeFile(gatesPath, `${JSON.stringify(validated, null, 2)}\n`),
]);
// D-13: the reduced contract is a new baseline, recorded the way a project
// that removes the capability records it; canonical check:ci then applies.
// 1103/16-02. A product feature owns no CI script; an empty list used to
// leave a trailing blank that the baseline schema refuses.
await updateCiContractBaseline(options.root, {
owner: "removal-fixture",
reason: `removal fixture pruned ${
options.removedScripts.size === 0
? "no CI scripts"
: [...options.removedScripts].join(", ")
}`,
});
}
+141
View File
@@ -0,0 +1,141 @@
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).
*/
export const REPOSITORY_LAYOUT_SETS = Object.freeze([
"fixture-copy",
"fixture-documents",
"secret-scan",
"history-free",
"scale-source",
"vite-build",
"typescript-only",
] 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",
] 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");
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}`);
}
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;
}
+4 -11
View File
@@ -1,3 +1,5 @@
import { selectRepositoryPaths } from "./repository-layout.ts";
/**
* 1105/15-03. The files `vite build` reads from the repository root, for the
* measurements and tests that copy them into a temporary root and build
@@ -7,15 +9,6 @@
* a new local import in vite.config.ts broke both, and both had to be edited
* (7f9a515, 799ab7f). tests/unit/vite-build-inputs.test.ts fails, naming the
* file, when vite.config.ts imports a local file this list does not cover.
* The list is the vite-build set of config/repository-layout.json (R2).
*/
export const VITE_BUILD_INPUTS = Object.freeze([
"src",
"public",
"index.html",
"package.json",
"vite.config.ts",
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/run-isolation.ts",
"scripts/lib/vite-module-inventory.ts",
] as const);
export const VITE_BUILD_INPUTS = selectRepositoryPaths("vite-build");
-1
View File
@@ -42,7 +42,6 @@ try {
});
const removedCiScripts = new Set([
"check:types:recipes",
"test:recipes",
"check:optional-recipes",
"check:optional-recipes:source",
-52
View File
@@ -1,52 +0,0 @@
import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import {
CI_CONTRACT_BASELINE_PATH,
measureCiContractBaseline,
parseCiGateContract,
type CiContractBaseline,
} from "./contracts/ci-gates.ts";
/**
* D-13. Records the current `config/ci/gates.json` size and gate shape as the
* reviewed baseline. Run it after an intended contract change; the diff of
* `config/ci/contract-baseline.json` is what review approves.
*/
export async function updateCiContractBaseline(
root: string,
approval: Readonly<{ owner: string; reason: string }>,
): Promise<CiContractBaseline> {
const contract = parseCiGateContract(
JSON.parse(await readFile(path.join(root, "config/ci/gates.json"), "utf8")),
);
const baseline: CiContractBaseline = {
schemaVersion: 1,
owner: approval.owner,
reason: approval.reason,
...measureCiContractBaseline(contract),
};
await writeFile(
path.join(root, CI_CONTRACT_BASELINE_PATH),
`${JSON.stringify(baseline, null, 2)}\n`,
);
return baseline;
}
const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isCli) {
const owner = process.env.CI_CONTRACT_BASELINE_OWNER;
const reason = process.env.CI_CONTRACT_BASELINE_REASON;
if (!owner || !reason) {
process.stderr.write(
"CI_CONTRACT_BASELINE_OWNER and CI_CONTRACT_BASELINE_REASON are required.\n",
);
process.exit(1);
}
const baseline = await updateCiContractBaseline(process.cwd(), { owner, reason });
process.stdout.write(
`CI contract baseline updated: ${baseline.gates} gates, ${baseline.commands} commands, ` +
`${baseline.commandReferences} command references, ${baseline.artifacts} artifacts\n`,
);
}
+2 -2
View File
@@ -24,7 +24,7 @@ type ManualA11yResult = Readonly<{
if (process.argv.includes("--format-only")) {
const failures: string[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const record = await readFile(path, "utf8").catch(() => null);
const invalid = record === null ? ["missing record"] : validateManualA11yRecordFormat(record, routeId);
if (invalid.length > 0) failures.push(`${path}: ${invalid.join(", ")}`);
@@ -41,7 +41,7 @@ if (process.argv.includes("--format-only")) {
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const evidence = await readFile(path, "utf8");
const validation = validateManualA11yEvidence(evidence);
const failures =
+51 -3
View File
@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts";
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
import { checkDocsSystem, deletableHistory, HISTORY_HOLDERS, livingDocuments } from "./lib/docs-system.ts";
import { checkDocsSystem, checkedForDrift, deletableHistory, HISTORY_HOLDERS, livingDocuments } from "./lib/docs-system.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
import {
REMOVABLE_TEMPLATE_FEATURES,
@@ -22,7 +22,7 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
* every new feature edit two template-owned documents (1101/14-05), so the
* documents now name this folder and the record files are what is checked.
*/
const MANUAL_A11Y_RECORDS = "artifacts/tests/a11y-manual/";
const MANUAL_A11Y_RECORDS = "docs/accessibility/route-reviews/";
type DocumentationReview = Readonly<{
sourcePath: string;
@@ -167,7 +167,8 @@ const DOCUMENT_INDEX = "docs/README.md";
const UNCHECKED_DOCUMENTS = HISTORY_HOLDERS;
const NOT_CREATED = new Set([
// Reserved by generic-worker-has-no-network-or-credentials. The generic CPU
// worker is NOT_SELECTED (tsconfig.web-worker.json).
// worker is NOT_SELECTED; docs/manual/03-outside-feature-folder.md says how
// to add it with its own tsconfig.
"src/adapters/web-worker",
]);
// pnpm's own commands, which are not package scripts.
@@ -411,6 +412,46 @@ const documentReferencesValid = documentReferences.every(
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
);
// Repository layout rules of docs/manual/03-outside-feature-folder.md.
// R6: the manual's examples point at generator output or at code blocks in
// the manual, never at a sample feature a copy is meant to delete (the
// template's own sample took the manual's examples with it on 2026-11-07).
// R7: host, cluster and infrastructure configuration (nginx, Kubernetes,
// Helm, Terraform) lives in the infrastructure repository; a current document
// links to it and states the host contract (config/hosting/, FE-GATE-019)
// instead of carrying a copy. The history folders are records and keep what
// they recorded: the current documents are the living documents
// scripts/lib/docs-system.ts reads for drift (records and decision records out).
const INFRASTRUCTURE_FENCE = /^\s*```\s*(nginx|hcl|terraform|helm)\b/iu;
const INFRASTRUCTURE_MANIFEST =
/^\s*kind:\s*(Deployment|StatefulSet|DaemonSet|Ingress|Service|ConfigMap|CronJob|HelmRelease|Kustomization)\s*$/u;
const sampleFeaturePaths = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => removableTemplateFeaturePaths(feature));
const currentDocuments = [
"README.md",
...((await readdir("docs", { recursive: true }).catch(() => [])) as string[])
.filter((name) => name.endsWith(".md"))
.map((name) => `docs/${name}`)
.filter(checkedForDrift),
].sort();
const layoutRuleViolations: { path: string; rule: "R6" | "R7"; detail: string }[] = [];
for (const document of currentDocuments) {
const text = await readFile(document, "utf8").catch(() => null);
if (text === null) continue;
let fenced = false;
text.split("\n").forEach((line, index) => {
if (/^\s*```/u.test(line)) fenced = !fenced;
if (INFRASTRUCTURE_FENCE.test(line) || (fenced && INFRASTRUCTURE_MANIFEST.test(line))) {
layoutRuleViolations.push({ path: document, rule: "R7", detail: `line ${index + 1}: ${line.trim()}` });
}
if (!document.startsWith("docs/manual/")) return;
for (const samplePath of sampleFeaturePaths) {
if (line.includes(samplePath)) {
layoutRuleViolations.push({ path: document, rule: "R6", detail: `line ${index + 1}: ${samplePath}` });
}
}
});
}
// docs-system.md K1, K2, K4-K6 and the polite-form rule: language, record
// head blocks, copied numbers, the documents map, README sections, style.
const documentsSystem = checkDocsSystem(process.cwd(), rootDirectory);
@@ -425,6 +466,7 @@ const failedChecks = [
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
...(sourceStructureDocumented ? [] : ["source structure"]),
...(documentReferencesValid ? [] : ["document references"]),
...(layoutRuleViolations.length === 0 ? [] : ["repository layout rules"]),
...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]),
...(results.length === 2 && results.every((result) => result.passed)
? []
@@ -449,6 +491,7 @@ await writeValidatedJsonArtifact({
missingRuntimeVariables,
sourceStructure,
documentReferences,
layoutRuleViolations,
results,
passed,
},
@@ -486,6 +529,11 @@ if (!passed) {
);
}
}
for (const violation of layoutRuleViolations) {
process.stderr.write(
`${violation.path} breaks ${violation.rule} of docs/manual/03-outside-feature-folder.md: ${violation.detail}\n`,
);
}
if (documentReferences.some((entry) => entry.missingPaths.some((file) => file.startsWith("../")))) {
const checked = [...pairedTrees]
.filter(([, tree]) => "paths" in tree)
+15 -16
View File
@@ -5,6 +5,8 @@ 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.
*
@@ -46,20 +48,8 @@ export const EXTREME_SCALE_GATES = Object.freeze([
"check:scale:release",
] as const);
/** Inputs whose content defines "the current code" for this evidence. */
const SOURCE_ROOTS = Object.freeze(["src", "scripts", "tests", "config", ".storybook", "recipes"]);
const SOURCE_FILES = Object.freeze([
"package.json",
"pnpm-lock.yaml",
".dependency-cruiser.json",
"eslint.config.ts",
"vite.config.ts",
"vitest.config.ts",
"tsconfig.json",
"tsconfig.app.json",
"tsconfig.test.json",
"tsconfig.node.json",
]);
/** 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[] = [];
@@ -80,8 +70,17 @@ async function listFiles(directory: string): Promise<string[]> {
/** 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_ROOTS.map((entry) => listFiles(path.join(root, entry))))).flat(),
...SOURCE_FILES.map((file) => path.join(root, file)).filter((file) => existsSync(file)),
...(
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();
+1 -1
View File
@@ -129,7 +129,7 @@ if (liveTarget?.passed && !slotEmpty) {
} else {
mode = "fixture";
const fixture = await readDocument(
"config/hosting/response-headers.fixture.json",
"tests/fixtures/hosting/response-headers.json",
);
responses = responseHeaders(fixture.responses);
}
+1 -1
View File
@@ -95,7 +95,7 @@ const buildManifestDocument: unknown = JSON.parse(
);
assertMatchesJsonSchema(
JSON.parse(
await readFile("schemas/artifacts/build-manifest.schema.json", "utf8"),
await readFile("config/schemas/artifacts/build-manifest.schema.json", "utf8"),
),
buildManifestDocument,
"build manifest",