@autor3search/javascript 0.2.0

package/src/profile.js

@@ -0,0 +1,100 @@
+/**
+ * Runs the declared benchmarks under V8's CPU and heap profilers and reports
+ * the hot spots.
+ *
+ * The point is to give an agent real data on where time actually goes, rather
+ * than have it guess from reading source. A .cpuprofile is a documented V8
+ * JSON structure, so the hot-spot table is computed here directly — no pprof
+ * equivalent is needed — and the raw files stay on disk for a human to open.
+ */
+import { readFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { runProfiled } from './adapters/driver.js'
+import { benchFiles } from './discover.js'
+import { parseDuration } from './duration.js'
+
+/** Where profiles are written, relative to the repository root. */
+export const PROFILE_DIR = '.autor3search/profiles'
+
+/** V8's synthetic frames: never code an agent can optimize. */
+const SYNTHETIC = new Set(['(root)', '(program)', '(idle)', '(garbage collector)'])
+
+/**
+ * The functions with the most self time in a .cpuprofile.
+ *
+ * Self time is what matters for optimization: a function high in total time
+ * may simply be a caller of the real hot spot. Self time per node is the sum
+ * of the timeDeltas (microseconds) attributed to the samples that name it —
+ * `samples` and `timeDeltas` are parallel arrays, each samples[i] a node id
+ * and timeDeltas[i] the microseconds charged to it.
+ *
+ * @param {object} cpuProfile parsed .cpuprofile JSON
+ * @param {number} limit
+ * @returns {{name: string, file: string, selfMs: number, pct: number}[]}
+ */
+export function topFunctions(cpuProfile, limit) {
+  const byId = new Map((cpuProfile.nodes ?? []).map((n) => [n.id, n]))
+  const selfMicros = new Map()
+
+  const samples = cpuProfile.samples ?? []
+  const deltas = cpuProfile.timeDeltas ?? []
+  for (let i = 0; i < samples.length; i++) {
+    const id = samples[i]
+    selfMicros.set(id, (selfMicros.get(id) ?? 0) + (deltas[i] ?? 0))
+  }
+
+  const entries = [...selfMicros.entries()]
+    .map(([id, micros]) => {
+      const frame = byId.get(id)?.callFrame ?? {}
+      return {
+        name: frame.functionName || '(anonymous)',
+        file: frame.url ? basename(frame.url) : '',
+        selfMs: micros / 1000,
+        micros,
+      }
+    })
+    .filter((entry) => !SYNTHETIC.has(entry.name))
+
+  const total = entries.reduce((a, e) => a + e.micros, 0)
+  if (total === 0) return []
+
+  return entries
+    .map(({ micros, ...rest }) => ({ ...rest, pct: (micros / total) * 100 }))
+    .sort((a, b) => b.selfMs - a.selfMs)
+    .slice(0, limit)
+}
+
+/**
+ * Profiles each bench file in turn, one output directory per file.
+ *
+ * One directory per file rather than one combined profile, because a merged
+ * profile cannot say which benchmark a hot function belongs to — which is the
+ * question the agent is asking.
+ *
+ * @param {string} root
+ * @param {object} cfg loaded run configuration
+ * @param {{iterations?: number, top?: number}} [opts]
+ * @returns {Promise<{file: string, cpuProfile: string, heapProfile: string, top: object[]}[]>}
+ */
+export async function profile(root, cfg, opts = {}) {
+  const files = await benchFiles(root)
+  if (files.length === 0) throw new Error(`no *.bench.* files found in ${root}`)
+
+  const reports = []
+  for (const file of files) {
+    const outDir = join(root, PROFILE_DIR, basename(file).replace(/\.bench\.[^.]+$/, ''))
+    const written = await runProfiled(root, {
+      benchFiles: [file],
+      benchmarks: cfg.benchmarks,
+      outDir,
+      iterations: opts.iterations ?? 2000,
+      timeoutMs: parseDuration(cfg.timeout),
+    })
+    let cpu = {}
+    if (written.cpuProfile) {
+      cpu = JSON.parse(await readFile(written.cpuProfile, 'utf8').catch(() => '{}'))
+    }
+    reports.push({ file, ...written, top: topFunctions(cpu, opts.top ?? 15) })
+  }
+  return reports
+}

package/src/results.js

@@ -0,0 +1,124 @@
+/**
+ * Reads and appends the experiment log.
+ *
+ * results.tsv is HARNESS-OWNED and lives inside the repository so a human can
+ * read it in the morning. It is a log, not part of the metric: nothing here
+ * feeds a verdict.
+ */
+import { appendFile, readFile, stat } from 'node:fs/promises'
+
+/** Log location, relative to the repository root. */
+export const RESULTS_PATH = 'results.tsv'
+
+/**
+ * The first line of every log file. Column order must be kept in step with
+ * COLUMNS, formatRow and parseRow.
+ */
+export const HEADER = 'commit\tscore\tbest_bench_delta\tbytes_delta\tstatus\tdescription'
+
+const COLUMN_COUNT = 6
+
+/**
+ * The longest description written verbatim. `-desc` has no length cap of its
+ * own, and an agent pasting something large (a stack trace, a diff) would
+ * otherwise produce a line long enough to break every future load — after
+ * which `report` fails on the whole file, not just that line, until a human
+ * edits it by hand.
+ */
+export const MAX_DESCRIPTION_LEN = 256
+
+/**
+ * Appends one row, creating the file with a header when needed.
+ *
+ * @param {string} path
+ * @param {{commit: string, score: number, bestBenchDelta: number, bytesDelta: number, status: string, description: string}} row
+ */
+export async function appendRow(path, row) {
+  const exists = await stat(path).then(
+    () => true,
+    () => false,
+  )
+  const line = [
+    clean(row.commit),
+    format(row.score, 4),
+    format(row.bestBenchDelta, 2),
+    format(row.bytesDelta, 2),
+    clean(row.status),
+    truncate(clean(row.description)),
+  ].join('\t')
+  await appendFile(path, `${exists ? '' : `${HEADER}\n`}${line}\n`, 'utf8')
+}
+
+/**
+ * Reads every row written by appendRow. A missing file is not an error — it
+ * is a run that has not recorded an experiment yet.
+ *
+ * @param {string} path
+ * @returns {Promise<object[]>}
+ */
+export async function loadRows(path) {
+  let text
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return []
+    throw new Error(`read ${path}: ${err.message}`, { cause: err })
+  }
+
+  const rows = []
+  const lines = text.split('\n')
+  for (const [i, line] of lines.entries()) {
+    if (line.trim() === '') continue
+    if (i === 0 && line === HEADER) continue
+    rows.push(parseRow(path, i + 1, line))
+  }
+  return rows
+}
+
+function parseRow(path, lineNo, line) {
+  const parts = line.split('\t')
+  if (parts.length !== COLUMN_COUNT) {
+    throw new Error(`${path}:${lineNo}: expected ${COLUMN_COUNT} columns, got ${parts.length}`)
+  }
+  return {
+    commit: parts[0],
+    score: number(path, lineNo, 'score', parts[1]),
+    bestBenchDelta: number(path, lineNo, 'best_bench_delta', parts[2]),
+    bytesDelta: number(path, lineNo, 'bytes_delta', parts[3]),
+    status: parts[4],
+    description: parts[5],
+  }
+}
+
+function number(path, lineNo, field, text) {
+  const n = Number(text)
+  if (text.trim() === '' || Number.isNaN(n)) {
+    throw new Error(`${path}:${lineNo}: ${field} ${JSON.stringify(text)} is not a number`)
+  }
+  return n
+}
+
+/** Makes a field safe for a tab-separated single-line record. */
+function clean(s) {
+  return String(s ?? '')
+    .replace(/[\t\r\n]/g, ' ')
+    .trim()
+}
+
+/**
+ * Caps s at MAX_DESCRIPTION_LEN characters. Counting characters rather than
+ * bytes means a multi-byte character is never split in half.
+ */
+function truncate(s) {
+  const chars = [...s]
+  return chars.length <= MAX_DESCRIPTION_LEN ? s : `${chars.slice(0, MAX_DESCRIPTION_LEN).join('')}...`
+}
+
+/**
+ * Formats a number with fixed precision. A non-finite value (a gate failure
+ * has no score) is written as zero rather than "NaN", which loadRows would
+ * refuse to read back.
+ */
+function format(n, digits) {
+  return (Number.isFinite(n) ? n : 0).toFixed(digits)
+}

