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:
@@ -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(
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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");
|
||||
@@ -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
|
||||
);
|
||||
}
|
||||
@@ -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",
|
||||
),
|
||||
),
|
||||
|
||||
@@ -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",
|
||||
),
|
||||
),
|
||||
|
||||
@@ -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`);
|
||||
}
|
||||
}
|
||||
@@ -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
@@ -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"]),
|
||||
|
||||
@@ -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" });
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -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)`,
|
||||
|
||||
@@ -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,
|
||||
},
|
||||
|
||||
@@ -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,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");
|
||||
|
||||
@@ -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({
|
||||
|
||||
@@ -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 " +
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
|
||||
|
||||
@@ -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(", ")
|
||||
}`,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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");
|
||||
|
||||
@@ -42,7 +42,6 @@ try {
|
||||
});
|
||||
|
||||
const removedCiScripts = new Set([
|
||||
"check:types:recipes",
|
||||
"test:recipes",
|
||||
"check:optional-recipes",
|
||||
"check:optional-recipes:source",
|
||||
|
||||
@@ -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`,
|
||||
);
|
||||
}
|
||||
@@ -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 =
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user