Merge lane K: CI, guardrails and release fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 23:42:40 +09:00
co-authored by Claude Opus 5.5
88 changed files with 2049 additions and 746 deletions
+10 -5
View File
@@ -3,6 +3,7 @@ import { rm } from "node:fs/promises";
import process from "node:process";
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
import { makeDistFilesPublic } from "./lib/dist-permissions.ts";
/**
* §17.2.2. Deterministic two-pass build.
@@ -17,15 +18,16 @@ import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtim
* 5. scan app dist and generate the static asset source
* 6. ACTIVE only: Vite Service Worker build (emptyOutDir = false)
* 7. generate Release Manifest V2 and the build manifest
* 8. 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.
*
* 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).
*/
const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker;
@@ -68,3 +70,6 @@ if (buildsActiveWorker) {
// 6. release + build manifest
run("node", ["scripts/generate-build-manifest.ts"]);
// 8. publishable permissions: the validated writer creates 0600 files
await makeDistFilesPublic("dist");
+114 -51
View File
@@ -6,11 +6,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
import { createRequire } from "node:module";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
type ArchitectureRule = Readonly<{
name: string;
comment?: string;
severity?: string;
from?: PathRule;
to?: PathRule & Readonly<{ circular?: boolean }>;
@@ -53,7 +55,6 @@ type GraphFixtureResult = Readonly<{
failures: string[];
}>;
type DependencyResolution = Readonly<{ path?: string; reason: string }>;
type DependencyCruiserReport = Record<string, unknown>;
type TypeScriptOnlyPolicy = Readonly<{
checkedRoots: readonly string[];
exceptionsAllowed: false;
@@ -111,27 +112,15 @@ function runPnpm(arguments_: string[]) {
});
}
// Keep dependency-cruiser's report and checks. The second graph is authoritative
// for TypeScript 7 coverage because dependency-cruiser 18 cannot parse TS 7 yet.
const dependencyCruiser = runPnpm([
"exec",
"depcruise",
"src",
"--config",
".dependency-cruiser.json",
"--output-type",
"json",
]);
// 12-05 (D-11): this graph is the only architecture checker. dependency-cruiser
// 18 cannot parse TypeScript 7, so it cruised zero modules and still passed.
// .dependency-cruiser.json keeps its name and is read here as the rule file.
const sourceGraph = await analyzeSourceGraph(sourceRoot, "src");
const typeScriptOnlyPolicy = await inspectTypeScriptOnlyPolicy();
const graphFixtureResult = await runGraphFixtureChecks();
const dependencyReport = parseDependencyCruiserReport(dependencyCruiser.stdout);
const graphErrors = blockingViolations(sourceGraph);
const dependencyCruiserReportValid = !(
"dependencyCruiserOutput" in dependencyReport
);
dependencyReport.staticImportGraph = {
const staticImportGraph = {
analyzer: "babel-parser-node-resolver",
modules: sourceGraph.modules,
dependencies: sourceGraph.dependencies,
@@ -162,25 +151,11 @@ dependencyReport.staticImportGraph = {
await writeValidatedJsonArtifact({
path: qualityArtifact,
schema: architectureDependencyReportArtifactSchema,
value: dependencyReport,
value: { staticImportGraph },
});
let architectureFailed = false;
if (!dependencyCruiserReportValid) {
architectureFailed = true;
process.stderr.write("dependency-cruiser returned an invalid JSON report\n");
}
if (dependencyCruiser.status !== 0) {
architectureFailed = true;
process.stderr.write(
(dependencyCruiser.error?.message ?? dependencyCruiser.stderr) ||
dependencyCruiser.stdout ||
"dependency-cruiser failed\n",
);
}
for (const failure of sourceGraph.parseFailures) {
architectureFailed = true;
process.stderr.write(
@@ -197,11 +172,16 @@ for (const dependency of sourceGraph.unresolved) {
for (const violation of graphErrors) {
architectureFailed = true;
const cycle = violation.cycle
? ` (cycle group: ${violation.cycle.join(", ")})`
: "";
process.stderr.write(
`Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${cycle}\n`,
formatArchitectureViolation(
violation,
violation.cycle
? []
: sourceGraph.dependencies
.filter(({ source, target }) => source === violation.source && target === violation.target)
.map(({ specifier }) => specifier),
architectureRules.find(({ name }) => name === violation.rule)?.comment,
),
);
}
@@ -443,7 +423,7 @@ async function importSpecifiers(sourceFile: string): Promise<string[]> {
visitSyntaxNode(syntaxTree, specifiers, nonLiteralModuleLoads);
if (nonLiteralModuleLoads.size > 0) {
throw new Error(
`module loading must use string literals: ${[...nonLiteralModuleLoads].join(", ")}`,
`module loading must name one module with a string literal: ${[...nonLiteralModuleLoads].join(", ")}`,
);
}
for (const comment of syntaxTree.comments ?? []) {
@@ -503,6 +483,17 @@ function visitSyntaxNode(
if (!addStringLiteral(arguments_[0], specifiers)) {
nonLiteralModuleLoads.add("require()");
}
} else if (
nodeType === "CallExpression" &&
syntaxNodeType(node.callee) === "MemberExpression" &&
syntaxNodeType(syntaxNodeProperty(node.callee, "object")) === "MetaProperty" &&
/^glob(?:Eager)?$/u.test(
String(syntaxNodeProperty(syntaxNodeProperty(node.callee, "property"), "name")),
)
) {
// 12-06: a glob pulls in every matching module without naming one, so no
// edge rule can see it. Refuse it like a non-literal import().
nonLiteralModuleLoads.add("import.meta.glob()");
} else if (nodeType === "TSExternalModuleReference") {
addStringLiteral(node.expression, specifiers);
} else if (nodeType === "TSImportType") {
@@ -831,6 +822,7 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
cycleGraph,
barrelGraph,
crossBoundaryGraph,
importBoundaryGraph,
] = await Promise.all([
analyzeSourceGraph(allowedRoot, "src"),
analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"),
@@ -838,6 +830,7 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
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(
@@ -876,6 +869,66 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
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",
),
},
{
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(
@@ -885,6 +938,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(
@@ -954,6 +1022,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(
@@ -1099,6 +1175,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;
}
@@ -1124,17 +1201,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 };
}
}
+3 -5
View File
@@ -8,6 +8,7 @@ import {
type GateResult,
} from "./lib/promotion-readiness.ts";
import {
CANONICAL_GATE_IDS,
loadCiGateContract,
indexCiGateContract,
} from "./contracts/ci-gates.ts";
@@ -104,10 +105,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"]),
);
@@ -168,4 +166,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`);
+4 -12
View File
@@ -97,22 +97,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 (
!file.includes("src/presentation/design-system/tokens/") &&
/(?:#[0-9a-f]{3,8}\b|oklch\(|rgba?\()/i.test(source)
@@ -151,5 +143,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`,
);
@@ -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 (
@@ -249,6 +249,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 +307,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 +340,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",
},
});
+21 -9
View File
@@ -438,6 +438,19 @@ export type CiGateContractIndex = Readonly<{
jobs: ReadonlyMap<string, CiWorkflowJob>;
retentionClasses: ReadonlyMap<string, CiGateContract["retention"]["classes"][number]>;
}>;
/**
* 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
@@ -789,12 +802,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],
@@ -864,12 +874,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"],
};
@@ -918,7 +928,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
@@ -964,7 +974,9 @@ 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.
production_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }],
field_gate: [
{ name: "FIELD_WEB_VITALS_INPUT", value: "${{ vars.FIELD_WEB_VITALS_INPUT }}" },
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
+76 -40
View File
@@ -152,6 +152,8 @@ export const moduleInventoryArtifactSchema = z
})
.strict(),
),
// 13-12: `name@version` of every package with a module in the bundle.
packages: z.array(z.string().regex(/^(?:@[^/@]+\/)?[^/@]+@[^/@]+$/u)),
})
.strict();
@@ -723,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"]);
@@ -948,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({
@@ -1023,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(),
@@ -1289,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,
@@ -1300,11 +1319,19 @@ 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" });
@@ -1369,6 +1396,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({
@@ -1407,6 +1436,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" });
@@ -1433,9 +1463,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 -205
View File
@@ -1,4 +1,5 @@
import { access, mkdir, readFile } from "node:fs/promises";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { shouldRetry } from "../src/adapters/http/retry-policy.ts";
@@ -15,21 +16,30 @@ import {
} 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 +61,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 +71,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 +122,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 +173,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 +205,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 +218,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 +254,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 +287,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 +301,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 +337,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 +368,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 +391,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 +456,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 +484,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 &&
+2 -2
View File
@@ -29,7 +29,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,7 +49,7 @@ 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;
}
@@ -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}`;
}
+18
View File
@@ -0,0 +1,18 @@
import { chmod, readdir, stat } from "node:fs/promises";
import path from "node:path";
/**
* 13-02. dist is published as-is to a web server that may run as another OS
* user, so every file in it must be readable by others. The validated JSON
* writer creates files 0600 on purpose (evidence under artifacts/ stays
* private); the build adds read bits to what it publishes instead of loosening
* that writer.
*/
export async function makeDistFilesPublic(directory: string): Promise<void> {
for (const entry of await readdir(directory, { recursive: true, withFileTypes: true })) {
if (!entry.isFile()) continue;
const file = path.join(entry.parentPath, entry.name);
const { mode } = await stat(file);
if ((mode & 0o004) === 0) await chmod(file, (mode & 0o7777) | 0o444);
}
}
+31 -1
View File
@@ -9,6 +9,7 @@ import {
import {
PROMOTION_VERIFIER_ID,
PROMOTION_VERIFIER_VERSION,
PROVIDER_FUTURE_SKEW_MS,
assertDistinctProviderTrust,
evaluatePromotionEvidence,
providerVerificationArtifactSchema,
@@ -35,6 +36,29 @@ export type ExactPromotionExpectedContext = Readonly<{
lockfileSha256?: string;
}>;
/**
* 13-04. `current` checks provider evidence against the clock, as a new
* promotion must. `archived` re-verifies a release promoted earlier (deploying
* it later, or rolling back to it): signatures, digests and members are checked
* the same way, but freshness is judged at the promotion's recorded
* `verifiedAt`, which may not lie in the future. Promotion itself
* (promotion-stager.ts) never passes `archived`.
*/
export type PromotionFreshness = "current" | "archived";
export function promotionEvidenceTime(
freshness: PromotionFreshness,
verifiedAt: string,
now: number,
): number {
if (freshness === "current") return now;
const verified = Date.parse(verifiedAt);
if (!Number.isFinite(verified) || verified > now + PROVIDER_FUTURE_SKEW_MS) {
throw new Error("archived promotion verifiedAt is in the future or invalid");
}
return verified;
}
export async function verifyExactPromotionBundle(
files: ExactPromotionBundle,
options: Readonly<{
@@ -42,6 +66,7 @@ export async function verifyExactPromotionBundle(
provenanceTrust: ProviderTrust;
expected: ExactPromotionExpectedContext;
nowEpochMs?: () => number;
freshness?: PromotionFreshness;
}>,
): Promise<Readonly<{ status: "PASS" }>> {
assertDistinctProviderTrust(options);
@@ -286,7 +311,12 @@ export async function verifyExactPromotionBundle(
provenanceAttestation: provenance,
vulnerabilityTrust: options.vulnerabilityTrust,
provenanceTrust: options.provenanceTrust,
nowEpochMs: options.nowEpochMs,
nowEpochMs: () =>
promotionEvidenceTime(
options.freshness ?? "current",
promotion.verifiedAt,
(options.nowEpochMs ?? Date.now)(),
),
});
if (
reevaluated.status !== "PASS" ||
+27
View File
@@ -1,6 +1,33 @@
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;
/**
+46 -3
View File
@@ -15,8 +15,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 +38,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 +87,7 @@ export function validateManualA11yEvidence(content: string) {
const result = fields[field];
if (
result !== "pass" &&
!/^not-applicable \(.+\)$/.test(result ?? "")
!NOT_APPLICABLE.test(result ?? "")
) {
failures.push(field);
}
+15
View File
@@ -1,3 +1,18 @@
/**
* Package-script graph for the CI contract (D-12, 12-10). Kept after checking
* whether `--ignore-scripts` on the workflow install and `allowBuilds` in
* pnpm-workspace.yaml already close the same risks. They do not:
*
* - Gate commands run installs themselves (`verify:lockfile`, removal
* fixtures). `allowBuilds` limits dependency build scripts under pnpm only;
* the root project's own install hooks and npm/yarn installs still run
* unless the command says `--ignore-scripts`.
* - A gate names a root package script. `--prefix`, `--filter`, `-C`, npm
* pre/post hooks and `npm_config_*` scope variables can make that name run a
* different manifest's script, which no install flag affects.
* - `reachablePackageScripts` is also how the ungated-test check (12-04) finds
* which Vitest paths a gate runs.
*/
type PackageManager = "pnpm" | "npm" | "yarn";
type ManagerParseResult = Readonly<{
+7 -2
View File
@@ -18,14 +18,19 @@ export const PROMOTION_FORMULA = Object.freeze({
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-015",
"FE-GATE-019",
"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-016",
// 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",
+4 -12
View File
@@ -1,10 +1,12 @@
import { readFile, readdir } from "node:fs/promises";
import path from "node:path";
// Importing the realtime or Web Push adapter from the composition root is the
// graph rule unselected-realtime-runtime-is-not-composed (12-10). This scan
// keeps what an import graph cannot see: native API calls and timers.
export type RealtimeBoundaryRuleId =
| "NATIVE_REALTIME_API_OUTSIDE_ADAPTER"
| "PRESENTATION_INTERVAL_OWNER"
| "UNSELECTED_REALTIME_RUNTIME_COMPOSED";
| "PRESENTATION_INTERVAL_OWNER";
export type RealtimeBoundaryViolation = Readonly<{
ruleId: RealtimeBoundaryRuleId;
@@ -17,8 +19,6 @@ const OWNED_NATIVE_ROOTS = [
"src/adapters/realtime/",
"src/adapters/web-push/",
] as const;
const REALTIME_ADAPTER_IMPORT =
/(?:from\s*|import\s*\()\s*["'][^"']*\/adapters\/(?:realtime|web-push)(?:\/[^"']*)?["']/gu;
const NATIVE_REALTIME_PATTERNS = [
/\bnew\s+(?:WebSocket|EventSource|Notification)\s*\(/gu,
/\bNotification\s*\.\s*requestPermission\s*\(/gu,
@@ -62,9 +62,6 @@ function inspectFile(
const presentationOwned =
logicalFile.startsWith("src/presentation/") ||
/^src\/features\/[^/]+\/presentation\//u.test(logicalFile);
const compositionBoundary =
logicalFile.startsWith("src/bootstrap/") ||
/^src\/features\/installed-feature-/u.test(logicalFile);
const report = (
ruleId: RealtimeBoundaryRuleId,
@@ -92,11 +89,6 @@ function inspectFile(
report("PRESENTATION_INTERVAL_OWNER", match.index);
}
}
if (compositionBoundary) {
for (const match of source.matchAll(REALTIME_ADAPTER_IMPORT)) {
report("UNSELECTED_REALTIME_RUNTIME_COMPOSED", match.index);
}
}
}
async function collectSourceFiles(
+16 -9
View File
@@ -3,12 +3,14 @@ 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>`) and Playwright config `testDir`s.
* 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";
@@ -53,17 +55,22 @@ export function gatedTestPaths(
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);
const vitestRun = tokens.findIndex(
(token, index) => token === "run" && /(?:run-vitest\.ts|vitest)$/u.test(tokens[index - 1] ?? ""),
);
if (vitestRun >= 0) {
for (const token of tokens.slice(vitestRun + 1)) {
if (token.startsWith("-")) break;
paths.add(token.replace(/\/$/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",
+49 -1
View File
@@ -1,3 +1,4 @@
import { readFileSync } from "node:fs";
import path from "node:path";
import type { Plugin } from "vite";
@@ -39,6 +40,7 @@ export function viteModuleInventoryPlugin(
{
schemaVersion: 1,
chunks,
packages: bundledPackages(chunks),
},
null,
2,
@@ -48,7 +50,41 @@ export function viteModuleInventoryPlugin(
};
}
function normalizeModuleId(
/**
* 13-12. The `name@version` of every package with at least one module in the
* emitted bundle: what the public release actually ships, as opposed to the
* SBOM, which lists the whole installed graph.
*/
export function bundledPackages(chunks: readonly ModuleInventoryChunk[]): string[] {
const packages = new Set<string>();
for (const chunk of chunks) {
for (const module of chunk.modules) {
const match = /^npm:((?:@[^/]+\/)?[^/@]+@[^/]+)\//u.exec(module);
if (match?.[1]) packages.add(match[1]);
}
}
return [...packages].sort();
}
const packageManifests = new Map<string, Readonly<{ name: string; version: string }>>();
function installedPackage(directory: string): Readonly<{ name: string; version: string }> {
let manifest = packageManifests.get(directory);
if (!manifest) {
const parsed = JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8")) as {
name?: unknown;
version?: unknown;
};
if (typeof parsed.name !== "string" || typeof parsed.version !== "string") {
throw new TypeError(`bundled package has no name/version: ${directory}`);
}
manifest = Object.freeze({ name: parsed.name, version: parsed.version });
packageManifests.set(directory, manifest);
}
return manifest;
}
export function normalizeModuleId(
moduleId: string,
repositoryRoot: string,
): string {
@@ -56,6 +92,18 @@ function normalizeModuleId(
if (!path.isAbsolute(withoutQuery)) {
return withoutQuery.replaceAll("\\", "/");
}
// 13-12: a dependency module keeps its package identity, read from the
// package.json of the directory it was resolved into.
const file = withoutQuery.replaceAll("\\", "/");
const marker = "/node_modules/";
const at = file.lastIndexOf(marker);
if (at >= 0) {
const segments = file.slice(at + marker.length).split("/");
const nameLength = segments[0]?.startsWith("@") ? 2 : 1;
const directory = file.slice(0, at + marker.length) + segments.slice(0, nameLength).join("/");
const { name, version } = installedPackage(directory);
return `npm:${name}@${version}/${segments.slice(nameLength).join("/")}`;
}
const relative = path.relative(repositoryRoot, withoutQuery);
return relative.startsWith("..")
? `external:${path.basename(withoutQuery)}`
+15 -10
View File
@@ -3,14 +3,21 @@ import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
/**
* Spec §47. CI execution tiers for the scale/chaos/soak program.
* Spec §47. Execution tiers for the scale/chaos/soak program.
*
* pr S0/S1 architecture, composition and traffic invariants
* main pr + S2 composition, TypeScript diagnostics and the stored
* baseline regression gate (config/scale/benchmark-baseline.json)
* 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
@@ -49,18 +56,16 @@ const PR_STEPS: readonly Step[] = [
"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-s1",
command: ["scripts/scale/run-composition-scale.ts", "--profiles=S0,S1"],
id: "composition-s0-s2",
command: ["scripts/scale/run-composition-scale.ts", "--profiles=S0,S1,S2"],
},
];
const MAIN_STEPS: readonly Step[] = [
...PR_STEPS,
{
id: "composition-s0-s2",
command: ["scripts/scale/run-composition-scale.ts", "--profiles=S0,S1,S2"],
},
{
id: "composition-scale-suite",
command: [...VITEST, "tests/scale/composition-scale.test.ts", "tests/scale/tsc-diagnostics-parser.test.ts"],
+22
View File
@@ -4,6 +4,7 @@ import { manualA11yReportArtifactSchema } from "./contracts/release-artifacts.ts
import {
MANUAL_A11Y_ROUTE_IDS,
validateManualA11yEvidence,
validateManualA11yRecordFormat,
} from "./lib/manual-a11y-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
@@ -17,6 +18,27 @@ type ManualA11yResult = Readonly<{
passed: boolean;
}>;
// 08-06: the signed review is a release-stage gate (FE-GATE-028). The merge
// stage (FE-GATE-009) runs `--format-only`: every route has a record in the
// template's shape, reviewed or not.
if (process.argv.includes("--format-only")) {
const failures: string[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const record = await readFile(path, "utf8").catch(() => null);
const invalid = record === null ? ["missing record"] : validateManualA11yRecordFormat(record, routeId);
if (invalid.length > 0) failures.push(`${path}: ${invalid.join(", ")}`);
}
if (failures.length > 0) {
process.stderr.write(`Manual accessibility record format is invalid:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write(
`Manual accessibility record format: PASS (${MANUAL_A11Y_ROUTE_IDS.length} routes; signed review runs in FE-GATE-028)\n`,
);
process.exit(0);
}
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
+21
View File
@@ -2,6 +2,7 @@ import { access, mkdir, readFile } from "node:fs/promises";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
/**
@@ -96,9 +97,25 @@ for (const path of ROUTE_SCOPE_DOCUMENTS) {
}
const routeScopeDocumented = routeScope.every((entry) => entry.documented);
// 13-15. README is where a project learns how to build for production. It
// named none of the variables the build and admission read, so each one is
// required here, taken from the code that reads it where possible.
const RUNTIME_VARIABLES = Object.freeze([
"APP_PROFILE",
"RELEASE_TARGET",
"VITE_BUILD_ID",
"RELEASE_ID",
...Object.values(RUNTIME_OVERRIDES),
]);
const readme = await readFile("README.md", "utf8").catch(() => "");
const missingRuntimeVariables = RUNTIME_VARIABLES.filter(
(variable) => !readme.includes(`\`${variable}\``),
);
const passed =
reportDigestValid &&
routeScopeDocumented &&
missingRuntimeVariables.length === 0 &&
results.length === 2 &&
results.every((result) => result.passed);
await mkdir("artifacts/quality", { recursive: true });
@@ -115,11 +132,15 @@ await writeValidatedJsonArtifact({
reportDigestValid,
routeScope,
routeScopeDocumented,
missingRuntimeVariables,
results,
passed,
},
});
if (!passed) {
if (missingRuntimeVariables.length > 0) {
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
}
process.stderr.write(
"Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n",
);
+5 -1
View File
@@ -55,9 +55,13 @@ const files = Object.fromEntries(
] as const),
),
);
// 13-04: `--archived` re-verifies a release promoted earlier (deploy later or
// roll back to it); freshness is judged at its recorded promotion time.
const freshness = process.argv.includes("--archived") ? "archived" : "current";
await verifyExactPromotionBundle(files, {
vulnerabilityTrust,
provenanceTrust,
freshness,
expected: {
run: {
id: required("EXPECTED_PROMOTION_RUN_ID"),
@@ -71,7 +75,7 @@ await verifyExactPromotionBundle(files, {
...optionalDigest("lockfileSha256", "EXPECTED_PROMOTION_LOCKFILE_SHA256"),
},
});
process.stdout.write("Exact promotion bundle verification: PASS\n");
process.stdout.write(`Exact promotion bundle verification (${freshness}): PASS\n`);
function asciiCompare(left: string, right: string): number {
return left < right ? -1 : left > right ? 1 : 0;
+34 -17
View File
@@ -5,12 +5,14 @@ import { hostingHeadersArtifactSchema } from "./contracts/release-artifacts.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;
@@ -74,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" });
@@ -110,6 +105,7 @@ if (liveTarget?.passed) {
value,
]),
);
return await response.text();
} catch (error: unknown) {
probeResults.push({
surface,
@@ -118,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";
@@ -193,6 +205,7 @@ results.push(
);
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",
@@ -205,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");