seer-mcp 0.1.0

package/src/indexer/detectchanges.ts

@@ -0,0 +1,94 @@
+import { Store } from '../db/store.js';
+import { gitChangedFiles, fileDiffHunksSync, isGitRepo } from './git.js';
+import type { SymbolRow } from '../types.js';
+
+/**
+ * Compute the blast radius of an uncommitted (or between-refs) diff. For each
+ * changed file we identify the symbols whose line ranges overlap the diff
+ * hunks, then expand by N levels of reverse callers (transitive callers,
+ * because they're the code most likely to break).
+ */
+
+export interface ChangedSymbol {
+  symbol: SymbolRow;
+  hunkCount: number;
+}
+
+export interface DetectChangesResult {
+  fromRef: string | null;
+  toRef: string | null;
+  changedFiles: Array<{ path: string; hunks: number; symbols: ChangedSymbol[] }>;
+  /** Direct changed symbols (the inner symbols in `changedFiles`). */
+  directlyChanged: SymbolRow[];
+  /** Transitive callers of the directly-changed set (deduped). */
+  transitivelyAffected: SymbolRow[];
+  elapsedMs: number;
+}
+
+export function detectChanges(
+  repoRoot: string, store: Store,
+  options: { fromRef?: string; toRef?: string; callerDepth?: number } = {},
+): DetectChangesResult {
+  const start = Date.now();
+  const callerDepth = options.callerDepth ?? 2;
+  const fromRef = options.fromRef ?? null;
+  const toRef = options.toRef ?? null;
+  if (!isGitRepo(repoRoot)) {
+    return { fromRef, toRef, changedFiles: [], directlyChanged: [], transitivelyAffected: [], elapsedMs: Date.now() - start };
+  }
+  const files = gitChangedFiles(repoRoot, fromRef ?? undefined, toRef ?? undefined);
+  if (files.length === 0) {
+    return { fromRef, toRef, changedFiles: [], directlyChanged: [], transitivelyAffected: [], elapsedMs: Date.now() - start };
+  }
+  const dbFiles = new Map(store.listFiles().map(f => [normalize(f.path), f.id]));
+  const changedFiles: DetectChangesResult['changedFiles'] = [];
+  const directIds = new Set<number>();
+  for (const abs of files) {
+    const fileId = dbFiles.get(normalize(abs));
+    if (fileId === undefined) continue;
+    const hunks = fileDiffHunksSync(repoRoot, abs, fromRef ?? undefined, toRef ?? undefined);
+    if (hunks.length === 0) continue;
+    // Convert 1-indexed git line ranges to 0-indexed Seer line ranges.
+    const ranges: Array<[number, number]> = hunks.map(h => [
+      Math.max(0, h.newStart - 1),
+      Math.max(0, h.newStart - 1 + Math.max(0, h.newLines - 1)),
+    ]);
+    const syms = store.symbolsTouchingLines(fileId, ranges);
+    for (const s of syms) directIds.add(s.id);
+    changedFiles.push({
+      path: abs,
+      hunks: hunks.length,
+      symbols: syms.map(s => ({ symbol: s, hunkCount: hunks.length })),
+    });
+  }
+  const directly: SymbolRow[] = [];
+  for (const id of directIds) {
+    const s = store.getSymbolById(id);
+    if (s) directly.push(s);
+  }
+  const transitiveIds = new Set<number>();
+  for (const s of directly) {
+    for (const id of store.reverseReachable(s.id, callerDepth)) {
+      if (!directIds.has(id)) transitiveIds.add(id);
+    }
+  }
+  const transitively: SymbolRow[] = [];
+  for (const id of transitiveIds) {
+    const s = store.getSymbolById(id);
+    if (s) transitively.push(s);
+  }
+  transitively.sort((a, b) => b.pagerank - a.pagerank);
+  return {
+    fromRef,
+    toRef,
+    changedFiles,
+    directlyChanged: directly,
+    transitivelyAffected: transitively,
+    elapsedMs: Date.now() - start,
+  };
+}
+
+function normalize(p: string): string {
+  const n = p.replace(/\\/g, '/');
+  return process.platform === 'win32' ? n.toLowerCase() : n;
+}

