seer-mcp 0.1.0

package/tests/parallel-recovery.ts

@@ -0,0 +1,241 @@
+/**
+ * Parallel parser stress & recovery tests (Step 5 of parallel parsing).
+ *
+ * Exercises the failure paths the audit flagged:
+ *   - Per-job attempt limit: a "poison" file that crashes every worker it
+ *     touches must be marked parse-error after `maxAttempts` worker deaths
+ *     and the dispatch must complete (not hang).
+ *   - Crashes are contained: a single sentinel-matched file inside a healthy
+ *     workspace produces exactly one parse-error; every other file is parsed
+ *     correctly and indexed by the indexer integration test.
+ *   - Edge cases:
+ *       - empty workspace runs cleanly under `parallel: true`
+ *       - one-file workspace with jobs > 1 doesn't deadlock
+ *       - `maxFileBytes` is honored (worker reports too-large; row pruned)
+ *
+ * The crash is injected via `SEER_WORKER_TEST_CRASH_ON` — when set, the worker
+ * `process.exit(13)`s on any parse job whose `abs` contains that substring.
+ * Production never sets the variable.
+ *
+ * Run with: npm run test:parallel-recovery
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { Indexer } from '../src/indexer/index';
+import { Store } from '../src/db/store';
+import { WorkerPool, WorkItem, PoolResult } from '../src/parser/workerpool';
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) {
+    console.log(`  ✓ ${message}`);
+    passed++;
+  } else {
+    console.error(`  ✗ ${message}`);
+    failed++;
+  }
+}
+
+function tmpDb(label: string): string {
+  return path.join(os.tmpdir(), `seer-parallel-recovery-${label}-${Date.now()}.db`);
+}
+
+// ── Run ─────────────────────────────────────────────────────────────────────
+
+async function run(): Promise<void> {
+  console.log('\nParallel Recovery Test (Step 5)');
+  console.log('=================================\n');
+
+  // ── 1. Empty workspace ───────────────────────────────────────────────────
+  console.log('── Empty workspace runs cleanly under parallel=true ──');
+  {
+    const root = path.join(os.tmpdir(), `seer-parallel-empty-${Date.now()}`);
+    fs.mkdirSync(root, { recursive: true });
+    const db = tmpDb('empty');
+    const store = new Store(db);
+    const indexer = new Indexer(store);
+    const res = await indexer.indexDirectory(root, { quiet: true, parallel: true });
+    store.close();
+    assert(res.filesIndexed === 0, 'empty workspace: filesIndexed=0');
+    assert(res.symbols === 0, 'empty workspace: symbols=0');
+    assert(res.pagerankRecomputed === false, 'empty workspace: no PageRank recompute');
+    fs.rmSync(root, { recursive: true, force: true });
+    try { fs.unlinkSync(db); } catch { /* */ }
+  }
+
+  // ── 2. Single-file workspace with jobs=8 doesn't deadlock ────────────────
+  console.log('\n── Single-file workspace, jobs=8 ──');
+  {
+    const root = path.join(os.tmpdir(), `seer-parallel-single-${Date.now()}`);
+    fs.mkdirSync(root, { recursive: true });
+    fs.copyFileSync(path.join(FIXTURES_DIR, 'sample.ts'), path.join(root, 'sample.ts'));
+    const db = tmpDb('single');
+    const store = new Store(db);
+    const indexer = new Indexer(store);
+    const res = await indexer.indexDirectory(root, { quiet: true, parallel: true, jobs: 8 });
+    store.close();
+    assert(res.filesIndexed === 1, 'single file: filesIndexed=1');
+    assert(res.symbols > 0, 'single file: symbols extracted');
+    fs.rmSync(root, { recursive: true, force: true });
+    try { fs.unlinkSync(db); } catch { /* */ }
+  }
+
+  // ── 3. maxFileBytes enforcement ──────────────────────────────────────────
+  console.log('\n── maxFileBytes enforcement (parallel) ──');
+  {
+    const root = path.join(os.tmpdir(), `seer-parallel-toolarge-${Date.now()}`);
+    fs.mkdirSync(root, { recursive: true });
+    fs.copyFileSync(path.join(FIXTURES_DIR, 'sample.ts'), path.join(root, 'small.ts'));
+    // Build a 50 KB file that exceeds the cap.
+    fs.writeFileSync(path.join(root, 'big.ts'), 'const x = 1;\n'.repeat(5000));
+    const db = tmpDb('toolarge');
+    const store = new Store(db);
+    const indexer = new Indexer(store);
+    const res = await indexer.indexDirectory(root, {
+      quiet: true, parallel: true, jobs: 2, maxFileBytes: 8192,
+    });
+    store.close();
+    assert(res.filesSkippedTooLarge === 1, `one file skipped as too-large (got ${res.filesSkippedTooLarge})`);
+    assert(res.filesIndexed === 1, `the other file was indexed (got ${res.filesIndexed})`);
+    fs.rmSync(root, { recursive: true, force: true });
+    try { fs.unlinkSync(db); } catch { /* */ }
+  }
+
+  // ── 4. Poison job hits attempt limit → parse-error (pool layer) ──────────
+  console.log('\n── Poison job hits maxAttempts → parse-error ──');
+  {
+    process.env.SEER_WORKER_TEST_CRASH_ON = 'POISON_SENTINEL';
+    try {
+      const pool = new WorkerPool({ jobs: 2, maxAttempts: 3 });
+      await pool.ready();
+      const goodPath = path.join(FIXTURES_DIR, 'sample.ts');
+      const poisonPath = path.join(os.tmpdir(), `POISON_SENTINEL-${Date.now()}.ts`);
+      // The poison file doesn't actually need to exist on disk — the worker
+      // crashes BEFORE it tries to read.
+      const items: WorkItem[] = [
+        { abs: goodPath,   lang: 'typescript', expectedHash: null, maxFileBytes: 0 },
+        { abs: poisonPath, lang: 'typescript', expectedHash: null, maxFileBytes: 0 },
+        { abs: goodPath,   lang: 'typescript', expectedHash: null, maxFileBytes: 0 },
+      ];
+      const results: PoolResult[] = [];
+      await pool.dispatch(items, (seq, result) => { results[seq] = result; });
+      assert(results.length === 3, 'all 3 items delivered (no hang)');
+      assert(results[0].kind === 'parsed', 'good file 0 parsed');
+      assert(results[1].kind === 'parse-error', `poison file synthesized parse-error (got ${results[1]?.kind})`);
+      assert(results[2].kind === 'parsed', 'good file 2 parsed (pool recovered after the crash)');
+      await pool.shutdown();
+    } finally {
+      delete process.env.SEER_WORKER_TEST_CRASH_ON;
+    }
+  }
+
+  // ── 5. Many crashes don't deadlock the pool ──────────────────────────────
+  console.log('\n── Many poison jobs interleaved with healthy ones ──');
+  {
+    process.env.SEER_WORKER_TEST_CRASH_ON = 'POISON_MANY';
+    try {
+      const pool = new WorkerPool({ jobs: 4, maxAttempts: 2 });
+      await pool.ready();
+      const goodPath = path.join(FIXTURES_DIR, 'sample.ts');
+      const items: WorkItem[] = [];
+      for (let i = 0; i < 12; i++) {
+        const isPoison = i % 3 === 0; // 4 of 12 are poison
+        items.push({
+          abs: isPoison
+            ? path.join(os.tmpdir(), `POISON_MANY-${i}.ts`)
+            : goodPath,
+          lang: 'typescript', expectedHash: null, maxFileBytes: 0,
+        });
+      }
+      const kinds: string[] = [];
+      await pool.dispatch(items, (seq, result) => { kinds[seq] = result.kind; });
+      assert(kinds.length === 12, '12 items delivered (no hang under 4 poison + 8 healthy)');
+      const goodCount     = kinds.filter(k => k === 'parsed').length;
+      const errorCount    = kinds.filter(k => k === 'parse-error').length;
+      assert(goodCount === 8, `8 healthy parses (got ${goodCount})`);
+      assert(errorCount === 4, `4 poison parse-errors (got ${errorCount})`);
+      await pool.shutdown();
+    } finally {
+      delete process.env.SEER_WORKER_TEST_CRASH_ON;
+    }
+  }
+
+  // ── 6. Indexer integration: parallel run with one poison file ────────────
+  console.log('\n── Indexer integration: worker WASM reset count is aggregated ──');
+  {
+    const root = path.join(os.tmpdir(), `seer-parallel-reset-aggregation-${Date.now()}`);
+    fs.mkdirSync(root, { recursive: true });
+    fs.copyFileSync(path.join(FIXTURES_DIR, 'sample.ts'), path.join(root, 'FAKE_WASM_RESET_INDEXER.ts'));
+    process.env.SEER_WORKER_TEST_FAKE_WASM_RESET_ON = 'FAKE_WASM_RESET_INDEXER';
+    try {
+      const db = tmpDb('reset-aggregation');
+      const store = new Store(db);
+      const indexer = new Indexer(store);
+      const res = await indexer.indexDirectory(root, {
+        quiet: true, parallel: true, jobs: 1,
+      });
+      store.close();
+      assert(res.filesIndexed === 1, `reset aggregation fixture indexed (got ${res.filesIndexed})`);
+      assert(res.wasmResets === 1, `IndexResult aggregates worker-local wasm resets (got ${res.wasmResets})`);
+      try { fs.unlinkSync(db); } catch { /* */ }
+    } finally {
+      delete process.env.SEER_WORKER_TEST_FAKE_WASM_RESET_ON;
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  // ── 7. Indexer integration: parallel run with one poison file ────────────
+  console.log('\n── Indexer integration: parallel + one poison file ──');
+  {
+    const root = path.join(os.tmpdir(), `seer-parallel-indexer-recovery-${Date.now()}`);
+    fs.mkdirSync(root, { recursive: true });
+    // Stage a couple of healthy fixtures plus the poison file.
+    for (const f of ['sample.ts', 'sample.py']) {
+      fs.copyFileSync(path.join(FIXTURES_DIR, f), path.join(root, f));
+    }
+    // The poison file MUST exist on disk so discoverFiles picks it up; the
+    // worker exits before opening it though, so content is irrelevant.
+    fs.writeFileSync(path.join(root, 'POISON_INDEXER.ts'), 'const x = 1;\n');
+    process.env.SEER_WORKER_TEST_CRASH_ON = 'POISON_INDEXER';
+    try {
+      const db = tmpDb('indexer-recovery');
+      const store = new Store(db);
+      const indexer = new Indexer(store);
+      const res = await indexer.indexDirectory(root, {
+        quiet: true, parallel: true, jobs: 2,
+      });
+      store.close();
+      assert(res.filesIndexed === 2, `2 healthy files indexed (got ${res.filesIndexed})`);
+      assert(res.filesParseError === 1, `1 file reported as parse-error (got ${res.filesParseError})`);
+      // The poison file's row should still exist (upsert with hash+lines was
+      // synthesized from the parse-error result), so it's not pruned.
+      const store2 = new Store(db);
+      const filesNow = store2.listFiles().map(f => f.relPath);
+      store2.close();
+      assert(filesNow.includes('POISON_INDEXER.ts'), 'poison file row preserved (not pruned)');
+      try { fs.unlinkSync(db); } catch { /* */ }
+    } finally {
+      delete process.env.SEER_WORKER_TEST_CRASH_ON;
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  console.log('\n══════════════════════════════════════════════════════════════');
+  console.log(`  Parallel-recovery results: ${passed} passed, ${failed} failed`);
+  if (failed > 0) {
+    console.error('\n  PARALLEL-RECOVERY TESTS FAILED\n');
+    process.exit(1);
+  } else {
+    console.log('\n  All parallel-recovery tests passed! ✓\n');
+  }
+}
+
+run().catch(err => {
+  console.error('parallel-recovery test threw:', err);
+  process.exit(1);
+});

package/tests/perf-callers.ts

@@ -0,0 +1,145 @@
+/**
+ * Perf probe for the findCallers() fix.
+ *
+ * Targets the case the user flagged: Unreal's `Num` with ~127k callers, which
+ * previously took ~745ms for the direct Store query and ~1.65s through the CLI.
+ * The <50ms target only makes sense with a LIMIT (the CLI's display window) —
+ * unbounded fetch of 127k rows is dominated by JS object allocation and cannot
+ * realistically hit 50ms regardless of SQL plan.
+ *
+ * Run:  npx tsx tests/perf-callers.ts
+ */
+import path from 'path';
+import fs from 'fs';
+import { Store } from '../src/db/store';
+
+const DB_PATH = path.resolve(__dirname, 'outputs/dbs/unreal.db');
+
+interface ProbeResult {
+  symbol: string;
+  countMs: number;
+  limit40Ms: number;
+  unboundedMs: number;
+  total: number;
+  limit40Rows: number;
+  unboundedRows: number;
+}
+
+function timeMs(fn: () => void): number {
+  const start = process.hrtime.bigint();
+  fn();
+  return Number(process.hrtime.bigint() - start) / 1e6;
+}
+
+function bestOf(n: number, fn: () => number): number {
+  let best = Infinity;
+  for (let i = 0; i < n; i++) best = Math.min(best, fn());
+  return best;
+}
+
+function probeOne(store: Store, symbol: string, runUnbounded: boolean): ProbeResult {
+  // Warm the prepared-statement cache once
+  store.countCallers(symbol);
+  store.findCallers(symbol, 40);
+
+  const total = store.countCallers(symbol);
+  const countMs = bestOf(5, () => timeMs(() => store.countCallers(symbol)));
+  let limit40Rows = 0;
+  const limit40Ms = bestOf(5, () => timeMs(() => {
+    limit40Rows = store.findCallers(symbol, 40).length;
+  }));
+
+  let unboundedMs = 0;
+  let unboundedRows = total;
+  if (runUnbounded) {
+    unboundedMs = bestOf(2, () => timeMs(() => {
+      unboundedRows = store.findCallers(symbol).length;
+    }));
+  }
+
+  return { symbol, countMs, limit40Ms, unboundedMs, total, limit40Rows, unboundedRows };
+}
+
+function main(): void {
+  if (!fs.existsSync(DB_PATH)) {
+    console.error(`No Unreal DB at ${DB_PATH}.`);
+    console.error('Run `npm run scale-test -- --only unreal` first.');
+    process.exit(1);
+  }
+
+  const store = new Store(DB_PATH);
+
+  // Discover the highest-fan-in symbols in the DB instead of hard-coding
+  // names — keeps the probe meaningful even if upstream Unreal API drifts.
+  const sym = (store as unknown as { ['db']: { prepare: (s: string) => { all: (...a: unknown[]) => unknown[] } } }).db;
+  type Row = Record<string, unknown>;
+  const top = (sym.prepare(
+    'SELECT to_name AS name, COUNT(*) AS c FROM edges GROUP BY to_name ORDER BY c DESC LIMIT 5'
+  ).all() as Row[]).map(r => ({ name: String(r.name), c: Number(r.c) }));
+
+  console.log('\nPerf probe — Unreal high-fan-in findCallers');
+  console.log('────────────────────────────────────────────');
+  console.log(`DB: ${DB_PATH}\n`);
+  console.log('Top 5 callees by fan-in:');
+  for (const t of top) console.log(`  ${t.name.padEnd(28)} ${t.c.toLocaleString()} callers`);
+  console.log('');
+
+  const results: ProbeResult[] = [];
+  for (const t of top) {
+    const heavy = t.c >= 10_000;
+    results.push(probeOne(store, t.name, !heavy /* skip unbounded on huge fan-in */));
+  }
+
+  // Also probe `Num` explicitly if present (the user-cited symbol).
+  if (!results.some(r => r.symbol === 'Num')) {
+    const c = store.countCallers('Num');
+    if (c > 0) results.push(probeOne(store, 'Num', c < 10_000));
+  }
+
+  console.log('Results (best-of, ms):');
+  console.log(`  ${'symbol'.padEnd(28)} ${'count'.padStart(10)} ${'countMs'.padStart(10)} ${'limit40Ms'.padStart(12)} ${'unboundedMs'.padStart(13)}`);
+  console.log('  ' + '─'.repeat(75));
+  for (const r of results) {
+    const unbStr = r.unboundedMs > 0
+      ? r.unboundedMs.toFixed(2)
+      : 'skipped';
+    console.log(
+      `  ${r.symbol.padEnd(28)} ${r.total.toLocaleString().padStart(10)} ${r.countMs.toFixed(2).padStart(10)} ${r.limit40Ms.toFixed(2).padStart(12)} ${String(unbStr).padStart(13)}`,
+    );
+  }
+
+  // User-facing target: <50ms for the CLI's query roundtrip on the worst
+  // symbol. The CLI runs `countCallers + findCallers(symbol, limit)`, so we
+  // judge against the combined budget. countCallers alone is index-only but
+  // still scans matching B-tree leaves, so on the heaviest symbols it costs
+  // ~10ms — that's why we don't split it into a separate <5ms target.
+  const worstLimited = Math.max(...results.map(r => r.limit40Ms));
+  const worstCount = Math.max(...results.map(r => r.countMs));
+  const worstCombined = Math.max(...results.map(r => r.countMs + r.limit40Ms));
+  console.log('');
+  console.log(`Worst limit40Ms:   ${worstLimited.toFixed(2)} ms`);
+  console.log(`Worst countMs:     ${worstCount.toFixed(2)} ms (informational)`);
+  console.log(`Worst combined:    ${worstCombined.toFixed(2)} ms (target <50ms — full CLI query roundtrip)`);
+
+  const ok = worstCombined < 50;
+
+  // Persist for later cross-checks
+  const outPath = path.resolve(__dirname, `outputs/perf-callers-${Date.now()}.json`);
+  fs.writeFileSync(outPath, JSON.stringify({
+    db: DB_PATH,
+    timestamp: new Date().toISOString(),
+    targets: { combinedMsMax: 50 },
+    results,
+  }, null, 2));
+  console.log(`\nSaved: ${path.relative(path.resolve(__dirname, '..'), outPath)}`);
+
+  store.close();
+
+  if (!ok) {
+    console.error('\nPerf targets MISSED.');
+    process.exit(1);
+  }
+  console.log('\nPerf targets met.\n');
+}
+
+main();

package/tests/query-parity.ts

@@ -0,0 +1,184 @@
+/**
+ * Tree-Sitter query candidate-collection parity test.
+ *
+ * Parses each fixture twice — once with the query-assisted candidate walker
+ * (default) and once with the baseline walker forced — and asserts the two
+ * extractions are identical for every category: definitions, references,
+ * imports, routes, config keys.
+ *
+ * If parity ever fails, the candidate node-type list is missing a type that
+ * the corresponding tryExtract* handler accepts.
+ *
+ * Run with: npx tsx tests/query-parity.ts  (also runs from `npm test`)
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { parseFile, setForceBaselineWalker } from '../src/parser/index';
+import type { FileExtraction } from '../src/types';
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) {
+    console.log(`  ✓ ${message}`);
+    passed++;
+  } else {
+    console.error(`  ✗ ${message}`);
+    failed++;
+  }
+}
+
+function canonicalize(extraction: FileExtraction): string {
+  // Sort each list deterministically so order-of-traversal differences (which
+  // there shouldn't be — but defensively) don't fail the comparison.
+  const defs = [...extraction.definitions].sort((a, b) =>
+    (a.lineStart - b.lineStart) ||
+    (a.name.localeCompare(b.name)) ||
+    ((a.qualifiedName ?? '').localeCompare(b.qualifiedName ?? ''))
+  );
+  const refs = [...extraction.references].sort((a, b) =>
+    (a.line - b.line) || a.calleeName.localeCompare(b.calleeName) || a.callerName.localeCompare(b.callerName)
+  );
+  const imports = [...extraction.importedModules].sort();
+  const routes = [...(extraction.routes ?? [])].sort((a, b) =>
+    (a.line - b.line) || a.method.localeCompare(b.method) || a.path.localeCompare(b.path)
+  );
+  const configKeys = [...(extraction.configKeys ?? [])].sort((a, b) =>
+    (a.line - b.line) || a.key.localeCompare(b.key)
+  );
+  return JSON.stringify({
+    language: extraction.language,
+    definitions: defs.map(d => ({
+      name: d.name,
+      qualifiedName: d.qualifiedName,
+      kind: d.kind,
+      lineStart: d.lineStart,
+      lineEnd: d.lineEnd,
+      cyclomatic: d.cyclomatic ?? null,
+      cognitive: d.cognitive ?? null,
+      maxNesting: d.maxNesting ?? null,
+      loc: d.loc ?? null,
+    })),
+    references: refs.map(r => ({
+      calleeName: r.calleeName,
+      callerName: r.callerName,
+      kind: r.kind,
+      line: r.line,
+    })),
+    imports,
+    routes: routes.map(r => ({
+      method: r.method,
+      path: r.path,
+      framework: r.framework,
+      handlerName: r.handlerName ?? null,
+      line: r.line,
+    })),
+    configKeys: configKeys.map(c => ({
+      key: c.key,
+      source: c.source,
+      callerName: c.callerName ?? '',
+      line: c.line,
+    })),
+  }, null, 2);
+}
+
+async function compareFile(filePath: string): Promise<void> {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const rel = path.relative(FIXTURES_DIR, filePath);
+
+  setForceBaselineWalker(false);
+  const queryAssisted = await parseFile(content, filePath);
+
+  setForceBaselineWalker(true);
+  const baseline = await parseFile(content, filePath);
+  setForceBaselineWalker(false);
+
+  if (!queryAssisted && !baseline) {
+    // Both null (probably an unsupported extension) — skip without counting.
+    return;
+  }
+
+  assert(
+    queryAssisted !== null && baseline !== null,
+    `[${rel}] both walkers succeed`,
+  );
+  if (!queryAssisted || !baseline) return;
+
+  const queryStr = canonicalize(queryAssisted);
+  const baselineStr = canonicalize(baseline);
+
+  const equal = queryStr === baselineStr;
+  assert(equal, `[${rel}] query-assisted ≡ baseline (${queryAssisted.definitions.length} defs, ${queryAssisted.references.length} refs, ${queryAssisted.importedModules.length} imports, ${queryAssisted.routes?.length ?? 0} routes, ${queryAssisted.configKeys?.length ?? 0} configKeys)`);
+  if (!equal) {
+    // Locate the first differing section for a useful failure message.
+    const diff = firstDiff(queryStr, baselineStr);
+    console.error(`    First difference at offset ${diff.offset}:`);
+    console.error(`      query:    ${diff.queryLine}`);
+    console.error(`      baseline: ${diff.baselineLine}`);
+  }
+}
+
+function firstDiff(a: string, b: string): { offset: number; queryLine: string; baselineLine: string } {
+  let off = 0;
+  while (off < a.length && off < b.length && a[off] === b[off]) off++;
+  const lineStart = Math.max(0, a.lastIndexOf('\n', off));
+  const aEnd = a.indexOf('\n', off);
+  const bEnd = b.indexOf('\n', off);
+  return {
+    offset: off,
+    queryLine: a.slice(lineStart, aEnd === -1 ? a.length : aEnd).trim(),
+    baselineLine: b.slice(lineStart, bEnd === -1 ? b.length : bEnd).trim(),
+  };
+}
+
+async function walkFixtures(dir: string, out: string[]): Promise<void> {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkFixtures(p, out);
+    } else if (entry.isFile()) {
+      out.push(p);
+    }
+  }
+}
+
+async function run(): Promise<void> {
+  console.log('\nSeer Query-Assisted Walker Parity Test');
+  console.log('========================================\n');
+
+  const all: string[] = [];
+  await walkFixtures(FIXTURES_DIR, all);
+  // Also include the Track-C/D fixtures so we exercise the route + configKey
+  // extractors against the same parity check.
+  const trackcdDir = path.join(__dirname, 'fixtures-trackcd');
+  if (fs.existsSync(trackcdDir)) await walkFixtures(trackcdDir, all);
+
+  for (const f of all) {
+    const ext = path.extname(f).toLowerCase();
+    if (!['.py', '.pyw', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+          '.go', '.java', '.rs', '.c', '.cpp', '.cc', '.cxx', '.c++',
+          '.hpp', '.hh', '.h++', '.h', '.cs'].includes(ext)) {
+      continue;
+    }
+    await compareFile(f);
+  }
+
+  console.log('\n══════════════════════════════════════════════════════════════');
+  console.log(`  Results: ${passed} passed, ${failed} failed`);
+
+  if (failed > 0) {
+    console.error('\n  QUERY PARITY FAILED\n');
+    process.exit(1);
+  } else {
+    console.log('\n  All query-parity tests passed! ✓\n');
+  }
+}
+
+run().catch(err => {
+  console.error('Query parity test threw:', err);
+  process.exit(1);
+});

package/tests/query-perf.ts

@@ -0,0 +1,55 @@
+/**
+ * Micro-bench: compare query-assisted vs baseline walker on the same fixtures.
+ * Not part of the standard test suite — run manually when changing the query
+ * path:  npx tsx tests/query-perf.ts
+ */
+import path from 'path';
+import fs from 'fs';
+import { parseFile, setForceBaselineWalker } from '../src/parser/index';
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+const REPEATS = 5;
+
+async function walkFixtures(dir: string, out: string[]): Promise<void> {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) await walkFixtures(p, out);
+    else out.push(p);
+  }
+}
+
+async function time(label: string, files: string[]): Promise<number> {
+  // Warmup
+  for (const f of files) await parseFile(fs.readFileSync(f, 'utf8'), f);
+  const start = Date.now();
+  for (let i = 0; i < REPEATS; i++) {
+    for (const f of files) await parseFile(fs.readFileSync(f, 'utf8'), f);
+  }
+  const elapsed = Date.now() - start;
+  console.log(`  ${label.padEnd(30)} ${elapsed}ms (${files.length} files × ${REPEATS} = ${files.length * REPEATS} parses)`);
+  return elapsed;
+}
+
+async function run(): Promise<void> {
+  const all: string[] = [];
+  await walkFixtures(FIXTURES_DIR, all);
+  const tcd = path.join(__dirname, 'fixtures-trackcd');
+  if (fs.existsSync(tcd)) await walkFixtures(tcd, all);
+  const fixtures = all.filter(f => /\.(ts|tsx|js|py|go|java|rs|c|cpp|cs|h|hpp)$/.test(f));
+  console.log(`\nQuery vs baseline walker micro-bench`);
+  console.log(`====================================\n`);
+  console.log(`  fixtures: ${fixtures.length}`);
+
+  setForceBaselineWalker(false);
+  const queryMs = await time('query-assisted', fixtures);
+
+  setForceBaselineWalker(true);
+  const baselineMs = await time('baseline', fixtures);
+
+  setForceBaselineWalker(false);
+
+  const ratio = queryMs / baselineMs;
+  console.log(`\n  query / baseline = ${ratio.toFixed(2)}x  (${ratio < 1 ? 'query faster' : 'baseline faster'})`);
+}
+
+run().catch(err => { console.error(err); process.exit(1); });