@esneiderbravo/speclaw 2.0.10 → 2.0.12

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, FILE_NODE_KIND } 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, 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,6 +31,132 @@ 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");
 }
@@ -431,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()) {
@@ -441,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.
  *
@@ -467,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,
@@ -485,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, is_member, spec) 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);
@@ -553,98 +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, reexports } = 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++;
-            }
-            // 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(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];
-                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;
-                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("") ?? "";
@@ -655,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();
@@ -666,6 +892,7 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
             }
             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 = ?
@@ -688,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 {
@@ -706,6 +936,202 @@ 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);
     const nodes = Number(db.prepare(`SELECT COUNT(*) AS n FROM nodes WHERE kind <> '${FILE_NODE_KIND}'`).get().n);