package/src/indexer/discovery.ts

@@ -0,0 +1,176 @@
+import fs from 'fs';
+import path from 'path';
+import ignore from 'ignore';
+import glob from 'fast-glob';
+
+export interface DiscoveredFile {
+  absolutePath: string;
+  relativePath: string;
+}
+
+/**
+ * Discovery mode controls how aggressively we filter directories/files before
+ * parsing. Modes are layered defaults — finer-grained `includeVendor` /
+ * `includeGenerated` toggles can still override the mode's vendor/generated
+ * decisions, and `.seerignore` rules apply on top of all of them.
+ *
+ *   - `full`     index everything we can parse (only build/meta and .git skipped)
+ *   - `standard` skip vendor + generated by default (current historical default)
+ *   - `fast`     standard + skip docs/examples/static/assets/migrations — aimed
+ *                at iterative agent loops where most non-source dirs are dead
+ *                weight
+ *
+ * Default is `standard`; `fast` is a deliberate opt-in for power users on
+ * very large repos where they want indexing as cheap as possible.
+ */
+export type DiscoveryMode = 'full' | 'standard' | 'fast';
+
+export interface DiscoveryOptions {
+  /**
+   * If true, vendored / generated directories that the default ignore list
+   * would skip are included in discovery. Vendored/generated classification
+   * still happens at index time — this just lets the user inspect what
+   * Seer would normally hide. Off by default; the README and master guide
+   * describe this as the "I really do want vendored code" escape hatch.
+   */
+  includeVendor?: boolean;
+  includeGenerated?: boolean;
+  /**
+   * Discovery aggressiveness. Defaults to 'standard'. See `DiscoveryMode`.
+   */
+  mode?: DiscoveryMode;
+}
+
+// Globally-skipped paths that are never source code (build outputs, IDE
+// state, VCS metadata). These are unconditional — `includeVendor` /
+// `includeGenerated` do NOT re-enable them. The user can override by adding
+// a `!pattern` line in `.seerignore`.
+const BUILD_AND_META_IGNORE = [
+  'node_modules', '.git', '.hg', '.svn',
+  'dist', 'build', 'out', '.next', '.nuxt', '__pycache__',
+  '*.min.js', '*.min.css', '*.bundle.js',
+  '*.lock', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+  // Build outputs across other ecosystems. `target/` is universally Rust
+  // (`cargo build`), `obj/` is .NET, `cmake-build-*` is JetBrains/CLion,
+  // `_build/` is Erlang/Elixir and some doc generators. Not adding `bin/`
+  // here — TypeScript-main and others keep entry scripts there.
+  'target/**', '**/target/**',
+  'obj/**', '**/obj/**',
+  'cmake-build-*/**', '**/cmake-build-*/**',
+  '_build/**', '**/_build/**',
+  '.gradle/**', '**/.gradle/**',
+  '.cache/**',
+  '.idea/**', '.vs/**',
+  // Unreal-specific build outputs (won't exist in a clean checkout but cheap
+  // to add defensively for users who built before indexing).
+  'Intermediate/**', '**/Intermediate/**',
+  'Saved/**', '**/Saved/**',
+  'DerivedDataCache/**',
+];
+
+// Vendored dependency roots — discovery-time skip by default, but classified
+// even when included. Match both the top level and any nested depth (Godot
+// uses `thirdparty/`, Unreal uses `Engine/Source/ThirdParty/`, etc.).
+const VENDOR_IGNORE = [
+  'vendor/**', '**/vendor/**',
+  'vendored/**', '**/vendored/**',
+  'Vendored/**', '**/Vendored/**',
+  'third_party/**', '**/third_party/**',
+  'thirdparty/**', '**/thirdparty/**',
+  'ThirdParty/**', '**/ThirdParty/**',
+];
+
+// Generated-code patterns that don't earn a place in default indexing. Same
+// "skip-by-default, classify-when-included" model as vendored code.
+const GENERATED_IGNORE = [
+  '*.pb.go', '*.pb.ts', '*.pb.h', '*.pb.cc',
+  '*.generated.h', '*.gen.cpp', '*.gen.h',
+];
+
+// Extra skips active only under `--mode fast`. These directories rarely
+// contain source code that contributes to the call graph — examples are
+// either demos that re-import from src, docs/static/assets are non-code, and
+// migrations are usually flat SQL or schema-only Python. Skipping them in
+// fast mode trims discovery and parse cost meaningfully on large monorepos.
+// Conservative on purpose: anything that might contain real call edges
+// (`tests/`, `src/`, `lib/`) stays indexed even in fast mode.
+const FAST_MODE_EXTRA_IGNORE = [
+  'docs/**', '**/docs/**',
+  'examples/**', '**/examples/**',
+  'example/**', '**/example/**',
+  'assets/**', '**/assets/**',
+  'static/**', '**/static/**',
+  'public/**', '**/public/**',
+  'media/**', '**/media/**',
+  'fixtures/**', '**/fixtures/**',
+  'testdata/**', '**/testdata/**',
+  'migrations/**', '**/migrations/**',
+];
+
+export async function discoverFiles(repoRoot: string, options: DiscoveryOptions = {}): Promise<DiscoveredFile[]> {
+  const absRoot = path.resolve(repoRoot);
+  const mode: DiscoveryMode = options.mode ?? 'standard';
+  // `full` mode flips both include flags ON regardless of caller intent. We
+  // still honor explicit `includeVendor=false` from a caller, but the typical
+  // use of `--mode full` is "index literally everything", so the default
+  // there is to include them.
+  const includeVendor = options.includeVendor ?? (mode === 'full');
+  const includeGenerated = options.includeGenerated ?? (mode === 'full');
+
+  const skip = [...BUILD_AND_META_IGNORE];
+  if (!includeVendor)    skip.push(...VENDOR_IGNORE);
+  if (!includeGenerated) skip.push(...GENERATED_IGNORE);
+  if (mode === 'fast')   skip.push(...FAST_MODE_EXTRA_IGNORE);
+
+  // Build ignore rules from .gitignore + optional .seerignore. The two are
+  // separate intentionally — .gitignore controls what's committed (often
+  // includes build outputs that we ALSO want hidden) while .seerignore is
+  // for repo-specific tweaks that don't belong in version control rules
+  // (e.g. "don't index our `examples/` folder").
+  const ig = ignore();
+  const gitignorePath = path.join(absRoot, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    ig.add(fs.readFileSync(gitignorePath, 'utf8'));
+  }
+  const seerignorePath = path.join(absRoot, '.seerignore');
+  if (fs.existsSync(seerignorePath)) {
+    ig.add(fs.readFileSync(seerignorePath, 'utf8'));
+  }
+
+  // Glob for source files in supported languages
+  const entries = await glob(
+    [
+      '**/*.py', '**/*.pyw',
+      '**/*.ts', '**/*.tsx',
+      '**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs',
+      '**/*.go',
+      '**/*.java',
+      '**/*.rs',
+      '**/*.c',
+      '**/*.cpp', '**/*.cc', '**/*.cxx', '**/*.c++',
+      '**/*.hpp', '**/*.hh', '**/*.h++', '**/*.h',
+      '**/*.cs',
+    ],
+    {
+      cwd: absRoot,
+      ignore: skip,
+      onlyFiles: true,
+      followSymbolicLinks: false,
+      dot: false,
+    },
+  );
+
+  // Stable order across runs is a correctness requirement: file IDs are
+  // AUTOINCREMENT, and tests/scale invariants depend on the same input
+  // producing the same IDs. `fast-glob` on Windows returns files in MFT/
+  // FS-cache order, which is not stable run-to-run. Sort here so every
+  // downstream stage — the byte semaphore window, parser-worker dispatch,
+  // SQLite inserts — sees the same sequence on every invocation.
+  return entries
+    .filter(rel => !ig.ignores(rel))
+    .sort()
+    .map(rel => ({
+      absolutePath: path.join(absRoot, rel),
+      relativePath: rel,
+    }));
+}

