OPT106 — Runtime TypeScript Transpilation on the Long Pole
TL;DR: A long-pole tool or test step starts through tsx, ts-node, or a
node --loader / --import / --require TypeScript hook, transpiling the same
files on every process start. Measure the loader's share of the step, then
precompile the exact tool surface once, or preload a cached transform, and make
any fallback to runtime transpilation fail loudly.
Detection heuristic (default path, every gate required):
- The step is on a measured long pole: its measured p50 is at least 20 seconds and at least 15% of the pole job's p50 (the OPT83 step floors).
- The step's workflow
run:command, resolved throughpackage.jsonscripts the same way OPT84 reads them (pnpm test->tsx --test src/*.test.ts), starts a runtime TypeScript loader: thetsx,ts-nodeorts-node-esmbinary (directly or throughnpx,pnpm exec,yarn,bunx);nodewith--loader,--experimental-loader,--import,-ror--requirenamingtsxorts-node(tsx/esm,ts-node/register,ts-node/esm...); or aNODE_OPTIONScarrying such a flag, inline (cross-envandenvread through) or in the step, job or workflowenv. A package script whose name only starts with a loader name (yarn tsx-lint), anecho, a comment, and a precompilednode dist/...do not count. A command the read cannot follow (an expression, a directory change, an unreadable script) stays quiet.
Without a profile the loader's share of the step is unknown, so the finding is unsized on both axes and its fix starts with measuring it.
Upgrade path (profiled): when the same step also emits
CI_SPEEDUP_RUNTIME_TS_PROFILE_V1 with the loader, self-time in milliseconds,
retained .cpuprofile filename and SHA-256 (produced by the workflow's own
CPU-profile parser; Node's --cpu-prof flag does not emit such a summary by
itself), and that self-time is at least 30 seconds and at least 20% of the job's
measured wall without exceeding it, the finding is sized from the profile.
A free-form jiti self time line or a summary in another step is not evidence.
Fix recipe, safest first:
- Measure first: profile one run of the step (
node --cpu-prof, or one instrumented run) to learn the loader's self time. Skip the rest if it is small. - Identify the exact TypeScript entry surfaces the measured command loads. Precompile those surfaces once, or preload their cached transform through the existing module graph. Keep the same module format, inputs, and outputs.
- Add a guard around the exercised path that records every runtime-loader fallback and fails if the count is non-zero. The guard is part of the fix: without it, a new entry surface can silently restore the long pole.
- Compare generated bytes where applicable, run the same tests, and profile the same command again on the same runner class and cache state.
Guardrail: do not skip an entry surface, commit stale generated output, or change test/tool semantics to remove the loader. Preserve generated bytes, module resolution, source-map behavior, test coverage, failures, and exit status. A warm transform cache is acceptable only when its key includes every source and toolchain input that changes the emitted code.
Sizing: on the default path both axes read "unsized (loader share not measured; the step's measured p50 of N s is an upper bound)"; the step's duration is never credited as a saving. On the profiled path the loader self-time is a ceiling on both per-run wall clock and runner-minute saving: "runner-minute saving: at most N/month (profiled loader ceiling from 1 representative run x R workflow runs in 30 days)", clamped to the affected job's measured completed-run compute. The realized saving is the matched before/after difference after the guarded replacement.
Real-world example (OpenClaw), their numbers, not a forecast for another repository: openclaw/openclaw #109757 reported 354 seconds falling to 54 seconds for the runtime-transpilation fix in that pull request.
Risk: MEDIUM. The mechanical change is reversible, but a missing entry surface can leave CI green while testing a different path. The fallback guard and output comparison are mandatory.