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:
@@ -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");
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user