package/src/indexer/externaldeps.ts

@@ -0,0 +1,243 @@
+import fs from 'fs';
+import path from 'path';
+import glob from 'fast-glob';
+import { Store } from '../db/store.js';
+
+/**
+ * Walk the repo for known package manifests and emit one row per declared
+ * dependency. Idempotent: clears `external_dependencies` and re-inserts every
+ * call, so deletions in package.json are reflected on the next index.
+ *
+ * Supported ecosystems:
+ *   npm    package.json / package-lock.json / pnpm-lock.yaml (deps only)
+ *   cargo  Cargo.toml (Cargo.lock not parsed — duplicates would be noisy)
+ *   pypi   requirements.txt, pyproject.toml (PEP 621 [project.dependencies])
+ *   go     go.mod
+ *
+ * Manifest discovery uses fast-glob with the same ignores as the rest of the
+ * indexer (no node_modules, no vendor) so monorepos can be picked up from
+ * `packages/foo/package.json`.
+ */
+export async function extractExternalDependencies(repoRoot: string, store: Store): Promise<number> {
+  const abs = path.resolve(repoRoot);
+  const manifestPatterns = [
+    'package.json',
+    '**/package.json',
+    'Cargo.toml',
+    '**/Cargo.toml',
+    'pyproject.toml',
+    '**/pyproject.toml',
+    'requirements*.txt',
+    '**/requirements*.txt',
+    'go.mod',
+    '**/go.mod',
+  ];
+  const ignored = [
+    'node_modules/**', '**/node_modules/**',
+    'vendor/**', '**/vendor/**', 'vendored/**', '**/vendored/**',
+    'third_party/**', '**/third_party/**', 'thirdparty/**', '**/thirdparty/**',
+    'target/**', '**/target/**',
+    'dist/**', '**/dist/**',
+    '.git/**',
+  ];
+  const matches = await glob(manifestPatterns, {
+    cwd: abs, ignore: ignored, onlyFiles: true, followSymbolicLinks: false, dot: false,
+    unique: true,
+  });
+
+  store.clearExternalDeps();
+  let inserted = 0;
+  for (const rel of matches) {
+    const filePath = path.join(abs, rel);
+    let content: string;
+    try { content = fs.readFileSync(filePath, 'utf8'); } catch { continue; }
+    if (rel.endsWith('package.json') || rel === 'package.json') {
+      inserted += parsePackageJson(content, rel, store);
+    } else if (rel.endsWith('Cargo.toml') || rel === 'Cargo.toml') {
+      inserted += parseCargoToml(content, rel, store);
+    } else if (rel.endsWith('pyproject.toml') || rel === 'pyproject.toml') {
+      inserted += parsePyproject(content, rel, store);
+    } else if (rel.endsWith('.txt')) {
+      inserted += parseRequirementsTxt(content, rel, store);
+    } else if (rel.endsWith('go.mod') || rel === 'go.mod') {
+      inserted += parseGoMod(content, rel, store);
+    }
+  }
+  return inserted;
+}
+
+function parsePackageJson(content: string, manifestPath: string, store: Store): number {
+  let json: any;
+  try { json = JSON.parse(content); } catch { return 0; }
+  if (!json || typeof json !== 'object') return 0;
+  let count = 0;
+  const groups: Array<[Record<string, unknown> | undefined, 0 | 1]> = [
+    [json.dependencies, 0],
+    [json.devDependencies, 1],
+    [json.peerDependencies, 0],
+    [json.optionalDependencies, 0],
+  ];
+  for (const [group, isDev] of groups) {
+    if (!group || typeof group !== 'object') continue;
+    for (const [name, version] of Object.entries(group)) {
+      if (!name) continue;
+      store.insertExternalDep('npm', name, typeof version === 'string' ? version : null, manifestPath, isDev);
+      count++;
+    }
+  }
+  return count;
+}
+
+function parseCargoToml(content: string, manifestPath: string, store: Store): number {
+  // Lightweight TOML parser for [dependencies] / [dev-dependencies] sections.
+  // We intentionally don't pull in a full TOML lib — Cargo manifests are
+  // well-formed enough that a section-aware line walk suffices.
+  let count = 0;
+  let section = '';
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const sectionMatch = line.match(/^\[(.+?)\]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1].trim();
+      continue;
+    }
+    const inDeps = section === 'dependencies' || section === 'dev-dependencies' || section === 'build-dependencies';
+    if (!inDeps) continue;
+    const eq = line.indexOf('=');
+    if (eq < 0) continue;
+    const name = line.slice(0, eq).trim();
+    const rest = line.slice(eq + 1).trim();
+    if (!name || /[\[{]/.test(name)) continue;
+    let version: string | null = null;
+    const strMatch = rest.match(/^"([^"]+)"/);
+    if (strMatch) version = strMatch[1];
+    else {
+      const inlineVer = rest.match(/version\s*=\s*"([^"]+)"/);
+      if (inlineVer) version = inlineVer[1];
+    }
+    const isDev: 0 | 1 = section === 'dev-dependencies' ? 1 : 0;
+    store.insertExternalDep('cargo', name, version, manifestPath, isDev);
+    count++;
+  }
+  return count;
+}
+
+function parsePyproject(content: string, manifestPath: string, store: Store): number {
+  // [project] dependencies / optional-dependencies — Poetry uses
+  // [tool.poetry.dependencies] in addition. We handle both.
+  let count = 0;
+  let section = '';
+  let inList = false;
+  let buf: string[] = [];
+  const flushList = (isDev: 0 | 1): void => {
+    for (const item of buf) {
+      const m = item.match(/^"([^"]+)"|^'([^']+)'/);
+      if (!m) continue;
+      const spec = (m[1] ?? m[2] ?? '').trim();
+      if (!spec) continue;
+      // Strip extras / version: "package[extras]>=1.2.3"
+      const nameMatch = spec.match(/^([A-Za-z0-9_.\-]+)/);
+      if (!nameMatch) continue;
+      const name = nameMatch[1];
+      const versionMatch = spec.slice(nameMatch[0].length).match(/[<>=~!^].+/);
+      const version = versionMatch ? versionMatch[0].trim() : null;
+      store.insertExternalDep('pypi', name, version, manifestPath, isDev);
+      count++;
+    }
+    buf = [];
+  };
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.replace(/#.*$/, '').trim();
+    const sectionMatch = line.match(/^\[(.+?)\]$/);
+    if (sectionMatch) {
+      if (inList) { flushList(section.includes('dev') ? 1 : 0); inList = false; }
+      section = sectionMatch[1].trim();
+      continue;
+    }
+    if (section === 'project' || section === 'tool.poetry.dependencies' || section === 'tool.poetry.dev-dependencies') {
+      // [project] dependencies = ["pkg>=1.0", ...]
+      if (section === 'project' && /^dependencies\s*=\s*\[/.test(line)) {
+        inList = true;
+        const after = line.replace(/^dependencies\s*=\s*\[/, '');
+        if (after.includes(']')) {
+          for (const item of after.replace(/\].*$/, '').split(',')) buf.push(item.trim());
+          flushList(0);
+          inList = false;
+        } else {
+          buf.push(after);
+        }
+        continue;
+      }
+      if (inList) {
+        if (line.includes(']')) {
+          for (const item of line.replace(/\].*$/, '').split(',')) if (item.trim()) buf.push(item.trim());
+          flushList(0);
+          inList = false;
+        } else {
+          for (const item of line.split(',')) if (item.trim()) buf.push(item.trim());
+        }
+        continue;
+      }
+      if (section.startsWith('tool.poetry') && /^[A-Za-z0-9_.\-]+\s*=/.test(line)) {
+        const eq = line.indexOf('=');
+        const name = line.slice(0, eq).trim();
+        const rest = line.slice(eq + 1).trim();
+        const verMatch = rest.match(/^"([^"]+)"/);
+        const version = verMatch ? verMatch[1] : null;
+        const isDev: 0 | 1 = section.includes('dev') ? 1 : 0;
+        store.insertExternalDep('pypi', name, version, manifestPath, isDev);
+        count++;
+      }
+    }
+  }
+  if (inList) flushList(section.includes('dev') ? 1 : 0);
+  return count;
+}
+
+function parseRequirementsTxt(content: string, manifestPath: string, store: Store): number {
+  let count = 0;
+  const isDev: 0 | 1 = /dev|test/i.test(manifestPath) ? 1 : 0;
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line || line.startsWith('-')) continue;
+    const m = line.match(/^([A-Za-z0-9_.\-]+)/);
+    if (!m) continue;
+    const name = m[1];
+    const rest = line.slice(m[0].length);
+    const ver = rest.match(/[<>=~!^].+/);
+    store.insertExternalDep('pypi', name, ver ? ver[0].trim() : null, manifestPath, isDev);
+    count++;
+  }
+  return count;
+}
+
+function parseGoMod(content: string, manifestPath: string, store: Store): number {
+  let count = 0;
+  let inRequire = false;
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/\/\/.*$/, '').trim();
+    if (!line) continue;
+    if (line.startsWith('require (')) { inRequire = true; continue; }
+    if (line === ')') { inRequire = false; continue; }
+    if (line.startsWith('require ')) {
+      // single-line: `require mod v1.2.3`
+      const parts = line.slice('require '.length).trim().split(/\s+/);
+      if (parts.length >= 2) {
+        store.insertExternalDep('go', parts[0], parts[1], manifestPath, 0);
+        count++;
+      }
+      continue;
+    }
+    if (inRequire) {
+      const parts = line.split(/\s+/);
+      if (parts.length >= 2 && !/^\/\//.test(parts[0])) {
+        store.insertExternalDep('go', parts[0], parts[1], manifestPath, 0);
+        count++;
+      }
+    }
+  }
+  return count;
+}

