@monoes/monograph 1.2.0 → 1.2.1

package/dist/src/graph/dependency-closure.js

@@ -1,3 +1,4 @@
+const SQLITE_VAR_LIMIT = 200; // safe batch size for IN clauses
 export function computeDependencyClosure(db, maxNodes = 100) {
     // Get File nodes sorted by degree (most connected first)
     const fileNodes = db.prepare(`
@@ -15,6 +16,9 @@ export function computeDependencyClosure(db, maxNodes = 100) {
       JOIN nodes n ON n.id = e.target_id
       WHERE e.relation = 'IMPORTS' AND n.file_path IS NOT NULL
     `).all().map(r => r.file_path));
+    // Hoist prepared statement outside the per-node BFS loop to avoid recompiling
+    // on every iteration (N×maxNodes calls previously).
+    const edgeStmt = db.prepare(`SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`);
     const results = [];
     for (const fileNode of fileNodes) {
         // BFS forward (following IMPORTS edges from this node)
@@ -28,7 +32,7 @@ export function computeDependencyClosure(db, maxNodes = 100) {
             depth++;
             const next = [];
             for (const id of frontier) {
-                const edges = db.prepare(`SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`).all(id);
+                const edges = edgeStmt.all(id);
                 for (const e of edges) {
                     if (!visited.has(e.target_id)) {
                         visited.add(e.target_id);
@@ -45,12 +49,24 @@ export function computeDependencyClosure(db, maxNodes = 100) {
             }
             frontier = next;
         }
+        // Batch-resolve file_paths for all transitive deps in one chunked SQL query
+        // instead of one SELECT per dep (N+1 → O(deps/CHUNK) queries).
+        const depFilePathMap = new Map();
+        for (let i = 0; i < transitiveDeps.length; i += SQLITE_VAR_LIMIT) {
+            const chunk = transitiveDeps.slice(i, i + SQLITE_VAR_LIMIT);
+            const ph = chunk.map(() => '?').join(',');
+            const rows = db
+                .prepare(`SELECT id, file_path FROM nodes WHERE id IN (${ph})`)
+                .all(...chunk);
+            for (const row of rows)
+                depFilePathMap.set(row.id, row.file_path);
+        }
         // unusedTransitiveDeps: transitive deps whose file_path is NOT in importedFilePaths
         const unusedTransitiveDeps = transitiveDeps.filter(depId => {
-            const depNode = db.prepare('SELECT file_path FROM nodes WHERE id = ?').get(depId);
-            if (!depNode?.file_path)
+            const fp = depFilePathMap.get(depId);
+            if (!fp)
                 return false;
-            return !importedFilePaths.has(depNode.file_path);
+            return !importedFilePaths.has(fp);
         });
         results.push({
             nodeId: fileNode.id,

package/dist/src/graph/dependency-closure.js.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-closure.js","sourceRoot":"","sources":["../../../src/graph/dependency-closure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dependency-closure.js","sourceRoot":"","sources":["../../../src/graph/dependency-closure.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/dfs.d.ts

@@ -5,5 +5,19 @@ export interface DfsNode {
 export interface DfsOptions {
     maxDepth?: number;
 }
+export interface DfsResult {
+    visited: DfsNode[];
+    maxDepth: number;
+    nodeCount: number;
+}
 export declare function dfsTraversal(startId: string, adjacency: Map<string, string[]>, visitor: (node: DfsNode) => void, options?: DfsOptions): void;
+/** Collect all reachable nodes from startId via DFS, returning structured result. */
+export declare function dfsCollect(startId: string, adjacency: Map<string, string[]>, options?: DfsOptions): DfsResult;
+/** BFS level-order traversal — useful when shortest-path distance matters more than DFS order. */
+export declare function bfsTraversal(startId: string, adjacency: Map<string, string[]>, visitor: (node: DfsNode) => void, options?: DfsOptions): void;
+/**
+ * Format a DfsResult as structured text for LLM consumption.
+ * Groups nodes by depth level for easy reading.
+ */
+export declare function formatDfsResult(result: DfsResult, startId: string): string;
 //# sourceMappingURL=dfs.d.ts.map

package/dist/src/graph/dfs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dfs.d.ts","sourceRoot":"","sources":["../../../src/graph/dfs.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAChC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,EAChC,OAAO,GAAE,UAAe,GACvB,IAAI,CAyBN"}
+{"version":3,"file":"dfs.d.ts","sourceRoot":"","sources":["../../../src/graph/dfs.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAChC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,EAChC,OAAO,GAAE,UAAe,GACvB,IAAI,CAyBN;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAChC,OAAO,GAAE,UAAe,GACvB,SAAS,CAQX;AAED,kGAAkG;AAClG,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAChC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,EAChC,OAAO,GAAE,UAAe,GACvB,IAAI,CAsBN;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAqB1E"}

package/dist/src/graph/dfs.js

@@ -22,4 +22,65 @@ export function dfsTraversal(startId, adjacency, visitor, options = {}) {
         }
     }
 }
+/** Collect all reachable nodes from startId via DFS, returning structured result. */
+export function dfsCollect(startId, adjacency, options = {}) {
+    const visited = [];
+    let maxReachedDepth = 0;
+    dfsTraversal(startId, adjacency, (node) => {
+        visited.push(node);
+        if (node.depth > maxReachedDepth)
+            maxReachedDepth = node.depth;
+    }, options);
+    return { visited, maxDepth: maxReachedDepth, nodeCount: visited.length };
+}
+/** BFS level-order traversal — useful when shortest-path distance matters more than DFS order. */
+export function bfsTraversal(startId, adjacency, visitor, options = {}) {
+    if (!adjacency.has(startId))
+        return;
+    const { maxDepth = Infinity } = options;
+    const visited = new Set([startId]);
+    const queue = [{ id: startId, depth: 0 }];
+    while (queue.length > 0) {
+        const { id, depth } = queue.shift();
+        visitor({ id, depth });
+        if (depth < maxDepth) {
+            const neighbors = adjacency.get(id) ?? [];
+            for (let i = 0; i < neighbors.length; i++) {
+                const neighbor = neighbors[i];
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    queue.push({ id: neighbor, depth: depth + 1 });
+                }
+            }
+        }
+    }
+}
+/**
+ * Format a DfsResult as structured text for LLM consumption.
+ * Groups nodes by depth level for easy reading.
+ */
+export function formatDfsResult(result, startId) {
+    if (result.nodeCount === 0)
+        return `No nodes reachable from "${startId}".`;
+    const byDepth = new Map();
+    for (const node of result.visited) {
+        let bucket = byDepth.get(node.depth);
+        if (!bucket) {
+            bucket = [];
+            byDepth.set(node.depth, bucket);
+        }
+        bucket.push(node.id);
+    }
+    const lines = [
+        `DFS from "${startId}": ${result.nodeCount} nodes, max depth ${result.maxDepth}`,
+        '',
+    ];
+    // Iterate in depth order
+    const depths = Array.from(byDepth.keys()).sort((a, b) => a - b);
+    for (const depth of depths) {
+        const ids = byDepth.get(depth);
+        lines.push(`  depth ${depth}: ${ids.join(', ')}`);
+    }
+    return lines.join('\n');
+}
 //# sourceMappingURL=dfs.js.map

package/dist/src/graph/dfs.js.map

@@ -1 +1 @@
-{"version":3,"file":"dfs.js","sourceRoot":"","sources":["../../../src/graph/dfs.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,SAAgC,EAChC,OAAgC,EAChC,UAAsB,EAAE;IAExB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO;IAEpC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,KAAK,GAAyC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAEhF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACnC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAC9B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEhB,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAEvB,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;YACrB,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YAC1C,2FAA2F;YAC3F,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/C,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;gBAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"dfs.js","sourceRoot":"","sources":["../../../src/graph/dfs.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/duplication-stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplication-stats.d.ts","sourceRoot":"","sources":["../../../src/graph/duplication-stats.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,KAAK,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,eAAe,EAAE,EACzB,YAAY,EAAE,MAAM,EAAE,EACtB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAgClB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOtE"}
+{"version":3,"file":"duplication-stats.d.ts","sourceRoot":"","sources":["../../../src/graph/duplication-stats.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,KAAK,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,eAAe,EAAE,EACzB,YAAY,EAAE,MAAM,EAAE,EACtB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAoClB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CActE"}

package/dist/src/graph/duplication-stats.js

@@ -13,8 +13,17 @@ export function computeDuplicationStats(groups, allFilePaths, totalLines, totalT
         }
     }
     const filesWithClones = fileLines.size;
-    const duplicatedLines = [...fileLines.values()].reduce((s, set) => s + set.size, 0);
-    const duplicatedTokens = Math.min(totalTokens, groups.reduce((s, g) => s + g.instances.reduce((t, i) => t + (i.tokenCount ?? 0), 0), 0));
+    // Single-pass line count — avoids spread allocation over all file Sets
+    let duplicatedLines = 0;
+    for (const set of fileLines.values())
+        duplicatedLines += set.size;
+    // Single-pass token sum — avoids nested reduce and intermediate arrays
+    let rawTokens = 0;
+    for (const group of groups) {
+        for (const inst of group.instances)
+            rawTokens += inst.tokenCount ?? 0;
+    }
+    const duplicatedTokens = Math.min(totalTokens, rawTokens);
     return {
         totalFiles: allFilePaths.length,
         filesWithClones,
@@ -28,11 +37,18 @@ export function computeDuplicationStats(groups, allFilePaths, totalLines, totalT
     };
 }
 export function formatDuplicationStats(stats) {
+    const pct = stats.duplicationPct;
+    const grade = pct < 5 ? 'A' : pct < 10 ? 'B' : pct < 20 ? 'C' : pct < 30 ? 'D' : 'F';
+    const tokenPct = stats.totalTokens > 0
+        ? ((stats.duplicatedTokens / stats.totalTokens) * 100).toFixed(1)
+        : '0.0';
     return [
+        `Duplication grade: ${grade} (${pct.toFixed(1)}% duplicated lines)`,
         `Clone groups:      ${stats.cloneGroups}`,
         `Clone instances:   ${stats.cloneInstances}`,
         `Files with clones: ${stats.filesWithClones} / ${stats.totalFiles}`,
-        `Duplicated lines:  ${stats.duplicatedLines} / ${stats.totalLines} (${stats.duplicationPct.toFixed(1)}%)`,
+        `Duplicated lines:  ${stats.duplicatedLines} / ${stats.totalLines} (${pct.toFixed(1)}%)`,
+        `Duplicated tokens: ${stats.duplicatedTokens} / ${stats.totalTokens} (${tokenPct}%)`,
     ].join('\n');
 }
 //# sourceMappingURL=duplication-stats.js.map

package/dist/src/graph/duplication-stats.js.map

@@ -1 +1 @@
-{"version":3,"file":"duplication-stats.js","sourceRoot":"","sources":["../../../src/graph/duplication-stats.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,uBAAuB,CACrC,MAAyB,EACzB,YAAsB,EACtB,UAAkB,EAClB,WAAmB;IAEnB,2DAA2D;IAC3D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IACjD,IAAI,cAAc,GAAG,CAAC,CAAC;IAEvB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YACnC,cAAc,EAAE,CAAC;YACjB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAC3E,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAE,CAAC;YAC1C,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE;gBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,MAAM,eAAe,GAAG,SAAS,CAAC,IAAI,CAAC;IACvC,MAAM,eAAe,GAAG,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAC/B,WAAW,EACX,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CACzF,CAAC;IAEF,OAAO;QACL,UAAU,EAAE,YAAY,CAAC,MAAM;QAC/B,eAAe;QACf,UAAU;QACV,eAAe;QACf,WAAW;QACX,gBAAgB;QAChB,WAAW,EAAE,MAAM,CAAC,MAAM;QAC1B,cAAc;QACd,cAAc,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAuB;IAC5D,OAAO;QACL,sBAAsB,KAAK,CAAC,WAAW,EAAE;QACzC,sBAAsB,KAAK,CAAC,cAAc,EAAE;QAC5C,sBAAsB,KAAK,CAAC,eAAe,MAAM,KAAK,CAAC,UAAU,EAAE;QACnE,sBAAsB,KAAK,CAAC,eAAe,MAAM,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;KAC1G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"duplication-stats.js","sourceRoot":"","sources":["../../../src/graph/duplication-stats.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/edge-filter.d.ts

@@ -20,4 +20,6 @@ export declare function filterEdges(db: MonographDb, options?: EdgeFilterOptions
  * Useful when the caller already has edges and does not need a DB round-trip.
  */
 export declare function filterEdgesInMemory(edges: MonographEdge[], options?: EdgeFilterOptions): MonographEdge[];
+/** Format a list of filtered edges as structured text for LLM consumption. */
+export declare function formatFilteredEdges(edges: MonographEdge[]): string;
 //# sourceMappingURL=edge-filter.d.ts.map

package/dist/src/graph/edge-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edge-filter.d.ts","sourceRoot":"","sources":["../../../src/graph/edge-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;GAGG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,iBAAsB,GAC9B,aAAa,EAAE,CAkDjB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EAAE,EACtB,OAAO,GAAE,iBAAsB,GAC9B,aAAa,EAAE,CAgBjB"}
+{"version":3,"file":"edge-filter.d.ts","sourceRoot":"","sources":["../../../src/graph/edge-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;GAGG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,iBAAsB,GAC9B,aAAa,EAAE,CAkDjB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EAAE,EACtB,OAAO,GAAE,iBAAsB,GAC9B,aAAa,EAAE,CAgBjB;AAID,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,CASlE"}

package/dist/src/graph/edge-filter.js

@@ -44,22 +44,36 @@ export function filterEdges(db, options = {}) {
  * Useful when the caller already has edges and does not need a DB round-trip.
  */
 export function filterEdgesInMemory(edges, options = {}) {
+    // Convert arrays to Sets once before the loop for O(1) membership checks
+    const relationSet = options.relations && options.relations.length > 0
+        ? new Set(options.relations) : null;
+    const confidenceSet = options.confidences && options.confidences.length > 0
+        ? new Set(options.confidences) : null;
+    const minScore = options.minConfidenceScore;
+    const maxScore = options.maxConfidenceScore;
     return edges.filter(e => {
-        if (options.relations && options.relations.length > 0) {
-            if (!options.relations.includes(e.relation))
-                return false;
-        }
-        if (options.confidences && options.confidences.length > 0) {
-            if (!options.confidences.includes(e.confidence))
-                return false;
-        }
-        if (options.minConfidenceScore !== undefined && e.confidenceScore < options.minConfidenceScore) {
+        if (relationSet && !relationSet.has(e.relation))
             return false;
-        }
-        if (options.maxConfidenceScore !== undefined && e.confidenceScore > options.maxConfidenceScore) {
+        if (confidenceSet && !confidenceSet.has(e.confidence))
+            return false;
+        if (minScore !== undefined && e.confidenceScore < minScore)
+            return false;
+        if (maxScore !== undefined && e.confidenceScore > maxScore)
             return false;
-        }
         return true;
     });
 }
+// ── Formatting ─────────────────────────────────────────────────────────────────
+/** Format a list of filtered edges as structured text for LLM consumption. */
+export function formatFilteredEdges(edges) {
+    if (edges.length === 0)
+        return 'No edges match the filter.';
+    const lines = [`Filtered edges (${edges.length}):`];
+    for (const e of edges) {
+        const score = e.confidenceScore !== undefined ? ` [${e.confidenceScore.toFixed(2)}]` : '';
+        const reason = e.reason ? ` — ${e.reason}` : '';
+        lines.push(`  ${e.sourceId} -[${e.relation}/${e.confidence}${score}]-> ${e.targetId}${reason}`);
+    }
+    return lines.join('\n');
+}
 //# sourceMappingURL=edge-filter.js.map

package/dist/src/graph/edge-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"edge-filter.js","sourceRoot":"","sources":["../../../src/graph/edge-filter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"edge-filter.js","sourceRoot":"","sources":["../../../src/graph/edge-filter.ts"],"names":[],"mappings":"AAgBA,kFAAkF;AAElF;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,EAAe,EACf,UAA6B,EAAE;IAE/B,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,MAAM,GAAc,EAAE,CAAC;IAE7B,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtD,UAAU,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxD,UAAU,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAC7C,UAAU,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAC7C,UAAU,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,MAAM,GAAG,GAAG;4BACc,KAAK,EAAE,CAAC;IAElC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CASvC,CAAC;IAEJ,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpB,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,QAAQ,EAAE,CAAC,CAAC,QAAwB;QACpC,UAAU,EAAE,CAAC,CAAC,UAA4B;QAC1C,eAAe,EAAE,CAAC,CAAC,gBAAgB;QACnC,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;KAC9B,CAAC,CAAC,CAAC;AACN,CAAC;AAED,kFAAkF;AAElF;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAsB,EACtB,UAA6B,EAAE;IAE/B,yEAAyE;IACzE,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;QACnE,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtC,MAAM,aAAa,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QACzE,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAE5C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;QACtB,IAAI,WAAW,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9D,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QACpE,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,eAAe,GAAG,QAAQ;YAAE,OAAO,KAAK,CAAC;QACzE,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,eAAe,GAAG,QAAQ;YAAE,OAAO,KAAK,CAAC;QACzE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kFAAkF;AAElF,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,KAAsB;IACxD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,4BAA4B,CAAC;IAC5D,MAAM,KAAK,GAAa,CAAC,mBAAmB,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9D,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,CAAC,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,UAAU,GAAG,KAAK,OAAO,CAAC,CAAC,QAAQ,GAAG,MAAM,EAAE,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/graph/health-score.d.ts

@@ -15,4 +15,12 @@ export interface HealthScoreResult {
 }
 export declare function letterGrade(score: number): 'A' | 'B' | 'C' | 'D' | 'F';
 export declare function computeHealthScore(db: Database.Database): HealthScoreResult;
+/**
+ * Format a HealthScoreResult as structured text for LLM navigation.
+ * Provides a concise grade breakdown that an LLM can parse and act on.
+ *
+ * @param result - HealthScoreResult from computeHealthScore()
+ * @returns structured text suitable for LLM consumption
+ */
+export declare function formatHealthScore(result: HealthScoreResult): string;
 //# sourceMappingURL=health-score.d.ts.map

package/dist/src/graph/health-score.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health-score.d.ts","sourceRoot":"","sources":["../../../src/graph/health-score.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnC,SAAS,EAAE,oBAAoB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAMtE;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,iBAAiB,CA6H3E"}
+{"version":3,"file":"health-score.d.ts","sourceRoot":"","sources":["../../../src/graph/health-score.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnC,SAAS,EAAE,oBAAoB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAMtE;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,iBAAiB,CAmH3E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CA+BnE"}

package/dist/src/graph/health-score.js

@@ -48,23 +48,13 @@ export function computeHealthScore(db) {
     // Each circular pair is counted once; each pair has 2 edges contributing
     const circularEdges = circularRow.c * 2;
     // ── Hotspot files (churnScore > 0.5 in properties) ───────────────────────
-    // Files where properties contain a churnScore > 0.5
-    // We detect presence of churnScore via LIKE and then evaluate in JS
-    const hotspotCandidates = db.prepare("SELECT properties FROM nodes WHERE label = 'File' AND properties LIKE '%churnScore%'").all();
-    let hotspotCount = 0;
-    for (const row of hotspotCandidates) {
-        if (!row.properties)
-            continue;
-        try {
-            const props = JSON.parse(row.properties);
-            const churn = props['churnScore'];
-            if (typeof churn === 'number' && churn > 0.5)
-                hotspotCount++;
-        }
-        catch {
-            // ignore malformed JSON
-        }
-    }
+    // Push the numeric filter into SQLite via json_extract() — avoids O(N) JS JSON.parse loop
+    const hotspotRow = db.prepare(`
+    SELECT COUNT(*) as c FROM nodes
+    WHERE label = 'File'
+      AND CAST(json_extract(properties, '$.churnScore') AS REAL) > 0.5
+  `).get();
+    const hotspotCount = hotspotRow.c;
     // ── Isolated nodes (degree = 0) ───────────────────────────────────────────
     const isolatedRow = db.prepare(`
     SELECT COUNT(*) as c FROM nodes n
@@ -114,4 +104,45 @@ export function computeHealthScore(db) {
     ].join('\n');
     return { score, grade, penalties, summary };
 }
+/**
+ * Format a HealthScoreResult as structured text for LLM navigation.
+ * Provides a concise grade breakdown that an LLM can parse and act on.
+ *
+ * @param result - HealthScoreResult from computeHealthScore()
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatHealthScore(result) {
+    const { score, grade, penalties } = result;
+    const fmt = (val) => val.toFixed(1);
+    const lines = [
+        `health_score: ${score}/100  grade: ${grade}`,
+        '',
+        'penalties:',
+        `  unreachable_files:     ${fmt(penalties.unreachableFilePct)}%  (max -25)`,
+        `  god_nodes:             ${fmt(penalties.godNodePct)}%  (max -20)`,
+        `  circular_edges:        ${fmt(penalties.circularEdgePct)}%  (max -20)`,
+        `  hotspot_files:         ${fmt(penalties.hotspotPct)}%  (max -15)`,
+        `  isolated_nodes:        ${fmt(penalties.isolatedNodePct)}%  (max -10)`,
+        `  cross_community_edges: ${fmt(penalties.crossCommunityEdgePct)}%  (max -10)`,
+        '',
+    ];
+    // Actionable guidance for grades below B
+    if (grade === 'F' || grade === 'D') {
+        lines.push('action_required: yes');
+        if (penalties.circularEdgePct > 5)
+            lines.push('  - break circular import cycles (monograph_context for file dependencies)');
+        if (penalties.godNodePct > 5)
+            lines.push('  - split god nodes (monograph_god_nodes for candidates)');
+        if (penalties.unreachableFilePct > 10)
+            lines.push('  - investigate unreachable files (monograph_detect_changes to surface dead paths)');
+    }
+    else if (grade === 'C') {
+        lines.push('action_suggested: yes');
+        if (penalties.hotspotPct > 10)
+            lines.push('  - reduce churn on hotspot files');
+        if (penalties.isolatedNodePct > 10)
+            lines.push('  - connect or remove isolated nodes');
+    }
+    return lines.join('\n');
+}
 //# sourceMappingURL=health-score.js.map

package/dist/src/graph/health-score.js.map

@@ -1 +1 @@
-{"version":3,"file":"health-score.js","sourceRoot":"","sources":["../../../src/graph/health-score.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"health-score.js","sourceRoot":"","sources":["../../../src/graph/health-score.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/hotspots.d.ts

@@ -34,4 +34,11 @@ export declare function computeHotspots(db: Database.Database, projectDir: strin
     limit?: number;
     minCommits?: number;
 }): HotspotResult[];
+/**
+ * Format hotspot results as structured text with file:line hints for LLM navigation.
+ *
+ * @param hotspots - Results from computeHotspots()
+ * @returns structured text suitable for LLM consumption
+ */
+export declare function formatHotspots(hotspots: HotspotResult[]): string;
 //# sourceMappingURL=hotspots.d.ts.map

package/dist/src/graph/hotspots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hotspots.d.ts","sourceRoot":"","sources":["../../../src/graph/hotspots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,EAAE,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C,qCAAqC;IACrC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,aAAa,EAAE,CA2HjB"}
+{"version":3,"file":"hotspots.d.ts","sourceRoot":"","sources":["../../../src/graph/hotspots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAO3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,EAAE,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C,qCAAqC;IACrC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,aAAa,EAAE,CAkIjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,CA6BhE"}

package/dist/src/graph/hotspots.js

@@ -1,4 +1,8 @@
 import { execSync } from 'child_process';
+// ── Process-scoped TTL cache for expensive git log calls ─────────────────────
+// Key: `${projectDir}:${windowDays}` → { output, ts }
+const GIT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const gitLogCache = new Map();
 /**
  * Compute hotspot scores for all file nodes in the graph.
  * Combines recency-weighted git churn (half-life 90 days) with
@@ -16,14 +20,22 @@ export function computeHotspots(db, projectDir, options = {}) {
     const minCommits = options.minCommits ?? 2;
     const now = Date.now();
     const HALF_LIFE_DAYS = 90;
-    // ── Step 1: Get git log with dates ────────────────────────────────────────
+    // ── Step 1: Get git log with dates (TTL-cached per projectDir+window) ────
     // Format: ISO-date\tfile-path (one per changed file per commit)
     let gitOutput = '';
-    try {
-        gitOutput = execSync(`git log --since="${windowDays} days ago" --name-only --pretty=format:"%ci" -- .`, { cwd: projectDir, maxBuffer: 10 * 1024 * 1024 }).toString();
+    const cacheKey = `${projectDir}:${windowDays}`;
+    const cached = gitLogCache.get(cacheKey);
+    if (cached && now - cached.ts < GIT_CACHE_TTL_MS) {
+        gitOutput = cached.output;
     }
-    catch {
-        return []; // not a git repo or git not available
+    else {
+        try {
+            gitOutput = execSync(`git log --since="${windowDays} days ago" --name-only --pretty=format:"%ci" -- .`, { cwd: projectDir, maxBuffer: 10 * 1024 * 1024 }).toString();
+            gitLogCache.set(cacheKey, { output: gitOutput, ts: now });
+        }
+        catch {
+            return []; // not a git repo or git not available
+        }
     }
     const churnMap = new Map();
     const halfWindowMs = (windowDays / 2) * 24 * 60 * 60 * 1000;
@@ -119,4 +131,37 @@ export function computeHotspots(db, projectDir, options = {}) {
         .sort((a, b) => b.hotspotScore - a.hotspotScore)
         .slice(0, limit);
 }
+/**
+ * Format hotspot results as structured text with file:line hints for LLM navigation.
+ *
+ * @param hotspots - Results from computeHotspots()
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatHotspots(hotspots) {
+    if (hotspots.length === 0) {
+        return 'hotspots: none found (insufficient git history or no matching file nodes)\n';
+    }
+    const trendMark = (t) => {
+        if (t === 'accelerating')
+            return '+';
+        if (t === 'cooling')
+            return '-';
+        return '~';
+    };
+    const lines = [
+        `hotspots: ${hotspots.length} high-risk files (churn x centrality)`,
+        '',
+    ];
+    hotspots.forEach((h, i) => {
+        lines.push(`[${i + 1}] ${h.nodeName}  trend:${trendMark(h.trend)}`);
+        lines.push(`  file: ${h.filePath}:1`);
+        lines.push(`  score: ${h.hotspotScore.toFixed(2)}  churn: ${h.churnScore.toFixed(2)}  centrality: ${h.centralityScore.toFixed(2)}`);
+        lines.push(`  commits: ${h.rawCommitCount}  last: ${h.lastCommitDate ?? 'unknown'}`);
+        lines.push('');
+    });
+    const accelerating = hotspots.filter(h => h.trend === 'accelerating').length;
+    const cooling = hotspots.filter(h => h.trend === 'cooling').length;
+    lines.push(`summary: ${accelerating} accelerating, ${cooling} cooling, ${hotspots.length - accelerating - cooling} stable`);
+    return lines.join('\n');
+}
 //# sourceMappingURL=hotspots.js.map

package/dist/src/graph/hotspots.js.map

@@ -1 +1 @@
-{"version":3,"file":"hotspots.js","sourceRoot":"","sources":["../../../src/graph/hotspots.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hotspots.js","sourceRoot":"","sources":["../../../src/graph/hotspots.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/import-chain.d.ts

@@ -8,7 +8,9 @@ export interface ImportChainOptions {
 /**
  * Trace all import chains (paths) from `sourceId` to `targetId`.
  *
- * Uses BFS/DFS with cycle detection. Returns all simple paths up to `maxDepth`.
+ * Uses frontier-based BFS with lazy edge loading: only fetches outgoing edges
+ * for nodes as they are visited, avoiding loading the full edge table when
+ * the graph is large.  Returns all simple paths up to `maxDepth`.
  *
  * @param db - The MonographDb instance
  * @param sourceId - Starting node id
@@ -17,4 +19,18 @@ export interface ImportChainOptions {
  * @returns Array of paths; each path is an ordered array of node ids from source to target.
  */
 export declare function traceImportChain(db: MonographDb, sourceId: string, targetId: string, options?: ImportChainOptions): string[][];
+/**
+ * Format import-chain paths as structured text.
+ *
+ * Resolves node IDs to human-readable names (name + file_path) for LLM
+ * context injection.  Each path is printed as an arrow chain with file:line
+ * hints where available.
+ *
+ * @param db - The MonographDb instance (used for name resolution)
+ * @param paths - Result of traceImportChain()
+ * @param sourceId - Source node id (for summary line)
+ * @param targetId - Target node id (for summary line)
+ * @returns Structured text string
+ */
+export declare function formatImportChain(db: MonographDb, paths: string[][], sourceId: string, targetId: string): string;
 //# sourceMappingURL=import-chain.d.ts.map

package/dist/src/graph/import-chain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-chain.d.ts","sourceRoot":"","sources":["../../../src/graph/import-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,EAAE,EAAE,CAoDZ"}
+{"version":3,"file":"import-chain.d.ts","sourceRoot":"","sources":["../../../src/graph/import-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,EAAE,EAAE,CAmDZ;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CA6CR"}