@esneiderbravo/speclaw 2.0.9 → 2.0.11

package/dist/modules/compass/affected.js

@@ -1,13 +1,13 @@
 /**
  * Static affected-test selection: reverse reachability into `files.is_test = 1`,
- * plus a ready-to-run command string.
+ * plus ready-to-run commands per package (runner detected from `package.json`).
  */
 import fs from "node:fs";
 import path from "node:path";
 import { changedFiles, isGitRepo } from "../../shared/git.js";
 import { openDb, indexExists } from "./db.js";
 import { impact } from "./query.js";
-import { loadAffectedConfig, matchGlobalFiles, matchesAny, } from "./affected-config.js";
+import { loadAffectedConfig, matchGlobalFiles, matchesAny, matchGlob, } from "./affected-config.js";
 /**
  * Select a safe superset of test files affected by a change.
  *
@@ -40,7 +40,7 @@ export function affectedTests(projectPath, query = {}) {
                 reason: "no changed files",
                 tests: [],
                 skipped: { files: countTestFiles(projectPath), percent: 100 },
-                command: buildTestCommand(projectPath, [], cfg, "none"),
+                ...planTestCommand(projectPath, [], "none"),
                 warnings,
             };
         }
@@ -48,12 +48,13 @@ export function affectedTests(projectPath, query = {}) {
     const glob = matchGlobalFiles(files, cfg);
     if (glob.matched.length > 0) {
         const allTests = listTestFiles(projectPath);
+        const reason = `global file matched (${glob.matched.join(", ")})`;
         return {
             mode: "all",
-            reason: `global file matched (${glob.matched.join(", ")})`,
+            reason,
             tests: allTests.map((file) => ({ file, nodes: 0, minDepth: 0 })),
             skipped: { files: 0, percent: 0 },
-            command: buildTestCommand(projectPath, [], cfg, "all"),
+            ...planTestCommand(projectPath, [], "all", reason),
             warnings,
         };
     }
@@ -125,7 +126,7 @@ export function affectedTests(projectPath, query = {}) {
                 : "empty selection",
         tests,
         skipped: { files: skippedFiles, percent },
-        command: buildTestCommand(projectPath, tests.map((t) => t.file), cfg, tests.length === 0 ? "none" : "subset"),
+        ...planTestCommand(projectPath, tests.map((t) => t.file), tests.length === 0 ? "none" : "subset"),
         warnings,
     };
 }
@@ -160,43 +161,359 @@ function listTestFiles(projectPath) {
     }
 }
 /**
- * Build an executable test command from package.json scripts.test when present.
+ * Build the command for a selection as a single string (see {@link planTestCommand}).
  *
  * @param projectPath - Project root.
- * @param tests - Selected test paths (ignored for mode `all`).
+ * @param tests - Selected repo-relative test paths (ignored for mode `all`).
  * @param _cfg - Reserved for future runner overrides.
  * @param mode - `all` | `subset` | `none`.
+ * @returns The command to run from the root, or null when nothing is selected.
  */
 export function buildTestCommand(projectPath, tests, _cfg, mode) {
-    const pkgPath = path.join(projectPath, "package.json");
-    let script;
-    if (fs.existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-            script = pkg.scripts?.test;
-        }
-        catch {
-            /* ignore */
-        }
+    return planTestCommand(projectPath, tests, mode).command;
+}
+/** Read a `package.json`; null when absent or unparseable. */
+function readPackage(dir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
     }
