@esneiderbravo/speclaw 2.0.9 → 2.0.11

package/dist/modules/compass/indexer.js

@@ -1,13 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { openDb, clearNeedsReindex, needsReindex } from "./db.js";
+import { openDb, openCurrentDb, isCurrentIndex, clearNeedsReindex, needsReindex, postPending, setPostPending, clearPostPending, FILE_NODE_KIND, } from "./db.js";
 import { langForPath } from "./languages.js";
-import { extract } from "./extract.js";
+import { extract, importSpecifier } from "./extract.js";
 import { getEmbedder, toBlob } from "./embedder.js";
 import { contentHashFor, defaultEmbedText } from "./embed-input.js";
-import { buildDirHashMap } from "./merkle.js";
-import { loadAffectedConfig, isTestPath, inferModule } from "./affected-config.js";
+import { buildDirHashMap, dirHash, HASH_EMPTY } from "./merkle.js";
+import { loadAffectedConfig, isTestPath, inferModule, } from "./affected-config.js";
+import { realPathOf } from "../../shared/paths.js";
 import { personalizedPageRank, edgeWeightMul } from "./pagerank.js";
 const SKIP_DIRS = new Set([
     ".git",
@@ -30,112 +31,500 @@ const SKIP_DIRS = new Set([
     ".cache",
 ]);
 const MAX_FILE_BYTES = 1_500_000;
+/**
+ * Whether a directory or file name inside the project is walked by a full index.
+ * The single source of the skip rule shared by the walk and per-file reindex.
+ */
+function isSkippedDir(name) {
+    return SKIP_DIRS.has(name);
+}
+/**
+ * `p` with symlinks resolved and, where the platform reports it (macOS,
+ * Windows), each existing segment spelled as stored on disk. A missing tail
+ * keeps its given spelling. Falls back to {@link realPathOf} when the native
+ * resolver fails.
+ *
+ * @param p - An absolute path.
+ */
+function canonicalPathOf(p) {
+    const tail = [];
+    let cur = path.resolve(p);
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(cur), ...tail.reverse());
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return realPathOf(p);
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return realPathOf(p);
+            tail.push(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/**
+ * Classify one path against the full walk's file-set rules, so a per-file
+ * reindex and a full index agree on which files are indexed (and the directory
+ * Merkle tree stays the hash of the same file set).
+ *
+ * A path is eligible when it lies inside `projectPath` (symlinks in its existing
+ * prefix resolved, and its spelling taken from the filesystem where the platform
+ * reports it, so a case variant on a case-insensitive volume yields the stored
+ * spelling), no directory segment is a skipped directory, its extension
+ * maps to an indexed language, it is a regular file, and it does not exceed the
+ * walk's size cap. A path that does not exist yields `missing` with its
+ * repo-relative form, so the caller can drop a deleted file's rows.
+ *
+ * @param projectPath - Absolute project root.
+ * @param absPath - Absolute path to classify.
+ */
+export function classifyIndexPath(projectPath, absPath) {
+    const relNative = path.relative(canonicalPathOf(projectPath), canonicalPathOf(absPath));
+    if (!relNative || relNative.startsWith("..") || path.isAbsolute(relNative)) {
+        return { eligible: false, rel: null, reason: "outside" };
+    }
+    const rel = relNative.split(path.sep).join("/");
+    const parts = rel.split("/");
+    if (parts.slice(0, -1).some(isSkippedDir))
+        return { eligible: false, rel, reason: "ignored" };
+    const lang = langForPath(rel);
+    if (!lang)
+        return { eligible: false, rel, reason: "language" };
+    let stat;
+    try {
+        stat = fs.statSync(path.join(projectPath, rel));
+    }
+    catch {
+        return { eligible: false, rel, reason: "missing" };
+    }
+    if (!stat.isFile())
+        return { eligible: false, rel, reason: "ignored" };
+    if (stat.size > MAX_FILE_BYTES)
+        return { eligible: false, rel, reason: "size" };
+    return { eligible: true, rel, lang, size: stat.size, mtimeMs: Math.trunc(stat.mtimeMs) };
+}
+/**
+ * Whether a full walk of `projectPath` would yield exactly `rel`: every segment
+ * is listed by its parent directory with exactly that spelling (a case-sensitive
+ * compare, so a case-only rename on a case-insensitive volume does not match),
+ * every directory segment is a real, non-skipped directory and the leaf a
+ * regular file (no segment is a symlink, as the walk never follows one), and
+ * {@link classifyIndexPath} finds it eligible under the same `rel`.
+ *
+ * A full run keeps a stored row its walk did not see only when this holds;
+ * any other row would duplicate the file's symbols under a second path.
+ *
+ * @param projectPath - Absolute project root (as walked).
+ * @param rel - Repo-relative path with `/` separators.
+ * @param listings - Optional cache of directory listings, keyed by absolute
+ *   directory, shared across calls in one run.
+ */
+export function walkWouldYield(projectPath, rel, listings = new Map()) {
+    const parts = rel.split("/");
+    if (parts.some((p) => p === "" || p === "." || p === ".."))
+        return false;
+    let dir = projectPath;
+    for (let i = 0; i < parts.length; i++) {
+        const name = parts[i];
+        let names = listings.get(dir);
+        if (names === undefined) {
+            try {
+                names = new Set(fs.readdirSync(dir));
+            }
+            catch {
+                names = null;
+            }
+            listings.set(dir, names);
+        }
+        if (!names?.has(name))
+            return false;
+        const full = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.lstatSync(full);
+        }
+        catch {
+            return false;
+        }
+        const leaf = i === parts.length - 1;
+        if (leaf ? !stat.isFile() : !stat.isDirectory() || isSkippedDir(name))
+            return false;
+        dir = full;
+    }
+    const c = classifyIndexPath(projectPath, path.join(projectPath, rel));
+    return c.eligible && c.rel === rel;
+}
 function hashOf(content) {
     return createHash("sha256").update(content).digest("hex");
 }
 const DEFAULT_MAX_CACHE_MB = 256;
 const DEFAULT_RETENTION_DAYS = 30;
 /**
- * Point import edges at a representative node in the imported file so reverse
- * reachability can walk file-level dependencies (not just calls).
+ * Call names that are ambient globals in common runtimes and test frameworks.
+ * A plain call to one of them binds only to a definition in the same file, so
+ * a project symbol that happens to share the name never collects every test
+ * file as a caller.
+ */
+export const BUILTIN_GLOBALS = [
+    "describe",
+    "it",
+    "test",
+    "expect",
+    "beforeEach",
+    "afterEach",
+    "beforeAll",
+    "afterAll",
+    "setTimeout",
+    "setInterval",
+    "clearTimeout",
+    "clearInterval",
+    "queueMicrotask",
+    "parseInt",
+    "parseFloat",
+    "require",
+    "structuredClone",
+    "fetch",
+    "print",
+    "len",
+    "isinstance",
+    "super",
+];
+/** {@link BUILTIN_GLOBALS} as a quoted SQL `IN (...)` list. */
+export const BUILTIN_SQL_LIST = BUILTIN_GLOBALS.map((n) => `'${n}'`).join(", ");
+/** Most bind parameters a scoped {@link resolveEdges} call uses before running unscoped. */
+const MAX_SCOPE_PARAMS = 10_000;
+/**
+ * Resolve call and import edges to node ids — the one place edge resolution
+ * lives, shared by the full index run and incremental re-indexing.
+ *
+ * - Edges whose `dst_node_id` points at a node that no longer exists (its file
+ *   was re-extracted) are reset to unresolved first.
+ * - Imports are resolved first (below). A call's "import target" is the file
+ *   the same-file import edge with the call's `spec` resolved to.
+ * - Calls with `is_member = 1` are never resolved by name. Calls with
+ *   `is_member = 2` (a member call on an import binding) resolve only when their
+ *   import target exists: an import that no relative/alias/baseUrl resolution
+ *   maps to a project file is a package, so `path.parse()` stays foreign.
+ * - A call to a {@link BUILTIN_GLOBALS} name resolves only to a definition in
+ *   the same file or in its import target (`import { fetch } from "./http"`).
+ * - Otherwise a call prefers its import target, then a definition under the
+ *   import target's directory (a barrel's subtree), then a same-file
+ *   definition, else the lowest-id node with that name. File-owner nodes are
+ *   never call targets. An import of a symbol-less or re-exporting file (a
+ *   barrel) resolves to that file's file-owner node, so member calls through
+ *   it bind by name like this.
+ * - Imports resolve their specifier relative to the importing file, then
+ *   through the nearest `tsconfig.json`/`jsconfig.json` `paths`/`baseUrl`, and
+ *   point at the target file's file-owner node when it has one, otherwise at
+ *   its first node by `start_line`.
+ *
+ * The project root is read from the database's own path
+ * (`<root>/.speclaw/index.db`), so callers pass only the connection.
+ *
+ * @param db - Open index database (the caller owns the transaction).
+ * @param fileIds - When set, only calls owned by these files or by files whose
+ * import this pass resolved, and unresolved calls whose name a node in these
+ * files defines; unresolved imports are always all processed (a new file may
+ * satisfy any of them). When omitted, every
+ * unresolved edge.
+ * @returns How many call and import edges this call resolved.
+ */
+export function resolveEdges(db, fileIds) {
+    // Covers: req~impact-id-first~1
+    db.exec(`UPDATE edges SET dst_node_id = NULL
+     WHERE dst_node_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM nodes n WHERE n.id = edges.dst_node_id)`);
+    const scoped = fileIds !== undefined;
+    const ids = fileIds ?? [];
+    const idList = ids.map(() => "?").join(", ") || "NULL";
+    const resolvedCalls = () => Number(db
+        .prepare("SELECT COUNT(*) AS n FROM edges WHERE kind = 'call' AND dst_node_id IS NOT NULL")
+        .get().n);
+    // Imports first: whether a call on an import binding may bind depends on
+    // whether that binding's import resolved to a project file.
+    const { resolved: imports, srcFiles } = resolveImportEdges(db, projectRootOf(db));
+    const before = resolvedCalls();
+    // A file whose import just resolved may have pending is_member = 2 calls.
+    // Past a bound (SQLite caps bind parameters) the pass is simply unscoped.
+    const importScope = [...srcFiles];
+    const importList = importScope.map(() => "?").join(", ") || "NULL";
+    const narrow = scoped && 2 * ids.length + importScope.length <= MAX_SCOPE_PARAMS;
+    const callScope = narrow
+        ? `AND (src_file_id IN (${idList}) OR src_file_id IN (${importList})
+          OR dst_name IN (SELECT name FROM nodes WHERE file_id IN (${idList}) AND kind <> '${FILE_NODE_KIND}'))`
+        : "";
+    // File of the node the same-file import with this call's spec resolved to;
+    // NULL when the call has no spec (the subquery is skipped) or that import
+    // stayed unresolved (a package).
+    const importTarget = `(CASE WHEN edges.spec IS NULL THEN NULL ELSE (
+       SELECT t.file_id FROM edges i JOIN nodes t ON t.id = i.dst_node_id
+       WHERE i.src_file_id = edges.src_file_id AND i.kind = 'import' AND i.spec = edges.spec
+       ORDER BY i.id LIMIT 1) END)`;
+    // Candidate n lies under the import target's directory: a barrel
+    // (`libs/core/src/index.ts`) usually re-exports its own subtree, so this
+    // stands in for "reachable through the barrel's re-exports" without storing
+    // them. rtrim(p, <p without '/'>) is p's directory with its trailing slash.
+    const underTargetDir = `EXISTS (
+       SELECT 1 FROM files tf, files nf
+       WHERE tf.id = ${importTarget} AND nf.id = n.file_id
+         AND substr(nf.path, 1, length(rtrim(tf.path, replace(tf.path, '/', ''))))
+             = rtrim(tf.path, replace(tf.path, '/', '')))`;
+    db.prepare(`UPDATE edges SET dst_node_id = (
+       SELECT n.id FROM nodes n
+       WHERE n.name = edges.dst_name
+         AND n.kind <> '${FILE_NODE_KIND}'
+         AND (edges.dst_name NOT IN (${BUILTIN_SQL_LIST}) OR n.file_id = edges.src_file_id
+              OR n.file_id = ${importTarget})
+       ORDER BY CASE WHEN n.file_id = ${importTarget} THEN 0
+                     WHEN edges.spec IS NOT NULL AND ${underTargetDir} THEN 1
+                     WHEN n.file_id = edges.src_file_id THEN 2 ELSE 3 END, n.id
+       LIMIT 1
+     )
+     WHERE kind = 'call' AND dst_node_id IS NULL
+       AND (is_member = 0
+            OR (is_member = 2 AND edges.spec IS NOT NULL AND ${importTarget} IS NOT NULL))
+       ${callScope}`).run(...(narrow ? [...ids, ...importScope, ...ids] : []));
+    const calls = resolvedCalls() - before;
+    return { calls, imports };
+}
+/** Project root of an index database stored at `<root>/.speclaw/index.db`. */
+function projectRootOf(db) {
+    const row = db.prepare("SELECT file FROM pragma_database_list WHERE name = 'main'").get();
+    return path.dirname(path.dirname(row?.file ?? ""));
+}
+/**
+ * Point every unresolved import edge at a representative node of the imported
+ * file (its file-owner node, else its first node) so reverse reachability walks
+ * file-level dependencies, not just calls. Not narrowed by file: a newly
+ * indexed file can satisfy an import anywhere.
+ *
+ * @returns How many import edges were resolved, and the importing files' ids.
  */
 function resolveImportEdges(db, projectPath) {
+    // Covers: req~import-resolution~1
     const files = db.prepare("SELECT id, path FROM files").all();
     const byNorm = new Map();
-    for (const f of files) {
+    for (const f of files)
         byNorm.set(f.path.split("\\").join("/"), f.id);
-    }
-    const firstNode = db.prepare("SELECT id FROM nodes WHERE file_id = ? ORDER BY start_line ASC, id ASC LIMIT 1");
-    const namedNode = db.prepare("SELECT id FROM nodes WHERE file_id = ? AND name = ? ORDER BY id ASC LIMIT 1");
+    const target = db.prepare(`SELECT id FROM nodes WHERE file_id = ?
+     ORDER BY kind = '${FILE_NODE_KIND}' DESC, start_line ASC, id ASC LIMIT 1`);
     const upd = db.prepare("UPDATE edges SET dst_node_id = ? WHERE id = ?");
     const imports = db
-        .prepare(`SELECT e.id, e.dst_name, e.src_file_id, f.path AS src_path
+        .prepare(`SELECT e.id, e.dst_name, e.spec, e.src_file_id, f.path AS src_path
        FROM edges e JOIN files f ON f.id = e.src_file_id
        WHERE e.kind = 'import' AND e.dst_node_id IS NULL`)
         .all();
+    const aliases = new AliasResolver(projectPath);
+    let resolved = 0;
+    const srcFiles = new Set();
     for (const edge of imports) {
-        const spec = parseImportSpecifier(edge.dst_name);
+        const spec = edge.spec ?? importSpecifier(edge.dst_name);
         if (!spec)
             continue;
-        const targetRel = resolveImportPath(projectPath, edge.src_path, spec.from);
+        const targetRel = resolveImportPath(projectPath, edge.src_path, spec, byNorm, aliases);
         if (!targetRel)
             continue;
         const fileId = byNorm.get(targetRel);
         if (fileId === undefined)
             continue;
-        let nodeId;
-        for (const name of spec.names) {
-            const row = namedNode.get(fileId, name);
-            if (row) {
-                nodeId = row.id;
-                break;
+        const row = target.get(fileId);
+        if (!row)
+            continue;
+        upd.run(row.id, edge.id);
+        resolved++;
+        srcFiles.add(edge.src_file_id);
+    }
+    return { resolved, srcFiles };
+}
+/** Repo-relative candidate files for an import target (extension and index probing). */
+function importCandidates(projectPath, absBase) {
+    const rel = path.relative(projectPath, absBase).split(path.sep).join("/");
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return [];
+    return [
+        rel,
+        rel.replace(/\.js$/, ".ts"),
+        rel.replace(/\.js$/, ".tsx"),
+        rel.replace(/\.jsx$/, ".tsx"),
+        rel.replace(/\.mjs$/, ".mts"),
+        rel.replace(/\.cjs$/, ".cts"),
+        `${rel}.ts`,
+        `${rel}.tsx`,
+        `${rel}.js`,
+        `${rel}.jsx`,
+        `${rel}.mjs`,
+        `${rel}.cjs`,
+        `${rel}/index.ts`,
+        `${rel}/index.tsx`,
+        `${rel}/index.js`,
+    ];
+}
+/**
+ * Resolve an import specifier to an indexed repo-relative path: relative
+ * specifiers against the importing file (including `.js` → `.ts`), then
+ * tsconfig/jsconfig `paths` aliases and bare `baseUrl` lookups. Bare package
+ * names that match no project file stay unresolved (null).
+ */
+function resolveImportPath(projectPath, srcRel, spec, indexed, aliases) {
+    const firstIndexed = (absBase) => importCandidates(projectPath, absBase).find((c) => indexed.has(c)) ?? null;
+    const srcDir = path.dirname(path.join(projectPath, srcRel));
+    if (spec.startsWith(".") || spec.startsWith("/")) {
+        return firstIndexed(path.resolve(srcDir, spec));
+    }
+    for (const absBase of aliases.candidates(srcDir, spec)) {
+        const hit = firstIndexed(absBase);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/**
+ * Best-effort tsconfig/jsconfig alias lookup, cached per directory for one
+ * resolution pass. Never throws: an unreadable or malformed config disables
+ * alias resolution for the files under it, and relative imports still resolve.
+ */
+class AliasResolver {
+    root;
+    byDir = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    /** Absolute import bases to probe for a non-relative specifier, in order. */
+    candidates(fromDir, spec) {
+        const cfg = this.configFor(fromDir);
+        if (!cfg)
+            return [];
+        const out = [];
+        for (const { pattern, targets } of cfg.paths) {
+            const star = pattern.indexOf("*");
+            let captured = null;
+            if (star < 0) {
+                if (spec === pattern)
+                    captured = "";
+            }
+            else {
+                const pre = pattern.slice(0, star);
+                const post = pattern.slice(star + 1);
+                if (spec.startsWith(pre) &&
+                    spec.endsWith(post) &&
+                    spec.length >= pre.length + post.length) {
+                    captured = spec.slice(pre.length, spec.length - post.length);
+                }
+            }
+            if (captured === null)
+                continue;
+            for (const t of targets) {
+                out.push(path.resolve(cfg.baseUrl ?? cfg.pathsBase, t.replace("*", captured)));
             }
         }
-        if (nodeId === undefined) {
-            const row = firstNode.get(fileId);
-            nodeId = row?.id;
+        if (cfg.baseUrl)
+            out.push(path.resolve(cfg.baseUrl, spec));
+        return out;
+    }
+    /** Nearest tsconfig/jsconfig at or above `dir`, bounded by the project root. */
+    configFor(dir) {
+        const cached = this.byDir.get(dir);
+        if (cached !== undefined)
+            return cached;
+        let result = null;
+        const rel = path.relative(this.root, dir);
+        if (!rel.startsWith("..") && !path.isAbsolute(rel)) {
+            const own = ["tsconfig.json", "jsconfig.json"]
+                .map((n) => path.join(dir, n))
+                .find((f) => fs.existsSync(f));
+            if (own)
+                result = loadAliasConfig(own, this.root);
+            else if (dir !== this.root)
+                result = this.configFor(path.dirname(dir));
         }
-        if (nodeId !== undefined)
-            upd.run(nodeId, edge.id);
+        this.byDir.set(dir, result);
+        return result;
     }
 }
-/** Pull `from` path and optional named imports out of a raw import statement text. */
-function parseImportSpecifier(text) {
-    const fromMatch = text.match(/\bfrom\s+['"]([^'"]+)['"]/) ?? text.match(/require\s*\(\s*['"]([^'"]+)['"]/);
-    if (!fromMatch)
-        return null;
-    const from = fromMatch[1];
-    const names = [];
-    const brace = text.match(/\{([^}]+)\}/);
-    if (brace) {
-        for (const part of brace[1].split(",")) {
-            const id = part
-                .trim()
-                .split(/\s+as\s+/i)[0]
-                .trim();
-            if (id && /^[A-Za-z_$][\w$]*$/.test(id))
-                names.push(id);
+/**
+ * Strip `//` and block comments and trailing commas from JSONC text, leaving
+ * string literals untouched.
+ */
+export function stripJsonComments(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"')
+                j += text[j] === "\\" ? 2 : 1;
+            out += text.slice(i, j + 1);
+            i = j + 1;
+        }
+        else if (ch === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+        }
+        else if (ch === "/" && text[i + 1] === "*") {
+            const close = text.indexOf("*/", i + 2);
+            i = close < 0 ? text.length : close + 2;
+        }
+        else {
+            out += ch;
+            i++;
         }
     }
-    const def = text.match(/\bimport\s+([A-Za-z_$][\w$]*)\s+/);
-    if (def && !text.includes("{"))
-        names.push(def[1]);
-    return { from, names };
+    return out.replace(/,(\s*[}\]])/g, "$1");
 }
 /**
- * Resolve a relative/absolute-ish import specifier to a project-relative indexed path.
+ * Read a tsconfig and its relative `extends` chain (max depth 5, cycle-safe,
+ * inside the project root). The nearest definition of `baseUrl` and of `paths`
+ * wins, each resolved against the config file that declares it.
+ *
+ * @returns The effective alias config, or null when the file cannot be parsed.
  */
