@autor3search/javascript 0.2.0

package/src/cli/cmd-version.js

@@ -0,0 +1,31 @@
+/**
+ * Prints which build of the harness is running.
+ *
+ * A results.tsv row is only as reproducible as the harness that produced it,
+ * so this reports the package version and, when running from a checkout, the
+ * commit with a `dirty` marker.
+ */
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import * as gitx from '../gitx.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = join(HERE, '..', '..')
+
+export async function runVersion(args, io) {
+  parseArgs({ args, options: { C: { type: 'string', default: '.' } }, allowPositionals: false })
+
+  const pkg = JSON.parse(await readFile(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+  let provenance = 'not a git checkout'
+  try {
+    const commit = await gitx.headCommit(PACKAGE_ROOT)
+    const clean = await gitx.isClean(PACKAGE_ROOT)
+    provenance = `commit ${commit}${clean ? '' : ' (dirty)'}`
+  } catch {
+    // Installed from a registry rather than run from a checkout.
+  }
+  io.out.write(`autor3search-javascript ${pkg.version} (${provenance})\n`)
+  return 0
+}

package/src/cli/context.js

@@ -0,0 +1,98 @@
+/**
+ * Shared resolution for every command: which repository, which run.
+ *
+ * Nothing here calls process.chdir. `-C` is threaded through as a value
+ * instead, which is safer under concurrent invocations and lets the tests
+ * exercise commands without mutating global state.
+ */
+import { CONFIG_PATH, loadConfig } from '../config.js'
+import * as gitx from '../gitx.js'
+import { BRANCH_PREFIX, stateDir, validTag } from '../state/index.js'
+import { join } from 'node:path'
+
+/**
+ * Rewrites single-dash multi-character flags into the long form parseArgs
+ * accepts.
+ *
+ * Node's parseArgs recognises a single dash ONLY for a single-character option
+ * name, so `-C` works but `-tag` fails with "Unknown option '-t'" and `-desc`
+ * with "Unknown option '-d'". This harness documents the single-dash spelling
+ * throughout — program.md tells the agent to run `eval -desc "..."` and
+ * `baseline -tag sep7` — so the tokens are normalised here rather than
+ * changing a contract an agent already follows.
+ *
+ * Only an exact whole-token match is rewritten, so a VALUE that happens to
+ * look like a flag (`-desc "-tag is confusing"`) is left alone.
+ *
+ * @param {string[]} args
+ * @param {string[]} names long option names to accept in single-dash form
+ * @returns {string[]}
+ */
+export function expandSingleDashFlags(args, names) {
+  const single = new Set(names.map((name) => `-${name}`))
+  let expectingValue = false
+  return args.map((token) => {
+    if (expectingValue) {
+      expectingValue = false
+      return token
+    }
+    if (single.has(token)) {
+      expectingValue = true
+      return `--${token.slice(1)}`
+    }
+    return token
+  })
+}
+
+/** The repository root containing dir. */
+export async function resolveRepo(dir) {
+  try {
+    return await gitx.root(dir)
+  } catch (err) {
+    throw new Error(`${dir} is not inside a git repository: ${err.message}`, { cause: err })
+  }
+}
+
+/**
+ * Resolves the run a command should act on.
+ *
+ * The tag comes from `-tag` when given, otherwise from the checked-out branch
+ * — which is why `status` and `stop` accept `-tag`: they are meant to work
+ * from any branch, including one the agent is not on.
+ *
+ * @param {string} dir
+ * @param {string} [tag]
+ */
+export async function resolveRun(dir, tag) {
+  const root = await resolveRepo(dir)
+  let resolved = tag
+  if (!resolved) {
+    const branch = await gitx.currentBranch(root)
+    if (!branch.startsWith(BRANCH_PREFIX)) {
+      throw new Error(
+        `the checked-out branch ${JSON.stringify(branch)} is not a run branch, so there is no tag to ` +
+          `infer — pass -tag <tag>`,
+      )
+    }
+    resolved = branch.slice(BRANCH_PREFIX.length)
+  }
+  validTag(resolved)
+  return {
+    root,
+    tag: resolved,
+    branch: `${BRANCH_PREFIX}${resolved}`,
+    stateDir: await stateDir(root, resolved),
+  }
+}
+
+/** Loads the in-repo config, with a message naming what to run when absent. */
+export async function loadRepoConfig(root) {
+  try {
+    return await loadConfig(join(root, CONFIG_PATH))
+  } catch (err) {
+    if (err.cause?.code === 'ENOENT') {
+      throw new Error(`no ${CONFIG_PATH} in ${root}: run 'autor3search-javascript init' first`, { cause: err })
+    }
+    throw err
+  }
+}

package/src/cli/main.js

@@ -0,0 +1,62 @@
+/**
+ * Subcommand registry and dispatch.
+ *
+ * The binary never edits source code. It gates correctness, measures
+ * candidate against baseline, and returns a verdict.
+ */
+import { runVersion } from './cmd-version.js'
+
+/** Exit codes. program.md branches on 0-3; 64 is the conventional usage code. */
+export const EXIT_USAGE = 64
+
+const COMMANDS = [
+  ['init', 'scan the repo, discover benchmarks, write config and program.md', () => import('./cmd-init.js').then((m) => m.runInit)],
+  ['doctor', 'check whether this machine can measure reliably', () => import('./cmd-doctor.js').then((m) => m.runDoctor)],
+  ['baseline', 'create the run branch, freeze tests and benchmarks, record the baseline', () => import('./cmd-baseline.js').then((m) => m.runBaseline)],
+  ['profile', 'profile the declared benchmarks and report hot spots', () => import('./cmd-profile.js').then((m) => m.runProfile)],
+  ['eval', 'run one experiment step and return a verdict', () => import('./cmd-eval.js').then((m) => m.runEval)],
+  ['status', 'show where the run is: branch, worktree, experiments, stop state', () => import('./cmd-status.js').then((m) => m.runStatus)],
+  ['stop', 'ask the agent to end the run after the current experiment', () => import('./cmd-stop.js').then((m) => m.runStop)],
+  ['report', 'summarize results.tsv', () => import('./cmd-report.js').then((m) => m.runReport)],
+  ['version', 'print which build of the harness this is', async () => runVersion],
+]
+
+function usage(io) {
+  io.err.write('autor3search-javascript — autonomous JavaScript performance optimization harness\n')
+  io.err.write('\nusage: autor3search-javascript <command> [flags]\n\ncommands:\n')
+  for (const [name, summary] of COMMANDS) io.err.write(`  ${name.padEnd(9)} ${summary}\n`)
+  io.err.write('\nevery command accepts -C <dir> to run against another repository\n')
+}
+
+/**
+ * @param {string[]} argv arguments after the program name
+ * @param {{out: {write(s: string): void}, err: {write(s: string): void}}} io
+ * @returns {Promise<number>} the process exit code
+ */
+export async function dispatch(argv, io) {
+  if (argv.length === 0) {
+    usage(io)
+    return EXIT_USAGE
+  }
+  const entry = COMMANDS.find(([name]) => name === argv[0])
+  if (!entry) {
+    io.err.write(`unknown command "${argv[0]}"\n\n`)
+    usage(io)
+    return EXIT_USAGE
+  }
+
+  try {
+    const run = await entry[2]()
+    return await run(argv.slice(1), io)
+  } catch (err) {
+    // A bad flag is a usage error, not a crash: report it in one line rather
+    // than as a stack trace an unattended agent would have to parse.
+    if (err.code?.startsWith('ERR_PARSE_ARGS')) {
+      io.err.write(`${err.message}\n\n`)
+      usage(io)
+      return EXIT_USAGE
+    }
+    io.err.write(`${err.message}\n`)
+    return 2
+  }
+}

package/src/config.js

@@ -0,0 +1,209 @@
+/**
+ * Loads and validates the autor3search-javascript run configuration.
+ *
+ * The file lives inside the repository because humans own it and want it in
+ * version control. That means the agent can reach it, so it is protected by
+ * integrity checking rather than relocation: `baseline` records its hash and
+ * `eval` fails the run if it has changed. See src/pipeline.js.
+ */
+import { readFile } from 'node:fs/promises'
+import { parse as parseYaml } from 'yaml'
+import { parseDuration } from './duration.js'
+
+/** Config location, relative to the repository root. */
+export const CONFIG_PATH = '.autor3search/config.yaml'
+
+/** The only bench runner adapter registered in this version. */
+export const RUNNERS = ['vitest']
+
+/** Permitted values for each entry under `gates:`. */
+export const GATE_MODES = ['auto', 'on', 'off']
+
+/** The gates a config may name. Anything else under `gates:` is a typo. */
+export const GATE_NAMES = ['typecheck', 'lint', 'test']
+
+/**
+ * The smallest `count` at which the exact Mann-Whitney test used by
+ * src/bench/stats.js can ever report p < 0.05, however large or clean the
+ * improvement is. At 2 and 3 rounds per side the best achievable two-sided
+ * p-value is 0.3333 and 0.1 — both above the default alpha — so every single
+ * experiment would be discarded on a technicality rather than on its merits,
+ * with nothing in the output explaining why.
+ */
+export const MIN_COUNT = 4
+
+/**
+ * The largest `count` a config may ask for.
+ *
+ * Not a statistical limit — past a few dozen rounds per side the estimate has
+ * long stopped moving. It is a typo guard. `timeout` bounds each child process,
+ * not the run, so an extra zero does not fail: it quietly turns an overnight
+ * run into one that never finishes, and unattended is exactly how this tool is
+ * meant to be used. 1000 rounds per side is already 2000+ measurement
+ * processes and hours of wall clock, so a legitimate run stays well under it
+ * while `10000` or `1000000` stops at the config instead of at dawn.
+ */
+export const MAX_COUNT = 1000
+
+/** Returns the configuration used when a field is omitted. */
+export function defaultConfig() {
+  return {
+    benchmarks: [],
+    scope: ['**'],
+    count: 10,
+    maxRegressPct: 5,
+    minEffectPct: 1,
+    timeout: '15m',
+    unfreeze: [],
+    runner: 'vitest',
+    heapHint: true,
+    gates: { typecheck: 'auto', lint: 'auto', test: 'auto' },
+  }
+}
+
+/** YAML key -> in-memory field. Keys absent here keep their own name. */
+const KEY_MAP = {
+  max_regress_pct: 'maxRegressPct',
+  min_effect_pct: 'minEffectPct',
+  heap_hint: 'heapHint',
+}
+
+/** Every in-memory field name, derived from the defaults so the two cannot drift. */
+const KNOWN_FIELDS = new Set(Object.keys(defaultConfig()))
+
+/** Every key a user may legally write in the YAML, for the error message. */
+const KNOWN_YAML_KEYS = new Set([
+  ...Object.keys(KEY_MAP),
+  ...[...KNOWN_FIELDS].filter((f) => !Object.values(KEY_MAP).includes(f)),
+])
+
+/**
+ * Reads a config file, applying defaults for omitted fields and validating
+ * the result.
+ *
+ * @param {string} path
+ * @returns {Promise<object>}
+ */
+export async function loadConfig(path) {
+  let text
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (err) {
+    throw new Error(`read config ${path}: ${err.message}`, { cause: err })
+  }
+
+  let raw
+  try {
+    raw = parseYaml(text) ?? {}
+  } catch (err) {
+    throw new Error(`parse ${path}: ${err.message}`, { cause: err })
+  }
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`parse ${path}: expected a mapping of settings at the top level`)
+  }
+
+  const cfg = defaultConfig()
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === undefined || value === null) continue
+    const field = KEY_MAP[key] ?? key
+    // An unrecognised key is an ERROR, never a stray property. Without this, a
+    // typo like `max_regres_pct` is silently accepted while the real field
+    // keeps its default — so the run gates on a threshold the user never set
+    // and nothing says so. config.yaml is hashed at baseline, which means that
+    // typo is then locked in for the entire run.
+    if (!KNOWN_FIELDS.has(field)) {
+      throw new Error(
+        `${path}: unknown setting ${JSON.stringify(key)} — known settings are: ${[...KNOWN_YAML_KEYS].sort().join(', ')}`,
+      )
+    }
+    // `gates` merges rather than replaces, so a config setting one gate does
+    // not silently drop the defaults for the other two.
+    if (field === 'gates' && typeof value === 'object' && !Array.isArray(value)) {
+      // The same rule as above, one level down. `gates: {tests: "on"}` would
+      // otherwise merge a key nothing reads while `test` kept its default, so
+      // a user who asked for the test gate ON gets "auto" — which may skip the
+      // gate entirely — and the baseline hash locks that in for the whole run.
+      // Own keys only: a `__proto__` entry must be rejected, not walked into.
+      for (const name of Object.keys(value)) {
+        if (!GATE_NAMES.includes(name)) {
+          throw new Error(
+            `${path}: unknown gate ${JSON.stringify(name)} under 'gates' — known gates are: ${GATE_NAMES.join(', ')}`,
+          )
+        }
+      }
+      for (const name of GATE_NAMES) {
+        if (Object.hasOwn(value, name)) cfg.gates[name] = value[name]
+      }
+      continue
+    }
+    cfg[field] = value
+  }
+
+  try {
+    validate(cfg)
+  } catch (err) {
+    throw new Error(`invalid ${path}: ${err.message}`, { cause: err })
+  }
+  return cfg
+}
+
+/**
+ * Reports whether the configuration is usable, throwing an Error whose
+ * message explains the problem in terms of what it would do to a run.
+ *
+ * @param {object} c
+ * @throws {Error}
+ */
+export function validate(c) {
+  if (!Number.isInteger(c.count) || c.count < MIN_COUNT) {
+    throw new Error(
+      `count must be at least ${MIN_COUNT}: the significance test cannot report p < 0.05 with fewer ` +
+        `than ${MIN_COUNT} measured rounds per side no matter how large the improvement is, so every ` +
+        `experiment would be discarded regardless of what changed (the default is 10)`,
+    )
+  }
+  if (c.count > MAX_COUNT) {
+    throw new Error(
+      `count ${c.count} is above the ${MAX_COUNT} round limit: timeout bounds each measurement process, ` +
+        `not the run, so a count this high does not fail — it runs for hours or days without finishing. ` +
+        `If you really want more than ${MAX_COUNT} rounds per side, raise MAX_COUNT deliberately ` +
+        `(the default is 10, and the estimate stops moving well before 100)`,
+    )
+  }
+  if (typeof c.maxRegressPct !== 'number' || c.maxRegressPct < 0) {
+    throw new Error('max_regress_pct must not be negative')
+  }
+  if (typeof c.minEffectPct !== 'number' || c.minEffectPct < 0 || c.minEffectPct >= 100) {
+    throw new Error('min_effect_pct must be at least 0 and less than 100')
+  }
+  if (!Array.isArray(c.scope) || c.scope.length === 0) {
+    throw new Error('scope must list at least one path pattern')
+  }
+  for (const s of c.scope) {
+    if (typeof s !== 'string' || s.trim() === '') {
+      throw new Error('scope must not contain an empty or whitespace-only entry')
+    }
+  }
+  if (!Array.isArray(c.unfreeze) || c.unfreeze.some((u) => typeof u !== 'string')) {
+    throw new Error('unfreeze must be a list of file paths')
+  }
+  if (!Array.isArray(c.benchmarks) || c.benchmarks.some((b) => typeof b !== 'string')) {
+    throw new Error('benchmarks must be a list of benchmark names')
+  }
+
+  parseDuration(c.timeout)
+
+  if (!RUNNERS.includes(c.runner)) {
+    throw new Error(
+      `runner ${JSON.stringify(c.runner)} is not a registered bench adapter (have: ${RUNNERS.join(', ')})`,
+    )
+  }
+  if (typeof c.heapHint !== 'boolean') {
+    throw new Error('heap_hint must be true or false')
+  }
+  for (const name of GATE_NAMES) {
+    if (!GATE_MODES.includes(c.gates?.[name])) {
+      throw new Error(`gates.${name} must be one of ${GATE_MODES.join(', ')}`)
+    }
+  }
+}

