@esneiderbravo/speclaw 0.3.9 → 0.3.11

package/dist/modules/compass/affected.js

@@ -0,0 +1,249 @@
+/**
+ * Static affected-test selection: reverse reachability into `files.is_test = 1`,
+ * plus a ready-to-run command string.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { changedFiles, isGitRepo } from "../../shared/git.js";
+import { openDb, indexExists } from "./db.js";
+import { impact } from "./query.js";
+import { loadAffectedConfig, matchGlobalFiles, matchesAny, } from "./affected-config.js";
+/**
+ * Select a safe superset of test files affected by a change.
+ *
+ * @param projectPath - Absolute project root with a Compass index.
+ * @param query - Files, symbols, and/or a git diff base ref.
+ */
+export function affectedTests(projectPath, query = {}) {
+    if (!indexExists(projectPath)) {
+        throw new Error("No index found. Build it first with the index_build tool (creates .speclaw/index.db).");
+    }
+    const cfg = loadAffectedConfig(projectPath);
+    const warnings = [];
+    warnings.push(...warnUnindexedLanguages(projectPath));
+    let files = [...(query.files ?? [])];
+    if (query.fromDiff !== undefined) {
+        if (!isGitRepo(projectPath)) {
+            throw new Error("fromDiff requires a git repository");
+        }
+        const base = query.fromDiff === "WORKTREE" || query.fromDiff === "" ? "HEAD" : query.fromDiff;
+        // WORKTREE ≈ uncommitted: use merge-base against HEAD's first-parent via changedFiles("HEAD")
+        // when the caller passes a branch/ref; for literal WORKTREE fall back to HEAD...working tree
+        // is not in changedFiles — use the ref as merge-base target.
+        const diffFiles = query.fromDiff === "WORKTREE"
+            ? listWorktreeChanges(projectPath)
+            : changedFiles(projectPath, base);
+        files = [...new Set([...files, ...diffFiles])];
+        if (files.length === 0) {
+            return {
+                mode: "static",
+                reason: "no changed files",
+                tests: [],
+                skipped: { files: countTestFiles(projectPath), percent: 100 },
+                command: buildTestCommand(projectPath, [], cfg, "none"),
+                warnings,
+            };
+        }
+    }
+    const glob = matchGlobalFiles(files, cfg);
+    if (glob.matched.length > 0) {
+        const allTests = listTestFiles(projectPath);
+        return {
+            mode: "all",
+            reason: `global file matched (${glob.matched.join(", ")})`,
+            tests: allTests.map((file) => ({ file, nodes: 0, minDepth: 0 })),
+            skipped: { files: 0, percent: 0 },
+            command: buildTestCommand(projectPath, [], cfg, "all"),
+            warnings,
+        };
+    }
+    const impactOpts = {
+        files: files.length > 0 ? files : undefined,
+        symbol: query.symbols?.length === 1 ? query.symbols[0] : undefined,
+        maxDepth: query.maxDepth ?? 6,
+        format: "flat",
+        target: "test",
+        edgeKinds: ["call", "import"],
+    };
+    // Multiple symbols → union flat impacts.
+    const nodes = [...(impact(projectPath, impactOpts).nodes ?? [])];
+    if (query.symbols && query.symbols.length > 1) {
+        const seen = new Set(nodes.map((n) => n.nodeId));
+        for (const sym of query.symbols) {
+            for (const n of impact(projectPath, {
+                symbol: sym,
+                format: "flat",
+                maxDepth: impactOpts.maxDepth,
+            }).nodes ?? []) {
+                if (!seen.has(n.nodeId)) {
+                    seen.add(n.nodeId);
+                    nodes.push(n);
+                }
+            }
+        }
+    }
+    // Also include directly changed test files.
+    const testHits = new Map();
+    for (const f of files) {
+        const norm = f.split("\\").join("/");
+        if (matchesAny(norm, cfg.testGlobs)) {
+            testHits.set(norm, { file: norm, nodes: 0, minDepth: 0 });
+        }
+    }
+    const db = openDb(projectPath);
+    try {
+        const isTestByPath = new Map();
+        for (const row of db.prepare("SELECT path, is_test FROM files").all()) {
+            isTestByPath.set(row.path, row.is_test === 1);
+        }
+        for (const n of nodes) {
+            if (!isTestByPath.get(n.file))
+                continue;
+            const prior = testHits.get(n.file);
+            if (!prior) {
+                testHits.set(n.file, { file: n.file, nodes: 1, minDepth: n.depth });
+            }
+            else {
+                prior.nodes += 1;
+                prior.minDepth = Math.min(prior.minDepth, n.depth);
+            }
+        }
+    }
+    finally {
+        db.close();
+    }
+    const tests = [...testHits.values()].sort((a, b) => a.file.localeCompare(b.file));
+    const totalTests = countTestFiles(projectPath);
+    const skippedFiles = Math.max(0, totalTests - tests.length);
+    const percent = totalTests === 0 ? 0 : Math.round((skippedFiles / totalTests) * 100);
+    return {
+        mode: "static",
+        reason: files.length > 0
+            ? `changed ${files.length} file(s)`
+            : query.symbols?.length
+                ? `symbols ${query.symbols.join(", ")}`
+                : "empty selection",
+        tests,
+        skipped: { files: skippedFiles, percent },
+        command: buildTestCommand(projectPath, tests.map((t) => t.file), cfg, tests.length === 0 ? "none" : "subset"),
+        warnings,
+    };
+}
+function listWorktreeChanges(projectPath) {
+    // Prefer merge-base against main/master when available; else HEAD.
+    for (const base of ["main", "master", "HEAD"]) {
+        const files = changedFiles(projectPath, base);
+        if (files.length > 0 || base === "HEAD")
+            return files;
+    }
+    return [];
+}
+function countTestFiles(projectPath) {
+    if (!indexExists(projectPath))
+        return 0;
+    const db = openDb(projectPath);
+    try {
+        const row = db.prepare("SELECT COUNT(*) AS n FROM files WHERE is_test = 1").get();
+        return Number(row.n);
+    }
+    finally {
+        db.close();
+    }
+}
+function listTestFiles(projectPath) {
+    const db = openDb(projectPath);
+    try {
+        return db.prepare("SELECT path FROM files WHERE is_test = 1 ORDER BY path").all().map((r) => r.path);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Build an executable test command from package.json scripts.test when present.
+ *
+ * @param projectPath - Project root.
+ * @param tests - Selected test paths (ignored for mode `all`).
+ * @param _cfg - Reserved for future runner overrides.
+ * @param mode - `all` | `subset` | `none`.
+ */
+export function buildTestCommand(projectPath, tests, _cfg, mode) {
+    const pkgPath = path.join(projectPath, "package.json");
+    let script;
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            script = pkg.scripts?.test;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (mode === "all") {
+        return script ? "npm test" : "node --test";
+    }
+    if (mode === "none" || tests.length === 0) {
+        return script ? "npm test -- --test-name-pattern=^$" : "node --test --test-name-pattern=^$";
+    }
+    const args = tests.map(shellQuote).join(" ");
+    if (script && /\bnode\s+--test\b/.test(script)) {
+        return `node --test ${args}`;
+    }
+    if (script) {
+        // Pass paths after `--` for npm/vitest/jest-style scripts.
+        return `npm test -- ${args}`;
+    }
+    return `node --test ${args}`;
+}
+function shellQuote(p) {
+    if (/^[A-Za-z0-9_./-]+$/.test(p))
+        return p;
+    return `'${p.replace(/'/g, `'\\''`)}'`;
+}
+/** Warn when present extensions are not in the indexed language set. */
+function warnUnindexedLanguages(projectPath) {
+    const indexedExts = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]);
+    const seen = new Set();
+    const warnings = [];
+    walkQuick(projectPath, (rel) => {
+        const ext = path.extname(rel).toLowerCase();
+        if (!ext || indexedExts.has(ext) || seen.has(ext))
+            return;
+        // Only flag common source extensions that Compass does not parse.
+        if (![".go", ".rs", ".java", ".kt", ".rb", ".php", ".cs"].includes(ext))
+            return;
+        seen.add(ext);
+        warnings.push(`${ext} files are present but not indexed by Compass`);
+    });
+    return warnings;
+}
+function walkQuick(root, visit) {
+    const skip = new Set([".git", "node_modules", "dist", "dist-test", ".speclaw", "vendor"]);
+    const stack = [root];
+    let n = 0;
+    while (stack.length && n < 5000) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") && e.name !== ".speclaw") {
+                if (e.isDirectory() && e.name !== ".github")
+                    continue;
+            }
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skip.has(e.name))
+                    stack.push(full);
+            }
+            else if (e.isFile()) {
+                n++;
+                visit(path.relative(root, full));
+            }
+        }
+    }
+}

package/dist/modules/compass/db.js

@@ -10,8 +10,11 @@ CREATE TABLE IF NOT EXISTS files (
   id INTEGER PRIMARY KEY,
   path TEXT UNIQUE NOT NULL,
   hash TEXT NOT NULL,
-  lang TEXT NOT NULL
+  lang TEXT NOT NULL,
+  is_test INTEGER NOT NULL DEFAULT 0,
+  module TEXT NOT NULL DEFAULT ''
 );
+CREATE INDEX IF NOT EXISTS idx_files_is_test ON files(is_test);
 -- nodes: the definitions in the codebase (functions, classes, methods, types).
 CREATE TABLE IF NOT EXISTS nodes (
   id INTEGER PRIMARY KEY,
@@ -30,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,
@@ -101,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 = "6";
+export const SCHEMA_VERSION = "8";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -127,8 +137,16 @@ function isStale(db) {
         return false;
     if (readSchemaVersion(db) !== SCHEMA_VERSION)
         return true;
-    const cols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
-    return !cols.includes("src_node_id") || !cols.includes("dst_node_id");
+    const edgeCols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
+    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);
+    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) {
@@ -138,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,
+    };
+}