diff --git a/docs/manual/README.md b/docs/manual/README.md index 5c61e1be..f67ddd6c 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -3,7 +3,7 @@ 이 폴더는 이 템플릿으로 만든 프로젝트에 **새 기능 하나를 추가하는 절차**를 적는다. 기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다. -시작은 `corepack pnpm create:feature `다. 이 명령이 모든 merge 게이트를 통과하는 가장 작은 기능을 만든다. +시작은 `corepack pnpm create:feature `다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, `docs/manual/reference/create-feature.md`). 그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다. ## 누가 읽는가 diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md index 5321f33e..0824a0dd 100644 --- a/docs/manual/reference/create-feature.md +++ b/docs/manual/reference/create-feature.md @@ -1,6 +1,7 @@ # create:feature 참조 -모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 정본은 `scripts/create-feature.ts`다. +모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만드는 명령이다. 정본은 `scripts/create-feature.ts`다. +`test:feature-scaffold`가 생성한 기능으로 `config/ci/gates.json`의 merge 단계 명령을 돌려 확인한다. 브라우저 게이트(FE-GATE-008·009의 브라우저 명령)와 `test:system`은 빼고 돈다. 뺀 명령과 이유는 `scripts/lib/feature-scaffold-drill.ts`에 있다. 템플릿 문자열이 그 파일 안에 있고, 참조 기능을 import하지 않는다. 그래서 참조 기능을 지운 프로젝트에서도 동작한다. ## 사용법 @@ -98,7 +99,7 @@ create:feature: in (new context), route at Next: 1. Before a release, have a person review and sign artifacts/tests/a11y-manual/.md (FE-GATE-028). ... - 2. Run the merge gates: corepack pnpm check:types, lint, ... + 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE- for each gate of the merge stage ... The feature's own tests: node scripts/run-vitest.ts run tests/features/ ... The registry baseline does not change: ... ``` diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index b035bbf1..e2f7a100 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -13,8 +13,11 @@ import { import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts"; /** - * U7. `pnpm create:feature ` writes the smallest feature that passes every - * merge gate: one list route without params, one GET (SAFE, EXTERNAL_BEARER), + * U7. `pnpm create:feature ` writes the smallest feature meant to pass + * every merge gate. test:feature-scaffold runs the merge stage on it except the + * commands SCAFFOLD_DRILL_EXCLUDED_SCRIPTS names (browser gates, test:system; + * scripts/lib/feature-scaffold-drill.ts). The feature has one list route + * without params, one GET (SAFE, EXTERNAL_BEARER), * one query, one invalidation topic, one CollectionPage with ko-KR and en-US * copy, and a router page test plus an input test. The templates live in this * file and import nothing from a sample feature, so the command keeps working @@ -1415,7 +1418,7 @@ function report(plan: FeaturePlan): string { "", "Next:", ` 1. Before a release, have a person review and sign artifacts/tests/a11y-manual/${plan.routeId}.md (FE-GATE-028). The merge gates check only its format.`, - " 2. Run the merge gates: corepack pnpm check:types, lint, check:architecture, check:registries, check:i18n, check:design-system, check:diagnostics, verify:documentation, test:unit, test:component, test:integration, test:coverage, check:ci, build.", + " 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE- for each gate of the merge stage in config/ci/gates.json (README lists the loop). test:feature-scaffold runs them on a generated feature except the browser gates FE-GATE-008/009 and test:system.", ` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`, " The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.", ]; diff --git a/scripts/lib/feature-scaffold-drill.ts b/scripts/lib/feature-scaffold-drill.ts new file mode 100644 index 00000000..f125bdbf --- /dev/null +++ b/scripts/lib/feature-scaffold-drill.ts @@ -0,0 +1,139 @@ +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_gate matrix browser: false). 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> = 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<{ + /** `:`, the check's name in the drill report. */ + name: string; + script: string; + args: readonly string[]; + expectation: GateStepExpectation; +}>; + +type ContractShape = Pick; + +export function scaffoldDrillCommands( + contract: ContractShape, + excluded: Readonly> = 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(); + const seen = new Set(); + 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 the merge stage no longer runs would hide nothing today and + // silently drop the command if it came back under the same name. + const stale = Object.keys(excluded).filter((script) => !mergeScripts.has(script)); + if (stale.length > 0) { + throw new TypeError( + `the scaffold drill excludes scripts the merge stage does not run: ${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"}`, + }; +} diff --git a/scripts/test-feature-scaffold.ts b/scripts/test-feature-scaffold.ts index 6348a516..59df1162 100644 --- a/scripts/test-feature-scaffold.ts +++ b/scripts/test-feature-scaffold.ts @@ -1,5 +1,10 @@ import { mkdir, rm, writeFile } from "node:fs/promises"; +import { loadCiGateContract } from "./contracts/ci-gates.ts"; +import { + runScaffoldDrillCommand, + scaffoldDrillCommands, +} from "./lib/feature-scaffold-drill.ts"; import { createRemovalFixtureRoot, prepareRemovalFixture, @@ -15,7 +20,16 @@ import { /** * U7. A feature from `create:feature` passes the merge gates without an edit * and breaks no other test. A copy of the repository, sample feature - * included, gets one generated feature and then runs the gates. + * included, gets one generated feature and then runs the merge stage of its + * config/ci/gates.json: every command except those + * SCAFFOLD_DRILL_EXCLUDED_SCRIPTS names with a reason (the browser gates, + * test:system, the install check and the removal drills). 1103/12-02: this + * used to be a hand-kept list of 15 commands. + * + * 1103/16-02. The generated feature is then removed again with + * `test:sample-removal -- --feature=`, the path the manual tells every + * product feature to take and that no gate ran. + * * test:sample-removal repeats the generation after deleting the sample * (decision 4), which proves the command needs nothing from it. */ @@ -41,23 +55,10 @@ try { // Commits the copy with the feature, as a project would: git-based // checks (git grep, git ls-files) then see the feature's files. sealRemovalFixtureRepository(fixtureRoot); - checks.push( - check("typecheck", "check:types"), - check("lint", "lint"), - check("architecture", "check:architecture"), - check("registries", "check:registries"), - check("i18n", "check:i18n"), - check("design-system", "check:design-system"), - check("diagnostics", "check:diagnostics"), - check("documentation", "verify:documentation"), - check("unit", "test:unit"), - check("component", "test:component"), - check("integration", "test:integration"), - check("features", "exec", ["node", "scripts/run-vitest.ts", "run", "tests/features"]), - check("coverage", "test:coverage"), - check("ci-contract", "check:ci"), - check("build", "build"), - ); + for (const command of scaffoldDrillCommands(await loadCiGateContract(fixtureRoot))) { + checks.push(runScaffoldDrillCommand(command, fixtureRoot, pnpmCli)); + } + checks.push(check("feature-removal", "test:sample-removal", ["--", `--feature=${FEATURE_ID}`])); } const failed = checks.filter((entry) => !entry.passed); await mkdir("artifacts/tests", { recursive: true }); diff --git a/tests/unit/feature-scaffold-drill.test.ts b/tests/unit/feature-scaffold-drill.test.ts new file mode 100644 index 00000000..414ae81a --- /dev/null +++ b/tests/unit/feature-scaffold-drill.test.ts @@ -0,0 +1,65 @@ +import { readFile } from "node:fs/promises"; + +import { describe, expect, it } from "vitest"; + +import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts"; +import { + SCAFFOLD_DRILL_EXCLUDED_SCRIPTS, + scaffoldDrillCommands, +} from "../../scripts/lib/feature-scaffold-drill.ts"; + +// 1103/12-02. The scaffold drill claimed "every merge gate" and ran 15 +// hand-picked commands of the 88 in the merge stage. +describe("feature scaffold drill commands", () => { + it("are the merge stage minus the named exclusions, each command once", async () => { + const contract = await loadCiGateContract(process.cwd()); + const merge = contract.stages.find(({ id }) => id === "merge")!; + const mergeCommandIds = new Set( + merge.gateIds.flatMap((gateId) => contract.gates.find(({ id }) => id === gateId)!.commandIds), + ); + const commands = scaffoldDrillCommands(contract); + const runCommandIds = commands.map(({ name }) => name.split(":").slice(1).join(":")); + expect(new Set(runCommandIds).size).toBe(runCommandIds.length); + for (const commandId of mergeCommandIds) { + const command = contract.commands.find(({ id }) => id === commandId)!; + expect( + runCommandIds.includes(commandId) || Object.hasOwn(SCAFFOLD_DRILL_EXCLUDED_SCRIPTS, command.script), + commandId, + ).toBe(true); + } + expect(commands.map(({ script }) => script)).toEqual(expect.arrayContaining([ + "check:types", "lint", "test:unit", "test:coverage", "build", "check:bundle", + "test:contract", "test:runtime-schema", "check:request-fanout", "build:release-candidate", + ])); + for (const reason of Object.values(SCAFFOLD_DRILL_EXCLUDED_SCRIPTS)) { + expect(reason.length).toBeGreaterThan(10); + } + }); + + it("keeps a negative fixture's registered exit and diagnostic", async () => { + const contract = await loadCiGateContract(process.cwd()); + expect(scaffoldDrillCommands(contract).find(({ script }) => script === "check:types:fixture")) + .toMatchObject({ expectation: { kind: "fail", expectedExitCode: 1, expectedDiagnosticId: "error TS2322:" } }); + }); + + it("runs a command added to the merge stage without an edit to the drill", async () => { + const contract = structuredClone(await loadCiGateContract(process.cwd())); + contract.commands.push({ id: "check-probe", script: "check:probe", expect: "pass" } as never); + contract.gates.find(({ id }) => id === "FE-GATE-010")!.commandIds.push("check-probe"); + expect(scaffoldDrillCommands(contract).map(({ name }) => name)).toContain("FE-GATE-010:check-probe"); + }); + + it("refuses an exclusion for a script the merge stage does not run", async () => { + const contract = await loadCiGateContract(process.cwd()); + expect(() => scaffoldDrillCommands(contract, { + ...SCAFFOLD_DRILL_EXCLUDED_SCRIPTS, + "check:gone": "no longer in the merge stage", + })).toThrow(/does not run: check:gone/u); + }); + + it("is what test:feature-scaffold runs", async () => { + const drill = await readFile("scripts/test-feature-scaffold.ts", "utf8"); + expect(drill).toContain("scaffoldDrillCommands("); + expect(drill).toContain("loadCiGateContract(fixtureRoot)"); + }); +});