Files
clean-architecture-frontend…/tests/unit/product-ci-overlay.test.ts
T
donghyeon.kang f6b2b96c53 ci(gates): 검사기 자기 시험과 gating 검사를 main 단계로 내리고 계약 기준선을 지운다
merge 단계(=PR)가 변경이 아니라 검사기 자신을 시험하는 명령까지 돈다.
검사기가 나쁜 입력을 거부하는지 보는 `*:fixture` 명령 15개, 모든 시험
파일과 검증 script가 게이트에 걸렸는지 보는 ungated 검사, CI 계약의
개수·해시 기준선(`config/ci/contract-baseline.json`)이다. 기준선은 게이트
명령 하나를 더하거나 빼도 OWNER·REASON을 붙여 다시 받아야 했다.
소유자 결정(2026-09-16)은 개수·배선 검사를 main 단계에 두는 것이다.

고른 방법(design-docs repo-structure/03-ci.md 7.3절 F2, README.md 3.3절,
소유자 승인 2026-11-07):
- 새 게이트 FE-GATE-029 `checker-self-tests`, 새 단계 `main`
  (`MAIN_READY`, 승격을 막지 않는다), 새 job `main_gate`. 브랜치 push와
  `workflow_dispatch`(stage=main)에서만 돈다. PR과 태그에서는 돌지 않는다.
- FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거
  산출물 10개를 FE-GATE-029로 옮긴다.
- `check:ci`의 ungated 검사를 `scripts/check-ci-gating.ts`
  (`check:ci:gating`)로 떼어 FE-GATE-029에 둔다. `check:ci`는 계약·
  workflow 검사만 PR에서 돈다.
- 기준선 파일, `update:ci-contract-baseline`, 그 검사를 지운다(소유자
  결정). 계약 모양은 ci-gates.ts의 의미 검사가 지킨다. 개수를 고정하던
  단위 시험의 개수 단언도 뺐다.

남긴 것: 음성 타입 fixture(`check:types:fixtures`, FE-GATE-003)는
이름이 `*:fixture`여도 merge에 둔다. 검사기가 아니라 src의 포트·계약
타입을 시험한다. `TelemetryPort.emit`을 넓히는 변경을 PR에서 막는다(정리
3단계 9.3절 변이로 확인). merge 단계 명령 참조 64 → 49.

위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다. 그
대가로 PR이 검사기 자기 시험을 기다리지 않는다(설계 7.5절의 같은 교환).
FE-GATE-029의 명령이 앞 게이트 산출물 없이 새 checkout에서 도는지는
desktop에서 따로 확인했다(PR 본문).

검증(desktop): check:ci, check:ci:gating, check:types, CI 시험 통과.
merge 단계·FE-GATE-029 실행 결과는 PR 본문에 적는다.

Refs: design-docs repo-structure/03-ci.md 7.3·7.4절, README.md 3.3절
2026-11-08 21:56:37 +09:00

221 lines
9.5 KiB
TypeScript