+}
+/**
+ * Turn a selection into runnable commands.
+ *
+ * - `none`: `command` is null with a reason; a run-nothing command is never emitted.
+ * - `all`: the root runner's full suite.
+ * - `subset`: files are grouped by their nearest `package.json` directory
+ *   (bounded by the root) and each group gets its own runner's command:
+ *   `npx vitest run`, `npx jest --runTestsByPath`, the `node --test` script's
+ *   flags without coverage flags (mapped onto a compiled-test glob, after
+ *   `npm run pretest`), or `npm test -- <files>` for an unrecognized script.
+ *   Several groups compose as `(cd a && …) && (cd b && …)` from the root.
+ *
+ * @param projectPath - Project root.
+ * @param tests - Selected repo-relative test paths (ignored unless `subset`).
+ * @param mode - `all` | `subset` | `none`.
+ * @param allReason - Why the full suite was selected (mode `all`).
+ * @returns The command plan; `commands` is empty exactly when `command` is null.
+ */
+export function planTestCommand(projectPath, tests, mode, allReason = "the full suite was selected") {
+    // Covers: req~affected-test-selection~1
     if (mode === "all") {
-        return script ? "npm test" : "node --test";
+        const command = fullSuiteCommand(readPackage(projectPath));
+        return {
+            command,
+            commandReason: `${allReason}; run the full suite`,
+            commands: [{ cwd: ".", command, files: [] }],
+        };
     }
     if (mode === "none" || tests.length === 0) {
-        return script ? "npm test -- --test-name-pattern=^$" : "node --test --test-name-pattern=^$";
+        return {
+            command: null,
+            commandReason: "no test file is reachable from the change; nothing to run",
+            commands: [],
+        };
+    }
+    const groups = new Map();
+    const nearest = new Map();
+    for (const t of [...tests].sort()) {
+        const cwd = nearestPackageDir(projectPath, path.posix.dirname(t), nearest);
+        const rel = cwd === "." ? t : t.slice(cwd.length + 1);
+        groups.set(cwd, [...(groups.get(cwd) ?? []), rel]);
+    }
+    const commands = [];
+    const notes = [];
+    const runners = [];
+    for (const cwd of [...groups.keys()].sort()) {
+        const files = groups.get(cwd);
+        const own = readPackage(path.join(projectPath, cwd));
+        const inherited = inheritedRunner(projectPath, cwd, own);
+        const plan = groupCommand(inherited?.pkg ?? own, files);
+        if (inherited) {
+            const from = inherited.dir === "." ? "the root package.json" : `${inherited.dir}/package.json`;
+            plan.note = [`${plan.runner} inherited from ${from}`, plan.note]
+                .filter((n) => n !== undefined)
+                .join("; ");
+        }
+        if (plan.note)
+            notes.push(cwd === "." ? plan.note : `${cwd}: ${plan.note}`);
+        if (plan.command === null)
+            continue;
+        commands.push({ cwd, command: plan.command, files: plan.kept ?? files });
+        runners.push(`${cwd}: ${plan.runner}`);
+    }
+    if (commands.length === 0) {
+        return {
+            command: null,
+            commandReason: `no runnable test file is selected; ${notes.join("; ")}`,
+            commands: [],
+        };
+    }
+    const command = commands.length === 1
+        ? commands[0].cwd === "."
+            ? commands[0].command
+            : `cd ${shellQuote(commands[0].cwd)} && ${commands[0].command}`
+        : commands
+            .map((c) => c.cwd === "." ? `(${c.command})` : `(cd ${shellQuote(c.cwd)} && ${c.command})`)
+            .join(" && ");
+    const head = commands.length === 1
+        ? `${runners[0].split(": ")[1]} in ${commands[0].cwd} for ${tests.length} selected test file(s)`
+        : `${tests.length} selected test file(s) across ${commands.length} packages (${runners.join(", ")}); run from the repository root`;
+    return {
+        command,
+        commandReason: [head, ...notes].join("; "),
+        commands,
+    };
+}
+/** Full-suite command for a package (root `all` mode). */
+function fullSuiteCommand(pkg) {
+    if (pkg?.scripts?.test)
+        return "npm test";
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    if (deps.vitest)
+        return "npx vitest run";
+    if (deps.jest)
+        return "npx jest";
+    return "node --test";
+}
+/** Nearest directory at or above `dir` (repo-relative) holding a `package.json`; `.` at worst. */
+function nearestPackageDir(root, dir, cache) {
+    const hit = cache.get(dir);
+    if (hit !== undefined)
+        return hit;
+    let found;
+    if (dir === "." || dir === "" || dir === "/")
+        found = ".";
+    else if (fs.existsSync(path.join(root, dir, "package.json")))
+        found = dir;
+    else
+        found = nearestPackageDir(root, path.posix.dirname(dir), cache);
+    cache.set(dir, found);
+    return found;
+}
+/** Whether a package declares vitest or jest as a dependency. */
+function declaresRunner(pkg) {
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    return Boolean(deps.vitest || deps.jest);
+}
+/**
+ * Runner inherited by a package that declares none (no `scripts.test`, no
+ * vitest/jest dependency): the nearest ancestor `package.json`, up to the
+ * root, that declares vitest or jest — the hoisted-monorepo layout. Returns
+ * the package to plan with (the leaf with the ancestor's runner dependencies)
+ * and the ancestor's directory, or null when nothing is inherited.
+ */
+function inheritedRunner(root, cwd, own) {
+    if (cwd === "." || own?.scripts?.test || declaresRunner(own))
+        return null;
+    let dir = cwd;
+    while (dir !== ".") {
+        dir = path.posix.dirname(dir);
+        if (dir === "" || dir === "/")
+            dir = ".";
+        const anc = readPackage(path.join(root, dir));
+        if (!declaresRunner(anc))
+            continue;
+        const deps = { ...anc?.dependencies, ...anc?.devDependencies };
+        const runnerDeps = {};
+        if (deps.vitest)
+            runnerDeps.vitest = deps.vitest;
+        if (deps.jest)
+            runnerDeps.jest = deps.jest;
+        return {
+            pkg: { ...own, devDependencies: { ...own?.devDependencies, ...runnerDeps } },
+            dir,
+        };
+    }
+    return null;
+}
+/** Flags dropped from a `node --test` script: coverage thresholds fail on a subset. */
+function isCoverageFlag(token) {
+    return token === "--experimental-test-coverage" || token.startsWith("--test-coverage-");
+}
+/** Node flags whose value may follow as a separate word (`--import ./x.mjs`). */
+const NODE_VALUE_FLAGS = new Set([
+    "--import",
+    "--require",
+    "-r",
+    "--loader",
+    "--experimental-loader",
+    "--env-file",
+    "--conditions",
+    "-C",
+    "--test-reporter",
+    "--test-reporter-destination",
+    "--test-name-pattern",
+    "--test-skip-pattern",
+    "--test-concurrency",
+    "--test-timeout",
+    "--test-shard",
+    "--test-coverage-lines",
+    "--test-coverage-branches",
+    "--test-coverage-functions",
+    "--test-coverage-include",
+    "--test-coverage-exclude",
+]);
+/**
+ * Split a `node --test` script's words (after `node`) into the flags to keep
+ * and the positional test globs. A value-taking flag keeps its value with it;
+ * coverage flags are dropped together with their values. A directory
+ * positional (no glob character, no file extension) becomes `<dir>/**`, so it
+ * matches every file under it.
+ */
+function splitNodeTestArgs(words) {
+    const flags = [];
+    const globs = [];
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        if (word.startsWith("-")) {
+            const group = [word];
+            if (!word.includes("=") && NODE_VALUE_FLAGS.has(word) && i + 1 < words.length) {
+                group.push(words[++i]);
+            }
+            if (!isCoverageFlag(word))
+                flags.push(...group);
+            continue;
+        }
+        const isDir = !/[*?{[]/.test(word) && !/\.[cm]?[jt]sx?$/.test(word);
+        globs.push(isDir ? `${word.replace(/\/+$/, "")}/**` : word);
     }
-    const args = tests.map(shellQuote).join(" ");
-    if (script && /\bnode\s+--test\b/.test(script)) {
-        return `node --test ${args}`;
+    return { flags, globs };
+}
+/** Source extensions mapped to their compiled JavaScript counterparts. */
+const COMPILED_EXT = [
+    [/\.tsx?$/, ".js"],
+    [/\.mts$/, ".mjs"],
+    [/\.cts$/, ".cjs"],
+];
+/** Source path with its TypeScript extension swapped for the compiled one. */
+function compiledPath(file) {
+    let out = file;
+    for (const [re, ext] of COMPILED_EXT)
+        out = out.replace(re, ext);
+    return out;
+}
+/**
+ * Map a source test path onto the script's globs: the path itself when a glob
+ * matches it, else `<first glob segment>/<compiled path>` when that matches.
+ * `helper` marks a file whose name no glob's last segment can match (e.g.
+ * `test/helpers/fixtures.ts` against `*.test.js`): the runner never executes it,
+ * not even in a full run, so it is left out rather than forcing the full suite.
+ * `null` means a test-shaped file that could not be mapped.
+ */
+function mapOntoGlobs(file, globs) {
+    if (globs.some((g) => matchGlob(file, g)))
+        return file;
+    const base = path.posix.basename(file);
+    const testShaped = globs.some((g) => {
+        const last = g.split("/").pop() ?? g;
+        return matchGlob(base, last) || matchGlob(compiledPath(base), last);
+    });
+    if (!testShaped)
+        return "helper";
+    for (const glob of globs) {
+        const first = glob.split("/")[0];
+        if (!first || /[*{]/.test(first))
+            continue;
+        const mapped = `${first}/${compiledPath(file)}`;
+        if (matchGlob(mapped, glob))
+            return mapped;
+    }
+    return null;
+}
+/**
+ * Command for one package group, with its detected runner and an optional note.
+ * `command` is null only when every file is a helper the runner never executes;
+ * `kept` lists the files the command runs when helpers were left out.
+ */
+function groupCommand(pkg, files) {
+    const script = pkg?.scripts?.test;
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const args = files.map(shellQuote).join(" ");
+    const tokens = script ? shellSplit(script) : [];
+    const isNodeTest = tokens[0] === "node" && tokens.includes("--test");
+    if ((script && /\bvitest\b/.test(script)) || (!script && deps.vitest)) {
+        return { command: `npx vitest run ${args}`, runner: "vitest" };
+    }
+    if ((script && /\bjest\b/.test(script)) || (!isNodeTest && deps.jest)) {
+        return { command: `npx jest --runTestsByPath ${args}`, runner: "jest" };
+    }
+    if (isNodeTest) {
+        const { flags, globs } = splitNodeTestArgs(tokens.slice(1));
+        const base = ["node", ...flags].map(shellQuote).join(" ");
+        if (globs.length === 0)
+            return { command: `${base} ${args}`, runner: "node --test" };
+        const mapped = files.map((f) => mapOntoGlobs(f, globs));
+        if (mapped.some((m) => m === null)) {
+            return {
+                command: "npm test",
+                runner: "node --test",
+                note: "a selected test file does not fit the test script's glob, so the full suite runs (a safe superset)",
+            };
+        }
+        const runnable = mapped.filter((m) => m !== null && m !== "helper");
+        const kept = files.filter((_, i) => mapped[i] !== "helper");
+        const helpers = mapped.length - runnable.length;
+        const helperNote = helpers > 0 ? `${helpers} helper file(s) the test script never runs left out` : undefined;
+        if (runnable.length === 0)
+            return { command: null, runner: "node --test", note: helperNote };
+        const compiled = runnable.some((m) => !files.includes(m));
+        const prefix = compiled && pkg?.scripts?.pretest ? "npm run pretest && " : "";
+        const notes = [
+            compiled ? "files mapped onto the compiled test glob; coverage flags dropped" : undefined,
+            helperNote,
+        ].filter((n) => n !== undefined);
+        return {
+            command: `${prefix}${base} ${runnable.map(shellQuote).join(" ")}`,
+            runner: "node --test",
+            note: notes.length > 0 ? notes.join("; ") : undefined,
+            kept,
+        };
     }
     if (script) {
-        // Pass paths after `--` for npm/vitest/jest-style scripts.
-        return `npm test -- ${args}`;
+        return {
+            command: `npm test -- ${args}`,
+            runner: "npm test",
+            note: "unrecognized test script: paths are forwarded and it may run the full suite (a superset)",
+        };
+    }
+    return { command: `node --test ${args}`, runner: "node --test" };
+}
+/** Split a shell command line into words, honoring single and double quotes. */
+function shellSplit(line) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    let has = false;
+    for (const ch of line) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                cur += ch;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            has = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (has || cur)
+                out.push(cur);
+            cur = "";
+            has = false;
+        }
+        else {
+            cur += ch;
+        }
     }
-    return `node --test ${args}`;
+    if (has || cur)
+        out.push(cur);
+    return out;
 }
 function shellQuote(p) {
-    if (/^[A-Za-z0-9_./-]+$/.test(p))
+    if (/^[A-Za-z0-9_./=:,@+-]+$/.test(p))
         return p;
     return `'${p.replace(/'/g, `'\\''`)}'`;
 }

package/dist/modules/compass/db.js

@@ -48,6 +48,13 @@ CREATE TABLE IF NOT EXISTS node_metrics (
   branches INTEGER NOT NULL
 );
 -- edges: a reference from one node to a named target, resolved lazily.
+-- src_node_id is never NULL for an edge indexed under schema 11: a reference
+-- outside any definition is owned by its file's file-owner node (kind 'file').
+-- is_member = 1 marks a member call on a foreign receiver (never bound by name);
+-- 2 a member call on an import binding, bound only once the import with the
+-- same spec in the same file resolves to a project file (a package otherwise).
+-- spec: JS/TS module specifier of an import edge, or of the import binding a
+-- call's receiver/callee comes from.
 CREATE TABLE IF NOT EXISTS edges (
   id INTEGER PRIMARY KEY,
   src_node_id INTEGER REFERENCES nodes(id) ON DELETE CASCADE,
@@ -55,9 +62,12 @@ CREATE TABLE IF NOT EXISTS edges (
   dst_name TEXT NOT NULL,
   dst_node_id INTEGER,
   kind TEXT NOT NULL,
-  line INTEGER NOT NULL
+  line INTEGER NOT NULL,
+  is_member INTEGER NOT NULL DEFAULT 0,
+  spec TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst_name);
+CREATE INDEX IF NOT EXISTS idx_edges_srcfile ON edges(src_file_id, kind);
 CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src_node_id);
 CREATE INDEX IF NOT EXISTS idx_edges_dstid ON edges(dst_node_id);
 -- embedding_cache: vectors keyed by embedder-input content hash (survives reindex).
@@ -224,7 +234,13 @@ export function probeFts5Support() {
     }
 }
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "10";
+export const SCHEMA_VERSION = "11";
+/**
+ * `nodes.kind` of the synthetic per-file owner node. It owns the references that
+ * sit outside any definition (top-level imports, calls in callbacks) and is
+ * hidden from find, name lookup, PageRank, FTS, embeddings, and metrics.
+ */
+export const FILE_NODE_KIND = "file";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -237,7 +253,7 @@ function readSchemaVersion(db) {
 }
 /**
  * Decide whether an existing database is from an incompatible schema and must be
- * rebuilt. Schema 8→9 and 9→10 are handled by migrators instead of a wipe.
+ * rebuilt. Schema 8→9, 9→10, and 10→11 are handled by migrators instead of a wipe.
  */
 function isStale(db) {
     const hasEdges = db
@@ -246,13 +262,19 @@ function isStale(db) {
     if (!hasEdges)
         return false;
     const ver = readSchemaVersion(db);
-    if (ver === "8" || ver === "9")
+    if (ver === "8" || ver === "9" || ver === "10")
         return false; // migrate in openDb
+    if (ver === "11" && !hasEdgeSpec(db))
+        return false; // pre-release 11: migrate in openDb
     if (ver !== SCHEMA_VERSION)
         return true;
     const edgeCols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
-    if (!edgeCols.includes("src_node_id") || !edgeCols.includes("dst_node_id"))
+    if (!edgeCols.includes("src_node_id") ||
+        !edgeCols.includes("dst_node_id") ||
+        !edgeCols.includes("is_member") ||
+        !edgeCols.includes("spec")) {
         return true;
+    }
     const fileCols = db.prepare("PRAGMA table_info(files)").all().map((c) => c.name);
     if (!fileCols.includes("is_test") || !fileCols.includes("module"))
         return true;
@@ -402,15 +424,62 @@ export function migrate9to10(db) {
         throw new Error(`schema 9→10 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
     }
 }
