@autor3search/javascript 0.2.0

package/src/adapters/bench/vitest.js

@@ -0,0 +1,128 @@
+/**
+ * The Vitest implementation of the BenchRunner interface.
+ *
+ * One call to run() is ONE MEASURED ROUND: a single `vitest bench` process
+ * invocation, contributing one observation per benchmark. Rounds are what the
+ * significance test counts, so this must never be asked to loop internally.
+ */
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { parseVitestBench } from '../../bench/parse.js'
+import { Runner } from '../../runner.js'
+
+/**
+ * Runs one measured round.
+ *
+ * The report is written to a temp file via --outputJson rather than parsed
+ * from stdout: Vitest interleaves progress output with the report, and a
+ * stray console.log from the measured code would corrupt a stdout parse.
+ *
+ * @param {string} dir the worktree to measure
+ * @param {{benchmarks?: string[], timeoutMs: number, env?: object, log?: {write(s: string): void}, signal?: AbortSignal}} opts
+ *   `benchmarks` selects the declared set AFTER parsing. Vitest has no working
+ *   benchmark name filter — `--testNamePattern` is accepted but does not filter
+ *   benches (confirmed against Vitest 2.1.9: `^(alpha)$` still returns `beta`
+ *   too) — so selection happens here rather than on the command line.
+ * @returns {Promise<import('../../bench/set.js').BenchSet>}
+ */
+async function run(dir, opts) {
+  const scratch = await mkdtemp(join(tmpdir(), 'a3s-bench-'))
+  const reportPath = join(scratch, 'bench.json')
+  try {
+    const runner = new Runner(dir, opts.timeoutMs, opts.log ?? null)
+    const result = await runner.run(
+      process.execPath,
+      [
+        vitestBin(dir),
+        'bench',
+        '--run',
+        // `--outputJson` is the ONLY working way to get a machine-readable
+        // benchmark report. `--reporter=json --outputFile=…` fails outright
+        // ("Failed to load custom Reporter from json") and writes nothing.
+        // There is no `--benchmark.time=…` flag either; `BenchmarkUserOptions`
+        // exposes only include/exclude/includeSource/reporters/outputFile/
+        // compare/outputJson/includeSamples.
+        `--outputJson=${reportPath}`,
+        `--root=${dir}`,
+        // Positional args are Vitest's FILENAME filter, which does work (the
+        // name filter does not). Narrowing to the files that hold the declared
+        // benchmarks is what keeps a round proportional to what was declared
+        // rather than to the size of the repository. Empty means no filter, so
+        // an undeclared run still measures everything.
+        ...(opts.benchFiles ?? []),
+      ],
+      { env: opts.env ?? process.env, signal: opts.signal },
+    )
+
+    if (result.timedOut) {
+      throw new Error(`benchmark round timed out in ${dir}`)
+    }
+
+    // A non-zero exit means some task (an import, a bench body) blew up. The
+    // JSON report may still exist in this case — Vitest writes it with an
+    // empty `groups` array for the failed file — but it cannot be trusted as
+    // a complete measurement, and the excerpt naming the real failure lives
+    // in the process output, not in the report. So this is checked BEFORE
+    // reading the report, not after, and carries the tail with it.
+    if (!result.ok()) {
+      throw new Error(`bench run failed in ${dir} (exit ${result.exitCode}):\n${result.tail(30)}`)
+    }
+
+    const report = await readFile(reportPath, 'utf8').catch(() => null)
+    if (report === null) {
+      throw new Error(
+        `bench run exited cleanly in ${dir} but wrote no report at ${reportPath}:\n${result.tail(30)}`,
+      )
+    }
+
+    // A bench body that throws at CALL time is NOT caught above: Vitest exits
+    // 0 for it and writes a report with zeros and no `median`. It is caught
+    // here instead, because parseVitestBench accepts only tinybench's median
+    // and refuses anything else. That coupling is deliberate and load-bearing
+    // — if a timing fallback were ever reintroduced in the parser, a
+    // half-failed benchmark would start being scored as a real measurement.
+    // test/adapters/vitest.test.js pins this.
+    let parsed
+    try {
+      parsed = parseVitestBench(report)
+    } catch (err) {
+      if (/contained no benchmarks/.test(err.message)) {
+        throw new Error(`Vitest measured no benchmarks at all in ${dir}: ${err.message}`, { cause: err })
+      }
+      throw err
+    }
+
+    // Selection happens HERE, not on the command line: Vitest accepts
+    // --testNamePattern for benches but does not act on it, so a run measures
+    // everything and the declared set is chosen afterwards. Costs wall-clock
+    // on undeclared benchmarks; correctness first.
+    const declared = opts.benchmarks ?? []
+    const set = parsed.selectByBase(declared)
+    if (set.names().length === 0) {
+      throw new Error(
+        `no benchmarks matched ${JSON.stringify(declared)} in ${dir} (measured: ${JSON.stringify(parsed.bases())})`,
+      )
+    }
+    return set
+  } finally {
+    await rm(scratch, { recursive: true, force: true })
+  }
+}
+
+/**
+ * The Vitest CLI entry point inside the measured repository.
+ *
+ * Exported so `doctor` can check for the SAME file this actually spawns.
+ * A module resolution (`require.resolve('vitest/vitest.mjs')`) is not
+ * equivalent: it honours the package's `exports` map, and Vitest 2 has a
+ * `./*` wildcard there while Vitest 3 and 4 do not — so the resolution
+ * reports "not installed" on a repository where this path exists and
+ * measurement works.
+ */
+export function vitestBin(dir) {
+  return join(dir, 'node_modules', 'vitest', 'vitest.mjs')
+}
+
+/** @type {{name: string, run: typeof run}} */
+export const vitestRunner = { name: 'vitest', run }

