@esneiderbravo/speclaw 0.3.10 → 0.3.11

package/dist/cli/commands/query.js

@@ -1,12 +1,13 @@
 import { explore, search, recall, impact, trace } from "../../modules/compass/query.js";
 import { affectedTests } from "../../modules/compass/affected.js";
+import { hotspots, coupling } from "../../modules/compass/hotspots.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 /**
  * Run a Compass query from the shell — the same surface agents call via MCP.
  *
- * @param cmd - Query verb: `explore`, `search`, `recall`, `impact`, `trace`, or
- *   `affected-tests`.
+ * @param cmd - Query verb: `explore`, `search`, `recall`, `impact`, `trace`,
+ *   `affected-tests`, `hotspots`, or `coupling`.
  * @param flags - Parsed flags supplying positional args and options in `_`.
  * @throws Exits the process with code 1 on missing arguments or query errors.
  */
@@ -114,6 +115,52 @@ export async function runQuery(cmd, flags) {
                 result.warnings.forEach((w) => ui.warn(w));
                 return;
             }
+            case "hotspots": {
+                const sortRaw = typeof flags.sort === "string" ? flags.sort : undefined;
+                const sortBy = sortRaw === "churn" || sortRaw === "complexity" || sortRaw === "combined"
+                    ? sortRaw
+                    : "combined";
+                const result = hotspots(cwd, {
+                    days: flags.days ? Number(flags.days) : undefined,
+                    since: typeof flags.since === "string" ? flags.since : undefined,
+                    sortBy,
+                    limit: flags.limit ? Number(flags.limit) : undefined,
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.heading(`Hotspots (${result.window.label}, sort=${result.sortBy}): ${result.hotspots.length}`);
+                for (const h of result.hotspots) {
+                    const health = h.health
+                        ? `branches=${h.health.worstBranches} nest=${h.health.worstNesting} loc=${h.health.worstLoc}`
+                        : "health=n/a";
+                    ui.info(`${h.file}  commits=${h.activity.commits} authors=${h.activity.authors}  ${health}`);
+                }
+                result.warnings.forEach((w) => ui.warn(w));
+                return;
+            }
+            case "coupling": {
+                const file = need(args[0], "coupling <file>");
+                const result = coupling(cwd, file, {
+                    days: flags.days ? Number(flags.days) : undefined,
+                    since: typeof flags.since === "string" ? flags.since : undefined,
+                    minShared: flags["min-shared"] ? Number(flags["min-shared"]) : undefined,
+                    maxFilesPerCommit: flags["max-files"] ? Number(flags["max-files"]) : undefined,
+                    limit: flags.limit ? Number(flags.limit) : undefined,
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.heading(`Coupling for ${result.file} (${result.window.label}): ${result.partners.length} partner(s)`);
+                ui.info(`scanned=${result.diagnostics.commitsScanned} skippedTooLarge=${result.diagnostics.skippedTooLarge}`);
+                for (const p of result.partners) {
+                    ui.info(`${p.file}  both=${p.both} strength=${p.strength.toFixed(3)} in_graph=${p.inGraph} isTestPair=${p.isTestPair}`);
+                }
+                result.warnings.forEach((w) => ui.warn(w));
+                return;
+            }
             case "trace": {
                 const r = trace(cwd, need(args[0], "trace <from> <to>"), need(args[1], "trace <from> <to>"));
                 ui.heading(`Trace ${r.from} → ${r.to}`);

package/dist/cli/commands/update.js

@@ -117,6 +117,14 @@ const MIGRATIONS = [
             "`.speclaw/affected.json` overrides globals/test globs.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.11",
+        describe: "Hotspots + coupling: schema 8 node_metrics, 90d activity window",
+        agentPrompt: "- Mention `compass_hotspots` / `speclaw hotspots` and `compass_coupling` / `speclaw coupling` " +
+            "(activity × AST health; Jaccard strength + in_graph + isTestPair). Compass schema is now 8 " +
+            "(`node_metrics`) — reindex with `speclaw index`. Default history window is 90 days.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/index.js

@@ -25,6 +25,8 @@ Compass (code intelligence — the same surface agents use via MCP)
   recall "<query>"         Find code by meaning (semantic)
   impact <node>            Blast radius (grouped by module; --flat / --json)
   affected-tests           Tests affected by a change (--file / --from-diff / --json)
+  hotspots                 Rank files by recent churn × AST complexity (--json / --sort)
+  coupling <file>          Temporal co-change partners for a file (--json)
   trace <from> <to>        A call path between two nodes
   visualize [node]         Interactive HTML graph → .speclaw/graph.html
 
@@ -51,9 +53,9 @@ Other
 // Commands that open with the one-line branded header. These are the
 // interactive, human-facing commands whose stdout is prose. Deliberately
 // excluded: `version`/`--version`/`-v` (bare scriptable value), the Compass
-// query family (`explore`/`search`/`recall`/`impact`/`trace`/`affected-tests`,
-// machine-consumed output), `mcp` (a long-running stdio server), and `init`
-// (already opens with the fuller `banner()`).
+// query family (`explore`/`search`/`recall`/`impact`/`trace`/`affected-tests`/
+// `hotspots`/`coupling`, machine-consumed output), `mcp` (a long-running stdio
+// server), and `init` (already opens with the fuller `banner()`).
 const HEADER_COMMANDS = new Set([
     undefined,
     "help",
@@ -128,6 +130,8 @@ async function dispatch(cmd, flags) {
         case "impact":
         case "trace":
         case "affected-tests":
+        case "hotspots":
+        case "coupling":
             return (await import("./commands/query.js")).runQuery(cmd, flags);
         case "visualize":
             return (await import("./commands/visualize.js")).runVisualize(flags);

package/dist/modules/compass/db.js

@@ -33,6 +33,13 @@ CREATE TABLE IF NOT EXISTS nodes (
 CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
 CREATE INDEX IF NOT EXISTS idx_nodes_norm_hash ON nodes(norm_hash);
+-- node_metrics: AST health frames (LOC / nesting / branches) per definition.
+CREATE TABLE IF NOT EXISTS node_metrics (
+  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  loc INTEGER NOT NULL,
+  max_nesting INTEGER NOT NULL,
+  branches INTEGER NOT NULL
+);
 -- edges: a reference from one node to a named target, resolved lazily.
 CREATE TABLE IF NOT EXISTS edges (
   id INTEGER PRIMARY KEY,
@@ -104,7 +111,7 @@ CREATE INDEX IF NOT EXISTS idx_anchors_symbol ON spec_anchors(symbol_name);
 CREATE INDEX IF NOT EXISTS idx_anchors_node ON spec_anchors(node_id);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "7";
+export const SCHEMA_VERSION = "8";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -134,7 +141,12 @@ function isStale(db) {
     if (!edgeCols.includes("src_node_id") || !edgeCols.includes("dst_node_id"))
         return true;
     const fileCols = db.prepare("PRAGMA table_info(files)").all().map((c) => c.name);
-    return !fileCols.includes("is_test") || !fileCols.includes("module");
+    if (!fileCols.includes("is_test") || !fileCols.includes("module"))
+        return true;
+    const hasMetrics = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'node_metrics'")
+        .get();
+    return !hasMetrics;
 }
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
@@ -144,6 +156,7 @@ function resetSchema(db) {
     DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;
+    DROP TABLE IF EXISTS node_metrics;
     DROP TABLE IF EXISTS nodes;
     DROP TABLE IF EXISTS files;
     DROP TABLE IF EXISTS meta;

package/dist/modules/compass/extract.js

@@ -37,6 +37,46 @@ function calleeName(node, lang) {
 function signatureOf(node) {
     return node.text.split("\n")[0].trim().slice(0, 200);
 }
+const BOOL_OPS = new Set(["&&", "||", "and", "or"]);
+/**
+ * Compute LOC / max nesting / branch counts for a definition subtree.
+ * Nesting depth is relative to the definition body (starts at 0).
+ */
+export function metricsOf(defNode, lang) {
+    const nesting = new Set(lang.nestingNodes);
+    const branchesSet = new Set(lang.branchNodes);
+    let maxNesting = 0;
+    let branches = 0;
+    const walk = (node, depth) => {
+        const nestHere = nesting.has(node.type);
+        const nextDepth = nestHere ? depth + 1 : depth;
+        if (nestHere)
+            maxNesting = Math.max(maxNesting, nextDepth);
+        if (branchesSet.has(node.type)) {
+            branches++;
+        }
+        else if (node.type === "binary_expression") {
+            const op = node.childForFieldName("operator")?.text ?? "";
+            if (BOOL_OPS.has(op))
+                branches++;
+        }
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child)
+                walk(child, nextDepth);
+        }
+    };
+    for (let i = 0; i < defNode.childCount; i++) {
+        const child = defNode.child(i);
+        if (child)
+            walk(child, 0);
+    }
+    return {
+        loc: defNode.endPosition.row - defNode.startPosition.row + 1,
+        maxNesting,
+        branches,
+    };
+}
 /** Parse Covers:/Needs: directives from a comment node's text. */
 function parseCoverageComment(node, ownerIndex) {
     const text = node.text;
@@ -105,6 +145,7 @@ export async function extract(source, lang) {
             const name = defName(node);
             if (name) {
                 const index = symbols.length;
+                const health = metricsOf(node, lang);
                 symbols.push({
                     name,
                     kind: kinds.get(node.type),
@@ -116,6 +157,9 @@ export async function extract(source, lang) {
                     signature: signatureOf(node),
                     bodyHash: rawHash(source, node.startIndex, node.endIndex),
                     normHash: structuralHash(node),
+                    loc: health.loc,
+                    maxNesting: health.maxNesting,
+                    branches: health.branches,
                 });
                 nextOwner = index;
             }

package/dist/modules/compass/git-history-cache.js

@@ -1,4 +1,4 @@
-import { churn, coChanges, headSha, } from "../../shared/git-history.js";
+import { churn, coChanges, fileActivity, headSha, } from "../../shared/git-history.js";
 import { openDb } from "./db.js";
 /**
  * Look up a cached payload valid at the current HEAD, or compute it and store it.
@@ -52,6 +52,19 @@ export function cachedChurn(projectPath, opts = {}) {
         return { shallow: parsed.shallow, byPath: new Map(parsed.byPath) };
     });
 }
+/**
+ * {@link fileActivity}, memoized in the Compass index until `HEAD` moves.
+ */
+export function cachedFileActivity(projectPath, opts = {}) {
+    const key = `fileActivity:${JSON.stringify({ since: opts.since ?? null, pathspec: opts.pathspec ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => fileActivity(projectPath, opts), (value) => JSON.stringify({
+        shallow: value.shallow,
+        byPath: [...value.byPath],
+    }), (payload) => {
+        const parsed = JSON.parse(payload);
+        return { shallow: parsed.shallow, byPath: new Map(parsed.byPath) };
+    });
+}
 /**
  * {@link coChanges}, memoized in the Compass index until `HEAD` moves.
  *
@@ -60,6 +73,10 @@ export function cachedChurn(projectPath, opts = {}) {
  * @returns The co-change pairs and the shallow marker, cached per HEAD.
  */
 export function cachedCoChanges(projectPath, opts = {}) {
-    const key = `coChanges:${JSON.stringify({ since: opts.since ?? null, minSupport: opts.minSupport ?? null })}`;
+    const key = `coChanges:${JSON.stringify({
+        since: opts.since ?? null,
+        minSupport: opts.minSupport ?? null,
+        maxFilesPerCommit: opts.maxFilesPerCommit ?? null,
+    })}`;
     return readThrough(projectPath, headSha(projectPath), key, () => coChanges(projectPath, opts), (value) => JSON.stringify(value), (payload) => JSON.parse(payload));
 }

package/dist/modules/compass/hotspots.js

@@ -0,0 +1,230 @@
+import { openDb } from "./db.js";
+import { cachedCoChanges, cachedFileActivity } from "./git-history-cache.js";
+import { jaccardStrength } from "../../shared/git-history.js";
+/** Default history window for hotspot / coupling ranking. */
+export const DEFAULT_WINDOW_DAYS = 90;
+/** Default max files in a commit before coupling discards it. */
+export const DEFAULT_MAX_FILES_PER_COMMIT = 50;
+/** Default minimum shared commits for a coupling pair. */
+export const DEFAULT_MIN_SHARED = 2;
+/** ISO date string for `git --since` N days ago (UTC calendar day). */
+export function sinceDaysAgo(days, now = new Date()) {
+    const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    d.setUTCDate(d.getUTCDate() - days);
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Combined sort heuristic: activity commits × (1 + worstBranches + worstNesting/2).
+ * Axes remain on each entry; this score is only for ordering.
+ */
+function combinedScore(activity, health) {
+    const complexity = health ? 1 + health.worstBranches + health.worstNesting / 2 : 1;
+    return activity.commits * complexity;
+}
+function loadFileHealth(projectPath) {
+    const db = openDb(projectPath);
+    try {
+        const rows = db
+            .prepare(`SELECT f.path AS path,
+                COUNT(n.id) AS symbols,
+                COALESCE(MAX(m.loc), 0) AS worst_loc,
+                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 node_metrics m ON m.node_id = n.id
+         GROUP BY f.id`)
+            .all();
+        const map = new Map();
+        for (const r of rows) {
+            map.set(r.path, {
+                worstLoc: Number(r.worst_loc),
+                worstNesting: Number(r.worst_nesting),
+                worstBranches: Number(r.worst_branches),
+                symbols: Number(r.symbols),
+            });
+        }
+        return map;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Rank files by git activity × AST health for agent attention.
+ *
+ * @param projectPath - Project root with `.speclaw/index.db` and git history.
+ * @param opts - Window, sort, and result limit.
+ */
+export function hotspots(projectPath, opts = {}) {
+    const days = opts.days ?? DEFAULT_WINDOW_DAYS;
+    const since = opts.since ?? sinceDaysAgo(days);
+    const sortBy = opts.sortBy ?? "combined";
+    const limit = opts.limit ?? 25;
+    const warnings = [];
+    const activity = cachedFileActivity(projectPath, { since });
+    if (activity.shallow) {
+        warnings.push("Repository is a shallow clone; history may be truncated.");
+    }
+    const healthByFile = loadFileHealth(projectPath);
+    const entries = [];
+    for (const [file, act] of activity.byPath) {
+        if (act.commits <= 0)
+            continue;
+        const health = healthByFile.get(file) ?? null;
+        entries.push({
+            file,
+            activity: {
+                commits: act.commits,
+                linesAdded: act.linesAdded,
+                linesDeleted: act.linesDeleted,
+                authors: act.authors,
+            },
+            health,
+            combinedScore: combinedScore(act, health),
+        });
+    }
+    const rank = (a, b) => {
+        if (sortBy === "churn") {
+            return (b.activity.commits - a.activity.commits ||
+                b.activity.linesAdded +
+                    b.activity.linesDeleted -
+                    (a.activity.linesAdded + a.activity.linesDeleted) ||
+                a.file.localeCompare(b.file));
+        }
+        if (sortBy === "complexity") {
+            const bw = b.health?.worstBranches ?? -1;
+            const aw = a.health?.worstBranches ?? -1;
+            return (bw - aw ||
+                (b.health?.worstNesting ?? -1) - (a.health?.worstNesting ?? -1) ||
+                (b.health?.worstLoc ?? -1) - (a.health?.worstLoc ?? -1) ||
+                a.file.localeCompare(b.file));
+        }
+        return b.combinedScore - a.combinedScore || a.file.localeCompare(b.file);
+    };
+    entries.sort(rank);
+    return {
+        window: { days, since, label: `last ${days} days (since ${since})` },
+        sortBy,
+        hotspots: entries.slice(0, limit),
+        diagnostics: {
+            filesWithActivity: entries.length,
+            indexedHealthFiles: [...healthByFile.keys()].length,
+        },
+        warnings,
+    };
+}
+function fileMeta(projectPath, paths) {
+    const db = openDb(projectPath);
+    try {
+        const map = new Map();
+        if (paths.length === 0)
+            return map;
+        const placeholders = paths.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT id, path, is_test FROM files WHERE path IN (${placeholders})`)
+            .all(...paths);
+        for (const r of rows)
+            map.set(r.path, { isTest: r.is_test === 1, id: r.id });
+        return map;
+    }
+    finally {
+        db.close();
+    }
+}
+/** True when any call/import edge links symbols in the two files (either direction). */
+function pairInGraph(projectPath, a, b) {
+    const db = openDb(projectPath);
+    try {
+        const row = db
+            .prepare(`SELECT 1 AS ok
+         FROM edges e
+         JOIN files sf ON sf.id = e.src_file_id
+         JOIN nodes dn ON dn.id = e.dst_node_id
+         JOIN files df ON df.id = dn.file_id
+         WHERE e.kind IN ('call', 'import')
+           AND ((sf.path = ? AND df.path = ?) OR (sf.path = ? AND df.path = ?))
+         LIMIT 1`)
+            .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).
+        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 files df ON df.id = dn.file_id
+         WHERE e.dst_node_id IS NULL
+           AND e.kind IN ('call', 'import')
+           AND ((sf.path = ? AND df.path = ?) OR (sf.path = ? AND df.path = ?))
+         LIMIT 1`)
+            .get(a, b, b, a);
+        return Boolean(byName);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Temporal coupling partners for a seed file, with graph contrast facts.
+ */
+export function coupling(projectPath, file, opts = {}) {
+    const days = opts.days ?? DEFAULT_WINDOW_DAYS;
+    const since = opts.since ?? sinceDaysAgo(days);
+    const minShared = opts.minShared ?? DEFAULT_MIN_SHARED;
+    const maxFilesPerCommit = opts.maxFilesPerCommit ?? DEFAULT_MAX_FILES_PER_COMMIT;
+    const limit = opts.limit ?? 25;
+    const warnings = [];
+    const rel = file.replace(/^\.\//, "");
+    const co = cachedCoChanges(projectPath, {
+        since,
+        minSupport: minShared,
+        maxFilesPerCommit,
+    });
+    if (co.shallow) {
+        warnings.push("Repository is a shallow clone; history may be truncated.");
+    }
+    const activity = cachedFileActivity(projectPath, { since });
+    const commitsSelf = activity.byPath.get(rel)?.commits ?? 0;
+    const partnersRaw = [];
+    for (const p of co.pairs) {
+        if (p.a === rel)
+            partnersRaw.push({ other: p.b, both: p.count });
+        else if (p.b === rel)
+            partnersRaw.push({ other: p.a, both: p.count });
+    }
+    const paths = [rel, ...partnersRaw.map((p) => p.other)];
+    const meta = fileMeta(projectPath, paths);
+    const selfTest = meta.get(rel)?.isTest ?? false;
+    const partners = partnersRaw
+        .map(({ other, both }) => {
+        const commitsOther = activity.byPath.get(other)?.commits ?? 0;
+        const otherTest = meta.get(other)?.isTest ?? false;
+        return {
+            file: other,
+            both,
+            commitsSelf,
+            commitsOther,
+            strength: jaccardStrength(both, commitsSelf, commitsOther),
+            inGraph: pairInGraph(projectPath, rel, other),
+            isTestPair: selfTest !== otherTest && (selfTest || otherTest),
+        };
+    })
+        .sort((a, b) => b.strength - a.strength || b.both - a.both || a.file.localeCompare(b.file))
+        .slice(0, limit);
+    return {
+        file: rel,
+        window: { days, since, label: `last ${days} days (since ${since})` },
+        partners,
+        diagnostics: {
+            commitsScanned: co.commitsScanned ?? 0,
+            skippedTooLarge: co.skippedTooLarge ?? 0,
+            maxFilesPerCommit,
+            minShared,
+        },
+        warnings,
+    };
+}

package/dist/modules/compass/indexer.js

@@ -214,6 +214,7 @@ export async function buildIndex(projectPath, onProgress) {
     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
@@ -265,6 +266,7 @@ 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));

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/register.js

@@ -4,6 +4,7 @@ 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) ───
@@ -55,6 +56,22 @@ export function registerCompass(server, opts = {}) {
         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

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

package/dist/shared/git-history.js

@@ -144,34 +144,114 @@ export function churn(projectPath, opts = {}) {
     }
     return { shallow, byPath };
 }
+/**
+ * Richer per-file activity (commits, lines added/deleted, distinct authors).
+ *
+ * Fail-soft and shallow-aware like {@link churn}. Does not follow renames.
+ * Suitable for hotspot ranking; existing {@link churn} callers stay on commit counts.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window and `pathspec` filter.
+ */
+export function fileActivity(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    // Per commit: \0<author>\0 then numstat lines until the next leading NUL.
+    const args = ["log", "--numstat", "--format=%x00%an%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    if (opts.pathspec && opts.pathspec.length > 0)
+        args.push("--", ...opts.pathspec);
+    const out = git(projectPath, args);
+    const byPath = new Map();
+    const authorsByPath = new Map();
+    if (out === null)
+        return { shallow, byPath };
+    const records = out.split(NUL);
+    for (let i = 1; i + 1 < records.length; i += 2) {
+        const author = (records[i] ?? "").trim();
+        const tail = records[i + 1] ?? "";
+        if (!author && !tail.trim())
+            continue;
+        for (const line of tail.split("\n")) {
+            const cols = line.split("\t");
+            if (cols.length < 3)
+                continue;
+            const path = cols[2].replace(/^\0+/, "").trim();
+            if (!path)
+                continue;
+            const added = numstat(cols[0]);
+            const deleted = numstat(cols[1]);
+            const cur = byPath.get(path) ?? { commits: 0, linesAdded: 0, linesDeleted: 0, authors: 0 };
+            cur.commits += 1;
+            cur.linesAdded += added;
+            cur.linesDeleted += deleted;
+            byPath.set(path, cur);
+            if (author) {
+                let set = authorsByPath.get(path);
+                if (!set) {
+                    set = new Set();
+                    authorsByPath.set(path, set);
+                }
+                set.add(author);
+            }
+        }
+    }
+    for (const [path, act] of byPath) {
+        act.authors = authorsByPath.get(path)?.size ?? 0;
+    }
+    return { shallow, byPath };
+}
+/**
+ * Jaccard-style coupling strength: `both / (commitsA + commitsB - both)`.
+ * Returns `0` when the denominator is zero.
+ */
+export function jaccardStrength(both, commitsA, commitsB) {
+    const denom = commitsA + commitsB - both;
+    if (denom <= 0)
+        return 0;
+    return both / denom;
+}
 /**
  * For every pair of files that changed together, how many commits touched both.
  *
  * Groups each commit's changed files and emits a count per unordered pair. Pairs
- * with fewer than `minSupport` shared commits are omitted. Fail-soft (empty on
- * git failure) and does not follow renames. Carries the shallow marker.
+ * with fewer than `minSupport` shared commits are omitted. Commits that touch
+ * more than `maxFilesPerCommit` files (when set) are skipped and counted in
+ * `skippedTooLarge`. Fail-soft (empty on git failure) and does not follow
+ * renames. Carries the shallow marker.
  *
  * @param projectPath - Project root to query.
- * @param opts - Optional `since` window and `minSupport` threshold (default `1`).
+ * @param opts - Optional `since` window, `minSupport` (default `1`), and
+ *   `maxFilesPerCommit` (omit to keep all commits).
  * @returns The qualifying co-change pairs and the shallow marker.
  */
 export function coChanges(projectPath, opts = {}) {
     const shallow = isShallowRepo(projectPath);
     const minSupport = opts.minSupport ?? 1;
+    const maxFiles = opts.maxFilesPerCommit;
     const args = ["log", "--name-only", "--format=%x00"];
     if (opts.since)
         args.push(`--since=${opts.since}`);
     const out = git(projectPath, args);
     if (out === null)
-        return { shallow, pairs: [] };
+        return { shallow, pairs: [], skippedTooLarge: 0, commitsScanned: 0 };
     const counts = new Map();
+    let skippedTooLarge = 0;
+    let commitsScanned = 0;
     // Each commit's file list is the run of lines between two %x00 markers.
     for (const commitBlock of out.split(NUL)) {
         const files = commitBlock
             .split("\n")
             .map((l) => l.trim())
             .filter((l) => l.length > 0);
+        if (files.length === 0)
+            continue;
         const unique = [...new Set(files)].sort();
+        if (maxFiles !== undefined && unique.length > maxFiles) {
+            skippedTooLarge++;
+            continue;
+        }
+        commitsScanned++;
         for (let i = 0; i < unique.length; i++) {
             for (let j = i + 1; j < unique.length; j++) {
                 const key = `${unique[i]}\t${unique[j]}`;
@@ -187,7 +267,7 @@ export function coChanges(projectPath, opts = {}) {
         pairs.push({ a: a, b: b, count });
     }
     pairs.sort((x, y) => y.count - x.count || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
-    return { shallow, pairs };
+    return { shallow, pairs, skippedTooLarge, commitsScanned };
 }
 /**
  * The SHA of the most recent commit that touched `relPath`, or `null` when the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "publishConfig": {
     "access": "public"
   },