chore: sync the frontend template from ebea300 to af3d8e6

Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
DongHyeonka
2026-11-12 08:28:54 +09:00
parent 585c62431a
commit c80320dfc7
738 changed files with 55027 additions and 13567 deletions
+24 -6
View File
@@ -1,8 +1,11 @@
import { spawnSync } from "node:child_process";
import { rm } from "node:fs/promises";
import { rm, writeFile } from "node:fs/promises";
import process from "node:process";
import { SERVICE_WORKER_SCRIPT_PATH } from "../src/contracts/service-worker.ts";
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
import { makeDistFilesPublic } from "./lib/dist-permissions.ts";
import { SELF_UNREGISTERING_SERVICE_WORKER } from "./lib/self-unregistering-service-worker.ts";
/**
* §17.2.2. Deterministic two-pass build.
@@ -16,17 +19,23 @@ import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtim
* 4. materialize dist/config.json from the declared APP_PROFILE
* 5. scan app dist and generate the static asset source
* 6. ACTIVE only: Vite Service Worker build (emptyOutDir = false)
* REMOVE_REGISTRATION only: write the self-unregistering worker (06-03)
* 7. generate the self-contained TechLog production serving boundary
* 8. generate Release Manifest V2 and the build manifest
* 9. make every dist file readable by other users (13-02)
*
* Steps 5 and 6 are skipped for `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES`
* and `null`: those modes never run an active worker build.
* `REMOVE_REGISTRATION` still ships a `service-worker.js` so the browser's
* update check can replace a worker that stops the page from booting (D-5).
*
* Step 4 has to follow the Vite build and precede the asset scan. Vite copies
* `public/` verbatim, so without it every build — including a production one —
* ships the local runtime document; and the Service Worker hashes the emitted
* `config.json`, so the profile must be in place before that inventory is
* taken.
* Step 4 has to follow the Vite build. Vite copies `public/` verbatim, so
* without it every build — including a production one — ships the local
* runtime document. The Service Worker asset scan excludes `config.json`
* (`scripts/generate-service-worker-assets.ts`), so the order against step 5
* is not what keeps the profile out of the worker cache (13-15). Step 6 reads
* the release manifest URL from the `dist/config.json` step 4 wrote, and fails
* if its `APP_ENV` is not `APP_PROFILE` (06-10).
*/
const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker;
@@ -61,6 +70,12 @@ if (buildsActiveWorker) {
run("node", ["scripts/generate-service-worker-assets.ts", "dist"]);
// 6. service worker build
run("npx", ["vite", "build", "--config", "vite.service-worker.config.ts"]);
} else if (selection?.mode === "REMOVE_REGISTRATION") {
// 6. self-unregistering worker in place of the active one
await writeFile(
`dist/${SERVICE_WORKER_SCRIPT_PATH}`,
SELF_UNREGISTERING_SERVICE_WORKER,
);
} else {
process.stdout.write(
`service worker mode ${selection?.mode ?? "null"}: skipping worker build\n`,
@@ -72,3 +87,6 @@ run("node", ["scripts/generate-tech-log-serving-artifact.ts"]);
// 8. release + build manifest
run("node", ["scripts/generate-build-manifest.ts"]);
// 9. publishable permissions: the validated writer creates 0600 files
await makeDistFilesPublic("dist");
+12 -1
View File
@@ -201,7 +201,18 @@ async function main(): Promise<void> {
// 23 → 22: `storage/indexeddb/indexeddb-maintenance.ts`가 같은 이유로 지웠다.
// 22 → 21: `storage/indexeddb/indexeddb-runtime.ts`가 같은 이유로 지웠다.
// 이것으로 IndexedDB 어댑터 4벌이 모두 커널을 쓴다.
const HAND_ROLLED_ABORT_CEILING = 21;
// 21 → 19: `browser-files/download-delivery-adapter.ts`와
// `browser-files/browser-file-vault.ts`가 커널 race로 옮겨갔다(Q-6.2-7).
// 19 → 18: `browser-file-storage/storage-manager-adapter.ts`의 inspection
// 대기가 커널 race로 옮겨갔다(Q-B).
// 17 → 16: `browser-transfer/image-cdn/image-cdn-runtime.ts`의 검증 deadline과
// probe 대기가 커널 operation으로 옮겨갔다(R3-2).
// 16 → 15: `browser-files/browser-file-picker.ts`의 native input 대기와
// system picker 대기가 커널 operation으로 옮겨갔다(R3-2).
// 15 → 13: `storage/opfs/opfs-worker-client.ts`가 커널 abort primitive를 쓰고,
// `storage/indexeddb/indexeddb-governance.ts`의 binding 검증이 커널
// 트랜잭션으로 옮겨갔다(05-07, 05-12).
const HAND_ROLLED_ABORT_CEILING = 13;
const handRolledScan = spawnSync(
"git",
["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"],
+143
View File
@@ -0,0 +1,143 @@
import { readFile } from "node:fs/promises";
import path from "node:path";
import {
createFileSystemDeclarationSource,
type TopologyDeclarationSource,
} from "./generate-product-feature-index.ts";
/**
* Spec §3 / §37. Build-input regression gate for deployable-app isolation.
*
* The app being built is the one recorded in `src/.generated/product-app.ts`.
* Its allowed features are exactly those owned (via their context) by that
* app's declarations. The gate fails when
* - a generated index imports a feature or declares a context outside that
* ownership set (e.g. a regression back to "import every src/features"),
* - the production bundle's module inventory contains a module of a feature
* the app does not own.
*/
export type AppBuildInputReport = Readonly<{
appId: string;
ownedContexts: readonly string[];
ownedFeatureDirectories: readonly string[];
generatedFeatureImports: readonly string[];
generatedContexts: readonly string[];
bundle: Readonly<{ checked: boolean; featureDirectories: readonly string[] }>;
violations: readonly string[];
}>;
const GENERATED = [
"src/.generated/product-feature-index.ts",
"src/.generated/product-context-index.ts",
"src/.generated/product-app.ts",
] as const;
function unique(values: Iterable<string>): string[] {
return [...new Set(values)].sort();
}
export async function inspectAppBuildInput(
root: string,
options: Readonly<{
source?: TopologyDeclarationSource;
bundleInventory?: string | null;
}> = {},
): Promise<AppBuildInputReport> {
const source = options.source ?? (await createFileSystemDeclarationSource(root));
const [featureIndex, contextIndex, appIndex] = await Promise.all(
GENERATED.map((file) => readFile(path.join(root, file), "utf8")),
);
const appId = /id:\s*"([^"]+)"/u.exec(appIndex ?? "")?.[1];
const violations: string[] = [];
if (!appId || !source.app(appId)) {
violations.push(`generated app ${appId ?? "<missing>"} is not a declared deployable app`);
}
const ownedContexts = appId ? source.contextsOf(appId).map((context) => context.id) : [];
const ownedFeatureDirectories = unique(
ownedContexts.flatMap((contextId) => source.featuresOf(contextId).map((feature) => feature.directory)),
);
const owned = new Set(ownedFeatureDirectories);
const featureDirectoriesIn = (text: string) =>
unique([...text.matchAll(/\.\.\/features\/([^/"']+)\//gu)].map((match) => match[1] as string));
const generatedFeatureImports = unique([
...featureDirectoriesIn(featureIndex ?? ""),
...featureDirectoriesIn(contextIndex ?? ""),
]);
for (const directory of generatedFeatureImports) {
if (!owned.has(directory)) {
violations.push(`generated index imports feature "${directory}" not owned by app ${appId}`);
}
}
const generatedContexts = unique(
[...(contextIndex ?? "").matchAll(/defineBoundedContextModule\(\{\s*id:\s*"([^"]+)"/gu)].map(
(match) => match[1] as string,
),
);
const ownedContextSet = new Set(ownedContexts);
for (const contextId of generatedContexts) {
if (!ownedContextSet.has(contextId)) {
violations.push(`generated index declares context "${contextId}" not owned by app ${appId}`);
}
}
let bundle: AppBuildInputReport["bundle"] = { checked: false, featureDirectories: [] };
const inventoryPath =
options.bundleInventory === undefined
? path.join(root, "artifacts/quality/vite-module-inventory.json")
: options.bundleInventory;
if (inventoryPath) {
const raw = await readFile(inventoryPath, "utf8").catch(() => null);
if (raw !== null) {
const inventory = JSON.parse(raw) as { chunks?: { modules?: string[] }[] };
const modules = (inventory.chunks ?? []).flatMap((chunk) => chunk.modules ?? []);
const featureDirectories = unique(
modules.flatMap((module) => {
const match = /^src\/features\/([^/]+)\//u.exec(module);
return match ? [match[1] as string] : [];
}),
);
bundle = { checked: true, featureDirectories };
for (const directory of featureDirectories) {
if (!owned.has(directory)) {
violations.push(`production bundle contains feature "${directory}" not owned by app ${appId}`);
}
}
}
}
return Object.freeze({
appId: appId ?? "",
ownedContexts: unique(ownedContexts),
ownedFeatureDirectories,
generatedFeatureImports,
generatedContexts,
bundle,
violations,
});
}
async function main(): Promise<void> {
// The bundle inventory is only meaningful right after a build of this tree;
// without `--require-bundle` the gate checks the generated indexes only, so a
// stale inventory from another build can never pass or fail it.
const requireBundle = process.argv.includes("--require-bundle");
const report = await inspectAppBuildInput(process.cwd(), requireBundle ? {} : { bundleInventory: null });
if (requireBundle && !report.bundle.checked) {
process.stderr.write("app build input: no production module inventory; run the build first\n");
process.exit(1);
}
for (const violation of report.violations) process.stderr.write(`FAIL ${violation}\n`);
process.stdout.write(
`app build input: app=${report.appId} contexts=${report.ownedContexts.length} ` +
`features=${report.ownedFeatureDirectories.length} generatedImports=${report.generatedFeatureImports.length} ` +
`bundle=${report.bundle.checked ? `${report.bundle.featureDirectories.length} feature dirs` : "not checked"} ` +
`${report.violations.length === 0 ? "PASS" : "FAIL"}\n`,
);
if (report.violations.length > 0) process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+163 -59
View File
@@ -6,11 +6,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
import { createRequire } from "node:module";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
type ArchitectureRule = Readonly<{
name: string;
comment?: string;
severity?: string;
from?: PathRule;
to?: PathRule & Readonly<{ circular?: boolean }>;
@@ -53,7 +55,6 @@ type GraphFixtureResult = Readonly<{
failures: string[];
}>;
type DependencyResolution = Readonly<{ path?: string; reason: string }>;
type DependencyCruiserReport = Record<string, unknown>;
type TypeScriptOnlyPolicy = Readonly<{
checkedRoots: readonly string[];
exceptionsAllowed: false;
@@ -111,27 +112,15 @@ function runPnpm(arguments_: string[]) {
});
}
// Keep dependency-cruiser's report and checks. The second graph is authoritative
// for TypeScript 7 coverage because dependency-cruiser 18 cannot parse TS 7 yet.
const dependencyCruiser = runPnpm([
"exec",
"depcruise",
"src",
"--config",
".dependency-cruiser.json",
"--output-type",
"json",
]);
// 12-05 (D-11): this graph is the only architecture checker. dependency-cruiser
// 18 cannot parse TypeScript 7, so it cruised zero modules and still passed.
// .dependency-cruiser.json keeps its name and is read here as the rule file.
const sourceGraph = await analyzeSourceGraph(sourceRoot, "src");
const typeScriptOnlyPolicy = await inspectTypeScriptOnlyPolicy();
const graphFixtureResult = await runGraphFixtureChecks();
const dependencyReport = parseDependencyCruiserReport(dependencyCruiser.stdout);
const graphErrors = blockingViolations(sourceGraph);
const dependencyCruiserReportValid = !(
"dependencyCruiserOutput" in dependencyReport
);
dependencyReport.staticImportGraph = {
const staticImportGraph = {
analyzer: "babel-parser-node-resolver",
modules: sourceGraph.modules,
dependencies: sourceGraph.dependencies,
@@ -162,25 +151,11 @@ dependencyReport.staticImportGraph = {
await writeValidatedJsonArtifact({
path: qualityArtifact,
schema: architectureDependencyReportArtifactSchema,
value: dependencyReport,
value: { staticImportGraph },
});
let architectureFailed = false;
if (!dependencyCruiserReportValid) {
architectureFailed = true;
process.stderr.write("dependency-cruiser returned an invalid JSON report\n");
}
if (dependencyCruiser.status !== 0) {
architectureFailed = true;
process.stderr.write(
(dependencyCruiser.error?.message ?? dependencyCruiser.stderr) ||
dependencyCruiser.stdout ||
"dependency-cruiser failed\n",
);
}
for (const failure of sourceGraph.parseFailures) {
architectureFailed = true;
process.stderr.write(
@@ -197,11 +172,16 @@ for (const dependency of sourceGraph.unresolved) {
for (const violation of graphErrors) {
architectureFailed = true;
const cycle = violation.cycle
? ` (cycle group: ${violation.cycle.join(", ")})`
: "";
process.stderr.write(
`Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${cycle}\n`,
formatArchitectureViolation(
violation,
violation.cycle
? []
: sourceGraph.dependencies
.filter(({ source, target }) => source === violation.source && target === violation.target)
.map(({ specifier }) => specifier),
architectureRules.find(({ name }) => name === violation.rule)?.comment,
),
);
}
@@ -443,7 +423,7 @@ async function importSpecifiers(sourceFile: string): Promise<string[]> {
visitSyntaxNode(syntaxTree, specifiers, nonLiteralModuleLoads);
if (nonLiteralModuleLoads.size > 0) {
throw new Error(
`module loading must use string literals: ${[...nonLiteralModuleLoads].join(", ")}`,
`module loading must name one module with a string literal: ${[...nonLiteralModuleLoads].join(", ")}`,
);
}
for (const comment of syntaxTree.comments ?? []) {
@@ -503,6 +483,17 @@ function visitSyntaxNode(
if (!addStringLiteral(arguments_[0], specifiers)) {
nonLiteralModuleLoads.add("require()");
}
} else if (
nodeType === "CallExpression" &&
syntaxNodeType(node.callee) === "MemberExpression" &&
syntaxNodeType(syntaxNodeProperty(node.callee, "object")) === "MetaProperty" &&
/^glob(?:Eager)?$/u.test(
String(syntaxNodeProperty(syntaxNodeProperty(node.callee, "property"), "name")),
)
) {
// 12-06: a glob pulls in every matching module without naming one, so no
// edge rule can see it. Refuse it like a non-literal import().
nonLiteralModuleLoads.add("import.meta.glob()");
} else if (nodeType === "TSExternalModuleReference") {
addStringLiteral(node.expression, specifiers);
} else if (nodeType === "TSImportType") {
@@ -824,14 +815,23 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
"tests/fixtures/architecture/dependency-graph",
);
const allowedRoot = resolve(fixtureRoot, "allowed");
const [allowedGraph, unresolvedGraph, layerGraph, cycleGraph, barrelGraph] =
await Promise.all([
analyzeSourceGraph(allowedRoot, "src"),
analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "layer"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "cycle"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "barrel"), "src"),
]);
const [
allowedGraph,
unresolvedGraph,
layerGraph,
cycleGraph,
barrelGraph,
crossBoundaryGraph,
importBoundaryGraph,
] = await Promise.all([
analyzeSourceGraph(allowedRoot, "src"),
analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "layer"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "cycle"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "barrel"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "cross-boundary"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "import-boundaries"), "src"),
]);
const allowedFiles = new Set(await listFiles(allowedRoot));
const allowedSourceFile = resolve(
allowedRoot,
@@ -851,6 +851,100 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
),
);
const assertions = [
{
name: "cross-feature concrete imports are rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "features-do-not-import-other-features" &&
source === "src/features/alpha/read-beta.ts" &&
target === "src/features/beta/value.ts",
),
},
{
name: "cross-context concrete imports are rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "contexts-do-not-import-other-contexts" &&
source === "src/contexts/customer/read-admin.ts" &&
target === "src/contexts/admin/value.ts",
),
},
{
name: "feature root re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/features/alpha/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "context re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/contexts/customer/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "presentation import of a context is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "presentation-does-not-import-apps-or-contexts" &&
source === "src/presentation/read-context.ts" &&
target === "src/contexts/customer/telemetry.ts",
),
},
// 12-08 / 12-10: these import rules used to be regular expressions in
// check-design-system.ts and realtime-boundaries.ts beside the graph.
{
name: "design-system deep import is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source }) =>
rule === "design-system-is-reached-through-its-index" &&
source === "src/presentation/pages/deep-import.ts",
),
},
{
name: "design-system index and named facades are accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/presentation/pages/public-import.ts", "src/presentation/components/ui/button.ts"].includes(source),
),
},
{
name: "direct icon vendor import is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "icon-vendor-is-facade-only" &&
source === "src/presentation/pages/direct-icon.ts" &&
target === "lucide-react",
),
},
// F-7 (13-08): zod must be configured jitless before any schema is built.
{
name: "direct zod import outside src/contracts/zod.ts is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "zod-is-reached-through-contracts-zod" &&
source === "src/presentation/pages/direct-zod.ts" &&
target === "zod",
),
},
{
name: "zod through src/contracts/zod.ts is accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/contracts/zod.ts", "src/presentation/pages/wrapped-zod.ts"].includes(source),
),
},
{
name: "unselected realtime runtime composition is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source }) =>
rule === "unselected-realtime-runtime-is-not-composed" &&
source === "src/bootstrap/compose-realtime.ts",
),
},
{
name: "deep adapter import from outside the group is rejected",
passed: blockingViolations(barrelGraph).some(
@@ -860,6 +954,21 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
target === "src/adapters/http/client.ts",
),
},
{
name: "second-level index import from outside the group is rejected",
passed: blockingViolations(barrelGraph).some(
({ rule, source, target }) =>
rule === "adapter-groups-are-reached-through-their-barrel" &&
source === "src/bootstrap/compose-sub-barrel.ts" &&
target === "src/adapters/http/internals/index.ts",
),
},
{
name: "storage runtime sub-barrel import is accepted",
passed: !blockingViolations(barrelGraph).some(
({ source }) => source === "src/bootstrap/compose-storage-sub-barrel.ts",
),
},
{
name: "barrel import from outside the group is accepted",
passed: !blockingViolations(barrelGraph).some(
@@ -929,6 +1038,14 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
reason.includes("import()"),
),
},
{
name: "import.meta.glob module loads are rejected",
passed: unresolvedGraph.parseFailures.some(
({ source, reason }) =>
source === "src/application/glob-value.ts" &&
reason.includes("import.meta.glob"),
),
},
{
name: "non-literal CommonJS imports are rejected",
passed: unresolvedGraph.parseFailures.some(
@@ -1074,6 +1191,7 @@ function parseArchitectureConfig(value: unknown): ArchitectureConfig {
function isArchitectureRule(value: unknown): value is ArchitectureRule {
if (!isRecord(value) || typeof value.name !== "string") return false;
if (value.comment !== undefined && typeof value.comment !== "string") return false;
if (value.severity !== undefined && typeof value.severity !== "string") {
return false;
}
@@ -1099,17 +1217,3 @@ function isPathRule(value: unknown, allowCircular: boolean): value is PathRule {
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value && typeof value === "object" && !Array.isArray(value));
}
function parseDependencyCruiserReport(
output: string,
): DependencyCruiserReport {
try {
const report: unknown = JSON.parse(output);
if (!report || typeof report !== "object" || Array.isArray(report)) {
throw new Error("dependency-cruiser report must be a JSON object");
}
return report as DependencyCruiserReport;
} catch {
return { summary: { errors: 1 }, dependencyCruiserOutput: output };
}
}
+1 -1
View File
@@ -1,6 +1,6 @@
import { readFile } from "node:fs/promises";
import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.ts";
import { evaluateBundleBudget } from "./lib/performance-budgets.ts";
import {
bundleOutputInventoryArtifactSchema,
bundlePerformanceArtifactSchema,
+61 -11
View File
@@ -1,16 +1,22 @@
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import {
evaluatePromotionReadiness,
PROMOTION_FORMULA,
type GateResult,
} from "../src/application/policies/promotion-readiness.ts";
} from "./lib/promotion-readiness.ts";
import {
CANONICAL_GATE_IDS,
loadCiGateContract,
indexCiGateContract,
} from "./contracts/ci-gates.ts";
import { generateCiWorkflow, renderCiWorkflow } from "./generate-ci-workflow.ts";
import {
generateCiWorkflow,
renderCiWorkflow,
workflowGateExecutionFailures,
} from "./generate-ci-workflow.ts";
import {
ciContractReportSchema,
} from "./lib/ci-contract-report.ts";
@@ -18,12 +24,21 @@ 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 removalFixtureMode = process.argv.includes("--reduced-removal-fixture");
const contract = await loadCiGateContract(process.cwd(), {
mode: removalFixtureMode ? "removal-fixture" : "canonical",
});
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
const [packageDocument, nodeVersion] = await Promise.all([
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
@@ -63,6 +78,43 @@ 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),
(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);
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)}`);
}
const immutable = index.gates.get("FE-GATE-015");
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
if (JSON.stringify(immutableCommands) !== JSON.stringify(["build:release-candidate", "verify:local-evidence"])) {
@@ -76,10 +128,7 @@ if (!architecture?.evidenceArtifactIds.some((id) => index.artifacts.get(id)?.pat
failures.push("FE-GATE-010 must publish the typed CI contract report");
}
const expectedGateIds = Array.from(
{ length: 27 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const expectedGateIds = CANONICAL_GATE_IDS;
const passingResults: Record<string, GateResult> = Object.fromEntries(
expectedGateIds.map((gateId) => [gateId, "PASS"]),
);
@@ -116,6 +165,7 @@ try {
} catch (error) {
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
}
failures.push(...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8")));
const report = ciContractReportSchema.parse({
schemaVersion: 2,
nodeVersion,
@@ -139,4 +189,4 @@ if (failures.length > 0) {
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write("CI contract: 27 gates, strict v2 graph and generated workflow model PASS\n");
process.stdout.write(`CI contract: ${CANONICAL_GATE_IDS.length} gates, strict v2 graph and generated workflow model PASS\n`);
+55 -26
View File
@@ -1,53 +1,72 @@
import { mkdir, readFile } from "node:fs/promises";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts";
import { z } from "zod";
import {
classifyObjectSchemaChange,
type ObjectSchemaShape,
type SchemaChangeClassification,
} from "../src/contracts/compatibility.ts";
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type CompatibilitySchema = Readonly<{
required?: readonly string[];
properties?: Readonly<Record<string, unknown>>;
}>;
type CompatibilityFixture = Readonly<{
before: CompatibilitySchema;
after: CompatibilitySchema;
}>;
// FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema
// the previous release's reader accepts; the current schema is exactly what
// the build writes to dist/runtime-config.schema.json.
const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json";
type CompatibilityFixtures = Readonly<{
families: Readonly<
Record<string, Readonly<Record<"additive" | "breaking", CompatibilityFixture>>>
>;
cases: readonly Readonly<{
id: string;
expected: SchemaChangeClassification;
before: ObjectSchemaShape;
after: ObjectSchemaShape;
}>[];
}>;
const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema);
if (process.argv.includes("--update-baseline")) {
await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
process.stdout.write(`Updated ${BASELINE_PATH}\n`);
process.exit(0);
}
const fixtures = JSON.parse(
await readFile("config/compatibility/fixtures.json", "utf8"),
) as CompatibilityFixtures;
const results = [];
const results = fixtures.cases.map(({ id, expected, before, after }) => {
const actual = classifyObjectSchemaChange(before, after);
return { id, expected, actual, passed: actual === expected };
});
for (const [family, cases] of Object.entries(fixtures.families)) {
for (const expected of ["additive", "breaking"] as const) {
const fixture = cases[expected];
const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
results.push({ family, expected, actual, passed: actual === expected });
}
}
const baselineClassification = classifyObjectSchemaChange(
JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape,
current as ObjectSchemaShape,
);
const baseline = {
path: BASELINE_PATH,
classification: baselineClassification,
passed: baselineClassification !== "breaking",
};
await mkdir("artifacts/release", { recursive: true });
await writeValidatedJsonArtifact({
path: "artifacts/release/compatibility.json",
schema: compatibilityFixturesArtifactSchema,
value: {
schemaVersion: 1,
schemaVersion: 2,
generatedAt: new Date().toISOString(),
rules: [
"additive changes preserve required fields",
"breaking changes require version bump and migration, discard, fallback, or rollback",
"a change is additive only when it adds a property under a reader that tolerates unknown keys",
"type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)",
"adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first",
"config and API major versions must match",
"incompatible persisted cache is discarded by default",
"rollback uses a coherent compatibility tuple",
],
results,
baseline,
},
});
@@ -55,4 +74,14 @@ if (results.some((result) => !result.passed)) {
process.stderr.write("Compatibility fixture classification failed.\n");
process.exit(1);
}
process.stdout.write("Compatibility fixtures: PASS\n");
if (!baseline.passed) {
process.stderr.write(
`Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` +
"Follow docs/contracts/compatibility.md (deploy readers first), then run\n" +
"`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n",
);
process.exit(1);
}
process.stdout.write(
`Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`,
);
+11 -13
View File
@@ -29,8 +29,14 @@ for (const [layer, file, tokens] of tokenLayers) {
}
}
// theme.css only imports the files under styles/theme/, so check them all.
const styleFiles = (
await readdir("src/presentation/styles", { recursive: true })
)
.filter((file) => file.endsWith(".css"))
.map((file) => path.join("src/presentation/styles", file));
const cssSources = await Promise.all(
[...Object.values(tokenFiles), "src/presentation/styles/theme.css"].map(
[...Object.values(tokenFiles), ...styleFiles].map(
async (file) => ({ file, source: await readFile(file, "utf8") }),
),
);
@@ -97,22 +103,14 @@ const sources = fixtureMode
: await listSourceFiles("src");
for (const file of sources) {
const source = await readFile(file, "utf8");
const vendorFacade =
file === "src/presentation/design-system/icons/vendors/lucide.tsx";
if (!vendorFacade && /from\s+["']lucide-react["']/.test(source)) {
failures.push(`direct icon vendor import in ${file}`);
}
// Icon vendor and design-system deep imports are graph rules in
// .dependency-cruiser.json (check:architecture), which also sees relative,
// dynamic and type imports (12-08, 12-10).
if (
/from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source)
) {
failures.push(`direct headless vendor import in ${file}`);
}
if (
!file.includes("src/presentation/design-system/") &&
/presentation\/design-system\/(?!index(?:\.tsx?)?["'])/.test(source)
) {
failures.push(`design-system deep import in ${file}`);
}
if (
!rawPaletteSourceFiles.has(file) &&
containsRawPaletteValue(source)
@@ -151,5 +149,5 @@ if (failures.length > 0) {
process.exit(1);
}
process.stdout.write(
`Design system contract: ${report.checkedTokenCount} tokens and vendor boundaries PASS\n`,
`Design system contract: ${report.checkedTokenCount} tokens and headless vendor boundary PASS\n`,
);
+25 -3
View File
@@ -4,8 +4,15 @@ import { diagnosticsReportArtifactSchema } from "./contracts/release-artifacts.t
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
import path from "node:path";
import { DIAGNOSTIC_EVENT_REGISTRY } from "../src/contracts/diagnostics.ts";
import { TELEMETRY_REGISTRY } from "../src/contracts/telemetry.ts";
import {
DIAGNOSTIC_CONTEXT_ALLOWLIST,
DIAGNOSTIC_CONTEXT_CARDINALITY,
DIAGNOSTIC_EVENT_REGISTRY,
} from "../src/contracts/diagnostics.ts";
import {
TELEMETRY_ATTRIBUTE_ALLOWLIST,
TELEMETRY_REGISTRY,
} from "../src/contracts/telemetry.ts";
const fixtureMode = process.argv.includes("--fixture");
const failures: string[] = [];
@@ -26,6 +33,7 @@ const telemetryProducerFiles: Readonly<Record<string, string>> = {
"api.request.failed": "src/adapters/http/client.ts",
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"service-worker.start.failed": "src/bootstrap/optional-runtime-host.ts",
"telemetry.delivery.dropped":
"src/adapters/telemetry/best-effort-telemetry.ts",
};
@@ -40,7 +48,21 @@ const diagnosticProducerFiles: Readonly<Record<string, string>> = {
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts",
};
"feature.override.unknown": "src/bootstrap/runtime-adapters.ts",
};
for (const key of DIAGNOSTIC_CONTEXT_ALLOWLIST) {
if (!DIAGNOSTIC_CONTEXT_CARDINALITY[key]) {
failures.push(`diagnostic context key has no cardinality class: ${key}`);
}
}
for (const key of TELEMETRY_ATTRIBUTE_ALLOWLIST) {
// Defensive at runtime: the types already exclude it, the gate still checks.
const cardinality: string | undefined = DIAGNOSTIC_CONTEXT_CARDINALITY[key];
if (cardinality === "request") {
failures.push(`request-cardinality telemetry attribute is forbidden: ${key}`);
}
}
if (!fixtureMode) {
for (const eventName of Object.keys(TELEMETRY_REGISTRY)) {
+53 -10
View File
@@ -53,26 +53,57 @@ if (!fixtureMode) {
}
}
// 08-04. Screen code under these directories must take its words from the
// catalog. `src/presentation/examples` is the component gallery and stays out
// of scope on purpose. Fixture mode runs the same discovery on a fixture tree.
const sourceRoot = fixtureMode ? "tests/fixtures/i18n/forbidden" : ".";
const commonDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
"src/presentation/design-system",
"src/presentation/forms",
"src/presentation/layouts",
"src/presentation/pages",
"src/presentation/routes",
"src/presentation/templates",
];
const commonSources = fixtureMode
? await listSourceFiles("tests/fixtures/i18n/forbidden")
: (
await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
).flat();
async function featurePresentationDirectories(root: string): Promise<string[]> {
const features = path.join(root, "src/features");
const entries = await readdir(features, { withFileTypes: true }).catch(
() => [],
);
return entries
.filter((entry) => entry.isDirectory())
.map((entry) => path.join("src/features", entry.name, "presentation"));
}
async function existingSourceFiles(directory: string): Promise<string[]> {
return listSourceFiles(directory).catch((error: NodeJS.ErrnoException) => {
if (error.code === "ENOENT") return [];
throw error;
});
}
// Template sync (af3d8e6). TechLog's presentation is held to its own
// behavioral-literal policy (scripts/lib/tech-log-i18n-policy.ts), which reads
// string literals and JSX text rather than whole files, so the whole-file
// Korean rule above applies to every other feature and not to it.
const techLogPresentation = path.join("src/features", "tech-log", "presentation");
const sourceDirectories = [
...commonDirectories,
...(await featurePresentationDirectories(sourceRoot)).filter(
(directory) => directory !== techLogPresentation,
),
].map((directory) => path.join(sourceRoot, directory));
const sources = (
await Promise.all(sourceDirectories.map(existingSourceFiles))
).flat();
const techLogSources = fixtureMode
? []
: await listSourceFiles("src/features/tech-log/presentation");
const sources = [...commonSources, ...techLogSources];
: await existingSourceFiles(techLogPresentation);
for (const file of commonSources) {
for (const file of sources) {
const source = await readFile(file, "utf8");
if (koreanLiteral.test(source)) {
failures.push(`hardcoded common user-facing locale literal in ${file}`);
@@ -85,7 +116,6 @@ for (const file of commonSources) {
}
}
for (const file of techLogSources) {
const source = await readFile(file, "utf8");
for (const violation of findTechLogBehavioralLiteralViolations(source)) {
@@ -106,7 +136,7 @@ const report = i18nReportArtifactSchema.parse({
mode: fixtureMode ? "negative-fixture" : "source",
localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
messageKeyCount: Object.keys(KO_MESSAGES).length,
checkedFiles: sources.length,
checkedFiles: sources.length + techLogSources.length,
failures,
passed: failures.length === 0,
});
@@ -119,6 +149,19 @@ await writeValidatedJsonArtifact({
value: report,
});
// Every fixture file must be rejected on its own; one rejected file must not
// hide a directory the discovery above stopped reaching.
const fixtureFiles = fixtureMode ? await listSourceFiles(sourceRoot) : [];
const unrejectedFixtures = fixtureFiles.filter(
(file) => !failures.some((failure) => failure.endsWith(file)),
);
if (fixtureMode && (fixtureFiles.length === 0 || unrejectedFixtures.length > 0)) {
process.stderr.write(
`I18n fixture was not rejected:\n${unrejectedFixtures.join("\n") || "(no fixture files found)"}\n`,
);
process.exit(2);
}
if (failures.length > 0) {
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
@@ -13,7 +13,6 @@ const forbiddenOutput = `${forbidden.stdout}${forbidden.stderr}`;
const expectedRules = [
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
"PRESENTATION_INTERVAL_OWNER",
"UNSELECTED_REALTIME_RUNTIME_COMPOSED",
] as const;
if (
+26 -1
View File
@@ -330,6 +330,27 @@ function projectSnapshotRows(
});
}
/**
* 09-07. `src/features/*\/adapters` names that directory in every feature, so
* adding a feature does not mean adding it to this governance file.
*/
async function expandDirectoryPattern(pattern: string): Promise<string[]> {
const star = pattern.split("/").indexOf("*");
if (star === -1) return [pattern];
const segments = pattern.split("/");
const parent = segments.slice(0, star).join("/");
const rest = segments.slice(star + 1).join("/");
const entries = await readdir(parent, { withFileTypes: true }).catch(() => []);
const expanded = await Promise.all(
entries
.filter((entry) => entry.isDirectory())
.map((entry) =>
expandDirectoryPattern(path.join(parent, entry.name, rest)),
),
);
return expanded.flat();
}
async function filesBelow(directory: string): Promise<string[]> {
try {
const entries = await readdir(directory, { withFileTypes: true });
@@ -548,7 +569,11 @@ for (const specification of governance.registries) {
if (specification.consumerIdentityField) {
const consumerFiles = (
await Promise.all(
(specification.consumerDirectories ?? []).map(filesBelow),
(await Promise.all(
(specification.consumerDirectories ?? []).map(expandDirectoryPattern),
))
.flat()
.map(filesBelow),
)
).flat();
const sourcePath = sourcesByRegistry.get(specification.registryId);
+26
View File
@@ -7,7 +7,9 @@ import {
isDeploymentTarget,
type AdmissionInput,
} from "../src/contracts/deployment-admission.ts";
import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts";
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
/**
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
@@ -40,6 +42,17 @@ async function main(): Promise<void> {
process.exitCode = 1;
return;
}
// 13-01: the build profile and the admission target are separate repository
// variables; a profile left on staging must not ship to production.
const profile = process.env["APP_PROFILE"];
if (profile !== undefined && profile !== declared) {
process.stderr.write(
`release admission refused: the artifact was built with APP_PROFILE=${profile} ` +
`but RELEASE_TARGET=${declared}. Set both to the same environment.\n`,
);
process.exitCode = 1;
return;
}
let document: unknown;
try {
@@ -68,6 +81,18 @@ async function main(): Promise<void> {
}
const violations = findAdmissionViolations(declared, config);
// 09-09. Inert by design (a shared document may name another build's
// features), so this warns instead of refusing.
const warnings = unknownProductFeatureOverrides(
COMPILED_PRODUCT_FEATURE_IDS,
"FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined,
).map((featureId) => ({
field: `FEATURE_OVERRIDES.${featureId}`,
reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`,
}));
for (const warning of warnings) {
process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`);
}
await mkdir("artifacts/release", { recursive: true });
await writeFile(
RECORD_PATH,
@@ -82,6 +107,7 @@ async function main(): Promise<void> {
releaseId: config.RELEASE_ID ?? null,
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
violations,
warnings,
},
null,
2,
+1 -1
View File
@@ -1,4 +1,4 @@
import { access, readFile } from "node:fs/promises";
import { readFile } from "node:fs/promises";
/**
* GOV-03. Joins the machine-readable remediation dispositions against the prose
+185
View File
@@ -0,0 +1,185 @@
import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import { parseAsync } from "@babel/core";
/**
* Spec §12 / §41. Source gate against frontend N+1 request fan-out.
*
* In feature code and application use cases, a physical-request dispatch must
* not run once per element of a collection. The gate rejects a dispatch call
* - inside a loop statement (for / for-of / for-in / while / do-while), or
* - inside a callback passed to an array iteration method
* (map, flatMap, forEach, filter, reduce, some, every, find, findIndex),
* where a dispatch is `fetch(...)`, or any method call on a receiver named like
* a transport (`http`, `executor`, `client`, `gateway`, `api`, `transport`).
*
* The HTTP runtime itself (src/adapters/http) owns its bounded retry loop and is
* out of scope. A reviewed exception is written on the call's line as
* `// fanout-reviewed: <reason>`.
*/
export const REQUEST_FANOUT_ROOTS = Object.freeze(["src/features", "src/application"]);
const TRANSPORT_RECEIVER = /^(?:http|executor|client|gateway|api|transport)$|(?:Http|Executor|Client|Gateway|Api|Transport)$/u;
const ITERATION_METHODS = new Set([
"map",
"flatMap",
"forEach",
"filter",
"reduce",
"some",
"every",
"find",
"findIndex",
]);
const LOOP_TYPES = new Set([
"ForStatement",
"ForOfStatement",
"ForInStatement",
"WhileStatement",
"DoWhileStatement",
]);
const FUNCTION_TYPES = new Set(["ArrowFunctionExpression", "FunctionExpression"]);
type Node = { type: string; loc?: { start: { line: number } } } & Record<string, unknown>;
export type FanoutViolation = Readonly<{ file: string; line: number; call: string; context: string }>;
function receiverName(node: Node | undefined): string | null {
if (!node) return null;
if (node.type === "Identifier") return node["name"] as string;
if (node.type === "MemberExpression" && (node["property"] as Node).type === "Identifier") {
return ((node["property"] as Node)["name"] as string) ?? null;
}
if (node.type === "ThisExpression") return "this";
return null;
}
function dispatchDescription(call: Node): string | null {
const callee = call["callee"] as Node;
if (callee.type === "Identifier" && callee["name"] === "fetch") return "fetch()";
if (callee.type === "MemberExpression") {
const receiver = receiverName(callee["object"] as Node);
const property = callee["property"] as Node;
const method = property.type === "Identifier" ? (property["name"] as string) : "?";
if (receiver && TRANSPORT_RECEIVER.test(receiver)) return `${receiver}.${method}()`;
}
return null;
}
function iterationCallback(parent: Node | undefined, child: Node): string | null {
if (!parent || parent.type !== "CallExpression" || !FUNCTION_TYPES.has(child.type)) return null;
if (!(parent["arguments"] as Node[]).includes(child)) return null;
const callee = parent["callee"] as Node;
if (callee.type !== "MemberExpression") return null;
const property = callee["property"] as Node;
const method = property.type === "Identifier" ? (property["name"] as string) : "";
return ITERATION_METHODS.has(method) ? `.${method}() callback` : null;
}
export async function findRequestFanout(
file: string,
sourceText: string,
): Promise<readonly FanoutViolation[]> {
const plugins: ("jsx" | ["typescript", { dts: boolean }])[] = [["typescript", { dts: false }]];
if (file.endsWith(".tsx")) plugins.push("jsx");
const tree = (await parseAsync(sourceText, {
filename: file,
babelrc: false,
configFile: false,
sourceType: "module",
parserOpts: { plugins },
})) as unknown as Node | null;
if (!tree) throw new Error(`cannot parse ${file}`);
const lines = sourceText.split("\n");
const violations: FanoutViolation[] = [];
const visit = (node: Node, parent: Node | undefined, repeating: string | null): void => {
let context = repeating;
if (LOOP_TYPES.has(node.type)) context = node.type.replace("Statement", " loop");
const callback = iterationCallback(parent, node);
if (callback) context = callback;
// A nested function declared (not iterated) resets the repetition context.
if (!callback && FUNCTION_TYPES.has(node.type)) context = null;
if (node.type === "FunctionDeclaration") context = null;
if (node.type === "CallExpression" && context) {
const call = dispatchDescription(node);
const line = node.loc?.start.line ?? 0;
if (call && !/fanout-reviewed:\s*\S/u.test(lines[line - 1] ?? "")) {
violations.push({ file, line, call, context });
}
}
for (const [key, value] of Object.entries(node)) {
if (key === "loc" || key === "start" || key === "end" || key === "extra") continue;
const children = Array.isArray(value) ? value : [value];
for (const child of children) {
if (child && typeof child === "object" && typeof (child as Node).type === "string") {
visit(child as Node, node, context);
}
}
}
};
visit(tree, undefined, null);
return violations;
}
async function sourceFiles(directory: string): Promise<string[]> {
const found: string[] = [];
let entries;
try {
entries = await readdir(directory, { withFileTypes: true });
} catch {
return found;
}
for (const entry of entries) {
const target = path.join(directory, entry.name);
if (entry.isDirectory()) found.push(...(await sourceFiles(target)));
else if (/\.tsx?$/u.test(entry.name) && !/\.d\.ts$/u.test(entry.name)) found.push(target);
}
return found;
}
export async function scanRequestFanout(
root: string,
roots: readonly string[] = REQUEST_FANOUT_ROOTS,
): Promise<Readonly<{ files: number; violations: readonly FanoutViolation[] }>> {
const files = (await Promise.all(roots.map((entry) => sourceFiles(path.join(root, entry))))).flat();
const violations: FanoutViolation[] = [];
for (const file of files) {
violations.push(
...(await findRequestFanout(path.relative(root, file), await readFile(file, "utf8"))),
);
}
return { files: files.length, violations };
}
async function main(): Promise<void> {
const fixture = process.argv.includes("--fixture");
const root = process.cwd();
if (fixture) {
// The forbidden fixture must be rejected; the allowed fixture must pass.
const forbidden = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/forbidden"]);
const allowed = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/allowed"]);
const ok = forbidden.violations.length >= forbidden.files && forbidden.files > 0 && allowed.violations.length === 0;
process.stdout.write(
`request fan-out fixtures: forbidden ${forbidden.violations.length} rejected in ${forbidden.files} files, allowed ${allowed.violations.length} violations ${ok ? "PASS" : "FAIL"}\n`,
);
if (!ok) process.exitCode = 1;
return;
}
const result = await scanRequestFanout(root);
for (const violation of result.violations) {
process.stderr.write(
`FAIL ${violation.file}:${violation.line} ${violation.call} inside ${violation.context}\n`,
);
}
process.stdout.write(
`request fan-out: ${result.files} files scanned, ${result.violations.length} per-row dispatches ${result.violations.length === 0 ? "PASS" : "FAIL"}\n`,
);
if (result.violations.length > 0) process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
@@ -41,7 +41,10 @@ import {
releaseCandidateManifestSchema,
} from "./lib/release-candidate.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
import { linkFixtureNodeModules } from "./lib/fixture-node-modules.ts";
import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "./lib/fixture-node-modules.ts";
const repositoryRoot = process.cwd();
const fixtureRoot = await mkdtemp(path.join(tmpdir(), "provider-exact-five-fixture-"));
@@ -74,6 +77,7 @@ try {
maxBuffer: 32 * 1024 * 1024,
env: {
...process.env,
...FIXTURE_PNPM_ENVIRONMENT,
CI: "true",
VITE_BUILD_ID: "provider-exact-five-fixture",
VITE_COMMIT_SHA: revision,
@@ -249,6 +253,31 @@ try {
},
nowEpochMs: () => now,
} as const;
// 13-04: the same bundle three hours later. Current freshness refuses the
// expired provider evidence; archived freshness accepts it at the recorded
// promotion time, and still refuses a tampered archive.
const threeHoursLater = now + 3 * 60 * 60 * 1_000;
const archivedAfterWindow = await captureRejection(async () => {
await verifyExactPromotionBundle(exactFiles, {
...bundleTrust,
nowEpochMs: () => threeHoursLater,
freshness: "archived",
});
});
const currentAfterWindow = await captureRejection(async () => {
await verifyExactPromotionBundle(exactFiles, {
...bundleTrust,
nowEpochMs: () => threeHoursLater,
});
});
const tamperedArchive = Buffer.from(exactFiles["release-candidate.tar.gz"]);
tamperedArchive[tamperedArchive.length - 1] ^= 0xff;
const archivedTampered = await captureRejection(async () => {
await verifyExactPromotionBundle(
{ ...exactFiles, "release-candidate.tar.gz": tamperedArchive },
{ ...bundleTrust, nowEpochMs: () => threeHoursLater, freshness: "archived" },
);
});
const absentFiles = { ...exactFiles } as Partial<typeof exactFiles>;
delete absentFiles["provider-verification.json"];
const absent = await captureRejection(async () => {
@@ -282,7 +311,8 @@ try {
await captureCiCandidateArchive({ archivePath, expectedSha256: "0".repeat(64) });
});
const passed =
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected;
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected &&
!archivedAfterWindow.rejected && currentAfterWindow.rejected && archivedTampered.rejected;
await cleanupFinalizedPromotion({
runnerTempRoot,
stagingRoot: finalized.stagingRoot,
@@ -314,12 +344,24 @@ try {
status: invalidTar.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [invalidTar.failure],
},
archivedAfterWindow: {
status: archivedAfterWindow.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: archivedAfterWindow.rejected ? [archivedAfterWindow.failure] : [],
},
currentAfterWindow: {
status: currentAfterWindow.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [currentAfterWindow.failure],
},
archivedTampered: {
status: archivedTampered.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [archivedTampered.failure],
},
},
externalTreeCanary: {
status: validImmutable ? "PASS" : "FAIL_UNVERIFIED",
failures: validImmutable ? [] : ["external tree canary influenced captured archive"],
},
passingFixtureCount: validImmutable ? 1 : 0,
passingFixtureCount: (validImmutable ? 1 : 0) + (archivedAfterWindow.rejected ? 0 : 1),
status: passed ? "PASS" : "FAIL",
},
});
+24 -3
View File
@@ -281,17 +281,27 @@ if (!scenarioOnly) {
const sourceFiles = (await filesBelow(sourceRoot)).filter(
(file) => fixtureMode || !file.split(path.sep).includes("fixtures"),
);
const today = new Date().toISOString().slice(0, 10);
for (const file of sourceFiles) {
if (!/\.(?:ts|tsx|fixture|txt)$/.test(file)) continue;
const source = await readFile(file, "utf8");
facts.scannedFiles += 1;
if (/\b(?:test|it|describe)(?:\.describe)?\.only\s*\(/.test(source)) {
failures.push(`${file}: focused test (.only) runs alone and hides the rest of the suite`);
}
const skipPattern = /\b(?:test|it|describe)(?:\.describe)?\.(?:skip|fixme)\s*\(/g;
if (skipPattern.test(source)) {
const quarantine =
/quarantine\(owner=[^)]+,\s*defect=[^)]+,\s*expires=\d{4}-\d{2}-\d{2}\)/;
if (!quarantine.test(source)) {
const quarantines = [
...source.matchAll(
/quarantine\(owner=[^)]+,\s*defect=[^)]+,\s*expires=(\d{4}-\d{2}-\d{2})\)/g,
),
];
if (quarantines.length === 0) {
failures.push(`${file}: skip/fixme lacks owned expiring quarantine`);
}
for (const [, expires = ""] of quarantines) {
if (expires < today) failures.push(`${file}: quarantine expired on ${expires}`);
}
}
const wholeUiMask =
/\bmask\s*:\s*\[[\s\S]{0,240}(?:locator|getByRole)\s*\(\s*["'](?:html|body|main|application|document)["']/i;
@@ -370,6 +380,17 @@ if (!fixtureMode && !scenarioOnly) {
failures.push(`playwright.config.ts missing release evidence token ${token}`);
}
}
// playwright.dev.config.ts spreads playwright.config.ts.
for (const config of [
"playwright.config.ts",
"playwright.visual.config.ts",
"playwright.storybook.config.ts",
"playwright.capabilities.config.ts",
]) {
if (!(await readFile(config, "utf8")).includes("forbidOnly: true")) {
failures.push(`${config}: missing forbidOnly: true, so a committed test.only passes the gate`);
}
}
const e2eFiles = (await filesBelow("tests/e2e")).filter((file) =>
/\.spec\.ts$/.test(file),
+1 -1
View File
@@ -3,7 +3,7 @@ import { mkdir, readFile } from "node:fs/promises";
import {
evaluateFieldBudget,
percentile75,
} from "../src/application/policies/performance-budgets.ts";
} from "./lib/performance-budgets.ts";
import { fieldWebVitalsArtifactSchema } from "./contracts/release-artifacts.ts";
import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
+148 -160
View File
@@ -4,8 +4,8 @@ import path from "node:path";
import { z } from "zod";
import { PROMOTION_FORMULA } from "../../src/application/policies/promotion-readiness.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "../lib/manual-a11y-evidence.ts";
import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts";
import {
RELEASE_CANDIDATE_EVIDENCE_PATHS,
RELEASE_CANDIDATE_MANIFEST_PATH,
@@ -439,56 +439,42 @@ export type CiGateContractIndex = Readonly<{
jobs: ReadonlyMap<string, CiWorkflowJob>;
retentionClasses: ReadonlyMap<string, CiGateContract["retention"]["classes"][number]>;
}>;
export type LoadCiGateContractOptions = Readonly<{
mode?: "canonical" | "removal-fixture";
}>;
const CANONICAL_GATE_SHAPE_SHA256 =
// 환경 구성(SETUP) 문서 종류: FE-GATE-009 가 TECH_LOG_SETUP 수동 접근성 증거를 얻어 다시
// 계산했다. 같은 방법이다 — 이전 상수 e4e61b06… 을 이전 gates.json 에서 먼저 재현해
// 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
// 개념(CONCEPT) 문서 종류: FE-GATE-009 가 TECH_LOG_CONCEPT 수동 접근성 증거를 얻어 다시 계산했다.
// 같은 방법으로 — 옛 gates.json 에서 이전 상수 fb138e7c… 를 먼저 재현해 계산이 맞는지
// 확인한 뒤 새 파일을 해싱했다.
// Template merge. Both sides carried a digest of their own gate set; neither
// describes the merged one. Recomputed from the merged config/ci/gates.json.
// Task 11: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_ASSETS manual accessibility evidence artifact.
// Final fix wave item 1: recomputed again after FE-GATE-010 gained
// `check-tech-log-contract`. Recomputed with `canonicalGateShapeSha256`
// below, verified by first reproducing the previous constant from the
// previous `config/ci/gates.json` before hashing the new one.
// Alignment follow-up item 2: recomputed again after FE-GATE-007 gained
// `test-tech-log` and its junit evidence, by the same method — the previous
// constant f3cc9075… was reproduced from the previous gates.json first, so
// the transcription that produced this value is known to be the real one.
// Dev release manifest drift fix, item 2: recomputed again after FE-GATE-010
// gained `check-dev-release-manifest`. Same method — 98d19911… was first
// reproduced from the previous gates.json before this value was hashed.
// Taxonomy route: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_TAXONOMY manual accessibility evidence artifact. The gate
// lists one evidence artifact per installed route and refuses a set that does
// not match the route scope exactly, so adding a route necessarily moves this
// digest — that is the point of pinning it.
// Release authoring: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_RELEASES evidence artifact, by the same method — 8c73d447…
// was first reproduced from the previous gates.json, so the computation that
// produced this value is known to be the one the constant was pinned under.
// 프로젝트 편집 화면: FE-GATE-009 가 TECH_LOG_STUDIO_PROJECT_EDIT 증거 아티팩트를
// 얻어 다시 계산했다. 같은 방법이다 — 187dbd96… 을 이전 gates.json 에서 먼저 재현해,
// 이 값을 만든 계산이 상수가 고정될 때 쓰인 그 계산임을 확인했다.
// 릴리즈 편집 화면: 같은 방법으로 다시 계산했다. f9e7e521… 을 이전 gates.json 에서 먼저
// 재현했다.
// 주제 화면 셋(`/topics`, `/topics/:slug/:variant`, `/studio/topics/:id`): FE-GATE-009 가 각
// 라우트의 수동 접근성 증거를 얻어 다시 계산했다. 같은 방법이다 — 87a22f68… 을 이전
// gates.json 에서 먼저 재현해 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
// Template sync (ebea300). Both sides again carried a digest of their own
// gate set — 8a1a5479… here, 43dc4ed1… upstream — and neither describes the
// merged config/ci/gates.json. Recomputed from the merged file by the same
// method: 8a1a5479… was first reproduced from the pre-merge gates.json, so
// the computation that produced this value is the one the constant is
// pinned under.
"629e5898f6a38d5056fc6a4bee834c47f363669ce9925a2c0dabeddd64d11879";
/**
* D-14. FE-GATE-016 (rollback-drill) ran the same FE-RB-005 drill as
* FE-GATE-025 and counted it twice toward production readiness. Its id stays
* retired so no later gate reuses it with a different meaning.
*/
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")}`)
.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(
@@ -513,57 +499,52 @@ function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
}
function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[] {
const failures: string[] = [];
const commandReferenceCount = contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
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 (contract.gates.length !== 27) {
failures.push(`gate authority baseline must contain exactly 27 gates; received ${contract.gates.length}`);
}
// Final fix wave, item 1: FE-GATE-010 gained `check-tech-log-contract`, the
// drift gate that pins the vendored canonical Studio contract to its digest.
// Until it was referenced by a gate it ran only when typed by hand.
// Alignment follow-up, item 2: FE-GATE-007 gained `test-tech-log`. The suite
// already ran inside `test:coverage`'s combined vitest invocation, so a
// TechLog failure was reported as a coverage-gate failure with no junit of
// its own to name it.
// Dev release manifest drift fix, item 2: FE-GATE-010 gained
// `check-dev-release-manifest`. No gate read `public/*.json` at all, so a
// fixture that did not declare the compiled contract set broke `pnpm dev`
// outright while every static gate stayed green.
// Template sync (ebea300). The template's own baseline was 91/103; this
// product's was 85/97. Recomputed from the merged config/ci/gates.json.
if (contract.commands.length !== 94 || commandReferenceCount !== 106) {
failures.push(
`command authority baseline must contain exactly 94 definitions and 106 references; received ${contract.commands.length} definitions and ${commandReferenceCount} references`,
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")}`,
);
}
// Template merge. 126 product artifacts plus the two the template added.
// Task 11 added one more: the TECH_LOG_STUDIO_ASSETS manual a11y evidence file.
// Alignment follow-up, item 2 added the TechLog junit report.
// The taxonomy route added its own manual a11y evidence file — every installed
// route carries one, and the gate checks that the two sets match exactly.
// The project edit route did the same: it is what finally lets a project carry
// a purpose, a current objective, and a next step, so the public screens that
// read those fields stop rendering blanks.
// The release edit route followed: the editor used to open below the release
// list, so editing meant scrolling past every release to reach it.
// 개념(CONCEPT) 문서 종류가 `/concepts/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성 증거를
// 하나씩 갖는 규칙이 그대로 적용된다.
// 주제(Topic) 화면 셋이 뒤를 이었다: 목록 `/topics`, 축 상세 `/topics/:slug/:variant`,
// 그리고 Studio 의 주제 편집 `/studio/topics/:id`.
// 환경 구성(SETUP) 문서 종류가 `/setups/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성
// 증거를 하나씩 갖는 규칙이 그대로 적용된다.
// Template sync (ebea300). The template's own baseline was 109 artifacts;
// this product's was 139. Recomputed from the merged config/ci/gates.json.
if (contract.artifacts.length !== 141) {
failures.push(`artifact authority baseline must contain exactly 141 artifacts; received ${contract.artifacts.length}`);
}
if (contract.stages.length !== 5) {
failures.push(`stage authority baseline must contain exactly 5 stages; received ${contract.stages.length}`);
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" },
{ id: "release-coherence", policy: "at least until the next release is promoted" },
@@ -571,16 +552,12 @@ function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[]
{ id: "field", policy: "through the 28-day window and aggregation" },
{ id: "documentation", policy: "through documentation readiness review" },
];
if (JSON.stringify(contract.retention.classes) !== JSON.stringify(expectedRetentionClasses)) {
failures.push("retention registry must contain exactly the five canonical retention classes");
}
return failures;
return JSON.stringify(contract.retention.classes) === JSON.stringify(expectedRetentionClasses)
? []
: ["retention registry must contain exactly the five canonical retention classes"];
}
export function parseCiGateContract(
value: unknown,
options: LoadCiGateContractOptions = {},
): CiGateContract {
export function parseCiGateContract(value: unknown): CiGateContract {
const result = ciGateContractSchema.safeParse(value);
if (!result.success) {
const diagnostic = result.error.issues
@@ -588,49 +565,21 @@ export function parseCiGateContract(
.join("\n");
throw new TypeError(`CI gate contract invalid:\n${diagnostic}`);
}
if ((options.mode ?? defaultCiContractMode()) === "canonical") {
const failures = canonicalAuthorityBaselineFailures(result.data);
if (failures.length > 0) {
throw new TypeError(`CI gate contract invalid:\n${failures.map((failure) => `root: ${failure}`).join("\n")}`);
}
const failures = retentionRegistryFailures(result.data);
if (failures.length > 0) {
throw new TypeError(`CI gate contract invalid:\n${failures.map((failure) => `root: ${failure}`).join("\n")}`);
}
return result.data;
}
/**
* A removal fixture runs the whole suite against a deliberately *reduced* CI
* contract: the removed capability's gates, commands and artifacts are pruned.
* Loading that contract in canonical mode re-imposes the full exact-count
* authority on it, so the fixture failed on the very reduction it exists to
* prove. `runRemovalFixturePnpm` marks those runs, and this is where the mark
* is honoured.
*/
export function defaultCiContractMode(): "canonical" | "removal-fixture" {
return process.env.CI_CONTRACT_MODE === "removal-fixture"
? "removal-fixture"
: "canonical";
}
export function isReducedCiContractRun(): boolean {
return defaultCiContractMode() === "removal-fixture";
}
export async function loadCiGateContract(
root = process.cwd(),
options: LoadCiGateContractOptions = {},
): Promise<CiGateContract> {
const mode = options.mode ?? defaultCiContractMode();
const [rawContract, rawPackage] = await Promise.all([
readFile(path.join(root, "config/ci/gates.json"), "utf8"),
readFile(path.join(root, "package.json"), "utf8"),
]);
const contract = parseCiGateContract(JSON.parse(rawContract), { mode });
if (
mode === "canonical" &&
canonicalGateShapeSha256(contract.gates) !== CANONICAL_GATE_SHAPE_SHA256
) {
throw new TypeError("CI gate contract canonical gate semantic shape drift");
}
const contract = parseCiGateContract(JSON.parse(rawContract));
const packageDocument = z
.object({ scripts: z.record(z.string(), z.string()).default({}) })
.passthrough()
@@ -642,17 +591,17 @@ export async function loadCiGateContract(
if (missing.length > 0) {
throw new TypeError(`CI gate contract missing package scripts: ${missing.join(", ")}`);
}
const expectedCheckCi = mode === "canonical"
? "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow"
: "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts --reduced-removal-fixture && corepack pnpm check:ci-workflow";
const expectedCheckCi =
"corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow";
if (packageDocument.scripts["check:ci"] !== expectedCheckCi) {
throw new TypeError("check:ci must use the exact canonical non-recursive orchestration");
}
const canonicalCheckCiDependencies = {
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": mode === "canonical"
? "node scripts/generate-ci-workflow.ts --check"
: "node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture",
// R-0. The schema generator imports src, which loads the gitignored
// product index, so the index is rendered first.
"check:artifact-schemas":
"node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
} as const;
for (const [script, expected] of Object.entries(canonicalCheckCiDependencies)) {
if (packageDocument.scripts[script] !== expected) {
@@ -682,6 +631,7 @@ export async function loadCiGateContract(
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
);
}
await assertCiContractBaseline(root, contract);
return contract;
}
@@ -819,15 +769,17 @@ function validateContractSemantics(
}
}
// Template sync (af3d8e6). The signed manual review moved from FE-GATE-009
// to release gate FE-GATE-028 upstream (08-06); the one-artifact-per-route
// rule this product pins moved with it.
const accessibilityGate = contract.gates.find(
({ id: gateId }) => gateId === "FE-GATE-009",
({ id: gateId }) => gateId === "FE-GATE-028",
);
const manualAccessibilityArtifacts = MANUAL_A11Y_ROUTE_IDS.map((routeId) => ({
id: `artifact-artifacts-tests-a11y-manual-${routeId.replaceAll("_", "-")}-md`,
path: `artifacts/tests/a11y-manual/${routeId}.md`,
}));
const expectedAccessibilityEvidenceArtifactIds = [
"artifact-artifacts-tests-a11y-json",
...manualAccessibilityArtifacts.map(({ id: artifactId }) => artifactId),
"artifact-artifacts-tests-a11y-manual-report-json",
];
@@ -837,7 +789,7 @@ function validateContractSemantics(
JSON.stringify(expectedAccessibilityEvidenceArtifactIds)
) {
issue(
"FE-GATE-009 manual accessibility evidence must exactly match the installed route scope",
"FE-GATE-028 manual accessibility evidence must exactly match the installed route scope",
);
}
for (const expected of manualAccessibilityArtifacts) {
@@ -851,7 +803,7 @@ function validateContractSemantics(
artifact.production !== "source-controlled"
) {
issue(
`FE-GATE-009 manual accessibility artifact registration is invalid: ${expected.id}`,
`FE-GATE-028 manual accessibility artifact registration is invalid: ${expected.id}`,
);
}
}
@@ -891,12 +843,9 @@ function validateContractSemantics(
issue(`stage dependency cycle: ${cycle.join(" -> ")}`);
}
const expectedGateIds = Array.from(
{ length: 27 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const expectedGateIds = CANONICAL_GATE_IDS;
if (JSON.stringify(contract.gates.map(({ id }) => id)) !== JSON.stringify(expectedGateIds)) {
issue("gate registry must contain FE-GATE-001..027 in canonical order");
issue(`gate registry must contain FE-GATE-001..028 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],
@@ -966,12 +915,12 @@ function validateContractSemantics(
}
const expectedJobOwnership: Readonly<Record<string, readonly string[]>> = {
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-013", "FE-GATE-020"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-019", "FE-GATE-026"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-026", "FE-GATE-028"],
immutable_build: ["FE-GATE-015", "FE-GATE-027"],
vulnerability_provider: [],
provenance_provider: [],
promotion: [],
production_gate: ["FE-GATE-016", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
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"],
};
@@ -991,7 +940,7 @@ function validateContractSemantics(
vulnerability_provider: ["provider", ["immutable_build"], "always"],
provenance_provider: ["provider", ["immutable_build"], "always"],
promotion: ["promotion", ["immutable_build", "vulnerability_provider", "provenance_provider"], "needs-success"],
production_gate: ["gate-matrix", ["promotion"], "production"],
production_gate: ["gate-matrix", ["immutable_build", "promotion"], "production"],
field_gate: ["gate-single", ["production_gate"], "field"],
documentation_gate: ["gate-single", [], "documentation"],
};
@@ -1008,7 +957,7 @@ function validateContractSemantics(
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"],
production_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
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"],
};
@@ -1020,7 +969,7 @@ function validateContractSemantics(
}
const expectedEnvironmentBindings: Readonly<Record<string, readonly Readonly<{ name: string; value: string }> []>> = {
merge_gate: [],
release_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }],
release_gate: [],
immutable_build: [
// FE-GATE-027 admits the built artifact to a named environment, so both
// the profile it was built from and the destination it is claimed for are
@@ -1066,7 +1015,14 @@ function validateContractSemantics(
{ name: "VULNERABILITY_INVOCATION_NONCE", value: "${{ needs.vulnerability_provider.outputs.invocation_nonce }}" },
{ name: "PROVENANCE_INVOCATION_NONCE", value: "${{ needs.provenance_provider.outputs.invocation_nonce }}" },
],
production_gate: [],
// 13-05: FE-GATE-019 probes the promoted release after the provider has
// deployed it, so the live base URL belongs to the production stage.
// 13-03: the drills extract the promoted archive and check it against the
// digest immutable_build recorded.
production_gate: [
{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" },
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
],
field_gate: [
{ name: "FIELD_WEB_VITALS_INPUT", value: "${{ vars.FIELD_WEB_VITALS_INPUT }}" },
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
@@ -1261,6 +1217,38 @@ function validateCanonicalStepFields(
) {
issue("promotion download fields and finalizer/cleanup step identities must remain linked");
}
// 13-03: the production stage drills the promoted archive it downloads. It
// used to rebuild from source, so the drilled bytes were not the release.
const production = contract.jobs.find(({ id }) => id === "production_gate");
const promotedDownload = production?.steps.find(
(step) => step.kind === "download" && step.transferId === "promoted-release",
);
const promotedExtract = production?.steps.find(({ kind }) => kind === "extract");
if (
!production ||
promotedDownload?.kind !== "download" ||
promotedExtract?.kind !== "extract" ||
promotedExtract.archivePath !== `${promotedDownload.path}/release-candidate.tar.gz`
) {
issue("production_gate must download the promoted release and extract its release-candidate.tar.gz");
} else {
for (const gateId of production.gateIds) {
const commands = (contract.gates.find(({ id }) => id === gateId)?.commandIds ?? [])
.map((commandId) => contract.commands.find(({ id }) => id === commandId));
if (!commands.some((command) => command?.script === "drill:runbook")) continue;
if (commands.some((command) => command?.script !== "drill:runbook")) {
issue(`production drill gate must drill the promoted archive only, without rebuilding: ${gateId}`);
}
for (const command of commands) {
const args = command?.args ?? [];
const releaseRoot = args.indexOf("--release-root");
if (releaseRoot < 0 || args[releaseRoot + 1] !== promotedExtract.targetRoot) {
issue(`production drill must pass --release-root ${promotedExtract.targetRoot} (the promoted archive): ${command?.id ?? gateId}`);
}
}
}
}
}
function validateJobStepKinds(
@@ -1268,7 +1256,7 @@ function validateJobStepKinds(
issue: (message: string, path?: PropertyKey[]) => void,
): void {
const allowed: Readonly<Record<z.infer<typeof jobSchema>["kind"], ReadonlySet<string>>> = {
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]),
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "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"]),
+97 -47
View File
@@ -152,6 +152,8 @@ export const moduleInventoryArtifactSchema = z
})
.strict(),
),
// 13-12: `name@version` of every package with a module in the bundle.
packages: z.array(z.string().regex(/^(?:@[^/@]+\/)?[^/@]+@[^/@]+$/u)),
})
.strict();
@@ -688,6 +690,11 @@ export const deploymentAdmissionArtifactSchema = z
violations: z.array(
z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(),
),
// 09-09. Findings that do not refuse the artifact, e.g. an override key
// naming a feature this build does not declare.
warnings: z.array(
z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(),
),
})
.strict();
@@ -718,31 +725,67 @@ export const releaseVerificationArtifactSchema = z
})
.strict();
// 11-01 / 13-03 (D-14): each verdict is PASS or FAIL only when observed on the
// local build; anything that needs a boot, live traffic or the provider is
// UNVERIFIED, and so is a drill with provider scope.
const drillVerdict = z.enum(["PASS", "FAIL", "UNVERIFIED"]);
export type DrillVerdict = z.infer<typeof drillVerdict>;
/** FAIL beats UNVERIFIED beats PASS; provider scope alone keeps a drill UNVERIFIED. */
export function combineDrillVerdicts(
verdicts: readonly DrillVerdict[],
providerVerificationRequired: boolean,
): DrillVerdict {
if (verdicts.includes("FAIL")) return "FAIL";
if (verdicts.includes("UNVERIFIED") || providerVerificationRequired) return "UNVERIFIED";
return "PASS";
}
export const runbookRecordArtifactSchema = z
.object({
schemaVersion: z.literal(1),
schemaVersion: z.literal(2),
runbookId: z.string().regex(/^FE-RB-00[1-5]$/u),
releaseId: nonEmptyString,
drillTimestamp: timestamp,
triggerInjected: nonEmptyString,
triggerAsserted: z.boolean(),
containmentAsserted: z.boolean(),
escalationPathAsserted: z.boolean(),
triggerAsserted: drillVerdict,
containmentAsserted: drillVerdict,
escalationPathAsserted: drillVerdict,
recoveryAssertions: z.array(
z
.object({
assertion: nonEmptyString,
evidence: nonEmptyString,
passed: z.boolean(),
result: drillVerdict,
})
.strict(),
),
negativeFixtureFailedAsExpected: z.boolean(),
negativeFixtureFailedAsExpected: drillVerdict,
windowObservedBucket: nonEmptyString,
providerVerificationRequired: z.boolean(),
passed: z.boolean(),
result: drillVerdict,
})
.strict();
.strict()
.superRefine((record, context) => {
const expected = combineDrillVerdicts(
[
record.triggerAsserted,
record.containmentAsserted,
record.escalationPathAsserted,
...record.recoveryAssertions.map(({ result }) => result),
record.negativeFixtureFailedAsExpected,
],
record.providerVerificationRequired,
);
if (record.result !== expected) {
context.addIssue({
code: "custom",
path: ["result"],
message: `result must be ${expected} for these verdicts`,
});
}
});
const failureList = z.array(nonEmptyString).max(4_096);
const sourceOrFixtureMode = z.enum(["source", "negative-fixture"]);
@@ -943,33 +986,11 @@ const staticImportGraphSchema = z
context.addIssue({ code: "custom", path: ["typeScriptOnlySourcePolicy", "passed"], message: "must agree with violations and summary" });
}
});
const dependencyCruiserSummarySchema = z
.object({
violations: z.array(jsonObject),
error: z.int().nonnegative(),
warn: z.int().nonnegative(),
info: z.int().nonnegative(),
ignore: z.int().nonnegative(),
totalCruised: z.int().nonnegative(),
totalDependenciesCruised: z.int().nonnegative(),
})
.catchall(z.json());
export const architectureDependencyReportArtifactSchema = z.union([
z
.object({
modules: z.array(jsonObject),
summary: dependencyCruiserSummarySchema,
staticImportGraph: staticImportGraphSchema,
})
.strict(),
z
.object({
summary: z.object({ errors: z.literal(1) }).strict(),
dependencyCruiserOutput: z.string(),
staticImportGraph: staticImportGraphSchema,
})
.strict(),
]);
// 12-05 (D-11): dependency-cruiser checked zero modules under TypeScript 7 and
// no longer runs; the report carries the import graph that enforces the rules.
export const architectureDependencyReportArtifactSchema = z
.object({ staticImportGraph: staticImportGraphSchema })
.strict();
export const designSystemReportArtifactSchema = z
.object({
@@ -1018,7 +1039,6 @@ export const realtimeBoundariesArtifactSchema = z
ruleId: z.enum([
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
"PRESENTATION_INTERVAL_OWNER",
"UNSELECTED_REALTIME_RUNTIME_COMPOSED",
]),
file: nonEmptyString,
line: z.int().positive(),
@@ -1284,6 +1304,10 @@ export const supplyChainProviderFixturesArtifactSchema = z
validImmutable: providerFixtureResultSchema,
wrongDigest: providerFixtureResultSchema,
invalidTar: providerFixtureResultSchema,
// 13-04: archived re-verification of the same bundle three hours on.
archivedAfterWindow: providerFixtureResultSchema,
currentAfterWindow: providerFixtureResultSchema,
archivedTampered: providerFixtureResultSchema,
})
.strict(),
externalTreeCanary: providerFixtureResultSchema,
@@ -1295,43 +1319,60 @@ export const supplyChainProviderFixturesArtifactSchema = z
const expectedPass =
artifact.actualDefaultVerifier.status === "PASS" &&
artifact.fixtures.validImmutable.status === "PASS" &&
artifact.fixtures.archivedAfterWindow.status === "PASS" &&
artifact.externalTreeCanary.status === "PASS" &&
[artifact.fixtures.absent, artifact.fixtures.wrongDigest, artifact.fixtures.invalidTar]
.every(({ status }) => status === "FAIL_UNVERIFIED");
if (artifact.passingFixtureCount !== (artifact.fixtures.validImmutable.status === "PASS" ? 1 : 0)) {
context.addIssue({ code: "custom", path: ["passingFixtureCount"], message: "must count the passing immutable fixture" });
[
artifact.fixtures.absent,
artifact.fixtures.wrongDigest,
artifact.fixtures.invalidTar,
artifact.fixtures.currentAfterWindow,
artifact.fixtures.archivedTampered,
].every(({ status }) => status === "FAIL_UNVERIFIED");
const passing = [artifact.fixtures.validImmutable, artifact.fixtures.archivedAfterWindow]
.filter(({ status }) => status === "PASS").length;
if (artifact.passingFixtureCount !== passing) {
context.addIssue({ code: "custom", path: ["passingFixtureCount"], message: "must count the passing fixtures" });
}
if ((artifact.status === "PASS") !== expectedPass) {
context.addIssue({ code: "custom", path: ["status"], message: "must agree with required fixture outcomes" });
}
});
const compatibilityClassificationSchema = z.enum(["additive", "breaking"]);
const compatibilityClassificationSchema = z.enum(["additive", "breaking", "none"]);
export const compatibilityFixturesArtifactSchema = z
.object({
schemaVersion: z.literal(1),
schemaVersion: z.literal(2),
generatedAt: timestamp,
rules: z.array(nonEmptyString).length(5),
rules: z.array(nonEmptyString).min(1),
results: z.array(
z
.object({
family: z.enum(["api", "config", "storage", "release"]),
id: nonEmptyString,
expected: compatibilityClassificationSchema,
actual: compatibilityClassificationSchema,
passed: z.boolean(),
})
.strict(),
).length(8),
).min(1),
baseline: z
.object({
path: nonEmptyString,
classification: compatibilityClassificationSchema,
passed: z.boolean(),
})
.strict(),
})
.strict()
.superRefine((artifact, context) => {
const keys = artifact.results.map(({ family, expected }) => `${family}\0${expected}`);
addUniqueStringIssues(keys, ["results"], context);
addUniqueStringIssues(artifact.results.map(({ id }) => id), ["results"], context);
artifact.results.forEach((result, index) => {
if (result.passed !== (result.actual === result.expected)) {
context.addIssue({ code: "custom", path: ["results", index, "passed"], message: "must agree with expected and actual" });
}
});
if (artifact.baseline.passed !== (artifact.baseline.classification !== "breaking")) {
context.addIssue({ code: "custom", path: ["baseline", "passed"], message: "must fail exactly when the baseline change is breaking" });
}
});
export const documentationReviewArtifactSchema = z
@@ -1364,6 +1405,8 @@ export const documentationReviewArtifactSchema = z
.strict(),
).min(1),
routeScopeDocumented: z.boolean(),
// 13-15: build and deploy variables README.md does not name.
missingRuntimeVariables: z.array(nonEmptyString),
results: z.array(
z
.object({
@@ -1402,6 +1445,7 @@ export const documentationReviewArtifactSchema = z
artifact.passed !==
(artifact.reportDigestValid &&
artifact.routeScopeDocumented &&
artifact.missingRuntimeVariables.length === 0 &&
artifact.results.every(({ passed }) => passed))
) {
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope and review results" });
@@ -1428,9 +1472,15 @@ export const hostingHeadersArtifactSchema = z
.strict(),
).min(1),
passed: z.boolean(),
// 13-05 (D-14): only a live probe can PASS; the fixture is UNVERIFIED.
status: z.enum(["PASS", "FAIL", "UNVERIFIED"]),
})
.strict()
.superRefine((artifact, context) => {
const expectedStatus = !artifact.passed ? "FAIL" : artifact.mode === "live" ? "PASS" : "UNVERIFIED";
if (artifact.status !== expectedStatus) {
context.addIssue({ code: "custom", path: ["status"], message: `must be ${expectedStatus} for this mode and result` });
}
const keys = artifact.results.map(({ surface, header }) => `${surface}\0${header}`);
addUniqueStringIssues(keys, ["results"], context);
const requiredKeys = [
+228 -206
View File
@@ -1,4 +1,5 @@
import { access, mkdir, readFile } from "node:fs/promises";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { shouldRetry } from "../src/adapters/http/retry-policy.ts";
@@ -11,25 +12,33 @@ import type { InstalledContractPackageIdentity } from "../src/contracts/external
import {
parseReleaseArtifact,
parseRuntimeConfigArtifact,
type ReleaseArtifact,
} from "../src/contracts/release-artifacts.ts";
import { projectTelemetryEvent } from "../src/contracts/telemetry.ts";
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
import { runbookRecordArtifactSchema } from "./contracts/release-artifacts.ts";
import {
combineDrillVerdicts,
runbookRecordArtifactSchema,
type DrillVerdict,
} from "./contracts/release-artifacts.ts";
import { verifyReleaseRuntimeCoherence } from "./lib/release-runtime-coherence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
// 11-01 / 13-03 (D-14). A verdict is PASS or FAIL only when the drill observed
// it on the local build. What needs a browser boot, live traffic or the hosting
// provider is UNVERIFIED, and so is every drill whose runbook needs provider
// verification: a local drill never claims the release can be recovered.
type RecoveryAssertion = Readonly<{
assertion: string;
evidence: string;
passed: boolean;
result: DrillVerdict;
}>;
type DrillResult = Readonly<{
triggerAsserted: boolean;
containmentAsserted: boolean;
triggerAsserted: DrillVerdict;
containmentAsserted: DrillVerdict;
recoveryAssertions: RecoveryAssertion[];
negativeFixtureFailedAsExpected: boolean;
negativeFixtureFailedAsExpected: DrillVerdict;
providerVerificationRequired: boolean;
}>;
@@ -51,10 +60,8 @@ type RunbookDocument = Readonly<{
export type JsonArtifactReader = (path: string) => Promise<unknown>;
export type RollbackArtifactPaths = Readonly<{
primaryRelease: string;
fallbackRelease: string;
primaryRuntime: string;
fallbackRuntime: string;
release: string;
runtime: string;
}>;
export type RollbackCoherenceOptions = Readonly<{
@@ -63,27 +70,41 @@ export type RollbackCoherenceOptions = Readonly<{
paths?: RollbackArtifactPaths;
}>;
export type DrillOptions = Readonly<{
/**
* Directory holding the release's `dist/`. Defaults to the cwd (the local
* build). 13-04: pass an extracted candidate or promoted archive to drill
* the release that is actually deployed or rolled back to.
*/
releaseRoot?: string;
contractPackages?: readonly InstalledContractPackageIdentity[];
}>;
type DrillContext = Readonly<{
root: string;
contractPackages: readonly InstalledContractPackageIdentity[];
}>;
// 13-03: the drill reads the built release only. It used to fall back to the
// placeholders in public/, so it passed without any build at all.
const DEFAULT_ROLLBACK_PATHS = Object.freeze({
primaryRelease: "dist/release-manifest.json",
fallbackRelease: "public/release-manifest.json",
primaryRuntime: "dist/config.json",
fallbackRuntime: "public/config.json",
release: "dist/release-manifest.json",
runtime: "dist/config.json",
});
async function readJsonArtifact(path: string): Promise<unknown> {
return JSON.parse(await readFile(path, "utf8"));
try {
return JSON.parse(await readFile(path, "utf8"));
} catch (error) {
if (hasErrorCode(error, "ENOENT")) {
throw new Error(`${path} is missing; build the release before running the drill`, { cause: error });
}
throw error;
}
}
async function releaseManifest(
readArtifact: JsonArtifactReader = readJsonArtifact,
paths: RollbackArtifactPaths = DEFAULT_ROLLBACK_PATHS,
): Promise<ReleaseArtifact> {
const value = await readPrimaryOrFallback(
readArtifact,
paths.primaryRelease,
paths.fallbackRelease,
);
return parseReleaseArtifact(value);
function rootedReader(root: string): JsonArtifactReader {
return (file) => readJsonArtifact(path.join(root, file));
}
const validConfig = {
@@ -100,12 +121,48 @@ const validConfig = {
RELEASE_ID: "local-release",
};
function verdict(passed: boolean): DrillVerdict {
return passed ? "PASS" : "FAIL";
}
function assertion(
assertion: string,
evidence: string,
passed: boolean,
result: DrillVerdict,
): RecoveryAssertion {
return { assertion, evidence, passed };
return { assertion, evidence, result };
}
/** An assertion the local drill cannot observe; `needs` names what can. */
function notObserved(name: string, needs: string): RecoveryAssertion {
return assertion(name, `not observed locally; needs ${needs}`, "UNVERIFIED");
}
/**
* Every file the Vite manifest names (entries, lazy chunks, CSS, assets) exists
* in the local dist. Hosting reachability still needs the provider smoke.
*/
async function builtAssetsPresent(root: string): Promise<boolean> {
const manifest = await readJsonArtifact(path.join(root, "dist/.vite/manifest.json"));
if (!manifest || typeof manifest !== "object") return false;
const files = new Set<string>();
for (const chunk of Object.values(manifest as Record<string, Record<string, unknown>>)) {
for (const key of ["file", "css", "assets"] as const) {
const value = chunk[key];
for (const file of Array.isArray(value) ? value : [value]) {
if (typeof file === "string") files.add(file);
}
}
}
if (![...files].some((file) => file.endsWith(".js"))) return false;
try {
await Promise.all(
["index.html", ...files].map((file) => access(path.join(root, "dist", file))),
);
return true;
} catch {
return false;
}
}
async function drillBoot(): Promise<DrillResult> {
@@ -115,19 +172,22 @@ async function drillBoot(): Promise<DrillResult> {
API_BASE_URL: "http://insecure.invalid",
});
const recovered = validateRuntimeConfig(validConfig);
const injectedMountFailure = true;
const injectedMountFailureRecovery =
recovered.success && !injectedMountFailure;
return {
triggerAsserted: !invalid.success,
containmentAsserted: !invalid.success,
triggerAsserted: verdict(!invalid.success),
containmentAsserted: verdict(!invalid.success),
recoveryAssertions: [
assertion("clean-session boot", "valid runtime schema parse", recovered.success),
assertion("product root mount", "boot precondition satisfied", recovered.success),
assertion("config validation", "invalid fixture rejected", !invalid.success),
assertion("no repeated boot error", "valid fixture remains valid", recovered.success),
notObserved("clean-session boot", "a browser boot of the promoted release"),
notObserved("product root mount", "a browser boot of the promoted release"),
assertion(
"config validation",
"invalid fixture rejected, valid fixture accepted",
verdict(!invalid.success && recovered.success),
),
notObserved("no repeated boot error", "boot telemetry from the promoted release"),
],
negativeFixtureFailedAsExpected: !injectedMountFailureRecovery,
// The runbook's negative fixture injects a mount failure after a valid
// config; that needs a mounted app, which a Node drill does not have.
negativeFixtureFailedAsExpected: "UNVERIFIED",
providerVerificationRequired: false,
};
}
@@ -144,7 +204,7 @@ function memoryStorage(): StoragePort {
};
}
async function drillChunkMismatch(): Promise<DrillResult> {
async function drillChunkMismatch(context: DrillContext): Promise<DrillResult> {
const storage = memoryStorage();
const input: Parameters<typeof decideChunkRecovery>[0] = {
failureKind: "DEPLOY_MISMATCH",
@@ -157,29 +217,26 @@ async function drillChunkMismatch(): Promise<DrillResult> {
};
const first = decideChunkRecovery(input);
const second = decideChunkRecovery(input);
const manifest = await releaseManifest();
let assetsReachable = true;
try {
await access("dist/index.html");
await access("dist/.vite/manifest.json");
} catch {
assetsReachable = false;
}
const { coherence } = await verifyRollbackReleaseCoherence({
readArtifact: rootedReader(context.root),
contractPackages: context.contractPackages,
});
return {
triggerAsserted: first.action === "reload-once",
containmentAsserted:
triggerAsserted: verdict(first.action === "reload-once"),
containmentAsserted: verdict(
first.action === "reload-once" && second.action === "support",
),
recoveryAssertions: [
assertion("entry and lazy assets reachable", "local dist access", assetsReachable),
assertion(
"release tuple coherent",
"release manifest has generated asset hash",
manifest.assetManifestHash !== "generated-during-build",
"entry and lazy assets reachable",
"every Vite manifest file exists in the local dist",
verdict(await builtAssetsPresent(context.root)),
),
assertion("second reload blocked", "reload guard decision", second.action === "support"),
assertion("critical route smoke", "built index available", assetsReachable),
assertion("release tuple coherent", "build/config/manifest tuple", verdict(coherence.compatible)),
assertion("second reload blocked", "reload guard decision", verdict(second.action === "support")),
notObserved("critical route smoke", "a browser smoke against the hosted release"),
],
negativeFixtureFailedAsExpected: second.action !== "reload-once",
negativeFixtureFailedAsExpected: verdict(second.action !== "reload-once"),
providerVerificationRequired: true,
};
}
@@ -196,15 +253,20 @@ async function drillApiDegradation(): Promise<DrillResult> {
0,
);
return {
triggerAsserted: true,
containmentAsserted: !unkeyedRetry,
// The trigger is a failure rate over live traffic.
triggerAsserted: "UNVERIFIED",
containmentAsserted: verdict(!unkeyedRetry && safeRetry),
recoveryAssertions: [
assertion("failure rate at baseline", "deterministic recovery window", true),
assertion("no retry amplification", "unkeyed retry policy", !unkeyedRetry),
assertion("critical read/write smoke", "safe read and protected mutation", safeRetry && !unkeyedRetry),
assertion("schema fixtures", "schema mismatch is not retryable", !shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
notObserved("terminal failure rate at baseline", "API failure telemetry from the promoted release"),
assertion("no retry amplification", "unkeyed retry policy", verdict(!unkeyedRetry)),
notObserved("critical read/write smoke", "a read and a write against the live API"),
assertion(
"schema fixtures",
"schema mismatch is not retryable",
verdict(!shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
),
],
negativeFixtureFailedAsExpected: !unkeyedRetry,
negativeFixtureFailedAsExpected: verdict(!unkeyedRetry),
providerVerificationRequired: true,
};
}
@@ -224,7 +286,10 @@ async function drillTelemetry(): Promise<DrillResult> {
attempt_count_bucket: "1",
route_id: "APP_HOME",
});
await adapter.flush();
const flushResolved = await adapter.flush().then(
() => true,
() => false,
);
const projected = projectTelemetryEvent("api.request.failed", {
error_kind: "SERVER_FAILURE",
http_status_group: "5xx",
@@ -235,22 +300,25 @@ async function drillTelemetry(): Promise<DrillResult> {
const redacted =
projected.success && !JSON.stringify(projected).includes("raw_url");
return {
triggerAsserted: adapter.droppedCount() === 1,
containmentAsserted: adapter.pendingCount() === 0,
triggerAsserted: verdict(adapter.droppedCount() === 1),
containmentAsserted: verdict(adapter.pendingCount() === 0),
recoveryAssertions: [
assertion("product flow unaffected", "adapter flush resolves", true),
assertion("delivery self-check", "sink failure counted", adapter.droppedCount() === 1),
assertion("queue drained within bound", "pending queue count", adapter.pendingCount() === 0),
assertion("forbidden attributes absent", "default-deny projection", redacted),
assertion("product flow unaffected", "adapter flush resolves despite the sink failure", verdict(flushResolved)),
assertion("delivery self-check", "sink failure counted", verdict(adapter.droppedCount() === 1)),
assertion("queue drained within bound", "pending queue count", verdict(adapter.pendingCount() === 0)),
assertion("forbidden attributes absent", "default-deny projection", verdict(redacted)),
],
negativeFixtureFailedAsExpected: redacted,
negativeFixtureFailedAsExpected: verdict(redacted),
providerVerificationRequired: true,
};
}
async function drillRollback(): Promise<DrillResult> {
const verified = await verifyRollbackReleaseCoherence();
const { release, coherence: coherent } = verified;
async function drillRollback(context: DrillContext): Promise<DrillResult> {
const { release, coherence: coherent } = await verifyRollbackReleaseCoherence({
readArtifact: rootedReader(context.root),
contractPackages: context.contractPackages,
});
const assetsPresent = await builtAssetsPresent(context.root);
const mixed = verifyCompatibilityTuple({
frontend: {
buildId: "build-a",
@@ -268,20 +336,25 @@ async function drillRollback(): Promise<DrillResult> {
},
});
return {
triggerAsserted: true,
containmentAsserted: coherent.compatible,
// A release-blocking defect is declared by a person during an incident.
triggerAsserted: "UNVERIFIED",
containmentAsserted: verdict(coherent.compatible && assetsPresent),
recoveryAssertions: [
assertion("compatibility gate", "typed version comparison", coherent.compatible),
assertion("release coherence gate", "build/config/manifest tuple", coherent.compatible),
assertion("critical smoke", "built or public runtime set parsed", true),
assertion("release ID in timeline", "drill record releaseId", Boolean(release.releaseId)),
assertion("compatibility gate", "typed version comparison", verdict(coherent.compatible)),
assertion(
"release coherence gate",
"build/config/manifest tuple and every Vite manifest file in the local dist",
verdict(coherent.compatible && assetsPresent),
),
notObserved("critical smoke", "a browser smoke after the provider switches to the prior release"),
assertion("release ID in timeline", "drill record releaseId", verdict(Boolean(release.releaseId))),
],
negativeFixtureFailedAsExpected: !mixed.compatible,
negativeFixtureFailedAsExpected: verdict(!mixed.compatible),
providerVerificationRequired: true,
};
}
const drillById: Record<string, () => Promise<DrillResult>> = {
const drillById: Record<string, (context: DrillContext) => Promise<DrillResult>> = {
"FE-RB-001": drillBoot,
"FE-RB-002": drillChunkMismatch,
"FE-RB-003": drillApiDegradation,
@@ -294,12 +367,12 @@ export async function verifyRollbackReleaseCoherence(
) {
const readArtifact = options.readArtifact ?? readJsonArtifact;
const paths = options.paths ?? DEFAULT_ROLLBACK_PATHS;
const artifactPair = await selectRollbackArtifactPair(
readArtifact,
paths,
);
const release = parseReleaseArtifact(artifactPair.release);
const runtimeArtifact = parseRuntimeConfigArtifact(artifactPair.runtime);
const [releaseValue, runtimeValue] = await Promise.all([
readArtifact(paths.release),
readArtifact(paths.runtime),
]);
const release = parseReleaseArtifact(releaseValue);
const runtimeArtifact = parseRuntimeConfigArtifact(runtimeValue);
const runtime = {
...runtimeArtifact,
BUILD_ID: requireIdentity(runtimeArtifact.BUILD_ID, "runtime BUILD_ID"),
@@ -317,43 +390,64 @@ export async function verifyRollbackReleaseCoherence(
return Object.freeze({ release, runtime, coherence });
}
export async function runRunbookDrill(runbookId: string, options: DrillOptions = {}) {
const context: DrillContext = {
root: options.releaseRoot ?? process.cwd(),
contractPackages: options.contractPackages ?? EXPECTED_CONTRACT_SET_PACKAGES,
};
const document = JSON.parse(
await readFile("config/runbooks/runbooks.json", "utf8"),
) as RunbookDocument;
const specification = document.runbooks[runbookId];
const drill = drillById[runbookId];
if (!specification || !drill) throw new RangeError(`unknown runbook: ${runbookId}`);
const release = parseReleaseArtifact(
await rootedReader(context.root)(DEFAULT_ROLLBACK_PATHS.release),
);
const result = await drill(context);
const escalationPathAsserted = verdict(specification.escalation.length >= 2);
return {
schemaVersion: 2 as const,
runbookId,
gateId: specification.gateId,
releaseId: release.releaseId,
drillTimestamp: new Date().toISOString(),
triggerInjected: specification.triggerKinds[0] ?? "",
triggerAsserted: result.triggerAsserted,
containmentAsserted: result.containmentAsserted,
escalationPathAsserted,
recoveryAssertions: result.recoveryAssertions,
negativeFixtureFailedAsExpected: result.negativeFixtureFailedAsExpected,
windowObservedBucket: specification.window,
providerVerificationRequired: result.providerVerificationRequired,
result: combineDrillVerdicts(
[
result.triggerAsserted,
result.containmentAsserted,
escalationPathAsserted,
...result.recoveryAssertions.map((item) => item.result),
result.negativeFixtureFailedAsExpected,
],
result.providerVerificationRequired,
),
};
}
async function main(): Promise<void> {
const runbookId = process.argv
.slice(2)
.find((argument) => /^FE-RB-00[1-5]$/.test(argument));
const document = JSON.parse(
await readFile("config/runbooks/runbooks.json", "utf8"),
) as RunbookDocument;
const specification = runbookId ? document.runbooks[runbookId] : undefined;
if (!runbookId || !specification) {
process.stderr.write("Usage: drill:runbook -- FE-RB-001..FE-RB-005\n");
const releaseRootFlag = process.argv.indexOf("--release-root");
const releaseRoot = releaseRootFlag >= 0 ? process.argv[releaseRootFlag + 1] : undefined;
if (!runbookId || (releaseRootFlag >= 0 && !releaseRoot)) {
process.stderr.write(
"Usage: drill:runbook -- FE-RB-001..FE-RB-005 [--release-root <extracted release archive>]\n",
);
process.exit(2);
}
const drill = await drillById[runbookId]();
const escalationPathAsserted = specification.escalation.length >= 2;
const passed =
drill.triggerAsserted &&
drill.containmentAsserted &&
escalationPathAsserted &&
drill.recoveryAssertions.every((item) => item.passed) &&
drill.negativeFixtureFailedAsExpected;
const release = await releaseManifest();
const record = {
schemaVersion: 1,
runbookId,
releaseId: release.releaseId,
drillTimestamp: new Date().toISOString(),
triggerInjected: specification.triggerKinds[0],
triggerAsserted: drill.triggerAsserted,
containmentAsserted: drill.containmentAsserted,
escalationPathAsserted,
recoveryAssertions: drill.recoveryAssertions,
negativeFixtureFailedAsExpected: drill.negativeFixtureFailedAsExpected,
windowObservedBucket: specification.window,
providerVerificationRequired: drill.providerVerificationRequired,
passed,
};
const { gateId, ...record } = await runRunbookDrill(runbookId, releaseRoot ? { releaseRoot } : {});
const artifactDirectory = `artifacts/runbooks/${runbookId}`;
await mkdir(artifactDirectory, { recursive: true });
await writeValidatedJsonArtifact({
@@ -361,15 +455,25 @@ async function main(): Promise<void> {
schema: runbookRecordArtifactSchema,
value: record,
});
if (!passed) {
process.stderr.write(`${runbookId} drill failed.\n`);
if (record.result === "FAIL") {
process.stderr.write(`${runbookId} drill: FAIL (${gateId})\n`);
process.exit(1);
}
process.stdout.write(
`${runbookId} drill: PASS (${specification.gateId}; provider verification ${
drill.providerVerificationRequired ? "still required" : "not required"
})\n`,
);
if (record.result === "UNVERIFIED") {
// Not a pass: the gate stays red until provider evidence exists (D-14).
const open = [
["trigger", record.triggerAsserted],
["containment", record.containmentAsserted],
...record.recoveryAssertions.map((item) => [item.assertion, item.result] as const),
["negative fixture", record.negativeFixtureFailedAsExpected],
["provider verification", record.providerVerificationRequired ? "UNVERIFIED" : "PASS"],
].filter(([, result]) => result === "UNVERIFIED").map(([name]) => name);
process.stderr.write(
`${runbookId} drill: UNVERIFIED (${gateId}; no local check failed; not observed locally: ${open.join(", ")})\n`,
);
process.exit(3);
}
process.stdout.write(`${runbookId} drill: PASS (${gateId})\n`);
}
function requireIdentity(value: string | undefined, label: string): string {
@@ -379,88 +483,6 @@ function requireIdentity(value: string | undefined, label: string): string {
return value;
}
async function selectRollbackArtifactPair(
readArtifact: JsonArtifactReader,
paths: RollbackArtifactPaths,
): Promise<Readonly<{ release: unknown; runtime: unknown }>> {
const primary = await readArtifactPair(
readArtifact,
paths.primaryRelease,
paths.primaryRuntime,
);
if (
primary.release.status === "fulfilled" &&
primary.runtime.status === "fulfilled"
) {
return Object.freeze({
release: primary.release.value,
runtime: primary.runtime.value,
});
}
const releaseMissing =
primary.release.status === "rejected" &&
hasErrorCode(primary.release.reason, "ENOENT");
const runtimeMissing =
primary.runtime.status === "rejected" &&
hasErrorCode(primary.runtime.reason, "ENOENT");
if (releaseMissing && runtimeMissing) {
const fallback = await readArtifactPair(
readArtifact,
paths.fallbackRelease,
paths.fallbackRuntime,
);
if (fallback.release.status === "rejected") {
throw fallback.release.reason;
}
if (fallback.runtime.status === "rejected") {
throw fallback.runtime.reason;
}
return Object.freeze({
release: fallback.release.value,
runtime: fallback.runtime.value,
});
}
if (primary.release.status === "rejected" && !releaseMissing) {
throw primary.release.reason;
}
if (primary.runtime.status === "rejected" && !runtimeMissing) {
throw primary.runtime.reason;
}
throw new Error("primary rollback artifact pair is incomplete");
}
async function readArtifactPair(
readArtifact: JsonArtifactReader,
releasePath: string,
runtimePath: string,
): Promise<
Readonly<{
release: PromiseSettledResult<unknown>;
runtime: PromiseSettledResult<unknown>;
}>
> {
const [release, runtime] = await Promise.allSettled([
Promise.resolve().then(() => readArtifact(releasePath)),
Promise.resolve().then(() => readArtifact(runtimePath)),
]);
return Object.freeze({ release, runtime });
}
async function readPrimaryOrFallback(
readArtifact: JsonArtifactReader,
primary: string,
fallback: string,
): Promise<unknown> {
try {
return await readArtifact(primary);
} catch (error) {
if (!hasErrorCode(error, "ENOENT")) throw error;
return readArtifact(fallback);
}
}
function hasErrorCode(error: unknown, code: string): boolean {
return Boolean(
error &&
+44 -12
View File
@@ -28,7 +28,6 @@ export type GenerateCiWorkflowOptions = Readonly<{
root: string;
contract?: CiGateContract;
check: boolean;
contractMode?: "canonical" | "removal-fixture";
}>;
export type GenerateCiWorkflowResult = Readonly<{
@@ -197,10 +196,16 @@ function renderStep(
" run: corepack pnpm exec playwright install --with-deps chromium firefox webkit",
];
case "run-gate": {
const gateId = job.kind === "gate-matrix" ? "${{ matrix.gate }}" : job.gateIds[0];
if (!gateId) throw new TypeError(`run-gate step lacks ownership: ${job.id}`);
const name = job.id === "documentation_gate" ? "Run documentation gate" : job.id === "immutable_build" ? "Build candidate once and verify local evidence" : "Run blocking gate";
return [` - name: ${name}`, ` run: corepack pnpm ci:gate -- ${gateId}`];
if (job.kind === "gate-matrix") {
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}`);
// 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) => [
` - name: ${runGateStepName(job.id, gateId)}`,
` run: corepack pnpm ci:gate -- ${gateId}`,
]);
}
case "archive-candidate": {
const archive = shellDoubleQuoted(step.archivePath);
@@ -347,6 +352,38 @@ function shellDoubleQuoted(value: string): string {
return `"${escaped}"`;
}
function runGateStepName(jobId: string, gateId: string): string {
if (gateId === "FE-GATE-015") return "Build candidate once and verify local evidence";
if (gateId === "FE-GATE-027") return "Admit the candidate to the declared release target";
return jobId === "documentation_gate" ? "Run documentation gate" : "Run blocking gate";
}
/**
* 12-02 / D-12. Every contract gate must be executed by the workflow text: a
* literal `ci:gate -- <id>` run line, or a matrix entry of a job whose run step
* is `ci:gate -- ${{ matrix.gate }}`. Owning a gate in the contract is not
* enough; the generator once dropped all but the first.
*/
export function workflowGateExecutionFailures(
contract: CiGateContract,
workflow: string,
): string[] {
const executed = new Set<string>();
for (const job of workflow.split(/^(?= {2}[a-z_]+:$)/mu)) {
for (const match of job.matchAll(/^ +run: corepack pnpm ci:gate -- (FE-GATE-\d{3})$/gmu)) {
executed.add(match[1]!);
}
if (/^ +run: corepack pnpm ci:gate -- \$\{\{ matrix\.gate \}\}$/mu.test(job)) {
for (const match of job.matchAll(/^ +- \{ gate: (FE-GATE-\d{3}),/gmu)) {
executed.add(match[1]!);
}
}
}
return contract.gates
.filter(({ id }) => !executed.has(id))
.map(({ id }) => `gate is not executed by any workflow run step: ${id}`);
}
function humanize(value: string): string {
return value.replaceAll("-", " ");
}
@@ -361,9 +398,7 @@ export function createCiWorkflowGenerator(
const createNonce = dependencies.createNonce ?? randomUUID;
return async function generate(options: GenerateCiWorkflowOptions): Promise<GenerateCiWorkflowResult> {
const root = path.resolve(options.root);
const contract = options.contract ?? (await loadCiGateContract(root, {
mode: options.contractMode ?? "canonical",
}));
const contract = options.contract ?? (await loadCiGateContract(root));
const target = path.resolve(root, contract.providerAdapter);
if (path.relative(root, target).startsWith("..") || path.relative(root, target) === "") {
throw new TypeError(`workflow target escapes repository root: ${contract.providerAdapter}`);
@@ -478,11 +513,8 @@ function hasErrorCode(error: unknown, code: string): boolean {
const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isCli) {
const check = process.argv.includes("--check");
const contractMode = process.argv.includes("--reduced-removal-fixture")
? "removal-fixture" as const
: "canonical" as const;
try {
const result = await generateCiWorkflow({ root: process.cwd(), check, contractMode });
const result = await generateCiWorkflow({ root: process.cwd(), check });
if (!result.matches) {
process.stderr.write(
`CI workflow drift: ${result.target} differs at byte ${result.firstDifferenceByte ?? 0}, line ${result.firstDifferenceLine ?? 1}\n`,
-5
View File
@@ -53,11 +53,6 @@ async function readJson<T>(file: string): Promise<T> {
return JSON.parse(await readFile(file, "utf8")) as T;
}
/** nginx location matching is not regex-escaped for us; only `=` exact paths are literal. */
function exactLocation(pathname: string): string {
return pathname;
}
/**
* A JS regex from the contract translated for nginx. Both use PCRE-ish syntax
* for what the contract uses (`^`, `$`, `[^/]+`, alternation), so the pattern
+427
View File
@@ -0,0 +1,427 @@
import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
import { dirname, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { selectCompiledProductFeatures } from "../src/contracts/product-features.ts";
export type FeatureImportEntry = Readonly<{
id: string;
importPath: string;
}>;
export type FeatureIndexEntry = FeatureImportEntry & Readonly<{
directory: string;
contextId: string;
contextRoutePath: string;
contextMaxFeatures: number;
}>;
/**
* `declaredIds` is every feature the app declares, selected or not, so a build
* that left one out still reports it as `NOT_INSTALLED` without importing it.
*/
export function renderFeatureIndex(
entries: readonly FeatureImportEntry[],
declaredIds: readonly string[] = entries.map((entry) => entry.id),
): string {
const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id));
const declared = [...declaredIds]
.sort((left, right) => left.localeCompare(right))
.map((id) => JSON.stringify(id))
.join(", ");
const imports = sorted
.map(
(entry, index) =>
`import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`,
)
.join("\n");
const modules = sorted.map((_, index) => ` featureModule${index},`).join("\n");
const featureImports = imports.length > 0 ? `${imports}\n` : "";
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport type { FeatureModule } from "../features/feature-module.ts";\n${featureImports}\nexport const DECLARED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze([${declared}]);\n\nexport const PRODUCT_FEATURE_MODULES = Object.freeze([\n${modules}\n] as const);\n\ntype GeneratedProductFeatureModule = (typeof PRODUCT_FEATURE_MODULES)[number];\nexport type ProductFeatureModule =\n [GeneratedProductFeatureModule] extends [never]\n ? FeatureModule\n : GeneratedProductFeatureModule;\n`;
}
export function renderContextIndex(entries: readonly FeatureIndexEntry[]): string {
if (entries.length === 0) {
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([] as const);\n`;
}
const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id));
const imports = sorted
.map(
(entry, index) =>
`import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`,
)
.join("\n");
const indexById = new Map(sorted.map((entry, index) => [entry.id, index] as const));
const grouped = new Map<string, FeatureIndexEntry[]>();
for (const entry of sorted) {
const group = grouped.get(entry.contextId) ?? [];
group.push(entry);
grouped.set(entry.contextId, group);
}
const contexts = [...grouped.entries()]
.sort(([left], [right]) => left.localeCompare(right))
.map(([contextId, features]) => {
const first = features[0];
if (!first) throw new Error(`Context ${contextId} has no features`);
for (const feature of features) {
if (feature.contextRoutePath !== first.contextRoutePath) {
throw new Error(
`Context ${contextId} has conflicting route paths: ${first.contextRoutePath}, ${feature.contextRoutePath}`,
);
}
if (feature.contextMaxFeatures !== first.contextMaxFeatures) {
throw new Error(
`Context ${contextId} has conflicting maxFeatures budgets: ${first.contextMaxFeatures}, ${feature.contextMaxFeatures}`,
);
}
}
if (features.length > first.contextMaxFeatures) {
throw new Error(
`Context ${contextId} feature cardinality ${features.length} exceeds budget ${first.contextMaxFeatures}`,
);
}
const featureRefs = features
.map((feature) => `featureModule${indexById.get(feature.id)}`)
.join(", ");
const routeImports = features
.map(
(feature, index) =>
` import(${JSON.stringify(`../features/${feature.directory}/context-routes.ts`)})${index < features.length - 1 ? "," : ""}`,
)
.join("\n");
const routeSpreads = features
.map((_, index) => ` ...routeModule${index}.FEATURE_CONTEXT_ROUTES,`)
.join("\n");
const routeBindings = features
.map((_, index) => `routeModule${index}`)
.join(", ");
return ` defineBoundedContextModule({\n id: ${JSON.stringify(contextId)},\n features: Object.freeze([${featureRefs}]),\n budget: Object.freeze({ maxFeatures: ${first.contextMaxFeatures} }),\n route: Object.freeze({\n path: ${JSON.stringify(first.contextRoutePath)},\n async loadRoutes() {\n const [${routeBindings}] = await Promise.all([\n${routeImports}\n ]);\n return Object.freeze([\n${routeSpreads}\n ]);\n },\n }),\n }),`;
})
.join("\n");
const featureImports = imports.length > 0 ? `${imports}\n` : "";
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport { defineBoundedContextModule } from "../contexts/bounded-context-module.ts";\n${featureImports}\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([\n${contexts}\n] as const);\n`;
}
/**
* Ownership declarations the generator reads, documented in
* docs/architecture/starter-experience.md ("Ownership declarations"). Each boundary
* declares only its parent:
*
* src/apps/<app>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
* src/contexts/<context>/context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID,
* CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES
* src/features/<feature>/feature-module.ts FEATURE_MODULE_ID, FEATURE_CONTEXT_ID
*
* The generated indexes describe exactly one deployable app: the contexts it
* owns and the features those contexts own. Features of other apps are never
* imported, so global growth elsewhere cannot enter this app's compile or
* boot graph.
*/
export type AppDeclaration = Readonly<{ id: string; maxContexts: number }>;
export type ContextDeclaration = Readonly<{
id: string;
appId: string;
routePath: string;
maxFeatures: number;
}>;
export type FeatureDeclaration = Readonly<{
id: string;
contextId: string;
directory: string;
}>;
/**
* Ownership-indexed view of the declarations. The generator only asks for one
* app, that app's contexts and those contexts' features, so its work and its
* output are local to the selected app.
*/
export interface TopologyDeclarationSource {
appIds(): readonly string[];
app(appId: string): AppDeclaration | undefined;
contextsOf(appId: string): readonly ContextDeclaration[];
featuresOf(contextId: string): readonly FeatureDeclaration[];
}
export type SelectedAppIndexes = Readonly<{
app: AppDeclaration;
entries: readonly FeatureIndexEntry[];
featureIndex: string;
contextIndex: string;
appIndex: string;
}>;
export function renderAppIndex(app: AppDeclaration): string {
return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.
export const PRODUCT_APP = Object.freeze({
id: ${JSON.stringify(app.id)},
maxContexts: ${app.maxContexts},
} as const);
`;
}
export function resolveSelectedApp(
source: TopologyDeclarationSource,
requested: string | undefined,
): string {
if (requested) {
if (!source.app(requested)) throw new Error(`Unknown deployable app: ${requested}`);
return requested;
}
const ids = source.appIds();
if (ids.length !== 1) {
throw new Error(
`Select a deployable app with --app=<id> or PRODUCT_APP_ID (declared: ${ids.join(", ") || "none"})`,
);
}
return ids[0] as string;
}
/**
* The production selection: one app -> its direct contexts -> their features,
* narrowed by `VITE_PRODUCT_FEATURES` (09-02, D-9). The narrowing happens here
* so the bundle, the Node build scripts and the context router all import the
* same set, and a misspelt id fails the first build step.
*/
export function selectAppIndexes(
source: TopologyDeclarationSource,
appId: string,
productFeatures?: string,
): SelectedAppIndexes {
const app = source.app(appId);
if (!app) throw new Error(`Unknown deployable app: ${appId}`);
const contexts = [...source.contextsOf(appId)].sort((left, right) =>
left.id.localeCompare(right.id),
);
const entries: FeatureIndexEntry[] = [];
let populatedContexts = 0;
for (const context of contexts) {
const features = source.featuresOf(context.id);
if (features.length === 0) continue;
populatedContexts += 1;
if (features.length > context.maxFeatures) {
throw new Error(
`Context ${context.id} feature cardinality ${features.length} exceeds budget ${context.maxFeatures}`,
);
}
for (const feature of features) {
entries.push({
id: feature.id,
importPath: `../features/${feature.directory}/feature-module.ts`,
directory: feature.directory,
contextId: context.id,
contextRoutePath: context.routePath,
contextMaxFeatures: context.maxFeatures,
});
}
}
if (populatedContexts > app.maxContexts) {
throw new Error(
`App ${app.id} context cardinality ${populatedContexts} exceeds budget ${app.maxContexts}`,
);
}
const ids = entries.map((entry) => entry.id);
if (new Set(ids).size !== ids.length) {
throw new Error(`Duplicate generated feature ids: ${ids.join(", ")}`);
}
const selected = selectCompiledProductFeatures(
entries.map((entry) => Object.freeze({ featureId: entry.id, entry })),
productFeatures,
).map(({ entry }) => entry);
return Object.freeze({
app,
entries: Object.freeze(selected),
featureIndex: renderFeatureIndex(selected, ids),
contextIndex: renderContextIndex(selected),
appIndex: renderAppIndex(app),
});
}
function requiredLiteral(source: string, name: string, file: string): string {
const match = source.match(
new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']([^"']+)["']`),
);
if (!match?.[1]) {
throw new Error(`${file} must export a literal ${name}`);
}
return match[1];
}
function requiredInteger(source: string, name: string, file: string): number {
const match = source.match(
new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(\\d+)`),
);
const parsed = match?.[1] ? Number.parseInt(match[1], 10) : Number.NaN;
if (!Number.isSafeInteger(parsed) || parsed < 1) {
throw new Error(`${file} must export a positive integer ${name}`);
}
return parsed;
}
/**
* 09-07 (D-10). A feature directory must declare itself or say it is not
* installed. A missing or misspelt `feature-module.ts` used to drop the
* feature from the product without a word.
*/
export const NOT_INSTALLED_MARKER = "NOT_INSTALLED";
async function readDeclarations(
directory: string,
fileName: string,
requiredUnless?: string,
): Promise<readonly Readonly<{ directory: string; file: string; source: string }>[]> {
const found: { directory: string; file: string; source: string }[] = [];
let items;
try {
items = await readdir(directory, { withFileTypes: true });
} catch {
return found;
}
for (const item of items) {
if (!item.isDirectory()) continue;
const file = resolve(directory, item.name, fileName);
try {
found.push({ directory: item.name, file, source: await readFile(file, "utf8") });
} catch {
if (requiredUnless === undefined) continue;
const marker = await readFile(resolve(directory, item.name, requiredUnless))
.then(() => true, () => false);
if (marker) continue;
throw new Error(
`src/features/${item.name} has no ${fileName}; add one or mark the directory with ${requiredUnless}`,
);
}
}
return found;
}
/**
* Filesystem declaration source. Declarations are small literal headers, so
* reading them is a metadata scan; only the selected app's features are ever
* imported by the generated output.
*/
export async function createFileSystemDeclarationSource(
root: string,
): Promise<TopologyDeclarationSource> {
const apps = new Map<string, AppDeclaration>();
for (const declaration of await readDeclarations(resolve(root, "src/apps"), "app-module.ts")) {
const id = requiredLiteral(declaration.source, "APP_MODULE_ID", declaration.file);
if (apps.has(id)) throw new Error(`Duplicate app id: ${id}`);
apps.set(id, {
id,
maxContexts: requiredInteger(declaration.source, "APP_MAX_CONTEXTS", declaration.file),
});
}
const contextsByApp = new Map<string, ContextDeclaration[]>();
const contextIds = new Set<string>();
for (const declaration of await readDeclarations(resolve(root, "src/contexts"), "context-module.ts")) {
const context: ContextDeclaration = {
id: requiredLiteral(declaration.source, "CONTEXT_MODULE_ID", declaration.file),
appId: requiredLiteral(declaration.source, "CONTEXT_APP_ID", declaration.file),
routePath: requiredLiteral(declaration.source, "CONTEXT_ROUTE_PATH", declaration.file),
maxFeatures: requiredInteger(declaration.source, "CONTEXT_MAX_FEATURES", declaration.file),
};
if (contextIds.has(context.id)) throw new Error(`Duplicate context id: ${context.id}`);
if (!apps.has(context.appId)) {
throw new Error(`Context ${context.id} belongs to undeclared app ${context.appId}`);
}
contextIds.add(context.id);
const owned = contextsByApp.get(context.appId) ?? [];
owned.push(context);
contextsByApp.set(context.appId, owned);
}
const featuresByContext = new Map<string, FeatureDeclaration[]>();
const featureIds = new Set<string>();
for (const declaration of await readDeclarations(
resolve(root, "src/features"),
"feature-module.ts",
NOT_INSTALLED_MARKER,
)) {
const feature: FeatureDeclaration = {
id: requiredLiteral(declaration.source, "FEATURE_MODULE_ID", declaration.file),
contextId: requiredLiteral(declaration.source, "FEATURE_CONTEXT_ID", declaration.file),
directory: declaration.directory,
};
if (featureIds.has(feature.id)) throw new Error(`Duplicate generated feature ids: ${feature.id}`);
if (!contextIds.has(feature.contextId)) {
throw new Error(`Feature ${feature.id} belongs to undeclared context ${feature.contextId}`);
}
featureIds.add(feature.id);
const owned = featuresByContext.get(feature.contextId) ?? [];
owned.push(feature);
featuresByContext.set(feature.contextId, owned);
}
return Object.freeze({
appIds: () => [...apps.keys()].sort(),
app: (appId: string) => apps.get(appId),
contextsOf: (appId: string) => contextsByApp.get(appId) ?? [],
featuresOf: (contextId: string) => featuresByContext.get(contextId) ?? [],
});
}
export async function generateAppIndexes(
root: string,
requestedApp: string | undefined,
productFeatures?: string,
): Promise<SelectedAppIndexes> {
const source = await createFileSystemDeclarationSource(root);
return selectAppIndexes(
source,
resolveSelectedApp(source, requestedApp),
productFeatures,
);
}
async function main(): Promise<void> {
const scriptDir = dirname(fileURLToPath(import.meta.url));
// `--root=` points the same production command at another checkout (used by
// the multi-app topology evidence); the default is this repository.
const rootArgument = process.argv
.find((argument) => argument.startsWith("--root="))
?.slice("--root=".length);
const root = rootArgument ? resolve(rootArgument) : resolve(scriptDir, "..");
const outputRoot = resolve(root, "src/.generated");
const outputs = {
feature: resolve(outputRoot, "product-feature-index.ts"),
context: resolve(outputRoot, "product-context-index.ts"),
app: resolve(outputRoot, "product-app.ts"),
};
const requestedApp =
process.argv.find((argument) => argument.startsWith("--app="))?.slice("--app=".length) ||
process.env["PRODUCT_APP_ID"] ||
undefined;
const selected = await generateAppIndexes(
root,
requestedApp,
process.env["VITE_PRODUCT_FEATURES"],
);
const rendered = {
feature: selected.featureIndex,
context: selected.contextIndex,
app: selected.appIndex,
};
await mkdir(outputRoot, { recursive: true });
if (process.argv.includes("--check")) {
const stale: string[] = [];
for (const key of ["feature", "context", "app"] as const) {
const current = await readFile(outputs[key], "utf8").catch(() => "");
if (current !== rendered[key]) stale.push(relative(root, outputs[key]));
}
if (stale.length > 0) {
throw new Error(`Generated topology index is stale: ${stale.join(", ")}`);
}
return;
}
await Promise.all(
(["feature", "context", "app"] as const).map((key) =>
writeFile(outputs[key], rendered[key], "utf8"),
),
);
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
await main();
}
+20 -3
View File
@@ -5,6 +5,7 @@ import process from "node:process";
import {
DEPLOYMENT_TARGETS,
isDeploymentTarget,
PUBLIC_TARGETS,
type DeploymentTarget,
} from "../src/contracts/deployment-admission.ts";
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
@@ -29,7 +30,7 @@ const OUTPUT_PATH = "dist/config.json";
* Deployment-supplied values. Everything else is fixed by the profile so a
* deployment cannot quietly widen what was reviewed.
*/
const OVERRIDES = Object.freeze({
export const RUNTIME_OVERRIDES = Object.freeze({
API_BASE_URL: "RUNTIME_API_BASE_URL",
TELEMETRY_ENDPOINT: "RUNTIME_TELEMETRY_ENDPOINT",
} as const);
@@ -49,11 +50,27 @@ export async function generateRuntimeConfig(
`${profilePath}: declares APP_ENV ${String(draft["APP_ENV"])}, expected ${target}`,
);
}
for (const [field, variable] of Object.entries(OVERRIDES)) {
for (const [field, variable] of Object.entries(RUNTIME_OVERRIDES)) {
const supplied = environment[variable];
if (supplied !== undefined && supplied !== "") draft[field] = supplied;
}
const buildId = environment["VITE_BUILD_ID"] ?? "local-build";
// 13-07. dist, and the release manifest in it, is served under the router
// base path; a root-relative profile URL is rebased onto it.
const basePath = environment["VITE_ROUTER_BASE_PATH"] || "/";
const manifestUrl = draft["RELEASE_MANIFEST_URL"];
if (
typeof manifestUrl === "string" &&
manifestUrl.startsWith("/") &&
!manifestUrl.startsWith(basePath)
) {
draft["RELEASE_MANIFEST_URL"] = `${basePath}${manifestUrl.slice(1)}`;
}
// F-6. A public build without its own identity would ship the local
// placeholder; fail here instead of at admission.
if (PUBLIC_TARGETS.has(target) && !environment["VITE_BUILD_ID"]) {
throw new Error(`${profilePath}: a ${target} build requires VITE_BUILD_ID`);
}
const buildId = environment["VITE_BUILD_ID"] || "local-build";
const releaseId = environment["RELEASE_ID"] ?? "local-release";
draft["BUILD_ID"] = buildId;
draft["RELEASE_ID"] = releaseId;
+2 -1
View File
@@ -10,6 +10,7 @@ import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import {
HASHED_STATIC_ASSET_NAME,
SERVICE_WORKER_BOUNDS,
SERVICE_WORKER_SCRIPT_PATH,
type StaticAssetManifestV1,
@@ -38,7 +39,7 @@ const EXCLUDED_FILES: ReadonlySet<string> = new Set([
]);
/** Vite emits content-hashed names; only those may be treated as immutable. */
const HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/;
const HASHED_NAME = HASHED_STATIC_ASSET_NAME;
export async function collectStaticAssets(
distDirectory: string,
-4
View File
@@ -66,10 +66,6 @@ async function jsonDocument(file: string): Promise<Document> {
return documentValue(parsed, file);
}
async function sha256File(file: string): Promise<string> {
return createHash("sha256").update(await readFile(file)).digest("hex");
}
async function optionalJson(file: string): Promise<Document | null> {
try {
const parsed: unknown = JSON.parse(await readFile(file, "utf8"));
@@ -0,0 +1,17 @@
/**
* 12-11. One violation line names the rule, the edge and the import specifier
* as written, then the rule's `comment` from .dependency-cruiser.json: why the
* edge is forbidden and where the code should go instead.
*/
export function formatArchitectureViolation(
violation: Readonly<{ rule: string; source: string; target: string; cycle?: readonly string[] }>,
specifiers: readonly string[],
comment: string | undefined,
): string {
const imports = specifiers.length > 0
? ` (import ${specifiers.map((specifier) => JSON.stringify(specifier)).join(", ")})`
: "";
const cycle = violation.cycle ? ` (cycle group: ${violation.cycle.join(", ")})` : "";
const why = comment ? ` why: ${comment}\n` : "";
return `Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${imports}${cycle}\n${why}`;
}
-1
View File
@@ -4,7 +4,6 @@ import { constants } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import {
lstat,
mkdir,
open,
readFile,
readdir,
+7 -3
View File
@@ -2,12 +2,15 @@ type ViteManifestEntry = Readonly<{
file: string;
isEntry?: boolean;
imports?: readonly string[];
dynamicImports?: readonly string[];
}>;
/**
* Static imports of an entry are part of initial JavaScript. Every remaining
* JavaScript output is governed by the lazy-chunk budget.
*
* Static imports of an entry are part of initial JavaScript, and so are the
* chunks the entry itself imports dynamically: main.tsx only imports the
* application graph that way so it can report a graph that fails to evaluate
* (09-03). Every remaining JavaScript output is governed by the lazy-chunk
* budget.
*/
export function classifyViteJavascript(
manifest: Readonly<Record<string, ViteManifestEntry>>,
@@ -31,6 +34,7 @@ export function classifyViteJavascript(
}
if (entry.file.endsWith(".js")) initialFiles.add(entry.file);
pendingKeys.push(...(entry.imports ?? []));
if (entry.isEntry) pendingKeys.push(...(entry.dynamicImports ?? []));
}
const allJavaScript = new Set(
+18
View File
@@ -0,0 +1,18 @@
import { chmod, readdir, stat } from "node:fs/promises";
import path from "node:path";
/**
* 13-02. dist is published as-is to a web server that may run as another OS
* user, so every file in it must be readable by others. The validated JSON
* writer creates files 0600 on purpose (evidence under artifacts/ stays
* private); the build adds read bits to what it publishes instead of loosening
* that writer.
*/
export async function makeDistFilesPublic(directory: string): Promise<void> {
for (const entry of await readdir(directory, { recursive: true, withFileTypes: true })) {
if (!entry.isFile()) continue;
const file = path.join(entry.parentPath, entry.name);
const { mode } = await stat(file);
if ((mode & 0o004) === 0) await chmod(file, (mode & 0o7777) | 0o444);
}
}
+31 -1
View File
@@ -9,6 +9,7 @@ import {
import {
PROMOTION_VERIFIER_ID,
PROMOTION_VERIFIER_VERSION,
PROVIDER_FUTURE_SKEW_MS,
assertDistinctProviderTrust,
evaluatePromotionEvidence,
providerVerificationArtifactSchema,
@@ -35,6 +36,29 @@ export type ExactPromotionExpectedContext = Readonly<{
lockfileSha256?: string;
}>;
/**
* 13-04. `current` checks provider evidence against the clock, as a new
* promotion must. `archived` re-verifies a release promoted earlier (deploying
* it later, or rolling back to it): signatures, digests and members are checked
* the same way, but freshness is judged at the promotion's recorded
* `verifiedAt`, which may not lie in the future. Promotion itself
* (promotion-stager.ts) never passes `archived`.
*/
export type PromotionFreshness = "current" | "archived";
export function promotionEvidenceTime(
freshness: PromotionFreshness,
verifiedAt: string,
now: number,
): number {
if (freshness === "current") return now;
const verified = Date.parse(verifiedAt);
if (!Number.isFinite(verified) || verified > now + PROVIDER_FUTURE_SKEW_MS) {
throw new Error("archived promotion verifiedAt is in the future or invalid");
}
return verified;
}
export async function verifyExactPromotionBundle(
files: ExactPromotionBundle,
options: Readonly<{
@@ -42,6 +66,7 @@ export async function verifyExactPromotionBundle(
provenanceTrust: ProviderTrust;
expected: ExactPromotionExpectedContext;
nowEpochMs?: () => number;
freshness?: PromotionFreshness;
}>,
): Promise<Readonly<{ status: "PASS" }>> {
assertDistinctProviderTrust(options);
@@ -286,7 +311,12 @@ export async function verifyExactPromotionBundle(
provenanceAttestation: provenance,
vulnerabilityTrust: options.vulnerabilityTrust,
provenanceTrust: options.provenanceTrust,
nowEpochMs: options.nowEpochMs,
nowEpochMs: () =>
promotionEvidenceTime(
options.freshness ?? "current",
promotion.verifiedAt,
(options.nowEpochMs ?? Date.now)(),
),
});
if (
reevaluated.status !== "PASS" ||
+50 -3
View File
@@ -1,4 +1,4 @@
import { lstat, mkdir, readdir, symlink } from "node:fs/promises";
import { copyFile, mkdir, readdir, readFile, stat, symlink, writeFile } from "node:fs/promises";
import path from "node:path";
/**
@@ -15,7 +15,32 @@ import path from "node:path";
* is an individual symlink. Package resolution is unchanged, but a recursive
* delete unlinks the fixture's own symlinks instead of walking through one link
* into the shared tree.
*
* Top-level files are pnpm's install state (`.modules.yaml`,
* `.pnpm-workspace-state-v1.json`, ...). pnpm rewrites them in place when it
* runs inside the fixture, so they are copied: a link would carry the fixture's
* path into the repository's own state and make its next pnpm command
* re-verify the install.
*
* The copied workspace state still names the repository as its validated
* project, so pnpm in the fixture would re-verify and start an install through
* the linked directories. It is rewritten to name the fixture root instead:
* the packages are the repository's own, already validated.
*/
/**
* F-4. The environment for every `pnpm` a linked fixture runs. pnpm verifies
* the install before a script and, when the fixture's copied state disagrees
* with its own settings (for example `CI=true` against an install made
* without it), installs. `.pnpm` and `.bin` are links into the repository's
* node_modules, so that install rewrote the shared `.pnpm/lock.yaml` and bin
* shims. A fixture started through `pnpm <script>` inherits this setting from
* pnpm; one started directly (`node scripts/run-vitest.ts run <file>`) did not.
* The fixture uses the repository's packages as they are; it never installs.
*/
export const FIXTURE_PNPM_ENVIRONMENT = Object.freeze({
pnpm_config_verify_deps_before_run: "false",
});
export async function linkFixtureNodeModules(
fixtureRoot: string,
sourceRoot: string = process.cwd(),
@@ -25,7 +50,29 @@ export async function linkFixtureNodeModules(
await mkdir(target, { recursive: true });
for (const entry of await readdir(source)) {
const from = path.join(source, entry);
const stats = await lstat(from);
await symlink(from, path.join(target, entry), stats.isDirectory() ? "dir" : "file");
const to = path.join(target, entry);
if ((await stat(from)).isDirectory()) await symlink(from, to, "dir");
else await copyFile(from, to);
}
await retargetWorkspaceState(
path.join(target, ".pnpm-workspace-state-v1.json"),
fixtureRoot,
);
}
async function retargetWorkspaceState(
statePath: string,
fixtureRoot: string,
): Promise<void> {
let state: { projects?: Record<string, unknown>; lastValidatedTimestamp?: number };
try {
state = JSON.parse(await readFile(statePath, "utf8"));
} catch {
return; // no state file, or not pnpm's JSON: nothing to retarget
}
const [project] = Object.values(state.projects ?? {});
if (project === undefined) return;
state.projects = { [fixtureRoot]: project };
state.lastValidatedTimestamp = Date.now();
await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
}
+57
View File
@@ -1,5 +1,62 @@
import type { InstalledServiceWorkerSelection } from "../../src/contracts/service-worker.ts";
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
export type HostingMode = "live" | "invalid-live" | "fixture";
export type HostingVerdict = "PASS" | "FAIL" | "UNVERIFIED";
/**
* 13-05 (D-14). The fixture compares the declared headers with a copy of
* themselves, so it can only find a contradiction, never prove hosting. Only a
* live probe of the deployed release can PASS.
*/
export function hostingVerdict(mode: HostingMode, passed: boolean): HostingVerdict {
if (!passed) return "FAIL";
return mode === "live" ? "PASS" : "UNVERIFIED";
}
/**
* 13-05. The live probe requests the entry script the served index.html names,
* so it checks the release that is deployed rather than the first asset of a
* local build, which the deployed release may not contain.
*/
export function servedEntryScript(indexHtml: string): string | null {
for (const tag of indexHtml.match(/<script\b[^>]*>/gu) ?? []) {
if (!/\btype=["']module["']/u.test(tag)) continue;
const source = /\bsrc=["']([^"']+\.js)["']/u.exec(tag)?.[1];
if (source) return source;
}
return null;
}
const PUBLIC_SERVICE_WORKER = /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i;
/**
* A built `dist` may ship a worker script only when the static selection is
* `ACTIVE` or `REMOVE_REGISTRATION` (the self-unregistering worker, 06-03), and
* then only the selected script at the app root.
*/
export function checkPublicServiceWorkers(
distFiles: readonly string[],
selection: InstalledServiceWorkerSelection | null,
) {
const found = distFiles.filter((file) => PUBLIC_SERVICE_WORKER.test(file));
const allowed: string[] =
selection?.mode === "ACTIVE" || selection?.mode === "REMOVE_REGISTRATION"
? [selection.scriptPath]
: [];
const passed =
found.length === allowed.length &&
found.every((file) => allowed.includes(file));
return {
surface: "serviceWorker",
header: "enabled",
expected: allowed.length > 0,
observed: found.length > 0,
passed,
...(passed ? {} : { reason: `dist worker scripts: ${found.join(", ") || "none"}` }),
};
}
/**
* A release gate must not promote a local preview server as live hosting
* evidence.
+89
View File
@@ -0,0 +1,89 @@
/**
* 11-07. The pieces of the lab performance gate (`scripts/test-performance.ts`)
* that decide what is measured and whether the numbers can be trusted.
*/
export const DEFAULT_LAB_PORT = 4173;
export const DEFAULT_LAB_RUNS = 5;
/**
* `vite preview` arguments. Without `--strictPort` vite moved to the next free
* port when the requested one was taken, and the gate measured whatever server
* already listened there.
*/
export function previewArguments(port: number): readonly string[] {
return [
"pnpm",
"preview",
"--host",
"127.0.0.1",
"--port",
String(port),
"--strictPort",
];
}
export type SampleSummary = Readonly<{
median: number;
min: number;
max: number;
samples: readonly number[];
}>;
export function summarizeSamples(samples: readonly number[]): SampleSummary {
if (samples.length === 0) throw new RangeError("no samples to summarize");
const sorted = [...samples].sort((left, right) => left - right);
const middle = Math.floor(sorted.length / 2);
const median =
sorted.length % 2 === 1
? sorted[middle]!
: (sorted[middle - 1]! + sorted[middle]!) / 2;
return Object.freeze({
median,
min: sorted[0]!,
max: sorted.at(-1)!,
samples: Object.freeze([...samples]),
});
}
/** Fails when anything already answers where the preview server will listen. */
export async function assertPortUnused(
baseUrl: string,
fetchImpl: typeof fetch = fetch,
): Promise<void> {
let answered = false;
try {
await fetchImpl(baseUrl, { signal: AbortSignal.timeout(1_000) });
answered = true;
} catch {
// Nothing is listening: the expected state.
}
if (answered) {
throw new Error(
`${baseUrl} already answers before the preview server starts; another server holds the port.`,
);
}
}
/**
* Compares the release the server actually serves with the local build that
* is being measured, so the numbers belong to that build.
*/
export async function assertServedRelease(
baseUrl: string,
expected: Readonly<{ buildId: string; releaseId: string }>,
fetchImpl: typeof fetch = fetch,
): Promise<void> {
const response = await fetchImpl(new URL("/release-manifest.json", baseUrl), {
cache: "no-store",
});
const served = response.ok
? ((await response.json()) as Partial<Record<"buildId" | "releaseId", unknown>>)
: {};
if (served.buildId !== expected.buildId || served.releaseId !== expected.releaseId) {
throw new Error(
`${baseUrl} serves build ${String(served.buildId)}/${String(served.releaseId)}, ` +
`not the measured ${expected.buildId}/${expected.releaseId}.`,
);
}
}
+59 -5
View File
@@ -1,7 +1,18 @@
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
import { PLATFORM_ROUTE_REGISTRY } from "../../src/contracts/routes.ts";
import { TECH_LOG_ROUTE_REGISTRY } from "../../src/features/tech-log/contracts/tech-log-route-contract.ts";
/**
* Template sync (af3d8e6). The routes this product mounts: the platform's and
* TechLog's, the same set `AppRouter` composes. Read from those registries
* rather than the installed composition so the CI contract parser
* (scripts/contracts/ci-gates.ts), which pins FE-GATE-028 to this scope, does
* not depend on the generated feature index; `check:ci` has to stay the
* template's canonical command.
*/
export const MANUAL_A11Y_ROUTE_IDS = Object.freeze(
Object.values(ROUTE_REGISTRY).map((route) => route.routeId),
Object.values({ ...PLATFORM_ROUTE_REGISTRY, ...TECH_LOG_ROUTE_REGISTRY }).map(
(route) => route.routeId,
),
);
const REVIEW_FIELDS = Object.freeze([
@@ -15,8 +26,20 @@ const REVIEW_FIELDS = Object.freeze([
"Screen reader",
]);
export function validateManualA11yEvidence(content: string) {
const fields = Object.fromEntries(
const IDENTITY_FIELDS = Object.freeze([
"Status",
"Route ID",
"Release ID",
"Reviewer",
"Reviewed at",
"Signature",
"Attestation",
]);
const NOT_APPLICABLE = /^not-applicable \(.+\)$/;
function parseRecordFields(content: string): Record<string, string> {
return Object.fromEntries(
content
.split(/\r?\n/)
.map((line) => /^([^:]+):\s*(.*)$/.exec(line))
@@ -26,6 +49,37 @@ export function validateManualA11yEvidence(content: string) {
match[2].trim(),
]),
);
}
/**
* 08-06. The merge-stage check: the record for `routeId` keeps the template's
* fields and vocabulary, whether or not a human has reviewed it yet. A record
* that claims `reviewed` must also be complete. Returns the offending fields.
*/
export function validateManualA11yRecordFormat(content: string, routeId: string): string[] {
const fields = parseRecordFields(content);
const failures = [...IDENTITY_FIELDS, ...REVIEW_FIELDS].filter(
(field) => !(field in fields),
);
if (fields.Status !== undefined && !["pending-manual-review", "reviewed"].includes(fields.Status)) {
failures.push("Status");
}
if (fields["Route ID"] !== undefined && fields["Route ID"] !== routeId) failures.push("Route ID");
if (fields.Attestation !== undefined && !["pending", "accepted"].includes(fields.Attestation)) {
failures.push("Attestation");
}
for (const field of REVIEW_FIELDS) {
const verdict = fields[field];
if (verdict !== undefined && verdict !== "pass" && verdict !== "pending" && !NOT_APPLICABLE.test(verdict)) {
failures.push(field);
}
}
if (fields.Status === "reviewed") failures.push(...validateManualA11yEvidence(content).failures);
return [...new Set(failures)];
}
export function validateManualA11yEvidence(content: string) {
const fields = parseRecordFields(content);
const failures: string[] = [];
if (fields.Status !== "reviewed") failures.push("Status");
if (!fields["Route ID"]) failures.push("Route ID");
@@ -44,7 +98,7 @@ export function validateManualA11yEvidence(content: string) {
const result = fields[field];
if (
result !== "pass" &&
!/^not-applicable \(.+\)$/.test(result ?? "")
!NOT_APPLICABLE.test(result ?? "")
) {
failures.push(field);
}
+31
View File
@@ -1,3 +1,18 @@
/**
* Package-script graph for the CI contract (D-12, 12-10). Kept after checking
* whether `--ignore-scripts` on the workflow install and `allowBuilds` in
* pnpm-workspace.yaml already close the same risks. They do not:
*
* - Gate commands run installs themselves (`verify:lockfile`, removal
* fixtures). `allowBuilds` limits dependency build scripts under pnpm only;
* the root project's own install hooks and npm/yarn installs still run
* unless the command says `--ignore-scripts`.
* - A gate names a root package script. `--prefix`, `--filter`, `-C`, npm
* pre/post hooks and `npm_config_*` scope variables can make that name run a
* different manifest's script, which no install flag affects.
* - `reachablePackageScripts` is also how the ungated-test check (12-04) finds
* which Vitest paths a gate runs.
*/
type PackageManager = "pnpm" | "npm" | "yarn";
type ManagerParseResult = Readonly<{
@@ -182,6 +197,22 @@ export function validatePackageScriptGraph(
return [...new Set(failures)];
}
/** Every package script reachable from the entries through manager calls. */
export function reachablePackageScripts(
scripts: Readonly<Record<string, string>>,
entryScripts: readonly string[],
): string[] {
const visited = new Set<string>();
const visit = (scriptName: string): void => {
const command = scripts[scriptName];
if (visited.has(scriptName) || command === undefined) return;
visited.add(scriptName);
for (const dependency of parseManagerCommands(command, scripts).dependencies) visit(dependency);
};
for (const entryScript of entryScripts) visit(entryScript);
return [...visited];
}
export function validateInstallScriptPolicy(
scripts: Readonly<Record<string, string>>,
entryScripts: readonly string[],
+118
View File
@@ -0,0 +1,118 @@
export type BundleMeasurements = Readonly<{
initialJsGzipBytes: number;
lazyChunks: readonly Readonly<{ path: string; gzipBytes: number }>[];
}>;
export type BundleThresholds = Readonly<{
initialJsGzipBytes: number;
lazyChunkGzipBytes: number;
}>;
export function evaluateBundleBudget(
measurements: BundleMeasurements,
thresholds: BundleThresholds,
) {
const initialPassed =
measurements.initialJsGzipBytes <= thresholds.initialJsGzipBytes;
const lazyResults = measurements.lazyChunks.map((chunk) => ({
...chunk,
threshold: thresholds.lazyChunkGzipBytes,
passed: chunk.gzipBytes <= thresholds.lazyChunkGzipBytes,
}));
return Object.freeze({
initialPassed,
lazyResults: Object.freeze(lazyResults),
passed: initialPassed && lazyResults.every((chunk) => chunk.passed),
});
}
export type LabMetrics = Readonly<{
lcpMs: number;
cls: number;
namedInteractionMs: number;
}>;
export function evaluateLabBudget(
report: Readonly<{
context?: Readonly<Record<string, unknown>>;
metrics: LabMetrics;
}>,
thresholds: LabMetrics,
) {
const requiredContext = [
"runner",
"browser",
"viewport",
"network",
"cpu",
"cache",
"build",
];
const missingContext = requiredContext.filter(
(field) => report.context?.[field] === undefined,
);
const results = {
lcp: report.metrics.lcpMs <= thresholds.lcpMs,
cls: report.metrics.cls <= thresholds.cls,
namedInteraction:
report.metrics.namedInteractionMs <= thresholds.namedInteractionMs,
};
return Object.freeze({
missingContext: Object.freeze(missingContext),
results: Object.freeze(results),
passed: missingContext.length === 0 && Object.values(results).every(Boolean),
});
}
export function percentile75(values: readonly number[]): number | null {
if (values.length === 0) return null;
const sorted = [...values].sort((left, right) => left - right);
return sorted[Math.ceil(sorted.length * 0.75) - 1];
}
export type FieldMetrics = Readonly<{
p75LcpMs: number | null;
p75Cls: number | null;
p75InpMs: number | null;
}>;
export type FieldThresholds = Readonly<{
p75LcpMs: number;
p75Cls: number;
p75InpMs: number;
minimumEligibleSamples: number | null;
}>;
export type FieldBudgetResult = Readonly<{
status: "PASS" | "FAIL_THRESHOLD" | "FAIL_UNVERIFIED";
passed: boolean;
}>;
export function evaluateFieldBudget(
report: Readonly<{ metrics: FieldMetrics; eligibleSamples: number }>,
thresholds: FieldThresholds,
): FieldBudgetResult {
if (
thresholds.minimumEligibleSamples === null ||
report.eligibleSamples < thresholds.minimumEligibleSamples ||
Object.values(report.metrics).some((value) => value === null)
) {
return Object.freeze({
status: "FAIL_UNVERIFIED",
passed: false,
});
}
const metrics = report.metrics as Readonly<{
p75LcpMs: number;
p75Cls: number;
p75InpMs: number;
}>;
const passed =
metrics.p75LcpMs <= thresholds.p75LcpMs &&
metrics.p75Cls <= thresholds.p75Cls &&
metrics.p75InpMs <= thresholds.p75InpMs;
return Object.freeze({
status: passed ? "PASS" : "FAIL_THRESHOLD",
passed,
});
}
+68
View File
@@ -0,0 +1,68 @@
export const PROMOTION_FORMULA = Object.freeze({
MERGE_READY: Object.freeze([
"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-013",
"FE-GATE-020",
]),
RELEASE_READY: Object.freeze([
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-015",
"FE-GATE-026",
// FE-GATE-027. A candidate is only release-ready once it has been admitted
// to a named environment; coherence alone never proved it belonged there.
"FE-GATE-027",
// FE-GATE-028 (08-06). The signed human accessibility review belongs to a
// release candidate, so it gates release; merge checks the record format.
"FE-GATE-028",
]),
PROD_PROMOTION_READY: Object.freeze([
// FE-GATE-019 (13-05, D-14). Live hosting headers of the deployed promoted
// release; the declared-header fixture alone is UNVERIFIED, not PASS.
"FE-GATE-019",
// FE-GATE-016 is retired (D-14): it repeated FE-GATE-025's FE-RB-005 drill.
"FE-GATE-021",
"FE-GATE-022",
"FE-GATE-023",
"FE-GATE-024",
"FE-GATE-025",
]),
FIELD_SLO_READY: Object.freeze(["FE-GATE-018"]),
DOCUMENTATION_READY: Object.freeze(["FE-GATE-017"]),
});
export type GateResult = "PASS" | "FAIL" | "UNVERIFIED";
export function evaluatePromotionReadiness(
gateResults: Readonly<Record<string, GateResult>>,
) {
const allPass = (gateIds: readonly string[]) =>
gateIds.every((gateId) => gateResults[gateId] === "PASS");
const mergeReady = allPass(PROMOTION_FORMULA.MERGE_READY);
const releaseReady =
mergeReady && allPass(PROMOTION_FORMULA.RELEASE_READY);
const productionReady =
releaseReady && allPass(PROMOTION_FORMULA.PROD_PROMOTION_READY);
const fieldReady =
productionReady && allPass(PROMOTION_FORMULA.FIELD_SLO_READY);
const documentationReady = allPass(PROMOTION_FORMULA.DOCUMENTATION_READY);
return Object.freeze({
MERGE_READY: mergeReady,
RELEASE_READY: releaseReady,
PROD_PROMOTION_READY: productionReady,
FIELD_SLO_READY: fieldReady,
DOCUMENTATION_READY: documentationReady,
});
}
+4 -12
View File
@@ -1,10 +1,12 @@
import { readFile, readdir } from "node:fs/promises";
import path from "node:path";
// Importing the realtime or Web Push adapter from the composition root is the
// graph rule unselected-realtime-runtime-is-not-composed (12-10). This scan
// keeps what an import graph cannot see: native API calls and timers.
export type RealtimeBoundaryRuleId =
| "NATIVE_REALTIME_API_OUTSIDE_ADAPTER"
| "PRESENTATION_INTERVAL_OWNER"
| "UNSELECTED_REALTIME_RUNTIME_COMPOSED";
| "PRESENTATION_INTERVAL_OWNER";
export type RealtimeBoundaryViolation = Readonly<{
ruleId: RealtimeBoundaryRuleId;
@@ -17,8 +19,6 @@ const OWNED_NATIVE_ROOTS = [
"src/adapters/realtime/",
"src/adapters/web-push/",
] as const;
const REALTIME_ADAPTER_IMPORT =
/(?:from\s*|import\s*\()\s*["'][^"']*\/adapters\/(?:realtime|web-push)(?:\/[^"']*)?["']/gu;
const NATIVE_REALTIME_PATTERNS = [
/\bnew\s+(?:WebSocket|EventSource|Notification)\s*\(/gu,
/\bNotification\s*\.\s*requestPermission\s*\(/gu,
@@ -62,9 +62,6 @@ function inspectFile(
const presentationOwned =
logicalFile.startsWith("src/presentation/") ||
/^src\/features\/[^/]+\/presentation\//u.test(logicalFile);
const compositionBoundary =
logicalFile.startsWith("src/bootstrap/") ||
/^src\/features\/installed-feature-/u.test(logicalFile);
const report = (
ruleId: RealtimeBoundaryRuleId,
@@ -92,11 +89,6 @@ function inspectFile(
report("PRESENTATION_INTERVAL_OWNER", match.index);
}
}
if (compositionBoundary) {
for (const match of source.matchAll(REALTIME_ADAPTER_IMPORT)) {
report("UNSELECTED_REALTIME_RUNTIME_COMPOSED", match.index);
}
}
}
async function collectSourceFiles(
+88 -8
View File
@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
import {
cp,
mkdir,
mkdtemp,
readFile,
readdir,
rm,
@@ -14,8 +15,12 @@ import {
loadCiGateContract,
parseCiGateContract,
} from "../contracts/ci-gates.ts";
import { linkFixtureNodeModules } from "./fixture-node-modules.ts";
import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "./fixture-node-modules.ts";
import { generateCiWorkflow } from "../generate-ci-workflow.ts";
import { updateCiContractBaseline } from "../update-ci-contract-baseline.ts";
export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
"src", "tests", "recipes", "scripts", "schemas", "config", "public",
@@ -159,16 +164,89 @@ function runFixtureGit(root: string, argv: readonly string[]): void {
}
}
/**
* 14-08. A fresh fixture directory per run: two runs, or a run after one that
* crashed, no longer share (and overwrite) one fixed path. Callers remove it
* in `finally`.
*/
export async function createRemovalFixtureRoot(name: string): Promise<string> {
const parent = path.resolve(".tmp");
await mkdir(parent, { recursive: true });
return mkdtemp(path.join(parent, `${name}-`));
}
export type RemovalCheck = Readonly<{
name: string;
passed: boolean;
/** Why this check failed; each check names its own cause. */
failure?: string;
}>;
export function runRemovalFixtureCheck(
name: string,
root: string,
pnpmCli: string,
script: string,
extra: readonly string[] = [],
): RemovalCheck {
const status = spawnSync(process.execPath, [pnpmCli, script, ...extra], {
cwd: root,
stdio: "inherit",
env: { ...process.env, ...FIXTURE_PNPM_ENVIRONMENT },
}).status;
return status === 0
? { name, passed: true }
: {
name,
passed: false,
failure: `corepack pnpm ${[script, ...extra].join(" ")} exited ${status ?? "on a signal"}`,
};
}
function escapeXml(value: string): string {
return value
.replaceAll("&", "&amp;")
.replaceAll("<", "&lt;")
.replaceAll(">", "&gt;")
.replaceAll('"', "&quot;");
}
/**
* 14-08. The report used to say `failures="1"` whatever failed, and put the
* residue list into every failed testcase, so a type error read as residue.
*/
export function renderRemovalJunit(
suite: string,
checks: readonly RemovalCheck[],
): string {
const failures = checks.filter((check) => !check.passed).length;
const cases = checks
.map((check) =>
`<testcase name="${escapeXml(check.name)}">${
check.passed
? ""
: `<failure message="${escapeXml(check.failure ?? "failed")}" />`
}</testcase>`,
)
.join("");
return (
`<?xml version="1.0" encoding="UTF-8"?>\n` +
`<testsuite name="${escapeXml(suite)}" tests="${checks.length}" failures="${failures}">` +
`${cases}</testsuite>\n`
);
}
export function runRemovalFixturePnpm(
root: string,
pnpmCli: string,
script: string,
extra: readonly string[] = [],
env: Readonly<Record<string, string>> = {},
): boolean {
return spawnSync(process.execPath, [pnpmCli, script, ...extra], {
cwd: root,
stdio: "inherit",
env: { ...process.env, CI_CONTRACT_MODE: "removal-fixture" },
env: { ...process.env, ...FIXTURE_PNPM_ENVIRONMENT, ...env },
}).status === 0;
}
@@ -274,7 +352,7 @@ export function pruneScriptOrchestration(
}
export async function regenerateRemovalFixtureWorkflow(root: string): Promise<void> {
const contract = await loadCiGateContract(root, { mode: "removal-fixture" });
const contract = await loadCiGateContract(root);
await generateCiWorkflow({ root, contract, check: false });
// Every removal script calls this once, after it has finished mutating the
// tree, so it is the one place where the fixture's contents are final.
@@ -328,10 +406,6 @@ export async function pruneRemovalFixtureCiContract(options: Readonly<{
scripts: Record<string, string>;
};
for (const script of options.removedScripts) delete packageDocument.scripts[script];
packageDocument.scripts["check:ci-workflow"] =
"node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture";
packageDocument.scripts["check:ci"] =
"corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts --reduced-removal-fixture && corepack pnpm check:ci-workflow";
const contract = structuredClone(
parseCiGateContract(JSON.parse(await readFile(gatesPath, "utf8"))),
@@ -384,9 +458,15 @@ export async function pruneRemovalFixtureCiContract(options: Readonly<{
contract.artifactSchemas = contract.artifactSchemas.filter(({ id }) =>
referencedSchemaIds.has(id)
);
const validated = parseCiGateContract(contract, { mode: "removal-fixture" });
const validated = parseCiGateContract(contract);
await Promise.all([
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.
await updateCiContractBaseline(options.root, {
owner: "removal-fixture",
reason: `removal fixture pruned ${[...options.removedScripts].join(", ")}`,
});
}
@@ -0,0 +1,17 @@
/**
* 06-03 (D-5). The emergency exit for a worker that stops the page from
* booting. A `REMOVE_REGISTRATION` release writes this as `service-worker.js`.
* The browser's own update check (navigation, `updateViaCache: "none"`) then
* installs it over any worker of this scope without a page: it skips waiting,
* and on activation unregisters the registration. It has no fetch handler, so
* every request goes to the network. Owned caches stay for the
* `PURGE_OWNED_RESOURCES` release, as with the page-side removal.
*/
export const SELF_UNREGISTERING_SERVICE_WORKER = `// Generated by scripts/build-frontend.ts (REMOVE_REGISTRATION).
self.addEventListener("install", (event) => {
event.waitUntil(self.skipWaiting());
});
self.addEventListener("activate", (event) => {
event.waitUntil(self.registration.unregister());
});
`;
+11 -1
View File
@@ -29,7 +29,10 @@ export function resolveServiceWorkerBuildInput(input: Readonly<{
selection: InstalledServiceWorkerSelection | null;
assets: unknown;
contractSet: unknown;
/** `dist/config.json`, materialized from the build's profile (06-10). */
runtimeConfig: unknown;
/** The build's `APP_PROFILE`; the runtime document must be for it. */
appProfile: string;
buildId: string;
releaseId: string;
}>): ServiceWorkerBuildInput {
@@ -70,7 +73,14 @@ export function resolveServiceWorkerBuildInput(input: Readonly<{
throw new TypeError("Generated contract set digest is invalid.");
}
const runtimeConfig = record(input.runtimeConfig);
const releaseManifestUrl = runtimeConfig?.RELEASE_MANIFEST_URL;
// 06-10 / F-8. `public/config.json` is the local profile; a worker built from
// it for another profile would carry that profile's URLs.
if (runtimeConfig?.APP_ENV !== input.appProfile) {
throw new TypeError(
`Service Worker runtime config APP_ENV ${String(runtimeConfig?.APP_ENV)} does not match APP_PROFILE ${input.appProfile}.`,
);
}
const releaseManifestUrl = runtimeConfig.RELEASE_MANIFEST_URL;
if (
typeof releaseManifestUrl !== "string" ||
releaseManifestUrl.length === 0 ||
+76
View File
@@ -0,0 +1,76 @@
import { z } from "zod";
import { reachablePackageScripts } from "./package-script-graph.ts";
/**
* 12-04. A verification package script protects nothing unless a CI gate runs
* it. `ungated-tests.ts` covers test files; this covers the scripts. A script
* of a verification family is gated when a gate command reaches it through
* the package script graph, or when it only re-runs Vitest paths a gate
* already runs. Anything else needs a reasoned entry in
* config/ci/ungated-scripts.json.
*/
export const UNGATED_SCRIPTS_PATH = "config/ci/ungated-scripts.json";
const VERIFICATION_SCRIPT = /^(?:check|verify|test|drill|review):/u;
const ungatedScriptsSchema = z
.object({
schemaVersion: z.literal(1),
entries: z.array(
z
.object({
script: z.string().regex(VERIFICATION_SCRIPT),
reason: z.string().trim().min(1, "exclusion reason is required"),
})
.strict(),
),
})
.strict();
export type UngatedScriptExclusion = Readonly<{ script: string; reason: string }>;
export function parseUngatedScriptExclusions(value: unknown): readonly UngatedScriptExclusion[] {
return ungatedScriptsSchema.parse(value).entries;
}
/** Every segment is a Vitest run whose paths all lie inside gated paths. */
function rerunsGatedTests(command: string, gatedTestPaths: readonly string[]): boolean {
const gated = (target: string) =>
gatedTestPaths.some((gatedPath) => target === gatedPath || target.startsWith(`${gatedPath}/`));
return command.split("&&").every((segment) => {
const tokens = segment.trim().split(/\s+/u);
const run = tokens.findIndex(
(token, index) => token === "run" && /(?:run-vitest\.ts|vitest)$/u.test(tokens[index - 1] ?? ""),
);
if (run < 0) return false;
const paths = tokens.slice(run + 1).filter((token) => !token.startsWith("-"));
return paths.length > 0 && paths.every((target) => gated(target.replace(/\/$/u, "")));
});
}
export function ungatedScriptFailures(input: Readonly<{
scripts: Readonly<Record<string, string>>;
entryScripts: readonly string[];
gatedTestPaths: readonly string[];
exclusions: readonly UngatedScriptExclusion[];
}>): string[] {
const reached = new Set(reachablePackageScripts(input.scripts, input.entryScripts));
const gated = (script: string) =>
reached.has(script) || rerunsGatedTests(input.scripts[script] ?? "", input.gatedTestPaths);
const excluded = new Set(input.exclusions.map(({ script }) => script));
const failures = Object.keys(input.scripts)
.filter((script) => VERIFICATION_SCRIPT.test(script) && !gated(script) && !excluded.has(script))
.sort()
.map((script) =>
`verification script is not reached by any CI gate command and is not in ${UNGATED_SCRIPTS_PATH}: ${script}`
);
// An entry for a script a removal deleted is harmless; one for a script a
// gate now reaches would hide the next regression, so it has to go.
for (const { script } of input.exclusions) {
if (input.scripts[script] !== undefined && gated(script)) {
failures.push(`ungated script exclusion is stale; a CI gate reaches it: ${script}`);
}
}
return failures;
}
+108
View File
@@ -0,0 +1,108 @@
import { readdir } from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
import { SCALE_TIERS, type ScaleTier } from "../scale/run-scale-profile.ts";
import { reachablePackageScripts } from "./package-script-graph.ts";
/**
* 12-04. A test file protects nothing unless a CI gate runs it. The gated set
* is read from the package scripts the CI contract's commands reach: Vitest
* path filters (`run-vitest.ts run <paths>`), the Vitest steps of a scale tier
* (`run-scale-profile.ts <tier>`) and Playwright config `testDir`s.
* A test outside that set needs a reasoned entry in config/ci/ungated-tests.json.
*/
export const UNGATED_TESTS_PATH = "config/ci/ungated-tests.json";
const TEST_FILE = /\.(?:test|spec)\.tsx?$/u;
const ungatedTestsSchema = z
.object({
schemaVersion: z.literal(1),
entries: z.array(
z
.object({
path: z.string().regex(/^tests\/\S+$/u),
reason: z.string().trim().min(1, "exclusion reason is required"),
})
.strict(),
),
})
.strict();
export type UngatedTestExclusion = Readonly<{ path: string; reason: string }>;
export function parseUngatedTestExclusions(value: unknown): readonly UngatedTestExclusion[] {
return ungatedTestsSchema.parse(value).entries;
}
/** Repository-relative test files below tests/, fixtures excluded. */
export async function listTestFiles(root: string): Promise<string[]> {
const entries = await readdir(path.join(root, "tests"), { recursive: true, withFileTypes: true });
return entries
.filter((entry) => entry.isFile() && TEST_FILE.test(entry.name))
.map((entry) =>
path.relative(root, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"),
)
.filter((file) => !file.startsWith("tests/fixtures/"))
.sort();
}
export function gatedTestPaths(
scripts: Readonly<Record<string, string>>,
entryScripts: readonly string[],
readConfig: (file: string) => string,
): string[] {
const paths = new Set<string>();
const addVitestPaths = (tokens: readonly string[]) => {
const vitestRun = tokens.findIndex(
(token, index) => token === "run" && /(?:run-vitest\.ts|vitest)$/u.test(tokens[index - 1] ?? ""),
);
if (vitestRun < 0) return;
for (const token of tokens.slice(vitestRun + 1)) {
if (!token.startsWith("-")) paths.add(token.replace(/\/$/u, ""));
}
};
for (const script of reachablePackageScripts(scripts, entryScripts)) {
for (const segment of scripts[script]!.split("&&")) {
const tokens = segment.trim().split(/\s+/u);
addVitestPaths(tokens);
const scaleProfile = tokens.findIndex((token) => /run-scale-profile\.ts$/u.test(token));
if (scaleProfile >= 0) {
for (const step of SCALE_TIERS[tokens[scaleProfile + 1] as ScaleTier] ?? []) addVitestPaths(step.command);
}
const playwrightTest = tokens.findIndex(
(token, index) => token === "test" && tokens[index - 1] === "playwright",
);
if (playwrightTest >= 0) {
const configFlag = tokens.indexOf("--config");
const config = configFlag >= 0 ? tokens[configFlag + 1]! : "playwright.config.ts";
const testDir = /testDir:\s*["']\.?\/?([^"']+)["']/u.exec(readConfig(config))?.[1];
if (testDir) paths.add(testDir.replace(/\/$/u, ""));
}
}
}
return [...paths].sort();
}
export function ungatedTestFailures(input: Readonly<{
testFiles: readonly string[];
gatedPaths: readonly string[];
exclusions: readonly UngatedTestExclusion[];
}>): string[] {
const gated = (file: string) =>
input.gatedPaths.some((gatedPath) => file === gatedPath || file.startsWith(`${gatedPath}/`));
const excluded = new Set(input.exclusions.map(({ path: file }) => file));
const failures = input.testFiles
.filter((file) => !gated(file) && !excluded.has(file))
.map((file) =>
`test file is not run by any CI gate command and is not in ${UNGATED_TESTS_PATH}: ${file}`
);
// An entry for a file a removal deleted is harmless; one for a file a gate
// now runs would hide the next regression, so it has to go.
for (const { path: file } of input.exclusions) {
if (gated(file)) failures.push(`ungated test exclusion is stale; a CI gate runs it: ${file}`);
}
return failures;
}
+49 -1
View File
@@ -1,3 +1,4 @@
import { readFileSync } from "node:fs";
import path from "node:path";
import type { Plugin } from "vite";
@@ -39,6 +40,7 @@ export function viteModuleInventoryPlugin(
{
schemaVersion: 1,
chunks,
packages: bundledPackages(chunks),
},
null,
2,
@@ -48,7 +50,41 @@ export function viteModuleInventoryPlugin(
};
}
function normalizeModuleId(
/**
* 13-12. The `name@version` of every package with at least one module in the
* emitted bundle: what the public release actually ships, as opposed to the
* SBOM, which lists the whole installed graph.
*/
export function bundledPackages(chunks: readonly ModuleInventoryChunk[]): string[] {
const packages = new Set<string>();
for (const chunk of chunks) {
for (const module of chunk.modules) {
const match = /^npm:((?:@[^/]+\/)?[^/@]+@[^/]+)\//u.exec(module);
if (match?.[1]) packages.add(match[1]);
}
}
return [...packages].sort();
}
const packageManifests = new Map<string, Readonly<{ name: string; version: string }>>();
function installedPackage(directory: string): Readonly<{ name: string; version: string }> {
let manifest = packageManifests.get(directory);
if (!manifest) {
const parsed = JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8")) as {
name?: unknown;
version?: unknown;
};
if (typeof parsed.name !== "string" || typeof parsed.version !== "string") {
throw new TypeError(`bundled package has no name/version: ${directory}`);
}
manifest = Object.freeze({ name: parsed.name, version: parsed.version });
packageManifests.set(directory, manifest);
}
return manifest;
}
export function normalizeModuleId(
moduleId: string,
repositoryRoot: string,
): string {
@@ -56,6 +92,18 @@ function normalizeModuleId(
if (!path.isAbsolute(withoutQuery)) {
return withoutQuery.replaceAll("\\", "/");
}
// 13-12: a dependency module keeps its package identity, read from the
// package.json of the directory it was resolved into.
const file = withoutQuery.replaceAll("\\", "/");
const marker = "/node_modules/";
const at = file.lastIndexOf(marker);
if (at >= 0) {
const segments = file.slice(at + marker.length).split("/");
const nameLength = segments[0]?.startsWith("@") ? 2 : 1;
const directory = file.slice(0, at + marker.length) + segments.slice(0, nameLength).join("/");
const { name, version } = installedPackage(directory);
return `npm:${name}@${version}/${segments.slice(nameLength).join("/")}`;
}
const relative = path.relative(repositoryRoot, withoutQuery);
return relative.startsWith("..")
? `external:${path.basename(withoutQuery)}`
+12
View File
@@ -47,6 +47,18 @@ for (const key of [
delete testEnvironment[key];
}
// src/.generated is gitignored; every suite imports the product index, so a
// fresh checkout must render it before Vitest resolves the module graph.
const generated = spawnSync(
process.execPath,
[fileURLToPath(new URL("./generate-product-feature-index.ts", import.meta.url))],
{ stdio: "inherit", env: testEnvironment },
);
if (generated.status !== 0) {
process.stderr.write("Product feature index generation failed.\n");
process.exit(generated.status ?? 1);
}
const result = spawnSync(
process.execPath,
[vitestEntry, ...process.argv.slice(2)],
+69
View File
@@ -0,0 +1,69 @@
import { mkdir, writeFile } from "node:fs/promises";
import { dirname } from "node:path";
/**
* Spec §48. Machine-readable benchmark result.
*/
export type BenchmarkProfile = "S0" | "S1" | "S2" | "S3" | "S4";
export interface BenchmarkResult {
readonly name: string;
readonly profile: BenchmarkProfile;
readonly cardinality: number;
readonly samples: readonly number[];
readonly medianMs: number;
readonly heapBytes?: number;
readonly metadata: Readonly<Record<string, string | number | boolean>>;
}
export type BenchmarkArtifact = Readonly<{
schemaVersion: 1;
suite: string;
generatedAt: string;
node: string;
passed: boolean;
results: readonly BenchmarkResult[];
checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[];
}>;
const PROFILES: ReadonlySet<string> = new Set(["S0", "S1", "S2", "S3", "S4"]);
export function median(values: readonly number[]): number {
if (values.length === 0) throw new TypeError("median of an empty series");
const sorted = [...values].sort((left, right) => left - right);
const middle = Math.floor(sorted.length / 2);
return sorted.length % 2 === 1
? (sorted[middle] as number)
: ((sorted[middle - 1] as number) + (sorted[middle] as number)) / 2;
}
export function assertBenchmarkResult(value: BenchmarkResult): BenchmarkResult {
if (typeof value.name !== "string" || value.name.length === 0) {
throw new TypeError("benchmark name required");
}
if (!PROFILES.has(value.profile)) {
throw new TypeError(`unknown benchmark profile ${String(value.profile)}`);
}
if (!Number.isSafeInteger(value.cardinality) || value.cardinality < 0) {
throw new TypeError("benchmark cardinality must be a non-negative integer");
}
if (
value.samples.length === 0 ||
value.samples.some((sample) => !Number.isFinite(sample) || sample < 0)
) {
throw new TypeError("benchmark samples must be finite non-negative numbers");
}
if (value.medianMs !== median(value.samples)) {
throw new TypeError("benchmark medianMs must be the median of its samples");
}
return value;
}
export async function writeBenchmarkArtifact(
path: string,
artifact: BenchmarkArtifact,
): Promise<void> {
for (const result of artifact.results) assertBenchmarkResult(result);
await mkdir(dirname(path), { recursive: true });
await writeFile(path, `${JSON.stringify(artifact, null, 2)}\n`);
}
+64
View File
@@ -0,0 +1,64 @@
import { performance } from "node:perf_hooks";
import {
assertBenchmarkResult,
median,
type BenchmarkProfile,
type BenchmarkResult,
} from "./benchmark-result.ts";
/**
* Spec §49. Repeated samples with a median, so one noisy scheduler slice can
* neither fail a linear implementation nor hide a slow one.
*
* `run` either does the work (and is timed here) or returns a duration it
* measured itself, which lets tests inject exact durations.
*/
export type BenchmarkOptions = Readonly<{
samples: number;
warmup?: number;
profile?: BenchmarkProfile;
cardinality?: number;
metadata?: Readonly<Record<string, string | number | boolean>>;
measureHeap?: boolean;
run: () => unknown;
}>;
function heapUsed(): number {
return process.memoryUsage().heapUsed;
}
export async function benchmark(
name: string,
options: BenchmarkOptions,
): Promise<BenchmarkResult> {
if (!Number.isSafeInteger(options.samples) || options.samples < 1) {
throw new TypeError("benchmark samples must be a positive integer");
}
for (let index = 0; index < (options.warmup ?? 0); index += 1) {
await options.run();
}
const samples: number[] = [];
let peakHeapDelta = 0;
for (let index = 0; index < options.samples; index += 1) {
const heapBefore = options.measureHeap ? heapUsed() : 0;
const startedAt = performance.now();
const reported = await options.run();
const elapsed = performance.now() - startedAt;
if (options.measureHeap) {
peakHeapDelta = Math.max(peakHeapDelta, heapUsed() - heapBefore);
}
samples.push(typeof reported === "number" && Number.isFinite(reported) ? reported : elapsed);
}
return assertBenchmarkResult(
Object.freeze({
name,
profile: options.profile ?? "S0",
cardinality: options.cardinality ?? 0,
samples: Object.freeze(samples),
medianMs: median(samples),
...(options.measureHeap ? { heapBytes: Math.max(0, peakHeapDelta) } : {}),
metadata: Object.freeze({ ...(options.metadata ?? {}) }),
}),
);
}
+554
View File
@@ -0,0 +1,554 @@
import { createReadStream } from "node:fs";
import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
import { createServer, type Server } from "node:http";
import type { AddressInfo } from "node:net";
import path from "node:path";
import {
classifyCounterSeries,
classifyMemorySlope,
type MemorySlopeClass,
} from "./memory-slope.ts";
/**
* Spec §33 / §44. Browser soak on the existing Playwright runner.
*
* Serves the built `dist/` on an OS-assigned 127.0.0.1 port and keeps one
* long-lived page cycling through the app's routes by client-side navigation.
* The served runtime config turns telemetry on (pointed at a local collector)
* and points the API at a stub that always answers 503, so every cycle also
* exercises bounded retries and telemetry under a sustained backend failure.
*
* Collected per sample: JS heap, DOM nodes, event listeners, live timers,
* in-flight fetches, Web Storage size. Collected overall: cycles, navigation
* failures, API requests, telemetry POSTs/events. Without a build or browser
* the result is `skipped` (never a pass); too little evidence fails.
*/
export type SoakSample = Readonly<{
elapsedMs: number;
cycles: number;
heapBytes: number;
domNodes: number;
listeners: number;
activeTimers: number;
inFlightRequests: number;
storageKeys: number;
storageBytes: number;
}>;
export type SoakSummary = Readonly<{
cycles: number;
navigationFailures: number;
maxHeapBytes: number;
heapClassification: MemorySlopeClass;
listenerDelta: number;
listenerClassification: MemorySlopeClass;
timerDelta: number;
maxActiveTimers: number;
domNodeDelta: number;
maxInFlightRequests: number;
finalInFlightRequests: number;
storageKeyDelta: number;
storageByteDelta: number;
apiRequests: number;
referenceVisits: number;
settledReferenceVisits: number;
apiRequestsPerReferenceVisit: number;
telemetryPosts: number;
telemetryEvents: number;
maxTelemetryPostsPerMinute: number;
}>;
export type SoakCheck = Readonly<{ name: string; passed: boolean; detail: string }>;
export type SoakArtifact = Readonly<{
schemaVersion: 2;
status: "passed" | "failed" | "skipped";
reason?: string;
durationMs: number;
classification?: MemorySlopeClass;
summary?: SoakSummary;
checks?: readonly SoakCheck[];
/** Identity of the soaked build (from dist/release-manifest.json). */
build?: Readonly<{ buildId?: string; releaseId?: string; builtAt?: string }>;
browser?: string;
samples: readonly SoakSample[];
}>;
/** Thresholds a soak must meet; each is checked and recorded by name. */
export const SOAK_LIMITS = Object.freeze({
minCycles: 200,
minPostWarmupSamples: 3,
maxListenerDelta: 50,
maxTimerDelta: 10,
maxStorageKeyDelta: 2,
/** One logical execution: 1 attempt + at most 2 retries. */
maxApiRequestsPerReferenceVisit: 3,
/** Two bounded pipelines (platform events + feature events) x 20/min. */
maxTelemetryPostsPerMinute: 40,
});
export function summarizeSoak(
samples: readonly Pick<SoakSample, "elapsedMs" | "heapBytes">[],
warmupMs: number,
): MemorySlopeClass {
return classifyMemorySlope(
samples.map((sample) => ({
minute: sample.elapsedMs / 60_000,
heapMb: sample.heapBytes / (1024 * 1024),
})),
{ warmupMinutes: warmupMs / 60_000, maxSlopeMbPerMinute: 1, maxRelativeGrowth: 0.2 },
);
}
export type SoakTotals = Readonly<{
cycles: number;
navigationFailures: number;
referenceVisits: number;
settledReferenceVisits: number;
finalInFlightRequests: number;
apiRequests: number;
telemetryPosts: number;
telemetryEvents: number;
telemetryPostTimes: readonly number[];
}>;
export function evaluateSoak(
samples: readonly SoakSample[],
totals: SoakTotals,
warmupMs: number,
): Readonly<{ summary: SoakSummary; checks: readonly SoakCheck[] }> {
const measured = samples.filter((sample) => sample.elapsedMs >= warmupMs);
const first = measured[0];
const last = measured[measured.length - 1];
const delta = (pick: (sample: SoakSample) => number) =>
first && last ? pick(last) - pick(first) : 0;
let maxTelemetryPostsPerMinute = 0;
for (const time of totals.telemetryPostTimes) {
const inWindow = totals.telemetryPostTimes.filter(
(other) => other >= time && other < time + 60_000,
).length;
maxTelemetryPostsPerMinute = Math.max(maxTelemetryPostsPerMinute, inWindow);
}
const summary: SoakSummary = {
cycles: totals.cycles,
navigationFailures: totals.navigationFailures,
maxHeapBytes: Math.max(0, ...samples.map((sample) => sample.heapBytes)),
heapClassification: summarizeSoak(samples, warmupMs),
listenerDelta: delta((sample) => sample.listeners),
listenerClassification: classifyCounterSeries(
measured.map((sample) => sample.listeners),
{ maxSlopePerSample: 1 },
),
timerDelta: delta((sample) => sample.activeTimers),
maxActiveTimers: Math.max(0, ...samples.map((sample) => sample.activeTimers)),
domNodeDelta: delta((sample) => sample.domNodes),
maxInFlightRequests: Math.max(0, ...samples.map((sample) => sample.inFlightRequests)),
finalInFlightRequests: totals.finalInFlightRequests,
storageKeyDelta: delta((sample) => sample.storageKeys),
storageByteDelta: delta((sample) => sample.storageBytes),
apiRequests: totals.apiRequests,
referenceVisits: totals.referenceVisits,
settledReferenceVisits: totals.settledReferenceVisits,
apiRequestsPerReferenceVisit:
totals.referenceVisits === 0
? 0
: Math.round((totals.apiRequests / totals.referenceVisits) * 1_000) / 1_000,
telemetryPosts: totals.telemetryPosts,
telemetryEvents: totals.telemetryEvents,
maxTelemetryPostsPerMinute,
};
const checks: SoakCheck[] = [
{ name: "cycles", passed: summary.cycles >= SOAK_LIMITS.minCycles, detail: `${summary.cycles} >= ${SOAK_LIMITS.minCycles}` },
{
name: "post-warmup samples",
passed: measured.length >= SOAK_LIMITS.minPostWarmupSamples,
detail: `${measured.length} >= ${SOAK_LIMITS.minPostWarmupSamples}`,
},
{ name: "navigation", passed: summary.navigationFailures === 0, detail: `${summary.navigationFailures} failures` },
{ name: "heap slope", passed: summary.heapClassification === "stable", detail: summary.heapClassification },
{
name: "listeners",
passed:
summary.listenerClassification === "stable" &&
summary.listenerDelta <= SOAK_LIMITS.maxListenerDelta,
detail: `${summary.listenerClassification}, delta ${summary.listenerDelta}`,
},
{
name: "timers",
passed: summary.timerDelta <= SOAK_LIMITS.maxTimerDelta,
detail: `delta ${summary.timerDelta}, max ${summary.maxActiveTimers}`,
},
{
name: "in-flight settles",
passed: summary.finalInFlightRequests === 0,
detail: `final ${summary.finalInFlightRequests}, max ${summary.maxInFlightRequests}`,
},
{
name: "storage growth",
passed: summary.storageKeyDelta <= SOAK_LIMITS.maxStorageKeyDelta,
detail: `keys ${summary.storageKeyDelta}, bytes ${summary.storageByteDelta}`,
},
{
name: "backend failure exercised",
passed:
summary.settledReferenceVisits > 0 && summary.apiRequests > 0 && summary.telemetryEvents > 0,
detail: `${summary.settledReferenceVisits} settled visits, ${summary.apiRequests} API requests, ${summary.telemetryEvents} telemetry events`,
},
{
name: "request amplification",
passed:
summary.referenceVisits > 0 &&
summary.apiRequestsPerReferenceVisit <= SOAK_LIMITS.maxApiRequestsPerReferenceVisit,
detail: `${summary.apiRequests} requests / ${summary.referenceVisits} visits`,
},
{
name: "telemetry rate",
passed: summary.maxTelemetryPostsPerMinute <= SOAK_LIMITS.maxTelemetryPostsPerMinute,
detail: `max ${summary.maxTelemetryPostsPerMinute}/min, ${summary.telemetryPosts} posts, ${summary.telemetryEvents} events`,
},
];
return { summary, checks };
}
const CONTENT_TYPES: Readonly<Record<string, string>> = {
".css": "text/css; charset=utf-8",
".html": "text/html; charset=utf-8",
".js": "text/javascript; charset=utf-8",
".json": "application/json; charset=utf-8",
".svg": "image/svg+xml",
".png": "image/png",
".webmanifest": "application/manifest+json",
};
type Counters = {
apiRequests: number;
telemetryPosts: number;
telemetryEvents: number;
telemetryPostTimes: number[];
};
async function serveSoakTarget(
root: string,
counters: Counters,
startedAt: () => number,
): Promise<Readonly<{ server: Server; baseUrl: string }>> {
let baseUrl = "";
const baseConfig = JSON.parse(
await readFile(path.join(root, "config.json"), "utf8"),
) as Record<string, unknown>;
const server = createServer(async (request, response) => {
try {
const url = new URL(request.url ?? "/", "http://127.0.0.1");
if (url.pathname === "/__telemetry") {
let body = "";
request.on("data", (chunk: Buffer) => {
body += chunk.toString("utf8");
});
request.on("end", () => {
counters.telemetryPosts += 1;
counters.telemetryPostTimes.push(Date.now() - startedAt());
try {
const parsed = JSON.parse(body) as { events?: unknown[] };
counters.telemetryEvents += Array.isArray(parsed.events) ? parsed.events.length : 0;
} catch {
// Counted as a post regardless of its body.
}
response.writeHead(204).end();
});
return;
}
if (url.pathname.startsWith("/api/")) {
counters.apiRequests += 1;
response.writeHead(503, { "Content-Type": "application/json" }).end("{}");
return;
}
if (url.pathname === "/config.json") {
response
.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" })
.end(
JSON.stringify({
...baseConfig,
API_BASE_URL: `${baseUrl}/api/`,
TELEMETRY_ENABLED: true,
TELEMETRY_ENDPOINT: `${baseUrl}/__telemetry`,
}),
);
return;
}
const requested = path.resolve(root, `.${decodeURIComponent(url.pathname)}`);
if (requested !== root && !requested.startsWith(`${root}${path.sep}`)) {
response.writeHead(403).end();
return;
}
const details = await stat(requested).catch(() => null);
const file = details?.isFile() ? requested : path.join(root, "index.html");
response.writeHead(200, {
"Content-Type": CONTENT_TYPES[path.extname(file)] ?? "application/octet-stream",
"Cache-Control": "no-store",
});
createReadStream(file).pipe(response);
} catch {
response.writeHead(404).end();
}
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const { port } = server.address() as AddressInfo;
baseUrl = `http://127.0.0.1:${port}`;
return { server, baseUrl };
}
const PAGE_PROBES = `
(() => {
const live = new Set();
const setT = window.setTimeout, clearT = window.clearTimeout;
const setI = window.setInterval, clearI = window.clearInterval;
window.setTimeout = (fn, ms, ...rest) => {
const id = setT(() => { live.delete(id); typeof fn === "function" && fn(...rest); }, ms);
live.add(id); return id;
};
window.clearTimeout = (id) => { live.delete(id); clearT(id); };
window.setInterval = (fn, ms, ...rest) => { const id = setI(fn, ms, ...rest); live.add(id); return id; };
window.clearInterval = (id) => { live.delete(id); clearI(id); };
let inFlight = 0;
const nativeFetch = window.fetch.bind(window);
window.fetch = (...args) => {
inFlight += 1;
return nativeFetch(...args).finally(() => { inFlight -= 1; });
};
const storageSize = (storage) => {
let bytes = 0;
for (let i = 0; i < storage.length; i += 1) {
const key = storage.key(i) ?? "";
bytes += key.length + (storage.getItem(key) ?? "").length;
}
return { keys: storage.length, bytes };
};
Object.defineProperty(window, "__soakProbe", {
value: () => {
const local = storageSize(window.localStorage);
const session = storageSize(window.sessionStorage);
return {
activeTimers: live.size,
inFlight,
storageKeys: local.keys + session.keys,
storageBytes: local.bytes + session.bytes,
};
},
});
})();
`;
type Probe = { activeTimers: number; inFlight: number; storageKeys: number; storageBytes: number };
export async function runBrowserSoak(
options: Readonly<{
distRoot: string;
durationMs: number;
intervalMs: number;
warmupMs: number;
routes: readonly string[];
}>,
): Promise<SoakArtifact> {
try {
await access(path.join(options.distRoot, "index.html"));
await access(path.join(options.distRoot, "config.json"));
} catch {
return {
schemaVersion: 2,
status: "skipped",
reason: "no built dist/index.html + config.json",
durationMs: 0,
samples: [],
};
}
let chromium: (typeof import("@playwright/test"))["chromium"];
try {
({ chromium } = await import("@playwright/test"));
} catch {
return { schemaVersion: 2, status: "skipped", reason: "playwright unavailable", durationMs: 0, samples: [] };
}
const counters: Counters = {
apiRequests: 0,
telemetryPosts: 0,
telemetryEvents: 0,
telemetryPostTimes: [],
};
let started = Date.now();
const { server, baseUrl } = await serveSoakTarget(
path.resolve(options.distRoot),
counters,
() => started,
);
let browser: Awaited<ReturnType<typeof chromium.launch>> | undefined;
try {
try {
browser = await chromium.launch();
} catch (error) {
return {
schemaVersion: 2,
status: "skipped",
reason: `browser unavailable: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`,
durationMs: 0,
samples: [],
};
}
const page = await browser.newPage();
await page.addInitScript(PAGE_PROBES);
const cdp = await page.context().newCDPSession(page);
await cdp.send("Performance.enable");
await page.goto(`${baseUrl}/examples/reference-resources`, { waitUntil: "load" });
await page.waitForSelector("#root > *", { timeout: 15_000 });
// Protected routes need a session: start the local demo session once, so
// the reference feature really dispatches its (failing) API requests.
const login = page.getByRole("button", { name: /로그인 시작|Sign in|Start sign-in/u });
if (await login.count()) {
await login.first().click();
await page.waitForTimeout(500);
}
const samples: SoakSample[] = [];
started = Date.now();
let nextSample = 0;
let cycles = 0;
let navigationFailures = 0;
let referenceVisits = 0;
let settledReferenceVisits = 0;
const probe = async () =>
(await page.evaluate(() =>
(window as unknown as { __soakProbe: () => Probe }).__soakProbe(),
)) as Probe;
while (Date.now() - started < options.durationMs) {
const route = options.routes[cycles % options.routes.length] ?? "/";
cycles += 1;
if (route === "/examples/reference-resources") referenceVisits += 1;
// Client-side navigation keeps one long-lived document, like a real session.
await page.evaluate((target) => {
window.history.pushState({}, "", target);
window.dispatchEvent(new PopStateEvent("popstate"));
}, route);
await page.waitForTimeout(50);
const rendered = await page.evaluate(
(target) =>
window.location.pathname === target &&
(document.getElementById("root")?.childElementCount ?? 0) > 0,
route,
);
if (!rendered) navigationFailures += 1;
// Most visits leave after 50ms, which cancels the query (a cancelled
// request is intentionally not reported). Every 5th reference visit
// dwells until its interaction settles, so the failing backend is really
// observed end to end: bounded retries, then feature/platform telemetry.
if (route === "/examples/reference-resources" && referenceVisits % 5 === 1) {
await page.waitForTimeout(200);
await page
.waitForFunction(
() => (window as unknown as { __soakProbe: () => Probe }).__soakProbe().inFlight === 0,
undefined,
{ timeout: 5_000 },
)
.catch(() => undefined);
settledReferenceVisits += 1;
}
const elapsedMs = Date.now() - started;
if (elapsedMs >= nextSample) {
nextSample = elapsedMs + options.intervalMs;
await cdp.send("HeapProfiler.collectGarbage").catch(() => undefined);
const { metrics } = (await cdp.send("Performance.getMetrics")) as {
metrics: { name: string; value: number }[];
};
const metric = (name: string) => metrics.find((entry) => entry.name === name)?.value ?? 0;
const probed = await probe();
samples.push({
elapsedMs,
cycles,
heapBytes: metric("JSHeapUsedSize"),
domNodes: metric("Nodes"),
listeners: metric("JSEventListeners"),
activeTimers: probed.activeTimers,
inFlightRequests: probed.inFlight,
storageKeys: probed.storageKeys,
storageBytes: probed.storageBytes,
});
}
}
// Let the last interaction's bounded retries and deadlines settle.
let finalInFlightRequests = (await probe()).inFlight;
for (let wait = 0; wait < 30 && finalInFlightRequests > 0; wait += 1) {
await page.waitForTimeout(500);
finalInFlightRequests = (await probe()).inFlight;
}
const evaluation = evaluateSoak(
samples,
{
cycles,
navigationFailures,
referenceVisits,
settledReferenceVisits,
finalInFlightRequests,
apiRequests: counters.apiRequests,
telemetryPosts: counters.telemetryPosts,
telemetryEvents: counters.telemetryEvents,
telemetryPostTimes: counters.telemetryPostTimes,
},
options.warmupMs,
);
const build = await readFile(path.join(options.distRoot, "release-manifest.json"), "utf8")
.then((raw) => {
const manifest = JSON.parse(raw) as Record<string, unknown>;
const pick = (key: string) =>
typeof manifest[key] === "string" ? (manifest[key] as string) : undefined;
return {
...(pick("buildId") ? { buildId: pick("buildId") } : {}),
...(pick("releaseId") ? { releaseId: pick("releaseId") } : {}),
...(pick("builtAt") ? { builtAt: pick("builtAt") } : {}),
};
})
.catch(() => ({}));
return {
schemaVersion: 2,
status: evaluation.checks.every((check) => check.passed) ? "passed" : "failed",
durationMs: options.durationMs,
classification: evaluation.summary.heapClassification,
summary: evaluation.summary,
checks: evaluation.checks,
build,
browser: `chromium ${browser.version()}`,
samples,
};
} finally {
await browser?.close().catch(() => undefined);
await new Promise<void>((resolve) => server.close(() => resolve()));
}
}
async function main(): Promise<void> {
const argument = (name: string, fallback: string) =>
process.argv.find((entry) => entry.startsWith(`--${name}=`))?.slice(name.length + 3) ?? fallback;
const artifact = path.resolve(argument("artifact", "artifacts/scale/browser-soak.json"));
const result = await runBrowserSoak({
distRoot: argument("dist", "dist"),
durationMs: Number(argument("duration-ms", "60000")),
intervalMs: Number(argument("interval-ms", "5000")),
warmupMs: Number(argument("warmup-ms", "15000")),
routes: argument(
"routes",
"/,/examples/reference-resources,/examples/platform,/examples/ui,/examples/states,/examples/reference-resources/status",
).split(","),
});
await mkdir(path.dirname(artifact), { recursive: true });
await writeFile(artifact, `${JSON.stringify(result, null, 2)}\n`);
process.stdout.write(
`browser soak: ${result.status}${result.reason ? ` (${result.reason})` : ""}` +
`${result.classification ? ` classification=${result.classification}` : ""} samples=${result.samples.length}` +
`${result.summary ? ` cycles=${result.summary.cycles}` : ""}\n`,
);
for (const check of result.checks ?? []) {
process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`);
}
if (result.status === "failed") process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+113
View File
@@ -0,0 +1,113 @@
import { spawnSync } from "node:child_process";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import { collectTscScale } from "./collect-tsc-diagnostics.ts";
import { runCompositionScale } from "./run-composition-scale.ts";
import {
approveBaseline,
compareToBaseline,
currentEnvironment,
snapshotMetrics,
type ScaleBaseline,
} from "./scale-baseline.ts";
/**
* Spec §48–§49. Relative regression gate against the stored, approved scale
* baseline (`config/scale/benchmark-baseline.json`).
*
* node scripts/scale/check-scale-baseline.ts compare, fail on regression
* SCALE_BASELINE_OWNER=... SCALE_BASELINE_REASON=... \
* node scripts/scale/check-scale-baseline.ts --update re-measure and re-approve
*
* The comparison is written to artifacts/scale/baseline-comparison.json (or
* `--artifact=`). Updating is an explicit, attributed act; the check never
* rewrites the baseline.
*/
export const BASELINE_PATH = "config/scale/benchmark-baseline.json";
export const LOCAL_TSC_SIZES = Object.freeze([25, 100, 400]);
function typescriptVersion(): string {
const result = spawnSync(path.resolve("node_modules/.bin/tsc"), ["-v"], { encoding: "utf8" });
const match = /Version\s+(\S+)/u.exec(result.stdout ?? "");
if (!match?.[1]) throw new Error("cannot determine TypeScript version");
return match[1];
}
async function measure() {
const composition = await runCompositionScale(["S0", "S1", "S2"], { samples: 9, warmup: 2 });
const compiler = await collectTscScale(LOCAL_TSC_SIZES);
return snapshotMetrics(composition.results, compiler);
}
async function main(): Promise<void> {
const update = process.argv.includes("--update");
const artifact = path.resolve(
process.argv.find((entry) => entry.startsWith("--artifact="))?.slice("--artifact=".length) ??
"artifacts/scale/baseline-comparison.json",
);
const environment = currentEnvironment(typescriptVersion());
const metrics = await measure();
if (update) {
const owner = process.env["SCALE_BASELINE_OWNER"];
const reason = process.env["SCALE_BASELINE_REASON"];
if (!owner || !reason) {
process.stderr.write("SCALE_BASELINE_OWNER and SCALE_BASELINE_REASON are required.\n");
process.exit(1);
}
const baseline = approveBaseline(environment, metrics, {
owner,
reason,
approvedAt: new Date().toISOString(),
});
await mkdir(path.dirname(BASELINE_PATH), { recursive: true });
await writeFile(BASELINE_PATH, `${JSON.stringify(baseline, null, 2)}\n`);
process.stdout.write(`scale baseline approved: ${baseline.approval.metricsDigest}\n`);
return;
}
let baseline: ScaleBaseline;
try {
baseline = JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ScaleBaseline;
} catch {
process.stderr.write(`missing or unreadable ${BASELINE_PATH}; run update:scale-baseline\n`);
process.exit(1);
}
const comparison = compareToBaseline(baseline, environment, metrics);
await mkdir(path.dirname(artifact), { recursive: true });
await writeFile(
artifact,
`${JSON.stringify(
{ schemaVersion: 1, generatedAt: new Date().toISOString(), environment, baselineApproval: baseline.approval, ...comparison },
null,
2,
)}\n`,
);
const { compatibility } = comparison;
process.stdout.write(
`compatibility: structural=${compatibility.structural.ok} compiler=${compatibility.compiler.ok} timing=${compatibility.timing.ok}\n`,
);
if (!compatibility.timing.ok) {
process.stdout.write(
`timing regression NOT compared (incomplete): ${compatibility.timing.reasons.join("; ")}\n`,
);
}
process.stdout.write(
`axes: absolute ${comparison.absolute.findings.length} (${comparison.absolute.passed ? "ok" : "FAIL"}), ` +
`growth ${comparison.growth.findings.length} (${comparison.growth.passed ? "ok" : "FAIL"}), ` +
`relative ${comparison.compiler.length} compiler + ${comparison.timing.length} timing\n`,
);
for (const failure of comparison.failures) process.stdout.write(`FAIL ${failure}\n`);
process.stdout.write(
`scale baseline gate: ${comparison.status.toUpperCase()} (${path.relative(process.cwd(), artifact)})\n`,
);
if (comparison.status === "failed") process.exitCode = 1;
else if (comparison.status === "incomplete" && process.env["SCALE_ALLOW_INCOMPLETE"] !== "1") {
process.exitCode = 1;
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+208
View File
@@ -0,0 +1,208 @@
import { spawnSync } from "node:child_process";
import { mkdir, rm, writeFile } from "node:fs/promises";
import { join, resolve } from "node:path";
import {
assertLinearOrBetter,
growthExponents,
} from "../../src/platform/cardinality/growth-regression.ts";
/**
* Spec §38. TypeScript scale gate.
*
* Parses `tsc --extendedDiagnostics` and measures bounded local fixtures:
* generated feature modules composed by one context, at increasing local
* cardinality. S3/S4 are never compiled; they are verified as topology.
*/
export type TscDiagnostics = Readonly<{
files: number;
lines?: number;
types: number;
symbols: number;
instantiations: number;
memoryKb?: number;
totalTimeSeconds?: number;
}>;
const FIELD_NAMES: Readonly<Record<string, keyof TscDiagnostics>> = Object.freeze({
Files: "files",
Lines: "lines",
Types: "types",
Symbols: "symbols",
Instantiations: "instantiations",
"Memory used": "memoryKb",
"Total time": "totalTimeSeconds",
});
export function parseTscExtendedDiagnostics(text: string): TscDiagnostics {
const parsed: Partial<Record<keyof TscDiagnostics, number>> = {};
for (const line of text.split(/\r?\n/u)) {
const match = /^\s*([A-Za-z][A-Za-z ]*?):\s+([\d.]+)\s*([KMs]?)\s*$/u.exec(line);
if (!match) continue;
const field = FIELD_NAMES[match[1] as string];
if (!field) continue;
const value = Number(match[2]);
if (!Number.isFinite(value)) continue;
parsed[field] = match[3] === "M" ? value * 1024 : value;
}
for (const required of ["files", "types", "symbols", "instantiations"] as const) {
if (parsed[required] === undefined) {
throw new TypeError(`tsc diagnostics missing ${required}`);
}
}
return Object.freeze(parsed) as TscDiagnostics;
}
export function runTscDiagnostics(project: string, cwd = process.cwd()): TscDiagnostics {
const tsc = resolve(cwd, "node_modules/.bin/tsc");
const result = spawnSync(tsc, ["--project", project, "--noEmit", "--extendedDiagnostics"], {
cwd,
encoding: "utf8",
maxBuffer: 16 * 1024 * 1024,
});
if (result.status !== 0) {
throw new Error(`tsc failed for ${project}: ${(result.stdout + result.stderr).slice(-2_000)}`);
}
return parseTscExtendedDiagnostics(result.stdout);
}
/**
* Generates one bounded local app: `features` feature modules, each with its
* own typed contract, composed by one generated index. The shape mirrors the
* repository's feature-module/generated-index pattern.
*/
export async function writeLocalTscFixture(
root: string,
features: number,
): Promise<string> {
await rm(root, { recursive: true, force: true });
await mkdir(join(root, "features"), { recursive: true });
const imports: string[] = [];
const members: string[] = [];
for (let index = 0; index < features; index += 1) {
const id = `feature${index}`;
await writeFile(
join(root, "features", `${id}.ts`),
`export type ${id}Input = Readonly<{ id: string; limit: number; tags?: readonly string[] }>;\n` +
`export type ${id}Output = Readonly<{ items: readonly Readonly<{ id: string; name: string }>[] }>;\n` +
`export const ${id} = Object.freeze({\n` +
` id: "${id}" as const,\n` +
` routes: Object.freeze({ ${id.toUpperCase()}_LIST: "/${id}" }),\n` +
` execute(input: ${id}Input): ${id}Output {\n` +
` return { items: [{ id: input.id, name: String(input.limit) }] };\n` +
` },\n` +
`});\n`,
);
imports.push(`import { ${id} } from "./features/${id}.ts";`);
members.push(` ${id},`);
}
await writeFile(
join(root, "index.ts"),
`${imports.join("\n")}\nexport const LOCAL_FEATURES = Object.freeze([\n${members.join("\n")}\n] as const);\n` +
`export type LocalFeatureId = (typeof LOCAL_FEATURES)[number]["id"];\n`,
);
const tsconfig = join(root, "tsconfig.json");
await writeFile(
tsconfig,
JSON.stringify(
{
compilerOptions: {
target: "ES2022",
module: "ESNext",
moduleResolution: "Bundler",
allowImportingTsExtensions: true,
strict: true,
noEmit: true,
skipLibCheck: true,
types: [],
lib: ["ES2022"],
},
include: ["index.ts", "features/*.ts"],
},
null,
2,
),
);
return tsconfig;
}
export type TscScaleReport = Readonly<{
passed: boolean;
app: TscDiagnostics;
local: readonly Readonly<{ features: number; diagnostics: TscDiagnostics }>[];
checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[];
}>;
export async function collectTscScale(
localSizes: readonly number[],
cwd = process.cwd(),
): Promise<TscScaleReport> {
const app = runTscDiagnostics("tsconfig.app.json", cwd);
const local: { features: number; diagnostics: TscDiagnostics }[] = [];
for (const features of localSizes) {
const tsconfig = await writeLocalTscFixture(
resolve(cwd, ".tmp/scale-tsc", `local-${features}`),
features,
);
local.push({ features, diagnostics: runTscDiagnostics(tsconfig, cwd) });
}
const checks: { name: string; passed: boolean; detail: string }[] = [];
for (const metric of ["types", "symbols", "instantiations"] as const) {
const series = local.map(({ features, diagnostics }) => ({
n: features,
// Library/baseline cost is constant; growth is judged on what the local
// features add on top of the smallest fixture.
cost: Math.max(1, diagnostics[metric]),
}));
try {
assertLinearOrBetter(series, { maxExponent: 1.3 });
checks.push({
name: `tsc:${metric}`,
passed: true,
detail: `exponents ${growthExponents(series).map((value) => value.toFixed(2)).join(", ")}`,
});
} catch (error) {
checks.push({
name: `tsc:${metric}`,
passed: false,
detail: error instanceof Error ? error.message : String(error),
});
}
}
return Object.freeze({
passed: checks.every((check) => check.passed),
app,
local: Object.freeze(local),
checks: Object.freeze(checks),
});
}
async function main(): Promise<void> {
const artifactArg = process.argv.find((argument) => argument.startsWith("--artifact="));
const sizesArg = process.argv.find((argument) => argument.startsWith("--local-sizes="));
const sizes = (sizesArg?.slice("--local-sizes=".length) ?? "25,100,400")
.split(",")
.map(Number)
.filter((value) => Number.isSafeInteger(value) && value > 0);
const artifact = resolve(
artifactArg?.slice("--artifact=".length) ?? "artifacts/scale/tsc-diagnostics.json",
);
const report = await collectTscScale(sizes);
await mkdir(resolve(artifact, ".."), { recursive: true });
await writeFile(
artifact,
`${JSON.stringify({ schemaVersion: 1, generatedAt: new Date().toISOString(), ...report }, null, 2)}\n`,
);
process.stdout.write(
`tsc app: files=${report.app.files} types=${report.app.types} instantiations=${report.app.instantiations}\n`,
);
for (const check of report.checks) {
process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`);
}
process.stdout.write(`tsc diagnostics artifact: ${artifact}\n`);
if (!report.passed) process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+108
View File
@@ -0,0 +1,108 @@
import { composeUniqueRecord } from "../../src/platform/cardinality/compose-unique-record.ts";
import {
resolveProductFeatures,
selectCompiledProductFeatures,
} from "../../src/contracts/product-features.ts";
import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts";
import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts";
/**
* Spec §39. Scale-sensitive production composition paths, each parameterized
* by one cardinality `n`. Inputs are built outside the timed region.
*/
export type CompositionWorkload = Readonly<{
name: string;
implementation: string;
prepare(n: number): () => unknown;
}>;
export function createUniqueRegistryParts(
count: number,
): readonly Readonly<Record<string, number>>[] {
return Array.from({ length: count }, (_, index) =>
Object.freeze({ [`route-${index}`]: index }),
);
}
function featureIds(count: number): string[] {
return Array.from(
{ length: count },
(_, index) => `feature-${index.toString().padStart(7, "0")}`,
);
}
const CONTEXT_FEATURES = 200;
export const COMPOSITION_WORKLOADS: readonly CompositionWorkload[] = Object.freeze([
{
name: "registry-composition",
implementation: "composeUniqueRecord",
prepare(n: number) {
const parts = createUniqueRegistryParts(n);
return () => composeUniqueRecord(parts, () => "route");
},
},
{
name: "product-feature-selection",
implementation: "selectCompiledProductFeatures",
prepare(n: number) {
const compiled = featureIds(n).map((featureId) => Object.freeze({ featureId }));
const declared = compiled
.filter((_, index) => index % 2 === 0)
.map((feature) => feature.featureId)
.join(",");
return () => selectCompiledProductFeatures(compiled, declared);
},
},
{
name: "product-feature-resolution",
implementation: "resolveProductFeatures",
prepare(n: number) {
const compiled = featureIds(n);
const installed = compiled.filter((_, index) => index % 3 !== 0);
return () => resolveProductFeatures(compiled, installed);
},
},
{
name: "context-hierarchy-composition",
implementation: "defineBoundedContextModule+defineDeployableAppModule",
prepare(n: number) {
const features = featureIds(n).map((id) =>
Object.freeze({
id,
contracts: Object.freeze({ featureId: id }),
routes: Object.freeze({}),
adapters: Object.freeze([]),
runtimes: Object.freeze([]),
messages: Object.freeze({}),
contractContributions: Object.freeze([]),
}),
);
const contextCount = Math.ceil(n / CONTEXT_FEATURES);
return () => {
const contexts = Array.from({ length: contextCount }, (_, contextIndex) =>
defineBoundedContextModule({
id: `context-${contextIndex}`,
features: features.slice(
contextIndex * CONTEXT_FEATURES,
(contextIndex + 1) * CONTEXT_FEATURES,
),
budget: Object.freeze({ maxFeatures: CONTEXT_FEATURES }),
}),
);
// Apps are sharded by the same direct-child budget.
const apps: unknown[] = [];
for (let index = 0; index < contexts.length; index += 20) {
apps.push(
defineDeployableAppModule({
id: `app-${index / 20}`,
contexts: contexts.slice(index, index + 20),
budget: Object.freeze({ maxContexts: 20 }),
}),
);
}
return apps;
};
},
},
]);
@@ -0,0 +1,259 @@
import { spawnSync } from "node:child_process";
import { cp, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
import { availableParallelism, cpus, loadavg, tmpdir } from "node:os";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { gzipSync } from "node:zlib";
import { classifyViteJavascript } from "../lib/classify-vite-bundle.ts";
import { linkFixtureNodeModules } from "../lib/fixture-node-modules.ts";
import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc-diagnostics.ts";
/**
* 11-04 (D-18). Cost of one app as its feature count grows, measured with
* features shaped like the real one: `src/features/reference-feature` copied N
* times with every feature-owned identifier renamed (feature id, route ids and
* paths, API operations, schemas, query namespace, invalidation topic,
* messages). The copies live in contexts of their own (200 features each, the
* context ceiling) so the reference context is unchanged.
*
* For each N the script runs the product generator, `tsc --extendedDiagnostics`
* over tsconfig.app.json and `vite build`, and records compiler counts, wall
* times and initial/lazy JavaScript gzip bytes. Deterministic counts repeat
* exactly; times depend on the host, so the CPU and load average are recorded
* next to them. A typecheck that fails (for example TS2590, a union too complex
* to represent) is recorded as a result with its first error.
*
* node scripts/scale/measure-feature-shape-growth.ts [--sizes=0,25,100] [--repeats=2] [--write]
*
* `--write` stores the result as config/scale/feature-shape-growth.json.
*/
export const FEATURE_SHAPE_BASELINE_PATH = "config/scale/feature-shape-growth.json";
/** What the declared ceilings rest on, derived by hand from the baseline. */
export const FEATURE_SHAPE_CEILINGS_PATH = "config/scale/feature-shape-ceilings.json";
const SOURCE_FEATURE = "src/features/reference-feature";
const FEATURES_PER_CONTEXT = 200;
const BUILD_INPUTS = [
"src",
"public",
"index.html",
"package.json",
"vite.config.ts",
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/vite-module-inventory.ts",
] as const;
// Platform-owned names that only happen to contain "reference".
const PLATFORM_TOKENS = [
"REFERENCE_EXTERNAL_BEARER",
"REFERENCE_FEATURE_V1",
"supportReference",
] as const;
/** Renames every feature-owned identifier of the reference feature for copy `id`. */
export function renameReferenceFeature(
text: string,
id: string,
context: Readonly<{ id: string; routeRoot: string }>,
): string {
const upper = id.toUpperCase();
let renamed = text;
PLATFORM_TOKENS.forEach((token, index) => {
renamed = renamed.replaceAll(token, `\u0000${index}\u0000`);
});
renamed = renamed
.replaceAll("/examples/reference-resources", `/${context.routeRoot}/${id}-resources`)
.replaceAll("qinv.01k10f7m3w9p6r2c8v5n4x", `qinv.shape.${id}`)
.replaceAll("NoRequest", `${upper}NoRequest`)
.replaceAll("reference-context", context.id)
.replaceAll("REFERENCE", upper)
.replaceAll("Reference", upper)
.replaceAll("reference", id);
PLATFORM_TOKENS.forEach((token, index) => {
renamed = renamed.replaceAll(`\u0000${index}\u0000`, token);
});
return renamed;
}
async function copyRenamed(from: string, to: string, rename: (text: string) => string) {
await mkdir(to, { recursive: true });
for (const entry of await readdir(from, { withFileTypes: true })) {
const source = path.join(from, entry.name);
const target = path.join(to, rename(entry.name));
if (entry.isDirectory()) await copyRenamed(source, target, rename);
else await writeFile(target, rename(await readFile(source, "utf8")));
}
}
async function createFixture(features: number): Promise<string> {
const root = await mkdtemp(path.join(tmpdir(), `feature-shape-${features}-`));
for (const input of BUILD_INPUTS) {
await mkdir(path.dirname(path.join(root, input)), { recursive: true });
await cp(path.resolve(input), path.join(root, input), { recursive: true });
}
await rm(path.join(root, "src/.generated"), { recursive: true, force: true });
await linkFixtureNodeModules(root);
for (let index = 0; index < features; index += 1) {
const contextNumber = Math.floor(index / FEATURES_PER_CONTEXT);
const context = { id: `shape-context-${contextNumber}`, routeRoot: `shape-${contextNumber}` };
if (index % FEATURES_PER_CONTEXT === 0) {
const contextFile = path.join(root, "src/contexts", context.id, "context-module.ts");
await mkdir(path.dirname(contextFile), { recursive: true });
await writeFile(
contextFile,
`export const CONTEXT_MODULE_ID = "${context.id}";\n` +
`export const CONTEXT_APP_ID = "template-app";\n` +
`export const CONTEXT_ROUTE_PATH = "${context.routeRoot}/*";\n` +
`export const CONTEXT_MAX_FEATURES = ${FEATURES_PER_CONTEXT};\n`,
);
}
const id = `s${String(index).padStart(3, "0")}`;
await copyRenamed(
path.resolve(SOURCE_FEATURE),
path.join(root, "src/features", `${id}-feature`),
(text) => renameReferenceFeature(text, id, context),
);
}
return root;
}
function run(
command: string,
args: readonly string[],
cwd: string,
options: Readonly<{ allowFailure?: boolean }> = {},
) {
const started = performance.now();
const result = spawnSync(command, args, {
cwd,
encoding: "utf8",
maxBuffer: 64 * 1024 * 1024,
});
const ms = Math.round(performance.now() - started);
if (result.status !== 0 && !(options.allowFailure && result.stdout.includes("Instantiations:"))) {
throw new Error(
`${path.basename(command)} ${args.join(" ")} failed in ${cwd}:\n${(result.stdout + result.stderr).slice(0, 4_000)}`,
);
}
return { ms, passed: result.status === 0, stdout: result.stdout };
}
const load = () => loadavg().map((value) => Math.round(value * 100) / 100);
async function javascriptGzipBytes(root: string, files: readonly string[]) {
let bytes = 0;
for (const file of files) bytes += gzipSync(await readFile(path.join(root, "dist", file))).byteLength;
return bytes;
}
async function measureOnce(root: string, features: number) {
const loadBefore = load();
run(process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], root);
// The composed registries throw at module evaluation on a duplicate route,
// operation, schema, namespace or message key: prove the copies compose.
const contracts = (await import(
`${pathToFileURL(path.join(root, "src/features/installed-feature-contracts.ts")).href}?features=${features}`
)) as typeof import("../../src/features/installed-feature-contracts.ts");
const routes = Object.keys(contracts.ROUTE_REGISTRY).length;
const tsc = run(
path.resolve("node_modules/.bin/tsc"),
["--project", path.join(root, "tsconfig.app.json"), "--noEmit", "--extendedDiagnostics"],
root,
// A type error is a result here (the typecheck stops scaling), not a crash.
{ allowFailure: true },
);
await rm(path.join(root, "dist"), { recursive: true, force: true });
const build = run(path.resolve("node_modules/.bin/vite"), ["build", "--logLevel", "error"], root);
const manifest = JSON.parse(await readFile(path.join(root, "dist/.vite/manifest.json"), "utf8"));
const javascript = classifyViteJavascript(manifest);
const diagnostics: TscDiagnostics = parseTscExtendedDiagnostics(tsc.stdout);
return {
addedFeatures: features,
routes,
tsc: {
passed: tsc.passed,
firstError: tsc.stdout.split("\n").find((line) => line.includes("error TS")) ?? null,
files: diagnostics.files,
types: diagnostics.types,
symbols: diagnostics.symbols,
instantiations: diagnostics.instantiations,
memoryKb: diagnostics.memoryKb ?? null,
wallMs: tsc.ms,
},
build: {
wallMs: build.ms,
initialJavascriptFiles: javascript.initialFiles.length,
initialJavascriptGzipBytes: await javascriptGzipBytes(root, javascript.initialFiles),
lazyJavascriptFiles: javascript.lazyFiles.length,
lazyJavascriptGzipBytes: await javascriptGzipBytes(root, javascript.lazyFiles),
},
loadBefore,
loadAfter: load(),
};
}
function version(bin: string): string {
const result = spawnSync(path.resolve("node_modules/.bin", bin), ["--version"], { encoding: "utf8" });
return (result.stdout ?? "").trim();
}
async function main(): Promise<void> {
const argument = (name: string) =>
process.argv.find((entry) => entry.startsWith(`--${name}=`))?.slice(name.length + 3);
const sizes = (argument("sizes") ?? "0,25,100").split(",").map(Number);
const repeats = Number(argument("repeats") ?? "2");
if (!sizes.every((size) => Number.isSafeInteger(size) && size >= 0) || !(repeats >= 1)) {
throw new TypeError("--sizes must be nonnegative integers and --repeats at least 1");
}
const runs = [];
for (const features of sizes) {
const root = await createFixture(features);
try {
for (let repeat = 1; repeat <= repeats; repeat += 1) {
const measured = await measureOnce(root, features);
runs.push({ repeat, ...measured });
process.stdout.write(
`features +${features} (repeat ${repeat}): routes=${measured.routes} ` +
`instantiations=${measured.tsc.instantiations} tsc=${measured.tsc.wallMs}ms ` +
`build=${measured.build.wallMs}ms initial=${measured.build.initialJavascriptGzipBytes}B ` +
`lazy=${measured.build.lazyJavascriptGzipBytes}B load=${measured.loadBefore.join("/")}` +
`${measured.tsc.passed ? "" : ` typecheck FAILED: ${measured.tsc.firstError}`}\n`,
);
// Compiler results repeat exactly; a failed typecheck costs minutes and
// gigabytes again for no new information.
if (!measured.tsc.passed) break;
}
} finally {
await rm(root, { recursive: true, force: true });
}
}
const cpu = cpus();
const result = {
schemaVersion: 1,
measuredAt: new Date().toISOString(),
command: `node scripts/scale/measure-feature-shape-growth.ts --sizes=${sizes.join(",")} --repeats=${repeats}`,
environment: {
node: process.versions.node,
platform: process.platform,
arch: process.arch,
cpuModel: cpu[0]?.model.trim() ?? "unknown",
logicalCpus: cpu.length,
availableParallelism: availableParallelism(),
typescript: version("tsc"),
vite: version("vite"),
},
sourceFeature: SOURCE_FEATURE,
runs,
};
const output = process.argv.includes("--write")
? FEATURE_SHAPE_BASELINE_PATH
: "artifacts/scale/feature-shape-growth.json";
await mkdir(path.dirname(output), { recursive: true });
await writeFile(output, `${JSON.stringify(result, null, 2)}\n`);
process.stdout.write(`feature-shape growth: ${output}\n`);
}
if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
await main();
}
+66
View File
@@ -0,0 +1,66 @@
/**
* Spec §44. Soak classification.
*
* The leak signal is sustained positive growth after warm-up, not an
* arbitrary absolute maximum. The classifier fits a least-squares line over
* the post-warm-up samples and reports `unbounded-growth` only when both the
* slope and the total relative growth are material.
*/
export type SlopeSample = Readonly<{ minute: number; heapMb: number }>;
export type MemorySlopeClass = "stable" | "unbounded-growth" | "insufficient-data";
export type MemorySlopeOptions = Readonly<{
/** Samples before this minute are warm-up. Default 0. */
warmupMinutes?: number;
/** Largest tolerated post-warm-up slope in MB per minute. Default 0.5. */
maxSlopeMbPerMinute?: number;
/** Largest tolerated relative growth first->last fitted value. Default 0.1. */
maxRelativeGrowth?: number;
}>;
export function linearSlope(points: readonly Readonly<{ x: number; y: number }>[]): number {
const count = points.length;
if (count < 2) return 0;
const meanX = points.reduce((sum, point) => sum + point.x, 0) / count;
const meanY = points.reduce((sum, point) => sum + point.y, 0) / count;
let numerator = 0;
let denominator = 0;
for (const point of points) {
numerator += (point.x - meanX) * (point.y - meanY);
denominator += (point.x - meanX) ** 2;
}
return denominator === 0 ? 0 : numerator / denominator;
}
export function classifyMemorySlope(
samples: readonly SlopeSample[],
options: MemorySlopeOptions = {},
): MemorySlopeClass {
const warmup = options.warmupMinutes ?? 0;
const maxSlope = options.maxSlopeMbPerMinute ?? 0.5;
const maxGrowth = options.maxRelativeGrowth ?? 0.1;
const measured = samples
.filter((sample) => sample.minute >= warmup)
.filter((sample) => Number.isFinite(sample.minute) && Number.isFinite(sample.heapMb))
.sort((left, right) => left.minute - right.minute);
if (measured.length < 3) return "insufficient-data";
const slope = linearSlope(measured.map((sample) => ({ x: sample.minute, y: sample.heapMb })));
const first = measured[0] as SlopeSample;
const last = measured[measured.length - 1] as SlopeSample;
const fittedStart = Math.max(first.heapMb, Number.MIN_VALUE);
const growth = (slope * (last.minute - first.minute)) / fittedStart;
return slope > maxSlope && growth > maxGrowth ? "unbounded-growth" : "stable";
}
/** Generic variant for logical counters (timers, listeners, buffered events). */
export function classifyCounterSeries(
values: readonly number[],
options: Readonly<{ warmupSamples?: number; maxSlopePerSample?: number }> = {},
): MemorySlopeClass {
const warmup = options.warmupSamples ?? 0;
const measured = values.slice(warmup);
if (measured.length < 3) return "insufficient-data";
const slope = linearSlope(measured.map((y, x) => ({ x, y })));
return slope > (options.maxSlopePerSample ?? 0.01) ? "unbounded-growth" : "stable";
}
+136
View File
@@ -0,0 +1,136 @@
import { resolve } from "node:path";
import {
assertLinearOrBetter,
growthExponents,
} from "../../src/platform/cardinality/growth-regression.ts";
import { benchmark } from "./benchmark.ts";
import {
writeBenchmarkArtifact,
type BenchmarkProfile,
type BenchmarkResult,
} from "./benchmark-result.ts";
import { COMPOSITION_WORKLOADS } from "./composition-workloads.ts";
/**
* Spec §36 / §39. Runtime composition scale gate for S0-S2.
*
* Every production composition workload runs at each requested profile with
* warm-up and repeated samples; the median series must be linear-or-better.
* Results are written as a machine-readable artifact under artifacts/scale/.
*/
export const COMPOSITION_PROFILES: Readonly<Record<string, number>> = Object.freeze({
S0: 100,
S1: 1_000,
S2: 10_000,
});
/** Scheduler noise below this median is not evidence of growth. */
export const COMPOSITION_NOISE_FLOOR_MS = 0.5;
/**
* n log n paths (sorting, allocation-heavy string work) measure ~1.1-1.4
* between S1 and S2; a quadratic path measures ~2. 1.6 separates the two.
*/
export const COMPOSITION_MAX_EXPONENT = 1.6;
export type CompositionScaleReport = Readonly<{
passed: boolean;
results: readonly BenchmarkResult[];
checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[];
}>;
export async function runCompositionScale(
profiles: readonly string[],
options: Readonly<{
samples?: number;
warmup?: number;
/**
* `median` (default) for standalone gate runs. `min` (best observed) when
* the gate shares the machine with other suites: stolen CPU and foreign
* GC only ever add time, so the minimum keeps the algorithmic shape.
*/
statistic?: "median" | "min";
}> = {},
): Promise<CompositionScaleReport> {
const results: BenchmarkResult[] = [];
const checks: { name: string; passed: boolean; detail: string }[] = [];
for (const workload of COMPOSITION_WORKLOADS) {
const series: { n: number; cost: number }[] = [];
for (const profile of profiles) {
const cardinality = COMPOSITION_PROFILES[profile];
if (cardinality === undefined) throw new TypeError(`unknown profile ${profile}`);
const run = workload.prepare(cardinality);
const result = await benchmark(workload.name, {
samples: options.samples ?? 7,
warmup: options.warmup ?? 2,
profile: profile as BenchmarkProfile,
cardinality,
measureHeap: true,
metadata: { implementation: workload.implementation },
run,
});
results.push(result);
series.push({
n: cardinality,
cost:
options.statistic === "min" ? Math.min(...result.samples) : result.medianMs,
});
}
if (series.length < 2) continue;
try {
assertLinearOrBetter(series, {
maxExponent: COMPOSITION_MAX_EXPONENT,
noiseFloor: COMPOSITION_NOISE_FLOOR_MS,
});
checks.push({
name: `${workload.name}:growth`,
passed: true,
detail: `exponents ${growthExponents(series, COMPOSITION_NOISE_FLOOR_MS)
.map((exponent) => exponent.toFixed(2))
.join(", ")}`,
});
} catch (error) {
checks.push({
name: `${workload.name}:growth`,
passed: false,
detail: error instanceof Error ? error.message : String(error),
});
}
}
return Object.freeze({
passed: checks.every((check) => check.passed),
results: Object.freeze(results),
checks: Object.freeze(checks),
});
}
async function main(): Promise<void> {
const profileArg = process.argv.find((argument) => argument.startsWith("--profiles="));
const artifactArg = process.argv.find((argument) => argument.startsWith("--artifact="));
const profiles = (profileArg?.slice("--profiles=".length) ?? "S0,S1,S2")
.split(",")
.map((entry) => entry.trim())
.filter(Boolean);
const artifact = resolve(
artifactArg?.slice("--artifact=".length) ?? "artifacts/scale/composition-scale.json",
);
const report = await runCompositionScale(profiles);
await writeBenchmarkArtifact(artifact, {
schemaVersion: 1,
suite: "composition-scale",
generatedAt: new Date().toISOString(),
node: process.version,
passed: report.passed,
results: report.results,
checks: report.checks,
});
for (const check of report.checks) {
process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`);
}
process.stdout.write(`composition scale artifact: ${artifact}\n`);
if (!report.passed) process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+195
View File
@@ -0,0 +1,195 @@
import { spawnSync } from "node:child_process";
import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
/**
* Spec §47. Execution tiers for the scale/chaos/soak program.
*
* pr architecture and traffic invariants, S0-S2 composition growth
* main pr + TypeScript diagnostics and the stored baseline regression
* gate (config/scale/benchmark-baseline.json)
* nightly main + S3/S4 topology, telemetry storm, session cycles, browser soak
* release release-coherence matrix + the stable main/nightly subset
*
* Only `pr` runs in CI (merge gate FE-GATE-005, 11-03). Its checks are counts,
* bounds and growth shape, so they hold on any CPU; the composition timings it
* writes are advisory. `main`, `nightly` and `release` include
* `baseline-regression`, which compares timings only on the CPU model that
* recorded config/scale/benchmark-baseline.json and is `incomplete` elsewhere,
* so no CI job runs them; they are local commands for that machine.
*
* Every step's output goes to artifacts/scale/<tier>/<step>.log and the tier
* writes one machine-readable summary.json. A step that could not run (e.g. a
* browser soak without a build or browser) is `skipped`, and a tier with any
* skipped step is `incomplete`: it is never reported as passed and exits
* non-zero. `SCALE_ALLOW_INCOMPLETE=1` keeps the exit code zero for local runs,
* but the summary still says `incomplete`.
*/
export type ScaleTier = "pr" | "main" | "nightly" | "release";
type Step = Readonly<{
id: string;
command: readonly string[];
/** A step that may legitimately report `skipped` in its own artifact. */
optional?: boolean;
}>;
const VITEST = ["scripts/run-vitest.ts", "run", "--reporter=default"];
const PR_STEPS: readonly Step[] = [
{
id: "architecture-topology",
command: [...VITEST, "tests/architecture", "tests/platform/cardinality", "tests/platform/routing"],
},
{
id: "traffic-budgets",
command: [...VITEST, "tests/platform/execution", "tests/platform/traffic", "tests/platform/resilience"],
},
{
id: "scale-units",
command: [
...VITEST,
"tests/scale/growth-regression.test.ts",
"tests/scale/benchmark.test.ts",
"tests/scale/synthetic-topology.test.ts",
"tests/scale/scale-baseline.test.ts",
"tests/scale/traffic",
],
},
// 11-03: S2 is included because below it every workload stays under the
// noise floor, so a quadratic accumulation passed S0/S1 unnoticed.
{
id: "composition-s0-s2",
command: ["scripts/scale/run-composition-scale.ts", "--profiles=S0,S1,S2"],
},
];
const MAIN_STEPS: readonly Step[] = [
...PR_STEPS,
{
id: "composition-scale-suite",
command: [...VITEST, "tests/scale/composition-scale.test.ts", "tests/scale/tsc-diagnostics-parser.test.ts"],
},
{
id: "typescript-diagnostics",
command: ["scripts/scale/collect-tsc-diagnostics.ts", "--local-sizes=25,100,400"],
},
{
id: "baseline-regression",
command: ["scripts/scale/check-scale-baseline.ts"],
},
];
const NIGHTLY_STEPS: readonly Step[] = [
...MAIN_STEPS,
{
id: "topology-s3-s4",
command: [...VITEST, "tests/scale/global-local-independence.test.ts", "tests/platform/cardinality/extreme-scale-registry.test.ts"],
},
{
id: "telemetry-storm",
command: [...VITEST, "tests/scale/telemetry", "tests/platform/telemetry"],
},
{ id: "session-cycles", command: [...VITEST, "tests/scale/session"] },
{
id: "browser-soak",
command: ["scripts/scale/browser-soak.ts", "--duration-ms=120000", "--interval-ms=5000", "--warmup-ms=30000"],
optional: true,
},
];
const RELEASE_STEPS: readonly Step[] = [
{
id: "release-coherence",
command: [...VITEST, "tests/platform/release", "tests/release"],
},
...MAIN_STEPS,
{
id: "topology-s3-s4",
command: [...VITEST, "tests/scale/global-local-independence.test.ts"],
},
{
id: "telemetry-storm",
command: [...VITEST, "tests/scale/telemetry"],
},
];
export const SCALE_TIERS: Readonly<Record<ScaleTier, readonly Step[]>> = Object.freeze({
pr: PR_STEPS,
main: MAIN_STEPS,
nightly: NIGHTLY_STEPS,
release: RELEASE_STEPS,
});
function withArtifact(step: Step, directory: string): readonly string[] {
const script = step.command[0] ?? "";
if (
script.endsWith("run-composition-scale.ts") ||
script.endsWith("collect-tsc-diagnostics.ts") ||
script.endsWith("browser-soak.ts") ||
script.endsWith("check-scale-baseline.ts")
) {
return [...step.command, `--artifact=${path.join(directory, `${step.id}.json`)}`];
}
return step.command;
}
async function main(): Promise<void> {
const tier = process.argv[2] as ScaleTier | undefined;
if (!tier || !(tier in SCALE_TIERS)) {
process.stderr.write(`usage: run-scale-profile.ts <${Object.keys(SCALE_TIERS).join("|")}>\n`);
process.exit(2);
}
const directory = path.resolve("artifacts/scale", tier);
await mkdir(directory, { recursive: true });
const results: { id: string; status: "passed" | "failed" | "skipped"; durationMs: number; log: string }[] = [];
for (const step of SCALE_TIERS[tier]) {
const startedAt = Date.now();
const run = spawnSync(process.execPath, [...withArtifact(step, directory)], {
encoding: "utf8",
maxBuffer: 64 * 1024 * 1024,
env: { ...process.env, SCALE_ARTIFACT_DIR: path.join(directory, "metrics") },
});
const log = path.join(directory, `${step.id}.log`);
await writeFile(log, `${run.stdout ?? ""}${run.stderr ?? ""}`);
const skipped = step.optional === true && /: skipped/u.test(run.stdout ?? "");
const status = run.status === 0 ? (skipped ? "skipped" : "passed") : "failed";
results.push({ id: step.id, status, durationMs: Date.now() - startedAt, log: path.relative(process.cwd(), log) });
process.stdout.write(`${status.toUpperCase()} ${tier}:${step.id} (${Date.now() - startedAt}ms)\n`);
}
const failed = results.some((result) => result.status === "failed");
const skipped = results.filter((result) => result.status === "skipped").map((result) => result.id);
const status = failed ? "failed" : skipped.length > 0 ? "incomplete" : "passed";
await writeFile(
path.join(directory, "summary.json"),
`${JSON.stringify(
{
schemaVersion: 1,
tier,
generatedAt: new Date().toISOString(),
node: process.version,
environment: {
node: process.version,
nodeMajor: Number(process.versions.node.split(".")[0]),
platform: process.platform,
arch: process.arch,
},
status,
passed: status === "passed",
skipped,
steps: results,
},
null,
2,
)}\n`,
);
process.stdout.write(
`scale tier ${tier}: ${status.toUpperCase()}${skipped.length > 0 ? ` (skipped: ${skipped.join(", ")})` : ""} (artifacts/scale/${tier}/summary.json)\n`,
);
if (status === "failed") process.exitCode = 1;
else if (status === "incomplete" && process.env["SCALE_ALLOW_INCOMPLETE"] !== "1") process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+381
View File
@@ -0,0 +1,381 @@
import { createHash } from "node:crypto";
import { cpus } from "node:os";
import { growthExponents } from "../../src/platform/cardinality/growth-regression.ts";
import type { BenchmarkResult } from "./benchmark-result.ts";
import type { TscDiagnostics } from "./collect-tsc-diagnostics.ts";
/**
* Spec §48–§49. Stored benchmark baseline, compatibility check and relative
* regression gate.
*
* The growth gates judge the *shape* of one run. This module compares a run
* against an approved stored baseline so a change that keeps the shape but
* multiplies the cost (or silently adds compiler work) is still caught.
*
* Two kinds of metric are compared differently:
* - deterministic metrics (TypeScript types/symbols/instantiations/files) are
* exact for a given compiler, so they use a tight relative tolerance and
* require a compatible toolchain;
* - timing metrics depend on the machine, so they use a loose tolerance plus an
* absolute noise floor, and are only enforced on a compatible environment.
*/
export const SCALE_BASELINE_SCHEMA_VERSION = 1;
export type ScaleEnvironment = Readonly<{
nodeMajor: number;
platform: string;
arch: string;
cpuModel: string;
cpuCount: number;
typescript: string;
}>;
export type TimingEntry = Readonly<{
workload: string;
profile: string;
cardinality: number;
medianMs: number;
minMs: number;
}>;
export type CompilerEntry = Readonly<{
fixture: string;
files: number;
types: number;
symbols: number;
instantiations: number;
}>;
export type ScaleMetrics = Readonly<{
timing: readonly TimingEntry[];
compiler: readonly CompilerEntry[];
}>;
export type ScaleBaseline = Readonly<{
schemaVersion: typeof SCALE_BASELINE_SCHEMA_VERSION;
environment: ScaleEnvironment;
metrics: ScaleMetrics;
approval: Readonly<{
owner: string;
reason: string;
approvedAt: string;
metricsDigest: string;
}>;
}>;
export const REGRESSION_TOLERANCE = Object.freeze({
/** Deterministic compiler counts may grow at most 10% without re-approval. */
compilerRelative: 0.1,
/** Timings may grow at most 2.5x (scheduler/GC noise lives below that)... */
timingRelative: 1.5,
/** ...and never fail on differences below this absolute noise floor. */
timingNoiseFloorMs: 1,
});
/**
* Axis 1 — absolute ceilings. Machine-agnostic hard limits (roughly 50x the
* approved baseline for timings, ~2x for compiler work) that hold even with
* no comparable baseline.
*/
export const ABSOLUTE_CEILINGS = Object.freeze({
timingMinMsByProfile: Object.freeze({ S0: 5, S1: 25, S2: 150 } as Record<string, number>),
app: Object.freeze({ files: 1_500, types: 600_000, symbols: 1_600_000, instantiations: 1_500_000 }),
/**
* Generated `local-<N>` compiler fixtures: a fixed base (lib/runtime
* overhead present at any N) plus a per-local-feature allowance.
*/
localBase: Object.freeze({ files: 100, types: 5_000, symbols: 15_000, instantiations: 5_000 }),
localPerFeature: Object.freeze({ files: 2, types: 100, symbols: 250, instantiations: 150 }),
});
/** Axis 3 — growth shape (see src/platform/cardinality/growth-regression.ts). */
export const GROWTH_LIMITS = Object.freeze({
timingMaxExponent: 1.6,
timingNoiseFloorMs: 0.5,
compilerMaxExponent: 1.3,
});
export function currentEnvironment(typescript: string): ScaleEnvironment {
const cpu = cpus();
return Object.freeze({
nodeMajor: Number(process.versions.node.split(".")[0]),
platform: process.platform,
arch: process.arch,
cpuModel: cpu[0]?.model.trim() ?? "unknown",
cpuCount: cpu.length,
typescript,
});
}
function canonical(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
if (value && typeof value === "object") {
return `{${Object.keys(value)
.sort()
.map((key) => `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`)
.join(",")}}`;
}
return JSON.stringify(value);
}
export function metricsDigest(metrics: ScaleMetrics): string {
return createHash("sha256").update(canonical(metrics)).digest("hex");
}
export function snapshotMetrics(
composition: readonly BenchmarkResult[],
compiler: Readonly<{
app: TscDiagnostics;
local: readonly Readonly<{ features: number; diagnostics: TscDiagnostics }>[];
}>,
): ScaleMetrics {
const round = (value: number) => Math.round(value * 1_000) / 1_000;
const toCompiler = (fixture: string, diagnostics: TscDiagnostics): CompilerEntry => ({
fixture,
files: diagnostics.files,
types: diagnostics.types,
symbols: diagnostics.symbols,
instantiations: diagnostics.instantiations,
});
return Object.freeze({
timing: composition
.map((result) => ({
workload: result.name,
profile: result.profile,
cardinality: result.cardinality,
medianMs: round(result.medianMs),
minMs: round(Math.min(...result.samples)),
}))
.sort((left, right) =>
`${left.workload}/${left.profile}`.localeCompare(`${right.workload}/${right.profile}`),
),
compiler: [
toCompiler("app", compiler.app),
...compiler.local.map((entry) => toCompiler(`local-${entry.features}`, entry.diagnostics)),
].sort((left, right) => left.fixture.localeCompare(right.fixture)),
});
}
export type Compatibility = Readonly<{
/** Baseline format, digest and metric coverage are usable at all. */
structural: Readonly<{ ok: boolean; reasons: readonly string[] }>;
/** Same compiler: deterministic compiler counts are comparable. */
compiler: Readonly<{ ok: boolean; reasons: readonly string[] }>;
/** Same machine class and runtime: timings are comparable. */
timing: Readonly<{ ok: boolean; reasons: readonly string[] }>;
}>;
export function checkCompatibility(
baseline: ScaleBaseline,
environment: ScaleEnvironment,
current: ScaleMetrics,
): Compatibility {
const structural: string[] = [];
if (baseline.schemaVersion !== SCALE_BASELINE_SCHEMA_VERSION) {
structural.push(`baseline schemaVersion ${String(baseline.schemaVersion)} is not ${SCALE_BASELINE_SCHEMA_VERSION}`);
}
if (metricsDigest(baseline.metrics) !== baseline.approval?.metricsDigest) {
structural.push("baseline metrics do not match their approved digest (hand-edited?)");
}
const timingKey = (entry: TimingEntry) => `${entry.workload}/${entry.profile}/${entry.cardinality}`;
const baselineTiming = new Set(baseline.metrics.timing.map(timingKey));
const baselineCompiler = new Set(baseline.metrics.compiler.map((entry) => entry.fixture));
for (const entry of current.timing) {
if (!baselineTiming.has(timingKey(entry))) structural.push(`no baseline for timing ${timingKey(entry)}`);
}
for (const entry of current.compiler) {
if (!baselineCompiler.has(entry.fixture)) structural.push(`no baseline for compiler fixture ${entry.fixture}`);
}
const compiler: string[] = [];
if (baseline.environment.typescript !== environment.typescript) {
compiler.push(`TypeScript ${environment.typescript} differs from baseline ${baseline.environment.typescript}`);
}
const timing: string[] = [];
const base = baseline.environment;
if (base.nodeMajor !== environment.nodeMajor) timing.push(`Node ${environment.nodeMajor} vs baseline ${base.nodeMajor}`);
if (base.platform !== environment.platform || base.arch !== environment.arch) {
timing.push(`${environment.platform}/${environment.arch} vs baseline ${base.platform}/${base.arch}`);
}
if (base.cpuModel !== environment.cpuModel) timing.push(`CPU "${environment.cpuModel}" vs baseline "${base.cpuModel}"`);
return Object.freeze({
structural: { ok: structural.length === 0, reasons: structural },
compiler: { ok: compiler.length === 0, reasons: compiler },
timing: { ok: timing.length === 0, reasons: timing },
});
}
export type RegressionFinding = Readonly<{
metric: string;
baseline: number;
current: number;
limit: number;
passed: boolean;
}>;
export type AxisResult = Readonly<{
passed: boolean;
findings: readonly RegressionFinding[];
}>;
export type BaselineComparison = Readonly<{
/**
* `passed` only when every axis was evaluated and held. `incomplete` when the
* environment is not timing-compatible: timing regression was not compared,
* so it is not evidence of a pass.
*/
status: "passed" | "failed" | "incomplete";
passed: boolean;
compatibility: Compatibility;
absolute: AxisResult;
growth: AxisResult;
compiler: readonly RegressionFinding[];
/** Empty when the environment is not timing-compatible. */
timing: readonly RegressionFinding[];
failures: readonly string[];
}>;
function finding(metric: string, baseline: number, current: number, limit: number): RegressionFinding {
return { metric, baseline, current, limit: Math.round(limit * 1_000) / 1_000, passed: current <= limit };
}
export function checkAbsoluteCeilings(current: ScaleMetrics): AxisResult {
const findings: RegressionFinding[] = [];
for (const entry of current.timing) {
const limit = ABSOLUTE_CEILINGS.timingMinMsByProfile[entry.profile];
if (limit !== undefined) {
findings.push(finding(`ceiling:time:${entry.workload}/${entry.profile}`, 0, entry.minMs, limit));
}
}
for (const entry of current.compiler) {
const local = /^local-(\d+)$/u.exec(entry.fixture);
for (const metric of ["files", "types", "symbols", "instantiations"] as const) {
const limit = local
? ABSOLUTE_CEILINGS.localBase[metric] +
ABSOLUTE_CEILINGS.localPerFeature[metric] * Number(local[1])
: entry.fixture === "app"
? ABSOLUTE_CEILINGS.app[metric]
: Number.POSITIVE_INFINITY;
findings.push(finding(`ceiling:tsc:${entry.fixture}:${metric}`, 0, entry[metric], limit));
}
}
return { passed: findings.every((item) => item.passed), findings };
}
export function checkGrowthShape(current: ScaleMetrics): AxisResult {
const findings: RegressionFinding[] = [];
const byWorkload = new Map<string, { n: number; cost: number }[]>();
for (const entry of current.timing) {
const series = byWorkload.get(entry.workload) ?? [];
series.push({ n: entry.cardinality, cost: entry.minMs });
byWorkload.set(entry.workload, series);
}
for (const [workload, series] of byWorkload) {
if (series.length < 2) continue;
const worst = Math.max(...growthExponents(series, GROWTH_LIMITS.timingNoiseFloorMs));
findings.push(finding(`growth:time:${workload}`, 1, Math.round(worst * 1_000) / 1_000, GROWTH_LIMITS.timingMaxExponent));
}
const local = current.compiler
.map((entry) => ({ entry, n: Number(/^local-(\d+)$/u.exec(entry.fixture)?.[1]) }))
.filter(({ n }) => Number.isFinite(n));
if (local.length >= 2) {
for (const metric of ["files", "types", "symbols", "instantiations"] as const) {
const worst = Math.max(...growthExponents(local.map(({ entry, n }) => ({ n, cost: entry[metric] }))));
findings.push(finding(`growth:tsc:local:${metric}`, 1, Math.round(worst * 1_000) / 1_000, GROWTH_LIMITS.compilerMaxExponent));
}
}
return { passed: findings.every((item) => item.passed), findings };
}
export function compareToBaseline(
baseline: ScaleBaseline,
environment: ScaleEnvironment,
current: ScaleMetrics,
tolerance = REGRESSION_TOLERANCE,
): BaselineComparison {
const compatibility = checkCompatibility(baseline, environment, current);
const failures: string[] = [...compatibility.structural.reasons];
// A different compiler changes every deterministic count: the baseline must
// be re-approved, it is never silently compared or silently skipped.
if (!compatibility.compiler.ok) {
failures.push(
...compatibility.compiler.reasons.map((reason) => `${reason}; re-approve with update:scale-baseline`),
);
}
const absolute = checkAbsoluteCeilings(current);
const growth = checkGrowthShape(current);
for (const item of [...absolute.findings, ...growth.findings]) {
if (!item.passed) failures.push(`${item.metric} ${item.current} exceeds ${item.limit}`);
}
const compiler: RegressionFinding[] = [];
if (compatibility.structural.ok && compatibility.compiler.ok) {
const byFixture = new Map(baseline.metrics.compiler.map((entry) => [entry.fixture, entry]));
for (const entry of current.compiler) {
const reference = byFixture.get(entry.fixture);
if (!reference) continue;
for (const metric of ["files", "types", "symbols", "instantiations"] as const) {
const item = finding(
`tsc:${entry.fixture}:${metric}`,
reference[metric],
entry[metric],
Math.floor(reference[metric] * (1 + tolerance.compilerRelative)),
);
compiler.push(item);
if (!item.passed) {
failures.push(`${item.metric} ${item.current} exceeds ${item.limit} (baseline ${item.baseline})`);
}
}
}
}
const timing: RegressionFinding[] = [];
if (compatibility.structural.ok && compatibility.timing.ok) {
const key = (entry: TimingEntry) => `${entry.workload}/${entry.profile}`;
const byKey = new Map(baseline.metrics.timing.map((entry) => [key(entry), entry]));
for (const entry of current.timing) {
const reference = byKey.get(key(entry));
if (!reference) continue;
// Best-observed samples: contention only ever adds time.
const item = finding(
`time:${key(entry)}`,
reference.minMs,
entry.minMs,
Math.max(reference.minMs * (1 + tolerance.timingRelative), reference.minMs + tolerance.timingNoiseFloorMs),
);
timing.push(item);
if (!item.passed) {
failures.push(`${item.metric} ${item.current}ms exceeds ${item.limit}ms (baseline ${item.baseline}ms)`);
}
}
}
const status =
failures.length > 0 ? "failed" : compatibility.timing.ok ? "passed" : "incomplete";
return Object.freeze({
status,
passed: status === "passed",
compatibility,
absolute,
growth,
compiler,
timing,
failures,
});
}
export function approveBaseline(
environment: ScaleEnvironment,
metrics: ScaleMetrics,
approval: Readonly<{ owner: string; reason: string; approvedAt: string }>,
): ScaleBaseline {
return Object.freeze({
schemaVersion: SCALE_BASELINE_SCHEMA_VERSION,
environment,
metrics,
approval: { ...approval, metricsDigest: metricsDigest(metrics) },
});
}
@@ -8,18 +8,19 @@ import path from "node:path";
import {
assertNoRuntimeImports,
createRemovalFixtureRoot,
prepareRemovalFixture,
pruneRemovalFixtureCiContract,
regenerateRemovalFixtureWorkflow,
removeRuntimeDependentTests,
renderRemovalJunit,
requireRemovalFixtureEnvironment,
runRemovalFixturePnpm,
runRemovalFixtureCheck,
type RemovalCheck,
} from "./lib/removal-fixture.ts";
const fixtureRoot = path.resolve(
".tmp/browser-file-storage-runtime-removal",
);
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
const fixtureRoot = await createRemovalFixtureRoot("browser-file-storage-runtime-removal");
const runtimePaths = [
"src/application/ports/browser-file-storage",
"src/application/ports/browser-transfer",
@@ -31,6 +32,8 @@ const runtimePaths = [
"src/adapters/storage/opfs",
"tests/browser-capabilities",
"tests/fixtures/browser-file-storage-boundaries",
// The composition example of this runtime goes with it.
"recipes/frontend-capabilities/indexeddb-feature-capability.ts",
] as const;
const runtimeSourceRoots = runtimePaths.filter((entry) =>
entry.startsWith("src/"),
@@ -45,124 +48,117 @@ const removedEvidencePathFragments = [
"browser-capabilities",
"browser-file-storage-runtime-removal",
] as const;
function runPnpm(script: string): boolean {
return runRemovalFixturePnpm(fixtureRoot, pnpmCli, script);
function check(name: string, script: string): RemovalCheck {
return runRemovalFixtureCheck(name, fixtureRoot, pnpmCli, script);
}
await prepareRemovalFixture(fixtureRoot);
let checks: RemovalCheck[];
let removedRuntimeTests: number;
try {
await prepareRemovalFixture(fixtureRoot);
const removedRuntimeTests =
await removeRuntimeDependentTests(fixtureRoot, runtimeSourceRoots);
for (const runtimePath of runtimePaths) {
await rm(path.join(fixtureRoot, runtimePath), {
recursive: true,
removedRuntimeTests =
await removeRuntimeDependentTests(fixtureRoot, runtimeSourceRoots);
for (const runtimePath of runtimePaths) {
await rm(path.join(fixtureRoot, runtimePath), {
recursive: true,
force: true,
});
}
const catalogPath = path.join(
fixtureRoot,
"config/recipes/frontend-capability-recipes.json",
);
const catalog = JSON.parse(await readFile(catalogPath, "utf8")) as {
recipes: Array<Record<string, unknown>>;
};
const browserFileRuntimeRecipeIds = new Set([
"offline-indexeddb",
"service-worker-pwa",
"file-transfer",
]);
let removedRuntimeEntries = 0;
for (const recipe of catalog.recipes) {
if (
typeof recipe.id !== "string" ||
!browserFileRuntimeRecipeIds.has(recipe.id) ||
!Object.hasOwn(recipe, "referenceRuntime")
) {
continue;
}
delete recipe.referenceRuntime;
removedRuntimeEntries += 1;
}
if (removedRuntimeEntries !== 3) {
throw new Error(
`Expected three reference runtime catalog entries, removed ${removedRuntimeEntries}`,
);
}
await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
await rm(path.join(fixtureRoot, "playwright.capabilities.config.ts"), {
force: true,
});
}
const catalogPath = path.join(
fixtureRoot,
"config/recipes/frontend-capability-recipes.json",
);
const catalog = JSON.parse(await readFile(catalogPath, "utf8")) as {
recipes: Array<Record<string, unknown>>;
};
const browserFileRuntimeRecipeIds = new Set([
"offline-indexeddb",
"service-worker-pwa",
"file-transfer",
]);
let removedRuntimeEntries = 0;
for (const recipe of catalog.recipes) {
if (
typeof recipe.id !== "string" ||
!browserFileRuntimeRecipeIds.has(recipe.id) ||
!Object.hasOwn(recipe, "referenceRuntime")
) {
continue;
}
delete recipe.referenceRuntime;
removedRuntimeEntries += 1;
}
if (removedRuntimeEntries !== 3) {
throw new Error(
`Expected three reference runtime catalog entries, removed ${removedRuntimeEntries}`,
await rm(
path.join(fixtureRoot, "scripts/check-browser-file-storage-boundaries.ts"),
{ force: true },
);
await rm(
path.join(fixtureRoot, "scripts/verify-browser-capability-evidence.ts"),
{ force: true },
);
await rm(
path.join(fixtureRoot, "scripts/test-browser-file-storage-runtime-removal.ts"),
{ force: true },
);
// The root snapshot locks the full repository inventory. This removal fixture
// validates its smaller registry through check:ci and its regenerated workflow.
await rm(
path.join(fixtureRoot, "tests/unit/ci-workflow-generation.test.ts"),
{ force: true },
);
await rm(
path.join(
fixtureRoot,
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
),
{ force: true },
);
}
await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
await rm(path.join(fixtureRoot, "playwright.capabilities.config.ts"), {
force: true,
});
await rm(
path.join(fixtureRoot, "scripts/check-browser-file-storage-boundaries.ts"),
{ force: true },
);
await rm(
path.join(fixtureRoot, "scripts/verify-browser-capability-evidence.ts"),
{ force: true },
);
await rm(
path.join(fixtureRoot, "scripts/test-browser-file-storage-runtime-removal.ts"),
{ force: true },
);
// The root snapshot locks the full repository inventory. This removal fixture
// validates its smaller registry through check:ci and its regenerated workflow.
await rm(
path.join(fixtureRoot, "tests/unit/ci-workflow-generation.test.ts"),
{ force: true },
);
await rm(
path.join(
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts,
removedEvidencePathFragments,
});
await regenerateRemovalFixtureWorkflow(fixtureRoot);
await assertNoRuntimeImports(
fixtureRoot,
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
),
{ force: true },
);
runtimeSourceRoots,
"browser file/storage",
);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts,
removedEvidencePathFragments,
});
await regenerateRemovalFixtureWorkflow(fixtureRoot);
await assertNoRuntimeImports(
fixtureRoot,
runtimeSourceRoots,
"browser file/storage",
);
const checks: Array<readonly [string, boolean]> = [
["typecheck", runPnpm("check:types")],
["lint", runPnpm("lint")],
["architecture", runPnpm("check:architecture")],
["test", runPnpm("test:all")],
["build", runPnpm("build")],
["optional-catalog", runPnpm("check:optional-recipes:source")],
["ci-contract", runPnpm("check:ci")],
];
const passed = checks.every(([, result]) => result);
checks = [
check("typecheck", "check:types"),
check("lint", "lint"),
check("architecture", "check:architecture"),
check("test", "test:all"),
check("build", "build"),
check("optional-catalog", "check:optional-recipes:source"),
check("ci-contract", "check:ci"),
];
} finally {
await rm(fixtureRoot, { recursive: true, force: true });
}
const failed = checks.filter((entry) => !entry.passed);
await mkdir("artifacts/tests", { recursive: true });
await writeFile(
"artifacts/tests/browser-file-storage-runtime-removal.xml",
`<?xml version="1.0" encoding="UTF-8"?>\n` +
`<testsuite name="browser-file-storage-runtime-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
checks
.map(
([name, result]) =>
`<testcase name="${name}">${result ? "" : "<failure />"}</testcase>`,
)
.join("") +
`</testsuite>\n`,
renderRemovalJunit("browser-file-storage-runtime-removal", checks),
);
await rm(fixtureRoot, { recursive: true, force: true });
if (!passed) {
if (failed.length > 0) {
process.stderr.write(
`Browser file/storage runtime removal failed: ${checks
.filter(([, result]) => !result)
.map(([name]) => name)
.join(", ")}\n`,
`Browser file/storage runtime removal failed: ${failed.map((entry) => entry.name).join(", ")}\n`,
);
process.exit(1);
}
+73 -73
View File
@@ -7,98 +7,98 @@ import {
import path from "node:path";
import {
createRemovalFixtureRoot,
filesBelow,
prepareRemovalFixture,
pruneRemovalFixtureCiContract,
pruneScriptOrchestration,
regenerateRemovalFixtureWorkflow,
renderRemovalJunit,
requireRemovalFixtureEnvironment,
runRemovalFixturePnpm,
runRemovalFixtureCheck,
type RemovalCheck,
} from "./lib/removal-fixture.ts";
const fixtureRoot = path.resolve(".tmp/optional-recipe-removal");
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
const fixtureRoot = await createRemovalFixtureRoot("optional-recipe-removal");
function runPnpm(script: string): boolean {
return runRemovalFixturePnpm(fixtureRoot, pnpmCli, script);
function check(name: string, script: string): RemovalCheck {
return runRemovalFixtureCheck(name, fixtureRoot, pnpmCli, script);
}
await prepareRemovalFixture(fixtureRoot);
for (const rootOnlyTest of [
"tests/unit/ci-workflow-generation.test.ts",
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
]) {
await rm(path.join(fixtureRoot, rootOnlyTest), { force: true });
}
await rm(path.join(fixtureRoot, "recipes"), { recursive: true, force: true });
await rm(path.join(fixtureRoot, "tests/recipes"), {
recursive: true,
force: true,
});
const removedCiScripts = new Set([
"check:types:recipes",
"test:recipes",
"check:optional-recipes",
"check:optional-recipes:source",
"check:optional-recipe-fixtures",
"test:optional-recipe-removal",
]);
const fixturePackagePath = path.join(fixtureRoot, "package.json");
const fixturePackage = JSON.parse(await readFile(fixturePackagePath, "utf8")) as {
scripts: Record<string, string>;
};
pruneScriptOrchestration(fixturePackage.scripts, "check:types", removedCiScripts);
pruneScriptOrchestration(fixturePackage.scripts, "test:all", removedCiScripts);
await writeFile(fixturePackagePath, `${JSON.stringify(fixturePackage, null, 2)}\n`);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts: removedCiScripts,
removedEvidencePathFragments: [
"optional-recipes",
"optional-recipe-fixtures",
"optional-recipe-removal",
],
});
await regenerateRemovalFixtureWorkflow(fixtureRoot);
const checks: Array<[string, boolean]> = [
["typecheck", runPnpm("check:types")],
["architecture", runPnpm("check:architecture")],
["test", runPnpm("test:all")],
["build", runPnpm("build")],
["ci-contract", runPnpm("check:ci")],
];
const residue: string[] = [];
for (const file of await filesBelow(path.join(fixtureRoot, "dist"))) {
if (!/\.(?:js|css|html|json)$/.test(file)) continue;
const content = await readFile(file, "utf8");
if (content.includes("frontend-optional-recipe-must-not-reach-production")) {
residue.push(path.relative(fixtureRoot, file));
let checks: RemovalCheck[];
try {
await prepareRemovalFixture(fixtureRoot);
for (const rootOnlyTest of [
"tests/unit/ci-workflow-generation.test.ts",
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
]) {
await rm(path.join(fixtureRoot, rootOnlyTest), { force: true });
}
await rm(path.join(fixtureRoot, "recipes"), { recursive: true, force: true });
await rm(path.join(fixtureRoot, "tests/recipes"), {
recursive: true,
force: true,
});
const removedCiScripts = new Set([
"check:types:recipes",
"test:recipes",
"check:optional-recipes",
"check:optional-recipes:source",
"check:optional-recipe-fixtures",
"test:optional-recipe-removal",
]);
const fixturePackagePath = path.join(fixtureRoot, "package.json");
const fixturePackage = JSON.parse(await readFile(fixturePackagePath, "utf8")) as {
scripts: Record<string, string>;
};
pruneScriptOrchestration(fixturePackage.scripts, "check:types", removedCiScripts);
pruneScriptOrchestration(fixturePackage.scripts, "test:all", removedCiScripts);
await writeFile(fixturePackagePath, `${JSON.stringify(fixturePackage, null, 2)}\n`);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts: removedCiScripts,
removedEvidencePathFragments: [
"optional-recipes",
"optional-recipe-fixtures",
"optional-recipe-removal",
],
});
await regenerateRemovalFixtureWorkflow(fixtureRoot);
checks = [
check("typecheck", "check:types"),
check("architecture", "check:architecture"),
check("test", "test:all"),
check("build", "build"),
check("ci-contract", "check:ci"),
];
const residue: string[] = [];
for (const file of await filesBelow(path.join(fixtureRoot, "dist")).catch(() => [])) {
if (!/\.(?:js|css|html|json)$/.test(file)) continue;
const content = await readFile(file, "utf8");
if (content.includes("frontend-optional-recipe-must-not-reach-production")) {
residue.push(path.relative(fixtureRoot, file));
}
}
checks.push(
residue.length === 0
? { name: "bundle-residue", passed: true }
: { name: "bundle-residue", passed: false, failure: `residue: ${residue.join(", ")}` },
);
} finally {
await rm(fixtureRoot, { recursive: true, force: true });
}
checks.push(["bundle-residue", residue.length === 0]);
const passed = checks.every(([, result]) => result);
const failed = checks.filter((entry) => !entry.passed);
await mkdir("artifacts/tests", { recursive: true });
await writeFile(
"artifacts/tests/optional-recipe-removal.xml",
`<?xml version="1.0" encoding="UTF-8"?>\n` +
`<testsuite name="optional-recipe-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
checks
.map(
([name, result]) =>
`<testcase name="${name}">${result ? "" : `<failure>${residue.join(", ")}</failure>`}</testcase>`,
)
.join("") +
`</testsuite>\n`,
renderRemovalJunit("optional-recipe-removal", checks),
);
await rm(fixtureRoot, { recursive: true, force: true });
if (!passed) {
if (failed.length > 0) {
process.stderr.write(
`Optional recipe removal failed: ${checks
.filter(([, result]) => !result)
.map(([name]) => name)
.join(", ")}\n`,
`Optional recipe removal failed: ${failed.map((entry) => entry.name).join(", ")}\n`,
);
process.exit(1);
}
+174 -43
View File
@@ -1,11 +1,19 @@
import { spawn } from "node:child_process";
import { mkdir, readFile } from "node:fs/promises";
import { performance } from "node:perf_hooks";
import { cpus, loadavg } from "node:os";
import process from "node:process";
import { chromium } from "@playwright/test";
import { chromium, type Browser } from "@playwright/test";
import { evaluateLabBudget } from "../src/application/policies/performance-budgets.ts";
import {
assertPortUnused,
assertServedRelease,
DEFAULT_LAB_PORT,
DEFAULT_LAB_RUNS,
previewArguments,
summarizeSamples,
} from "./lib/lab-performance.ts";
import { evaluateLabBudget } from "./lib/performance-budgets.ts";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import { labPerformanceArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
@@ -13,6 +21,9 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type ContractPerformanceEvidence = {
lcpMs: number;
cls: number;
clickAt: number | null;
headingAt: number | null;
eventDurationMs: number | null;
};
type ContractPerformanceWindow = Window & {
@@ -24,15 +35,44 @@ type LayoutShiftEntry = PerformanceEntry & {
value: number;
};
const server = spawn(
"corepack",
["pnpm", "preview", "--host", "127.0.0.1", "--port", "4173"],
{ stdio: "ignore" },
);
const baseUrl = "http://127.0.0.1:4173";
const argument = (name: string) =>
process.argv.find((entry) => entry.startsWith(`--${name}=`))?.slice(name.length + 3);
const port = Number(process.env.LAB_PERFORMANCE_PORT ?? DEFAULT_LAB_PORT);
const runs = Number(argument("runs") ?? DEFAULT_LAB_RUNS);
if (!Number.isSafeInteger(port) || port <= 0 || !Number.isSafeInteger(runs) || runs < 1) {
throw new TypeError("LAB_PERFORMANCE_PORT must be a port and --runs a positive integer.");
}
const baseUrl = `http://127.0.0.1:${port}`;
// Template sync (af3d8e6). The named interaction is this product's first
// primary navigation entry: from the landing page to Explore. The previous
// sync measured the landing heading alone, which the template's page-clock
// interaction (click to target heading) cannot express.
const target = ROUTE_REGISTRY.TECH_LOG_EXPLORE;
const navigationLabel = target.navigationLabel;
if (!navigationLabel) {
throw new Error("Performance route must be present in navigation.");
}
// TechLog's route labels are typed `string | null`; the check above is what
// makes this one a string inside the hoisted measurement function too.
const targetLabel: string = navigationLabel;
// 11-07. A server already on the port used to be measured in place of this
// build: vite moved to another port and the gate never noticed.
await assertPortUnused(baseUrl);
// Its own process group: `corepack` starts pnpm, which starts vite, and a
// signal to `corepack` alone left vite serving the port after the gate ended.
const server = spawn("corepack", [...previewArguments(port)], {
stdio: "ignore",
detached: true,
});
let serverExit: string | null = null;
server.on("exit", (code, signal) => {
serverExit = `preview server exited (${signal ?? code})`;
});
async function waitForServer() {
for (let attempt = 0; attempt < 50; attempt += 1) {
for (let attempt = 0; attempt < 100; attempt += 1) {
if (serverExit) throw new Error(serverExit);
try {
const response = await fetch(baseUrl);
if (response.ok) return;
@@ -44,19 +84,14 @@ async function waitForServer() {
throw new Error("Preview server did not become ready.");
}
try {
await waitForServer();
const release = JSON.parse(
await readFile("dist/release-manifest.json", "utf8"),
);
const thresholds = JSON.parse(
await readFile("config/performance/budgets.json", "utf8"),
).lab;
const browser = await chromium.launch();
type RunMetrics = { lcpMs: number; cls: number; namedInteractionMs: number; eventDurationMs: number | null };
async function measureOnce(browser: Browser): Promise<RunMetrics> {
// Every run is a cold, isolated context.
const context = await browser.newContext({
viewport: { width: 1280, height: 720 },
});
try {
const context = await browser.newContext({
viewport: { width: 1280, height: 720 },
});
const page = await context.newPage();
const cdp = await context.newCDPSession(page);
await cdp.send("Network.enable");
@@ -68,8 +103,14 @@ try {
connectionType: "cellular4g",
});
await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 });
await page.addInitScript(() => {
const evidence = { lcpMs: 0, cls: 0 };
await page.addInitScript((title: string) => {
const evidence: ContractPerformanceEvidence = {
lcpMs: 0,
cls: 0,
clickAt: null,
headingAt: null,
eventDurationMs: null,
};
(window as ContractPerformanceWindow).__contractPerformance = evidence;
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) evidence.lcpMs = entry.startTime;
@@ -82,30 +123,97 @@ try {
}
}
}).observe({ type: "layout-shift", buffered: true });
});
// 11-07. The interaction is timed by the page's own clock, from the
// click event to the target heading entering the DOM, so Playwright's
// round trips are not in it. The Event Timing entry of the click (the
// INP input) is recorded next to it.
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.name === "click") {
evidence.eventDurationMs = Math.max(evidence.eventDurationMs ?? 0, entry.duration);
}
}
}).observe({ type: "event", buffered: true, durationThreshold: 16 } as PerformanceObserverInit);
document.addEventListener(
"click",
(event) => {
evidence.clickAt ??= event.timeStamp;
},
{ capture: true },
);
new MutationObserver((_records, observer) => {
if (evidence.clickAt === null) return;
const found = [...document.querySelectorAll("h1, h2")].some(
(heading) => heading.textContent?.trim() === title,
);
if (found) {
evidence.headingAt = performance.now();
observer.disconnect();
}
}).observe(document, { childList: true, subtree: true, characterData: true });
}, target.title);
await page.goto(baseUrl, { waitUntil: "networkidle" });
const target = ROUTE_REGISTRY.TECH_LOG_HOME;
const interactionStarted = performance.now();
// Template merge. The template clicked a navigation link here; this
// product measures its own landing route, which `goto` already reached, so
// there is no click and no `targetLabel`. The template's lesson is kept
// because it applies to whatever click lands here next: Playwright matches
// accessible names by substring, so a nav entry can also match a call to
// action and resolve to two links — a strict-mode violation before the
// first measurement, which produces no performance evidence at all.
// Playwright matches accessible names by substring, so a navigation entry
// can also match a call to action that contains it; `exact` keeps the
// locator on the navigation link.
await page.getByRole("link", { name: targetLabel, exact: true }).click();
await page.getByRole("heading", { name: target.title }).waitFor();
const namedInteractionMs = performance.now() - interactionStarted;
await page.waitForFunction(
() => (window as ContractPerformanceWindow).__contractPerformance?.headingAt !== null,
);
const paint = await page.evaluate(
() => (window as ContractPerformanceWindow).__contractPerformance,
);
if (!paint) {
if (!paint || paint.clickAt === null || paint.headingAt === null) {
throw new Error("Browser performance evidence was not initialized.");
}
return {
lcpMs: Math.round(paint.lcpMs),
cls: Number(paint.cls.toFixed(4)),
namedInteractionMs: Math.round(paint.headingAt - paint.clickAt),
eventDurationMs:
paint.eventDurationMs === null ? null : Math.round(paint.eventDurationMs),
};
} finally {
await context.close();
}
}
const load = () => loadavg().map((value) => Math.round(value * 100) / 100);
try {
await waitForServer();
const release = JSON.parse(
await readFile("dist/release-manifest.json", "utf8"),
);
await assertServedRelease(baseUrl, release);
const thresholds = JSON.parse(
await readFile("config/performance/budgets.json", "utf8"),
).lab;
const browser = await chromium.launch();
try {
const loadBefore = load();
const samples: RunMetrics[] = [];
for (let run = 0; run < runs; run += 1) samples.push(await measureOnce(browser));
const loadAfter = load();
// The served build must not have changed under the runs either.
await assertServedRelease(baseUrl, release);
const lcp = summarizeSamples(samples.map((sample) => sample.lcpMs));
const cls = summarizeSamples(samples.map((sample) => sample.cls));
const interaction = summarizeSamples(
samples.map((sample) => sample.namedInteractionMs),
);
const eventDurations = samples.flatMap((sample) =>
sample.eventDurationMs === null ? [] : [sample.eventDurationMs],
);
const contextMetadata = {
runner: {
platform: process.platform,
architecture: process.arch,
nodeVersion: process.version,
cpuModel: cpus()[0]?.model.trim() ?? "unknown",
logicalCpus: cpus().length,
loadAverage: { before: loadBefore, after: loadAfter },
},
browser: { name: "chromium", version: await browser.version() },
viewport: { width: 1280, height: 720 },
@@ -117,12 +225,29 @@ try {
},
cpu: { throttlingRate: 4 },
cache: { state: "cold", isolation: "new-browser-context" },
build: { buildId: release.buildId, releaseId: release.releaseId },
build: {
buildId: release.buildId,
releaseId: release.releaseId,
served: `${baseUrl}/release-manifest.json`,
},
// 11-07. The budget is judged on the median of cold runs; every run and
// the spread stay in the evidence.
sampling: {
runs,
statistic: "median",
interactionClock: "page: click event to target heading in DOM",
lcpMs: lcp,
cls,
namedInteractionMs: interaction,
clickEventDurationMs: eventDurations.length
? summarizeSamples(eventDurations)
: null,
},
};
const metrics = {
lcpMs: Math.round(paint.lcpMs),
cls: Number(paint.cls.toFixed(4)),
namedInteractionMs: Math.round(namedInteractionMs),
lcpMs: lcp.median,
cls: cls.median,
namedInteractionMs: interaction.median,
};
const result = evaluateLabBudget(
{ context: contextMetadata, metrics },
@@ -160,14 +285,20 @@ try {
},
});
if (!passed) {
throw new Error(`Lab performance failed: ${JSON.stringify(metrics)}`);
throw new Error(
`Lab performance failed (median of ${runs}): ${JSON.stringify(metrics)}; ` +
`interaction samples ${interaction.samples.join(",")}`,
);
}
process.stdout.write(
`Lab performance: PASS (LCP ${metrics.lcpMs}ms, CLS ${metrics.cls}, interaction ${metrics.namedInteractionMs}ms)\n`,
`Lab performance: PASS, median of ${runs} (LCP ${metrics.lcpMs}ms, CLS ${metrics.cls}, interaction ${metrics.namedInteractionMs}ms ` +
`[${interaction.min}-${interaction.max}])\n`,
);
} finally {
await browser.close();
}
} finally {
server.kill("SIGTERM");
if (server.pid !== undefined && serverExit === null) {
process.kill(-server.pid, "SIGTERM");
}
}
+91 -95
View File
@@ -8,16 +8,19 @@ import path from "node:path";
import {
assertNoRuntimeImports,
createRemovalFixtureRoot,
prepareRemovalFixture,
pruneRemovalFixtureCiContract,
regenerateRemovalFixtureWorkflow,
removeRuntimeDependentTests,
renderRemovalJunit,
requireRemovalFixtureEnvironment,
runRemovalFixturePnpm,
runRemovalFixtureCheck,
type RemovalCheck,
} from "./lib/removal-fixture.ts";
const fixtureRoot = path.resolve(".tmp/realtime-runtime-removal");
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
const fixtureRoot = await createRemovalFixtureRoot("realtime-runtime-removal");
const runtimePaths = [
"src/application/ports/realtime",
"src/application/ports/out/web-push-control.ts",
@@ -41,111 +44,104 @@ const removedEvidencePathFragments = [
"realtime-boundaries",
"realtime-runtime-removal",
] as const;
function runPnpm(script: string): boolean {
return runRemovalFixturePnpm(fixtureRoot, pnpmCli, script);
function check(name: string, script: string): RemovalCheck {
return runRemovalFixtureCheck(name, fixtureRoot, pnpmCli, script);
}
await prepareRemovalFixture(fixtureRoot);
let checks: RemovalCheck[];
let removedRuntimeTests: number;
try {
await prepareRemovalFixture(fixtureRoot);
const removedRuntimeTests =
await removeRuntimeDependentTests(fixtureRoot, runtimeSourceRoots);
for (const runtimePath of runtimePaths) {
await rm(path.join(fixtureRoot, runtimePath), {
recursive: true,
force: true,
});
}
removedRuntimeTests =
await removeRuntimeDependentTests(fixtureRoot, runtimeSourceRoots);
for (const runtimePath of runtimePaths) {
await rm(path.join(fixtureRoot, runtimePath), {
recursive: true,
force: true,
});
}
const outputPortsIndexPath = path.join(
fixtureRoot,
"src/application/ports/out/index.ts",
);
const outputPortsIndex = await readFile(outputPortsIndexPath, "utf8");
await writeFile(
outputPortsIndexPath,
outputPortsIndex.replace(
'export type { WebPushControlPort } from "./web-push-control.ts";\n',
"",
),
);
const catalogPath = path.join(
fixtureRoot,
"config/recipes/frontend-capability-recipes.json",
);
const catalog = JSON.parse(await readFile(catalogPath, "utf8")) as {
recipes: Array<Record<string, unknown>>;
};
const realtimeRecipe = catalog.recipes.find(
(recipe) => recipe.id === "realtime",
);
if (!realtimeRecipe || !Object.hasOwn(realtimeRecipe, "referenceRuntime")) {
throw new Error("Expected realtime reference runtime catalog entry");
}
delete realtimeRecipe.referenceRuntime;
await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
for (const scriptPath of [
"scripts/check-realtime-boundaries.ts",
"scripts/check-realtime-boundary-fixtures.ts",
"scripts/lib/realtime-boundaries.ts",
"scripts/test-realtime-runtime-removal.ts",
]) {
await rm(path.join(fixtureRoot, scriptPath), { force: true });
}
// The root snapshot locks the full repository inventory. This removal fixture
// validates its smaller registry through check:ci and its regenerated workflow.
await rm(
path.join(fixtureRoot, "tests/unit/ci-workflow-generation.test.ts"),
{ force: true },
);
await rm(
path.join(
const outputPortsIndexPath = path.join(
fixtureRoot,
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
),
{ force: true },
);
"src/application/ports/out/index.ts",
);
const outputPortsIndex = await readFile(outputPortsIndexPath, "utf8");
await writeFile(
outputPortsIndexPath,
outputPortsIndex.replace(
'export type { WebPushControlPort } from "./web-push-control.ts";\n',
"",
),
);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts: new Set<string>(runtimeScripts),
removedEvidencePathFragments,
});
await regenerateRemovalFixtureWorkflow(fixtureRoot);
await assertNoRuntimeImports(fixtureRoot, runtimeSourceRoots, "realtime");
const catalogPath = path.join(
fixtureRoot,
"config/recipes/frontend-capability-recipes.json",
);
const catalog = JSON.parse(await readFile(catalogPath, "utf8")) as {
recipes: Array<Record<string, unknown>>;
};
const realtimeRecipe = catalog.recipes.find(
(recipe) => recipe.id === "realtime",
);
if (!realtimeRecipe || !Object.hasOwn(realtimeRecipe, "referenceRuntime")) {
throw new Error("Expected realtime reference runtime catalog entry");
}
delete realtimeRecipe.referenceRuntime;
await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
const checks: Array<readonly [string, boolean]> = [
["typecheck", runPnpm("check:types")],
["lint", runPnpm("lint")],
["architecture", runPnpm("check:architecture")],
["test", runPnpm("test:all")],
["build", runPnpm("build")],
["optional-catalog", runPnpm("check:optional-recipes:source")],
["ci-contract", runPnpm("check:ci")],
];
const passed = checks.every(([, result]) => result);
for (const scriptPath of [
"scripts/check-realtime-boundaries.ts",
"scripts/check-realtime-boundary-fixtures.ts",
"scripts/lib/realtime-boundaries.ts",
"scripts/test-realtime-runtime-removal.ts",
]) {
await rm(path.join(fixtureRoot, scriptPath), { force: true });
}
// The root snapshot locks the full repository inventory. This removal fixture
// validates its smaller registry through check:ci and its regenerated workflow.
await rm(
path.join(fixtureRoot, "tests/unit/ci-workflow-generation.test.ts"),
{ force: true },
);
await rm(
path.join(
fixtureRoot,
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
),
{ force: true },
);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts: new Set<string>(runtimeScripts),
removedEvidencePathFragments,
});
await regenerateRemovalFixtureWorkflow(fixtureRoot);
await assertNoRuntimeImports(fixtureRoot, runtimeSourceRoots, "realtime");
checks = [
check("typecheck", "check:types"),
check("lint", "lint"),
check("architecture", "check:architecture"),
check("test", "test:all"),
check("build", "build"),
check("optional-catalog", "check:optional-recipes:source"),
check("ci-contract", "check:ci"),
];
} finally {
await rm(fixtureRoot, { recursive: true, force: true });
}
const failed = checks.filter((entry) => !entry.passed);
await mkdir("artifacts/tests", { recursive: true });
await writeFile(
"artifacts/tests/realtime-runtime-removal.xml",
`<?xml version="1.0" encoding="UTF-8"?>\n` +
`<testsuite name="realtime-runtime-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
checks
.map(
([name, result]) =>
`<testcase name="${name}">${result ? "" : "<failure />"}</testcase>`,
)
.join("") +
`</testsuite>\n`,
renderRemovalJunit("realtime-runtime-removal", checks),
);
await rm(fixtureRoot, { recursive: true, force: true });
if (!passed) {
if (failed.length > 0) {
process.stderr.write(
`Realtime runtime removal failed: ${checks
.filter(([, result]) => !result)
.map(([name]) => name)
.join(", ")}\n`,
`Realtime runtime removal failed: ${failed.map((entry) => entry.name).join(", ")}\n`,
);
process.exit(1);
}
+248 -294
View File
@@ -1,32 +1,178 @@
import {
access,
mkdir,
mkdtemp,
readdir,
readFile,
rm,
writeFile,
} from "node:fs/promises";
import path from "node:path";
import { ROUTE_FEATURE_OWNER } from "../src/features/installed-feature-contracts.ts";
import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts";
import { isProductionModulePath } from "./lib/risk-coverage.ts";
import {
createRemovalFixtureRoot,
filesBelow,
prepareRemovalFixture,
pruneRemovalFixtureCiContract,
pruneScriptOrchestration,
regenerateRemovalFixtureWorkflow,
renderRemovalJunit,
requireRemovalFixtureEnvironment,
runRemovalFixtureCheck,
runRemovalFixturePnpm,
type RemovalCheck,
} from "./lib/removal-fixture.ts";
const fixtureParent = path.resolve(".tmp");
await mkdir(fixtureParent, { recursive: true });
const fixtureRoot = await mkdtemp(
path.join(fixtureParent, "reference-feature-removal-"),
);
/**
* 09-07 (D-10). Removes one installed feature, `--feature=<id>` (default: the
* reference sample), from a copy of the repository and proves the rest still
* typechecks, tests, covers and builds. Every feature loses its directory, its
* tests/features directory, its context when no other feature is left in it,
* its runtime-profile override and its central policy rows. The sample also
* owns the extra paths and scripts listed in SAMPLE_EXTRAS.
*/
const featureId =
process.argv.find((argument) => argument.startsWith("--feature="))
?.slice("--feature=".length) ?? "reference-feature";
type FeatureExtras = Readonly<{
paths: readonly string[];
ciScripts: readonly string[];
evidencePathFragments: readonly string[];
residue: RegExp;
}>;
const SAMPLE_EXTRAS: Readonly<Record<string, FeatureExtras>> = Object.freeze({
"reference-feature": Object.freeze({
paths: [
"tests/integration/http-scenario-catalog.test.ts",
"tests/component/product-feature-switch.test.tsx",
// Template sync (ebea300). This TechLog test imports the sample feature's
// contract contribution on purpose — it proves a 403 on *another*
// feature's operation does not discard TechLog's CSRF token, which needs
// a second feature to exist. With the sample gone the premise is gone,
// so the test goes with it rather than being rewritten around a feature
// that is not there.
"tests/features/tech-log/studio-csrf-composition.test.ts",
// Template sync (af3d8e6). The sample is not installed here (its
// directory carries NOT_INSTALLED), so its bounded context owns no other
// feature and goes with it, as upstream removes a context with its last
// feature.
"src/contexts/reference-context",
"tests/e2e/reference-form.spec.ts",
"tests/e2e/reference-route.spec.ts",
"tests/e2e/reference-save.spec.ts",
// 11-04: the growth measurement copies this sample feature.
"tests/unit/feature-shape-growth.test.ts",
"scripts/scale/measure-feature-shape-growth.ts",
"config/scale/feature-shape-growth.json",
"config/scale/feature-shape-ceilings.json",
"tests/mocks",
"tests/fixtures/typecheck/invalid-feature-input.ts",
"tests/fixtures/typecheck/invalid-reference-operation.ts",
"tests/fixtures/typecheck/invalid-http-operation-input.ts",
"tests/fixtures/typecheck/invalid-http-wire-mapper.ts",
"tests/fixtures/typecheck/invalid-http-operation-id.ts",
"tests/fixtures/typecheck/invalid-http-route-id.ts",
"tests/fixtures/typecheck/invalid-feature-contribution-input.ts",
"tests/fixtures/typecheck/invalid-feature-capability-selection.ts",
"tests/fixtures/typecheck/tsconfig.feature-input.json",
"tests/fixtures/typecheck/tsconfig.reference-operation.json",
"tests/fixtures/typecheck/tsconfig.http-operation-input.json",
"tests/fixtures/typecheck/tsconfig.http-wire-mapper.json",
"tests/fixtures/typecheck/tsconfig.http-operation-id.json",
"tests/fixtures/typecheck/tsconfig.http-route-id.json",
"tests/fixtures/typecheck/tsconfig.feature-contribution-input.json",
"tests/fixtures/typecheck/tsconfig.feature-capability-selection.json",
],
ciScripts: [
"check:types:fixture:feature-input",
"check:types:fixture:reference-operation",
"check:types:fixture:http-operation-input",
"check:types:fixture:http-wire-mapper",
"check:types:fixture:http-operation-id",
"check:types:fixture:http-route-id",
"check:types:fixture:feature-contribution-input",
"check:types:fixture:feature-capability-selection",
"test:http-scenario-evidence",
"test:reference-feature",
],
evidencePathFragments: [
"reference-feature.xml",
"http-scenario-executions",
"http-scenario-evidence",
],
residue: /REFERENCE_RESOURCE|reference-feature|reference-resource/i,
}),
});
function escapeRegExp(value: string): string {
return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
}
async function locateFeature(id: string) {
// Template sync (af3d8e6). A feature directory marked NOT_INSTALLED is not
// declared to the generator, so it has no context to look up; its directory
// is still what removal deletes. This product's sample is in that state.
const marker = await access(path.join("src/features", id, "NOT_INSTALLED")).then(
() => true,
() => false,
);
if (marker) {
return Object.freeze({ directory: id, contextDirectory: null });
}
const source = await createFileSystemDeclarationSource(process.cwd());
for (const appId of source.appIds()) {
for (const context of source.contextsOf(appId)) {
const features = source.featuresOf(context.id);
const feature = features.find((candidate) => candidate.id === id);
if (!feature) continue;
let contextDirectory: string | null = null;
for (const entry of await readdir("src/contexts", { withFileTypes: true })) {
if (!entry.isDirectory()) continue;
const declaration = await readFile(
path.join("src/contexts", entry.name, "context-module.ts"),
"utf8",
).catch(() => "");
if (
new RegExp(`CONTEXT_MODULE_ID\\s*=\\s*["']${escapeRegExp(context.id)}["']`, "u")
.test(declaration)
) {
contextDirectory = `src/contexts/${entry.name}`;
}
}
return Object.freeze({
directory: feature.directory,
// The context goes with its last feature.
contextDirectory: features.length === 1 ? contextDirectory : null,
});
}
}
throw new Error(`No installed feature declares FEATURE_MODULE_ID "${id}"`);
}
const located = await locateFeature(featureId);
const extras: FeatureExtras = SAMPLE_EXTRAS[featureId] ?? Object.freeze({
paths: [],
ciScripts: [],
evidencePathFragments: [],
residue: new RegExp(
`${escapeRegExp(featureId)}|${escapeRegExp(located.directory)}`,
"i",
),
});
// Captured from this repository before the copy loses them.
const featureRouteIds = Object.entries(ROUTE_FEATURE_OWNER)
.filter(([, owner]) => owner === featureId)
.map(([routeId]) => routeId);
const fixtureRoot = await createRemovalFixtureRoot(`${featureId}-removal`);
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
const featureSource = "src/features/reference-feature";
const featureTests = "tests/features/reference-feature";
const featureSource = `src/features/${located.directory}`;
const featureTests = `tests/features/${located.directory}`;
const isSample = featureId in SAMPLE_EXTRAS;
/**
* Platform tests that must survive the sample feature's removal. Asserting they
* are still present is what stops the removal fixture from "passing" by having
@@ -41,165 +187,12 @@ const commonTestPaths = [
const featureOwnedPaths = [
featureSource,
featureTests,
"tests/integration/http-scenario-catalog.test.ts",
"tests/features/tech-log/runtime-composition.test.ts",
// Template sync (ebea300). The kill-switch test attributes a real route to a
// real installed feature id; with the sample feature gone there is no
// installed feature left to attribute to, so it goes with it.
"tests/component/product-feature-switch.test.tsx",
// Same sync. This TechLog test imports the sample feature's contract
// contribution on purpose — it proves a 403 on *another* feature's operation
// does not discard TechLog's CSRF token, which needs a second feature to
// exist. With the sample feature gone the premise is gone, so the test goes
// with it rather than being rewritten around a feature that is not there.
"tests/features/tech-log/studio-csrf-composition.test.ts",
"tests/e2e/reference-form.spec.ts",
"tests/e2e/reference-route.spec.ts",
"tests/mocks",
"tests/fixtures/typecheck/invalid-feature-input.ts",
"tests/fixtures/typecheck/invalid-reference-operation.ts",
"tests/fixtures/typecheck/invalid-http-operation-input.ts",
"tests/fixtures/typecheck/invalid-http-wire-mapper.ts",
"tests/fixtures/typecheck/invalid-http-operation-id.ts",
"tests/fixtures/typecheck/invalid-http-route-id.ts",
"tests/fixtures/typecheck/invalid-feature-contribution-input.ts",
"tests/fixtures/typecheck/invalid-feature-capability-selection.ts",
"tests/fixtures/typecheck/tsconfig.feature-input.json",
"tests/fixtures/typecheck/tsconfig.reference-operation.json",
"tests/fixtures/typecheck/tsconfig.http-operation-input.json",
"tests/fixtures/typecheck/tsconfig.http-wire-mapper.json",
"tests/fixtures/typecheck/tsconfig.http-operation-id.json",
"tests/fixtures/typecheck/tsconfig.http-route-id.json",
"tests/fixtures/typecheck/tsconfig.feature-contribution-input.json",
"tests/fixtures/typecheck/tsconfig.feature-capability-selection.json",
// The feature's bounded-context declaration when it was the last feature in
// it; the template app stays.
...(located.contextDirectory === null ? [] : [located.contextDirectory]),
...extras.paths,
];
const emptyProductManifest = `export const COMPILED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze([]);
export const INSTALLED_PRODUCT_FEATURES: readonly never[] = Object.freeze([]);
export const INSTALLED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze([]);
`;
const emptyContracts = `import type { RouteDefinition } from "../contracts/routes.ts";
import { PLATFORM_SCHEMA_REGISTRY } from "../contracts/schema-registry.ts";
import { INSTALLED_PRODUCT_FEATURES } from "./installed-product-manifest.ts";
import {
TECH_LOG_ROUTE_REGISTRY,
TECH_LOG_ROUTE_RUNTIME_CONTRACT,
TECH_LOG_ROUTE_SCHEMA_REGISTRY,
} from "./tech-log/contracts/tech-log-route-contract.ts";
export const INSTALLED_FEATURE_CONTRACTS = INSTALLED_PRODUCT_FEATURES;
export const ROUTE_REGISTRY = TECH_LOG_ROUTE_REGISTRY;
export const ROUTE_RUNTIME_CONTRACT = TECH_LOG_ROUTE_RUNTIME_CONTRACT;
export const API_OPERATIONS = Object.freeze({});
export const INVALIDATION_REGISTRY = Object.freeze({
topics: Object.freeze([]),
namespaces: Object.freeze([]),
edges: Object.freeze([]),
});
export const INVALIDATION_TOPIC_VERSIONS = Object.freeze([]);
export const SCHEMA_REGISTRY = Object.freeze({
...PLATFORM_SCHEMA_REGISTRY,
...TECH_LOG_ROUTE_SCHEMA_REGISTRY,
});
export const ROUTE_FEATURE_OWNER: Readonly<Record<string, string>> = Object.freeze({});
export const NAVIGATION_ROUTES = Object.freeze(
Object.values(ROUTE_REGISTRY)
.filter((definition) => definition.navigationOrder !== null)
.sort(
(left, right) =>
left.navigationOrder! - right.navigationOrder!,
),
);
export function getRoute(routeId: string): RouteDefinition {
const registry = ROUTE_REGISTRY as Readonly<Record<string, RouteDefinition>>;
const selected = registry[routeId];
if (!selected) throw new Error(\`Unregistered route: \${routeId}\`);
return selected;
}
export function routePath(routeId: string): string {
return getRoute(routeId).path;
}
`;
const emptyRuntimes = `import { PLATFORM_ROUTE_CODECS } from "../presentation/routes/platform-route-codecs.ts";
import { TECH_LOG_ROUTE_CODECS } from "./tech-log/presentation/tech-log-route-codecs.ts";
import { TECH_LOG_ROUTE_RUNTIME } from "./tech-log/presentation/tech-log-route-runtime.tsx";
export const ROUTE_CODECS = Object.freeze({
...PLATFORM_ROUTE_CODECS,
...TECH_LOG_ROUTE_CODECS,
});
export const ROUTE_RUNTIME = TECH_LOG_ROUTE_RUNTIME;
`;
const emptyAdapters = `import type { InstalledHttpOperationExecutor } from "../adapters/http/index.ts";
import type { ApplicationFeatureInputs } from "../application/ports/in/application-api.ts";
import {
composeFeatureAdapterInputs,
type InstalledFeatureInputs,
} from "./feature-adapter-contribution.ts";
import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts";
import {
createTechLogFeatureInstalledInput,
type TechLogInstallContext,
} from "./tech-log/adapters/create-tech-log-feature-input.ts";
import { TECH_LOG_FEATURE_ID } from "./tech-log/application/tech-log-feature-input.ts";
const COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS = Object.freeze([] as const);
type ProductFeatureInputs = InstalledFeatureInputs &
Readonly<Pick<ApplicationFeatureInputs, typeof TECH_LOG_FEATURE_ID>>;
export function createInstalledFeatureInputs(
context: TechLogInstallContext &
Readonly<{ http: InstalledHttpOperationExecutor }>,
): ProductFeatureInputs {
const techLog = createTechLogFeatureInstalledInput(context);
return Object.freeze({
...composeFeatureAdapterInputs(
COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS,
INSTALLED_PRODUCT_FEATURE_IDS,
context,
),
[techLog.featureId]: techLog.input,
}) as ProductFeatureInputs;
}
`;
const emptyContractContributions = `import {
composeContractContributions,
type InstalledContractContribution,
type InstalledContractPackageIdentity,
} from "../contracts/external-contract-runtime.ts";
import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts";
const COMPILED_CONTRACT_CONTRIBUTIONS: readonly InstalledContractContribution[] =
Object.freeze([]);
export const INSTALLED_CONTRACT_CONTRIBUTIONS: readonly InstalledContractContribution[] =
Object.freeze(
COMPILED_CONTRACT_CONTRIBUTIONS.filter((contribution) =>
INSTALLED_PRODUCT_FEATURE_IDS.includes(contribution.featureId),
),
);
export const COMPOSED_CONTRACT_CONTRIBUTIONS = composeContractContributions(
INSTALLED_CONTRACT_CONTRIBUTIONS,
);
export const EXPECTED_CONTRACT_SET_PACKAGES: readonly InstalledContractPackageIdentity[] =
COMPOSED_CONTRACT_CONTRIBUTIONS.externalPackages;
`;
const emptyMessages = `import { TECH_LOG_MESSAGE_CATALOGS } from "./tech-log/contracts/tech-log-message-catalog.ts";
export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({
"ko-KR": TECH_LOG_MESSAGE_CATALOGS["ko-KR"],
"en-US": TECH_LOG_MESSAGE_CATALOGS["en-US"],
});
`;
type CoveragePolicy = {
repositoryBaseline: number;
generatedPaths: string[];
@@ -227,13 +220,21 @@ function runPnpm(script: string, extra: string[] = []): boolean {
return runRemovalFixturePnpm(fixtureRoot, pnpmCli, script, extra);
}
function check(name: string, script: string, extra: string[] = []): RemovalCheck {
return runRemovalFixtureCheck(name, fixtureRoot, pnpmCli, script, extra);
}
/** 14-08. A non-command check fails with its own findings, nothing else's. */
function outcome(name: string, findings: readonly string[], label: string): RemovalCheck {
return findings.length === 0
? { name, passed: true }
: { name, passed: false, failure: `${label}: ${findings.join(", ")}` };
}
try {
await prepareRemovalFixture(fixtureRoot);
for (const excludedFixtureTest of [
"tests/integration/security-followup-archive.test.ts",
// Template sync (ebea300). `ci-artifact-contract` moved to
// `tests/system/ci-runner/`, which `test:all` does not run, so it no longer
// needs excluding — upstream dropped it from this list for the same reason.
"tests/unit/ci-workflow-generation.test.ts",
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
"tests/unit/removal-fixture.test.ts",
@@ -267,52 +268,29 @@ try {
force: true,
});
}
await writeFile(
path.join(fixtureRoot, "src/features/installed-product-manifest.ts"),
emptyProductManifest,
);
await writeFile(
path.join(fixtureRoot, "src/features/installed-feature-contracts.ts"),
emptyContracts,
);
await writeFile(
path.join(fixtureRoot, "src/features/installed-feature-runtimes.tsx"),
emptyRuntimes,
);
await writeFile(
path.join(fixtureRoot, "src/features/installed-feature-adapters.ts"),
emptyAdapters,
);
await writeFile(
path.join(fixtureRoot, "src/features/installed-feature-messages.ts"),
emptyMessages,
);
await writeFile(
path.join(fixtureRoot, "src/features/installed-contract-contributions.ts"),
emptyContractContributions,
);
if (!runPnpm("generate:feature-index")) {
throw new Error("Feature topology indexes failed to regenerate after sample removal");
}
// Runtime profiles are product configuration. Once the feature is physically
// removed, its override key must disappear too or the built config still
// advertises a source capability that no longer exists.
for (const profile of [
"local",
"development",
"staging",
"production",
] as const) {
const profilePath = path.join(
fixtureRoot,
"config/runtime",
`${profile}.json`,
);
// advertises a source capability that no longer exists. public/config.json
// is the local profile `dev` serves and has to stay equal to it (F-5).
for (const configPath of [
"config/runtime/local.json",
"config/runtime/development.json",
"config/runtime/staging.json",
"config/runtime/production.json",
"public/config.json",
]) {
const profilePath = path.join(fixtureRoot, configPath);
const runtimeConfig = JSON.parse(
await readFile(profilePath, "utf8"),
) as {
FEATURE_OVERRIDES?: Record<string, string>;
};
if (runtimeConfig.FEATURE_OVERRIDES) {
delete runtimeConfig.FEATURE_OVERRIDES["reference-feature"];
delete runtimeConfig.FEATURE_OVERRIDES[featureId];
}
await writeFile(
profilePath,
@@ -324,6 +302,7 @@ try {
(modulePolicy) => !modulePolicy.path?.startsWith(`${featureSource}/`),
);
if (
isSample &&
retainedCriticalModules.length === coveragePolicy.criticalModules.length
) {
throw new Error("Reference feature coverage policy is not registered");
@@ -362,12 +341,12 @@ try {
}
evidencePolicy[policyKey] = contributions.filter((candidate: unknown) => {
const contribution = candidate as EvidenceContribution;
const retained = contribution.owner !== "reference-feature";
const retained = contribution.owner !== featureId;
if (!retained) removedEvidenceContributions += 1;
return retained;
});
}
if (removedEvidenceContributions === 0) {
if (isSample && removedEvidenceContributions === 0) {
throw new Error("Reference feature test evidence policy is not registered");
}
await writeFile(
@@ -390,7 +369,7 @@ try {
consumers: registry.consumers.filter(
(candidate: unknown) => {
const consumer = candidate as GovernanceConsumer;
return !consumer.path?.includes("features/reference-feature");
return !consumer.path?.includes(featureSource);
},
),
}
@@ -400,7 +379,7 @@ try {
consumerDirectories: registry.consumerDirectories.filter(
(directory: unknown) =>
typeof directory !== "string" ||
!directory.includes("features/reference-feature"),
!directory.includes(featureSource),
),
}
: {}),
@@ -411,37 +390,31 @@ try {
`${JSON.stringify(removalGovernance, null, 2)}\n`,
);
const removedCiScripts = new Set([
"check:types:fixture:feature-input",
"check:types:fixture:reference-operation",
"check:types:fixture:http-operation-input",
"check:types:fixture:http-wire-mapper",
"check:types:fixture:http-operation-id",
"check:types:fixture:http-route-id",
"check:types:fixture:feature-contribution-input",
"check:types:fixture:feature-capability-selection",
"test:http-scenario-evidence",
"test:reference-feature",
]);
const removedCiScripts = new Set(extras.ciScripts);
const fixturePackagePath = path.join(fixtureRoot, "package.json");
const fixturePackage = JSON.parse(await readFile(fixturePackagePath, "utf8")) as {
scripts: Record<string, string>;
};
pruneScriptOrchestration(fixturePackage.scripts, "test:all", removedCiScripts);
fixturePackage.scripts["test:coverage"] = fixturePackage.scripts["test:coverage"]
.replace(" tests/features/reference-feature", "");
delete fixturePackage.scripts["check:http-scenario-evidence"];
delete fixturePackage.scripts["check:http-scenario-evidence:fixture"];
if (isSample) {
delete fixturePackage.scripts["check:http-scenario-evidence"];
delete fixturePackage.scripts["check:http-scenario-evidence:fixture"];
}
await writeFile(fixturePackagePath, `${JSON.stringify(fixturePackage, null, 2)}\n`);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts: removedCiScripts,
removedEvidencePathFragments: [
"reference-feature.xml",
"http-scenario-executions",
"http-scenario-evidence",
],
removedEvidencePathFragments: extras.evidencePathFragments,
});
// D-13: removing the sample is a breaking registry change. The fixture
// records the new registry baseline the way a downstream project does, and
// the canonical check:registries then runs against it.
if (!runRemovalFixturePnpm(fixtureRoot, pnpmCli, "update:registry-baseline", [], {
REGISTRY_BASELINE_OWNER: "removal-fixture",
REGISTRY_BASELINE_REASON: `${featureId} removed`,
})) {
throw new Error("Registry baseline failed to update after sample removal");
}
await regenerateRemovalFixtureWorkflow(fixtureRoot);
const residue: string[] = [];
@@ -449,60 +422,43 @@ try {
for (const file of await filesBelow(path.join(fixtureRoot, root))) {
const relative = path.relative(fixtureRoot, file);
const content = await readFile(file, "utf8");
if (
/REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(
`${relative}\n${content}`,
)
) {
if (extras.residue.test(`${relative}\n${content}`)) {
residue.push(relative);
}
}
}
const checks: Array<[string, boolean]> = [
[
"common-test-evidence",
(
await Promise.all(
commonTestPaths.map(async (testPath) => {
try {
await access(path.join(fixtureRoot, testPath));
return true;
} catch {
return false;
}
}),
)
).every(Boolean),
],
["typecheck", runPnpm("check:types")],
["architecture", runPnpm("check:architecture")],
["registry-structure", runPnpm("check:registries:structure")],
["unit-integration", runPnpm("test:all")],
["coverage", runPnpm("test:coverage")],
["test-evidence-source", runPnpm("check:test-evidence:source")],
["ci-contract", runPnpm("check:ci")],
[
"home-smoke",
runPnpm("exec", [
"vitest",
"run",
"tests/component/router.test.tsx",
"--reporter=default",
]),
],
["build", runPnpm("build")],
const missingCommonTests: string[] = [];
for (const testPath of commonTestPaths) {
await access(path.join(fixtureRoot, testPath)).catch(() => {
missingCommonTests.push(testPath);
});
}
const checks: RemovalCheck[] = [
outcome("common-test-evidence", missingCommonTests, "platform tests missing"),
check("typecheck", "check:types"),
check("architecture", "check:architecture"),
check("registries", "check:registries"),
check("unit-integration", "test:all"),
check("coverage", "test:coverage"),
check("test-evidence-source", "check:test-evidence:source"),
check("ci-contract", "check:ci"),
check("home-smoke", "exec", [
"vitest",
"run",
"tests/component/router.test.tsx",
"--reporter=default",
]),
check("build", "build"),
];
const builtResidue: string[] = [];
const buildSucceeded =
checks.find(([name]) => name === "build")?.[1] === true;
checks.find(({ name }) => name === "build")?.passed === true;
if (buildSucceeded) {
for (const file of await filesBelow(path.join(fixtureRoot, "dist"))) {
if (!/\.(?:js|css|html|json)$/.test(file)) continue;
const content = await readFile(file, "utf8");
if (
/REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(content)
) {
if (extras.residue.test(content)) {
builtResidue.push(path.relative(fixtureRoot, file));
}
}
@@ -513,37 +469,35 @@ try {
`file://${fixtureRoot}/scripts/`,
).href}?removed=${Date.now()}`
) as { ROUTE_REGISTRY: Readonly<Record<string, unknown>> };
const routeIds = Object.keys(routeCatalog.ROUTE_REGISTRY);
const routeAbsent = routeIds.every((routeId) => !routeId.startsWith("REFERENCE_"));
checks.push(["route-absent", routeAbsent]);
checks.push(["fixture-id-residue", residue.length === 0]);
checks.push(["built-fixture-id-residue", builtResidue.length === 0]);
const routeIds = new Set(Object.keys(routeCatalog.ROUTE_REGISTRY));
checks.push(
outcome(
"route-absent",
featureRouteIds.filter((routeId) => routeIds.has(routeId)),
"routes still registered",
),
outcome("fixture-id-residue", residue, "residue"),
outcome("built-fixture-id-residue", builtResidue, "built residue"),
);
const passed = checks.every(([, result]) => result);
const failed = checks.filter((entry) => !entry.passed);
await mkdir("artifacts/tests", { recursive: true });
await writeFile(
"artifacts/tests/sample-removal.xml",
`<?xml version="1.0" encoding="UTF-8"?>\n` +
`<testsuite name="reference-feature-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
checks
.map(
([name, result]) =>
`<testcase name="${name}">${result ? "" : `<failure>${[...residue, ...builtResidue].join(", ")}</failure>`}</testcase>`,
)
.join("") +
`</testsuite>\n`,
isSample
? "artifacts/tests/sample-removal.xml"
: `artifacts/tests/feature-removal-${featureId}.xml`,
renderRemovalJunit(`${featureId}-removal`, checks),
);
if (!passed) {
const failures = checks
.filter(([, result]) => !result)
.map(([name]) => name);
if (failed.length > 0) {
process.stderr.write(
`Reference feature removal failed: ${failures.join(", ")}; residue: ${[...residue, ...builtResidue].join(", ")}\n`,
`${featureId} removal failed:\n${failed
.map((entry) => ` ${entry.name}: ${entry.failure ?? "failed"}`)
.join("\n")}\n`,
);
process.exitCode = 1;
} else {
process.stdout.write(
`Reference feature removal: PASS (${checks.length} checks, no fixture IDs)\n`,
`${featureId} removal: PASS (${checks.length} checks, no fixture IDs)\n`,
);
}
} finally {
+52
View File
@@ -0,0 +1,52 @@
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`,
);
}
+22
View File
@@ -4,6 +4,7 @@ import { manualA11yReportArtifactSchema } from "./contracts/release-artifacts.ts
import {
MANUAL_A11Y_ROUTE_IDS,
validateManualA11yEvidence,
validateManualA11yRecordFormat,
} from "./lib/manual-a11y-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
@@ -17,6 +18,27 @@ type ManualA11yResult = Readonly<{
passed: boolean;
}>;
// 08-06: the signed review is a release-stage gate (FE-GATE-028). The merge
// stage (FE-GATE-009) runs `--format-only`: every route has a record in the
// template's shape, reviewed or not.
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 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(", ")}`);
}
if (failures.length > 0) {
process.stderr.write(`Manual accessibility record format is invalid:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write(
`Manual accessibility record format: PASS (${MANUAL_A11Y_ROUTE_IDS.length} routes; signed review runs in FE-GATE-028)\n`,
);
process.exit(0);
}
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
+21
View File
@@ -2,6 +2,7 @@ import { access, mkdir, readFile } from "node:fs/promises";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
/**
@@ -96,9 +97,25 @@ for (const path of ROUTE_SCOPE_DOCUMENTS) {
}
const routeScopeDocumented = routeScope.every((entry) => entry.documented);
// 13-15. README is where a project learns how to build for production. It
// named none of the variables the build and admission read, so each one is
// required here, taken from the code that reads it where possible.
const RUNTIME_VARIABLES = Object.freeze([
"APP_PROFILE",
"RELEASE_TARGET",
"VITE_BUILD_ID",
"RELEASE_ID",
...Object.values(RUNTIME_OVERRIDES),
]);
const readme = await readFile("README.md", "utf8").catch(() => "");
const missingRuntimeVariables = RUNTIME_VARIABLES.filter(
(variable) => !readme.includes(`\`${variable}\``),
);
const passed =
reportDigestValid &&
routeScopeDocumented &&
missingRuntimeVariables.length === 0 &&
results.length === 2 &&
results.every((result) => result.passed);
await mkdir("artifacts/quality", { recursive: true });
@@ -115,11 +132,15 @@ await writeValidatedJsonArtifact({
reportDigestValid,
routeScope,
routeScopeDocumented,
missingRuntimeVariables,
results,
passed,
},
});
if (!passed) {
if (missingRuntimeVariables.length > 0) {
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
}
process.stderr.write(
"Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n",
);
+5 -1
View File
@@ -55,9 +55,13 @@ const files = Object.fromEntries(
] as const),
),
);
// 13-04: `--archived` re-verifies a release promoted earlier (deploy later or
// roll back to it); freshness is judged at its recorded promotion time.
const freshness = process.argv.includes("--archived") ? "archived" : "current";
await verifyExactPromotionBundle(files, {
vulnerabilityTrust,
provenanceTrust,
freshness,
expected: {
run: {
id: required("EXPECTED_PROMOTION_RUN_ID"),
@@ -71,7 +75,7 @@ await verifyExactPromotionBundle(files, {
...optionalDigest("lockfileSha256", "EXPECTED_PROMOTION_LOCKFILE_SHA256"),
},
});
process.stdout.write("Exact promotion bundle verification: PASS\n");
process.stdout.write(`Exact promotion bundle verification (${freshness}): PASS\n`);
function asciiCompare(left: string, right: string): number {
return left < right ? -1 : left > right ? 1 : 0;
+332
View File
@@ -0,0 +1,332 @@
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
import { arch, platform, userInfo } from "node:os";
import path from "node:path";
/**
* Executable evidence for the extreme-scale acceptance matrix.
*
* Runs every gate the acceptance rows cite, in order, under the *current*
* Node, and writes one machine-readable record:
* artifacts/quality/extreme-scale-gates.json
* artifacts/quality/extreme-scale-gates/<gate>.log
*
* On an unsupported Node the gates are not run at all and the record says
* `not-executed`; it is never reported as a failure of the code or as a pass.
* In an environment whose default Node is too old, put a supported binary
* first on PATH (for example a repository-local `.tmp/node24/bin`).
*/
export const EXTREME_SCALE_GATES = Object.freeze([
"check:feature-index",
"check:types:app",
"check:types:test",
"check:types",
"lint",
"check:architecture",
"check:app-build-input",
"check:request-fanout",
"check:registries",
"check:diagnostics",
"test:extreme-scale:focused",
"check:topology",
"check:traffic",
"check:observability",
"check:release-coherence",
"test:platform",
"test:reference-feature",
"check:scale:pr",
"check:scale:main",
"check:scale:baseline",
// The soak needs a build of the current source, never a stale dist/.
"build",
// The production bundle closure of the built app contains only its features.
"check:app-build-input:bundle",
"check:scale:nightly",
"check:scale:release",
] as const);
/** Inputs whose content defines "the current code" 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",
]);
async function listFiles(directory: string): Promise<string[]> {
const found: string[] = [];
let entries;
try {
entries = await readdir(directory, { withFileTypes: true });
} catch {
return found;
}
for (const entry of entries) {
const target = path.join(directory, entry.name);
if (entry.isDirectory()) found.push(...(await listFiles(target)));
else if (entry.isFile()) found.push(target);
}
return found;
}
/** sha256 over every source input (path + content), in a stable order. */
export async function sourceDigest(root: string): Promise<Readonly<{ digest: string; files: number }>> {
const files = [
...(await Promise.all(SOURCE_ROOTS.map((entry) => listFiles(path.join(root, entry))))).flat(),
...SOURCE_FILES.map((file) => path.join(root, file)).filter((file) => existsSync(file)),
]
.map((file) => path.relative(root, file))
.sort();
const hash = createHash("sha256");
for (const file of files) {
hash.update(file).update("\0").update(await readFile(path.join(root, file))).update("\0");
}
return { digest: hash.digest("hex"), files: files.length };
}
/** Sums vitest `Tests N passed` / `N failed` lines from a gate log. */
export function vitestCounts(log: string): Readonly<{ passed: number; failed: number; skipped: number; files: number }> {
const escape = String.fromCharCode(27);
const plain = log.split(escape).map((part, index) => (index === 0 ? part : part.replace(/^\[[0-9;]*m/u, ""))).join("");
let passed = 0;
let failed = 0;
let skipped = 0;
let files = 0;
for (const line of plain.split("\n")) {
const tests = /^\s*Tests\s+(.*)$/u.exec(line);
if (tests) {
passed += Number(/(\d+) passed/u.exec(tests[1] as string)?.[1] ?? 0);
failed += Number(/(\d+) failed/u.exec(tests[1] as string)?.[1] ?? 0);
skipped += Number(/(\d+) skipped/u.exec(tests[1] as string)?.[1] ?? 0);
}
const fileLine = /^\s*Test Files\s+.*?(\d+) passed/u.exec(line);
if (fileLine) files += Number(fileLine[1]);
}
return { passed, failed, skipped, files };
}
type Version = readonly [number, number, number];
function parseVersion(value: string): Version {
const [major = 0, minor = 0, patch = 0] = value.replace(/^v/u, "").split(".").map(Number);
return [major, minor, patch];
}
function compare(left: Version, right: Version): number {
for (let index = 0; index < 3; index += 1) {
const difference = (left[index] ?? 0) - (right[index] ?? 0);
if (difference !== 0) return difference;
}
return 0;
}
/** Supports the `>=a.b.c <x.y.z` form this repository declares. */
export function satisfiesEngine(version: string, range: string): boolean {
const current = parseVersion(version);
for (const clause of range.trim().split(/\s+/u)) {
const match = /^(>=|<=|>|<|=)?(\d+(?:\.\d+){0,2})$/u.exec(clause);
if (!match) return false;
const order = compare(current, parseVersion(match[2] as string));
const operator = match[1] ?? "=";
const ok =
operator === ">=" ? order >= 0
: operator === "<=" ? order <= 0
: operator === ">" ? order > 0
: operator === "<" ? order < 0
: order === 0;
if (!ok) return false;
}
return true;
}
async function main(): Promise<void> {
const root = process.cwd();
const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")) as {
engines?: { node?: string };
};
const engine = pkg.engines?.node ?? "";
const directory = path.join(root, "artifacts/quality/extreme-scale-gates");
const artifact = path.join(root, "artifacts/quality/extreme-scale-gates.json");
await mkdir(directory, { recursive: true });
const startedAt = new Date();
const pnpmVersion =
spawnSync("corepack", ["pnpm", "--version"], { cwd: root, encoding: "utf8" }).stdout?.trim() ?? "";
const identity = {
node: process.version,
nodeMajor: Number(process.versions.node.split(".")[0]),
pnpm: pnpmVersion,
engine,
platform: platform(),
arch: arch(),
user: (() => {
try {
return userInfo().username;
} catch {
return "unknown";
}
})(),
};
if (!satisfiesEngine(process.version, engine)) {
await writeFile(
artifact,
`${JSON.stringify(
{
schemaVersion: 1,
generatedAt: new Date().toISOString(),
...identity,
status: "not-executed",
reason: `Node ${process.version} does not satisfy engines.node "${engine}"`,
gates: [],
},
null,
2,
)}\n`,
);
process.stderr.write(
`not executed: Node ${process.version} does not satisfy "${engine}". Put a supported node first on PATH.\n`,
);
process.exit(2);
}
const browsers = path.join(root, ".tmp/ms-playwright");
const env = {
...process.env,
pnpm_config_verify_deps_before_run: "false",
...(process.env["PLAYWRIGHT_BROWSERS_PATH"] === undefined && existsSync(browsers)
? { PLAYWRIGHT_BROWSERS_PATH: browsers }
: {}),
};
const only = process.argv.find((argument) => argument.startsWith("--only="))?.slice(7).split(",");
const gates = only ? EXTREME_SCALE_GATES.filter((gate) => only.includes(gate)) : EXTREME_SCALE_GATES;
const sourceBefore = await sourceDigest(root);
const results: {
gate: string;
status: "passed" | "failed";
exitCode: number | null;
durationMs: number;
tests: ReturnType<typeof vitestCounts>;
log: string;
}[] = [];
for (const gate of gates) {
const gateStartedAt = Date.now();
const run = spawnSync("corepack", ["pnpm", "run", gate], {
cwd: root,
env,
encoding: "utf8",
maxBuffer: 256 * 1024 * 1024,
});
const log = path.join(directory, `${gate.replaceAll(":", "-")}.log`);
await writeFile(log, `${run.stdout ?? ""}${run.stderr ?? ""}`);
const status = run.status === 0 ? "passed" : "failed";
const tests = vitestCounts(`${run.stdout ?? ""}${run.stderr ?? ""}`);
results.push({
gate,
status,
exitCode: run.status,
durationMs: Date.now() - gateStartedAt,
tests,
log: path.relative(root, log),
});
process.stdout.write(
`${status.toUpperCase()} ${gate} (${Date.now() - gateStartedAt}ms${tests.passed + tests.failed > 0 ? `, ${tests.passed} tests passed, ${tests.failed} failed` : ""})\n`,
);
}
const sourceAfter = await sourceDigest(root);
const readJson = async (relative: string) => {
const file = path.join(root, relative);
if (!existsSync(file)) return null;
const fresh = (await stat(file)).mtimeMs >= startedAt.getTime();
return { fresh, value: JSON.parse(await readFile(file, "utf8")) as Record<string, unknown> };
};
// Machine-readable artifacts the acceptance depends on must be produced by
// this run, on this Node, and say passed. An old PASS is not evidence.
const evidenceChecks: { artifact: string; check: string; passed: boolean }[] = [];
const expect = (artifact: string, check: string, passed: boolean) =>
evidenceChecks.push({ artifact, check, passed });
const ran = new Set(gates);
for (const tier of ["nightly", "release"] as const) {
if (!ran.has(`check:scale:${tier}`)) continue;
const relative = `artifacts/scale/${tier}/summary.json`;
const summary = await readJson(relative);
expect(relative, "regenerated during this run", summary?.fresh === true);
expect(relative, "status passed with no skipped step", summary?.value["status"] === "passed" && Array.isArray(summary.value["skipped"]) && summary.value["skipped"].length === 0);
const environment = summary?.value["environment"] as { nodeMajor?: number } | undefined;
expect(relative, `environment.nodeMajor == ${identity.nodeMajor}`, environment?.nodeMajor === identity.nodeMajor);
}
const soakRecord = ran.has("check:scale:nightly")
? await readJson("artifacts/scale/nightly/browser-soak.json")
: null;
if (ran.has("check:scale:nightly")) {
expect("artifacts/scale/nightly/browser-soak.json", "regenerated during this run", soakRecord?.fresh === true);
expect("artifacts/scale/nightly/browser-soak.json", "status passed (not skipped)", soakRecord?.value["status"] === "passed");
}
if (ran.has("check:scale:baseline")) {
const comparison = await readJson("artifacts/scale/baseline-comparison.json");
expect("artifacts/scale/baseline-comparison.json", "regenerated during this run", comparison?.fresh === true);
expect("artifacts/scale/baseline-comparison.json", "status passed on all axes (timing compatible)", comparison?.value["status"] === "passed");
}
if (ran.has("check:app-build-input:bundle")) {
const inventory = await readJson("artifacts/quality/vite-module-inventory.json");
expect(
"artifacts/quality/vite-module-inventory.json",
"produced by this run's build (bundle isolation checked on current code)",
inventory?.fresh === true,
);
}
expect("source tree", "unchanged while the gates ran", sourceBefore.digest === sourceAfter.digest);
const soak = soakRecord?.value ?? null;
const status =
results.every((result) => result.status === "passed") && evidenceChecks.every((check) => check.passed)
? "passed"
: "failed";
await writeFile(
artifact,
`${JSON.stringify(
{
schemaVersion: 1,
generatedAt: new Date().toISOString(),
startedAt: startedAt.toISOString(),
...identity,
source: { digest: sourceAfter.digest, files: sourceAfter.files },
status,
gates: results,
totals: {
gates: results.length,
passedGates: results.filter((result) => result.status === "passed").length,
testsPassed: results.reduce((sum, result) => sum + result.tests.passed, 0),
testsFailed: results.reduce((sum, result) => sum + result.tests.failed, 0),
},
evidenceChecks,
browserSoak: soak
? {
status: soak["status"],
classification: soak["classification"],
samples: Array.isArray(soak["samples"]) ? soak["samples"].length : 0,
summary: soak["summary"],
browser: soak["browser"],
build: soak["build"],
}
: null,
},
null,
2,
)}\n`,
);
process.stdout.write(`extreme-scale gates: ${status.toUpperCase()} on Node ${process.version} (${path.relative(root, artifact)})\n`);
if (status !== "passed") process.exitCode = 1;
}
if (import.meta.url === `file://${process.argv[1]}`) {
await main();
}
+45 -30
View File
@@ -1,12 +1,18 @@
import { mkdir, readFile, readdir } from "node:fs/promises";
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
import { hostingHeadersArtifactSchema } from "./contracts/release-artifacts.ts";
import { classifyLiveHostingBaseUrl } from "./lib/hosting-probe.ts";
import {
checkPublicServiceWorkers,
classifyLiveHostingBaseUrl,
hostingVerdict,
servedEntryScript,
type HostingMode,
} from "./lib/hosting-probe.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type Document = Record<string, unknown>;
type ResponseHeaders = Record<string, Record<string, string>>;
type HostingMode = "live" | "invalid-live" | "fixture";
type ProbeResult = Readonly<{
surface: string;
header: string;
@@ -63,9 +69,6 @@ const baseUrl = process.env.HOSTING_BASE_URL;
const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null;
const distFiles = (await readdir("dist", { recursive: true })).map(String);
const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map"));
const publicServiceWorkers = distFiles.filter((file) =>
/(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i.test(file),
);
let responses: ResponseHeaders = {};
let mode: HostingMode;
@@ -73,16 +76,9 @@ const probeResults: ProbeResult[] = [];
if (liveTarget?.passed) {
mode = "live";
const assets = await readdir("dist/assets");
const hashedJavaScript = assets.find((file) => file.endsWith(".js"));
if (!hashedJavaScript) throw new Error("No built hashed JavaScript found.");
const paths = {
index: "/",
runtimeConfig: "/config.json",
releaseManifest: "/release-manifest.json",
hashedAsset: `/assets/${hashedJavaScript}`,
};
for (const [surface, pathname] of Object.entries(paths)) {
// 13-05: FE-GATE-019 runs after the promoted release is deployed, and the
// hashed asset it probes is the entry script that release's index.html names.
const probe = async (surface: string, pathname: string): Promise<string | null> => {
const requestedUrl = new URL(pathname, liveTarget.url);
try {
const response = await fetch(requestedUrl, { redirect: "follow" });
@@ -109,6 +105,7 @@ if (liveTarget?.passed) {
value,
]),
);
return await response.text();
} catch (error: unknown) {
probeResults.push({
surface,
@@ -117,7 +114,23 @@ if (liveTarget?.passed) {
observed: error instanceof Error ? error.name : "UnknownError",
passed: false,
});
return null;
}
};
const indexHtml = await probe("index", "/");
await probe("runtimeConfig", "/config.json");
await probe("releaseManifest", "/release-manifest.json");
const entryScript = indexHtml === null ? null : servedEntryScript(indexHtml);
if (entryScript) {
await probe("hashedAsset", entryScript);
} else {
probeResults.push({
surface: "hashedAsset",
header: "entry-script",
expected: "a module script named by the served index.html",
observed: null,
passed: false,
});
}
} else if (liveTarget) {
mode = "invalid-live";
@@ -184,17 +197,15 @@ results.push({
observed: publicSourceMaps.length > 0,
passed: sourceMapPolicy.public === false && publicSourceMaps.length === 0,
});
const serviceWorkerPolicy = recordValue(cacheSurfaces.serviceWorker);
results.push({
surface: "serviceWorker",
header: "enabled",
expected: false,
observed: publicServiceWorkers.length > 0,
passed:
serviceWorkerPolicy.enabled === false && publicServiceWorkers.length === 0,
});
results.push(
checkPublicServiceWorkers(
distFiles,
INSTALLED_RUNTIME_CAPABILITIES.serviceWorker,
),
);
const passed = results.every((result) => result.passed);
const status = hostingVerdict(mode, passed);
await mkdir("artifacts/release", { recursive: true });
await writeValidatedJsonArtifact({
path: "artifacts/release/hosting-headers.json",
@@ -207,17 +218,21 @@ await writeValidatedJsonArtifact({
providerVerificationRequired: mode !== "live",
results,
passed,
status,
},
});
if (!passed) {
if (status === "FAIL") {
process.stderr.write(
"Hosting cache/content-type/security header verification failed.\n",
);
process.exit(1);
}
process.stdout.write(
`Hosting header contract: PASS (${mode}; live verification ${
mode === "live" ? "complete" : "required before promotion"
})\n`,
);
if (status === "UNVERIFIED") {
// Not a pass (D-14): set HOSTING_BASE_URL to the deployed release.
process.stderr.write(
"Hosting header contract: UNVERIFIED (fixture: declared headers are consistent; set HOSTING_BASE_URL to probe the deployed release)\n",
);
process.exit(3);
}
process.stdout.write("Hosting header contract: PASS (live)\n");
-1
View File
@@ -87,7 +87,6 @@ const fixturesDocument = parseFixturesDocument(
const verifiedRuntime = await verifyReleaseArtifactsCoherence();
const {
release,
runtime: runtimeConfig,
coherence: artifactComparison,
} = verifiedRuntime;
const buildManifestDocument: unknown = JSON.parse(