@esneiderbravo/speclaw 0.3.9 → 0.3.11

package/dist/modules/compass/indexer.js

@@ -5,6 +5,7 @@ import { openDb, clearNeedsReindex } from "./db.js";
 import { langForPath } from "./languages.js";
 import { extract } from "./extract.js";
 import { getEmbedder, toBlob } from "./embedder.js";
+import { loadAffectedConfig, isTestPath, inferModule } from "./affected-config.js";
 const SKIP_DIRS = new Set([
     ".git",
     "node_modules",
@@ -29,6 +30,108 @@ const MAX_FILE_BYTES = 1_500_000;
 function hashOf(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+/**
+ * Point import edges at a representative node in the imported file so reverse
+ * reachability can walk file-level dependencies (not just calls).
+ */
+function resolveImportEdges(db, projectPath) {
+    const files = db.prepare("SELECT id, path FROM files").all();
+    const byNorm = new Map();
+    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 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
+       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();
+    for (const edge of imports) {
+        const spec = parseImportSpecifier(edge.dst_name);
+        if (!spec)
+            continue;
+        const targetRel = resolveImportPath(projectPath, edge.src_path, spec.from);
+        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;
+            }
+        }
+        if (nodeId === undefined) {
+            const row = firstNode.get(fileId);
+            nodeId = row?.id;
+        }
+        if (nodeId !== undefined)
+            upd.run(nodeId, edge.id);
+    }
+}
+/** 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);
+        }
+    }
+    const def = text.match(/\bimport\s+([A-Za-z_$][\w$]*)\s+/);
+    if (def && !text.includes("{"))
+        names.push(def[1]);
+    return { from, names };
+}
+/**
+ * Resolve a relative/absolute-ish import specifier to a project-relative indexed path.
+ */
+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(/^\.\//, "");
+}
 /**
  * Infer a covering artifact's type from its project-relative path.
  * Full glob config lives in lawbook; this is the indexer default so links are
@@ -98,18 +201,20 @@ export async function buildIndex(projectPath, onProgress) {
         removed: 0,
         embedder: embedder.id,
     };
+    const cfg = loadAffectedConfig(projectPath);
     const existing = new Map();
     for (const row of db.prepare("SELECT id, path, hash FROM files").all()) {
         existing.set(row.path, { id: row.id, hash: row.hash });
     }
     const seen = new Set();
-    const insFile = db.prepare("INSERT INTO files(path, hash, lang) VALUES (?, ?, ?)");
-    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ? WHERE id = ?");
+    const insFile = db.prepare("INSERT INTO files(path, hash, lang, is_test, module) VALUES (?, ?, ?, ?, ?)");
+    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ? 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)
      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
@@ -143,15 +248,17 @@ export async function buildIndex(projectPath, onProgress) {
                 continue;
             }
             let fileId;
+            const isTest = isTestPath(rel, cfg.testGlobs) ? 1 : 0;
+            const mod = inferModule(rel);
             if (prior) {
-                updFile.run(hash, lang.id, prior.id);
+                updFile.run(hash, lang.id, isTest, mod, 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).lastInsertRowid);
+                fileId = Number(insFile.run(rel, hash, lang.id, isTest, mod).lastInsertRowid);
             }
             const { symbols, refs, coverage } = await extract(content, lang);
             const nodeIds = [];
@@ -159,13 +266,18 @@ export async function buildIndex(projectPath, onProgress) {
                 const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
                 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).lastInsertRowid);
                 nodeIds.push(id);
+                insMetrics.run(id, s.loc, s.maxNesting, s.branches);
                 // embed the node from its name + signature (cheap, meaningful text)
                 const vec = await embedder.embed(`${s.kind} ${s.name} ${s.signature ?? ""}`);
                 insEmbed.run(id, embedder.dim, embedder.id, toBlob(vec));
                 stats.embeddings++;
             }
+            // Prefer a real symbol as import owner when the AST leaves imports file-scoped.
+            const fileOwner = nodeIds[0] ?? null;
             for (const r of refs) {
-                const srcId = r.ownerIndex !== null ? nodeIds[r.ownerIndex] : null;
+                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++;
             }
@@ -184,15 +296,17 @@ export async function buildIndex(projectPath, onProgress) {
                 stats.removed++;
             }
         }
-        // resolve call edges to node definitions by name match
+        // Prefer same-file callees so colliding names across files do not share one id.
         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);
         db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
         clearNeedsReindex(db);
         db.exec("COMMIT");

package/dist/modules/compass/languages.js

@@ -17,6 +17,19 @@ export const LANGUAGES = [
         callNode: "call",
         callField: "function",
         importNodes: ["import_statement", "import_from_statement"],
+        nestingNodes: ["block", "suite"],
+        branchNodes: [
+            "if_statement",
+            "elif_clause",
+            "for_statement",
+            "while_statement",
+            "match_statement",
+            "case_clause",
+            "conditional_expression",
+            "except_clause",
+            "with_statement",
+            "boolean_operator",
+        ],
     },
     {
         id: "javascript",
@@ -30,6 +43,19 @@ export const LANGUAGES = [
         callNode: "call_expression",
         callField: "function",
         importNodes: ["import_statement"],
+        nestingNodes: ["statement_block", "class_body"],
+        branchNodes: [
+            "if_statement",
+            "else_clause",
+            "for_statement",
+            "for_in_statement",
+            "while_statement",
+            "do_statement",
+            "switch_case",
+            "switch_default",
+            "catch_clause",
+            "ternary_expression",
+        ],
     },
     {
         id: "typescript",
@@ -46,6 +72,19 @@ export const LANGUAGES = [
         callNode: "call_expression",
         callField: "function",
         importNodes: ["import_statement"],
+        nestingNodes: ["statement_block", "class_body"],
+        branchNodes: [
+            "if_statement",
+            "else_clause",
+            "for_statement",
+            "for_in_statement",
+            "while_statement",
+            "do_statement",
+            "switch_case",
+            "switch_default",
+            "catch_clause",
+            "ternary_expression",
+        ],
     },
 ];
 const BY_EXT = new Map();

package/dist/modules/compass/query.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { openDb, indexExists } from "./db.js";
 import { getEmbedder, fromBlob, cosine } from "./embedder.js";
+import { loadAffectedConfig, filterFilesForTarget, matchGlobalFiles } from "./affected-config.js";
 function requireIndex(projectPath) {
     if (!indexExists(projectPath)) {
         throw new Error("No index found. Build it first with the index_build tool (creates .speclaw/index.db).");
@@ -164,50 +165,274 @@ export async function recall(projectPath, query, limit = 15) {
         db.close();
     }
 }
+const DEFAULT_HARD_LIMIT = 500;
 /**
- * Transitive blast radius: every node that (transitively) calls the target,
- * up to maxDepth hops. Expansion is by call-name, so dynamic dispatch is
- * included — the conservative answer to "what could break if I change this?".
+ * Reverse dependency closure (blast radius) for a symbol or set of files.
+ *
+ * Uses one recursive SQL CTE that prefers `edges.dst_node_id` and falls back to
+ * `dst_name` only when the id is NULL. Default edge kinds are `call` and
+ * `import`. Results are grouped by module unless `format: "flat"`.
  *
  * @param projectPath - Absolute path to the indexed project.
- * @param nodeName - Name of the node whose dependents are wanted.
- * @param maxDepth - Maximum number of call hops to traverse outward.
- * @returns The reached nodes, each tagged with its discovery depth.
- * @throws If no index exists for the project.
+ * @param symbolOrOpts - Symbol name (legacy) or full {@link ImpactQuery}.
+ * @param maxDepth - Used only with the legacy string form.
  */
-export function impact(projectPath, nodeName, maxDepth = 4) {
+export function impact(projectPath, symbolOrOpts, maxDepth = 4) {
+    const opts = typeof symbolOrOpts === "string"
+        ? { symbol: symbolOrOpts, maxDepth }
+        : { maxDepth: 4, ...symbolOrOpts };
     requireIndex(projectPath);
+    const cfg = loadAffectedConfig(projectPath);
+    const depth = Math.max(1, Math.min(12, opts.maxDepth ?? 4));
+    const edgeKinds = opts.edgeKinds?.length ? opts.edgeKinds : ["call", "import"];
+    const hardLimit = opts.hardLimit ?? DEFAULT_HARD_LIMIT;
+    const topModules = opts.topModules ?? 8;
+    const topPerModule = opts.topPerModule ?? 5;
+    const format = opts.format ?? "grouped";
+    const target = opts.target ?? "any";
+    const warnings = [];
     const db = openDb(projectPath);
     try {
-        const visited = new Set();
-        const results = [];
-        let frontier = [nodeName];
-        for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
-            const placeholders = frontier.map(() => "?").join(",");
-            const callers = db
-                .prepare(`SELECT DISTINCT owner.id, owner.name, owner.kind, f.path AS file, MIN(owner.start_line) AS line
-           FROM edges e
-           JOIN nodes owner ON owner.id = e.src_node_id
-           JOIN files f ON f.id = owner.file_id
-           WHERE e.kind = 'call' AND e.dst_name IN (${placeholders})
-           GROUP BY owner.id`)
-                .all(...frontier);
-            const nextNames = new Set();
-            for (const c of callers) {
-                if (visited.has(c.id))
-                    continue;
-                visited.add(c.id);
-                results.push({ name: c.name, kind: c.kind, file: c.file, line: c.line, depth });
-                nextNames.add(c.name);
+        let seedFiles = opts.files ? [...opts.files] : [];
+        if (seedFiles.length > 0) {
+            const filtered = filterFilesForTarget(seedFiles, target, cfg);
+            warnings.push(...filtered.warnings);
+            seedFiles = filtered.included;
+            const glob = matchGlobalFiles(seedFiles, cfg);
+            if (glob.matched.length > 0) {
+                return {
+                    target: { kind: "files", files: seedFiles },
+                    totals: { nodes: 0, files: 0, modules: 0 },
+                    global: {
+                        matched: glob.patterns,
+                        blastRadius: "repo",
+                        reason: `Global file(s) matched (${glob.matched.join(", ")}); treat blast radius as the whole repository`,
+                    },
+                    modules: [],
+                    resolution: { exact: 0, byName: 0 },
+                    limits: { maxDepth: depth, maxDepthReached: false, truncated: false },
+                    warnings,
+                };
+            }
+        }
+        const definitions = resolveImpactSeeds(db, opts, seedFiles, warnings);
+        if (definitions.length === 0 && !opts.symbol && seedFiles.length === 0) {
+            return emptyImpact(opts, seedFiles, depth, warnings);
+        }
+        if (definitions.length === 0) {
+            warnings.push("No seed definitions found in the index for the given target");
+            return emptyImpact(opts, seedFiles, depth, warnings);
+        }
+        const kindPlaceholders = edgeKinds.map(() => "?").join(",");
+        const seedPlaceholders = definitions.map(() => "(?, ?, 0, 0)").join(",");
+        const seedArgs = [];
+        for (const d of definitions) {
+            seedArgs.push(d.nodeId, d.name);
+        }
+        // Sticky by_name: MAX(frontier.by_name, CASE WHEN edge unresolved THEN 1 ELSE 0).
+        // Import edges that resolve to ANY node in the frontier node's file count as hits.
+        const sql = `
+      WITH RECURSIVE
+      frontier(node_id, node_name, depth, by_name) AS (
+        SELECT * FROM (VALUES ${seedPlaceholders})
+        UNION
+        SELECT owner.id,
+               owner.name,
+               f.depth + 1,
+               MAX(f.by_name, CASE
+                 WHEN e.kind = 'import' THEN 0
+                 WHEN e.dst_node_id IS NULL THEN 1
+                 ELSE 0
+               END)
+        FROM frontier f
+        JOIN edges e ON (
+          e.kind IN (${kindPlaceholders})
+          AND (
+            (e.kind = 'call' AND (
+              e.dst_node_id = f.node_id
+              OR (e.dst_node_id IS NULL AND e.dst_name = f.node_name)
+            ))
+            OR (
+              e.kind = 'import'
+              AND e.dst_node_id IS NOT NULL
+              AND EXISTS (
+                SELECT 1 FROM nodes dn
+                WHERE dn.id = e.dst_node_id
+                  AND dn.file_id = (SELECT file_id FROM nodes WHERE id = f.node_id)
+              )
+            )
+          )
+        )
+        JOIN nodes owner ON owner.id = e.src_node_id
+        WHERE f.depth < ?
+      )
+      SELECT r.node_id AS nodeId,
+             r.node_name AS name,
+             n.kind AS kind,
+             fl.path AS file,
+             n.start_line AS line,
+             MIN(r.depth) AS depth,
+             MIN(r.by_name) AS byName,
+             fl.module AS module
+      FROM frontier r
+      JOIN nodes n ON n.id = r.node_id
+      JOIN files fl ON fl.id = n.file_id
+      WHERE r.depth > 0
+      GROUP BY r.node_id
+      ORDER BY depth ASC, file ASC, line ASC
+      LIMIT ?
+    `;
+        const rows = db.prepare(sql).all(...seedArgs, ...edgeKinds, depth, hardLimit + 1);
+        const truncated = rows.length > hardLimit;
+        const sliced = truncated ? rows.slice(0, hardLimit) : rows;
+        const nodes = sliced.map((r) => ({
+            nodeId: r.nodeId,
+            name: r.name,
+            kind: r.kind,
+            file: r.file,
+            line: r.line,
+            depth: r.depth,
+            resolution: r.byName > 0 ? "by-name" : "exact",
+            module: r.module || inferModuleFallback(r.file),
+        }));
+        const exact = nodes.filter((n) => n.resolution === "exact").length;
+        const byName = nodes.length - exact;
+        const maxDepthReached = nodes.some((n) => n.depth >= depth);
+        const targetDesc = opts.symbol || opts.nodeId !== undefined
+            ? {
+                kind: "symbol",
+                symbol: opts.symbol ?? `#${opts.nodeId}`,
+                definitions: definitions.map((d) => ({
+                    nodeId: d.nodeId,
+                    file: d.file,
+                    line: d.line,
+                })),
             }
-            frontier = [...nextNames];
+            : { kind: "files", files: seedFiles };
+        if (format === "flat") {
+            const files = new Set(nodes.map((n) => n.file));
+            const modules = new Set(nodes.map((n) => n.module));
+            return {
+                target: targetDesc,
+                totals: { nodes: nodes.length, files: files.size, modules: modules.size },
+                modules: [],
+                nodes,
+                resolution: { exact, byName },
+                limits: { maxDepth: depth, maxDepthReached, truncated },
+                warnings,
+            };
         }
-        return results;
+        return {
+            target: targetDesc,
+            totals: {
+                nodes: nodes.length,
+                files: new Set(nodes.map((n) => n.file)).size,
+                modules: new Set(nodes.map((n) => n.module)).size,
+            },
+            modules: groupImpactModules(nodes, topModules, topPerModule),
+            resolution: { exact, byName },
+            limits: { maxDepth: depth, maxDepthReached, truncated },
+            warnings,
+        };
     }
     finally {
         db.close();
     }
 }
+function inferModuleFallback(file) {
+    const parts = file.split(/[/\\]/).filter(Boolean);
+    if (parts.length <= 1)
+        return parts[0] ?? ".";
+    return parts.slice(0, 2).join("/");
+}
+function emptyImpact(opts, seedFiles, depth, warnings) {
+    return {
+        target: opts.symbol || opts.nodeId !== undefined
+            ? {
+                kind: "symbol",
+                symbol: opts.symbol ?? `#${opts.nodeId}`,
+                definitions: [],
+            }
+            : { kind: "files", files: seedFiles },
+        totals: { nodes: 0, files: 0, modules: 0 },
+        modules: [],
+        nodes: opts.format === "flat" ? [] : undefined,
+        resolution: { exact: 0, byName: 0 },
+        limits: { maxDepth: depth, maxDepthReached: false, truncated: false },
+        warnings,
+    };
+}
+function resolveImpactSeeds(db, opts, seedFiles, warnings) {
+    if (opts.nodeId !== undefined) {
+        const row = db
+            .prepare(`SELECT n.id AS nodeId, n.name, f.path AS file, n.start_line AS line
+         FROM nodes n JOIN files f ON f.id = n.file_id WHERE n.id = ?`)
+            .get(opts.nodeId);
+        return row ? [row] : [];
+    }
+    if (opts.symbol) {
+        const rows = db
+            .prepare(`SELECT n.id AS nodeId, n.name, f.path AS file, n.start_line AS line
+         FROM nodes n JOIN files f ON f.id = n.file_id
+         WHERE n.name = ?
+         ORDER BY n.kind = 'function' DESC, n.kind = 'class' DESC, n.id ASC
+         LIMIT 50`)
+            .all(opts.symbol);
+        if (rows.length > 1) {
+            warnings.push(`"${opts.symbol}" is defined in ${rows.length} places; impact is the union. Pass nodeId to disambiguate.`);
+        }
+        return rows;
+    }
+    if (seedFiles.length === 0)
+        return [];
+    db.exec("CREATE TEMP TABLE IF NOT EXISTS changed(path TEXT PRIMARY KEY)");
+    db.exec("DELETE FROM changed");
+    const ins = db.prepare("INSERT OR IGNORE INTO changed(path) VALUES (?)");
+    for (const f of seedFiles)
+        ins.run(f.split("\\").join("/"));
+    const indexed = db
+        .prepare(`SELECT n.id AS nodeId, n.name, f.path AS file, n.start_line AS line
+       FROM nodes n
+       JOIN files f ON f.id = n.file_id
+       JOIN changed c ON c.path = f.path`)
+        .all();
+    const indexedPaths = new Set(indexed.map((r) => r.file));
+    for (const f of seedFiles) {
+        const norm = f.split("\\").join("/");
+        if (!indexedPaths.has(norm)) {
+            warnings.push(`${norm} is not indexed; run compass_index`);
+        }
+    }
+    return indexed;
+}
+function groupImpactModules(nodes, topModules, topPerModule) {
+    const byMod = new Map();
+    for (const n of nodes) {
+        const list = byMod.get(n.module) ?? [];
+        list.push(n);
+        byMod.set(n.module, list);
+    }
+    const modules = [];
+    for (const [module, list] of byMod) {
+        list.sort((a, b) => {
+            if (a.depth !== b.depth)
+                return a.depth - b.depth;
+            if (a.resolution !== b.resolution)
+                return a.resolution === "exact" ? -1 : 1;
+            return a.file.localeCompare(b.file) || a.line - b.line;
+        });
+        modules.push({
+            module,
+            nodes: list.length,
+            files: new Set(list.map((n) => n.file)).size,
+            minDepth: list[0]?.depth ?? 0,
+            byName: list.filter((n) => n.resolution === "by-name").length,
+            top: list.slice(0, topPerModule),
+        });
+    }
+    modules.sort((a, b) => b.nodes - a.nodes || a.module.localeCompare(b.module));
+    return modules.slice(0, topModules);
+}
 /**
  * Trace a call path from one node to another: BFS forward over call edges (by
  * name) from `from` until `to` is reached, returning the chain of names. null

package/dist/modules/compass/register.js

@@ -3,6 +3,8 @@ import { defineTool, text } from "../../shared/mcp.js";
 import { shouldExpose } from "../../shared/exposure.js";
 import { buildIndex } from "./indexer.js";
 import { explore, search, recall, impact, trace } from "./query.js";
+import { affectedTests } from "./affected.js";
+import { hotspots, coupling } from "./hotspots.js";
 import { startWatch, stopWatch, watchStatus } from "./watcher.js";
 import { visualize } from "./visualize.js";
 // ─── Compass: speclaw's own code-intelligence engine (no external deps) ───
@@ -23,7 +25,53 @@ export function registerCompass(server, opts = {}) {
     add("compass_explore", "Read a symbol's source plus callers and callees. Prefer this before grep or Read.", { projectPath: z.string(), node: z.string() }, async ({ projectPath, node }) => text(explore(projectPath, node)));
     add("compass_search", "Find symbols by name or keyword (substring). Cheaper structural search than grep.", { projectPath: z.string(), query: z.string(), limit: z.number().optional() }, async ({ projectPath, query, limit }) => text(search(projectPath, query, limit ?? 25)));
     add("compass_recall", "Find symbols by meaning via local embeddings. Use when names are unknown.", { projectPath: z.string(), query: z.string(), limit: z.number().optional() }, async ({ projectPath, query, limit }) => text(await recall(projectPath, query, limit ?? 15)));
-    add("compass_impact", "List transitive callers of a symbol (blast radius) before editing.", { projectPath: z.string(), node: z.string(), maxDepth: z.number().optional() }, async ({ projectPath, node, maxDepth }) => text(impact(projectPath, node, maxDepth ?? 4)));
+    add("compass_impact", "Blast radius for a symbol or files, grouped by module (not a flat dump).", {
+        projectPath: z.string(),
+        /** @deprecated Prefer `symbol`. Kept for existing callers. */
+        node: z.string().optional(),
+        symbol: z.string().optional(),
+        files: z.array(z.string()).optional(),
+        nodeId: z.number().int().optional(),
+        maxDepth: z.number().int().min(1).max(12).optional(),
+        edgeKinds: z.array(z.enum(["call", "import"])).optional(),
+        target: z.enum(["build", "test", "lint", "any"]).optional(),
+        format: z.enum(["grouped", "flat"]).optional(),
+        topModules: z.number().int().min(1).max(50).optional(),
+        topPerModule: z.number().int().min(1).max(50).optional(),
+    }, async (args) => text(impact(args.projectPath, {
+        symbol: args.symbol ?? args.node,
+        files: args.files,
+        nodeId: args.nodeId,
+        maxDepth: args.maxDepth ?? 4,
+        edgeKinds: args.edgeKinds,
+        target: args.target,
+        format: args.format ?? "grouped",
+        topModules: args.topModules,
+        topPerModule: args.topPerModule,
+    })));
+    add("compass_affected_tests", "Select test files affected by a change; returns a ready-to-run command.", {
+        projectPath: z.string(),
+        files: z.array(z.string()).optional(),
+        symbols: z.array(z.string()).optional(),
+        fromDiff: z.string().optional(),
+        maxDepth: z.number().int().min(1).max(12).optional(),
+    }, async ({ projectPath, files, symbols, fromDiff, maxDepth }) => text(affectedTests(projectPath, { files, symbols, fromDiff, maxDepth })));
+    add("compass_hotspots", "Rank files by recent churn and AST complexity; two axes, no magic score.", {
+        projectPath: z.string(),
+        days: z.number().int().min(1).max(3650).optional(),
+        since: z.string().optional(),
+        sortBy: z.enum(["churn", "complexity", "combined"]).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+    }, async ({ projectPath, days, since, sortBy, limit }) => text(hotspots(projectPath, { days, since, sortBy, limit })));
+    add("compass_coupling", "Files that co-change with a target; strength, graph edge, and test-pair facts.", {
+        projectPath: z.string(),
+        file: z.string(),
+        days: z.number().int().min(1).max(3650).optional(),
+        since: z.string().optional(),
+        minShared: z.number().int().min(1).optional(),
+        maxFilesPerCommit: z.number().int().min(2).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+    }, async ({ projectPath, file, days, since, minShared, maxFilesPerCommit, limit }) => text(coupling(projectPath, file, { days, since, minShared, maxFilesPerCommit, limit })));
     add("compass_trace", "Find a call path between two symbols within a depth limit.", {
         projectPath: z.string(),
         from: z.string(),

package/dist/shared/exposure.js

@@ -11,6 +11,9 @@ export const MINIMAL_OMIT = new Set([
     "compass_index",
     "compass_watch",
     "compass_impact",
+    "compass_affected_tests",
+    "compass_hotspots",
+    "compass_coupling",
     "compass_trace",
     "compass_visualize",
     "lawbook_init",