package/src/runner.js

@@ -0,0 +1,198 @@
+/**
+ * Executes subprocesses with a timeout, captured output and group-kill
+ * semantics.
+ *
+ * Every child is spawned into its OWN PROCESS GROUP (detached: true) and
+ * killed by group. This is not a nicety: `vitest` forks worker processes to
+ * run benchmarks, so a vitest killed without taking its group with it leaves
+ * those workers running — burning CPU, and corrupting every later measurement
+ * on the machine, including ones belonging to other runs.
+ */
+import { spawn } from 'node:child_process'
+import { formatDuration } from './duration.js'
+
+/** Bytes retained per stream before output is truncated. */
+export const OUTPUT_CAP = 4 * 1024 * 1024
+
+/** Grace period between SIGTERM and SIGKILL when tearing a group down. */
+const KILL_GRACE_MS = 10_000
+
+export class Runner {
+  /**
+   * @param {string} dir working directory for every command
+   * @param {number} timeoutMs bound on each command
+   * @param {{write(s: string): void} | null} [log] receives the command line and its output
+   * @param {{killGraceMs?: number}} [opts] killGraceMs shortens the SIGTERM->SIGKILL
+   *   grace period; the default is right for production, and tests override it so the
+   *   escalation path can be covered without a ten-second wait.
+   */
+  constructor(dir, timeoutMs, log = null, opts = {}) {
+    this.dir = dir
+    this.timeoutMs = timeoutMs
+    this.log = log
+    this.killGraceMs = opts.killGraceMs ?? KILL_GRACE_MS
+  }
+
+  /**
+   * Runs one command to completion.
+   *
+   * A non-zero exit is a RESULT, not an exception — callers turn it into a
+   * verdict. Only a command that could not be started at all throws.
+   *
+   * @param {string} command
+   * @param {string[]} args
+   * @param {{env?: NodeJS.ProcessEnv, cwd?: string, signal?: AbortSignal}} [opts]
+   * @returns {Promise<Result>}
+   */
+  run(command, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+      const started = Date.now()
+      const child = spawn(command, args, {
+        cwd: opts.cwd ?? this.dir,
+        env: opts.env ?? process.env,
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+
+      const stdout = new Capped(OUTPUT_CAP)
+      const stderr = new Capped(OUTPUT_CAP)
+      child.stdout.on('data', (chunk) => stdout.write(chunk))
+      child.stderr.on('data', (chunk) => stderr.write(chunk))
+
+      let timedOut = false
+      let killTimer = null
+      const timer = setTimeout(() => {
+        timedOut = true
+        killGroup(child.pid, 'SIGTERM')
+        // `??=` guards against the abort path having already scheduled the
+        // escalation (both a timeout and an abort can fire for the same
+        // child); reuse that timer rather than orphaning it.
+        killTimer ??= setTimeout(() => killGroup(child.pid, 'SIGKILL'), this.killGraceMs)
+        killTimer.unref()
+      }, this.timeoutMs)
+      timer.unref()
+
+      const onAbort = () => {
+        timedOut = true
+        killGroup(child.pid, 'SIGTERM')
+        // Escalate exactly as the timeout path does. Without this, a child
+        // that IGNORES SIGTERM survives the abort until the unrelated timeout
+        // timer happens to fire — measured at 12.9s with a 3s timeout, and up
+        // to the full 15m default in a real run. An abort is meant to be the
+        // fast path, so it must not depend on the slow one as its backstop.
+        killTimer ??= setTimeout(() => killGroup(child.pid, 'SIGKILL'), this.killGraceMs)
+        killTimer.unref()
+      }
+      opts.signal?.addEventListener('abort', onAbort, { once: true })
+
+      const cleanup = () => {
+        clearTimeout(timer)
+        if (killTimer) clearTimeout(killTimer)
+        opts.signal?.removeEventListener('abort', onAbort)
+      }
+
+      child.on('error', (err) => {
+        cleanup()
+        reject(new Error(`run ${command} ${args.join(' ')}: ${err.message}`, { cause: err }))
+      })
+
+      child.on('close', (code, signal) => {
+        cleanup()
+        const result = new Result({
+          argv: [command, ...args],
+          stdout: stdout.text(),
+          stderr: stderr.text(),
+          // A process killed by a signal has a null exit code; report it as
+          // non-zero so ok() is false rather than accidentally true.
+          exitCode: code ?? (signal ? -1 : 0),
+          timedOut,
+          durationMs: Date.now() - started,
+        })
+        this.#writeLog(result)
+        resolve(result)
+      })
+    })
+  }
+
+  #writeLog(result) {
+    if (!this.log) return
+    this.log.write(
+      `\n$ ${result.argv.join(' ')}\n(dir=${this.dir} exit=${result.exitCode} ` +
+        `timedOut=${result.timedOut} took=${formatDuration(result.durationMs)})\n`,
+    )
+    this.log.write(result.stdout)
+    this.log.write(result.stderr)
+  }
+}
+
+/** The outcome of one subprocess. */
+export class Result {
+  constructor(fields) {
+    Object.assign(this, fields)
+  }
+
+  /** Reports a clean, in-time run. */
+  ok() {
+    return this.exitCode === 0 && !this.timedOut
+  }
+
+  /**
+   * The last n lines of stderr, falling back to stdout when stderr is empty.
+   * Used to put an actionable excerpt in a FAIL message without flooding an
+   * unattended agent's context with the whole transcript.
+   */
+  tail(n) {
+    const source = this.stderr.trim() === '' ? this.stdout : this.stderr
+    const lines = source.replace(/\n+$/, '').split('\n')
+    return lines.slice(Math.max(0, lines.length - Math.max(0, n))).join('\n')
+  }
+}
+
+/** Retains at most `limit` bytes, then drops the rest and records that. */
+class Capped {
+  constructor(limit) {
+    this.limit = limit
+    this.chunks = []
+    this.length = 0
+    this.truncated = false
+  }
+
+  write(chunk) {
+    const remaining = this.limit - this.length
+    if (remaining <= 0) {
+      this.truncated = true
+      return
+    }
+    if (chunk.length > remaining) {
+      this.chunks.push(chunk.subarray(0, remaining))
+      this.length = this.limit
+      this.truncated = true
+      return
+    }
+    this.chunks.push(chunk)
+    this.length += chunk.length
+  }
+
+  text() {
+    const text = Buffer.concat(this.chunks).toString('utf8')
+    return this.truncated ? `${text}\n[output truncated at 4MB]\n` : text
+  }
+}
+
+/**
+ * Signals a child's whole process group. A negative pid addresses the group.
+ * Failures are swallowed: the group is already gone in the common case, and a
+ * teardown that throws would mask the real result being reported.
+ */
+function killGroup(pid, signal) {
+  if (!pid) return
+  try {
+    process.kill(-pid, signal)
+  } catch {
+    try {
+      process.kill(pid, signal)
+    } catch {
+      // Already exited.
+    }
+  }
+}

