@esneiderbravo/speclaw 2.0.9 → 2.0.11

package/dist/modules/compass/diff-context.js

@@ -1,5 +1,5 @@
 import { isGitRepo, changedFiles, worktreeChangedFiles } from "../../shared/git.js";
-import { openDb, indexExists } from "./db.js";
+import { openDb, indexExists, FILE_NODE_KIND } from "./db.js";
 import { impact } from "./query.js";
 import { affectedTests } from "./affected.js";
 import { hotspots } from "./hotspots.js";
@@ -26,7 +26,7 @@ function symbolsForFiles(projectPath, files, overestimate) {
             const nodes = db
                 .prepare(`SELECT n.name, n.kind, n.start_line AS line, f.path AS file
            FROM nodes n JOIN files f ON f.id = n.file_id
-           WHERE f.path = ?`)
+           WHERE f.path = ? AND n.kind <> '${FILE_NODE_KIND}'`)
                 .all(file);
             if (overestimate || nodes.length === 0) {
                 for (const n of nodes)
@@ -100,6 +100,8 @@ export function diffContext(query) {
         result.affectedTests = {
             tests: at.tests,
             command: at.command,
+            commandReason: at.commandReason,
+            commands: at.commands,
             mode: at.mode,
             reason: at.reason,
         };

package/dist/modules/compass/explore-rich.js

@@ -1,5 +1,6 @@
 import { explore, impact, trace } from "./query.js";
 import { affectedTests } from "./affected.js";
+import { FILE_NODE_KIND } from "./db.js";
 import { hotspots } from "./hotspots.js";
 import { summarizeImpact } from "./impact-summary.js";
 import { budgetExploreShape, applyTextBudget, } from "../../shared/output-budget.js";
@@ -41,8 +42,10 @@ export async function exploreRich(query) {
             out.symbol = withoutSource(out.symbol);
         if (!includes.includes("callers"))
             out.callers = [];
-        if (!includes.includes("callees"))
+        if (!includes.includes("callees")) {
             out.callees = [];
+            delete out.unresolvedCallees;
+        }
         budgetExploreShape(out, mode, truncated);
         return out;
     }
@@ -52,15 +55,17 @@ export async function exploreRich(query) {
         out.symbol = withoutSource(out.symbol);
     if (!includes.includes("callers"))
         out.callers = [];
-    if (!includes.includes("callees"))
+    if (!includes.includes("callees")) {
         out.callees = [];
+        delete out.unresolvedCallees;
+    }
     if (base.found && base.symbol) {
         const sym = base.symbol.name;
         const file = base.symbol.file;
         if (includes.includes("blast_radius")) {
             try {
                 const imp = impact(query.projectPath, {
-                    symbol: sym,
+                    ...(base.symbol.kind === FILE_NODE_KIND ? { files: [file] } : { symbol: sym }),
                     maxDepth: query.maxDepth ?? 4,
                     format: "grouped",
                 });
@@ -72,14 +77,16 @@ export async function exploreRich(query) {
         }
         if (includes.includes("tests")) {
             try {
-                const at = affectedTests(query.projectPath, {
-                    symbols: [sym],
-                    maxDepth: query.maxDepth ?? 6,
-                });
+                // A file-owner node is named by its path: select by file, not by name.
+                const at = affectedTests(query.projectPath, base.symbol.kind === FILE_NODE_KIND
+                    ? { files: [file], maxDepth: query.maxDepth ?? 6 }
+                    : { symbols: [sym], maxDepth: query.maxDepth ?? 6 });
                 out.affectedTests = {
                     count: at.tests.length,
                     files: at.tests.map((t) => t.file),
                     command: at.command,
+                    commandReason: at.commandReason,
+                    commands: at.commands,
                 };
             }
             catch {

package/dist/modules/compass/extract.js

@@ -34,6 +34,115 @@ function calleeName(node, lang) {
         return fn.text;
     return fn.text.split(/[.\s(]/)[0] || null;
 }
+/** Python receivers that mean "this class/instance". */
+const PY_SELF = new Set(["self", "cls"]);
+/**
+ * The receiver of a member call (`recv.f()`), or null for a plain call.
+ * `kind` is `self` for `this`/`super`/`self`/`cls`, `ident` for a bare
+ * identifier (classified later against the file's import bindings), and
+ * `other` for any chain, subscript, or call result.
+ */
+function callReceiver(node, lang) {
+    const fn = node.childForFieldName(lang.callField);
+    if (!fn)
+        return null;
+    if (fn.type === "identifier" || fn.type === "super")
+        return null;
+    if (fn.type !== "member_expression" && fn.type !== "attribute") {
+        return { kind: "other", text: fn.text };
+    }
+    const obj = fn.childForFieldName("object");
+    if (!obj)
+        return { kind: "other", text: fn.text };
+    if (obj.type === "this" || obj.type === "super")
+        return { kind: "self", text: obj.text };
+    if (obj.type === "identifier") {
+        // Python's `self`/`cls` are conventions, not keywords; JS `self` is a global.
+        if (lang.id === "python" && PY_SELF.has(obj.text))
+            return { kind: "self", text: obj.text };
+        return { kind: "ident", text: obj.text };
+    }
+    return { kind: "other", text: obj.text };
+}
+/** Longest import text stored on an edge (`dst_name`). */
+export const IMPORT_TEXT_CAP = 1024;
+/**
+ * Module specifier of a raw import statement (`from "x"`, `import "x"`,
+ * `require("x")`, `import("x")`), or null when the text has none.
+ *
+ * @param text - Import statement text, whitespace collapsed.
+ */
+export function importSpecifier(text) {
+    const m = text.match(/\bfrom\s+['"]([^'"]+)['"]/) ??
+        text.match(/^import\s+['"]([^'"]+)['"]/) ??
+        text.match(/\brequire\s*\(\s*['"]([^'"]+)['"]/) ??
+        text.match(/\bimport\s*\(\s*['"]([^'"]+)['"]/);
+    return m ? m[1] : null;
+}
+/**
+ * Import text as stored on its edge: unchanged up to {@link IMPORT_TEXT_CAP}
+ * characters, else the head of the statement, ` … `, and its trailing `from`
+ * clause, so the specifier at the end survives the cap. Bindings and the
+ * specifier are read from the full text before capping; this only bounds what
+ * is stored.
+ *
+ * @param text - Import statement text, whitespace collapsed.
+ */
+export function capImportText(text) {
+    if (text.length <= IMPORT_TEXT_CAP)
+        return text;
+    const tail = text.match(/\s(from\s+['"][^'"]+['"].*)$/)?.[1] ??
+        text.match(/((?:require|import)\s*\(\s*['"][^'"]+['"].*)$/)?.[1];
+    if (!tail || tail.length > IMPORT_TEXT_CAP / 2)
+        return text.slice(0, IMPORT_TEXT_CAP);
+    return `${text.slice(0, IMPORT_TEXT_CAP - tail.length - 3)} … ${tail}`;
+}
+/**
+ * Local names an import statement binds: default, namespace (`* as ns`), and
+ * named (`{ a, b as c }` → `a`, `c`) for JS/TS; `import a.b` → `a`,
+ * `import x as y` → `y`, `from m import a, b as c` → `a`, `c` for Python.
+ *
+ * @param text - Import statement text, whitespace collapsed.
+ * @param langId - Language id of the file.
+ */
+export function importBindings(text, langId) {
+    const out = [];
+    const ident = /^[A-Za-z_$][\w$]*$/;
+    const localOf = (part) => {
+        const bits = part.trim().split(/\s+as\s+/);
+        const name = (bits[1] ?? bits[0] ?? "").trim().replace(/^type\s+/, "");
+        return ident.test(name) ? name : null;
+    };
+    if (langId === "python") {
+        const from = text.match(/^from\s+\S+\s+import\s+(.+)$/);
+        const list = from ? from[1] : (text.match(/^import\s+(.+)$/)?.[1] ?? "");
+        for (const raw of list.replace(/[()]/g, "").split(",")) {
+            const bits = raw.trim().split(/\s+as\s+/);
+            const name = bits[1] ?? (from ? bits[0] : bits[0]?.split(".")[0]);
+            if (name && ident.test(name.trim()))
+                out.push(name.trim());
+        }
+        return out;
+    }
+    const clause = text.match(/^import\s+(?:type\s+)?(.+?)\s+from\s/)?.[1];
+    if (!clause)
+        return out;
+    const ns = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
+    if (ns)
+        out.push(ns[1]);
+    const brace = clause.match(/\{([^}]*)\}/);
+    if (brace) {
+        for (const part of brace[1].split(",")) {
+            const name = localOf(part);
+            if (name)
+                out.push(name);
+        }
+    }
+    const def = clause.match(/^([A-Za-z_$][\w$]*)\s*(?:,|$)/);
+    if (def)
+        out.push(def[1]);
+    return out;
+}
 /** First line of the node's text, trimmed — a lightweight signature. */
 function signatureOf(node) {
     return node.text.split("\n")[0].trim().slice(0, 200);
@@ -223,6 +332,17 @@ export async function extract(source, lang) {
     const symbols = [];
     const refs = [];
     const rawCoverage = [];
+    // Identifier receivers and bare callees are classified after the walk, once
+    // every import binding of the file is known (imports may follow their first
+    // use). Whether a binding is a package is not decided here: that needs the
+    // project's alias/baseUrl config, so resolveEdges decides it from whether the
+    // binding's import (matched by `spec`) resolved to a project file.
+    const identReceivers = [];
+    const bareCalls = [];
+    const bindings = new Set();
+    // JS/TS import binding → its import's module specifier.
+    const bindingSpecs = new Map();
+    const reexports = [];
     const walk = (node, ownerIndex) => {
         let nextOwner = ownerIndex;
         if (kinds.has(node.type)) {
@@ -252,20 +372,52 @@ export async function extract(source, lang) {
         }
         else if (node.type === lang.callNode) {
             const name = calleeName(node, lang);
-            if (name)
-                refs.push({ name, kind: "call", line: node.startPosition.row + 1, ownerIndex });
+            if (name) {
+                const receiver = callReceiver(node, lang);
+                const ref = {
+                    name,
+                    kind: "call",
+                    line: node.startPosition.row + 1,
+                    ownerIndex,
+                    member: receiver !== null && receiver.kind === "other" ? 1 : 0,
+                    spec: null,
+                };
+                if (receiver?.kind === "ident")
+                    identReceivers.push({ ref, receiver: receiver.text });
+                else if (receiver === null)
+                    bareCalls.push(ref);
+                refs.push(ref);
+            }
         }
         else if (importSet.has(node.type)) {
+            // Covers: req~import-resolution~1
+            // The whole statement, so a specifier on a later line is still parseable.
+            // Bindings and the specifier come from the full text; only storage is capped.
+            const text = node.text.replace(/\s+/g, " ").trim();
+            const bound = importBindings(text, lang.id);
+            const spec = lang.id === "python" ? null : importSpecifier(text);
+            for (const b of bound) {
+                bindings.add(b);
+                if (spec !== null)
+                    bindingSpecs.set(b, spec);
+            }
             refs.push({
-                name: node.text.split("\n")[0].trim().slice(0, 200),
+                name: capImportText(text),
                 kind: "import",
                 line: node.startPosition.row + 1,
                 ownerIndex,
+                member: 0,
+                spec,
             });
         }
         else if (COMMENT_TYPES.has(node.type)) {
             rawCoverage.push(...parseCoverageComment(node, ownerIndex));
         }
+        else if (node.type === "export_statement" && lang.id !== "python") {
+            const source = node.childForFieldName("source");
+            if (source && source.text.length >= 2)
+                reexports.push(source.text.slice(1, -1));
+        }
         for (let i = 0; i < node.childCount; i++) {
             const child = node.child(i);
             if (child)
@@ -274,5 +426,12 @@ export async function extract(source, lang) {
     };
     walk(tree.rootNode, null);
     tree.delete();
-    return { symbols, refs, coverage: attachCoverage(rawCoverage, symbols) };
+    for (const { ref, receiver } of identReceivers) {
+        const spec = bindingSpecs.get(receiver) ?? null;
+        ref.member = !bindings.has(receiver) ? 1 : spec !== null ? 2 : 0;
+        ref.spec = spec;
+    }
+    for (const ref of bareCalls)
+        ref.spec = bindingSpecs.get(ref.name) ?? null;
+    return { symbols, refs, coverage: attachCoverage(rawCoverage, symbols), reexports };
 }

package/dist/modules/compass/hotspots.js

@@ -1,4 +1,5 @@
-import { openDb } from "./db.js";
+import { openDb, FILE_NODE_KIND } from "./db.js";
+import { BUILTIN_SQL_LIST } from "./indexer.js";
 import { cachedCoChanges, cachedFileActivity } from "./git-history-cache.js";
 import { jaccardStrength } from "../../shared/git-history.js";
 /** Default history window for hotspot / coupling ranking. */
@@ -31,7 +32,7 @@ function loadFileHealth(projectPath) {
                 COALESCE(MAX(m.max_nesting), 0) AS worst_nesting,
                 COALESCE(MAX(m.branches), 0) AS worst_branches
          FROM files f
-         LEFT JOIN nodes n ON n.file_id = f.id
+         LEFT JOIN nodes n ON n.file_id = f.id AND n.kind <> '${FILE_NODE_KIND}'
          LEFT JOIN node_metrics m ON m.node_id = n.id
          GROUP BY f.id`)
             .all();