import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts";
import {
loadProductCiOverlay,
parseProductCiOverlay,
PRODUCT_CI_OVERLAY_PATH,
} from "../../scripts/contracts/product-ci-overlay.ts";
import { renderCiWorkflow, workflowGateExecutionFailures } from "../../scripts/generate-ci-workflow.ts";
/**
* 1103/12-07. A product attached its deployment and its own merge checks by
* editing the template-owned config/ci/gates.json (3,000 lines) and the
* generated workflow, and met them again in every template sync. The product
* now writes them in config/ci/product-gates.json, which the template ships
* empty and never changes.
*/
const roots: string[] = [];
afterEach(async () => {
await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
});
async function productRoot(
overlay: unknown,
extraScripts: Readonly<Record<string, string>> = {},
): Promise<string> {
const root = await mkdtemp(path.join(tmpdir(), "product-ci-overlay-"));
roots.push(root);
await mkdir(path.join(root, "config/ci"), { recursive: true });
await writeFile(path.join(root, "config/ci/gates.json"), await readFile("config/ci/gates.json"));
const packageDocument = JSON.parse(await readFile("package.json", "utf8")) as {
scripts: Record<string, string>;
};
Object.assign(packageDocument.scripts, extraScripts);
await writeFile(path.join(root, "package.json"), JSON.stringify(packageDocument, null, 2));
await writeFile(path.join(root, PRODUCT_CI_OVERLAY_PATH), JSON.stringify(overlay, null, 2));
return root;
}
const DEPLOYMENT = {
script: "deploy:desktop",
environment: [
{ name: "DEPLOY_HOST", value: "${{ vars.DEPLOY_HOST }}" },
{ name: "DEPLOY_SSH_KEY", value: "${{ secrets.DEPLOY_SSH_KEY }}" },
],
};
const DEPLOY_SCRIPTS = { "deploy:desktop": "node scripts/deploy-desktop.ts" };
const GATE = { id: "PRODUCT-GATE-001", name: "backend-contract", script: "check:backend-contract" };
const GATE_SCRIPTS = { "check:backend-contract": "node scripts/check-backend-contract.ts" };
const RELEASE_HELD_BY_TEMPLATE = " needs: [merge_static, merge_test, merge_browser]\n";
const RELEASE_HELD_BY_PRODUCT = " needs: [merge_static, merge_test, merge_browser, product_merge_gate]\n";
describe("product CI overlay (1103/12-07)", () => {
it("ships empty, so the template's own workflow is unchanged", async () => {
expect(await loadProductCiOverlay(process.cwd())).toEqual({
schemaVersion: 1,
deployment: null,
mergeGates: [],
});
});
it("fills the deployment slot with the promoted candidate and the product's script", async () => {
const root = await productRoot(
{ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [] },
DEPLOY_SCRIPTS,
);
const contract = await loadCiGateContract(root);
const slot = contract.jobs.find(({ id }) => id === "deployment");
expect(slot?.steps.map(({ kind }) => kind)).toEqual([
"checkout",
"setup-node",
"frozen-install",
"download",
"extract",
"deploy",
]);
expect(slot?.steps).toContainEqual(expect.objectContaining({ kind: "download", transferId: "promoted-release" }));
expect(slot?.steps.at(-1)).toEqual({ kind: "deploy", script: "deploy:desktop" });
expect(slot?.environment).toEqual([
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
...DEPLOYMENT.environment,
]);
const workflow = renderCiWorkflow(contract);
const job = workflow.slice(workflow.indexOf(" deployment:\n"), workflow.indexOf(" production_gate:\n"));
expect(job).toContain("corepack pnpm deploy:desktop");
expect(job.match(/secrets\./gu)).toHaveLength(1);
});
it("refuses a slot filled in the template contract and in the overlay", async () => {
const root = await productRoot(
{ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [] },
DEPLOY_SCRIPTS,
);
const gatesPath = path.join(root, "config/ci/gates.json");
const gates = JSON.parse(await readFile(gatesPath, "utf8")) as {
jobs: { id: string; steps: unknown[]; environment: unknown[] }[];
};
const slot = gates.jobs.find(({ id }) => id === "deployment")!;
slot.environment = [
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
];
slot.steps = [
{ kind: "download", transferId: "promoted-release", path: ".release/promoted" },
{
kind: "extract",
archivePath: ".release/promoted/release-candidate.tar.gz",
targetRoot: ".release/promoted-release",
},
{ kind: "deploy", script: "deploy:desktop" },
];
await writeFile(gatesPath, JSON.stringify(gates));
await expect(loadCiGateContract(root)).rejects.toThrow(/product-gates\.json/u);
});
it("refuses an overlay script that package.json does not define", async () => {
const root = await productRoot({ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [GATE] });
await expect(loadCiGateContract(root)).rejects.toThrow(
/missing package scripts: deploy:desktop, check:backend-contract/u,
);
});
it("runs product merge gates in a job of their own, apart from the template gates", async () => {
const root = await productRoot(
{ schemaVersion: 1, deployment: null, mergeGates: [GATE] },
GATE_SCRIPTS,
);
const contract = await loadCiGateContract(root);
const { mergeGates } = await loadProductCiOverlay(root);
const workflow = renderCiWorkflow(contract, mergeGates);
const job = workflow.slice(workflow.indexOf(" product_merge_gate:\n"));
expect(job).toContain(' - { gate: PRODUCT-GATE-001, name: backend-contract, script: "check:backend-contract" }');
expect(job).toContain(" run: corepack pnpm ${{ matrix.script }}");
expect(job).toContain(
` if: ${"${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}"}`,
);
expect(workflowGateExecutionFailures(contract, workflow, mergeGates)).toEqual([]);
// The template part of the workflow is the same bytes with or without the
// overlay, except that the release stage waits for the product job (1105/13-02).
expect(
workflow.replace(RELEASE_HELD_BY_PRODUCT, RELEASE_HELD_BY_TEMPLATE).startsWith(renderCiWorkflow(contract).trimEnd()),
).toBe(true);
expect(workflowGateExecutionFailures(contract, renderCiWorkflow(contract), mergeGates)).toEqual([
"product gate is not executed by the product_merge_gate job: PRODUCT-GATE-001",
"product gates do not hold the release stage: release_gate does not need product_merge_gate",
]);
});
// 1105/13-02. A failing product gate stopped only a PR merge (as a required
// check): the same run went on to release, promote and deploy, and the fixed
// job graph left the product no way to link them.
it("holds the release stage until the product merge gates pass", async () => {
const root = await productRoot(
{ schemaVersion: 1, deployment: DEPLOYMENT, mergeGates: [GATE] },
{ ...DEPLOY_SCRIPTS, ...GATE_SCRIPTS },
);
const contract = await loadCiGateContract(root);
const { mergeGates } = await loadProductCiOverlay(root);
const releaseJob = (workflow: string) =>
workflow.slice(workflow.indexOf(" release_gate:\n"), workflow.indexOf(" immutable_build:\n"));
const workflow = renderCiWorkflow(contract, mergeGates);
expect(releaseJob(workflow)).toContain(RELEASE_HELD_BY_PRODUCT);
// immutable_build, and through it every later release-stage job
// (deployment included), needs release_gate.
expect(contract.jobs.find(({ id }) => id === "immutable_build")?.needs).toEqual(["release_gate"]);
// Without product gates the template's own graph is rendered.
expect(releaseJob(renderCiWorkflow(contract))).toContain(RELEASE_HELD_BY_TEMPLATE);
// check:ci refuses a workflow that runs the product gates without the link.
expect(
workflowGateExecutionFailures(
contract,
workflow.replace(RELEASE_HELD_BY_PRODUCT, RELEASE_HELD_BY_TEMPLATE),
mergeGates,
),
).toEqual(["product gates do not hold the release stage: release_gate does not need product_merge_gate"]);
});
it.each([
["a template gate id", { mergeGates: [{ ...GATE, id: "FE-GATE-030" }] }, /PRODUCT-GATE-NNN/u],
["a duplicate gate id", { mergeGates: [GATE, { ...GATE, name: "other" }] }, /duplicate product gate/u],
[
"a binding to another job's output",
{
deployment: {
...DEPLOYMENT,
environment: [{ name: "NONCE", value: "${{ needs.promotion.outputs.staging_root }}" }],
},
},
/vars\.\* or secrets\.\*/u,
],
[
"the candidate digest the template binds",
{
deployment: {
...DEPLOYMENT,
environment: [{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ vars.DIGEST }}" }],
},
},
/CANDIDATE_ARCHIVE_SHA256/u,
],
["a script that is not a plain name", { deployment: { ...DEPLOYMENT, script: "deploy; rm -rf ." } }, /script/u],
["an unknown field", { gates: [] }, /unrecognized|Unrecognized/u],
] as const)("refuses %s", (_name, change, diagnostic) => {
expect(() =>
parseProductCiOverlay({ schemaVersion: 1, deployment: null, mergeGates: [], ...change }),
).toThrow(diagnostic);
});
});