@autor3search/javascript 0.2.0

package/src/adapters/gates/util.js

@@ -0,0 +1,45 @@
+/** Helpers shared by the gates and by src/doctor.js. */
+import { createRequire } from 'node:module'
+import { readdir } from 'node:fs/promises'
+import { join, relative, resolve, sep } from 'node:path'
+
+/**
+ * Resolves a package entry point from inside the MEASURED repository, so the
+ * repository's own installed tool versions are used — never this harness's.
+ * A repository pinned to an older TypeScript must be typechecked by that
+ * TypeScript, or the gate would report errors its own build never sees.
+ *
+ * @returns {string|null} an absolute path, or null when it does not resolve
+ */
+export function resolveFrom(dir, specifier) {
+  try {
+    // resolve() FIRST. createRequire throws on a relative path, which the
+    // catch below turns into null — indistinguishable from "the tool is not
+    // installed". That silent false negative already bit once: `doctor -C .`
+    // reported vitest missing in repositories that had it. Guarding here
+    // rather than at each call site means no future caller can hit it.
+    return createRequire(join(resolve(dir), 'noop.js')).resolve(specifier)
+  } catch {
+    return null
+  }
+}
+
+/** Every source file under dir with one of the given extensions, repo-relative. */
+export async function walkSources(dir, exts) {
+  const skipDirs = new Set(['node_modules', 'dist', 'build', 'coverage', 'out', '.git'])
+  const out = []
+  async function visit(absolute) {
+    const entries = await readdir(absolute, { withFileTypes: true }).catch(() => [])
+    for (const entry of entries) {
+      const child = join(absolute, entry.name)
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name) || entry.name.startsWith('.')) continue
+        await visit(child)
+      } else if (entry.isFile() && exts.some((e) => entry.name.endsWith(e))) {
+        out.push(relative(dir, child).split(sep).join('/'))
+      }
+    }
+  }
+  await visit(dir)
+  return out.sort()
+}

package/src/adapters/vitest-shim.js

@@ -0,0 +1,51 @@
+/**
+ * Stands in for the `vitest` module inside the standalone driver child.
+ *
+ * The real `bench` throws outside a Vitest runner, so a driver that wants to
+ * import a bench file for any purpose OTHER than timing — allocation
+ * sampling, CPU profiling — has to supply its own. Registrations land on a
+ * global the child reads back; a module-level array would be invisible across
+ * the loader boundary.
+ */
+const registry = () => {
+  globalThis.__a3sTasks ??= []
+  globalThis.__a3sSuite ??= []
+  return globalThis
+}
+
+/** Registers one benchmark. `bench.skip` and `bench.only` register too — the
+ * driver measures allocation and CPU, where skipping is not meaningful. */
+export function bench(name, fn) {
+  const g = registry()
+  g.__a3sTasks.push({ name: String(name), path: [...g.__a3sSuite, String(name)].join(' > '), fn })
+}
+bench.skip = bench
+bench.only = bench
+bench.todo = () => {}
+
+/** Opens a naming scope, so a task's path matches how Vitest names it. */
+export function describe(name, fn) {
+  const g = registry()
+  g.__a3sSuite.push(String(name))
+  try {
+    fn?.()
+  } finally {
+    g.__a3sSuite.pop()
+  }
+}
+describe.skip = describe
+describe.only = describe
+
+export const suite = describe
+
+/** No-ops, so a bench file that also imports these still loads. */
+export const beforeAll = (fn) => fn
+export const afterAll = () => {}
+export const beforeEach = () => {}
+export const afterEach = () => {}
+export const test = () => {}
+export const it = () => {}
+export const expect = () => {
+  throw new Error('expect() is not available inside the autor3search driver')
+}
+export default { bench, describe, suite }

package/src/bench/parse.js