package/src/adapters/driver-child.js

@@ -0,0 +1,72 @@
+/**
+ * The child process the driver spawns.
+ *
+ * Invoked as:
+ *   node [--expose-gc] driver-child.js <mode> <jsonOptionsPath>
+ * where mode is "list", "heap" or "profile". It prints ONE JSON object to
+ * stdout and nothing else, so the parent never has to parse around noise.
+ */
+import { readFile } from 'node:fs/promises'
+import { register } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+const [, , mode, optionsPath] = process.argv
+
+async function main() {
+  register('./driver-hooks.js', import.meta.url)
+  const options = JSON.parse(await readFile(optionsPath, 'utf8'))
+
+  const tasks = []
+  for (const file of options.benchFiles) {
+    globalThis.__a3sTasks = []
+    globalThis.__a3sSuite = []
+    await import(pathToFileURL(file).href)
+    for (const task of globalThis.__a3sTasks) tasks.push({ ...task, file })
+  }
+
+  // Selection is by NAME, matching how the rest of the harness selects (see
+  // BenchSet.selectByBase). An empty list selects everything. Deliberately not
+  // a regexp: a hand-edited config name containing a metacharacter must never
+  // silently widen what gets measured.
+  const wanted = new Set(options.benchmarks ?? [])
+  const selected = wanted.size === 0 ? tasks : tasks.filter((t) => wanted.has(t.name))
+
+  if (mode === 'list') {
+    return { tasks: selected.map(({ name, path, file }) => ({ name, path, file })) }
+  }
+
+  const results = []
+  for (const task of selected) {
+    // A short warmup lets V8 tier the function up, so the measured window
+    // reflects steady-state allocation rather than first-call overhead.
+    for (let i = 0; i < Math.min(50, options.iterations); i++) await task.fn()
+
+    globalThis.gc?.()
+    const before = process.memoryUsage().heapUsed
+    for (let i = 0; i < options.iterations; i++) await task.fn()
+    // Deliberately NOT collecting here: a collection would discard exactly the
+    // allocations being counted. The cost is that a collection running INSIDE
+    // the loop shows up as a negative delta, which is reported as no
+    // observation rather than as a negative allocation figure.
+    const after = process.memoryUsage().heapUsed
+
+    const delta = after - before
+    results.push({
+      name: task.name,
+      path: task.path,
+      file: task.file,
+      bytesPerOp: delta > 0 ? delta / options.iterations : null,
+    })
+  }
+  return { results, gcAvailable: typeof globalThis.gc === 'function' }
+}
+
+main().then(
+  (payload) => {
+    process.stdout.write(JSON.stringify(payload))
+  },
+  (err) => {
+    process.stdout.write(JSON.stringify({ error: err?.stack ?? String(err) }))
+    process.exitCode = 1
+  },
+)