package/src/discover.js

@@ -0,0 +1,239 @@
+/**
+ * Finds benchmarks and test files by PARSING them, never by running Vitest.
+ *
+ * Parsing means discovery works on a tree that does not build — which is
+ * exactly when `init` is run, and exactly when a broken candidate needs to be
+ * reported as a typecheck failure rather than as "no benchmarks found".
+ */
+import { readdir, readFile } from 'node:fs/promises'
+import { join, posix, relative, sep } from 'node:path'
+import { parse } from '@babel/parser'
+
+/** Extensions a bench or test file may carry. */
+export const SOURCE_EXTS = ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']
+
+/** Directories never descended, matching what a JS toolchain itself ignores. */
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', 'out', '.git'])
+
+const EXT_GROUP = SOURCE_EXTS.map((e) => e.slice(1)).join('|')
+const BENCH_RE = new RegExp(`\\.bench\\.(${EXT_GROUP})$`)
+const TEST_RE = new RegExp(`(\\.(test|spec)\\.(${EXT_GROUP})$)|(^|/)__tests__/`)
+
+/** Identifiers that register a benchmark. */
+const BENCH_CALLEES = new Set(['bench'])
+/** Identifiers that open a naming scope around benchmarks. */
+const SUITE_CALLEES = new Set(['describe', 'suite'])
+
+/** @param {string} rel repo-relative, slash-separated */
+export const isBenchFile = (rel) => BENCH_RE.test(rel)
+
+/** @param {string} rel repo-relative, slash-separated */
+export const isTestFile = (rel) => !BENCH_RE.test(rel) && TEST_RE.test(rel)
+
+/** Every `*.bench.*` path in the repository, sorted. */
+export async function benchFiles(root) {
+  return (await walk(root)).filter(isBenchFile)
+}
+
+/** Every test path in the repository, sorted. */
+export async function testFiles(root) {
+  return (await walk(root)).filter(isTestFile)
+}
+
+/**
+ * Every file that must be frozen at baseline: tests AND benchmarks.
+ *
+ * Freezing the benchmarks is not optional. In Vitest a benchmark lives in its
+ * own `*.bench.*` file, separate from the tests — so freezing only the tests
+ * would leave the metric itself editable, and an agent could rewrite the
+ * benchmark to measure something easier with every other gate still passing.
+ * Tests protect correctness; freezing the bench files protects the number.
+ *
+ * @param {string} root
+ * @param {string[]} [exclude] repo-relative paths deliberately left unfrozen
+ */
+export async function frozenFiles(root, exclude = []) {
+  const skip = new Set(exclude.map(toSlash))
+  return (await walk(root)).filter((rel) => (isBenchFile(rel) || isTestFile(rel)) && !skip.has(rel))
+}
+
+/**
+ * Every benchmark declared in the repository, sorted by full path.
+ *
+ * @returns {Promise<{name: string, path: string, file: string, dir: string}[]>}
+ */
+export async function benchmarks(root) {
+  const out = []
+  for (const rel of await benchFiles(root)) {
+    let ast
+    try {
+      ast = parse(await readFile(join(root, rel), 'utf8'), {
+        sourceType: 'unambiguous',
+        errorRecovery: false,
+        plugins: pluginsFor(rel),
+      })
+    } catch {
+      // An unparseable bench file is not fatal to discovery. `init` reporting
+      // "no benchmarks" for a whole repository because one file has a syntax
+      // error would be a worse failure than silently skipping it.
+      continue
+    }
+    const dir = posix.dirname(rel)
+    collect(ast.program.body, [], (name, path) => {
+      out.push({ name, path, file: rel, dir })
+    })
+  }
+  out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  return out
+}
+
+/**
+ * The bench FILES that contain any of the declared benchmarks.
+ *
+ * Vitest has no working name filter for benchmarks — `--testNamePattern` does
+ * not apply to them — so the declared set is selected after parsing, by
+ * BenchSet.selectByBase. Without this, every round runs every benchmark in the
+ * repository and throws almost all of it away: on a repository with 286 bench
+ * files and 1131 `bench()` calls, one round costs ~9 minutes instead of ~8
+ * seconds, and an eval needs fourteen of them.
+ *
+ * Filtering by FILE is safe where filtering by name is not, because it cannot
+ * change which benchmarks are scored — selectByBase still decides that. It
+ * only stops Vitest measuring benchmarks nothing will look at. The same list
+ * is used for both sides of the comparison, so the two sides stay identical.
+ *
+ * An empty `declared` means "every benchmark" and returns every bench file.
+ * A declared name matching nothing also returns [], which runs everything and
+ * lets selectByBase fail loudly naming what it could not match — the same
+ * behaviour as before this filter existed.
+ *
+ * @param {string} root
+ * @param {string[]} declared leaf benchmark names, as recorded at baseline
+ * @returns {Promise<string[]>} repo-relative paths, sorted
+ */
+export async function benchFilesFor(root, declared = []) {
+  if (declared.length === 0) return benchFiles(root)
+  const want = new Set(declared)
+  const files = new Set()
+  for (const b of await benchmarks(root)) {
+    if (want.has(b.name)) files.add(b.file)
+  }
+  return [...files].sort()
+}
+
+/** The leaf benchmark names, sorted and deduplicated. */
+export function baseNames(list) {
+  return [...new Set(list.map((b) => b.name))].sort()
+}
+
+/**
+ * Walks the statements of a scope, recording `bench(...)` calls and
+ * descending into `describe(...)` bodies so a nested benchmark's reported
+ * path matches how Vitest names the task.
+ */
+function collect(nodes, prefix, emit) {
+  for (const node of nodes ?? []) {
+    const call = asCall(node)
+    if (!call) continue
+    const callee = rootCalleeName(call.callee)
+    const name = literalName(call.arguments?.[0])
+    if (name === null) continue
+
+    if (BENCH_CALLEES.has(callee)) {
+      emit(name, [...prefix, name].join(' > '))
+      continue
+    }
+    if (SUITE_CALLEES.has(callee)) {
+      const body = call.arguments[1]
+      if (body?.body?.type === 'BlockStatement') {
+        collect(body.body.body, [...prefix, name], emit)
+      }
+    }
+  }
+}
+
+/**
+ * The Babel plugins to parse one file with, keyed by extension.
+ *
+ * `jsx` must NOT be enabled for a plain `.ts` file. There, `<number>value` is
+ * a legacy type assertion, but with `jsx` on, Babel reads it as an unclosed
+ * JSX element and the whole file fails to parse — so its benchmarks silently
+ * vanish from discovery. TypeScript itself forbids JSX syntax in `.ts` for
+ * exactly this ambiguity, which is why `.tsx` exists, so keying on the
+ * extension costs nothing and cannot regress a legitimate construct.
+ */
+export function pluginsFor(rel) {
+  const common = ['decorators-legacy', 'importAttributes']
+  if (/\.(mts|cts|ts)$/.test(rel)) return ['typescript', ...common]
+  if (rel.endsWith('.tsx')) return ['typescript', 'jsx', ...common]
+  return ['jsx', ...common]
+}
+
+/** Unwraps an expression statement into its call expression, if it is one. */
+function asCall(node) {
+  const expr = node?.type === 'ExpressionStatement' ? node.expression : null
+  return expr?.type === 'CallExpression' ? expr : null
+}
+
+/**
+ * The base identifier of a callee, so `bench.skip` and `describe.each(...)`
+ * are recognised as `bench` and `describe`.
+ */
+function rootCalleeName(callee) {
+  let node = callee
+  while (node) {
+    if (node.type === 'Identifier') return node.name
+    if (node.type === 'MemberExpression') node = node.object
+    else if (node.type === 'CallExpression') node = node.callee
+    else if (node.type === 'TaggedTemplateExpression') node = node.tag
+    else return null
+  }
+  return null
+}
+
+/**
+ * The static name of a task, from a string or a template literal with no
+ * substitutions. A computed name is returned as null and the call is skipped:
+ * the harness must never guess at a name it will later have to match against
+ * Vitest's own output.
+ */
+function literalName(node) {
+  if (node?.type === 'StringLiteral') return node.value
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis.map((q) => q.value.cooked).join('')
+  }
+  return null
+}
+
+/** Every file under root, repo-relative and slash-separated, sorted. */
+async function walk(root) {
+  const out = []
+  async function visit(absolute) {
+    let entries
+    try {
+      entries = await readdir(absolute, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const child = join(absolute, entry.name)
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.') || entry.name.startsWith('_')) {
+          // __tests__ is the one underscore-prefixed directory that matters.
+          if (entry.name !== '__tests__') continue
+        }
+        await visit(child)
+        continue
+      }
+      // Deliberately does NOT follow symlinked entries: a symlink is handled
+      // by src/freeze.js, which refuses them loudly rather than walking
+      // through one into a tree outside the repository.
+      if (!entry.isFile()) continue
+      out.push(toSlash(relative(root, child)))
+    }
+  }
+  await visit(root)
+  return out.sort()
+}
+
+const toSlash = (p) => p.split(sep).join('/')