Files
clean-architecture-frontend…/scripts/lib/feature-scaffold-drill.ts
T
donghyeon.kang 0739f26b80 ci(gates): merge 단계 job 14개를 셋으로 합친다
merge 단계가 게이트마다 job 하나(행렬 14개)라서 PR마다 checkout,
setup-node, `pnpm install`을 14번 하고 브라우저 설치를 2번 한다. Gitea
runner는 소유자 기계 한 대다. 사례(Vite 등)는 설치를 job당 한 번으로
묶는다(design-docs repo-structure/03-ci.md 3.5절).

고른 방법(03-ci.md 7.3절 F1, 소유자 승인 2026-11-07):
- job 종류 `gate-sequence`를 더한다. job 하나가 게이트 여럿을 차례로
  돈다. 게이트마다 `FE-GATE-NNN / <이름>` 단계이고 `if: !cancelled()`라
  앞 게이트가 실패해도 다음 게이트가 돈다(행렬의 fail-fast: false와 같다).
- merge job 셋: `merge_static`(001·002·003·010·011·012, 소스를 읽고
  빌드하는 검사), `merge_test`(004·005·006·007·013·020, 시험),
  `merge_browser`(008·009, 브라우저 설치). release 단계는 셋을 모두
  기다린다. 게이트 id·명령·증거·승격 공식은 그대로다.
- 증거 업로드는 job마다 하나(`merge-static-<run>` 등)다.

버린 것: 행렬을 두고 `pnpm install`만 캐시하는 방법. runner 한 대에서는
job 수만큼 checkout과 준비가 남는다. 게이트를 job 하나에 모두 넣는
방법은 브라우저 설치를 모든 게이트가 기다린다.

위험: 한 job 안의 게이트가 같은 작업 공간을 쓴다. 앞 게이트의 산출물이
뒤 게이트에 남는다. desktop의 merge 단계 실행(게이트를 한 checkout에서
차례로 도는 것)과 같은 조건이라 그 결과로 확인했다. 실제 Gitea runner의
`!cancelled()` 해석은 Actions를 켠 뒤 확인한다.

검증(desktop): check:ci, check:types, CI 시험 4파일 통과. 합치기
전후 merge 단계 게이트별 결과 비교는 PR 본문에 적는다.

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

144 lines
6.2 KiB
TypeScript

