Files
clean-architecture-frontend…/scripts/lib/run-isolation.ts
DongHyeonka 68fde02777 fix(test-run): RUN_OUTPUT_ROOT가 있으면 빌드 뒤 검사가 멈춘다
문제: 1105/12-04 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데,
check:bundle의 두 단계(`generate-supply-chain.ts`, `check-bundle.ts`)는 이
변수를 읽지 않고 checkout의 `dist`와 `artifacts/`를 읽는다. 셸에 이 변수를
둔 채 빌드와 check:bundle을 돌리면 예산을 3,504 B 넘는 새 빌드 대신 이전
빌드를 재서 PASS한다(리뷰 12-R2). ci:gate의 신선도 검사도 bundle.json을
check:bundle이 다시 쓰므로 막지 못한다.

고른 방법: `scripts/lib/run-isolation.ts`에 `checkoutBuildReadFailure`를
두고, 두 스크립트가 무엇을 읽기 전에 부른다. 출력 루트가 `.`이 아니면 변수
값과 이유를 적고 exit 1로 멈춘다. `.`(Playwright 설정이 run ID 없이 web
server에 넘기는 값)과 빈 값은 그대로 돈다. 그래서
`RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`도 check-bundle
단계에서 변수 이름을 적고 실패한다.
버린 대안: ci:gate가 시작 전에 거절하기(리뷰 문서 (b)). 12-R2처럼
check:bundle을 직접 돌리는 경우를 막지 못한다. 두 스크립트가 같은 루트를
읽게 하기(c)는 supply-chain 산출물 전부와 CI upload 경로를 함께 옮겨야 한다.

위험·한계:
- FE-GATE-012는 빌드 단계를 끝까지 돈 뒤 check-bundle에서 실패한다. 빌드
  시간만큼 늦게 알린다.
- 같은 모양일 수 있는 `check:app-build-input:bundle`,
  `check:optional-recipes --require-dist`, release candidate 조립은 보지
  않았다. FE-GATE-012에서는 check-bundle이 먼저 실패해 거기까지 가지 않는다.
- 디버깅으로 변수를 둔 사람은 check:bundle 전에 지워야 한다(문서에 적음).
- 이 노트북에서는 실행하지 못했다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/check-bundle-output.test.ts tests/unit/run-isolation.test.ts
리뷰 12-R2 명령(stale-bundle-rc=1, stderr에 RUN_OUTPUT_ROOT), check:types,
lint, verify:documentation, ci:gate FE-GATE-012

Refs: 1106/12-02
2026-11-06 05:35:48 +09:00

184 lines
7.3 KiB
TypeScript