package/src/indexer/freshness.ts

@@ -0,0 +1,166 @@
+import fs from 'fs';
+import crypto from 'crypto';
+import path from 'path';
+import { Indexer } from './index.js';
+import { Store } from '../db/store.js';
+import { discoverFiles } from './discovery.js';
+
+/**
+ * Quick freshness check + targeted re-index for MCP/CLI queries.
+ *
+ * Design contract: the watcher (when running) keeps the index warm by marking
+ * files dirty in the background. JIT sync runs before every query as the
+ * correctness layer — it does the actual reindex of dirty files so a query
+ * returning right now reflects the current workspace state.
+ *
+ * Implementation: discover the workspace, compare on-disk content hashes
+ * against what the DB says, and only reindex files whose hash changed.
+ * Unchanged files are skipped entirely; we don't touch the parser for them.
+ *
+ * The intentional bias here is correctness over latency: we re-discover the
+ * full workspace each time so newly-added or newly-renamed files are not
+ * missed. For very large repos this is still cheap (a glob + dir walk
+ * over 10-100k files is sub-second) compared to a single tree-sitter parse,
+ * and you only do it once per JIT call.
+ */
+export interface FreshnessReport {
+  /** Files where the on-disk hash differed from the DB. Reindexed. */
+  dirtyReindexed: number;
+  /** Files that vanished from disk since the last index. Pruned. */
+  removed: number;
+  /** Files newly seen this run (not in the DB yet). Indexed. */
+  added: number;
+  /** Total wall time in ms. */
+  elapsedMs: number;
+}
+
+/**
+ * Cheap content hash matching what the indexer uses internally. Kept here as
+ * a duplicate (not exported from indexer/index.ts) because the indexer's
+ * version is in the hot loop and we don't want to widen its export surface.
+ */
+function sha256Short(content: string): string {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 16);
+}
+
+/**
+ * Inspect a workspace for changes since the last index, then reindex only
+ * the files that need it. Designed to run before every MCP query.
+ *
+ * @param store     a writable Store (NOT readonly — we may need to mutate)
+ * @param indexer   an Indexer over the same store
+ * @param repoRoot  the workspace path used at index time
+ * @param options.maxDirty  cap reindex work per call. When the dirty set is
+ *   larger than this, we still run a full `indexer.indexDirectory()` because
+ *   a partial JIT pass would leave the index inconsistent (resolveEdges
+ *   needs the full graph). Defaults to 200 — small enough to keep the
+ *   "type a few characters and ask" workflow snappy.
+ */
+export async function jitSync(
+  store: Store,
+  indexer: Indexer,
+  repoRoot: string,
+  options: { maxDirty?: number; verbose?: boolean } = {},
+): Promise<FreshnessReport> {
+  const start = Date.now();
+  const maxDirty = options.maxDirty ?? 200;
+
+  const absRoot = path.resolve(repoRoot);
+
+  // 1. Snapshot what the DB knows.
+  const dbFiles = store.listFiles();
+  const dbByPath = new Map(dbFiles.map(f => [normalizeForCompare(f.path), f]));
+
+  // 2. Walk the workspace and find candidate files. discoverFiles() applies
+  //    the same ignore rules the indexer uses, so freshness can't be
+  //    misled by build artifacts or `vendor/` entries.
+  const discovered = await discoverFiles(absRoot);
+  const discoveredByPath = new Map<string, string>();
+  for (const d of discovered) {
+    discoveredByPath.set(normalizeForCompare(d.absolutePath), d.relativePath);
+  }
+
+  // 3. Identify added / removed / candidate-dirty files.
+  const added: string[] = [];
+  const removed: number[] = [];
+  const candidateDirty: typeof dbFiles = [];
+  for (const f of dbFiles) {
+    const key = normalizeForCompare(f.path);
+    if (!discoveredByPath.has(key)) {
+      removed.push(f.id);
+      continue;
+    }
+    candidateDirty.push(f);
+  }
+  for (const [key, _rel] of discoveredByPath) {
+    if (!dbByPath.has(key)) added.push(key);
+  }
+
+  // 4. Hash each candidate. Same trade-off as the indexer: read everything
+  //    we'd parse anyway, but if the hash matches we never spend time on
+  //    the parser. We stop early as soon as we cross `maxDirty` so a giant
+  //    change like a git checkout falls back to a full reindex.
+  const dirty: string[] = [];
+  for (const f of candidateDirty) {
+    if (dirty.length + added.length >= maxDirty) break;
+    let content: string;
+    try {
+      content = await fs.promises.readFile(f.path, 'utf8');
+    } catch {
+      // File became unreadable mid-check (rename, permission flip). Treat
+      // as removed so the next pass cleans it up.
+      removed.push(f.id);
+      continue;
+    }
+    const hash = sha256Short(content);
+    if (hash !== f.hash) dirty.push(f.path);
+  }
+
+  const fullReindexNeeded =
+    dirty.length + added.length >= maxDirty || removed.length > 0;
+
+  if (dirty.length === 0 && added.length === 0 && removed.length === 0) {
+    return { dirtyReindexed: 0, removed: 0, added: 0, elapsedMs: Date.now() - start };
+  }
+
+  if (fullReindexNeeded) {
+    // Cheaper to invoke the full pipeline than to surgically remove files
+    // and reconcile edge graphs. The indexer's cache means unchanged files
+    // are still skipped at parse time, so this is O(dirty + added + |touched|)
+    // not O(|workspace|).
+    // JIT pins parallel:false. The dirty set is small (≤ maxDirty=200) and
+    // worker spawn cost dominates the wins at this scale; serial is the
+    // right default for the snappy "edit + ask" loop. MCP servers that want
+    // parallel JIT can override later via an option.
+    const result = await indexer.indexDirectory(absRoot, { quiet: !options.verbose, parallel: false });
+    return {
+      dirtyReindexed: dirty.length,
+      removed: removed.length,
+      added: added.length,
+      elapsedMs: Date.now() - start + (result.elapsedMs ?? 0),
+    };
+  }
+
+  // Targeted JIT path: dirty/added files only, no full re-discovery. Reuse
+  // the indexer's machinery by calling indexDirectory — its cache skips
+  // unchanged files. This is dominated by the discovery walk we already did,
+  // so the marginal cost is small.
+  await indexer.indexDirectory(absRoot, { quiet: !options.verbose, parallel: false });
+  return {
+    dirtyReindexed: dirty.length,
+    removed: removed.length,
+    added: added.length,
+    elapsedMs: Date.now() - start,
+  };
+}
+
+/**
+ * Normalize a path for comparison across the OS-specific quirks we hit on
+ * Windows. We index with backslashes; discovery resolves through `path.join`
+ * which also produces backslashes. Read-only callers might pass a slash-form
+ * path through the MCP layer; lowercase folds Windows case-insensitivity.
+ */
+function normalizeForCompare(p: string): string {
+  const norm = p.replace(/\\/g, '/');
+  return process.platform === 'win32' ? norm.toLowerCase() : norm;
+}