@monoes/monograph 1.3.0 → 1.4.1

package/src/analysis/cluster-quality.ts

@@ -98,46 +98,45 @@ export function silhouetteScore(
 }
 
 /**
- * Compute Newman–Girvan modularity Q.
+ * Compute Newman–Girvan modularity Q using the community-level formula:
+ *   Q = Σ_c [e_c / m - (a_c / 2m)²]
+ * where e_c = intra-community edges, a_c = sum of degrees in community c, m = total edges.
  *
- * Q = (1/2m) * Σ_{ij} [A_ij - k_i*k_j/(2m)] * δ(c_i, c_j)
- *
- * where m = total edge count, k_i = degree of node i, A_ij = adjacency.
+ * O(E + N) instead of O(N²).
  * Returns a value in (-0.5, 1].
  */
 export function modularityScore(
   memberships: Map<string, number>,
   edges: Edge[],
 ): number {
+  if (edges.length === 0 || memberships.size === 0) return 0;
+
   const adj = buildAdjacency(edges);
+  const m = edges.length; // directed edges count (each undirected pair counted once in input)
 
-  // Degree map (undirected) — use adj to count undirected edges correctly
-  const degree = new Map<string, number>();
-  for (const [nodeId, neighbors] of adj) {
-    degree.set(nodeId, neighbors.size);
+  // Sum of degrees per community and intra-community edge count
+  const communityDegreeSum = new Map<number, number>();
+  const intraCommunityEdges = new Map<number, number>();
+
+  for (const [nodeId, cid] of memberships) {
+    const deg = adj.get(nodeId)?.size ?? 0;
+    communityDegreeSum.set(cid, (communityDegreeSum.get(cid) ?? 0) + deg);
   }
 
-  // m_undirected: each undirected edge is counted once in adj (both directions added)
-  // so sum of degrees = 2 * m_undirected
-  const totalDegree = [...degree.values()].reduce((s, d) => s + d, 0);
-  const m = totalDegree / 2;
-  if (m === 0) return 0;
+  for (const { sourceId, targetId } of edges) {
+    const cs = memberships.get(sourceId);
+    const ct = memberships.get(targetId);
+    if (cs !== undefined && ct !== undefined && cs === ct) {
+      intraCommunityEdges.set(cs, (intraCommunityEdges.get(cs) ?? 0) + 1);
+    }
+  }
 
   const twoM = 2 * m;
   let Q = 0;
-
-  const nodes = [...memberships.keys()];
-  for (let i = 0; i < nodes.length; i++) {
-    const u = nodes[i]!;
-    for (let j = i + 1; j < nodes.length; j++) {
-      const v = nodes[j]!;
-      if (memberships.get(u) !== memberships.get(v)) continue;
-      const aij = adj.get(u)?.has(v) ? 1 : 0;
-      const ki = degree.get(u) ?? 0;
-      const kj = degree.get(v) ?? 0;
-      Q += aij - (ki * kj) / twoM;
-    }
+  for (const [cid, degSum] of communityDegreeSum) {
+    const ec = intraCommunityEdges.get(cid) ?? 0;
+    Q += ec / m - (degSum / twoM) ** 2;
   }
 
-  return Q / m; // normalise by m (equivalent to 1/(2m) summed both directions)
+  return Q;
 }

package/src/analysis/combined.ts

@@ -29,6 +29,8 @@ export function resolveAnalyses(opts: CombinedOptions): Set<AnalysisKind> {
   return result;
 }
 
+// monolean: stub — resolves which analyses to run but doesn't execute them.
+// Wire up when dead-code/duplication detectors are called from a unified entry point.
 export async function runCombined(
   db: MonographDb,
   opts: CombinedOptions

package/src/analysis/feature-flags.ts

@@ -1,4 +1,4 @@
-import { readFileSync, readdirSync, statSync } from 'fs';
+import { readFileSync, readdirSync, lstatSync } from 'fs';
 import { join, extname } from 'path';
 
 export type FlagKind = 'EnvironmentVariable' | 'SdkCall' | 'ConfigObject';
@@ -170,13 +170,18 @@ export function crossReferenceWithDeadCode(
 }
 
 function walkDir(dir: string, fn: (filePath: string) => void): void {
-  let entries: string[];
-  try { entries = readdirSync(dir); } catch { return; }
-  for (const entry of entries) {
+  let dirents: import('fs').Dirent[];
+  try { dirents = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const dirent of dirents) {
+    const entry = dirent.name;
     if (entry === 'node_modules' || entry === '.git' || entry === 'dist' || entry === 'build') continue;
+    // Never follow symlinks — avoids infinite recursion on a symlink pointing to
+    // an ancestor directory, and avoids indexing a symlinked external tree as if
+    // it were part of the repo. Matches scan.ts's walk().
+    if (dirent.isSymbolicLink()) continue;
     const full = join(dir, entry);
     let st;
-    try { st = statSync(full); } catch { continue; }
+    try { st = lstatSync(full); } catch { continue; }
     if (st.isDirectory()) walkDir(full, fn);
     else if (st.isFile()) fn(full);
   }

package/src/analysis/targets.ts

@@ -44,13 +44,12 @@ export function computeRefactoringTargets(db: MonographDb): RefactoringTargetsRe
       n.id,
       n.file_path,
       n.properties,
-      COUNT(DISTINCT e_in.id) as in_degree,
-      COUNT(DISTINCT e_out.id) as out_degree
+      COALESCE(d_in.cnt, 0) as in_degree,
+      COALESCE(d_out.cnt, 0) as out_degree
     FROM nodes n
-    LEFT JOIN edges e_in ON e_in.target_id = n.id
-    LEFT JOIN edges e_out ON e_out.source_id = n.id
+    LEFT JOIN (SELECT target_id, COUNT(*) AS cnt FROM edges GROUP BY target_id) d_in ON d_in.target_id = n.id
+    LEFT JOIN (SELECT source_id, COUNT(*) AS cnt FROM edges GROUP BY source_id) d_out ON d_out.source_id = n.id
     WHERE n.label = 'File' AND n.file_path IS NOT NULL
-    GROUP BY n.id
   `).all() as FileNodeRow[];
 
   if (rows.length === 0) {

package/src/cache/extraction-cache.ts

@@ -1,14 +1,25 @@
 import { createHash } from 'crypto';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, renameSync, unlinkSync, readdirSync, mkdirSync, existsSync, statSync } from 'fs';
 import { join } from 'path';
 import type { MonographNode, MonographEdge } from '../types.js';
 
+/**
+ * Bump this whenever the parser/extractor output format changes in a way that
+ * would make previously-cached nodes/edges stale or wrong (e.g. a parser bugfix,
+ * a change to what symbols get extracted, a change to node/edge shape). Any
+ * cached entry written under an older version is treated as a miss on read, so
+ * bumping this effectively invalidates the entire on-disk extraction cache.
+ */
+export const EXTRACTION_CACHE_VERSION = 1;
+
 export interface CacheEntry {
   fileHash: string;
   mtimeMs?: number;
   size?: number;
   nodes: MonographNode[];
   edges: MonographEdge[];
+  /** Extraction format version this entry was written under — see EXTRACTION_CACHE_VERSION. */
+  cacheVersion?: number;
 }
 
 export class ExtractionCache {
@@ -32,6 +43,46 @@ export class ExtractionCache {
     return join(this.dir, `${key}.json`);
   }
 
+  /** tmp+rename write — cache corruption is low-stakes but a torn write from a
+   * killed process still shouldn't poison the next read. */
+  private writeAtomic(p: string, data: string): void {
+    const tmp = `${p}.${process.pid}.tmp`;
+    try {
+      writeFileSync(tmp, data);
+      renameSync(tmp, p);
+    } catch {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+    }
+  }
+
+  /**
+   * Delete cache entries whose mtime exceeds maxAgeMs (default 30 days).
+   * Covers files that were deleted/renamed (their cache entry is now orphaned
+   * and would otherwise sit on disk forever) as well as entries simply not
+   * touched in a long time. Single readdir + stat pass over the cache dir.
+   * Returns the number of entries removed.
+   */
+  prune(maxAgeMs = 30 * 24 * 60 * 60 * 1000): number {
+    let removed = 0;
+    let entries: string[];
+    try {
+      entries = readdirSync(this.dir).filter((f) => f.endsWith('.json') && !f.startsWith('._'));
+    } catch {
+      return 0;
+    }
+    const cutoff = Date.now() - maxAgeMs;
+    for (const f of entries) {
+      const p = join(this.dir, f);
+      try {
+        if (statSync(p).mtimeMs < cutoff) {
+          unlinkSync(p);
+          removed++;
+        }
+      } catch { /* ignore */ }
+    }
+    return removed;
+  }
+
   /**
    * Fast-path: check mtime+size before falling back to content hash.
    * Returns cached entry if file hasn't changed, null on miss.
@@ -41,6 +92,7 @@ export class ExtractionCache {
     if (!existsSync(p)) return null;
     try {
       const entry: CacheEntry = JSON.parse(readFileSync(p, 'utf-8'));
+      if (entry.cacheVersion !== EXTRACTION_CACHE_VERSION) return null;
       const st = statSync(filePath);
       if (entry.mtimeMs === st.mtimeMs && entry.size === st.size) return entry;
       // mtime/size differ or missing — recheck content hash
@@ -49,7 +101,7 @@ export class ExtractionCache {
       // Hash matches — update entry with current mtime+size for next run
       entry.mtimeMs = st.mtimeMs;
       entry.size = st.size;
-      try { writeFileSync(p, JSON.stringify(entry)); } catch { /* non-fatal */ }
+      try { this.writeAtomic(p, JSON.stringify(entry)); } catch { /* non-fatal */ }
       return entry;
     } catch { return null; }
   }
@@ -59,6 +111,7 @@ export class ExtractionCache {
     if (!existsSync(p)) return null;
     try {
       const entry: CacheEntry = JSON.parse(readFileSync(p, 'utf-8'));
+      if (entry.cacheVersion !== EXTRACTION_CACHE_VERSION) return null;
       return entry.fileHash === fileHash ? entry : null;
     } catch { return null; }
   }
@@ -67,21 +120,21 @@ export class ExtractionCache {
     let mtimeMs: number | undefined;
     let size: number | undefined;
     try { const st = statSync(filePath); mtimeMs = st.mtimeMs; size = st.size; } catch { /* ignore */ }
-    const entry: CacheEntry = { fileHash, mtimeMs, size, nodes, edges };
-    writeFileSync(this.entryPath(filePath), JSON.stringify(entry));
+    const entry: CacheEntry = { fileHash, mtimeMs, size, nodes, edges, cacheVersion: EXTRACTION_CACHE_VERSION };
+    this.writeAtomic(this.entryPath(filePath), JSON.stringify(entry));
   }
 
   setDeferred(filePath: string, fileHash: string, nodes: MonographNode[], edges: MonographEdge[]): void {
     let mtimeMs: number | undefined;
     let size: number | undefined;
     try { const st = statSync(filePath); mtimeMs = st.mtimeMs; size = st.size; } catch { /* ignore */ }
-    const entry: CacheEntry = { fileHash, mtimeMs, size, nodes, edges };
+    const entry: CacheEntry = { fileHash, mtimeMs, size, nodes, edges, cacheVersion: EXTRACTION_CACHE_VERSION };
     this.pending.push({ path: this.entryPath(filePath), data: JSON.stringify(entry) });
   }
 
   flush(): void {
     for (const { path, data } of this.pending) {
-      try { writeFileSync(path, data); } catch { /* non-fatal */ }
+      try { this.writeAtomic(path, data); } catch { /* non-fatal */ }
     }
     this.pending = [];
   }

package/src/cli/doctor.ts

@@ -51,12 +51,9 @@ function checkDbExists(dbPath: string): DoctorCheck {
   };
 }
 
-function checkDbReadable(dbPath: string): DoctorCheck {
+async function checkDbReadable(dbPath: string): Promise<DoctorCheck> {
   try {
-    // Dynamic require keeps this check lazy so missing better-sqlite3 doesn't
-    // crash the entire doctor invocation.
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const Database = require('better-sqlite3') as typeof import('better-sqlite3');
+    const Database = (await import('better-sqlite3')).default;
     const db = new Database(dbPath, { readonly: true });
     db.prepare('SELECT 1').get();
     db.close();
@@ -67,10 +64,9 @@ function checkDbReadable(dbPath: string): DoctorCheck {
   }
 }
 
-function checkNodeCount(dbPath: string): DoctorCheck {
+async function checkNodeCount(dbPath: string): Promise<DoctorCheck> {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const Database = require('better-sqlite3') as typeof import('better-sqlite3');
+    const Database = (await import('better-sqlite3')).default;
     const db = new Database(dbPath, { readonly: true });
     const row = db.prepare('SELECT COUNT(*) AS n FROM nodes').get() as { n: number } | undefined;
     db.close();
@@ -159,8 +155,8 @@ export async function runDoctor(repoPath: string): Promise<DoctorResult> {
 
   // 3. DB readable (only if DB exists)
   if (dbExistsCheck.status !== 'error') {
-    checks.push(checkDbReadable(dbPath));
-    checks.push(checkNodeCount(dbPath));
+    checks.push(await checkDbReadable(dbPath));
+    checks.push(await checkNodeCount(dbPath));
   } else {
     checks.push({
       name: 'SQLite DB readable',

package/src/export/analysis-json.ts

@@ -82,6 +82,6 @@ export function buildDuplicationResultsEnvelope(
 
 export function stripRootPrefix(obj: unknown, rootPrefix: string): unknown {
   const json = JSON.stringify(obj);
-  const escaped = rootPrefix.replace(/[/\\]/g, s => `\\${s}`);
+  const escaped = rootPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   return JSON.parse(json.replace(new RegExp(escaped, 'g'), ''));
 }

package/src/export/sarif.ts

@@ -1,6 +1,15 @@
 import type Database from 'better-sqlite3';
 import { createHash } from 'crypto';
-import { relative } from 'path';
+import { readFileSync } from 'fs';
+import { relative, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8')).version ?? '0.0.0';
+  } catch { return '0.0.0'; }
+})();
 
 export interface SarifRule {
   id: string;
@@ -231,6 +240,6 @@ export function exportHealthSarif(findings: SarifHealthFinding[], root?: string)
   return {
     $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
     version: '2.1.0',
-    runs: [{ tool: { driver: { name: 'monograph-health', version: '1.0.0', rules } }, results }],
+    runs: [{ tool: { driver: { name: 'monograph-health', version: PKG_VERSION, rules } }, results }],
   };
 }

package/src/graph/baseline.ts

@@ -126,15 +126,19 @@ export function extractFindingsFromDb(
 
   // God nodes (degree > 50)
   const gods = db.prepare(`
-    SELECT n.id, n.name, n.file_path, n.start_line,
-           COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) as degree
+    SELECT n.id, n.name, n.file_path, n.start_line, d.deg as degree
     FROM nodes n
-    LEFT JOIN edges e1 ON e1.source_id = n.id
-    LEFT JOIN edges e2 ON e2.target_id = n.id
-    GROUP BY n.id
-    HAVING degree > 50
-    ORDER BY degree DESC
-    LIMIT 100
+    JOIN (
+      SELECT node_id, SUM(cnt) AS deg FROM (
+        SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
+        UNION ALL
+        SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
+      ) GROUP BY node_id
+      HAVING deg > 50
+      ORDER BY deg DESC
+      LIMIT 100
+    ) d ON d.node_id = n.id
+    ORDER BY d.deg DESC
   `).all() as { id: string; name: string; file_path: string | null; start_line: number | null; degree: number }[];
 
   for (const n of gods) {
@@ -173,20 +177,25 @@ export function extractFindingsFromDb(
     });
   }
 
-  // Bridge nodes: nodes whose edges span more than one community_id
-  // Use JOIN+GROUP BY instead of correlated subqueries to avoid N*2 subquery executions
+  // Bridge nodes: nodes whose edges span 2+ distinct foreign communities.
+  // Pre-aggregate cross-community counts per direction to avoid 4-way cross product.
   const bridges = db.prepare(`
-    SELECT n.id, n.name, n.file_path, n.start_line,
-           COUNT(DISTINCT CASE WHEN e_out.source_id = n.id AND n_tgt.community_id != n.community_id THEN n_tgt.community_id END) +
-           COUNT(DISTINCT CASE WHEN e_in.target_id = n.id AND n_src.community_id != n.community_id THEN n_src.community_id END) AS cross_communities
+    SELECT n.id, n.name, n.file_path, n.start_line
     FROM nodes n
-    LEFT JOIN edges e_out ON e_out.source_id = n.id
-    LEFT JOIN nodes n_tgt ON n_tgt.id = e_out.target_id AND n_tgt.community_id IS NOT NULL
-    LEFT JOIN edges e_in ON e_in.target_id = n.id
-    LEFT JOIN nodes n_src ON n_src.id = e_in.source_id AND n_src.community_id IS NOT NULL
-    WHERE n.community_id IS NOT NULL
-    GROUP BY n.id
-    HAVING cross_communities >= 2
+    JOIN (
+      SELECT node_id, COUNT(DISTINCT foreign_community) AS cross_cnt FROM (
+        SELECT e.source_id AS node_id, n2.community_id AS foreign_community
+        FROM edges e
+        JOIN nodes n1 ON n1.id = e.source_id AND n1.community_id IS NOT NULL
+        JOIN nodes n2 ON n2.id = e.target_id AND n2.community_id IS NOT NULL AND n2.community_id != n1.community_id
+        UNION ALL
+        SELECT e.target_id AS node_id, n1.community_id AS foreign_community
+        FROM edges e
+        JOIN nodes n1 ON n1.id = e.source_id AND n1.community_id IS NOT NULL
+        JOIN nodes n2 ON n2.id = e.target_id AND n2.community_id IS NOT NULL AND n1.community_id != n2.community_id
+      ) GROUP BY node_id
+      HAVING cross_cnt >= 2
+    ) b ON b.node_id = n.id
     LIMIT 100
   `).all() as { id: string; name: string; file_path: string | null; start_line: number | null }[];
 

package/src/graph/dead-code.ts

@@ -11,8 +11,13 @@ import type { MonographDb } from '../storage/db.js';
  * - Only exported — private locals are internal by design
  * - Skips entry-point, test, dist, and node_modules paths
  * - Requires zero inbound CALLS, IMPORTS, REFERENCES, and RE_EXPORTS edges
- * - No same-name node in another file (catches import bindings)
- * - Not re-exported through any index.ts barrel file
+ * - Not re-exported through any index.ts barrel file, via an actual RE_EXPORTS
+ *   edge from that barrel's File node (not merely sharing a name with something
+ *   an index.ts happens to also define)
+ *
+ * Known gap: files consumed only via a dynamic `import()` call won't have a static
+ * edge in the graph, so they can still surface as false positives here — this
+ * detector only tracks statically-resolved edges.
  */
 export function detectDeadCode(db: MonographDb): string[] {
   return detectDeadCodeNodes(db).map(n => n.id);
@@ -58,21 +63,19 @@ export function detectDeadCodeNodes(db: MonographDb): DeadCodeNode[] {
            WHERE e.target_id = n.id
              AND e.relation IN ('CALLS', 'IMPORTS', 'REFERENCES', 'RE_EXPORTS')
          )
-         -- no same-name node in another file (import bindings, .cjs callers, etc.)
-         AND NOT EXISTS (
-           SELECT 1 FROM nodes o
-           WHERE o.name = n.name AND o.file_path != n.file_path
-             AND o.file_path IS NOT NULL
-             AND o.file_path NOT LIKE '%/dist/%'
-             AND o.file_path NOT LIKE '%node_modules%'
-         )
-         -- not re-exported through a barrel (index.ts/index.js)
+         -- not re-exported through a barrel (index.ts/index.js) — checked via an
+         -- ACTUAL RE_EXPORTS edge from the barrel's File node to this candidate's
+         -- File node, not a same-NAME coincidence with an unrelated symbol that
+         -- happens to also live in some index.ts elsewhere in the repo.
          AND NOT EXISTS (
-           SELECT 1 FROM nodes b
-           WHERE b.name = n.name
-             AND b.file_path LIKE '%/index.%'
-             AND b.file_path NOT LIKE '%/dist/%'
-             AND b.file_path NOT LIKE '%node_modules%'
+           SELECT 1 FROM edges e
+           JOIN nodes fn ON fn.id = e.target_id AND fn.label = 'File'
+           JOIN nodes bn ON bn.id = e.source_id AND bn.label = 'File'
+           WHERE e.relation = 'RE_EXPORTS'
+             AND fn.file_path = n.file_path
+             AND bn.file_path LIKE '%/index.%'
+             AND bn.file_path NOT LIKE '%/dist/%'
+             AND bn.file_path NOT LIKE '%node_modules%'
          )
        ORDER BY n.file_path, n.start_line`,
     )

package/src/graph/health-score.ts

@@ -33,7 +33,7 @@ export function computeHealthScore(db: Database.Database): HealthScoreResult {
 
   // ── Unreachable file nodes ────────────────────────────────────────────────
   const unreachableRow = db.prepare(
-    "SELECT COUNT(*) as c FROM nodes WHERE label = 'File' AND properties LIKE '%\"unreachable\"%'"
+    "SELECT COUNT(*) as c FROM nodes WHERE label = 'File' AND json_extract(properties, '$.unreachable') = 1"
   ).get() as { c: number };
   const unreachableFiles = unreachableRow.c;
 
@@ -42,23 +42,20 @@ export function computeHealthScore(db: Database.Database): HealthScoreResult {
   const totalNodes = totalNodesRow.c;
 
   // ── p95 degree (god nodes) ────────────────────────────────────────────────
-  const degreesRows = db.prepare(`
-    SELECT source_id as node_id, COUNT(*) as deg FROM edges GROUP BY source_id
-    UNION ALL
-    SELECT target_id as node_id, COUNT(*) as deg FROM edges GROUP BY target_id
-  `).all() as { node_id: string; deg: number }[];
-
-  // Sum degrees per node
-  const degMap = new Map<string, number>();
-  for (const row of degreesRows) {
-    degMap.set(row.node_id, (degMap.get(row.node_id) ?? 0) + row.deg);
-  }
-  const degrees = [...degMap.values()].sort((a, b) => a - b);
-  const p95Index = Math.floor(degrees.length * 0.95);
-  const p95Degree = degrees[p95Index] ?? 0;
+  // Compute per-node total degree (in + out) entirely in SQL
+  const degreeRows = db.prepare(`
+    SELECT node_id, SUM(cnt) AS degree FROM (
+      SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
+      UNION ALL
+      SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
+    ) GROUP BY node_id ORDER BY degree ASC
+  `).all() as { node_id: string; degree: number }[];
+
+  const p95Index = Math.floor(degreeRows.length * 0.95);
+  const p95Degree = degreeRows[p95Index]?.degree ?? 0;
 
   const godNodeCount = p95Degree > 0
-    ? [...degMap.values()].filter(d => d > p95Degree).length
+    ? degreeRows.filter(r => r.degree > p95Degree).length
     : 0;
 
   // ── Circular edges (bidirectional import pairs) ───────────────────────────

package/src/graph/hotspots.ts

@@ -123,12 +123,16 @@ export function computeHotspots(
   // ── Step 3: Get file nodes + centrality from DB ───────────────────────────
   const fileNodes = db.prepare(`
     SELECT n.id, n.name, n.file_path, n.label, n.community_id,
-           COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) as degree
+           COALESCE(d.deg, 0) as degree
     FROM nodes n
-    LEFT JOIN edges e1 ON e1.source_id = n.id
-    LEFT JOIN edges e2 ON e2.target_id = n.id
+    LEFT JOIN (
+      SELECT node_id, SUM(cnt) AS deg FROM (
+        SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
+        UNION ALL
+        SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
+      ) GROUP BY node_id
+    ) d ON d.node_id = n.id
     WHERE n.label = 'File' AND n.file_path IS NOT NULL
-    GROUP BY n.id
   `).all() as { id: string; name: string; file_path: string; label: string; community_id: number | null; degree: number }[];
 
   // ── Step 4: Join churn + centrality ──────────────────────────────────────

package/src/graph/pagerank.ts

@@ -24,6 +24,10 @@ function getStmts(db: MonographDb): StmtCache {
   const key = (db as unknown as { name: string }).name ?? '__default__';
   let cache = _stmtCache.get(key);
   if (!cache) {
+    if (_stmtCache.size >= MAX_STMT_CACHE) {
+      const oldest = _stmtCache.keys().next().value!;
+      _stmtCache.delete(oldest);
+    }
     cache = {
       selectNodes: db.prepare('SELECT id FROM nodes'),
       selectEdges: db.prepare('SELECT source_id, target_id FROM edges'),
@@ -38,6 +42,8 @@ function getStmts(db: MonographDb): StmtCache {
 // changed. Keyed by (dbName, nodeCount, edgeCount) with a 5-second TTL.
 // ---------------------------------------------------------------------------
 const PAGERANK_CACHE_TTL_MS = 5_000;
+const MAX_RESULT_CACHE = 50;
+const MAX_STMT_CACHE = 20;
 
 interface PageRankCacheEntry {
   result: Map<string, number>;
@@ -149,7 +155,10 @@ export function pageRank(db: MonographDb, options: PageRankOptions = {}): Map<st
     result.set(nodes[i], scores[i]);
   }
 
-  // Store in result cache
+  if (_resultCache.size >= MAX_RESULT_CACHE) {
+    const oldest = _resultCache.keys().next().value!;
+    _resultCache.delete(oldest);
+  }
   _resultCache.set(cacheKey, { result, expiresAt: now + PAGERANK_CACHE_TTL_MS });
 
   return result;

package/src/graph/statistics.ts

@@ -77,21 +77,24 @@ export function clusteringCoefficient(db: MonographDb): number {
   let totalCoeff = 0;
   let countWithNeighbors = 0;
 
+  // Cap per-node neighbor scan to avoid O(k²) explosion on hub nodes
+  const MAX_K = 200;
   for (const [node, nbrs] of neighbors) {
     const k = nbrs.size;
     if (k < 2) continue;
 
     let triangles = 0;
-    const nbList = [...nbrs];
-    for (let i = 0; i < nbList.length; i++) {
-      for (let j = i + 1; j < nbList.length; j++) {
+    const nbList = k <= MAX_K ? [...nbrs] : [...nbrs].slice(0, MAX_K);
+    const effectiveK = nbList.length;
+    for (let i = 0; i < effectiveK; i++) {
+      for (let j = i + 1; j < effectiveK; j++) {
         if (neighbors.get(nbList[i])?.has(nbList[j])) {
           triangles++;
         }
       }
     }
 
-    const possible = (k * (k - 1)) / 2;
+    const possible = (effectiveK * (effectiveK - 1)) / 2;
     totalCoeff += triangles / possible;
     countWithNeighbors++;
   }
@@ -112,19 +115,28 @@ export interface PathStats {
 }
 
 /**
- * Compute both average path length and graph diameter in a single BFS pass.
- * Unreachable pairs are excluded from averagePathLength.
+ * Compute both average path length and graph diameter via BFS.
+ * For graphs > 500 nodes, uses deterministic sampling (every Nth node)
+ * to keep runtime practical — O(sample * E) instead of O(N * E).
  */
 export function pathStats(db: MonographDb): PathStats {
   const graph = getGraph(db);
   const nodes = graph.nodes();
   if (nodes.length < 2) return { averagePathLength: 0, diameter: 0 };
 
+  // Sample sources for large graphs — stride ensures even coverage
+  const MAX_SOURCES = 500;
+  const stride = nodes.length <= MAX_SOURCES ? 1 : Math.ceil(nodes.length / MAX_SOURCES);
+  const sources: string[] = [];
+  for (let i = 0; i < nodes.length && sources.length < MAX_SOURCES; i += stride) {
+    sources.push(nodes[i]);
+  }
+
   let totalLength = 0;
   let reachablePairs = 0;
   let maxDist = 0;
 
-  for (const source of nodes) {
+  for (const source of sources) {
     bfsFromNode(graph, source, (node, _attr, depth) => {
       if (node !== source && depth > 0) {
         totalLength += depth;

package/src/graph/stats.ts

@@ -143,10 +143,11 @@ export function computeGraphStats(db: Database.Database): GraphStatsSummary {
 /** Format a GraphStatsSummary as structured text for LLM consumption. */
 export function formatGraphStats(s: GraphStatsSummary): string {
   const cp = s.couplingProfile;
+  const totalEntities = cp.fanInProfile.low + cp.fanInProfile.medium + cp.fanInProfile.high + cp.fanInProfile.critical;
   const lines: string[] = [
     `Graph Stats`,
     `  Nodes: ${s.nodeCount}  Edges: ${s.edgeCount}  Communities: ${s.communityCount}  Files: ${s.fileCount}`,
-    `Coupling Profile (${cp.totalFiles} files)`,
+    `Coupling Profile (${totalEntities} entities, ${cp.totalFiles} files)`,
     `  Fan-in p50/p75/p90/p95: ${cp.p50FanIn}/${cp.p75FanIn}/${cp.p90FanIn}/${cp.p95FanIn}`,
     `  High-coupling (>p95): ${cp.couplingHighPct}%`,
     `Fan-in Risk: low=${cp.fanInProfile.low}(${cp.fanInProfile.lowPct}%) med=${cp.fanInProfile.medium}(${cp.fanInProfile.mediumPct}%) high=${cp.fanInProfile.high}(${cp.fanInProfile.highPct}%) crit=${cp.fanInProfile.critical}(${cp.fanInProfile.criticalPct}%)`,