@@ -0,0 +1,120 @@
+/**
+ * Turns Vitest's benchmark JSON report into a BenchSet.
+ *
+ * The format belongs to Vitest, not to us, so this module validates what it
+ * receives and fails LOUDLY on anything it does not recognise. A silently
+ * changed reporter shape that yielded an empty set would surface downstream
+ * as "no benchmarks matched the pattern" — which reads like a user
+ * configuration error and is not one. See test/fixtures/README.md, which
+ * records the real, captured shape (confirmed against Vitest 2.1.9):
+ *
+ *   { files: [ { filepath, groups: [ { fullName, benchmarks: [
+ *       { name, median, mean, hz, samples, ... }, ...
+ *   ] }, ... ] }, ... ] }
+ *
+ * That shape is captured with `vitest bench --run --outputJson=<file>` — NOT
+ * the generic `--reporter=json --outputFile=<file>`, which fails because
+ * `bench` has no built-in reporter registered under the name "json"; see
+ * test/fixtures/README.md for the discrepancy.
+ *
+ * One parse contributes ONE observation per benchmark: the median Vitest
+ * reports for that task. Tinybench computes it over the samples taken inside
+ * a single process invocation, which is exactly the per-round statistic the
+ * scoring core needs — see the spec's section 3.2 for why the individual
+ * samples must never reach the significance test. There is deliberately no
+ * fallback to `mean` or to a median computed over `samples` if `median` is
+ * absent — see `timingMs` below for why.
+ */
+import { BenchSet, UNIT_TIME } from './set.js'
+
+/**
+ * Vitest reports task timings (min/max/mean/median/period/pNN) in
+ * milliseconds; the scoring core uses seconds.
+ */
+const MS_TO_SEC = 1e-3
+
+/**
+ * @param {object|string} payload the reporter's JSON, parsed or raw
+ * @returns {BenchSet}
+ */
+export function parseVitestBench(payload) {
+  const report = typeof payload === 'string' ? parseJson(payload) : payload
+
+  const files = report?.files
+  if (!Array.isArray(files)) {
+    throw new Error(
+      `unrecognised Vitest benchmark report: expected an object with a "files" array, got ` +
+        `${excerpt(report)}. Re-capture test/fixtures/vitest-bench.json and update src/bench/parse.js.`,
+    )
+  }
+
+  const set = new BenchSet()
+  let found = 0
+  for (const file of files) {
+    for (const group of file?.groups ?? []) {
+      for (const task of group?.benchmarks ?? []) {
+        const name = task?.name
+        if (typeof name !== 'string') {
+          throw new Error(`unrecognised Vitest benchmark entry, missing a string name: ${excerpt(task)}`)
+        }
+        const ms = timingMs(task)
+        if (ms === null) {
+          throw new Error(
+            `benchmark ${JSON.stringify(name)} reported no "median", which is the only timing this ` +
+              `parser accepts: ${excerpt(task)}`,
+          )
+        }
+        set.record(taskPath(file, group, name), name, UNIT_TIME, ms * MS_TO_SEC)
+        found++
+      }
+    }
+  }
+
+  if (found === 0) {
+    throw new Error(
+      'the Vitest benchmark report contained no benchmarks — check that the bench files declare ' +
+        'bench() tasks and that the name filter is not excluding all of them',
+    )
+  }
+  return set
+}
+
+/**
+ * The task's timing in milliseconds: tinybench's own reported median.
+ *
+ * Deliberately no fallback. A median-over-`samples` fallback was tried and
+ * removed: Vitest 2.1.9's --outputJson writer hardcodes `samples: []`
+ * regardless of `benchmark.includeSamples`, so that branch was provably dead
+ * code. A mean fallback was removed for a different reason — the mean is a
+ * DIFFERENT estimator, outlier-sensitive in exactly the way benchmark timings
+ * punish, so silently substituting it would change what the score means
+ * without saying so. If a future Vitest stops reporting a median, this throws
+ * and names the benchmark, which is the honest failure.
+ */
+function timingMs(task) {
+  return Number.isFinite(task?.median) ? task.median : null
+}
+
+/**
+ * The full task path, matching how Vitest names a benchmark: the group's
+ * fullName (which already includes the file and any enclosing describes),
+ * then the leaf name.
+ */
+function taskPath(file, group, name) {
+  const prefix = group?.fullName ?? file?.filepath ?? ''
+  return prefix === '' ? name : `${prefix} > ${name}`
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text)
+  } catch (err) {
+    throw new Error(`parse Vitest benchmark report: ${err.message}: ${excerpt(text)}`, { cause: err })
+  }
+}
+
+/** A short, safe excerpt of an unexpected payload, for the error message. */
+function excerpt(value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value)
+  return (text ?? String(value)).slice(0, 300)
+}