import { spawnSync } from "node:child_process";
import type { CiGateContract } from "../contracts/ci-gates.ts";
import { classifyGateStepResult, type GateStepExpectation } from "./ci-step-result.ts";
import { FIXTURE_PNPM_ENVIRONMENT } from "./fixture-node-modules.ts";
import type { RemovalCheck } from "./removal-fixture.ts";
/**
* 1103/12-02. test:feature-scaffold proves that a feature from
* `create:feature` passes the merge gates. It ran a hand-kept list of 15
* commands while the merge stage has 88, so a template change that broke a
* generated feature in any other merge command passed FE-GATE-020.
*
* The drill now runs the merge stage of the copy's config/ci/gates.json, in
* stage order, each command once. A command added to the merge stage runs here
* unless this list names it, with the reason it cannot run in the drill.
*/
const BROWSER =
"needs Playwright browsers. FE-GATE-020 runs in a merge job without them " +
"(merge_test installs none). The generated routes in the browser " +
"gates are reviewed as 1103/12-01 and 12-03.";
const DRILL =
"a removal drill copies the repository again. The drill runs the generated " +
"feature's own removal instead (feature-removal).";
export const SCAFFOLD_DRILL_EXCLUDED_SCRIPTS: Readonly<Record<string, string>> = Object.freeze({
"verify:lockfile":
"runs pnpm install, which writes into the node_modules the copy links from " +
"the repository (scripts/lib/fixture-node-modules.ts).",
"test:e2e": BROWSER,
"test:browser-capabilities": BROWSER,
"verify:browser-capability-evidence": `reads the test:browser-capabilities results; ${BROWSER}`,
"test:storybook": BROWSER,
"test:visual": BROWSER,
"check:test-evidence:browser": `reads the browser gates' results; ${BROWSER}`,
"test:a11y": BROWSER,
"test:system":
"needs the CI runner's bubblewrap, systemd and cgroup v2 " +
"(scripts/check-system-test-prerequisites.ts). It tests the provider " +
"sandbox, which a feature does not reach.",
"test:sample-removal": DRILL,
"test:feature-scaffold": "is this drill.",
"test:optional-recipe-removal": DRILL,
"test:browser-file-storage-removal": DRILL,
"test:realtime-removal": DRILL,
});
export type ScaffoldDrillCommand = Readonly<{
/** `<gate>:<command id>`, the check's name in the drill report. */
name: string;
script: string;
args: readonly string[];
expectation: GateStepExpectation;
}>;
type ContractShape = Pick<CiGateContract, "commands" | "gates" | "stages">;
export function scaffoldDrillCommands(
contract: ContractShape,
excluded: Readonly<Record<string, string>> = SCAFFOLD_DRILL_EXCLUDED_SCRIPTS,
): readonly ScaffoldDrillCommand[] {
const merge = contract.stages.find(({ id }) => id === "merge");
if (!merge) throw new TypeError("the CI contract has no merge stage");
const commands = new Map(contract.commands.map((command) => [command.id, command]));
const mergeScripts = new Set<string>();
const seen = new Set<string>();
const selected: ScaffoldDrillCommand[] = [];
for (const gateId of merge.gateIds) {
const gate = contract.gates.find(({ id }) => id === gateId);
if (!gate) throw new TypeError(`the merge stage names an undefined gate: ${gateId}`);
for (const commandId of gate.commandIds) {
const command = commands.get(commandId);
if (!command) throw new TypeError(`${gateId} names an undefined command: ${commandId}`);
mergeScripts.add(command.script);
if (seen.has(commandId) || Object.hasOwn(excluded, command.script)) continue;
seen.add(commandId);
selected.push(Object.freeze({
name: `${gateId}:${commandId}`,
script: command.script,
args: Object.freeze([...(command.args ?? [])]),
expectation: command.expect === "pass"
? Object.freeze({ kind: "pass" as const })
: Object.freeze({
kind: "fail" as const,
expectedExitCode: command.expectedExitCode ?? 1,
expectedDiagnosticId: command.expectedDiagnosticId ?? "",
}),
}));
}
}
// An exclusion for a command that moved out of the merge stage would hide
// nothing today and silently drop it if it came back. A command the contract
// no longer has at all (a removal drill pruned its capability) is not stale.
const contractScripts = new Set(contract.commands.map(({ script }) => script));
const stale = Object.keys(excluded).filter(
(script) => contractScripts.has(script) && !mergeScripts.has(script),
);
if (stale.length > 0) {
throw new TypeError(
`the scaffold drill excludes scripts the contract runs outside the merge stage: ${stale.join(", ")}`,
);
}
return Object.freeze(selected);
}
/**
* Runs one merge command in the fixture. A negative fixture command passes
* only with its registered exit code and diagnostic, as in run-ci-gate.ts.
*/
export function runScaffoldDrillCommand(
command: ScaffoldDrillCommand,
root: string,
pnpmCli: string,
): RemovalCheck {
const capture = command.expectation.kind === "fail";
const result = spawnSync(process.execPath, [pnpmCli, command.script, ...command.args], {
cwd: root,
encoding: "utf8",
stdio: capture ? "pipe" : "inherit",
maxBuffer: 64 * 1024 * 1024,
env: { ...process.env, ...FIXTURE_PNPM_ENVIRONMENT },
});
if (capture) {
process.stdout.write(result.stdout ?? "");
process.stderr.write(result.stderr ?? "");
}
const classification = classifyGateStepResult(command.expectation, {
status: result.status,
signal: result.signal,
stdout: result.stdout ?? "",
stderr: result.stderr ?? "",
...(result.error ? { error: { code: (result.error as NodeJS.ErrnoException).code } } : {}),
});
if (classification.expectationMet) return { name: command.name, passed: true };
const invocation = `corepack pnpm ${[command.script, ...command.args].join(" ")}`;
return {
name: command.name,
passed: false,
failure: command.expectation.kind === "fail"
? `${invocation}: ${classification.kind}, expected exit ${command.expectation.expectedExitCode} with ${JSON.stringify(command.expectation.expectedDiagnosticId)}, got exit ${result.status ?? result.signal}`
: `${invocation} exited ${result.status ?? result.signal ?? "on a spawn error"}`,
};
}