import { createServer } from "node:net";
import path from "node:path";
/**
* 1105/12-04. Where one run writes, so that two runs in one checkout do not
* overwrite each other's build, results and reports.
*
* Two variables, read by different code:
*
* - `TEST_RUN_ID` names a Playwright run. The Playwright configs put its
* results, HTML report, JUnit file and the build its web server serves under
* `.tmp/runs/<id>/`, at the paths they have in the checkout:
* `artifacts/tests/e2e/results` becomes
* `.tmp/runs/<id>/artifacts/tests/e2e/results`, `dist` becomes
* `.tmp/runs/<id>/dist`. Unset, a run writes where it always did, which is
* where the gates, the CI upload and the evidence checks read.
* - `RUN_OUTPUT_ROOT` is what a Playwright config hands its web server. The
* build (`scripts/build-frontend.ts` and every step it runs) writes `dist/`,
* `.generated/frontend-runtime/` and its `artifacts/` evidence under it, and
* Vite keeps its cache there. Build code reads only this variable, never
* `TEST_RUN_ID`: a test that builds a copy of the repository inherits the
* runner's environment and must still build into the copy's own `dist`.
*
* Both roots are `.` or a folder under `.tmp/`. Git ignores `.tmp/`, and so do
* Tailwind's source scan (a Playwright report there would add classes to the
* CSS), Vite's file watcher, Vitest and the e2e helpers that copy the
* repository.
*
* Ports are separate from the run ID: every config serves on a free port
* unless its `TEST_*_PORT` variable pins one (`TEST_PORT_VARIABLES`), so two
* checkouts on one machine do not collide either.
*/
export const TEST_RUN_ID_VARIABLE = "TEST_RUN_ID";
export const RUN_OUTPUT_ROOT_VARIABLE = "RUN_OUTPUT_ROOT";
export const TEST_RUN_DIRECTORY = ".tmp/runs";
type Environment = Readonly<Record<string, string | undefined>>;
const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
/** `.` without a run ID, `.tmp/runs/<id>` with one. */
export function testRunRoot(environment: Environment = process.env): string {
const runId = environment[TEST_RUN_ID_VARIABLE];
if (runId === undefined || runId === "") return ".";
if (!RUN_ID.test(runId)) {
throw new TypeError(
`${TEST_RUN_ID_VARIABLE} must be 1 to 64 letters, digits, ".", "_" or "-", ` +
`starting with a letter or digit; received ${JSON.stringify(runId)}`,
);
}
return `${TEST_RUN_DIRECTORY}/${runId}`;
}
/** `relativePath` as this run writes it: unchanged without a run ID. */
export function testRunPath(
relativePath: string,
environment: Environment = process.env,
): string {
return path.posix.join(testRunRoot(environment), relativePath);
}
/** `.` when unset; otherwise a normalized folder under `.tmp/`. */
export function runOutputRoot(environment: Environment = process.env): string {
const declared = environment[RUN_OUTPUT_ROOT_VARIABLE];
if (declared === undefined || declared === "") return ".";
const root = path.posix.normalize(declared).replace(/\/+$/u, "");
if (root === ".") return ".";
if (declared.includes("\\") || !root.startsWith(".tmp/") || root.split("/").includes("..")) {
throw new TypeError(
`${RUN_OUTPUT_ROOT_VARIABLE} must be "." or a folder under .tmp/ in this checkout; ` +
`received ${JSON.stringify(declared)}`,
);
}
return root;
}
/** `relativePath` as the build writes it: unchanged without an output root. */
export function runOutputPath(
relativePath: string,
environment: Environment = process.env,
): string {
return path.posix.join(runOutputRoot(environment), relativePath);
}
/**
* 1106/12-02. Why `step`, which reads the build where the checkout keeps it
* (`dist/`, the build manifest and the evidence under `artifacts/`), must not
* run in this environment; `undefined` when it may. With RUN_OUTPUT_ROOT set
* the build writes under that folder, so such a step would judge whatever
* build the checkout still holds: check:bundle passed an over-budget build
* that way, on the earlier one. `.` is the checkout itself, which is what a
* Playwright config hands its web server without a run ID.
*/
export function checkoutBuildReadFailure(
step: string,
environment: Environment = process.env,
): string | undefined {
let root: string;
try {
root = runOutputRoot(environment);
} catch (error) {
return `${step}: ${error instanceof Error ? error.message : String(error)}`;
}
if (root === ".") return undefined;
return (
`${step} reads the build at this checkout's paths (dist/, artifacts/), but ` +
`${RUN_OUTPUT_ROOT_VARIABLE}=${root} makes the build write under ${root}/, so it ` +
`would judge an earlier build. Unset ${RUN_OUTPUT_ROOT_VARIABLE}, build again and ` +
`run ${step} again.`
);
}
/**
* The port variable of each Playwright config's web server. Unset, the config
* picks a free port; set, it uses that one (to pin a port while debugging).
*/
export const TEST_PORT_VARIABLES = Object.freeze({
e2e: "TEST_E2E_PORT",
visual: "TEST_VISUAL_PORT",
capabilities: "TEST_CAPABILITIES_PORT",
storybook: "TEST_STORYBOOK_PORT",
dev: "TEST_DEV_PORT",
} as const);
/**
* A port nothing listens on now: the one the kernel gives a socket bound to
* port 0, which is closed again. Another process can still take it before the
* web server binds it. The configs start their servers with `--strictPort`
* (vite) or a fixed `listen` (serve-static) and `reuseExistingServer: false`,
* so that case is a start failure, never a run against someone else's server.
*/
export async function findFreePort(host = "127.0.0.1"): Promise<number> {
return new Promise<number>((resolve, reject) => {
const server = createServer();
server.unref();
server.once("error", reject);
server.listen(0, host, () => {
const address = server.address();
server.close(() => {
if (address !== null && typeof address === "object") resolve(address.port);
else reject(new Error(`no port was bound on ${host}`));
});
});
});
}
/**
* The port one config's web server listens on, kept in `variable`.
*
* Playwright evaluates the config again in each worker process, and the
* workers inherit the runner's environment. The runner's evaluation writes
* the port it picked into `variable`; the workers' evaluations read it, so
* `baseURL` is the same everywhere. A value already set is used as given.
*/
export async function reservePort(
variable: string,
environment: Record<string, string | undefined> = process.env,
find: () => Promise<number> = findFreePort,
): Promise<number> {
const pinned = environment[variable];
if (pinned !== undefined && pinned !== "") {
const port = Number(pinned);
if (!/^\d+$/u.test(pinned) || port < 1 || port > 65_535) {
throw new TypeError(
`${variable} must be a port from 1 to 65535; received ${JSON.stringify(pinned)}`,
);
}
return port;
}
const port = await find();
environment[variable] = String(port);
return port;
}
/**
* The import specifier a generated module at `fromFile` uses for `toFile`,
* both relative to the checkout. A generated module under an output root sits
* deeper than `.generated/` and needs more `../`.
*/
export function moduleSpecifier(fromFile: string, toFile: string): string {
const specifier = path.posix.relative(path.posix.dirname(fromFile), toFile);
return specifier.startsWith(".") ? specifier : `./${specifier}`;
}