문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid --unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가 아니므로 비특권 user namespace가 있어야 한다. 사전 점검 (scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트 (Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를 낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간 초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도 없고 운영 원장의 일회성 메모에만 있다. 고른 방법: - 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한 번 띄운다. 실패하면 "this host does not allow unprivileged user and network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값, 고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1. 기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다. - 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고 run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이 갈라지면 점검이 다른 것을 시험하게 된다. - 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access· readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다. - config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다. gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의 runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로 그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty 규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가 아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선 재기록 불필요). - 요구 목록 세 곳(docs/operations/ci-quality-gates.md, docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge 게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를 두었다. 버린 대안: - namespace가 없으면 provider 테스트를 skip: 거짓 초록이다. - FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다. - probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope 안과 밖의 결과가 같았다. 직접 실행이 더 단순하다. - workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직 없다. 주석이 지금 가능한 가장 작은 표시다. 위험·한계: - probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른 옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로 실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다. - 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만 한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서 이유와 함께 실패한다. - gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과 제품 overlay는 그대로 통과한다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts - corepack pnpm check:ci, check:types, lint, verify:documentation - desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과 namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지 Refs: 1105/12-01, 1105/11-02
657 lines
26 KiB
TypeScript
657 lines
26 KiB
TypeScript
import { randomUUID } from "node:crypto";
|
|
import { constants, type Stats } from "node:fs";
|
|
import {
|
|
mkdir,
|
|
open,
|
|
readFile,
|
|
rename,
|
|
rm,
|
|
} from "node:fs/promises";
|
|
import { fileURLToPath } from "node:url";
|
|
import path from "node:path";
|
|
|
|
import {
|
|
indexCiGateContract,
|
|
loadCiGateContract,
|
|
resolveCiStepActionUses,
|
|
type CiGateContract,
|
|
type CiWorkflowJob,
|
|
type CiWorkflowStep,
|
|
} from "./contracts/ci-gates.ts";
|
|
import { loadProductCiOverlay, type ProductGate } from "./contracts/product-ci-overlay.ts";
|
|
import {
|
|
assertSafeExistingPublishPath,
|
|
assertSafePublishLeaf,
|
|
ensureSafePublishDirectory,
|
|
} from "./lib/ci-gate-log.ts";
|
|
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;
|
|
}>;
|
|
|
|
export type GenerateCiWorkflowResult = Readonly<{
|
|
target: string;
|
|
written: boolean;
|
|
matches: boolean;
|
|
firstDifferenceByte: number | null;
|
|
firstDifferenceLine: number | null;
|
|
}>;
|
|
|
|
export type CiWorkflowFileSystem = Readonly<{
|
|
mkdir(directory: string): Promise<unknown>;
|
|
readFile(target: string): Promise<Buffer>;
|
|
open(target: string, flags: number, mode: number): Promise<{
|
|
writeFile(content: string, encoding: "utf8"): Promise<unknown>;
|
|
chmod(mode: number): Promise<unknown>;
|
|
sync(): Promise<unknown>;
|
|
close(): Promise<unknown>;
|
|
}>;
|
|
openDirectory(target: string): Promise<{ sync(): Promise<unknown>; close(): Promise<unknown> }>;
|
|
rename(source: string, destination: string): Promise<unknown>;
|
|
rm(target: string): Promise<unknown>;
|
|
}>;
|
|
|
|
const defaultFileSystem: CiWorkflowFileSystem = Object.freeze({
|
|
mkdir: async (directory) => mkdir(directory, { recursive: true }),
|
|
readFile: async (target) => readFile(target),
|
|
open: async (target, flags, mode) => open(target, flags, mode),
|
|
openDirectory: async (target) => open(target, constants.O_RDONLY),
|
|
rename: async (source, destination) => rename(source, destination),
|
|
rm: async (target) => rm(target, { force: true }),
|
|
});
|
|
|
|
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) {
|
|
for (const step of job.steps) {
|
|
if (step.kind === "upload") transfers.set(step.transferId, { name: step.name });
|
|
}
|
|
}
|
|
const lines = [
|
|
"# GENERATED FILE — edit config/ci/gates.json and run `corepack pnpm generate:ci-workflow`.",
|
|
"name: frontend-quality-gates",
|
|
"",
|
|
"on:",
|
|
" push:",
|
|
" branches: [main, develop]",
|
|
' tags: ["v*"]',
|
|
" pull_request:",
|
|
" workflow_dispatch:",
|
|
" inputs:",
|
|
" stage:",
|
|
" description: Highest promotion tier to evaluate",
|
|
" required: true",
|
|
" default: merge",
|
|
" type: choice",
|
|
" options:",
|
|
" - merge",
|
|
" - release",
|
|
" - production",
|
|
" - field",
|
|
" - documentation",
|
|
"",
|
|
"permissions:",
|
|
" contents: read",
|
|
"",
|
|
"env:",
|
|
' CI: "true"',
|
|
' VITE_BUILD_ID: "gitea-${{ gitea.run_id }}-${{ gitea.run_attempt }}"',
|
|
' VITE_COMMIT_SHA: "${{ gitea.sha }}"',
|
|
' RELEASE_ID: "${{ gitea.ref }}-${{ gitea.run_id }}-${{ gitea.run_attempt }}"',
|
|
' CI_RUNNER_IMAGE: "${{ vars.RUNNER_IMAGE_DIGEST }}"',
|
|
"",
|
|
"jobs:",
|
|
];
|
|
for (const [jobIndex, job] of contract.jobs.entries()) {
|
|
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>,
|
|
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
|
|
): string[] {
|
|
const lines = [` ${yamlKey(job.id)}:`, ` name: ${yamlScalar(job.displayName)}`];
|
|
if (job.needs.length === 1) lines.push(` needs: ${yamlKey(job.needs[0]!)}`);
|
|
if (job.needs.length > 1) lines.push(` needs: [${job.needs.map(yamlKey).join(", ")}]`);
|
|
const condition = renderCondition(job.condition);
|
|
if (condition) lines.push(` if: ${condition}`);
|
|
lines.push(
|
|
...renderHostRequirements(job, index),
|
|
" runs-on: ubuntu-latest",
|
|
` timeout-minutes: ${job.timeoutMinutes}`,
|
|
);
|
|
if (job.kind === "immutable") {
|
|
const archive = job.steps.find((step) => step.kind === "archive-candidate");
|
|
if (!archive || archive.kind !== "archive-candidate") throw new TypeError("immutable job lacks archive step");
|
|
lines.push(
|
|
" outputs:",
|
|
` ${archive.distOutputName}: \${{ steps.${archive.stepId}.outputs.${archive.distOutputName} }}`,
|
|
` ${archive.archiveOutputName}: \${{ steps.${archive.stepId}.outputs.${archive.archiveOutputName} }}`,
|
|
);
|
|
}
|
|
if (job.kind === "provider") {
|
|
const supervisor = job.steps.find((step) => step.kind === "run-provider");
|
|
if (!supervisor || supervisor.kind !== "run-provider") {
|
|
throw new TypeError("provider job lacks supervisor step");
|
|
}
|
|
lines.push(
|
|
" outputs:",
|
|
` invocation_nonce: \${{ steps.${supervisor.stepId}.outputs.invocation_nonce }}`,
|
|
);
|
|
}
|
|
if (job.kind === "deployment") {
|
|
lines.push(" outputs:", " deployed: ${{ steps.deploy.outputs.deployed }}");
|
|
}
|
|
const jobEnvironment = job.environment.filter((binding) => !isStepScopedSecret(job, binding));
|
|
if (jobEnvironment.length > 0) {
|
|
lines.push(" env:");
|
|
for (const binding of jobEnvironment) {
|
|
lines.push(` ${binding.name}: ${yamlScalar(binding.value)}`);
|
|
}
|
|
}
|
|
if (job.kind === "gate-matrix") {
|
|
lines.push(" strategy:", " fail-fast: false", " matrix:", " include:");
|
|
const includesBrowser = job.steps.some(({ kind }) => kind === "browser-install");
|
|
for (const gateId of job.gateIds) {
|
|
const gate = index.gates.get(gateId);
|
|
if (!gate) throw new TypeError(`unknown gate while rendering: ${gateId}`);
|
|
const browser = job.browserGateIds.includes(gateId);
|
|
lines.push(
|
|
` - { gate: ${gateId}, name: ${gate.name}${includesBrowser ? `, browser: ${browser ? "true" : "false"}` : ""} }`,
|
|
);
|
|
}
|
|
}
|
|
lines.push(" steps:");
|
|
for (const step of job.steps) lines.push(...renderStep(job, step, transfers));
|
|
return lines;
|
|
}
|
|
|
|
/**
|
|
* 1105/12-01. A gate's host requirements (`hostRequirements` in
|
|
* config/ci/gates.json) sit as comments beside the runner label of the job
|
|
* that runs the gate, where whoever picks the runner reads them. FE-GATE-013
|
|
* needs unprivileged user namespaces, and that was written nowhere a runner
|
|
* is chosen. The contract keeps line breaks out of each requirement.
|
|
*/
|
|
function renderHostRequirements(
|
|
job: CiWorkflowJob,
|
|
index: ReturnType<typeof indexCiGateContract>,
|
|
): string[] {
|
|
return job.gateIds.flatMap((gateId) =>
|
|
(index.gates.get(gateId)?.hostRequirements ?? []).map(
|
|
(requirement) => ` # ${gateId} runner requirement: ${requirement}`,
|
|
),
|
|
);
|
|
}
|
|
|
|
function renderStep(
|
|
job: CiWorkflowJob,
|
|
step: CiWorkflowStep,
|
|
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
|
|
): string[] {
|
|
switch (step.kind) {
|
|
case "checkout":
|
|
return [
|
|
` - uses: ${requiredStepActionUses(step.kind)}`,
|
|
" with:",
|
|
" persist-credentials: false",
|
|
];
|
|
case "setup-node":
|
|
return [
|
|
` - uses: ${requiredStepActionUses(step.kind)}`,
|
|
" with:",
|
|
" node-version-file: .nvmrc",
|
|
];
|
|
case "frozen-install":
|
|
return [
|
|
" - name: Frozen install",
|
|
" run: |",
|
|
" corepack enable",
|
|
" corepack pnpm install --frozen-lockfile --ignore-scripts",
|
|
];
|
|
case "browser-install":
|
|
return [
|
|
" - name: Install Playwright browsers",
|
|
...(job.kind === "gate-matrix" ? [" if: ${{ matrix.browser }}"] : []),
|
|
" run: |",
|
|
" corepack pnpm exec playwright install --with-deps chromium firefox webkit",
|
|
// 1103/11-02. The visual goldens' faces (tests/visual/fonts.conf) are
|
|
// not among Playwright's dependencies. `--with-deps` has refreshed the
|
|
// package lists; sudo only where the runner is not root.
|
|
` $(command -v sudo || true) ${VISUAL_TEST_FONT_INSTALL_ARGUMENTS}`,
|
|
];
|
|
case "run-gate": {
|
|
if (job.kind === "gate-matrix") {
|
|
return [" - name: Run blocking gate", " run: corepack pnpm ci:gate -- ${{ matrix.gate }}"];
|
|
}
|
|
if (job.gateIds.length === 0) throw new TypeError(`run-gate step lacks ownership: ${job.id}`);
|
|
// 12-02: every gate the job owns runs, in order. Rendering only the first
|
|
// left FE-GATE-027 (release admission) out of the workflow.
|
|
return job.gateIds.flatMap((gateId) => [
|
|
` - name: ${runGateStepName(job.id, gateId)}`,
|
|
` run: corepack pnpm ci:gate -- ${gateId}`,
|
|
]);
|
|
}
|
|
case "archive-candidate": {
|
|
const archive = shellDoubleQuoted(step.archivePath);
|
|
const lines = [
|
|
" - name: Archive and validate the exact candidate file set",
|
|
` id: ${yamlKey(step.stepId)}`,
|
|
" run: |",
|
|
" mkdir -p .release",
|
|
` tar --sort=name --mtime="@0" --owner=0 --group=0 --numeric-owner -czf ${archive} \\`,
|
|
];
|
|
step.members.forEach((member, memberIndex) => {
|
|
lines.push(` ${shellWord(member)}${memberIndex === step.members.length - 1 ? "" : " \\"}`);
|
|
});
|
|
lines.push(
|
|
` node scripts/verify-ci-candidate-archive.ts --archive ${archive} --github-output "$GITHUB_OUTPUT"`,
|
|
);
|
|
return lines;
|
|
}
|
|
case "download":
|
|
return [
|
|
` - name: Download ${humanize(step.transferId)}`,
|
|
` uses: ${requiredStepActionUses(step.kind)}`,
|
|
" with:",
|
|
` name: ${yamlScalar(requiredTransferName(transfers, step.transferId))}`,
|
|
` path: ${yamlScalar(step.path)}`,
|
|
];
|
|
case "extract":
|
|
return [
|
|
" - name: Verify and extract the candidate through one inode-bound operation",
|
|
` run: node scripts/verify-ci-candidate-archive.ts --archive ${shellDoubleQuoted(step.archivePath)} --extract-to ${shellDoubleQuoted(step.targetRoot)}`,
|
|
];
|
|
case "run-provider": {
|
|
return [
|
|
` - name: Run and validate external ${step.provider} provider in one trusted supervisor`,
|
|
` id: ${yamlKey(step.stepId)}`,
|
|
` run: node scripts/run-and-validate-provider.ts --kind ${step.provider}`,
|
|
];
|
|
}
|
|
case "validate-provider-evidence":
|
|
return [
|
|
` - name: Confirm sealed ${step.provider} provider evidence`,
|
|
' run: test -s "$VALIDATED_PROVIDER_REPORT_PATH"',
|
|
];
|
|
case "verify-promotion":
|
|
return [
|
|
" - name: Finalize verified promotion from inode-bound captured inputs",
|
|
` id: ${yamlKey(step.stepId)}`,
|
|
" run: node scripts/stage-verified-promotion.ts",
|
|
];
|
|
case "cleanup-promotion":
|
|
return [
|
|
" - name: Always remove private promotion staging",
|
|
" if: always()",
|
|
" env:",
|
|
` PROMOTION_STAGING_ROOT: \${{ steps.${step.finalizerStepId}.outputs.staging_root }}`,
|
|
` PROMOTION_CLEANUP_TOKEN: \${{ steps.${step.finalizerStepId}.outputs.cleanup_token }}`,
|
|
` PROMOTION_RUNNER_TEMP_DEV: \${{ steps.${step.finalizerStepId}.outputs.runner_temp_dev }}`,
|
|
` PROMOTION_RUNNER_TEMP_INO: \${{ steps.${step.finalizerStepId}.outputs.runner_temp_ino }}`,
|
|
` PROMOTION_STAGING_DEV: \${{ steps.${step.finalizerStepId}.outputs.staging_dev }}`,
|
|
` PROMOTION_STAGING_INO: \${{ steps.${step.finalizerStepId}.outputs.staging_ino }}`,
|
|
" run: |",
|
|
' if [ -n "$PROMOTION_STAGING_ROOT" ] && [ -n "$PROMOTION_CLEANUP_TOKEN" ] && [ -n "$PROMOTION_RUNNER_TEMP_DEV" ] && [ -n "$PROMOTION_RUNNER_TEMP_INO" ] && [ -n "$PROMOTION_STAGING_DEV" ] && [ -n "$PROMOTION_STAGING_INO" ]; then',
|
|
" node scripts/cleanup-verified-promotion.ts",
|
|
" fi",
|
|
];
|
|
// 1101/13-01. `run` fails on the first failing command, so deployed=true
|
|
// is written only after the project's script succeeded.
|
|
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}`,
|
|
' echo "deployed=true" >> "$GITHUB_OUTPUT"',
|
|
]
|
|
: [
|
|
" - name: Deployment slot is empty",
|
|
" id: deploy",
|
|
' run: echo "deployed=false" >> "$GITHUB_OUTPUT"',
|
|
];
|
|
}
|
|
case "upload": {
|
|
const lines = [
|
|
` - name: Upload ${humanize(step.transferId)}`,
|
|
...(step.always ? [" if: always()"] : []),
|
|
` uses: ${requiredStepActionUses(step.kind)}`,
|
|
" with:",
|
|
` name: ${yamlScalar(step.name)}`,
|
|
];
|
|
if (step.paths.length === 1) lines.push(` path: ${yamlScalar(step.paths[0]!)}`);
|
|
else {
|
|
lines.push(" path: |");
|
|
for (const target of step.paths) lines.push(` ${target}`);
|
|
}
|
|
lines.push(" if-no-files-found: error");
|
|
return lines;
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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}`);
|
|
return uses;
|
|
}
|
|
|
|
function renderCondition(condition: CiWorkflowJob["condition"]): string | null {
|
|
const expressions: Record<CiWorkflowJob["condition"], string | null> = {
|
|
always: null,
|
|
"needs-success": null,
|
|
merge: "${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}",
|
|
release: "${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}",
|
|
production: "${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}",
|
|
field: "${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'field' }}",
|
|
documentation: "${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'documentation' }}",
|
|
};
|
|
return expressions[condition];
|
|
}
|
|
|
|
function requiredTransferName(
|
|
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
|
|
transferId: string,
|
|
): string {
|
|
const transfer = transfers.get(transferId);
|
|
if (!transfer) throw new TypeError(`download transfer has no typed producer: ${transferId}`);
|
|
return transfer.name;
|
|
}
|
|
|
|
function yamlKey(value: string): string {
|
|
if (!/^[A-Za-z0-9_-]+$/u.test(value)) throw new TypeError(`unsafe YAML key: ${value}`);
|
|
return value;
|
|
}
|
|
|
|
function yamlScalar(value: string): string {
|
|
if (/^[A-Za-z0-9._/-]+$/u.test(value)) return value;
|
|
return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n")}"`;
|
|
}
|
|
|
|
function shellWord(value: string): string {
|
|
if (!/^[A-Za-z0-9._/-]+$/u.test(value)) throw new TypeError(`unsafe shell word: ${value}`);
|
|
return value;
|
|
}
|
|
|
|
function shellDoubleQuoted(value: string): string {
|
|
const expressions: string[] = [];
|
|
const withoutExpressions = value.replace(/\$\{\{ [A-Za-z0-9_.-]+ \}\}/gu, (expression) => {
|
|
expressions.push(expression);
|
|
return `__CI_EXPRESSION_${expressions.length - 1}__`;
|
|
});
|
|
if (withoutExpressions.includes("$")) {
|
|
throw new TypeError(`unapproved shell interpolation in workflow value: ${value}`);
|
|
}
|
|
let escaped = withoutExpressions
|
|
.replaceAll("\\", "\\\\")
|
|
.replaceAll('"', '\\"')
|
|
.replaceAll("`", "\\`");
|
|
expressions.forEach((expression, index) => {
|
|
escaped = escaped.replace(`__CI_EXPRESSION_${index}__`, expression);
|
|
});
|
|
return `"${escaped}"`;
|
|
}
|
|
|
|
function runGateStepName(jobId: string, gateId: string): string {
|
|
if (gateId === "FE-GATE-015") return "Build candidate once and verify local evidence";
|
|
if (gateId === "FE-GATE-027") return "Admit the candidate to the declared release target";
|
|
return jobId === "documentation_gate" ? "Run documentation gate" : "Run blocking gate";
|
|
}
|
|
|
|
/**
|
|
* 12-02 / D-12. Every contract gate must be executed by the workflow text: a
|
|
* literal `ci:gate -- <id>` run line, or a matrix entry of a job whose run step
|
|
* is `ci:gate -- ${{ matrix.gate }}`. Owning a gate in the contract is not
|
|
* enough; the generator once dropped all but the first.
|
|
*/
|
|
export function workflowGateExecutionFailures(
|
|
contract: CiGateContract,
|
|
workflow: string,
|
|
productGates: readonly ProductGate[] = [],
|
|
): string[] {
|
|
const executed = new Set<string>();
|
|
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]!);
|
|
}
|
|
if (/^ +run: corepack pnpm ci:gate -- \$\{\{ matrix\.gate \}\}$/mu.test(job)) {
|
|
for (const match of job.matchAll(/^ +- \{ gate: (FE-GATE-\d{3}),/gmu)) {
|
|
executed.add(match[1]!);
|
|
}
|
|
}
|
|
}
|
|
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 {
|
|
return value.replaceAll("-", " ");
|
|
}
|
|
|
|
export function createCiWorkflowGenerator(
|
|
dependencies: Readonly<{
|
|
fileSystem?: CiWorkflowFileSystem;
|
|
createNonce?: () => string;
|
|
}> = {},
|
|
) {
|
|
const fileSystem = dependencies.fileSystem ?? defaultFileSystem;
|
|
const createNonce = dependencies.createNonce ?? randomUUID;
|
|
return async function generate(options: GenerateCiWorkflowOptions): Promise<GenerateCiWorkflowResult> {
|
|
const root = path.resolve(options.root);
|
|
const contract = options.contract ?? (await loadCiGateContract(root));
|
|
const target = path.resolve(root, contract.providerAdapter);
|
|
if (path.relative(root, target).startsWith("..") || path.relative(root, target) === "") {
|
|
throw new TypeError(`workflow target escapes repository root: ${contract.providerAdapter}`);
|
|
}
|
|
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
|
|
? await assertSafeExistingPublishPath(root, target)
|
|
: true;
|
|
if (existingPathIsSafe) {
|
|
try {
|
|
actual = await fileSystem.readFile(target);
|
|
} catch (error) {
|
|
if (!hasErrorCode(error, "ENOENT")) throw error;
|
|
}
|
|
}
|
|
const difference = firstDifference(expected, actual);
|
|
if (options.check || difference === null) {
|
|
return Object.freeze({
|
|
target,
|
|
written: false,
|
|
matches: difference === null,
|
|
firstDifferenceByte: difference?.byte ?? null,
|
|
firstDifferenceLine: difference?.line ?? null,
|
|
});
|
|
}
|
|
|
|
let parentIdentity: Stats | undefined;
|
|
if (fileSystem === defaultFileSystem) {
|
|
parentIdentity = await ensureSafePublishDirectory(root, path.dirname(target));
|
|
await assertSafePublishLeaf(target, contract.providerAdapter);
|
|
} else {
|
|
await fileSystem.mkdir(path.dirname(target));
|
|
}
|
|
const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${createNonce()}.tmp`);
|
|
let ownsTemporary = false;
|
|
try {
|
|
const handle = await fileSystem.open(
|
|
temporary,
|
|
constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
|
|
0o644,
|
|
);
|
|
ownsTemporary = true;
|
|
let failure: unknown;
|
|
try {
|
|
await handle.writeFile(expected.toString("utf8"), "utf8");
|
|
await handle.chmod(0o644);
|
|
await handle.sync();
|
|
} catch (error) {
|
|
failure = error;
|
|
}
|
|
try {
|
|
await handle.close();
|
|
} catch (error) {
|
|
failure ??= error;
|
|
}
|
|
if (failure) throw failure;
|
|
if (fileSystem === defaultFileSystem && parentIdentity) {
|
|
const current = await ensureSafePublishDirectory(root, path.dirname(target));
|
|
if (
|
|
parentIdentity.dev <= 0 ||
|
|
parentIdentity.ino <= 0 ||
|
|
current.dev !== parentIdentity.dev ||
|
|
current.ino !== parentIdentity.ino
|
|
) {
|
|
throw new TypeError("CI workflow parent directory identity changed");
|
|
}
|
|
await assertSafePublishLeaf(target, contract.providerAdapter);
|
|
}
|
|
await fileSystem.rename(temporary, target);
|
|
ownsTemporary = false;
|
|
const directory = await fileSystem.openDirectory(path.dirname(target));
|
|
try {
|
|
try {
|
|
await directory.sync();
|
|
} catch (error) {
|
|
if (!hasErrorCode(error, "EINVAL") && !hasErrorCode(error, "ENOTSUP")) throw error;
|
|
}
|
|
} finally {
|
|
await directory.close();
|
|
}
|
|
} catch (error) {
|
|
if (ownsTemporary) {
|
|
try {
|
|
await fileSystem.rm(temporary);
|
|
} catch {
|
|
// The owned sibling temp is the only cleanup target; preserve the publish failure.
|
|
}
|
|
}
|
|
throw error;
|
|
}
|
|
return Object.freeze({ target, written: true, matches: true, firstDifferenceByte: null, firstDifferenceLine: null });
|
|
};
|
|
}
|
|
|
|
export const generateCiWorkflow = createCiWorkflowGenerator();
|
|
|
|
function firstDifference(expected: Buffer, actual: Buffer | null): { byte: number; line: number } | null {
|
|
if (actual?.equals(expected)) return null;
|
|
const limit = Math.min(expected.byteLength, actual?.byteLength ?? 0);
|
|
let byte = 0;
|
|
while (byte < limit && expected[byte] === actual?.[byte]) byte += 1;
|
|
const line = expected.subarray(0, byte).toString("utf8").split("\n").length;
|
|
return { byte, line };
|
|
}
|
|
|
|
function hasErrorCode(error: unknown, code: string): boolean {
|
|
return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
|
|
}
|
|
|
|
const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
|
if (isCli) {
|
|
const check = process.argv.includes("--check");
|
|
try {
|
|
const result = await generateCiWorkflow({ root: process.cwd(), check });
|
|
if (!result.matches) {
|
|
process.stderr.write(
|
|
`CI workflow drift: ${result.target} differs at byte ${result.firstDifferenceByte ?? 0}, line ${result.firstDifferenceLine ?? 1}\n`,
|
|
);
|
|
process.exitCode = 1;
|
|
} else {
|
|
process.stdout.write(check ? "CI workflow bytes: PASS\n" : "CI workflow generated atomically\n");
|
|
}
|
|
} catch (error) {
|
|
process.stderr.write(`CI workflow generation failed: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
process.exitCode = 1;
|
|
}
|
|
}
|