package/src/adapters/driver-hooks.js

@@ -0,0 +1,18 @@
+/**
+ * Module-resolution hooks redirecting the `vitest` specifier to our shim.
+ *
+ * Registered with module.register() (Node >= 20.6) from driver-child.js, so
+ * a bench file's `import { bench } from 'vitest'` resolves to
+ * vitest-shim.js instead of the real package.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const SHIM = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), 'vitest-shim.js')).href
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier === 'vitest' || specifier.startsWith('vitest/')) {
+    return { url: SHIM, shortCircuit: true }
+  }
+  return nextResolve(specifier, context)
+}

package/src/adapters/driver.js

@@ -0,0 +1,192 @@
+/**
+ * Drives bench files outside Vitest, for the two things Vitest's benchmark
+ * reporter cannot give us: an allocation hint, and a CPU/heap profile.
+ *
+ * Everything here is BEST-EFFORT. V8 has no allocation counter, the sampling
+ * window is at the mercy of GC scheduling, and a bench file may do something
+ * the shim cannot drive. Any failure yields an empty set and a note in the
+ * log — never an exception that would sink an otherwise-valid experiment.
+ * src/pipeline.js relies on that: a missing hint must not cost a KEEP.
+ */
+import { mkdir, mkdtemp, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { BenchSet, UNIT_BYTES } from '../bench/set.js'
+import { Runner } from '../runner.js'
+
+const CHILD = join(dirname(fileURLToPath(import.meta.url)), 'driver-child.js')
+
+/**
+ * Lists the benchmarks a bench file registers, without measuring anything.
+ *
+ * @param {string} benchFile absolute path
+ * @returns {Promise<{name: string, path: string}[]>}
+ */
+export async function collectTasks(benchFile) {
+  const payload = await invoke(dirname(benchFile), 'list', {
+    benchFiles: [benchFile],
+    benchmarks: [],
+    iterations: 0,
+  })
+  return (payload?.tasks ?? []).map(({ name, path }) => ({ name, path }))
+}
+
+/**
+ * Measures the approximate bytes allocated per operation, one observation per
+ * benchmark. Returns an EMPTY set when the measurement is unavailable.
+ *
+ * @param {string} dir the worktree to measure
+ * @param {{benchFiles: string[], benchmarks?: string[], iterations: number, timeoutMs: number, env?: object, log?: {write(s: string): void}, signal?: AbortSignal}} opts
+ * @returns {Promise<BenchSet>}
+ */
+export async function measureHeap(dir, opts) {
+  const set = new BenchSet()
+  let payload
+  try {
+    payload = await invoke(dir, 'heap', {
+      benchFiles: opts.benchFiles.map((f) => resolvePath(dir, f)),
+      benchmarks: opts.benchmarks ?? [],
+      iterations: opts.iterations ?? 1000,
+      timeoutMs: opts.timeoutMs,
+      env: opts.env,
+      execArgv: ['--expose-gc'],
+      signal: opts.signal,
+    })
+  } catch (err) {
+    opts.log?.write(`heap hint unavailable, continuing without it: ${err.message}\n`)
+    return set
+  }
+  if (payload?.error) {
+    opts.log?.write(`heap hint unavailable, continuing without it: ${payload.error}\n`)
+    return set
+  }
+  if (payload?.gcAvailable === false) {
+    opts.log?.write('heap hint unavailable: node was not started with --expose-gc\n')
+    return set
+  }
+  for (const r of payload?.results ?? []) {
+    if (r.bytesPerOp === null) continue
+    // Key on a path RELATIVE to `dir`, never the absolute one. `dir` is the
+    // pinned baseline worktree for one side and the repository root for the
+    // other, so absolute keys can never match across the two and every
+    // cross-directory comparison silently produced no hint at all. The time
+    // path avoids this only because Vitest's own report yields root-relative
+    // names — see taskPath in src/bench/parse.js — so this mirrors it.
+    set.record(`${relative(dir, r.file)} > ${r.path}`, r.name, UNIT_BYTES, r.bytesPerOp)
+  }
+  return set
+}
+
+/**
+ * Runs the benchmarks under V8's CPU and heap profilers, writing the raw
+ * profiles into outDir. Both files are openable in Chrome DevTools or
+ * speedscope; src/profile.js summarises the CPU one.
+ *
+ * @returns {Promise<{cpuProfile: string, heapProfile: string}>}
+ */
+export async function runProfiled(dir, opts) {
+  await mkdir(opts.outDir, { recursive: true })
+  const scratch = await mkdtemp(join(tmpdir(), 'a3s-prof-'))
+  try {
+    await invoke(dir, 'heap', {
+      benchFiles: opts.benchFiles.map((f) => resolvePath(dir, f)),
+      benchmarks: opts.benchmarks ?? [],
+      iterations: opts.iterations ?? 1000,
+      timeoutMs: opts.timeoutMs,
+      env: opts.env,
+      execArgv: [
+        '--expose-gc',
+        '--cpu-prof',
+        `--cpu-prof-dir=${scratch}`,
+        '--heap-prof',
+        `--heap-prof-dir=${scratch}`,
+      ],
+    })
+    // V8 names the profiles after a timestamp and pid — verified on Node
+    // 22.23.1 as `CPU.<timestamp>.<pid>.0.001.cpuprofile` and
+    // `Heap.<timestamp>.<pid>.0.002.heapprofile`. There is NO fixed filename to
+    // predict, so they are matched by extension.
+    //
+    // CRUCIALLY, there is more than one of each. `module.register` runs the
+    // resolve hooks on their own thread, and --cpu-prof/--heap-prof profile
+    // that thread too — so a run yields both the MAIN thread's profile (the
+    // benchmark frames we want) and the LOADER thread's (module-resolution
+    // internals, no user code at all). Taking whichever readdir happened to
+    // return last picked the loader's profile in 3 of 3 trials, handing back a
+    // perfectly valid, non-empty profile containing ZERO frames of the
+    // benchmarked code.
+    //
+    // Content-based heuristics were tried and rejected: CPU sample count
+    // discriminated correctly in every trial run during verification, but the
+    // equivalent heap "most tree nodes" heuristic FLIPPED between trials (the
+    // main thread's heap-prof tree was sometimes smaller than the loader
+    // thread's, since heap-prof sampling is allocation-triggered and its yield
+    // is luck-of-the-draw, not proportional to "is this the thread that ran
+    // the benchmark"). So instead this parses the filename's thread-id field:
+    // Node names each profile `<Kind>.<date>.<time>.<pid>.<threadId>.<seq>.<ext>`,
+    // and the main thread's threadId is always 0 — a structural guarantee
+    // (`node:worker_threads` documents `threadId === 0` off the main thread),
+    // not an empirical proxy. Verified across 5 trials: the threadId-0 file is
+    // the one containing `driver-child.js`/benchmark frames in every case.
+    const written = await readdir(scratch)
+    const out = { cpuProfile: join(opts.outDir, 'cpu.cpuprofile'), heapProfile: join(opts.outDir, 'heap.heapprofile') }
+    const cpu = mainThreadFile(written, '.cpuprofile')
+    const heap = mainThreadFile(written, '.heapprofile')
+    if (cpu) await rename(join(scratch, cpu), out.cpuProfile)
+    if (heap) await rename(join(scratch, heap), out.heapProfile)
+    return out
+  } finally {
+    await rm(scratch, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Of several profile files V8 wrote for one run, picks the one written by the
+ * MAIN thread — see the long comment in runProfiled for why this can't be a
+ * content heuristic. Falls back to the alphabetically-first file (still
+ * deterministic) on the Node versions this was verified against, every
+ * profile filename carries the thread-id field, so the fallback is not
+ * expected to trigger in practice.
+ */
+function mainThreadFile(names, extension) {
+  const candidates = names
+    .filter((n) => n.endsWith(extension))
+    .map((n) => ({ name: n, threadId: n.split('.').at(-3) }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+  return (candidates.find((c) => c.threadId === '0') ?? candidates[0])?.name ?? null
+}
+
+/**
+ * Spawns the driver child and parses its single JSON object.
+ *
+ * `options.signal`, when present, is threaded into the Runner that spawns
+ * the child — NOT into the JSON file the child itself reads. An AbortSignal
+ * is not data for driver-child.js (JSON.stringify would silently drop it
+ * anyway, since it carries no own enumerable properties), and without this
+ * split an abort during this call — Ctrl+C or `stop --force` during the
+ * heap-hint phase, most concretely — would never reach runner.run, leaving
+ * the `node --expose-gc` child running until its own timeout (15m by
+ * default) instead of being killed promptly, same as `Runner.onAbort`
+ * already does for every other subprocess this project spawns.
+ */
+async function invoke(dir, mode, options) {
+  const { signal, ...forChild } = options
+  const scratch = await mkdtemp(join(tmpdir(), 'a3s-driver-'))
+  const optionsPath = join(scratch, 'options.json')
+  try {
+    await writeFile(optionsPath, JSON.stringify(forChild))
+    const runner = new Runner(dir, options.timeoutMs ?? 120_000, null)
+    const result = await runner.run(
+      process.execPath,
+      [...(options.execArgv ?? []), CHILD, mode, optionsPath],
+      { env: options.env ?? process.env, signal },
+    )
+    if (result.stdout.trim() === '') {
+      throw new Error(`driver produced no output (exit ${result.exitCode}):\n${result.tail(20)}`)
+    }
+    return JSON.parse(result.stdout)
+  } finally {
+    await rm(scratch, { recursive: true, force: true })
+  }
+}

package/src/adapters/gates/index.js

@@ -0,0 +1,64 @@
+/**
+ * Runs the correctness gates in order, stopping at the first failure.
+ *
+ * Stopping early is deliberate: once a gate has rejected the candidate the
+ * experiment is over, and running the rest would spend minutes producing
+ * output nobody will read.
+ */
+import * as typecheck from './typecheck.js'
+import * as lint from './lint.js'
+import * as test from './test.js'
+
+/** Order matters: cheapest and most fundamental first. */
+const GATES = [typecheck, lint, test]
+
+/**
+ * @param {string} dir
+ * @param {{modes: Record<string,string>, scope: string[], timeoutMs: number, log?: object, signal?: AbortSignal}} opts
+ * @returns {Promise<{name: string, ran: boolean, ok: boolean, timedOut: boolean, skipped: string|null, detail: string}[]>}
+ */
+export async function runGates(dir, opts) {
+  const outcomes = []
+  for (const gate of GATES) {
+    const mode = opts.modes?.[gate.name] ?? 'auto'
+    if (mode === 'off') {
+      outcomes.push(skip(gate.name, 'gates.' + gate.name + ' is "off"'))
+      continue
+    }
+
+    const why = await gate.unavailable(dir)
+    if (why) {
+      if (mode === 'on') {
+        // A gate the user explicitly asked for must not silently vanish.
+        outcomes.push({
+          name: gate.name,
+          ran: false,
+          ok: false,
+          timedOut: false,
+          skipped: null,
+          detail: `gates.${gate.name} is "on" but the gate cannot run: ${why}`,
+        })
+        return outcomes
+      }
+      outcomes.push(skip(gate.name, why))
+      continue
+    }
+
+    const outcome = { name: gate.name, ...(await gate.run(dir, opts)) }
+    // Stop early if the caller aborted while this gate ran; the remaining
+    // gates would only spend minutes producing output nobody will read.
+    if (opts.signal?.aborted) return outcomes.concat(outcome)
+    // A gate that ran but only in a WEAKER form than the repository calls for
+    // fails when the user required it. Silently giving someone a lesser check
+    // than they asked for is the same defect as skipping it, but harder to notice.
+    if (mode === 'on' && outcome.degraded && outcome.ok) {
+      outcome.ok = false
+      outcome.detail = `gates.${gate.name} is "on" but only a degraded check was possible: ${outcome.detail}`
+    }
+    outcomes.push(outcome)
+    if (!outcome.ok) return outcomes
+  }
+  return outcomes
+}
+
+const skip = (name, why) => ({ name, ran: false, ok: true, timedOut: false, skipped: why, detail: '' })

package/src/adapters/gates/lint.js

@@ -0,0 +1,46 @@
+/** The lint gate: ESLint, when the repository is configured for it. */
+import { stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { Runner } from '../../runner.js'
+import { resolveFrom } from './util.js'
+
+export const name = 'lint'
+
+const CONFIGS = [
+  'eslint.config.js',
+  'eslint.config.mjs',
+  'eslint.config.cjs',
+  '.eslintrc',
+  '.eslintrc.js',
+  '.eslintrc.cjs',
+  '.eslintrc.json',
+  '.eslintrc.yml',
+  '.eslintrc.yaml',
+]
+
+export async function unavailable(dir) {
+  for (const candidate of CONFIGS) {
+    const found = await stat(join(dir, candidate)).then(
+      () => true,
+      () => false,
+    )
+    if (found) {
+      return resolveFrom(dir, 'eslint/bin/eslint.js') ? null : 'ESLint is configured but not installed'
+    }
+  }
+  return 'no ESLint config found'
+}
+
+export async function run(dir, opts) {
+  const bin = resolveFrom(dir, 'eslint/bin/eslint.js')
+  const result = await new Runner(dir, opts.timeoutMs, opts.log).run(process.execPath, [bin, '.'], {
+    signal: opts.signal,
+  })
+  return {
+    ran: true,
+    ok: result.ok(),
+    timedOut: result.timedOut,
+    skipped: null,
+    detail: result.ok() ? 'eslint .' : result.tail(30),
+  }
+}

package/src/adapters/gates/test.js

@@ -0,0 +1,27 @@
+/**
+ * The test gate. Correctness is never traded for speed: this runs the frozen
+ * tests, which were restored moments earlier, so a candidate that broke
+ * behaviour fails here before anything is measured.
+ */
+import { Runner } from '../../runner.js'
+import { resolveFrom } from './util.js'
+
+export const name = 'test'
+
+export async function unavailable(dir) {
+  return resolveFrom(dir, 'vitest/vitest.mjs') ? null : 'vitest is not installed in this repository'
+}
+
+export async function run(dir, opts) {
+  const bin = resolveFrom(dir, 'vitest/vitest.mjs')
+  const result = await new Runner(dir, opts.timeoutMs, opts.log).run(process.execPath, [bin, 'run'], {
+    signal: opts.signal,
+  })
+  return {
+    ran: true,
+    ok: result.ok(),
+    timedOut: result.timedOut,
+    skipped: null,
+    detail: result.ok() ? 'vitest run' : result.tail(40),
+  }
+}

package/src/adapters/gates/typecheck.js

@@ -0,0 +1,98 @@
+/**
+ * The build gate.
+ *
+ * A TypeScript repository gets `tsc --noEmit`. A plain-JavaScript repository
+ * has no build step, but it must still get a real "is this even valid code"
+ * gate — otherwise a candidate with a syntax error would reach the test gate
+ * and be reported as a FAILING TEST rather than as a CRASH, losing exactly
+ * the distinction the exit codes exist to draw. So it gets a parse of every
+ * in-scope source file instead.
+ *
+ * The parse fallback reuses discover.js's per-extension plugin choice
+ * (`pluginsFor`): `jsx` must not be enabled for a plain `.ts` file, where
+ * `<number>value` is a legacy type assertion rather than an unclosed JSX
+ * element. Hardcoding a single plugin list here would silently reject valid
+ * TypeScript that discover.js itself parses correctly.
+ */
+import { readFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse } from '@babel/parser'
+import { createMatcher } from '../../scope.js'
+import { SOURCE_EXTS, pluginsFor } from '../../discover.js'
+import { Runner } from '../../runner.js'
+import { resolveFrom, walkSources } from './util.js'
+
+export const name = 'typecheck'
+
+/**
+ * Reports why this gate cannot run here, or null when it can.
+ *
+ * Always null: the parse fallback works everywhere, so there is no repository
+ * where this gate cannot run AT ALL. Degradation is reported separately — see
+ * the `degraded` flag in `run` — because a repo with a tsconfig but no
+ * installed typescript can still be parse-checked, just not type-checked.
+ */
+export async function unavailable() {
+  return null // the parse fallback always works
+}
+
+export async function run(dir, opts) {
+  const hasTsconfig = await stat(join(dir, 'tsconfig.json')).then(
+    () => true,
+    () => false,
+  )
+  const tsc = hasTsconfig ? resolveFrom(dir, 'typescript/bin/tsc') : null
+
+  if (tsc) {
+    const result = await new Runner(dir, opts.timeoutMs, opts.log).run(process.execPath, [tsc, '--noEmit'], {
+      signal: opts.signal,
+    })
+    return {
+      ran: true,
+      ok: result.ok(),
+      timedOut: result.timedOut,
+      skipped: null,
+      degraded: false,
+      detail: result.ok() ? 'tsc --noEmit' : result.tail(30),
+    }
+  }
+
+  const matcher = createMatcher(opts.scope)
+  const failures = []
+  for (const rel of await walkSources(dir, SOURCE_EXTS)) {
+    // Cheap: a boolean read, not a listener. The parse fallback has no
+    // subprocess for the Runner to kill, so without this an abort mid-walk
+    // would wait out the rest of a large repository's file list.
+    if (opts.signal?.aborted) break
+    if (!matcher.match(rel)) continue
+    try {
+      parse(await readFile(join(dir, rel), 'utf8'), {
+        sourceType: 'unambiguous',
+        plugins: pluginsFor(rel),
+      })
+    } catch (err) {
+      failures.push(`${rel}: ${err.message}`)
+      if (failures.length >= 20) break
+    }
+  }
+  // `degraded` marks a check WEAKER than the repository asked for: a
+  // tsconfig.json is present, so this repo wants real type checking, but
+  // typescript is not installed and only a syntax parse was possible. Under
+  // gates.typecheck: "on" that is a failure — a user who required type
+  // checking must not silently receive syntax checking instead. Under "auto"
+  // it runs and says so.
+  const degraded = hasTsconfig
+  return {
+    ran: true,
+    ok: failures.length === 0,
+    timedOut: false,
+    skipped: null,
+    degraded,
+    detail:
+      failures.length > 0
+        ? failures.join('\n')
+        : degraded
+          ? 'parse check ONLY — tsconfig.json is present but typescript is not installed, so types were not checked'
+          : 'parse check (no tsconfig.json)',
+  }
+}