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//`, at the paths they have in the checkout: * `artifacts/tests/e2e/results` becomes * `.tmp/runs//artifacts/tests/e2e/results`, `dist` becomes * `.tmp/runs//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. */ 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>; const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u; /** `.` without a run ID, `.tmp/runs/` 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); } /** * 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}`; }