-function resolveImportPath(projectPath, srcRel, spec) {
-    if (!spec.startsWith(".") && !spec.startsWith("/"))
-        return null; // bare package — skip
-    const srcDir = path.dirname(path.join(projectPath, srcRel));
-    const absBase = path.resolve(srcDir, spec);
-    const candidates = [
-        absBase,
-        absBase.replace(/\.js$/, ".ts"),
-        absBase.replace(/\.js$/, ".tsx"),
-        absBase.replace(/\.jsx$/, ".tsx"),
-        `${absBase}.ts`,
-        `${absBase}.tsx`,
-        `${absBase}.js`,
-        `${absBase}.jsx`,
-        `${absBase}.mjs`,
-        `${absBase}.cjs`,
-        path.join(absBase, "index.ts"),
-        path.join(absBase, "index.js"),
-    ];
-    for (const abs of candidates) {
-        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
-            continue;
-        return path.relative(projectPath, abs).split("\\").join("/");
-    }
-    // Fall back without existence check — strip a trailing .js for TS sources.
-    let rel = path.relative(projectPath, absBase).split("\\").join("/");
-    if (rel.endsWith(".js"))
-        rel = rel.slice(0, -3) + ".ts";
-    else if (!/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(rel))
-        rel = `${rel}.ts`;
-    return rel.replace(/^\.\//, "");
+function loadAliasConfig(file, root) {
+    let baseUrl;
+    let paths;
+    let pathsBase = path.dirname(file);
+    const seen = new Set();
+    let current = file;
+    for (let depth = 0; current && depth < 6 && !seen.has(current); depth++) {
+        seen.add(current);
+        let parsed;
+        try {
+            parsed = JSON.parse(stripJsonComments(fs.readFileSync(current, "utf8")));
+        }
+        catch {
+            if (depth === 0)
+                return null;
+            break;
+        }
+        const dir = path.dirname(current);
+        const co = parsed.compilerOptions ?? {};
+        if (baseUrl === undefined && typeof co.baseUrl === "string") {
+            baseUrl = path.resolve(dir, co.baseUrl);
+        }
+        if (paths === undefined && co.paths && typeof co.paths === "object") {
+            paths = co.paths;
+            pathsBase = dir;
+        }
+        current = null;
+        if (typeof parsed.extends === "string" && parsed.extends.startsWith(".")) {
+            let next = path.resolve(dir, parsed.extends);
+            if (!next.endsWith(".json"))
+                next += ".json";
+            const rel = path.relative(root, next);
+            if (!rel.startsWith("..") && !path.isAbsolute(rel) && fs.existsSync(next))
+                current = next;
+        }
+    }
+    const entries = Object.entries(paths ?? {})
+        .filter(([, t]) => Array.isArray(t))
+        .map(([pattern, targets]) => ({
+        pattern,
+        targets: targets.filter((t) => typeof t === "string"),
+    }))
+        .sort((a, b) => b.pattern.split("*")[0].length - a.pattern.split("*")[0].length);
+    return { baseUrl, paths: entries, pathsBase };
 }
 /**
  * Infer a covering artifact's type from its project-relative path.
@@ -169,7 +558,7 @@ function* walkFiles(root) {
         for (const entry of entries) {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-                if (!SKIP_DIRS.has(entry.name))
+                if (!isSkippedDir(entry.name))
                     stack.push(full);
             }
             else if (entry.isFile()) {
@@ -179,6 +568,152 @@ function* walkFiles(root) {
         }
     }
 }
+function prepareFileWriter(db, embedder, cfg, touch = true) {
+    return {
+        db,
+        touch,
+        collectOwners: !touch,
+        embedder,
+        cfg,
+        insFile: db.prepare("INSERT INTO files(path, hash, lang, is_test, module, mtime_ms, size) VALUES (?, ?, ?, ?, ?, ?, ?)"),
+        updFile: db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ?, mtime_ms = ?, size = ? WHERE id = ?"),
+        detach: db.prepare("UPDATE edges SET dst_node_id = NULL WHERE dst_node_id IN (SELECT id FROM nodes WHERE file_id = ?)"),
+        detachedOwners: db.prepare(`SELECT DISTINCT src_file_id AS id FROM edges
+       WHERE src_file_id <> ? AND dst_node_id IN (SELECT id FROM nodes WHERE file_id = ?)`),
+        delNodes: db.prepare("DELETE FROM nodes WHERE file_id = ?"),
+        delEdges: db.prepare("DELETE FROM edges WHERE src_file_id = ?"),
+        delCoverage: db.prepare("DELETE FROM coverage_links WHERE file_path = ?"),
+        delFile: db.prepare("DELETE FROM files WHERE id = ?"),
+        insNode: db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash, content_hash)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        insMetrics: db.prepare(`INSERT INTO node_metrics(node_id, loc, max_nesting, branches) VALUES (?, ?, ?, ?)`),
+        insEdge: db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line, is_member, spec) VALUES (?, ?, ?, ?, ?, ?, ?)`),
+        insCoverage: db.prepare(`INSERT OR REPLACE INTO coverage_links(
+         artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        insCache: db.prepare(`INSERT INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(content_hash, model) DO UPDATE SET last_seen_at = excluded.last_seen_at`),
+        hasCache: db.prepare(`SELECT 1 AS ok FROM embedding_cache WHERE content_hash = ? AND model = ?`),
+        touchCache: db.prepare(`UPDATE embedding_cache SET last_seen_at = ? WHERE content_hash = ? AND model = ?`),
+        insNodeText: db.prepare(`INSERT INTO node_text(node_id, name, subtokens, signature, doc) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name = excluded.name,
+         subtokens = excluded.subtokens,
+         signature = excluded.signature,
+         doc = excluded.doc`),
+    };
+}
+/**
+ * Reset every edge whose destination is one of a file's nodes, before those
+ * nodes are deleted. Without this, a rowid freed by the delete and reused by a
+ * node inserted later in the same run would silently re-point another file's
+ * edge at an unrelated symbol; a post-hoc "id not in nodes" check cannot see
+ * that. The run's resolution pass then re-binds the edges by their rules.
+ *
+ * @returns The ids of the other files whose edges were reset (empty on a full run, which does not need them).
+ */
+function detachFileNodes(w, fileId) {
+    // Covers: req~edge-ids-survive-reindex~1
+    const owners = w.collectOwners
+        ? w.detachedOwners.all(fileId, fileId).map((r) => r.id)
+        : [];
+    w.detach.run(fileId);
+    return owners;
+}
+/**
+ * Drop a removed file: detach edges into it, delete its coverage links (the
+ * file-level ones have no node to cascade from), then delete its row (nodes and
+ * edges cascade).
+ */
+function removeFileRows(w, fileId, rel) {
+    const owners = detachFileNodes(w, fileId);
+    w.delCoverage.run(rel);
+    w.delFile.run(fileId);
+    return owners;
+}
+/**
+ * (Re-)extract one file and write its whole fragment: upsert its `files` row,
+ * replace its nodes, file-owner node, edges, `node_text`/FTS rows, metrics, and
+ * coverage links, and embed cache misses through `embedding_cache`. Edges are
+ * written unresolved; the caller runs {@link resolveEdges}.
+ *
+ * @returns The file id and the ids of other files whose edges were detached.
+ */
+async function writeFileFragment(w, f) {
+    const { rel, lang, content, stats } = f;
+    let fileId;
+    let detachedOwners = [];
+    const isTest = isTestPath(rel, w.cfg.testGlobs) ? 1 : 0;
+    const mod = inferModule(rel);
+    if (f.priorId !== null) {
+        w.updFile.run(f.hash, lang.id, isTest, mod, f.mtimeMs, f.size, f.priorId);
+        // Covers: req~edge-ids-survive-reindex~1
+        detachedOwners = detachFileNodes(w, f.priorId);
+        w.delNodes.run(f.priorId);
+        w.delEdges.run(f.priorId);
+        w.delCoverage.run(rel);
+        fileId = f.priorId;
+    }
+    else {
+        fileId = Number(w.insFile.run(rel, f.hash, lang.id, isTest, mod, f.mtimeMs, f.size).lastInsertRowid);
+    }
+    const { symbols, refs, coverage, reexports } = await extract(content, lang);
+    const nodeIds = [];
+    const now = Date.now();
+    for (const s of symbols) {
+        const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
+        const embedText = defaultEmbedText(s.kind, s.name, s.signature);
+        const ch = contentHashFor({
+            lang: lang.id,
+            kind: s.kind,
+            name: s.name,
+            signature: s.signature,
+            embedText,
+        });
+        const id = Number(w.insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash, ch).lastInsertRowid);
+        nodeIds.push(id);
+        w.insMetrics.run(id, s.loc, s.maxNesting, s.branches);
+        w.insNodeText.run(id, s.name, s.subtokens, s.signature ?? "", s.docstring);
+        const hit = w.hasCache.get(ch, w.embedder.id);
+        if (hit) {
+            if (w.touch)
+                w.touchCache.run(now, ch, w.embedder.id);
+            stats.fromCache++;
+        }
+        else {
+            const vec = await w.embedder.embed(embedText);
+            w.insCache.run(ch, w.embedder.id, w.embedder.dim, toBlob(vec), now, now);
+            stats.computed++;
+        }
+        stats.embeddings++;
+    }
+    // Covers: req~impact-id-first~1
+    // Imports and calls outside any definition belong to the file: give the
+    // file one hidden owner node so no edge is ever stored ownerless. A file
+    // with no symbols or with re-exports (a barrel: `export * from "./x"`)
+    // gets one too, so an import of it resolves to the file instead of
+    // looking like a package. It gets no text, embedding, or metrics.
+    const isOrphan = (r) => r.kind === "import" || r.ownerIndex === null;
+    let fileOwner = null;
+    if (refs.some(isOrphan) || symbols.length === 0 || reexports.length > 0) {
+        const lastLine = content.length === 0 ? 1 : content.replace(/\n$/, "").split("\n").length;
+        fileOwner = Number(w.insNode.run(fileId, rel, FILE_NODE_KIND, 1, lastLine, 0, content.length, null, null, null, null, null).lastInsertRowid);
+    }
+    for (const r of refs) {
+        const srcId = isOrphan(r) ? fileOwner : nodeIds[r.ownerIndex];
+        w.insEdge.run(srcId, fileId, r.name, r.kind, r.line, r.member, r.spec);
+        stats.edges++;
+    }
+    const sourceType = inferSourceType(rel);
+    for (const c of coverage) {
+        const nodeId = c.ownerIndex !== null ? nodeIds[c.ownerIndex] : null;
+        w.insCoverage.run(c.artifactType, c.name, c.revision, c.kind, rel, c.line, nodeId, sourceType, "comment");
+    }
+    stats.files++;
+    stats.nodes += symbols.length;
+    return { fileId, detachedOwners };
+}
 /**
  * Build or incrementally refresh the index for a project.
  *
@@ -205,7 +740,7 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
     const maxCacheMB = opts.maxCacheMB ?? DEFAULT_MAX_CACHE_MB;
     const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS;
     const db = openDb(projectPath);
-    const force = Boolean(opts.force) || needsReindex(db);
+    opts.hooks?.onOpen?.(db);
     const embedder = getEmbedder();
     const stats = {
         files: 0,
@@ -223,61 +758,45 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         nextStep: "",
     };
     const cfg = loadAffectedConfig(projectPath);
-    const existing = new Map();
-    for (const row of db.prepare("SELECT id, path, hash, mtime_ms, size FROM files").all()) {
-        existing.set(row.path, {
-            id: row.id,
-            hash: row.hash,
-            mtime_ms: row.mtime_ms,
-            size: row.size,
-        });
-    }
-    const prevRoot = db.prepare("SELECT hash FROM dir_hashes WHERE path = ''").get();
     const seen = new Set();
     const fileHashes = new Map();
-    const insFile = db.prepare("INSERT INTO files(path, hash, lang, is_test, module, mtime_ms, size) VALUES (?, ?, ?, ?, ?, ?, ?)");
-    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ?, mtime_ms = ?, size = ? WHERE id = ?");
-    const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
-    const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
-    const delCoverage = db.prepare("DELETE FROM coverage_links WHERE file_path = ?");
-    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash, content_hash)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    const insMetrics = db.prepare(`INSERT INTO node_metrics(node_id, loc, max_nesting, branches) VALUES (?, ?, ?, ?)`);
-    const insEdge = db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line) VALUES (?, ?, ?, ?, ?)`);
-    const insCoverage = db.prepare(`INSERT OR REPLACE INTO coverage_links(
-       artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    const insCache = db.prepare(`INSERT INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
-     VALUES (?, ?, ?, ?, ?, ?)
-     ON CONFLICT(content_hash, model) DO UPDATE SET last_seen_at = excluded.last_seen_at`);
-    const hasCache = db.prepare(`SELECT 1 AS ok FROM embedding_cache WHERE content_hash = ? AND model = ?`);
-    const insNodeText = db.prepare(`INSERT INTO node_text(node_id, name, subtokens, signature, doc) VALUES (?, ?, ?, ?, ?)
-     ON CONFLICT(node_id) DO UPDATE SET
-       name = excluded.name,
-       subtokens = excluded.subtokens,
-       signature = excluded.signature,
-       doc = excluded.doc`);
+    const w = prepareFileWriter(db, embedder, cfg);
     const allFiles = [...walkFiles(projectPath)];
     // Set inside the transaction; read after it to decide whether the map is written.
     let noop;
-    db.exec("BEGIN");
     try {
-        let done = 0;
-        for (const filePath of allFiles) {
-            const rel = path.relative(projectPath, filePath).split(path.sep).join("/");
-            done++;
-            if (onProgress)
-                onProgress({ file: rel, done, total: allFiles.length });
+        await opts.hooks?.afterWalk?.();
+        // Take the write lock before reading the stored file set: a per-file
+        // reindex committing a new file's row between that read and this run's
+        // insert would otherwise fail the whole run on the unique path. Per-file
+        // runs wait for (or give up on) this lock instead. Inside the try so a
+        // SQLITE_BUSY here still closes the connection.
+        db.exec("BEGIN IMMEDIATE");
+        const force = Boolean(opts.force) || needsReindex(db);
+        const existing = new Map();
+        for (const row of db
+            .prepare("SELECT id, path, hash, mtime_ms, size FROM files")
+            .all()) {
+            existing.set(row.path, {
+                id: row.id,
+                hash: row.hash,
+                mtime_ms: row.mtime_ms,
+                size: row.size,
+            });
+        }
+        const prevRoot = db.prepare("SELECT hash FROM dir_hashes WHERE path = ''").get();
+        // Stat, hash, and (when changed) re-extract one walked file.
+        const visit = async (filePath, rel) => {
             seen.add(rel);
             const lang = langForPath(filePath);
             let stat;
             try {
                 stat = fs.statSync(filePath);
                 if (stat.size > MAX_FILE_BYTES)
-                    continue;
+                    return;
             }
             catch {
-                continue;
+                return;
             }
             const prior = existing.get(rel);
             const mtimeMs = Math.trunc(stat.mtimeMs);
@@ -291,89 +810,60 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
                 fileHashes.set(rel, prior.hash);
                 stats.skippedByStat++;
                 stats.unchanged++;
-                continue;
+                return;
             }
             let content;
             try {
                 content = fs.readFileSync(filePath, "utf8");
             }
             catch {
-                continue;
+                return;
             }
             const hash = hashOf(content);
             fileHashes.set(rel, hash);
             if (!force && prior && prior.hash === hash) {
-                updFile.run(hash, lang.id, isTestPath(rel, cfg.testGlobs) ? 1 : 0, inferModule(rel), mtimeMs, size, prior.id);
+                w.updFile.run(hash, lang.id, isTestPath(rel, cfg.testGlobs) ? 1 : 0, inferModule(rel), mtimeMs, size, prior.id);
                 stats.unchanged++;
-                continue;
-            }
-            let fileId;
-            const isTest = isTestPath(rel, cfg.testGlobs) ? 1 : 0;
-            const mod = inferModule(rel);
-            if (prior) {
-                updFile.run(hash, lang.id, isTest, mod, mtimeMs, size, prior.id);
-                delNodes.run(prior.id);
-                delEdges.run(prior.id);
-                delCoverage.run(rel);
-                fileId = prior.id;
-            }
-            else {
-                fileId = Number(insFile.run(rel, hash, lang.id, isTest, mod, mtimeMs, size).lastInsertRowid);
+                return;
             }
-            const { symbols, refs, coverage } = await extract(content, lang);
-            const nodeIds = [];
-            const now = Date.now();
-            const touchCache = db.prepare(`UPDATE embedding_cache SET last_seen_at = ? WHERE content_hash = ? AND model = ?`);
-            for (const s of symbols) {
-                const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
-                const embedText = defaultEmbedText(s.kind, s.name, s.signature);
-                const ch = contentHashFor({
-                    lang: lang.id,
-                    kind: s.kind,
-                    name: s.name,
-                    signature: s.signature,
-                    embedText,
-                });
-                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash, ch).lastInsertRowid);
-                nodeIds.push(id);
-                insMetrics.run(id, s.loc, s.maxNesting, s.branches);
-                insNodeText.run(id, s.name, s.subtokens, s.signature ?? "", s.docstring);
-                const hit = hasCache.get(ch, embedder.id);
-                if (hit) {
-                    touchCache.run(now, ch, embedder.id);
-                    stats.fromCache++;
-                }
-                else {
-                    const vec = await embedder.embed(embedText);
-                    insCache.run(ch, embedder.id, embedder.dim, toBlob(vec), now, now);
-                    stats.computed++;
-                }
-                stats.embeddings++;
-            }
-            const fileOwner = nodeIds[0] ?? null;
-            for (const r of refs) {
-                let srcId = r.ownerIndex !== null ? nodeIds[r.ownerIndex] : null;
-                if (srcId === null && r.kind === "import")
-                    srcId = fileOwner;
-                insEdge.run(srcId, fileId, r.name, r.kind, r.line);
-                stats.edges++;
-            }
-            const sourceType = inferSourceType(rel);
-            for (const c of coverage) {
-                const nodeId = c.ownerIndex !== null ? nodeIds[c.ownerIndex] : null;
-                insCoverage.run(c.artifactType, c.name, c.revision, c.kind, rel, c.line, nodeId, sourceType, "comment");
-            }
-            stats.files++;
-            stats.nodes += symbols.length;
+            await writeFileFragment(w, {
+                rel,
+                lang,
+                content,
+                hash,
+                mtimeMs,
+                size,
+                priorId: prior?.id ?? null,
+                stats,
+            });
+        };
+        let done = 0;
+        for (const filePath of allFiles) {
+            const rel = path.relative(projectPath, filePath).split(path.sep).join("/");
+            done++;
+            if (onProgress)
+                onProgress({ file: rel, done, total: allFiles.length });
+            await visit(filePath, rel);
         }
+        const listings = new Map();
         for (const [rel, row] of existing) {
             if (!seen.has(rel)) {
-                db.prepare("DELETE FROM files WHERE id = ?").run(row.id);
-                stats.removed++;
+                // The walk ran before the lock: a per-file reindex may have committed
+                // a row for a file created after the walk passed its directory. Keep
+                // and index a row only when the walk would now yield that exact path;
+                // drop the rest (deleted, ineligible, renamed by case only, or reached
+                // only through a symlink) so no file is held under two paths.
+                const abs = path.join(projectPath, rel);
+                if (!walkWouldYield(projectPath, rel, listings)) {
+                    // Covers: req~edge-ids-survive-reindex~1
+                    removeFileRows(w, row.id, rel);
+                    stats.removed++;
+                    continue;
+                }
+                await visit(abs, rel);
             }
-            else if (!fileHashes.has(rel)) {
+            if (!fileHashes.has(rel))
                 fileHashes.set(rel, row.hash);
-            }
         }
         const dirMap = buildDirHashMap(fileHashes);
         const rootHash = dirMap.get("") ?? "";
@@ -384,7 +874,14 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         // would write — skip them so a run on every session start stays cheap.
         // `rootUnchanged` already implies no force (explicit or needs_reindex); an
         // explicit prune or cache cap is a maintenance request and runs in full.
-        noop = stats.rootUnchanged && !prune && opts.maxCacheMB === undefined && stats.removed === 0;
+        // A per-file reindex already moved the stored hashes to match the tree but
+        // deferred PageRank and the map to here: its marker disables the fast path.
+        noop =
+            stats.rootUnchanged &&
+                !prune &&
+                opts.maxCacheMB === undefined &&
+                stats.removed === 0 &&
+                !postPending(db);
         if (!noop) {
             const now = Date.now();
             db.prepare("DELETE FROM dir_hashes").run();
@@ -393,17 +890,9 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
                 const nFiles = [...fileHashes.keys()].filter((f) => dir === "" ? true : f === dir || f.startsWith(dir + "/")).length;
                 insDir.run(dir, hash, nFiles, now);
             }
-            db.exec(`
-        UPDATE edges SET dst_node_id = (
-          SELECT n.id FROM nodes n
-          WHERE n.name = edges.dst_name
-          ORDER BY CASE WHEN n.file_id = edges.src_file_id THEN 0 ELSE 1 END, n.id
-          LIMIT 1
-        )
-        WHERE kind = 'call' AND dst_node_id IS NULL
-      `);
-            resolveImportEdges(db, projectPath);
+            resolveEdges(db);
             recomputeGlobalPagerank(db);
+            clearPostPending(db);
             // Touch last_seen for all live content hashes under active model
             db.prepare(`UPDATE embedding_cache SET last_seen_at = ?
          WHERE model = ?
@@ -426,7 +915,10 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         db.exec("COMMIT");
     }
     catch (err) {
-        db.exec("ROLLBACK");
+        // SQLite may already have rolled back (or BEGIN never succeeded): an
+        // unguarded ROLLBACK would throw and mask the original error.
+        if (db.isTransaction)
+            db.exec("ROLLBACK");
         throw err;
     }
     finally {
@@ -444,9 +936,206 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
     }
     return stats;
 }
+/**
+ * Re-index exactly the given files in an existing, current index — the
+ * per-edit path behind `speclaw reindex-file`.
+ *
+ * Inside one `BEGIN IMMEDIATE` transaction (so each file is read after the
+ * write lock is held, and the last run to begin saw the last edit), each path
+ * is classified with the full walk's rules ({@link classifyIndexPath}): a
+ * changed file is re-extracted with the same fragment writer as
+ * {@link buildIndex}, a deleted file's rows are dropped, an unchanged file only
+ * refreshes its stat columns, and anything else is skipped. Edges are then
+ * resolved by {@link resolveEdges} scoped to the re-indexed files plus the files
+ * whose edges were detached from them (that scope also re-tries NULL edges that
+ * name a symbol the re-indexed files now define), and the directory hashes of
+ * the touched files' ancestors are recomputed.
+ *
+ * Global post-processing is deferred: no PageRank recomputation (the old rows of
+ * replaced nodes drop by cascade; new symbols have none until the next full
+ * run), no embedding-cache touch or eviction, no `docs/compass.md` write, no
+ * `meta.indexed_at` change, and no Compass call log entry. When it writes any
+ * row it sets `meta.post_pending`, which makes the next full run skip its no-op
+ * fast path and do that work.
+ *
+ * Caveat inherited from scoped resolution: an edge already bound to a node
+ * elsewhere is never re-ranked, so when an edit adds a better candidate for an
+ * ambiguous name the old binding stays until the next full run that re-extracts
+ * the calling file.
+ *
+ * Never creates, migrates, or wipes the database: a missing index or one that
+ * needs a full reindex returns `stale: true` with nothing written.
+ *
+ * @param projectPath - Absolute project root.
+ * @param paths - File paths, absolute or relative to `projectPath`.
+ * @throws When the database stays locked past the busy timeout (`SQLITE_BUSY`) or a write fails; the transaction is rolled back.
+ */
+export async function indexFiles(projectPath, paths) {
+    // Covers: req~reindex-on-edit~1
+    const result = {
+        reindexed: [],
+        removed: [],
+        unchanged: [],
+        skipped: [],
+        stale: false,
+    };
+    const db = openCurrentDb(projectPath);
+    if (!db) {
+        result.stale = true;
+        return result;
+    }
+    try {
+        const embedder = getEmbedder();
+        const w = prepareFileWriter(db, embedder, loadAffectedConfig(projectPath), false);
+        const getFile = db.prepare("SELECT id, hash FROM files WHERE path = ?");
+        const stats = {
+            files: 0,
+            nodes: 0,
+            edges: 0,
+            embeddings: 0,
+            computed: 0,
+            fromCache: 0,
+        };
+        const scope = new Set();
+        const changed = [];
+        const targets = [...new Set(paths.map((p) => path.resolve(projectPath, p)))];
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            // The probe ran before the lock: a full run (or another version) may
+            // have migrated, wiped, or flagged the index since. Re-check under the
+            // lock and leave it to the next full run if so.
+            if (!isCurrentIndex(db)) {
+                db.exec("ROLLBACK");
+                result.stale = true;
+                return result;
+            }
+            for (const abs of targets) {
+                let c = classifyIndexPath(projectPath, abs);
+                // Register only the path a full walk would yield (exact spelling, no
+                // symlink segment); a full run would otherwise drop the row again.
+                if (c.eligible && !walkWouldYield(projectPath, c.rel)) {
+                    c = { eligible: false, rel: c.rel, reason: "ignored" };
+                }
+                if (!c.eligible) {
+                    const row = c.reason === "missing" && c.rel !== null
+                        ? getFile.get(c.rel)
+                        : undefined;
+                    if (row && c.rel !== null) {
+                        // Covers: req~edge-ids-survive-reindex~1
+                        for (const id of removeFileRows(w, row.id, c.rel))
+                            scope.add(id);
+                        result.removed.push(c.rel);
+                        changed.push(c.rel);
+                    }
+                    else {
+                        result.skipped.push({ path: c.rel ?? abs, reason: c.reason });
+                    }
+                    continue;
+                }
+                let content;
+                try {
+                    content = fs.readFileSync(path.join(projectPath, c.rel), "utf8");
+                }
+                catch {
+                    result.skipped.push({ path: c.rel, reason: "missing" });
+                    continue;
+                }
+                const hash = hashOf(content);
+                const prior = getFile.get(c.rel);
+                if (prior && prior.hash === hash) {
+                    w.updFile.run(hash, c.lang.id, isTestPath(c.rel, w.cfg.testGlobs) ? 1 : 0, inferModule(c.rel), c.mtimeMs, c.size, prior.id);
+                    result.unchanged.push(c.rel);
+                    continue;
+                }
+                const written = await writeFileFragment(w, {
+                    rel: c.rel,
+                    lang: c.lang,
+                    content,
+                    hash,
+                    mtimeMs: c.mtimeMs,
+                    size: c.size,
+                    priorId: prior?.id ?? null,
+                    stats,
+                });
+                scope.add(written.fileId);
+                for (const id of written.detachedOwners)
+                    scope.add(id);
+                result.reindexed.push(c.rel);
+                changed.push(c.rel);
+            }
+            if (changed.length > 0) {
+                resolveEdges(db, [...scope]);
+                updateAncestorDirHashes(db, changed);
+                setPostPending(db);
+            }
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    finally {
+        db.close();
+    }
+    return result;
+}
+/**
+ * Recompute the `dir_hashes` rows of every ancestor directory of the given
+ * files (deepest first, root last) from the stored `files.hash` values and the
+ * child directory rows, with the same hash rule and `n_files` count as the full
+ * walk ({@link buildDirHashMap}). A directory left with no indexed file loses
+ * its row; the root row always exists.
+ */
+function updateAncestorDirHashes(db, rels) {
+    const dirs = new Set([""]);
+    for (const rel of rels) {
+        const parts = rel.split("/");
+        for (let i = 1; i < parts.length; i++)
+            dirs.add(parts.slice(0, i).join("/"));
+    }
+    const depth = (d) => (d === "" ? 0 : d.split("/").length);
+    const ordered = [...dirs].sort((a, b) => depth(b) - depth(a));
+    const all = db.prepare("SELECT path, hash FROM files");
+    // '/' + 1 is '0': [dir/, dir0) is every path under dir/ in byte order.
+    const under = db.prepare("SELECT path, hash FROM files WHERE path >= ? AND path < ?");
+    const dirRow = db.prepare("SELECT hash FROM dir_hashes WHERE path = ?");
+    const upsert = db.prepare(`INSERT INTO dir_hashes(path, hash, n_files, updated_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT(path) DO UPDATE SET hash = excluded.hash, n_files = excluded.n_files,
+       updated_at = excluded.updated_at`);
+    const del = db.prepare("DELETE FROM dir_hashes WHERE path = ?");
+    const now = Date.now();
+    for (const dir of ordered) {
+        const prefix = dir === "" ? "" : `${dir}/`;
+        const rows = (dir === "" ? all.all() : under.all(prefix, `${dir}0`));
+        if (rows.length === 0 && dir !== "") {
+            del.run(dir);
+            continue;
+        }
+        const children = new Map();
+        for (const r of rows) {
+            const rest = r.path.slice(prefix.length);
+            const slash = rest.indexOf("/");
+            if (slash < 0) {
+                children.set(rest, r.hash);
+            }
+            else {
+                const name = rest.slice(0, slash);
+                if (!children.has(name)) {
+                    const sub = dirRow.get(prefix + name);
+                    children.set(name, sub?.hash ?? HASH_EMPTY);
+                }
+            }
+        }
+        const hash = dirHash([...children].map(([name, h]) => ({ name, hash: h })));
+        upsert.run(dir, hash, rows.length, now);
+    }
+}
 function countTotals(db) {
     const count = (table) => Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
-    return { files: count("files"), nodes: count("nodes"), edges: count("edges") };
+    const nodes = Number(db.prepare(`SELECT COUNT(*) AS n FROM nodes WHERE kind <> '${FILE_NODE_KIND}'`).get().n);
+    return { files: count("files"), nodes, edges: count("edges") };
 }
 /** Next-step hint printed after an index run; names the query tools, not grep. */
 export function indexNextStep(totals) {
@@ -482,7 +1171,11 @@ function evictCacheBySize(db, maxCacheMB) {
  */
 export function recomputeGlobalPagerank(db) {
     const files = db.prepare("SELECT id, path FROM files").all();
-    const nodes = db.prepare("SELECT id, name, file_id FROM nodes").all();
+    // File-owner nodes are not ranked symbols; their outgoing calls count as
+    // references from their file in the file–symbol graph.
+    const nodes = db
+        .prepare(`SELECT id, name, file_id FROM nodes WHERE kind <> '${FILE_NODE_KIND}'`)
+        .all();
     if (nodes.length === 0) {
         db.exec("DELETE FROM pagerank");
         return;
@@ -499,10 +1192,12 @@ export function recomputeGlobalPagerank(db) {
         defCount.set(n.name, (defCount.get(n.name) ?? 0) + 1);
     const refCount = new Map();
     const callEdges = db
-        .prepare(`SELECT e.src_node_id, e.dst_node_id, e.dst_name, f.path AS src_path
+        .prepare(`SELECT e.src_node_id, e.src_file_id, src.kind AS src_kind, e.dst_node_id, e.dst_name,
+              f.path AS src_path
        FROM edges e
        JOIN files f ON f.id = e.src_file_id
-       WHERE e.kind = 'call' AND e.src_node_id IS NOT NULL`)
+       JOIN nodes src ON src.id = e.src_node_id
+       WHERE e.kind = 'call'`)
         .all();
     for (const e of callEdges) {
         refCount.set(e.dst_name, (refCount.get(e.dst_name) ?? 0) + 1);
@@ -521,7 +1216,8 @@ export function recomputeGlobalPagerank(db) {
         if (e.dst_node_id == null)
             continue;
         const w = edgeWeightMul(e.dst_name, e.src_path, ctx);
-        edges.push({ from: e.src_node_id, to: e.dst_node_id, weight: w });
+        const from = e.src_kind === FILE_NODE_KIND ? fileNodeId(e.src_file_id) : e.src_node_id;
+        edges.push({ from, to: e.dst_node_id, weight: w });
     }
     const scores = personalizedPageRank(nodeIds, edges, []);
     db.exec("DELETE FROM pagerank");