@@ -148,17 +149,21 @@ function pairInGraph(projectPath, a, b) {
             .get(a, b, b, a);
         if (row)
             return true;
-        // Name-only imports: dst_node_id NULL — check import edge text contains other path basename loosely via file paths of same module is hard;
-        // also match unresolved edges where dst resolves by file path of an indexed import target is out of scope.
-        // Fallback: any edge from a whose dst_name matches a symbol defined in b (or reverse).
+        // Fallback: an unresolved edge from a whose dst_name names a symbol defined
+        // in b (or reverse). Same rule as the query-time by-name arms: member calls
+        // (is_member 1 = foreign receiver, 2 = package receiver) never match by
+        // name, and a builtin global name only matches within its own file, which
+        // a cross-file pair never is.
         const byName = db
             .prepare(`SELECT 1 AS ok
          FROM edges e
          JOIN files sf ON sf.id = e.src_file_id
-         JOIN nodes dn ON dn.name = e.dst_name
+         JOIN nodes dn ON dn.name = e.dst_name AND dn.kind <> '${FILE_NODE_KIND}'
          JOIN files df ON df.id = dn.file_id
          WHERE e.dst_node_id IS NULL
            AND e.kind IN ('call', 'import')
+           AND e.is_member = 0
+           AND e.dst_name NOT IN (${BUILTIN_SQL_LIST})
            AND ((sf.path = ? AND df.path = ?) OR (sf.path = ? AND df.path = ?))
          LIMIT 1`)
             .get(a, b, b, a);

package/dist/modules/compass/hybrid.js

@@ -2,7 +2,7 @@
  * Hybrid retrieval pipeline: BM25 + KNN + name → RRF → ego expand →
  * personalized PageRank → structural rerank → token budget.
  */
-import { openDb, indexExists, ftsAvailable } from "./db.js";
+import { openDb, indexExists, ftsAvailable, FILE_NODE_KIND } from "./db.js";
 import { getEmbedder, fromBlob, cosine } from "./embedder.js";
 import { isGitRepo, worktreeChangedFiles } from "../../shared/git.js";
 import { escapeFtsQuery, nameBoost, routeWeights, rrfFuse, structuralScore, MAX_DEGREE, isSymbolQuery, } from "./rank.js";
@@ -113,7 +113,7 @@ export async function hybridSearch(projectPath, query, opts = {}) {
             const likeRows = db
                 .prepare(`SELECT n.id
            FROM nodes n
-           WHERE n.name LIKE ?
+           WHERE n.name LIKE ? AND n.kind <> '${FILE_NODE_KIND}'
            ORDER BY (n.name = ?) DESC, length(n.name) ASC
            LIMIT 20`)
                 .all(`%${q}%`, q);
@@ -125,8 +125,11 @@ export async function hybridSearch(projectPath, query, opts = {}) {
         const fused = rrfFuse({ bm25: bm25Ids, knn: knnIds, name: nameIds }, { bm25: weights.bm25, knn: weights.knn, name: weights.name });
         // Apply name boost using node names.
         const idMeta = new Map();
+        // File-owner nodes have no metadata here, so they never become a hit, even
+        // when the ego-graph expansion reaches one through a call edge.
         const loadMeta = db.prepare(`SELECT n.id, n.name, n.kind, f.path AS file, n.start_line AS line, n.signature
-       FROM nodes n JOIN files f ON f.id = n.file_id WHERE n.id = ?`);
+       FROM nodes n JOIN files f ON f.id = n.file_id
+       WHERE n.id = ? AND n.kind <> '${FILE_NODE_KIND}'`);
         for (const id of fused.keys()) {
             const row = loadMeta.get(id);
             if (row) {
@@ -208,7 +211,9 @@ export async function hybridSearch(projectPath, query, opts = {}) {
         }
         const prNodeIds = [...subgraphNodes, ...[...fileIdsNeeded].map((fid) => fileNodeId(fid))];
         const defCount = new Map();
-        const allNames = db.prepare("SELECT name FROM nodes").all();
+        const allNames = db
+            .prepare(`SELECT name FROM nodes WHERE kind <> '${FILE_NODE_KIND}'`)
+            .all();
         for (const r of allNames)
             defCount.set(r.name, (defCount.get(r.name) ?? 0) + 1);
         const refCount = new Map();