@esneiderbravo/speclaw 0.3.10 → 0.3.12

package/dist/cli/commands/lawbook.js

@@ -1,11 +1,13 @@
 import { specInit, specValidate, specSync, specArchive, specList, } from "../../modules/lawbook/engine.js";
+import { handleLevel } from "../../modules/lawbook/quick.js";
+import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
     // The MCP path passes the date in; the CLL runs on a real machine, so read it here.
     return new Date().toISOString().slice(0, 10);
 }
 /**
- * Run a spec-workflow subcommand: init, list, validate, sync, or archive.
+ * Run a spec-workflow subcommand: init, list, validate, sync, archive, or level.
  *
  * @param flags - Parsed flags; `_[0]` is the subcommand and `_[1]` the change name where required.
  * @throws Exits the process with code 1 on unknown subcommands, missing arguments, or engine errors.
@@ -27,13 +29,48 @@ export async function runSpec(flags) {
                 if (!r.initialized)
                     return ui.warn("No lawbook/ — run `speclaw lawbook init`.");
                 ui.heading("Lawbook workspace");
-                ui.info(`active changes: ${r.activeChanges.join(", ") || "none"}`);
+                if (r.activeChanges.length === 0)
+                    ui.info("active changes: none");
+                else {
+                    ui.info("active changes:");
+                    for (const name of r.activeChanges) {
+                        const lvl = r.activeLevels[name] ?? 3;
+                        ui.info(`  ${name}  (level ${lvl})`);
+                    }
+                }
                 ui.info(`archived: ${r.archivedChanges.join(", ") || "none"}`);
                 ui.info(`capabilities: ${r.capabilities.join(", ") || "none"}`);
                 return;
             }
+            case "level": {
+                const modeRaw = change ?? "propose";
+                const mode = modeRaw;
+                if (!["propose", "set", "promote", "explain"].includes(mode)) {
+                    ui.err("Usage: speclaw lawbook level <propose|set|promote|explain> [--change <c>] [--path …] [--level N] [--reason …] [--json]");
+                    process.exit(1);
+                }
+                const levelFlag = flags.level;
+                const level = levelFlag === undefined || levelFlag === true
+                    ? undefined
+                    : Number(levelFlag);
+                const result = handleLevel({
+                    projectPath: cwd,
+                    mode,
+                    change: typeof flags.change === "string" ? flags.change : flags._[2],
+                    paths: list(flags.path),
+                    symbols: list(flags.symbol),
+                    level,
+                    reason: typeof flags.reason === "string" ? flags.reason : undefined,
+                });
+                if (flags.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
             case "validate": {
-                const r = specValidate(cwd, req(change, "spec validate <change>"));
+                const r = specValidate(cwd, req(change, "lawbook validate <change>"));
                 if (r.valid)
                     ui.ok(`${r.change} is valid (${r.deltaSpecs.length} delta spec(s))`);
                 else {
@@ -47,13 +84,13 @@ export async function runSpec(flags) {
                 return;
             }
             case "sync": {
-                const r = specSync(cwd, req(change, "spec sync <change>"));
+                const r = specSync(cwd, req(change, "lawbook sync <change>"));
                 ui.ok(`promoted ${r.promoted.length} spec(s)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 return;
             }
             case "archive": {
-                const r = specArchive(cwd, req(change, "spec archive <change>"), today());
+                const r = specArchive(cwd, req(change, "lawbook archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 for (const s of r.seals) {
@@ -66,7 +103,7 @@ export async function runSpec(flags) {
                 return;
             }
             default:
-                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive> [change]");
+                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level> [change]");
                 process.exit(1);
         }
     }

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

@@ -0,0 +1,35 @@
+import { list } from "../lib/args.js";
+import { ui } from "../lib/ui.js";
+import { scaffoldQuick } from "../../modules/lawbook/quick.js";
+/**
+ * Scaffold a level-0 change (`speclaw quick <name>`).
+ *
+ * @param flags - `_[0]` is the change name; optional `--path` / `--symbol` / `--json`.
+ */
+export async function runQuick(flags) {
+    const cwd = process.cwd();
+    const name = flags._[0];
+    if (!name || typeof name !== "string") {
+        ui.err("Usage: speclaw quick <name> [--path <file>] [--symbol <sym>] [--json]");
+        process.exit(1);
+    }
+    try {
+        const result = scaffoldQuick(cwd, name, {
+            paths: list(flags.path),
+            symbols: list(flags.symbol),
+        });
+        if (flags.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        ui.ok(`level-0 change ${ui.code(result.change)} at ${result.dir}`);
+        ui.info(result.proposal.rationale);
+        if (result.proposal.level !== null && result.proposal.level > 0) {
+            ui.warn(`measured proposal was level ${result.proposal.level} — promote if the fix grows`);
+        }
+    }
+    catch (err) {
+        ui.err(err.message);
+        process.exit(1);
+    }
+}

package/dist/cli/commands/update.js

@@ -117,6 +117,24 @@ 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.",
+    },
+    {
+        version: "0.3.12",
+        describe: "Adaptive ceremony levels 0–3, speclaw quick, lawbook_level",
+        agentPrompt: "- Mention ceremony levels 0–3 (`change.json`), `speclaw quick` for level-0 scaffolds, and " +
+            "`lawbook_level` / `speclaw lawbook level` for propose/set/promote. Artifact volume follows " +
+            "the confirmed level; missing `change.json` still means full ceremony (level 3). Optional " +
+            "`ceremony:` block in `lawbook/config.yaml` (cuts default [3, 8, 15]). Update LAWS / " +
+            "docs/standards/lawbook.md wording if the project still says every change needs all four artifacts.\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,12 +25,16 @@ 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
 
 Lawbook (spec-driven workflow)
+  quick <name>             Scaffold a level-0 change (record.md + reports)
   lawbook init             Create the lawbook/ workspace
   lawbook list             Active/archived changes and capabilities
+  lawbook level <mode>     Propose/set/promote/explain ceremony level (--json)
   lawbook validate <c>     Validate a change's artifacts
   lawbook sync <c>         Promote delta specs to canonical
   lawbook archive <c>      Finalize and archive a change
@@ -51,9 +55,10 @@ 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), `quick` (often --json),
+// `mcp` (a long-running stdio
+// server), and `init` (already opens with the fuller `banner()`).
 const HEADER_COMMANDS = new Set([
     undefined,
     "help",
@@ -69,6 +74,7 @@ const HEADER_COMMANDS = new Set([
     "index",
     "watch",
     "lawbook",
+    "quick",
 ]);
 /**
  * Print the branded header once, ahead of a command's output, when it is a
@@ -92,6 +98,10 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "drift" && flags.json)
         return;
+    if (cmd === "quick" && flags.json)
+        return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "level")
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -128,9 +138,13 @@ 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);
+        case "quick":
+            return (await import("./commands/quick.js")).runQuick(flags);
         case "lawbook":
             return (await import("./commands/lawbook.js")).runSpec(flags);
         case "doctor":

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,
+    };
+}