Merge remote-tracking branch 'origin/main' into feat/frontend-nonroot
This commit is contained in:
@@ -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");
|
||||
|
||||
@@ -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"],
|
||||
|
||||
@@ -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
@@ -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,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,
|
||||
|
||||
@@ -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`);
|
||||
|
||||
@@ -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`,
|
||||
);
|
||||
|
||||
@@ -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`,
|
||||
);
|
||||
|
||||
@@ -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
@@ -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 (
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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",
|
||||
},
|
||||
});
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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
@@ -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"]),
|
||||
|
||||
@@ -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
@@ -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 &&
|
||||
|
||||
@@ -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`,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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}`;
|
||||
}
|
||||
@@ -4,7 +4,6 @@ import { constants } from "node:fs";
|
||||
import type { FileHandle } from "node:fs/promises";
|
||||
import {
|
||||
lstat,
|
||||
mkdir,
|
||||
open,
|
||||
readFile,
|
||||
readdir,
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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" ||
|
||||
|
||||
@@ -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`);
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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}.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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[],
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
@@ -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(
|
||||
|
||||
@@ -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("&", "&")
|
||||
.replaceAll("<", "<")
|
||||
.replaceAll(">", ">")
|
||||
.replaceAll('"', """);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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());
|
||||
});
|
||||
`;
|
||||
@@ -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 ||
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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)}`
|
||||
|
||||
@@ -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)],
|
||||
|
||||
@@ -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`);
|
||||
}
|
||||
@@ -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 ?? {}) }),
|
||||
}),
|
||||
);
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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";
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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
@@ -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");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
@@ -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 {
|
||||
|
||||
@@ -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`,
|
||||
);
|
||||
}
|
||||
@@ -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`;
|
||||
|
||||
@@ -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",
|
||||
);
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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");
|
||||
|
||||
@@ -87,7 +87,6 @@ const fixturesDocument = parseFixturesDocument(
|
||||
const verifiedRuntime = await verifyReleaseArtifactsCoherence();
|
||||
const {
|
||||
release,
|
||||
runtime: runtimeConfig,
|
||||
coherence: artifactComparison,
|
||||
} = verifiedRuntime;
|
||||
const buildManifestDocument: unknown = JSON.parse(
|
||||
|
||||
Reference in New Issue
Block a user