chore(review): 1103 release·CI·성능 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-07 13-01~13-03 13-05 15-02~15-07 # Conflicts: # docs/manual/03-outside-feature-folder.md # docs/operations/performance-evidence.md # scripts/lib/hosting-probe.ts
This commit is contained in:
+48
-9
@@ -1,6 +1,9 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import { evaluateBundleBudget } from "./lib/performance-budgets.ts";
|
||||
import {
|
||||
describeBundleBudgetFailures,
|
||||
evaluateBundleBudget,
|
||||
} from "./lib/performance-budgets.ts";
|
||||
import {
|
||||
bundleOutputInventoryArtifactSchema,
|
||||
bundlePerformanceArtifactSchema,
|
||||
@@ -14,6 +17,7 @@ type ViteManifest = Record<
|
||||
>;
|
||||
type BundleBudgets = {
|
||||
initialJsGzipBytes: number;
|
||||
initialJsFiles: number;
|
||||
lazyChunkGzipBytes: number;
|
||||
};
|
||||
|
||||
@@ -43,7 +47,11 @@ const missingOutputs = [
|
||||
...classification.initialFiles,
|
||||
...classification.lazyFiles,
|
||||
].filter((file) => !outputByPath.has(file));
|
||||
const measurements = { initialJsGzipBytes, lazyChunks };
|
||||
const measurements = {
|
||||
initialJsGzipBytes,
|
||||
initialJsFiles: classification.initialFiles.length,
|
||||
lazyChunks,
|
||||
};
|
||||
const result = evaluateBundleBudget(measurements, budgets);
|
||||
const fixtures = [
|
||||
{
|
||||
@@ -52,6 +60,7 @@ const fixtures = [
|
||||
!evaluateBundleBudget(
|
||||
{
|
||||
initialJsGzipBytes: budgets.initialJsGzipBytes + 1,
|
||||
initialJsFiles: 0,
|
||||
lazyChunks: [],
|
||||
},
|
||||
budgets,
|
||||
@@ -63,6 +72,7 @@ const fixtures = [
|
||||
!evaluateBundleBudget(
|
||||
{
|
||||
initialJsGzipBytes: 0,
|
||||
initialJsFiles: 0,
|
||||
lazyChunks: [
|
||||
{
|
||||
path: "fixture.js",
|
||||
@@ -73,6 +83,18 @@ const fixtures = [
|
||||
budgets,
|
||||
).passed,
|
||||
},
|
||||
{
|
||||
name: "initial-files-over-budget",
|
||||
passed:
|
||||
!evaluateBundleBudget(
|
||||
{
|
||||
initialJsGzipBytes: 0,
|
||||
initialJsFiles: budgets.initialJsFiles + 1,
|
||||
lazyChunks: [],
|
||||
},
|
||||
budgets,
|
||||
).passed,
|
||||
},
|
||||
];
|
||||
const passed =
|
||||
result.passed &&
|
||||
@@ -95,15 +117,32 @@ await writeValidatedJsonArtifact({
|
||||
schema: bundlePerformanceArtifactSchema,
|
||||
value: completedReport,
|
||||
});
|
||||
// 1103/15-03. The budget and the manifest integrity fail for different
|
||||
// reasons, so each says what failed and by how much.
|
||||
if (!passed) {
|
||||
process.stderr.write(
|
||||
`Bundle budget or manifest integrity failed: ${[
|
||||
...classification.missingImports,
|
||||
...missingOutputs,
|
||||
].join(", ")}\n`,
|
||||
);
|
||||
const budgetFailures = describeBundleBudgetFailures(measurements, budgets);
|
||||
if (budgetFailures.length > 0) {
|
||||
process.stderr.write(
|
||||
`Bundle budget failed (config/performance/budgets.json):\n${budgetFailures
|
||||
.map((line) => ` ${line}\n`)
|
||||
.join("")}`,
|
||||
);
|
||||
}
|
||||
const integrityFailures = [
|
||||
...classification.missingImports.map((key) => `manifest import without an entry: ${key}`),
|
||||
...missingOutputs.map((file) => `output missing from the inventory: ${file}`),
|
||||
...fixtures
|
||||
.filter((fixture) => !fixture.passed)
|
||||
.map((fixture) => `budget self-check did not fail: ${fixture.name}`),
|
||||
];
|
||||
if (integrityFailures.length > 0) {
|
||||
process.stderr.write(
|
||||
`Bundle manifest integrity failed:\n${integrityFailures.map((line) => ` ${line}\n`).join("")}`,
|
||||
);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Bundle budget: PASS (initial JS ${initialJsGzipBytes} / ${budgets.initialJsGzipBytes} gzip bytes)\n`,
|
||||
`Bundle budget: PASS (initial JS ${initialJsGzipBytes} / ${budgets.initialJsGzipBytes} gzip bytes, ` +
|
||||
`${measurements.initialJsFiles} / ${budgets.initialJsFiles} files)\n`,
|
||||
);
|
||||
|
||||
@@ -17,6 +17,7 @@ import {
|
||||
renderCiWorkflow,
|
||||
workflowGateExecutionFailures,
|
||||
} from "./generate-ci-workflow.ts";
|
||||
import { loadProductCiOverlay } from "./contracts/product-ci-overlay.ts";
|
||||
import {
|
||||
ciContractReportSchema,
|
||||
} from "./lib/ci-contract-report.ts";
|
||||
@@ -40,6 +41,9 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
const contract = await loadCiGateContract(process.cwd());
|
||||
const index = indexCiGateContract(contract);
|
||||
// 1103/12-07. The product's merge gates are entry scripts of CI as well.
|
||||
const { mergeGates: productGates } = await loadProductCiOverlay(process.cwd());
|
||||
const productGateScripts = productGates.map(({ script }) => script);
|
||||
const [packageDocument, nodeVersion] = await Promise.all([
|
||||
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
|
||||
readFile(".nvmrc", "utf8").then((value) => value.trim()),
|
||||
@@ -85,7 +89,7 @@ try {
|
||||
testFiles: await listTestFiles(process.cwd()),
|
||||
gatedPaths: gatedTestPaths(
|
||||
packageScripts,
|
||||
contract.commands.map(({ script }) => script),
|
||||
[...contract.commands.map(({ script }) => script), ...productGateScripts],
|
||||
(file) => readFileSync(file, "utf8"),
|
||||
),
|
||||
exclusions: parseUngatedTestExclusions(
|
||||
@@ -100,7 +104,7 @@ try {
|
||||
// 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);
|
||||
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
|
||||
failures.push(
|
||||
...ungatedScriptFailures({
|
||||
scripts: packageScripts,
|
||||
@@ -148,10 +152,11 @@ for (const readiness of Object.keys(PROMOTION_FORMULA) as Array<keyof typeof PRO
|
||||
}
|
||||
if (!Object.values(allPass).every(Boolean)) failures.push("all-PASS formula did not produce every readiness state");
|
||||
|
||||
const renderedWorkflow = renderCiWorkflow(contract);
|
||||
const renderedWorkflow = renderCiWorkflow(contract, productGates);
|
||||
const workflowCheck = await generateCiWorkflow({
|
||||
root: process.cwd(),
|
||||
contract,
|
||||
productGates,
|
||||
check: true,
|
||||
});
|
||||
if (!workflowCheck.matches) {
|
||||
@@ -165,7 +170,9 @@ try {
|
||||
} catch (error) {
|
||||
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
failures.push(...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8")));
|
||||
failures.push(
|
||||
...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8"), productGates),
|
||||
);
|
||||
const report = ciContractReportSchema.parse({
|
||||
schemaVersion: 2,
|
||||
nodeVersion,
|
||||
|
||||
@@ -12,6 +12,10 @@ import { unknownProductFeatureOverrides } from "../src/contracts/product-feature
|
||||
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
|
||||
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
|
||||
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
|
||||
import {
|
||||
changedRuntimeConfigBuildFields,
|
||||
RUNTIME_CONFIG_EMERGENCY_SWITCHES,
|
||||
} from "./lib/runtime-config-switches.ts";
|
||||
|
||||
/**
|
||||
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
|
||||
@@ -30,17 +34,7 @@ import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-
|
||||
|
||||
const RUNTIME_CONFIG_PATH = "dist/config.json";
|
||||
const RECORD_PATH = "artifacts/release/deployment-admission.json";
|
||||
|
||||
/**
|
||||
* 1101/13-05. The only fields an operator may change in a deployed config.json
|
||||
* without a rebuild (docs/runbooks/FE-RB-001.md). Every other field belongs to
|
||||
* the build: BUILD_ID and RELEASE_ID must still match the deployed HTML and
|
||||
* release manifest, or every boot stops with CONFIG_BUILD_MISMATCH.
|
||||
*/
|
||||
const EMERGENCY_SWITCHES: ReadonlySet<string> = new Set([
|
||||
"CAPABILITY_OVERRIDES",
|
||||
"FEATURE_OVERRIDES",
|
||||
]);
|
||||
const EMERGENCY_SWITCHES = RUNTIME_CONFIG_EMERGENCY_SWITCHES;
|
||||
|
||||
function refuse(reason: string): void {
|
||||
process.stderr.write(`release admission refused: ${reason}\n`);
|
||||
@@ -67,18 +61,6 @@ async function readRuntimeConfig(file: string): Promise<AdmissionInput | null> {
|
||||
}
|
||||
}
|
||||
|
||||
function changedBuildFields(original: object, edited: object): string[] {
|
||||
const before = new Map(Object.entries(original));
|
||||
const after = new Map(Object.entries(edited));
|
||||
return [...new Set([...before.keys(), ...after.keys()])]
|
||||
.filter(
|
||||
(field) =>
|
||||
!EMERGENCY_SWITCHES.has(field) &&
|
||||
JSON.stringify(before.get(field)) !== JSON.stringify(after.get(field)),
|
||||
)
|
||||
.sort();
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
// `pnpm check:release-admission -- --config …` may pass the separator through.
|
||||
const argv = process.argv.slice(2);
|
||||
@@ -127,7 +109,7 @@ async function main(): Promise<void> {
|
||||
if (options.original !== undefined) {
|
||||
const original = await readRuntimeConfig(options.original);
|
||||
if (original === null) return;
|
||||
const changed = changedBuildFields(original, config);
|
||||
const changed = changedRuntimeConfigBuildFields(original, config);
|
||||
if (changed.length > 0) {
|
||||
refuse(
|
||||
`${configPath} changes ${changed.join(", ")}; without a rebuild only ` +
|
||||
|
||||
@@ -14,6 +14,7 @@ import {
|
||||
validateNpmScopeEnvironment,
|
||||
validatePackageScriptGraph,
|
||||
} from "../lib/package-script-graph.ts";
|
||||
import { loadProductCiOverlay, withProductDeployment } from "./product-ci-overlay.ts";
|
||||
import { PROMOTED_UPLOAD_PATHS } from "./promotion-artifacts.ts";
|
||||
|
||||
const ciActionRegistrationSchema = z
|
||||
@@ -583,20 +584,30 @@ export function parseCiGateContract(value: unknown): CiGateContract {
|
||||
export async function loadCiGateContract(
|
||||
root = process.cwd(),
|
||||
): Promise<CiGateContract> {
|
||||
const [rawContract, rawPackage] = await Promise.all([
|
||||
const [rawContract, rawPackage, overlay] = await Promise.all([
|
||||
readFile(path.join(root, "config/ci/gates.json"), "utf8"),
|
||||
readFile(path.join(root, "package.json"), "utf8"),
|
||||
loadProductCiOverlay(root),
|
||||
]);
|
||||
const contract = parseCiGateContract(JSON.parse(rawContract));
|
||||
const template = parseCiGateContract(JSON.parse(rawContract));
|
||||
// 1103/12-07. The product fills the deployment slot in its own overlay; the
|
||||
// filled contract is parsed again, so the template's slot rules hold.
|
||||
const contract = overlay.deployment === null
|
||||
? template
|
||||
: parseCiGateContract(withProductDeployment(JSON.parse(rawContract), overlay.deployment));
|
||||
const packageDocument = z
|
||||
.object({ scripts: z.record(z.string(), z.string()).default({}) })
|
||||
.passthrough()
|
||||
.parse(JSON.parse(rawPackage));
|
||||
// 1101/13-01. A filled deployment slot runs a package script in CI, under the
|
||||
// same existence and script-graph rules as a gate command.
|
||||
const deployScripts = contract.jobs.flatMap(({ steps }) =>
|
||||
steps.flatMap((step) => (step.kind === "deploy" && step.script ? [step.script] : [])),
|
||||
);
|
||||
// same existence and script-graph rules as a gate command. So does a
|
||||
// product merge gate (1103/12-07).
|
||||
const deployScripts = [
|
||||
...contract.jobs.flatMap(({ steps }) =>
|
||||
steps.flatMap((step) => (step.kind === "deploy" && step.script ? [step.script] : [])),
|
||||
),
|
||||
...overlay.mergeGates.map(({ script }) => script),
|
||||
];
|
||||
const missing = [...contract.commands.map((command) => command.script), ...deployScripts]
|
||||
.filter((script, index, scripts) => scripts.indexOf(script) === index)
|
||||
.filter((script) => !packageDocument.scripts[script]);
|
||||
@@ -643,7 +654,8 @@ export async function loadCiGateContract(
|
||||
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
|
||||
);
|
||||
}
|
||||
await assertCiContractBaseline(root, contract);
|
||||
// The baseline describes the template contract; the overlay is the product's.
|
||||
await assertCiContractBaseline(root, template);
|
||||
return contract;
|
||||
}
|
||||
|
||||
@@ -1027,6 +1039,7 @@ function validateContractSemantics(
|
||||
if (duplicate || foreign.length > 0) {
|
||||
issue(`deployment slot binding must be the candidate digest or a vars.* or secrets.* value: ${job.id}`);
|
||||
}
|
||||
for (const failure of deploymentSlotInputFailures(job)) issue(failure);
|
||||
} else if (duplicate || JSON.stringify(job.environment) !== JSON.stringify(expectedEnvironmentBindings[job.id])) {
|
||||
issue(`job environment binding drift: ${job.id}`);
|
||||
}
|
||||
@@ -1244,6 +1257,47 @@ function validateCanonicalStepFields(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/13-01. A slot that runs a deploy script deploys the promoted candidate:
|
||||
* it downloads the promoted-release transfer and extracts its
|
||||
* release-candidate.tar.gz, checked against the digest immutable_build
|
||||
* recorded, before the script runs. A slot that rebuilt instead passed the
|
||||
* contract under the name deploy-promoted-release, and FE-GATE-019 could not
|
||||
* tell the rebuild from the candidate.
|
||||
*/
|
||||
function deploymentSlotInputFailures(job: z.infer<typeof jobSchema>): string[] {
|
||||
const deploy = job.steps.find((step) => step.kind === "deploy");
|
||||
if (deploy?.kind !== "deploy" || deploy.script === undefined) return [];
|
||||
const failures: string[] = [];
|
||||
const downloads = job.steps.filter((step) => step.kind === "download");
|
||||
const download = downloads[0];
|
||||
const extract = job.steps.find((step) => step.kind === "extract");
|
||||
if (
|
||||
downloads.length !== 1 ||
|
||||
download?.kind !== "download" ||
|
||||
download.transferId !== "promoted-release" ||
|
||||
extract?.kind !== "extract" ||
|
||||
extract.archivePath !== `${download.path}/release-candidate.tar.gz` ||
|
||||
job.steps.indexOf(download) > job.steps.indexOf(extract)
|
||||
) {
|
||||
failures.push(
|
||||
`deployment slot with a deploy script must download only the promoted-release transfer and extract its release-candidate.tar.gz before deploying: ${job.id}`,
|
||||
);
|
||||
}
|
||||
if (
|
||||
!job.environment.some(
|
||||
({ name, value }) =>
|
||||
name === "CANDIDATE_ARCHIVE_SHA256" &&
|
||||
value === "${{ needs.immutable_build.outputs.archive_sha256 }}",
|
||||
)
|
||||
) {
|
||||
failures.push(
|
||||
`deployment slot with a deploy script must bind CANDIDATE_ARCHIVE_SHA256 so its extract step checks the promoted archive: ${job.id}`,
|
||||
);
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
function validateJobStepKinds(
|
||||
job: z.infer<typeof jobSchema>,
|
||||
issue: (message: string, path?: PropertyKey[]) => void,
|
||||
|
||||
@@ -0,0 +1,146 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
/**
|
||||
* 1103/12-07. The product's own part of CI, kept out of the template-owned
|
||||
* config/ci/gates.json so a template sync never meets it. The template ships
|
||||
* this file empty and does not change it. It may hold only:
|
||||
*
|
||||
* - `deployment`: the package script that deploys the promoted release, and
|
||||
* its `vars.*` / `secrets.*` bindings. The template renders the rest of the
|
||||
* slot (download the promoted-release transfer, extract it against the
|
||||
* candidate digest, then run the script); secrets reach the deploy step only
|
||||
* (1103/13-05).
|
||||
* - `mergeGates`: product checks that run on every merge-stage run, in a job
|
||||
* of their own (`product_merge_gate`). Their ids are `PRODUCT-GATE-NNN`, so
|
||||
* they never take or change a template gate (`FE-GATE-NNN`), its commands,
|
||||
* artifacts or readiness formula. The template contract baseline counts
|
||||
* only the template contract.
|
||||
*/
|
||||
export const PRODUCT_CI_OVERLAY_PATH = "config/ci/product-gates.json";
|
||||
|
||||
const scriptName = z
|
||||
.string()
|
||||
.max(128)
|
||||
.regex(/^[A-Za-z0-9:_-]+$/u, "a product script is a package script name ([A-Za-z0-9:_-])");
|
||||
const binding = z
|
||||
.object({
|
||||
name: z.string().regex(/^[A-Z][A-Z0-9_]*$/u),
|
||||
value: z
|
||||
.string()
|
||||
.regex(
|
||||
/^\$\{\{ (?:vars|secrets)\.[A-Za-z_][A-Za-z0-9_]* \}\}$/u,
|
||||
"a product binding must be a vars.* or secrets.* value",
|
||||
),
|
||||
})
|
||||
.strict();
|
||||
const productGate = z
|
||||
.object({
|
||||
id: z
|
||||
.string()
|
||||
.regex(/^PRODUCT-GATE-\d{3}$/u, "product gate ids are PRODUCT-GATE-NNN; FE-GATE-NNN ids belong to the template"),
|
||||
name: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/u),
|
||||
script: scriptName,
|
||||
})
|
||||
.strict();
|
||||
|
||||
const productCiOverlaySchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(1),
|
||||
deployment: z
|
||||
.object({ script: scriptName, environment: z.array(binding).max(32) })
|
||||
.strict()
|
||||
.nullable(),
|
||||
mergeGates: z.array(productGate).max(32),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((overlay, context) => {
|
||||
const issue = (message: string) => context.addIssue({ code: "custom", message });
|
||||
const names = overlay.deployment?.environment.map(({ name }) => name) ?? [];
|
||||
if (new Set(names).size !== names.length) issue("duplicate deployment binding name");
|
||||
if (names.includes("CANDIDATE_ARCHIVE_SHA256")) {
|
||||
issue("CANDIDATE_ARCHIVE_SHA256 is bound by the template to the immutable_build digest");
|
||||
}
|
||||
for (const field of ["id", "name"] as const) {
|
||||
const values = overlay.mergeGates.map((gate) => gate[field]);
|
||||
if (new Set(values).size !== values.length) issue(`duplicate product gate ${field}`);
|
||||
}
|
||||
});
|
||||
|
||||
export type ProductCiOverlay = z.infer<typeof productCiOverlaySchema>;
|
||||
export type ProductDeployment = NonNullable<ProductCiOverlay["deployment"]>;
|
||||
export type ProductGate = ProductCiOverlay["mergeGates"][number];
|
||||
|
||||
const EMPTY_PRODUCT_CI_OVERLAY: ProductCiOverlay = Object.freeze({
|
||||
schemaVersion: 1,
|
||||
deployment: null,
|
||||
mergeGates: [],
|
||||
});
|
||||
|
||||
export function parseProductCiOverlay(value: unknown): ProductCiOverlay {
|
||||
const result = productCiOverlaySchema.safeParse(value);
|
||||
if (!result.success) {
|
||||
throw new TypeError(
|
||||
`${PRODUCT_CI_OVERLAY_PATH} invalid:\n${result.error.issues
|
||||
.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
|
||||
.join("\n")}`,
|
||||
);
|
||||
}
|
||||
return result.data;
|
||||
}
|
||||
|
||||
/** The overlay of `root`; a checkout without the file (synced before it existed) has none. */
|
||||
export async function loadProductCiOverlay(root: string): Promise<ProductCiOverlay> {
|
||||
let text: string;
|
||||
try {
|
||||
text = await readFile(path.join(root, PRODUCT_CI_OVERLAY_PATH), "utf8");
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") return EMPTY_PRODUCT_CI_OVERLAY;
|
||||
throw error;
|
||||
}
|
||||
return parseProductCiOverlay(JSON.parse(text));
|
||||
}
|
||||
|
||||
const PROMOTED_DOWNLOAD_PATH = ".release/deployment";
|
||||
/** Where the slot extracts the promoted archive; the deploy script uploads `<this>/dist`. */
|
||||
export const PROMOTED_RELEASE_ROOT = ".release/promoted-release";
|
||||
|
||||
/**
|
||||
* The template contract document with its empty deployment slot filled from
|
||||
* the overlay. The caller parses the result, so the slot rules of the
|
||||
* template contract still apply. A slot the template contract already
|
||||
* filled is refused: the slot has one owner.
|
||||
*/
|
||||
export function withProductDeployment(contract: unknown, deployment: ProductDeployment): unknown {
|
||||
const document = structuredClone(contract) as { jobs?: { id?: unknown; steps?: unknown; environment?: unknown }[] };
|
||||
const slot = document.jobs?.find(({ id }) => id === "deployment");
|
||||
if (
|
||||
!slot ||
|
||||
JSON.stringify(slot.steps) !== JSON.stringify([{ kind: "deploy" }]) ||
|
||||
JSON.stringify(slot.environment) !== "[]"
|
||||
) {
|
||||
throw new TypeError(
|
||||
`the deployment slot is filled in config/ci/gates.json and in ${PRODUCT_CI_OVERLAY_PATH}; ` +
|
||||
`keep the template slot empty and fill ${PRODUCT_CI_OVERLAY_PATH}`,
|
||||
);
|
||||
}
|
||||
slot.environment = [
|
||||
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
|
||||
...deployment.environment,
|
||||
];
|
||||
slot.steps = [
|
||||
{ kind: "checkout" },
|
||||
{ kind: "setup-node" },
|
||||
{ kind: "frozen-install" },
|
||||
{ kind: "download", transferId: "promoted-release", path: PROMOTED_DOWNLOAD_PATH },
|
||||
{
|
||||
kind: "extract",
|
||||
archivePath: `${PROMOTED_DOWNLOAD_PATH}/release-candidate.tar.gz`,
|
||||
targetRoot: PROMOTED_RELEASE_ROOT,
|
||||
},
|
||||
{ kind: "deploy", script: deployment.script },
|
||||
];
|
||||
return document;
|
||||
}
|
||||
@@ -364,12 +364,14 @@ const bundleClassificationSchema = z
|
||||
const bundleThresholdsSchema = z
|
||||
.object({
|
||||
initialJsGzipBytes: z.int().positive(),
|
||||
initialJsFiles: z.int().positive(),
|
||||
lazyChunkGzipBytes: z.int().positive(),
|
||||
})
|
||||
.strict();
|
||||
const bundleBudgetResultSchema = z
|
||||
.object({
|
||||
initialPassed: z.boolean(),
|
||||
initialFilesPassed: z.boolean(),
|
||||
lazyResults: z.array(
|
||||
bundleMeasurementSchema.extend({
|
||||
threshold: z.int().positive(),
|
||||
@@ -386,6 +388,7 @@ export const bundlePerformanceArtifactSchema = z
|
||||
measurements: z
|
||||
.object({
|
||||
initialJsGzipBytes: z.int().nonnegative(),
|
||||
initialJsFiles: z.int().nonnegative(),
|
||||
lazyChunks: z.array(bundleMeasurementSchema),
|
||||
})
|
||||
.strict(),
|
||||
@@ -396,6 +399,7 @@ export const bundlePerformanceArtifactSchema = z
|
||||
fixtures: z.tuple([
|
||||
z.object({ name: z.literal("initial-js-over-budget"), passed: z.boolean() }).strict(),
|
||||
z.object({ name: z.literal("lazy-chunk-over-budget"), passed: z.boolean() }).strict(),
|
||||
z.object({ name: z.literal("initial-files-over-budget"), passed: z.boolean() }).strict(),
|
||||
]),
|
||||
passed: z.boolean(),
|
||||
})
|
||||
@@ -441,6 +445,9 @@ export const bundlePerformanceArtifactSchema = z
|
||||
if (artifact.measurements.initialJsGzipBytes !== expectedInitialBytes) {
|
||||
issue(["measurements", "initialJsGzipBytes"], "must equal classified initial output bytes");
|
||||
}
|
||||
if (artifact.measurements.initialJsFiles !== artifact.classification.initialFiles.length) {
|
||||
issue(["measurements", "initialJsFiles"], "must equal the classified initial file count");
|
||||
}
|
||||
const expectedLazyChunks = artifact.classification.lazyFiles.map((file) => ({
|
||||
path: file,
|
||||
gzipBytes: outputs.get(file)?.gzipBytes ?? 0,
|
||||
@@ -453,6 +460,11 @@ export const bundlePerformanceArtifactSchema = z
|
||||
if (artifact.results.initialPassed !== expectedInitialPassed) {
|
||||
issue(["results", "initialPassed"], "must agree with initial threshold");
|
||||
}
|
||||
const expectedInitialFilesPassed =
|
||||
artifact.measurements.initialJsFiles <= artifact.thresholds.initialJsFiles;
|
||||
if (artifact.results.initialFilesPassed !== expectedInitialFilesPassed) {
|
||||
issue(["results", "initialFilesPassed"], "must agree with the initial file threshold");
|
||||
}
|
||||
const expectedLazyResults = artifact.measurements.lazyChunks.map((chunk) => ({
|
||||
...chunk,
|
||||
threshold: artifact.thresholds.lazyChunkGzipBytes,
|
||||
@@ -462,7 +474,9 @@ export const bundlePerformanceArtifactSchema = z
|
||||
issue(["results", "lazyResults"], "must agree with lazy measurements and threshold");
|
||||
}
|
||||
const expectedBudgetPassed =
|
||||
expectedInitialPassed && expectedLazyResults.every(({ passed }) => passed);
|
||||
expectedInitialPassed &&
|
||||
expectedInitialFilesPassed &&
|
||||
expectedLazyResults.every(({ passed }) => passed);
|
||||
if (artifact.results.passed !== expectedBudgetPassed) {
|
||||
issue(["results", "passed"], "must agree with budget results");
|
||||
}
|
||||
|
||||
@@ -18,6 +18,7 @@ import {
|
||||
type CiWorkflowJob,
|
||||
type CiWorkflowStep,
|
||||
} from "./contracts/ci-gates.ts";
|
||||
import { loadProductCiOverlay, type ProductGate } from "./contracts/product-ci-overlay.ts";
|
||||
import {
|
||||
assertSafeExistingPublishPath,
|
||||
assertSafePublishLeaf,
|
||||
@@ -28,6 +29,8 @@ import { VISUAL_TEST_FONT_INSTALL_ARGUMENTS } from "./lib/visual-test-fonts.ts";
|
||||
export type GenerateCiWorkflowOptions = Readonly<{
|
||||
root: string;
|
||||
contract?: CiGateContract;
|
||||
/** Product merge gates; read from the root's config/ci/product-gates.json when omitted. */
|
||||
productGates?: readonly ProductGate[];
|
||||
check: boolean;
|
||||
}>;
|
||||
|
||||
@@ -62,7 +65,10 @@ const defaultFileSystem: CiWorkflowFileSystem = Object.freeze({
|
||||
rm: async (target) => rm(target, { force: true }),
|
||||
});
|
||||
|
||||
export function renderCiWorkflow(contract: CiGateContract): string {
|
||||
export function renderCiWorkflow(
|
||||
contract: CiGateContract,
|
||||
productGates: readonly ProductGate[] = [],
|
||||
): string {
|
||||
const index = indexCiGateContract(contract);
|
||||
const transfers = new Map<string, { name: string }>();
|
||||
for (const job of contract.jobs) {
|
||||
@@ -109,9 +115,48 @@ export function renderCiWorkflow(contract: CiGateContract): string {
|
||||
if (jobIndex > 0) lines.push("");
|
||||
lines.push(...renderJob(job, index, transfers));
|
||||
}
|
||||
if (productGates.length > 0) lines.push("", ...renderProductGateJob(productGates));
|
||||
return `${lines.join("\n").replace(/\n+$/u, "")}\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/12-07. The product's merge gates (config/ci/product-gates.json) run in
|
||||
* a job after every template job, on the same merge condition. A product gate
|
||||
* is one package script; it has no log artifact or evidence of the template
|
||||
* gate contract and is not part of its readiness formula, so the product makes
|
||||
* this job a required check where it wants it to block a merge.
|
||||
*/
|
||||
function renderProductGateJob(productGates: readonly ProductGate[]): string[] {
|
||||
return [
|
||||
" product_merge_gate:",
|
||||
` name: ${yamlScalar("${{ matrix.gate }} / ${{ matrix.name }}")}`,
|
||||
` if: ${renderCondition("merge")}`,
|
||||
" runs-on: ubuntu-latest",
|
||||
" timeout-minutes: 45",
|
||||
" strategy:",
|
||||
" fail-fast: false",
|
||||
" matrix:",
|
||||
" include:",
|
||||
...productGates.map(
|
||||
(gate) => ` - { gate: ${gate.id}, name: ${gate.name}, script: ${yamlScalar(gate.script)} }`,
|
||||
),
|
||||
" steps:",
|
||||
` - uses: ${requiredStepActionUses("checkout")}`,
|
||||
" with:",
|
||||
" persist-credentials: false",
|
||||
` - uses: ${requiredStepActionUses("setup-node")}`,
|
||||
" with:",
|
||||
" node-version-file: .nvmrc",
|
||||
" - name: Frozen install",
|
||||
" run: |",
|
||||
" corepack enable",
|
||||
" corepack pnpm install --frozen-lockfile --ignore-scripts",
|
||||
// The overlay limits the script to [A-Za-z0-9:_-], a plain shell word.
|
||||
" - name: Run product gate",
|
||||
" run: corepack pnpm ${{ matrix.script }}",
|
||||
];
|
||||
}
|
||||
|
||||
function renderJob(
|
||||
job: CiWorkflowJob,
|
||||
index: ReturnType<typeof indexCiGateContract>,
|
||||
@@ -145,9 +190,10 @@ function renderJob(
|
||||
if (job.kind === "deployment") {
|
||||
lines.push(" outputs:", " deployed: ${{ steps.deploy.outputs.deployed }}");
|
||||
}
|
||||
if (job.environment.length > 0) {
|
||||
const jobEnvironment = job.environment.filter((binding) => !isStepScopedSecret(job, binding));
|
||||
if (jobEnvironment.length > 0) {
|
||||
lines.push(" env:");
|
||||
for (const binding of job.environment) {
|
||||
for (const binding of jobEnvironment) {
|
||||
lines.push(` ${binding.name}: ${yamlScalar(binding.value)}`);
|
||||
}
|
||||
}
|
||||
@@ -282,11 +328,15 @@ function renderStep(
|
||||
];
|
||||
// 1101/13-01. `run` fails on the first failing command, so deployed=true
|
||||
// is written only after the project's script succeeded.
|
||||
case "deploy":
|
||||
case "deploy": {
|
||||
const secrets = job.environment.filter((binding) => isStepScopedSecret(job, binding));
|
||||
return step.script
|
||||
? [
|
||||
" - name: Deploy the promoted release",
|
||||
" id: deploy",
|
||||
...(secrets.length > 0
|
||||
? [" env:", ...secrets.map((binding) => ` ${binding.name}: ${yamlScalar(binding.value)}`)]
|
||||
: []),
|
||||
" run: |",
|
||||
// The contract limits the name to [A-Za-z0-9:_-], a plain shell word.
|
||||
` corepack pnpm ${step.script}`,
|
||||
@@ -297,6 +347,7 @@ function renderStep(
|
||||
" id: deploy",
|
||||
' run: echo "deployed=false" >> "$GITHUB_OUTPUT"',
|
||||
];
|
||||
}
|
||||
case "upload": {
|
||||
const lines = [
|
||||
` - name: Upload ${humanize(step.transferId)}`,
|
||||
@@ -316,6 +367,16 @@ function renderStep(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/13-05. Job env reaches every step of the job: checkout, setup-node and
|
||||
* the third-party download action as well. In the deployment slot a
|
||||
* `secrets.*` binding is rendered on the deploy step instead, the one step
|
||||
* that uses it.
|
||||
*/
|
||||
function isStepScopedSecret(job: CiWorkflowJob, binding: CiWorkflowJob["environment"][number]): boolean {
|
||||
return job.kind === "deployment" && /^\$\{\{ secrets\./u.test(binding.value);
|
||||
}
|
||||
|
||||
function requiredStepActionUses(stepKind: string): string {
|
||||
const uses = resolveCiStepActionUses(stepKind);
|
||||
if (!uses) throw new TypeError(`workflow step has no registered CI action: ${stepKind}`);
|
||||
@@ -393,9 +454,22 @@ function runGateStepName(jobId: string, gateId: string): string {
|
||||
export function workflowGateExecutionFailures(
|
||||
contract: CiGateContract,
|
||||
workflow: string,
|
||||
productGates: readonly ProductGate[] = [],
|
||||
): string[] {
|
||||
const executed = new Set<string>();
|
||||
for (const job of workflow.split(/^(?= {2}[a-z_]+:$)/mu)) {
|
||||
const jobs = workflow.split(/^(?= {2}[a-z_]+:$)/mu);
|
||||
const productJob = jobs.find((job) => job.startsWith(" product_merge_gate:\n")) ?? "";
|
||||
const productRuns = /^ {8}run: corepack pnpm \$\{\{ matrix\.script \}\}$/mu.test(productJob);
|
||||
const productFailures = productGates
|
||||
.filter(
|
||||
(gate) =>
|
||||
!productRuns ||
|
||||
!productJob.includes(
|
||||
` - { gate: ${gate.id}, name: ${gate.name}, script: ${yamlScalar(gate.script)} }\n`,
|
||||
),
|
||||
)
|
||||
.map(({ id }) => `product gate is not executed by the product_merge_gate job: ${id}`);
|
||||
for (const job of jobs) {
|
||||
for (const match of job.matchAll(/^ +run: corepack pnpm ci:gate -- (FE-GATE-\d{3})$/gmu)) {
|
||||
executed.add(match[1]!);
|
||||
}
|
||||
@@ -405,9 +479,12 @@ export function workflowGateExecutionFailures(
|
||||
}
|
||||
}
|
||||
}
|
||||
return contract.gates
|
||||
.filter(({ id }) => !executed.has(id))
|
||||
.map(({ id }) => `gate is not executed by any workflow run step: ${id}`);
|
||||
return [
|
||||
...contract.gates
|
||||
.filter(({ id }) => !executed.has(id))
|
||||
.map(({ id }) => `gate is not executed by any workflow run step: ${id}`),
|
||||
...productFailures,
|
||||
];
|
||||
}
|
||||
|
||||
function humanize(value: string): string {
|
||||
@@ -429,7 +506,8 @@ export function createCiWorkflowGenerator(
|
||||
if (path.relative(root, target).startsWith("..") || path.relative(root, target) === "") {
|
||||
throw new TypeError(`workflow target escapes repository root: ${contract.providerAdapter}`);
|
||||
}
|
||||
const expected = Buffer.from(renderCiWorkflow(contract), "utf8");
|
||||
const productGates = options.productGates ?? (await loadProductCiOverlay(root)).mergeGates;
|
||||
const expected = Buffer.from(renderCiWorkflow(contract, productGates), "utf8");
|
||||
let actual: Buffer | null = null;
|
||||
const existingPathIsSafe =
|
||||
fileSystem === defaultFileSystem
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
import { validateVulnerabilityReport } from "./supply-chain.ts";
|
||||
|
||||
/**
|
||||
* 1103/13-03. The vulnerability verdict belongs to the external provider of
|
||||
* the production promotion (signed, independent of the build). Without a
|
||||
* provider nothing told the project that its lockfile already broke the
|
||||
* template's own policy (high and above, no exception). This summary is the
|
||||
* early signal: it reads `pnpm audit --json` and applies that policy, so it
|
||||
* names what the promotion would refuse. It does not replace the provider and
|
||||
* blocks nothing.
|
||||
*/
|
||||
export type AdvisoryStatus = "PASS" | "POLICY_VIOLATION" | "UNVERIFIED";
|
||||
type Severity = "critical" | "high" | "moderate" | "low" | "info";
|
||||
type SeverityCounts = Record<Severity, number>;
|
||||
|
||||
export type DependencyAdvisorySummary = Readonly<{
|
||||
status: AdvisoryStatus;
|
||||
reason: string | null;
|
||||
counts: Readonly<{ production: SeverityCounts; development: SeverityCounts }>;
|
||||
/** Findings the vulnerability policy would block at promotion: `id:package@version:severity`. */
|
||||
blocking: readonly string[];
|
||||
advisories: readonly Readonly<{
|
||||
id: string;
|
||||
packageName: string;
|
||||
versions: readonly string[];
|
||||
severity: string;
|
||||
development: boolean;
|
||||
patchedVersions: string;
|
||||
}>[];
|
||||
}>;
|
||||
|
||||
const SEVERITIES: readonly Severity[] = ["critical", "high", "moderate", "low", "info"];
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function emptyCounts(): SeverityCounts {
|
||||
return { critical: 0, high: 0, moderate: 0, low: 0, info: 0 };
|
||||
}
|
||||
|
||||
export function summarizeDependencyAdvisories(
|
||||
audit: unknown,
|
||||
policy: Readonly<Record<string, unknown>>,
|
||||
exceptions: Readonly<Record<string, unknown>>,
|
||||
lockfileSha256: string,
|
||||
now: Date = new Date(),
|
||||
): DependencyAdvisorySummary {
|
||||
const counts = { production: emptyCounts(), development: emptyCounts() };
|
||||
if (!isRecord(audit) || !isRecord(audit["advisories"]) || !isRecord(audit["metadata"])) {
|
||||
return {
|
||||
status: "UNVERIFIED",
|
||||
reason: "pnpm audit returned no advisory report (network or registry unavailable)",
|
||||
counts,
|
||||
blocking: [],
|
||||
advisories: [],
|
||||
};
|
||||
}
|
||||
const advisories = Object.values(audit["advisories"]).filter(isRecord).map((advisory) => {
|
||||
const findings = Array.isArray(advisory["findings"]) ? advisory["findings"].filter(isRecord) : [];
|
||||
return {
|
||||
id: String(advisory["github_advisory_id"] ?? advisory["id"] ?? "unknown"),
|
||||
packageName: String(advisory["module_name"] ?? "unknown"),
|
||||
versions: findings.map((finding) => String(finding["version"] ?? "unknown")),
|
||||
severity: String(advisory["severity"] ?? "unknown").toLowerCase(),
|
||||
// A package reached only through development dependencies never ships.
|
||||
development: findings.length > 0 && findings.every((finding) => finding["dev"] === true),
|
||||
patchedVersions: String(advisory["patched_versions"] ?? ""),
|
||||
};
|
||||
});
|
||||
for (const advisory of advisories) {
|
||||
const scope = advisory.development ? counts.development : counts.production;
|
||||
if ((SEVERITIES as readonly string[]).includes(advisory.severity)) scope[advisory.severity as Severity] += 1;
|
||||
}
|
||||
const verdict = validateVulnerabilityReport(
|
||||
{
|
||||
provider: "pnpm-audit (local, not the promotion provider)",
|
||||
scannedLockfileSha256: lockfileSha256,
|
||||
findings: advisories.flatMap((advisory) =>
|
||||
advisory.versions.map((version) => ({
|
||||
id: advisory.id,
|
||||
packageName: advisory.packageName,
|
||||
version,
|
||||
severity: advisory.severity,
|
||||
})),
|
||||
),
|
||||
},
|
||||
policy,
|
||||
exceptions,
|
||||
lockfileSha256,
|
||||
now,
|
||||
);
|
||||
return {
|
||||
status: verdict.blocking.length > 0 ? "POLICY_VIOLATION" : "PASS",
|
||||
reason: null,
|
||||
counts,
|
||||
blocking: verdict.blocking,
|
||||
advisories,
|
||||
};
|
||||
}
|
||||
@@ -1,7 +1,10 @@
|
||||
import { isIP } from "node:net";
|
||||
import path from "node:path";
|
||||
import { connect } from "node:tls";
|
||||
|
||||
import type { InstalledServiceWorkerSelection } from "../../src/contracts/service-worker.ts";
|
||||
import { CACHEABLE_ASSET_CONTENT_TYPES } from "../../src/contracts/service-worker-static-manifest.ts";
|
||||
import { changedRuntimeConfigBuildFields } from "./runtime-config-switches.ts";
|
||||
|
||||
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
|
||||
|
||||
@@ -42,6 +45,49 @@ export type ProbeResult = Readonly<{
|
||||
export type ResponseHeaders = Record<string, Record<string, string>>;
|
||||
export type HostingFetcher = (url: URL) => Promise<Response>;
|
||||
export type ReleaseIdentity = Readonly<{ buildId: string; releaseId: string }>;
|
||||
/** The promoted candidate: its manifest names and the texts of its dist/config.json and dist/index.html. */
|
||||
export type CandidateRelease = ReleaseIdentity & Readonly<{ runtimeConfig: string; indexHtml: string }>;
|
||||
export type ProbeTransport = Readonly<{
|
||||
fetcher?: HostingFetcher;
|
||||
/** The ALPN protocol the host negotiates over TLS, or null when none. */
|
||||
negotiateAlpn?: (base: URL) => Promise<string | null>;
|
||||
/** Accepted protocols (`transport.alpnProtocols` in config/hosting/cache-policy.json); empty skips the check. */
|
||||
alpnProtocols?: readonly string[];
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 1103/13-02. Node's fetch speaks HTTP/1.1 even to a host that offers h2, so
|
||||
* the protocol a browser gets is read from the TLS handshake instead: the
|
||||
* client offers h2 and http/1.1 and the host picks one. The certificate is
|
||||
* verified as fetch verifies it.
|
||||
*/
|
||||
export function negotiatedAlpnProtocol(base: URL, timeoutMs = 10_000): Promise<string | null> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const host = base.hostname.replace(/^\[|\]$/gu, "");
|
||||
const socket = connect({
|
||||
host,
|
||||
port: Number(base.port || 443),
|
||||
...(isIP(host) === 0 ? { servername: host } : {}),
|
||||
ALPNProtocols: ["h2", "http/1.1"],
|
||||
});
|
||||
socket.setTimeout(timeoutMs, () => socket.destroy(new Error("TLS handshake timed out")));
|
||||
socket.once("secureConnect", () => {
|
||||
const protocol = socket.alpnProtocol;
|
||||
socket.end();
|
||||
resolve(typeof protocol === "string" ? protocol : null);
|
||||
});
|
||||
socket.once("error", reject);
|
||||
});
|
||||
}
|
||||
|
||||
function parsedJsonObject(text: string | null): object | null {
|
||||
try {
|
||||
const value: unknown = JSON.parse(text ?? "");
|
||||
return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** `buildId` and `releaseId` of a release-manifest.json text, or null. */
|
||||
export function releaseIdentity(manifest: string | null): ReleaseIdentity | null {
|
||||
@@ -67,13 +113,24 @@ export function releaseIdentity(manifest: string | null): ReleaseIdentity | null
|
||||
*
|
||||
* 1101/13-01. The served release manifest must name the candidate's build and
|
||||
* release. Correct headers on an earlier release are not evidence for this one.
|
||||
*
|
||||
* 1103/13-01. Those names come from the CI run, so a release rebuilt in the
|
||||
* same run (say with the local profile) carries them too. The served
|
||||
* config.json must equal the candidate's, the one release admission
|
||||
* (FE-GATE-027) admitted, except for the two emergency switches FE-RB-001 may
|
||||
* change; and the served index.html must name the candidate's entry script.
|
||||
*
|
||||
* 1103/13-02. The host must negotiate a declared protocol (HTTP/2): the
|
||||
* template splits its initial chunks on that premise.
|
||||
*/
|
||||
export async function probeLiveRelease(
|
||||
base: URL,
|
||||
paths: Readonly<Record<string, string>>,
|
||||
candidate: ReleaseIdentity,
|
||||
fetcher: HostingFetcher = (url) => fetch(url, { redirect: "follow" }),
|
||||
candidate: CandidateRelease,
|
||||
transport: ProbeTransport = {},
|
||||
): Promise<{ responses: ResponseHeaders; results: ProbeResult[] }> {
|
||||
const fetcher = transport.fetcher ?? ((url: URL) => fetch(url, { redirect: "follow" }));
|
||||
const negotiateAlpn = transport.negotiateAlpn ?? negotiatedAlpnProtocol;
|
||||
const responses: ResponseHeaders = {};
|
||||
const results: ProbeResult[] = [];
|
||||
const probe = async (surface: string, pathname: string): Promise<string | null> => {
|
||||
@@ -148,6 +205,50 @@ export async function probeLiveRelease(
|
||||
passed: entryScript !== null && observed === entryScript,
|
||||
});
|
||||
}
|
||||
const candidateEntryScript = servedEntryScript(candidate.indexHtml);
|
||||
results.push({
|
||||
surface: "index",
|
||||
header: "candidate-entry-script",
|
||||
expected: candidateEntryScript,
|
||||
observed: entryScript,
|
||||
passed: candidateEntryScript !== null && entryScript === candidateEntryScript,
|
||||
});
|
||||
if ("runtimeConfig" in paths) {
|
||||
const served = parsedJsonObject(bodies["runtimeConfig"] ?? null);
|
||||
const admitted = parsedJsonObject(candidate.runtimeConfig);
|
||||
const changed = served && admitted ? changedRuntimeConfigBuildFields(admitted, served) : null;
|
||||
results.push({
|
||||
surface: "runtimeConfig",
|
||||
header: "build-fields",
|
||||
expected: [],
|
||||
observed: changed ?? "unreadable",
|
||||
...(changed === null
|
||||
? { reason: "the served or the candidate config.json is not a JSON object" }
|
||||
: changed.length > 0
|
||||
? { reason: "differs from the candidate's config.json beyond the emergency switches" }
|
||||
: {}),
|
||||
passed: changed !== null && changed.length === 0,
|
||||
});
|
||||
}
|
||||
const alpnProtocols = transport.alpnProtocols ?? [];
|
||||
if (alpnProtocols.length > 0) {
|
||||
let observed: string | null;
|
||||
try {
|
||||
observed = await negotiateAlpn(base);
|
||||
} catch (error: unknown) {
|
||||
observed = error instanceof Error ? error.name : "UnknownError";
|
||||
}
|
||||
results.push({
|
||||
surface: "transport",
|
||||
header: "alpn",
|
||||
expected: alpnProtocols,
|
||||
observed,
|
||||
...(observed !== null && alpnProtocols.includes(observed)
|
||||
? {}
|
||||
: { reason: "the split initial chunks assume HTTP/2 (docs/architecture/static-delivery.md)" }),
|
||||
passed: observed !== null && alpnProtocols.includes(observed),
|
||||
});
|
||||
}
|
||||
return { responses, results };
|
||||
}
|
||||
|
||||
|
||||
@@ -127,7 +127,7 @@ export async function measureOptionalRecipeBundle(input: Readonly<{
|
||||
copyPublicDir: false,
|
||||
cssCodeSplit: false,
|
||||
reportCompressedSize: false,
|
||||
rollupOptions: {
|
||||
rolldownOptions: {
|
||||
input: virtualEntry,
|
||||
// Budget the complete selected runtime, including internal fail-closed
|
||||
// guards that a synthetic consumer cannot predict it will exercise.
|
||||
|
||||
@@ -1,10 +1,18 @@
|
||||
export type BundleMeasurements = Readonly<{
|
||||
initialJsGzipBytes: number;
|
||||
initialJsFiles: number;
|
||||
lazyChunks: readonly Readonly<{ path: string; gzipBytes: number }>[];
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 1103/15-05. `initialJsFiles` bounds the number of initial JavaScript files
|
||||
* (entry included). The entry preloads them in parallel, which costs no round
|
||||
* trip over HTTP/2 and queues them six at a time over HTTP/1.1
|
||||
* (docs/operations/performance-evidence.md, "초기 청크 수와 HTTP/1.1").
|
||||
*/
|
||||
export type BundleThresholds = Readonly<{
|
||||
initialJsGzipBytes: number;
|
||||
initialJsFiles: number;
|
||||
lazyChunkGzipBytes: number;
|
||||
}>;
|
||||
|
||||
@@ -14,6 +22,7 @@ export function evaluateBundleBudget(
|
||||
) {
|
||||
const initialPassed =
|
||||
measurements.initialJsGzipBytes <= thresholds.initialJsGzipBytes;
|
||||
const initialFilesPassed = measurements.initialJsFiles <= thresholds.initialJsFiles;
|
||||
const lazyResults = measurements.lazyChunks.map((chunk) => ({
|
||||
...chunk,
|
||||
threshold: thresholds.lazyChunkGzipBytes,
|
||||
@@ -21,11 +30,38 @@ export function evaluateBundleBudget(
|
||||
}));
|
||||
return Object.freeze({
|
||||
initialPassed,
|
||||
initialFilesPassed,
|
||||
lazyResults: Object.freeze(lazyResults),
|
||||
passed: initialPassed && lazyResults.every((chunk) => chunk.passed),
|
||||
passed: initialPassed && initialFilesPassed && lazyResults.every((chunk) => chunk.passed),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/15-03. One line per exceeded limit with the measured value, the limit
|
||||
* and the excess, so a failed check:bundle says what to cut without opening
|
||||
* artifacts/performance/bundle.json.
|
||||
*/
|
||||
export function describeBundleBudgetFailures(
|
||||
measurements: BundleMeasurements,
|
||||
thresholds: BundleThresholds,
|
||||
): string[] {
|
||||
const over = (label: string, measured: number, limit: number, unit = " gzip bytes") =>
|
||||
`${label} ${measured}${unit} > budget ${limit} (over by ${measured - limit})`;
|
||||
const lines: string[] = [];
|
||||
if (measurements.initialJsGzipBytes > thresholds.initialJsGzipBytes) {
|
||||
lines.push(over("initial JavaScript", measurements.initialJsGzipBytes, thresholds.initialJsGzipBytes));
|
||||
}
|
||||
if (measurements.initialJsFiles > thresholds.initialJsFiles) {
|
||||
lines.push(over("initial JavaScript files", measurements.initialJsFiles, thresholds.initialJsFiles, ""));
|
||||
}
|
||||
for (const chunk of measurements.lazyChunks) {
|
||||
if (chunk.gzipBytes > thresholds.lazyChunkGzipBytes) {
|
||||
lines.push(over(`lazy chunk ${chunk.path}`, chunk.gzipBytes, thresholds.lazyChunkGzipBytes));
|
||||
}
|
||||
}
|
||||
return lines;
|
||||
}
|
||||
|
||||
export type LabMetrics = Readonly<{
|
||||
lcpMs: number;
|
||||
cls: number;
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
/**
|
||||
* 1101/13-05. The only fields an operator may change in a deployed config.json
|
||||
* without a rebuild (docs/runbooks/FE-RB-001.md). Every other field belongs to
|
||||
* the build: BUILD_ID and RELEASE_ID must still match the deployed HTML and
|
||||
* release manifest, or every boot stops with CONFIG_BUILD_MISMATCH.
|
||||
*
|
||||
* 1103/13-01. The live hosting probe (FE-GATE-019) compares the served
|
||||
* config.json with the promoted candidate's by the same rule, so the release
|
||||
* admission and the probe agree on what an edited document may change.
|
||||
*/
|
||||
export const RUNTIME_CONFIG_EMERGENCY_SWITCHES: ReadonlySet<string> = new Set([
|
||||
"CAPABILITY_OVERRIDES",
|
||||
"FEATURE_OVERRIDES",
|
||||
]);
|
||||
|
||||
/** Fields other than the emergency switches whose values differ, sorted. */
|
||||
export function changedRuntimeConfigBuildFields(original: object, edited: object): string[] {
|
||||
const before = new Map(Object.entries(original));
|
||||
const after = new Map(Object.entries(edited));
|
||||
return [...new Set([...before.keys(), ...after.keys()])]
|
||||
.filter(
|
||||
(field) =>
|
||||
!RUNTIME_CONFIG_EMERGENCY_SWITCHES.has(field) &&
|
||||
JSON.stringify(before.get(field)) !== JSON.stringify(after.get(field)),
|
||||
)
|
||||
.sort();
|
||||
}
|
||||
@@ -25,8 +25,11 @@ import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc-
|
||||
* 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]
|
||||
* node scripts/scale/measure-feature-shape-growth.ts --initial-baseline [--write]
|
||||
*
|
||||
* `--write` stores the result as config/scale/feature-shape-growth.json.
|
||||
* `--write` stores the result as config/scale/feature-shape-growth.json, or
|
||||
* with `--initial-baseline` the initial JavaScript record in
|
||||
* config/scale/feature-shape-ceilings.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. */
|
||||
@@ -143,10 +146,15 @@ function run(
|
||||
cwd: string,
|
||||
options: Readonly<{ allowFailure?: boolean }> = {},
|
||||
) {
|
||||
// 1103/15-02. Vitest sets NODE_ENV=test, and a vite build that inherits it
|
||||
// bundles React's development build: the unit test measured 264 KB where
|
||||
// the production build is 201 KB. Every command here measures production.
|
||||
const { NODE_ENV: _inherited, ...environment } = process.env;
|
||||
const started = performance.now();
|
||||
const result = spawnSync(command, args, {
|
||||
cwd,
|
||||
encoding: "utf8",
|
||||
env: environment,
|
||||
maxBuffer: 64 * 1024 * 1024,
|
||||
});
|
||||
const ms = Math.round(performance.now() - started);
|
||||
@@ -167,23 +175,77 @@ async function javascriptGzipBytes(root: string, files: readonly string[]) {
|
||||
}
|
||||
|
||||
/**
|
||||
* 15-01. Initial JavaScript gzip bytes of the app with `features` reference
|
||||
* copies added: the generator and `vite build` only, no typecheck. The unit
|
||||
* suite (merge stage) bounds what one more feature adds to the initial chunk
|
||||
* with it, so the growth is caught on the PR instead of at the next release.
|
||||
* 15-01. Initial JavaScript of the app with `features` reference copies
|
||||
* added: the generator and `vite build` only, no typecheck. The unit suite
|
||||
* (merge stage) bounds what one more feature adds to the initial chunk with
|
||||
* it, so the growth is caught on the PR instead of at the next release.
|
||||
*/
|
||||
export async function measureInitialJavascriptGzipBytes(features: number): Promise<number> {
|
||||
async function measureInitialJavascript(
|
||||
features: number,
|
||||
): Promise<Readonly<{ gzipBytes: number; files: number }>> {
|
||||
const root = await createFixture(features);
|
||||
try {
|
||||
run(process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], root);
|
||||
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"));
|
||||
return await javascriptGzipBytes(root, classifyViteJavascript(manifest).initialFiles);
|
||||
const { initialFiles } = classifyViteJavascript(manifest);
|
||||
return { gzipBytes: await javascriptGzipBytes(root, initialFiles), files: initialFiles.length };
|
||||
} finally {
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/15-02, 15-04. The template's initial JavaScript and what one more
|
||||
* feature and one more context add to it. The first copy lands in a new
|
||||
* context (shape-context-0) and the second in the same one, so the second
|
||||
* copy is a feature alone and the rest of the first is the context.
|
||||
* `initialJavascript` in config/scale/feature-shape-ceilings.json records
|
||||
* these numbers; tests/unit/feature-shape-growth.test.ts compares them with
|
||||
* the build on every unit run.
|
||||
*/
|
||||
export type InitialJavascriptCosts = Readonly<{
|
||||
gzipBytes: number;
|
||||
files: number;
|
||||
perFeatureGzipBytes: number;
|
||||
perContextGzipBytes: number;
|
||||
}>;
|
||||
|
||||
export async function measureInitialJavascriptCosts(): Promise<InitialJavascriptCosts> {
|
||||
const none = await measureInitialJavascript(0);
|
||||
const one = await measureInitialJavascript(1);
|
||||
const two = await measureInitialJavascript(2);
|
||||
const perFeatureGzipBytes = two.gzipBytes - one.gzipBytes;
|
||||
return {
|
||||
gzipBytes: none.gzipBytes,
|
||||
files: none.files,
|
||||
perFeatureGzipBytes,
|
||||
perContextGzipBytes: one.gzipBytes - none.gzipBytes - perFeatureGzipBytes,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Fields of the record that no longer describe the build. The total moves
|
||||
* by tens of bytes with the build id (CI and local builds differ), so it may
|
||||
* be 1% off; the per-feature and per-context costs are differences of builds
|
||||
* with the same id but only a few hundred bytes, so 10%; the file count is
|
||||
* exact.
|
||||
*/
|
||||
export function initialJavascriptRecordDrift(
|
||||
measured: InitialJavascriptCosts,
|
||||
record: InitialJavascriptCosts,
|
||||
): string[] {
|
||||
const tolerance: Readonly<Record<keyof InitialJavascriptCosts, number>> = {
|
||||
gzipBytes: 0.01,
|
||||
files: 0,
|
||||
perFeatureGzipBytes: 0.1,
|
||||
perContextGzipBytes: 0.1,
|
||||
};
|
||||
return (Object.keys(tolerance) as (keyof InitialJavascriptCosts)[])
|
||||
.filter((field) => Math.abs(record[field] - measured[field]) > Math.abs(measured[field]) * tolerance[field])
|
||||
.map((field) => `${field}: record ${record[field]}, build ${measured[field]}`);
|
||||
}
|
||||
|
||||
async function measureOnce(root: string, features: number) {
|
||||
const loadBefore = load();
|
||||
run(process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], root);
|
||||
@@ -262,7 +324,27 @@ function version(bin: string): string {
|
||||
return (result.stdout ?? "").trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* 1103/15-02. `--initial-baseline` measures the record the documents cite and,
|
||||
* with `--write`, stores it as `initialJavascript` in
|
||||
* config/scale/feature-shape-ceilings.json. Run it in the change that moves
|
||||
* the initial JavaScript.
|
||||
*/
|
||||
async function writeInitialBaseline(): Promise<void> {
|
||||
const measured = await measureInitialJavascriptCosts();
|
||||
process.stdout.write(`initial JavaScript: ${JSON.stringify(measured)}\n`);
|
||||
if (!process.argv.includes("--write")) return;
|
||||
const ceilings = JSON.parse(await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8")) as Record<string, unknown>;
|
||||
ceilings["initialJavascript"] = measured;
|
||||
await writeFile(FEATURE_SHAPE_CEILINGS_PATH, `${JSON.stringify(ceilings, null, 2)}\n`);
|
||||
process.stdout.write(`feature-shape initial baseline: ${FEATURE_SHAPE_CEILINGS_PATH}\n`);
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
if (process.argv.includes("--initial-baseline")) {
|
||||
await writeInitialBaseline();
|
||||
return;
|
||||
}
|
||||
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);
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
|
||||
import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts";
|
||||
|
||||
/**
|
||||
* 1103/13-03. Release-stage signal for known dependency advisories
|
||||
* (FE-GATE-027, next to the release admission of the candidate). It runs
|
||||
* `pnpm audit --json` over the lockfile and applies
|
||||
* config/security/vulnerability-policy.json with its exceptions, the policy the
|
||||
* production promotion provider is held to. The result is a line in the gate
|
||||
* log and artifacts/security/dependency-advisories.json.
|
||||
*
|
||||
* It never fails the gate. An advisory database that changes under unchanged
|
||||
* code would otherwise break a release run, and without the registry the
|
||||
* result is UNVERIFIED, not PASS. The signed verdict of the vulnerability
|
||||
* provider stays the only one that decides a promotion.
|
||||
*/
|
||||
const RECORD_PATH = "artifacts/security/dependency-advisories.json";
|
||||
|
||||
const [policy, exceptions, lockfile] = await Promise.all([
|
||||
readFile("config/security/vulnerability-policy.json", "utf8").then((text) => JSON.parse(text) as Record<string, unknown>),
|
||||
readFile("config/security/vulnerability-exceptions.json", "utf8").then((text) => JSON.parse(text) as Record<string, unknown>),
|
||||
readFile("pnpm-lock.yaml"),
|
||||
]);
|
||||
const lockfileSha256 = createHash("sha256").update(lockfile).digest("hex");
|
||||
|
||||
// pnpm audit exits 1 when it finds advisories; the JSON on stdout is the result.
|
||||
const run = spawnSync("corepack", ["pnpm", "audit", "--json"], {
|
||||
encoding: "utf8",
|
||||
maxBuffer: 64 * 1024 * 1024,
|
||||
timeout: 120_000,
|
||||
});
|
||||
let audit: unknown;
|
||||
try {
|
||||
audit = JSON.parse(run.stdout ?? "");
|
||||
} catch {
|
||||
audit = null;
|
||||
}
|
||||
const summary = summarizeDependencyAdvisories(audit, policy, exceptions, lockfileSha256);
|
||||
|
||||
await mkdir("artifacts/security", { recursive: true });
|
||||
await writeFile(
|
||||
RECORD_PATH,
|
||||
`${JSON.stringify(
|
||||
{
|
||||
schemaVersion: 1,
|
||||
generatedAt: new Date().toISOString(),
|
||||
source: "pnpm audit --json",
|
||||
authoritative: false,
|
||||
lockfileSha256,
|
||||
blockAtSeverity: policy["blockAtSeverity"] ?? null,
|
||||
...summary,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)}\n`,
|
||||
);
|
||||
|
||||
const count = (scope: Readonly<Record<string, number>>) =>
|
||||
`critical ${scope["critical"]}, high ${scope["high"]}, moderate ${scope["moderate"]}, low ${scope["low"]}`;
|
||||
process.stdout.write(
|
||||
`Dependency advisories: ${summary.status} (production: ${count(summary.counts.production)}; ` +
|
||||
`development: ${count(summary.counts.development)}); record at ${RECORD_PATH}. ` +
|
||||
"Not blocking: the production promotion provider decides.\n",
|
||||
);
|
||||
if (summary.status === "POLICY_VIOLATION") {
|
||||
process.stderr.write(
|
||||
`WARNING: the vulnerability policy (block at ${String(policy["blockAtSeverity"])}) would refuse this lockfile at production promotion:\n` +
|
||||
summary.blocking.map((finding) => ` ${finding}\n`).join("") +
|
||||
"Update the dependency or record a reviewed exception in config/security/vulnerability-exceptions.json.\n",
|
||||
);
|
||||
}
|
||||
if (summary.status === "UNVERIFIED") {
|
||||
process.stderr.write(`WARNING: dependency advisories UNVERIFIED: ${summary.reason}\n`);
|
||||
}
|
||||
@@ -100,11 +100,20 @@ if (liveTarget?.passed && !slotEmpty) {
|
||||
),
|
||||
);
|
||||
const candidateManifest = await readFile(path.join(distRoot, "release-manifest.json"), "utf8").catch(() => null);
|
||||
const candidate = releaseIdentity(candidateManifest);
|
||||
if (!candidate) {
|
||||
const identity = releaseIdentity(candidateManifest);
|
||||
if (!identity) {
|
||||
throw new Error(`${distRoot}/release-manifest.json does not name a buildId and releaseId`);
|
||||
}
|
||||
const probed = await probeLiveRelease(liveTarget.url, paths, candidate);
|
||||
// 1103/13-01. The served config.json and index.html are compared with the
|
||||
// candidate's, not only the manifest names a rebuild in the same run shares.
|
||||
const candidate = {
|
||||
...identity,
|
||||
runtimeConfig: await readFile(path.join(distRoot, "config.json"), "utf8"),
|
||||
indexHtml: await readFile(path.join(distRoot, "index.html"), "utf8"),
|
||||
};
|
||||
const probed = await probeLiveRelease(liveTarget.url, paths, candidate, {
|
||||
alpnProtocols: strings(recordValue(cachePolicy.transport).alpnProtocols),
|
||||
});
|
||||
responses = probed.responses;
|
||||
probeResults.push(...probed.results);
|
||||
// 1103/06-03. The worker needs every precached asset kind typed exactly.
|
||||
@@ -151,6 +160,19 @@ for (const [surface, policy] of requiredSurfaces) {
|
||||
observed: observedContentType,
|
||||
passed: observedMime !== undefined && contentTypes.includes(observedMime),
|
||||
});
|
||||
// 1103/13-02. The bundle budget counts gzip bytes. The probe's fetch offers
|
||||
// br and gzip, so an uncompressed answer is the host's choice.
|
||||
const contentEncodings = strings(policy.contentEncodings);
|
||||
if (contentEncodings.length > 0) {
|
||||
const observedEncoding = responses[surface]?.["content-encoding"];
|
||||
results.push({
|
||||
surface,
|
||||
header: "content-encoding",
|
||||
expected: contentEncodings,
|
||||
observed: observedEncoding,
|
||||
passed: observedEncoding !== undefined && contentEncodings.includes(observedEncoding.trim().toLowerCase()),
|
||||
});
|
||||
}
|
||||
if (policy.securityHeaders === true) {
|
||||
for (const [header, expected] of Object.entries(securityHeaders)) {
|
||||
const observedSecurity = responses[surface]?.[header.toLowerCase()];
|
||||
@@ -207,7 +229,7 @@ if (status === "FAIL") {
|
||||
}
|
||||
if (status === "UNVERIFIED" && slotEmpty) {
|
||||
process.stderr.write(
|
||||
"Hosting header contract: UNVERIFIED (the deployment slot is empty: nothing deployed this release, so the host was not probed; fill the deployment job in config/ci/gates.json)\n",
|
||||
"Hosting header contract: UNVERIFIED (the deployment slot is empty: nothing deployed this release, so the host was not probed; fill deployment in config/ci/product-gates.json)\n",
|
||||
);
|
||||
process.exit(3);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user