+/** Whether `edges` already has the schema-11 `spec` column (or does not exist yet). */
+function hasEdgeSpec(db) {
+    const cols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
+    return cols.length === 0 || cols.includes("spec");
+}
+/** Reason recorded with the needs-reindex marker by the 10→11 migration. */
+export const SCHEMA_11_REINDEX_REASON = "schema 11 adds file-owner nodes, member-call flags and full import text; reindex required";
+/**
+ * Migrate schema 10 → 11: add `edges.is_member` and `edges.spec` (each only
+ * when missing, so a pre-release schema-11 index lacking `spec` takes the same
+ * path), set the needs-reindex marker, and stamp `"11"`, all in one
+ * `BEGIN IMMEDIATE` transaction. The next index
+ * run re-extracts every file (edge ownership and import text change), while
+ * `embedding_cache` is untouched so unchanged symbols reuse their vectors.
+ *
+ * @param db - Open connection already at schema 10.
+ * @throws If any step fails; the transaction is rolled back and the stamp stays `"10"`.
+ */
+export function migrate10to11(db) {
+    // Covers: req~schema-edge-membership~1
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const cols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
+        // No edges table yet (a partial older index): the schema DDL creates it with the column.
+        if (cols.length > 0 && !cols.includes("is_member")) {
+            db.exec("ALTER TABLE edges ADD COLUMN is_member INTEGER NOT NULL DEFAULT 0");
+        }
+        if (cols.length > 0 && !cols.includes("spec")) {
+            db.exec("ALTER TABLE edges ADD COLUMN spec TEXT");
+        }
+        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        db.prepare("INSERT INTO meta(key, value) VALUES ('reindex_reason', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(SCHEMA_11_REINDEX_REASON);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("11");
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back */
+        }
+        throw new Error(`schema 10→11 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
+    }
+}
 /**
  * Open (creating if needed) the index database at `<projectPath>/.speclaw/index.db`.
  *
  * Ensures the `.speclaw` directory exists, enables WAL journaling and foreign
- * keys, and applies the schema. Schema 8→9 and 9→10 migrate in place
- * (embeddings preserved). Other incompatible schemas are wiped and rebuilt.
+ * keys, and applies the schema. Schema 8→9, 9→10, and 10→11 migrate in place
+ * and chain forward (embeddings preserved). Other incompatible schemas are wiped
+ * and rebuilt.
  *
  * @param projectPath - Absolute path to the project root.
  * @returns An open connection to the index database.
+ * @throws If an in-place migration fails (the connection is closed first).
  */
 export function openDb(projectPath) {
     const dir = path.join(projectPath, ".speclaw");
@@ -425,15 +494,18 @@ export function openDb(projectPath) {
             return null;
         }
     })();
-    if (ver === "8") {
-        migrate8to9(db, projectPath);
-        migrate9to10(db);
-        db.exec(SCHEMA);
-        ensureEmbeddingsView(db);
-        ensureFts(db);
-    }
-    else if (ver === "9") {
-        migrate9to10(db);
+    if (ver === "8" || ver === "9" || ver === "10" || (ver === "11" && !hasEdgeSpec(db))) {
+        try {
+            if (ver === "8")
+                migrate8to9(db, projectPath);
+            if (ver === "8" || ver === "9")
+                migrate9to10(db);
+            migrate10to11(db);
+        }
+        catch (err) {
+            db.close();
+            throw err;
+        }
         db.exec(SCHEMA);
         ensureEmbeddingsView(db);
         ensureFts(db);
@@ -496,6 +568,67 @@ export function needsReindex(db) {
 export function clearNeedsReindex(db) {
     db.prepare("DELETE FROM meta WHERE key = 'needs_reindex'").run();
 }
+/** `meta` key set by a per-file reindex until the next full post-processing pass. */
+const POST_PENDING_KEY = "post_pending";
+/**
+ * Whether a per-file reindex left global post-processing (PageRank, the compact
+ * map, cache upkeep) for the next full run. While set, a full run may not take
+ * its no-op fast path.
+ */
+export function postPending(db) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(POST_PENDING_KEY);
+    return row?.value === "1";
+}
+/** Record that a per-file reindex wrote rows and deferred the global pass. */
+export function setPostPending(db) {
+    db.prepare("INSERT INTO meta(key, value) VALUES (?, '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(POST_PENDING_KEY);
+}
+/** Clear the per-file marker once a full run has done the global pass. */
+export function clearPostPending(db) {
+    db.prepare("DELETE FROM meta WHERE key = ?").run(POST_PENDING_KEY);
+}
+/**
+ * Whether an open index is current for a per-file write: this release's schema
+ * version and edge shape, not stale, and no full reindex pending. Callers that
+ * probe before taking the write lock re-check under it.
+ */
+export function isCurrentIndex(db) {
+    return (readSchemaVersion(db) === SCHEMA_VERSION && hasEdgeSpec(db) && !isStale(db) && !needsReindex(db));
+}
+/**
+ * Open an existing index for a per-file write only when it is current.
+ *
+ * Unlike {@link openDb}, this never creates the `.speclaw` directory or the
+ * database, and never migrates, wipes, or re-stamps a schema: a missing index,
+ * an old or stale schema, or a pending full reindex returns `null` after a
+ * read-only probe, so the caller writes nothing and leaves the repair to the
+ * next full run.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns A read-write connection (WAL, foreign keys, 5 s busy timeout), or `null`.
+ */
+export function openCurrentDb(projectPath) {
+    const file = indexPath(projectPath);
+    if (!fs.existsSync(file))
+        return null;
+    let current;
+    const probe = new DatabaseSync(file, { readOnly: true });
+    try {
+        probe.exec("PRAGMA busy_timeout = 5000;");
+        current = isCurrentIndex(probe);
+    }
+    catch {
+        current = false;
+    }
+    finally {
+        probe.close();
+    }
+    if (!current)
+        return null;
+    const db = new DatabaseSync(file);
+    db.exec("PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+    return db;
+}
 /** Absolute path to the index database file for a project. */
 export function indexPath(projectPath) {
     return path.join(projectPath, ".speclaw", "index.db");