package/src/scope.js

@@ -0,0 +1,92 @@
+/**
+ * Decides which files an agent is allowed to modify.
+ *
+ * Patterns are globs ("src/**", "lib/**\/*.js") — the shape a JavaScript
+ * project already expects, and the only shape accepted. A leading "./" is
+ * tolerated; anything else is handed to picomatch verbatim, so a pattern
+ * this harness does not understand matches nothing rather than more.
+ */
+import picomatch from 'picomatch'
+
+/**
+ * Compiles scope patterns into a matcher over repository-relative paths.
+ *
+ * A blank or whitespace-only pattern is SKIPPED rather than treated as the
+ * repository root, so a stray empty entry in a config list matches nothing
+ * instead of silently granting root-level access.
+ *
+ * @param {string[]} patterns
+ * @returns {{ match(rel: string): boolean }}
+ */
+export function createMatcher(patterns) {
+  if (patterns != null && !Array.isArray(patterns)) {
+    // A bare string would be iterated CHARACTER BY CHARACTER by the loop
+    // below, silently degrading "**" into two one-character patterns. A
+    // security gate must fail closed and loudly, not quietly narrow itself.
+    throw new TypeError(`scope patterns must be an array, got ${typeof patterns}`)
+  }
+
+  const compiled = []
+  for (const raw of patterns ?? []) {
+    if (typeof raw !== 'string') continue
+    const trimmed = raw.trim()
+    if (trimmed === '') continue
+    // dot is deliberately LEFT OFF. With `dot: true`, the default "**" would
+    // also match dot-files and dot-directories, so an agent scoped to the
+    // whole repository could write .npmrc (redirecting the package registry)
+    // or .github/workflows/*.yml (arbitrary CI execution) and have the change
+    // accepted. A user who genuinely wants one in scope names it
+    // explicitly — picomatch still matches a literal dot written in the
+    // pattern, so `scope: [".github/**"]` works while `**` does not reach it.
+    compiled.push(picomatch(normalisePattern(trimmed)))
+  }
+
+  return {
+    match(rel) {
+      const path = normalisePath(rel)
+      if (path === null) return false
+      return compiled.some((isMatch) => isMatch(path))
+    },
+  }
+}
+
+/**
+ * Rewrites a pattern into the glob picomatch will see: normalises backslashes
+ * and strips a leading "./". Nothing else is rewritten — a pattern means what
+ * picomatch says it means, with no dialect of this project's own on top.
+ */
+function normalisePattern(p) {
+  return p.replace(/\\/g, '/').replace(/^\.\//, '')
+}
+
+/**
+ * Normalises a candidate path, returning null for anything that can never be
+ * in scope no matter what the patterns say.
+ *
+ * The null cases have to be rejected EXPLICITLY, because they would otherwise
+ * be admitted: "**" matches every string handed to it, so the one pattern
+ * meaning "the whole repository" would also be the one meaning "anywhere on
+ * the disk". Nothing produces such a path today — callers pass the output of
+ * `git diff --name-only` and `git ls-files`, which are always root-relative —
+ * so this is the gate refusing to depend on that staying true.
+ */
+function normalisePath(rel) {
+  if (typeof rel !== 'string' || rel === '') return null
+  const slashed = rel.replace(/\\/g, '/')
+  if (slashed.startsWith('/') || /^[A-Za-z]:\//.test(slashed)) return null
+
+  const parts = []
+  for (const part of slashed.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') {
+      // A ".." that cannot be cancelled by a preceding segment climbs out of
+      // the repository root.
+      if (parts.length === 0) return null
+      parts.pop()
+      continue
+    }
+    parts.push(part)
+  }
+  if (parts.length === 0) return null
+  return parts.join('/')
+}