문제: 배포 슬롯을 채우거나 제품 전용 merge 검사를 더하려면 템플릿 소유 config/ci/gates.json(약 3,000줄)과 생성 workflow를 고쳐야 했다. 문서도 "deployment job을 gates.json에서 고치라"고 적었다. 템플릿 gates.json이 바뀔 때마다 제품은 큰 JSON과 생성 YAML의 충돌을 손으로 풀어야 했고, 다운스트림 tech-log는 이미 제품 커밋 3개에서 gates.json을 고쳤다. 고른 방법: 제품 소유 config/ci/product-gates.json을 둔다. 템플릿은 빈 파일로 싣고 고치지 않는다. 담을 수 있는 것은 둘뿐이다. - deployment: deploy package script와 vars.*·secrets.* 바인딩. 나머지 슬롯(promoted-release download, digest로 확인하는 extract, deploy)은 템플릿이 렌더링하고, 채운 계약을 다시 parse해 슬롯 규칙(앞 커밋)을 그대로 적용한다. secret은 deploy 단계에만 간다. gates.json과 overlay 양쪽에서 슬롯을 채우면 거절한다. - mergeGates: PRODUCT-GATE-NNN id의 package script. 템플릿 job 뒤의 product_merge_gate job이 merge와 같은 조건에서 matrix로 돈다. FE-GATE id·명령·산출물·readiness 공식은 건드리지 못한다. loadCiGateContract와 생성기, check:ci가 두 파일을 함께 읽고, 계약 기준선(contract-baseline.json)은 템플릿 계약만 센다. 없는 script는 거절하고, 제품 gate script는 ungated 검사에서 gated로 센다. 버린 대안: 저장소 변수로 배포 명령만 받기(제품 게이트를 못 풀고 실행할 명령이 저장소 밖에 숨는다), 제품 전용 workflow 파일(Gitea에서 run 사이 산출물 전달이 검증되지 않았다). 위험·한계: 제품 gate는 ci:gate의 로그·증거 산출물과 readiness 공식 밖이다. merge를 막으려면 제품이 그 job을 필수 검사로 지정한다. 생성 workflow는 여전히 커밋되는 파일이라, 템플릿 변경과 같은 줄을 건드리면 재생성이 필요하다. 실제 Gitea runner에서는 돌리지 않았다. 검증: tests/unit/product-ci-overlay.test.ts 11건(빈 overlay, 슬롯 채우기와 기준선 유지, 양쪽 채우기 거절, 없는 script 거절, 제품 job 렌더링과 실행 확인, 스키마 거절 6건). 작업 트리에서 overlay와 script를 채워 generate:ci-workflow → check:ci PASS, CI workflow bytes PASS, 생성 YAML 파싱 확인 후 되돌렸다. 그 상태의 workflow와 gates.json에 템플릿 변경(게이트 이름 2개)을 diff3로 3-way 병합하면 충돌 0이다. ci-workflow-generation 425건, check:ci PASS. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
200 lines
7.3 KiB
TypeScript
200 lines
7.3 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
import { readFileSync } from "node:fs";
|
|
import { readFile } from "node:fs/promises";
|
|
|
|
import {
|
|
evaluatePromotionReadiness,
|
|
PROMOTION_FORMULA,
|
|
type GateResult,
|
|
} from "./lib/promotion-readiness.ts";
|
|
import {
|
|
CANONICAL_GATE_IDS,
|
|
loadCiGateContract,
|
|
indexCiGateContract,
|
|
} from "./contracts/ci-gates.ts";
|
|
import {
|
|
generateCiWorkflow,
|
|
renderCiWorkflow,
|
|
workflowGateExecutionFailures,
|
|
} from "./generate-ci-workflow.ts";
|
|
import { loadProductCiOverlay } from "./contracts/product-ci-overlay.ts";
|
|
import {
|
|
ciContractReportSchema,
|
|
} from "./lib/ci-contract-report.ts";
|
|
import {
|
|
validateInstallScriptPolicy,
|
|
validatePackageScriptGraph,
|
|
} from "./lib/package-script-graph.ts";
|
|
import {
|
|
gatedTestPaths,
|
|
listTestFiles,
|
|
parseUngatedTestExclusions,
|
|
ungatedTestFailures,
|
|
UNGATED_TESTS_PATH,
|
|
} from "./lib/ungated-tests.ts";
|
|
import {
|
|
parseUngatedScriptExclusions,
|
|
ungatedScriptFailures,
|
|
UNGATED_SCRIPTS_PATH,
|
|
} from "./lib/ungated-scripts.ts";
|
|
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
|
|
|
const 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()),
|
|
]);
|
|
const packageScripts = packageDocument.scripts ?? {};
|
|
const failures: string[] = [];
|
|
|
|
if (!/^\d+\.\d+\.\d+$/u.test(nodeVersion)) {
|
|
failures.push(".nvmrc must contain one exact Node.js semantic version");
|
|
}
|
|
for (const script of [
|
|
"build:release-candidate",
|
|
"verify:local-evidence",
|
|
"verify:promotion",
|
|
"generate:ci-workflow",
|
|
"check:ci-workflow",
|
|
"check:ci",
|
|
]) {
|
|
if (!packageScripts[script]) failures.push(`package script missing ${script}`);
|
|
}
|
|
for (const removedScript of [
|
|
"build:release",
|
|
"verify:supply-chain",
|
|
"verify:supply-chain:promotion",
|
|
]) {
|
|
if (packageScripts[removedScript]) failures.push(`legacy package script remains ${removedScript}`);
|
|
}
|
|
if (/\b(?:build|rebuild)(?::[\w-]+)?\b/u.test(packageScripts["verify:promotion"] ?? "")) {
|
|
failures.push("verify:promotion must not build or rebuild candidate bytes");
|
|
}
|
|
failures.push(...validatePackageScriptGraph(packageScripts, "check:ci"));
|
|
failures.push(
|
|
...validateInstallScriptPolicy(
|
|
packageScripts,
|
|
[...new Set(contract.commands.map(({ script }) => script))],
|
|
),
|
|
);
|
|
|
|
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
|
|
try {
|
|
failures.push(
|
|
...ungatedTestFailures({
|
|
testFiles: await listTestFiles(process.cwd()),
|
|
gatedPaths: gatedTestPaths(
|
|
packageScripts,
|
|
[...contract.commands.map(({ script }) => script), ...productGateScripts],
|
|
(file) => readFileSync(file, "utf8"),
|
|
),
|
|
exclusions: parseUngatedTestExclusions(
|
|
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
|
|
),
|
|
}),
|
|
);
|
|
} catch (error) {
|
|
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
|
|
}
|
|
|
|
// 12-04: every verification package script is reached by a gate, or
|
|
// config/ci/ungated-scripts.json says why not.
|
|
try {
|
|
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
|
|
failures.push(
|
|
...ungatedScriptFailures({
|
|
scripts: packageScripts,
|
|
entryScripts,
|
|
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
|
|
exclusions: parseUngatedScriptExclusions(
|
|
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
|
|
),
|
|
}),
|
|
);
|
|
} catch (error) {
|
|
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
|
|
}
|
|
|
|
const immutable = index.gates.get("FE-GATE-015");
|
|
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
|
|
if (JSON.stringify(immutableCommands) !== JSON.stringify(["build:release-candidate", "verify:local-evidence"])) {
|
|
failures.push("FE-GATE-015 must build candidate bytes once and verify local evidence only");
|
|
}
|
|
const architecture = index.gates.get("FE-GATE-010");
|
|
if (!architecture?.commandIds.some((id) => index.commands.get(id)?.script === "check:ci")) {
|
|
failures.push("a blocking gate must execute check:ci");
|
|
}
|
|
if (!architecture?.evidenceArtifactIds.some((id) => index.artifacts.get(id)?.path === "artifacts/quality/ci-contract.json")) {
|
|
failures.push("FE-GATE-010 must publish the typed CI contract report");
|
|
}
|
|
|
|
const expectedGateIds = CANONICAL_GATE_IDS;
|
|
const passingResults: Record<string, GateResult> = Object.fromEntries(
|
|
expectedGateIds.map((gateId) => [gateId, "PASS"]),
|
|
);
|
|
const allPass = evaluatePromotionReadiness(passingResults);
|
|
const negativeFixtures: Array<{
|
|
readiness: keyof typeof PROMOTION_FORMULA;
|
|
failedGate: string;
|
|
passed: boolean;
|
|
}> = [];
|
|
for (const readiness of Object.keys(PROMOTION_FORMULA) as Array<keyof typeof PROMOTION_FORMULA>) {
|
|
const failedGate = PROMOTION_FORMULA[readiness][0];
|
|
if (!failedGate) throw new TypeError(`${readiness} has no configured gates`);
|
|
const evaluated = evaluatePromotionReadiness({ ...passingResults, [failedGate]: "FAIL" });
|
|
const passed = evaluated[readiness] === false;
|
|
negativeFixtures.push({ readiness, failedGate, passed });
|
|
if (!passed) failures.push(`${readiness} did not fail closed`);
|
|
}
|
|
if (!Object.values(allPass).every(Boolean)) failures.push("all-PASS formula did not produce every readiness state");
|
|
|
|
const renderedWorkflow = renderCiWorkflow(contract, productGates);
|
|
const workflowCheck = await generateCiWorkflow({
|
|
root: process.cwd(),
|
|
contract,
|
|
productGates,
|
|
check: true,
|
|
});
|
|
if (!workflowCheck.matches) {
|
|
failures.push(
|
|
`generated workflow drift at byte ${workflowCheck.firstDifferenceByte ?? "missing"}, line ${workflowCheck.firstDifferenceLine ?? "missing"}`,
|
|
);
|
|
}
|
|
let checkedWorkflowBytes = Buffer.from(renderedWorkflow, "utf8");
|
|
try {
|
|
checkedWorkflowBytes = await readFile(workflowCheck.target);
|
|
} catch (error) {
|
|
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
|
|
}
|
|
failures.push(
|
|
...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8"), productGates),
|
|
);
|
|
const report = ciContractReportSchema.parse({
|
|
schemaVersion: 2,
|
|
nodeVersion,
|
|
gateCount: contract.gates.length,
|
|
commandDefinitionCount: contract.commands.length,
|
|
commandReferenceCount: contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0),
|
|
artifactCount: contract.artifacts.length,
|
|
jobCount: contract.jobs.length,
|
|
workflowSha256: createHash("sha256").update(checkedWorkflowBytes).digest("hex"),
|
|
durationStatus: contract.retention.durationStatus,
|
|
negativeFixtures,
|
|
failures,
|
|
passed: failures.length === 0,
|
|
});
|
|
await writeValidatedJsonArtifact({
|
|
path: "artifacts/quality/ci-contract.json",
|
|
schema: ciContractReportSchema,
|
|
value: report,
|
|
});
|
|
if (failures.length > 0) {
|
|
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
|
|
process.exit(1);
|
|
}
|
|
process.stdout.write(`CI contract: ${CANONICAL_GATE_IDS.length} gates, strict v2 graph and generated workflow model PASS\n`);
|