package/src/bench/set.js

@@ -0,0 +1,101 @@
+/**
+ * The container for benchmark measurements: every observation of every unit,
+ * for every benchmark, in the order it was observed.
+ *
+ * One measured ROUND contributes exactly one observation per benchmark per
+ * unit. See src/measure.js and the spec's section 3.2 for why the
+ * per-iteration samples inside a round are never recorded here.
+ */
+
+/** The scored unit: seconds per operation. */
+export const UNIT_TIME = 'sec/op'
+
+/**
+ * The hint unit: approximate bytes allocated per operation. Never scored,
+ * and never able to trip the regression guard. See src/adapters/driver.js.
+ */
+export const UNIT_BYTES = 'bytes/op'
+
+export class BenchSet {
+  constructor() {
+    /** @type {Map<string, {name: string, base: string, metrics: Map<string, {unit: string, values: number[]}>}>} */
+    this.series = new Map()
+  }
+
+  /**
+   * Records one observation.
+   *
+   * @param {string} name full task path, e.g. "x.bench.js > parse > big"
+   * @param {string} base leaf benchmark name, what config.benchmarks selects on
+   * @param {string} unit
+   * @param {number} value
+   */
+  record(name, base, unit, value) {
+    let ser = this.series.get(name)
+    if (!ser) {
+      ser = { name, base, metrics: new Map() }
+      this.series.set(name, ser)
+    }
+    let metric = ser.metrics.get(unit)
+    if (!metric) {
+      metric = { unit, values: [] }
+      ser.metrics.set(unit, metric)
+    }
+    metric.values.push(value)
+  }
+
+  /** @returns {string[]} every benchmark name, sorted. */
+  names() {
+    return [...this.series.keys()].sort()
+  }
+
+  /** @returns {string[]} every base name, sorted and deduplicated. */
+  bases() {
+    return [...new Set([...this.series.values()].map((s) => s.base))].sort()
+  }
+
+  /**
+   * @returns {number[] | null} a defensive copy of the observations, so a
+   * caller that sorts or mutates the result cannot corrupt the stored data.
+   */
+  values(name, unit) {
+    const metric = this.series.get(name)?.metrics.get(unit)
+    return metric ? [...metric.values] : null
+  }
+
+  /**
+   * Answers the question `values` is usually asked only to answer, without
+   * its defensive copy.
+   */
+  has(name, unit) {
+    return this.series.get(name)?.metrics.has(unit) ?? false
+  }
+
+  /** Appends every observation in other into this set, preserving order. */
+  add(other) {
+    for (const name of other.names()) {
+      const ser = other.series.get(name)
+      for (const [unit, metric] of ser.metrics) {
+        for (const value of metric.values) this.record(name, ser.base, unit, value)
+      }
+    }
+  }
+
+  /**
+   * Returns a new, independent set holding the subset whose base names appear
+   * in `bases`. An empty list selects everything. Selecting on the base is
+   * what lets a config say "parse" and still match "parse > big".
+   */
+  selectByBase(bases) {
+    const want = bases.length === 0 ? null : new Set(bases)
+    const out = new BenchSet()
+    for (const name of this.names()) {
+      const ser = this.series.get(name)
+      if (want && !want.has(ser.base)) continue
+      for (const [unit, metric] of ser.metrics) {
+        for (const value of metric.values) out.record(name, ser.base, unit, value)
+      }
+    }
+    return out
+  }
+}