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:
DongHyeonka
2026-11-04 23:10:59 +09:00
45 changed files with 3393 additions and 1732 deletions
+48 -9
View File
@@ -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`,
);
+11 -4
View File
@@ -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,
+6 -24
View File
@@ -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 ` +
+61 -7
View File
@@ -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,
+146
View File
@@ -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;
}
+15 -1
View File
@@ -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");
}
+87 -9
View File
@@ -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
+100
View File
@@ -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,
};
}
+103 -2
View File
@@ -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 };
}
+1 -1
View File
@@ -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.
+37 -1
View File
@@ -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;
+27
View File
@@ -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();
}
+89 -7
View File
@@ -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);
+77
View File
@@ -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`);
}
+26 -4
View File
@@ -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);
}