@monoes/monograph 1.2.0 → 1.2.1

package/src/mcp-tools/impact.ts

@@ -118,13 +118,32 @@ export function getMonographImpact(
 
   // Reverse BFS to find all callers (depth 0 = start node)
   const visited = reverseBfs(nodeId, db, maxDepth, {});
+  return { node, ...extractCallerResult(db, nodeId, visited) };
+}
+
+// ── Shared helper: fetch nodes by IDs in a single query ───────────────────────
+
+function getNodesByIds(db: Database.Database, ids: string[]): MonographNode[] {
+  if (ids.length === 0) return [];
+  const placeholders = ids.map(() => '?').join(',');
+  const rows = db
+    .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
+    .all(...ids) as Record<string, unknown>[];
+  return rows.map(rowToNode);
+}
+
+// ── Shared helper: turn a visited map into structured caller lists ─────────────
 
-  // Separate direct callers (depth 1) from transitive (depth 2+)
+function extractCallerResult(
+  db: Database.Database,
+  startNodeId: string,
+  visited: Map<string, number>,
+): Omit<MonographImpactResult, 'node'> {
   const directCallerIds: string[] = [];
   const byDepth = new Map<number, string[]>();
 
   for (const [id, depth] of visited.entries()) {
-    if (id === nodeId) continue;
+    if (id === startNodeId) continue;
     if (depth === 1) {
       directCallerIds.push(id);
     } else {
@@ -134,39 +153,24 @@ export function getMonographImpact(
     }
   }
 
-  // Fetch node details for direct callers
-  const getNodesByIds = (ids: string[]): MonographNode[] => {
-    if (ids.length === 0) return [];
-    const placeholders = ids.map(() => '?').join(',');
-    const rows = db
-      .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
-      .all(...ids) as Record<string, unknown>[];
-    return rows.map(rowToNode);
-  };
-
-  const directCallers = getNodesByIds(directCallerIds);
+  const directCallers = getNodesByIds(db, directCallerIds);
 
   const transitiveCallers: Array<{ depth: number; nodes: MonographNode[] }> = [];
   const sortedDepths = Array.from(byDepth.keys()).sort((a, b) => a - b);
   for (const depth of sortedDepths) {
-    const ids = byDepth.get(depth)!;
-    transitiveCallers.push({ depth, nodes: getNodesByIds(ids) });
+    transitiveCallers.push({ depth, nodes: getNodesByIds(db, byDepth.get(depth)!) });
   }
 
-  // Collect unique affected file paths (excluding start node)
   const allAffectedNodes = [...directCallers, ...transitiveCallers.flatMap(t => t.nodes)];
   const affectedFiles = [...new Set(
-    allAffectedNodes
-      .map(n => n.filePath)
-      .filter((p): p is string => p != null),
+    allAffectedNodes.map(n => n.filePath).filter((p): p is string => p != null),
   )];
 
-  // Risk score: log2(totalCallerCount + 1) normalized to [0, 1] (max log2(11) ≈ 3.46, capped at 10, /10)
   const totalCallerCount = visited.size - 1; // exclude start node
   const rawScore = Math.min(Math.log2(totalCallerCount + 1), 10);
   const riskScore = rawScore / 10;
 
-  return { node, directCallers, transitiveCallers, affectedFiles, riskScore, riskLevel: computeRiskLevel(riskScore) };
+  return { directCallers, transitiveCallers, affectedFiles, riskScore, riskLevel: computeRiskLevel(riskScore) };
 }
 
 // ── id-based impact with filtering options ────────────────────────────────────
@@ -188,49 +192,5 @@ export async function monographImpact(
 
   const node = rowToNode(nodeRow);
   const visited = reverseBfs(nodeId, db, maxDepth, options);
-
-  const directCallerIds: string[] = [];
-  const byDepth = new Map<number, string[]>();
-
-  for (const [id, depth] of visited.entries()) {
-    if (id === nodeId) continue;
-    if (depth === 1) {
-      directCallerIds.push(id);
-    } else {
-      const existing = byDepth.get(depth) ?? [];
-      existing.push(id);
-      byDepth.set(depth, existing);
-    }
-  }
-
-  const getNodesByIds = (ids: string[]): MonographNode[] => {
-    if (ids.length === 0) return [];
-    const placeholders = ids.map(() => '?').join(',');
-    const rows = db
-      .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
-      .all(...ids) as Record<string, unknown>[];
-    return rows.map(rowToNode);
-  };
-
-  const directCallers = getNodesByIds(directCallerIds);
-
-  const transitiveCallers: Array<{ depth: number; nodes: MonographNode[] }> = [];
-  const sortedDepths = Array.from(byDepth.keys()).sort((a, b) => a - b);
-  for (const depth of sortedDepths) {
-    const ids = byDepth.get(depth)!;
-    transitiveCallers.push({ depth, nodes: getNodesByIds(ids) });
-  }
-
-  const allAffectedNodes = [...directCallers, ...transitiveCallers.flatMap(t => t.nodes)];
-  const affectedFiles = [...new Set(
-    allAffectedNodes
-      .map(n => n.filePath)
-      .filter((p): p is string => p != null),
-  )];
-
-  const totalCallerCount = visited.size - 1;
-  const rawScore = Math.min(Math.log2(totalCallerCount + 1), 10);
-  const riskScore = rawScore / 10;
-
-  return { node, directCallers, transitiveCallers, affectedFiles, riskScore, riskLevel: computeRiskLevel(riskScore) };
+  return { node, ...extractCallerResult(db, nodeId, visited) };
 }

package/src/mcp-tools/neighbors.ts

@@ -30,6 +30,36 @@ export interface MonographNeighborsResult {
   neighbors: NeighborEntry[];
 }
 
+// ── Shared edge query helper ──────────────────────────────────────────────────
+
+function queryEdges(
+  db: Database.Database,
+  nodeId: string,
+  direction: 'outbound' | 'inbound',
+  relationFilter?: string,
+): NeighborEntry[] {
+  // outbound: source_id = nodeId → join target_id
+  // inbound:  target_id = nodeId → join source_id
+  const [idCol, joinCol] = direction === 'outbound'
+    ? ['source_id', 'target_id']
+    : ['target_id', 'source_id'];
+
+  const sql = relationFilter
+    ? `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.${joinCol} WHERE e.${idCol} = ? AND e.relation = ? LIMIT 50`
+    : `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.${joinCol} WHERE e.${idCol} = ? LIMIT 50`;
+
+  const params = relationFilter ? [nodeId, relationFilter] : [nodeId];
+  const rows = db.prepare(sql).all(...params) as Record<string, unknown>[];
+
+  return rows.map(row => ({
+    node: rowToNode(row),
+    relation: row['relation'] as string,
+    confidence: row['confidence'] as string,
+    confidenceScore: (row['confidence_score'] as number) ?? 1,
+    direction,
+  }));
+}
+
 export function getMonographNeighbors(
   db: Database.Database,
   input: { name: string; relationFilter?: string; includeInbound?: boolean },
@@ -41,45 +71,10 @@ export function getMonographNeighbors(
   if (!nodeRow) return { node: null, neighbors: [] };
 
   const node = rowToNode(nodeRow);
-  const neighbors: NeighborEntry[] = [];
-
-  // Outbound edges
-  const outboundSql = input.relationFilter
-    ? `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.target_id WHERE e.source_id = ? AND e.relation = ? LIMIT 50`
-    : `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.target_id WHERE e.source_id = ? LIMIT 50`;
-
-  const outboundParams = input.relationFilter ? [node.id, input.relationFilter] : [node.id];
-  const outboundRows = db.prepare(outboundSql).all(...outboundParams) as Record<string, unknown>[];
-
-  for (const row of outboundRows) {
-    neighbors.push({
-      node: rowToNode(row),
-      relation: row['relation'] as string,
-      confidence: row['confidence'] as string,
-      confidenceScore: (row['confidence_score'] as number) ?? 1,
-      direction: 'outbound',
-    });
-  }
-
-  // Inbound edges
-  if (input.includeInbound) {
-    const inboundSql = input.relationFilter
-      ? `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.source_id WHERE e.target_id = ? AND e.relation = ? LIMIT 50`
-      : `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.source_id WHERE e.target_id = ? LIMIT 50`;
-
-    const inboundParams = input.relationFilter ? [node.id, input.relationFilter] : [node.id];
-    const inboundRows = db.prepare(inboundSql).all(...inboundParams) as Record<string, unknown>[];
-
-    for (const row of inboundRows) {
-      neighbors.push({
-        node: rowToNode(row),
-        relation: row['relation'] as string,
-        confidence: row['confidence'] as string,
-        confidenceScore: (row['confidence_score'] as number) ?? 1,
-        direction: 'inbound',
-      });
-    }
-  }
+  const neighbors: NeighborEntry[] = [
+    ...queryEdges(db, node.id, 'outbound', input.relationFilter),
+    ...(input.includeInbound ? queryEdges(db, node.id, 'inbound', input.relationFilter) : []),
+  ];
 
   return { node, neighbors };
 }

package/src/mcp-tools/query.ts

@@ -8,6 +8,8 @@ export interface QueryResult {
   label: string;
   name: string;
   filePath?: string;
+  /** Line number where the symbol is defined — enables direct file:line navigation. */
+  startLine?: number | null;
   score: number;
   isProcess: boolean;
 }
@@ -66,6 +68,7 @@ export const monographQueryTool = {
           label: h.label ?? 'Symbol',
           name: h.name ?? h.id,
           filePath: h.filePath ?? undefined,
+          startLine: h.startLine ?? null,
           score: h.score,
           isProcess: h.label === 'Process',
         }));

package/src/mcp-tools/rename.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'fs';
+import { readFileSync, statSync } from 'fs';
 import type Database from 'better-sqlite3';
 import type { MonographNode } from '../types.js';
 
@@ -68,7 +68,10 @@ export function getMonographRename(
 
   // Build changes list by reading source files
   const changes: Array<{ file: string; line: number; before: string; after: string }> = [];
-  const nameRegex = new RegExp(`\\b${escapeRegExp(input.oldName)}\\b`, 'g');
+  // Two separate regexes: testRe has no `g` flag (safe for repeated test()), replaceRe has `g`
+  const testRe = new RegExp(`\\b${escapeRegExp(input.oldName)}\\b`);
+  const replaceRe = new RegExp(`\\b${escapeRegExp(input.oldName)}\\b`, 'g');
+  const MAX_FILE_BYTES = 1_048_576; // 1 MiB guard
 
   // File line cache to avoid re-reading the same file multiple times
   const fileLineCache = new Map<string, string[]>();
@@ -76,6 +79,8 @@ export function getMonographRename(
   const getLines = (filePath: string): string[] => {
     if (fileLineCache.has(filePath)) return fileLineCache.get(filePath)!;
     try {
+      const st = statSync(filePath);
+      if (st.size > MAX_FILE_BYTES) { fileLineCache.set(filePath, []); return []; }
       const content = readFileSync(filePath, 'utf-8');
       const lines = content.split('\n');
       fileLineCache.set(filePath, lines);
@@ -94,13 +99,9 @@ export function getMonographRename(
     if (lineIdx < 0 || lineIdx >= lines.length) continue;
 
     const originalLine = lines[lineIdx];
-    if (!nameRegex.test(originalLine)) {
-      nameRegex.lastIndex = 0;
-      continue;
-    }
-    nameRegex.lastIndex = 0;
+    if (!testRe.test(originalLine)) continue;
 
-    const updatedLine = originalLine.replace(nameRegex, input.newName);
+    const updatedLine = originalLine.replace(replaceRe, input.newName);
     changes.push({
       file: row.file_path,
       line: row.start_line,

package/src/mcp-tools/route-map.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'fs';
+import { readFileSync, statSync } from 'fs';
 import type Database from 'better-sqlite3';
 import { extractMiddlewareChain } from '../pipeline/phases/middleware-extractor.js';
 
@@ -19,39 +19,34 @@ export interface MonographRouteMapResult {
   total: number;
 }
 
+const MAX_FILE_BYTES = 1_048_576; // 1 MiB guard for middleware source reads
+
 // ── Implementation ─────────────────────────────────────────────────────────────
 
 export function getMonographRouteMap(
   db: Database.Database,
   input: { prefix?: string; method?: string; includeMiddleware?: boolean; repoPath?: string },
 ): MonographRouteMapResult {
-  // 1. Query all Route nodes
-  let routeRows = db
-    .prepare("SELECT * FROM nodes WHERE label = 'Route'")
-    .all() as Record<string, unknown>[];
+  // 1. Build SQL-level filters to avoid loading the whole Route table into JS
+  const conditions: string[] = ["label = 'Route'"];
+  const params: unknown[] = [];
 
-  // 2. Apply prefix filter
   if (input.prefix) {
-    const prefix = input.prefix;
-    routeRows = routeRows.filter((row) => {
-      const name = row.name as string;
-      // name is like "GET /api/users" — find the path part
-      const spaceIdx = name.indexOf(' ');
-      const path = spaceIdx >= 0 ? name.slice(spaceIdx + 1) : name;
-      return path.startsWith(prefix);
-    });
+    // Route name format: "METHOD /path" — prefix applies to path portion after first space
+    conditions.push("name LIKE ?");
+    params.push(`% ${input.prefix}%`);
   }
 
-  // 3. Apply method filter
   if (input.method) {
     const methodUpper = input.method.toUpperCase();
-    routeRows = routeRows.filter((row) => {
-      const name = row.name as string;
-      return name.startsWith(methodUpper + ' ') || name.startsWith('ANY ');
-    });
+    conditions.push("(name LIKE ? OR name LIKE ?)");
+    params.push(`${methodUpper} %`, 'ANY %');
   }
 
-  // 4. For each route, find handler via HANDLES_ROUTE edge
+  const sql = `SELECT * FROM nodes WHERE ${conditions.join(' AND ')}`;
+  const routeRows = db.prepare(sql).all(...params) as Record<string, unknown>[];
+
+  // 2. For each route, find handler via HANDLES_ROUTE edge (prepared once)
   const handlerStmt = db.prepare(
     `SELECT n.name, n.file_path, n.start_line FROM nodes n
      JOIN edges e ON n.id = e.target_id
@@ -78,10 +73,13 @@ export function getMonographRouteMap(
     if (input.includeMiddleware && input.repoPath && handlerRow?.name && handlerRow?.file_path) {
       try {
         const absPath = `${input.repoPath}/${handlerRow.file_path}`;
-        const source = readFileSync(absPath, 'utf-8');
-        middlewareChain = extractMiddlewareChain(source, handlerRow.name).middlewareNames;
+        const st = statSync(absPath);
+        if (st.size <= MAX_FILE_BYTES) {
+          const source = readFileSync(absPath, 'utf-8');
+          middlewareChain = extractMiddlewareChain(source, handlerRow.name).middlewareNames;
+        }
       } catch {
-        // File not found or unreadable — leave middlewareChain as []
+        // File not found, unreadable, or too large — leave middlewareChain as []
       }
     }
 

package/src/mcp-tools/shape-check.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'fs';
+import { readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import type Database from 'better-sqlite3';
 import {
@@ -24,8 +24,12 @@ export interface ShapeCheckResult {
 
 // ── Internal helpers ───────────────────────────────────────────────────────────
 
+const MAX_FILE_BYTES = 1_048_576; // 1 MiB guard
+
 function safeReadFile(absPath: string): string {
   try {
+    const st = statSync(absPath);
+    if (st.size > MAX_FILE_BYTES) return '';
     return readFileSync(absPath, 'utf-8');
   } catch {
     return '';
@@ -64,19 +68,19 @@ export function getShapeCheck(
       .prepare("SELECT * FROM nodes WHERE label = 'Route' AND file_path = ? LIMIT 1")
       .get(options.file) as Record<string, unknown> | undefined;
   } else if (options.route) {
-    // Search by name substring (name is like "GET /api/users")
-    // We match against path part of the name to avoid matching the method token
-    const allRoutes = db
-      .prepare("SELECT * FROM nodes WHERE label = 'Route'")
-      .all() as Record<string, unknown>[];
-
-    const searchTerm = options.route.toLowerCase();
-    routeRow = allRoutes.find((row) => {
-      const name = (row.name as string).toLowerCase();
-      const spaceIdx = name.indexOf(' ');
-      const path = spaceIdx >= 0 ? name.slice(spaceIdx + 1) : name;
-      return path.includes(searchTerm);
-    });
+    // Search by name substring (name is like "GET /api/users") using SQL LIKE to avoid full scan
+    // The route path follows the first space, so we match anywhere after it via a LIKE pattern.
+    const likeTerm = `% ${options.route.toLowerCase()}%`;
+    routeRow = db
+      .prepare("SELECT * FROM nodes WHERE label = 'Route' AND lower(name) LIKE ? LIMIT 1")
+      .get(likeTerm) as Record<string, unknown> | undefined;
+
+    // Fallback: match anywhere in the name (e.g. no space prefix)
+    if (!routeRow) {
+      routeRow = db
+        .prepare("SELECT * FROM nodes WHERE label = 'Route' AND lower(name) LIKE ? LIMIT 1")
+        .get(`%${options.route.toLowerCase()}%`) as Record<string, unknown> | undefined;
+    }
   }
 
   if (!routeRow) {

package/src/parsers/loader.ts

@@ -70,14 +70,14 @@ export async function getParser(ext: string): Promise<{ parser: Parser; config:
   }
 
   try {
+    const lang = config.getLanguage();
+    if (!lang) throw new Error('getLanguage() returned undefined');
     const parser = new Parser();
-    parser.setLanguage(config.getLanguage());
+    parser.setLanguage(lang);
     parserCache.set(ext, parser);
     return { parser, config };
-  } catch (err) {
-    // Grammar unavailable at runtime (ABI mismatch, native build failure, etc.).
-    // Log a warning and skip the language gracefully.
-    console.warn(`[monograph] warning: grammar for "${config.name}" (${ext}) could not be loaded: ${err}`);
+  } catch {
+    // Grammar unavailable at runtime (ABI mismatch, native build failure, etc.) — skip silently.
     return null;
   }
 }

package/src/pipeline/cluster-only.ts

@@ -43,18 +43,22 @@ export async function runClusterOnly(db: Database.Database): Promise<ClusterOnly
     }
   }
 
-  // Write community assignments back to DB
+  // Write community assignments back to DB and count in a single pass
   const updateStmt = db.prepare('UPDATE nodes SET community_id = ? WHERE id = ?');
+  const communityIds = new Set<number>();
+  let nodeCount = 0;
   const updateAll = db.transaction(() => {
-    for (const [nodeId, commId] of Object.entries(communities)) {
+    for (const nodeId in communities) {
+      const commId = communities[nodeId];
       updateStmt.run(commId, nodeId);
+      communityIds.add(commId);
+      nodeCount++;
     }
   });
   updateAll();
 
-  const communityIds = new Set(Object.values(communities));
   return {
     communityCount: communityIds.size,
-    nodeCount: Object.keys(communities).length,
+    nodeCount,
   };
 }

package/src/pipeline/orchestrator.ts

@@ -38,11 +38,33 @@ function getCurrentCommitHash(repoPath: string): string | null {
 export interface BuildOptions extends Partial<PipelineOptions> {
   onProgress?: (p: PipelineProgress) => void;
   force?: boolean;
+  /** When true, skip the full rebuild if the index is already fresh (matches HEAD). Default false. */
+  incremental?: boolean;
 }
 
 export async function buildAsync(repoPath: string, options: BuildOptions = {}): Promise<void> {
   const dbPath = resolve(join(repoPath, '.monomind', 'monograph.db'));
   const fullOptions: PipelineOptions = { ...DEFAULT_OPTIONS, ...options };
+
+  // Incremental guard: if the caller requested skip-when-fresh and force is
+  // not set, check staleness before opening the DB for a full write cycle.
+  if (options.incremental && !options.force) {
+    const { existsSync: _existsSync } = await import('fs');
+    if (_existsSync(dbPath)) {
+      const { checkStaleness } = await import('../staleness/git-staleness.js');
+      const tmpDb = openDb(dbPath);
+      try {
+        const report = checkStaleness(tmpDb, resolve(repoPath));
+        if (!report.isStale && report.currentCommit !== null) {
+          options.onProgress?.({ phase: 'skip', message: 'Index is fresh — skipping rebuild' });
+          return; // Already up-to-date
+        }
+      } finally {
+        closeDb(tmpDb);
+      }
+    }
+  }
+
   const db = openDb(dbPath);
 
   try {

package/src/pipeline/phases/boundary.ts

@@ -34,6 +34,28 @@ function globToRegex(glob: string): RegExp {
   return new RegExp('^' + pattern + '$');
 }
 
+/** Zone with its regex precompiled — built once per detectBoundaryViolations call. */
+interface CompiledZone {
+  name: string;
+  re: RegExp;
+}
+
+/** Compile a ZoneConfig[] into CompiledZone[] once to avoid reconstructing RegExps per path. */
+function compileZones(zones: ZoneConfig[]): CompiledZone[] {
+  return zones.map(z => ({ name: z.name, re: globToRegex(z.glob) }));
+}
+
+/**
+ * Classify a file path into a zone name using precompiled regexes.
+ * Returns null if no zone matches.
+ */
+function classifyZoneCompiled(filePath: string, compiled: CompiledZone[]): string | null {
+  for (const z of compiled) {
+    if (z.re.test(filePath)) return z.name;
+  }
+  return null;
+}
+
 /**
  * Load .monographrc.json from repoRoot. Returns empty config if not found or invalid.
  */
@@ -50,6 +72,8 @@ export function loadMonographConfig(repoRoot: string): MonographConfig {
 
 /**
  * Classify a file path into a zone name. Returns null if no zone matches.
+ * Compiles the glob patterns on every call — use classifyZoneCompiled with
+ * precompiled zones for hot paths.
  */
 export function classifyZone(filePath: string, zones: ZoneConfig[]): string | null {
   for (const zone of zones) {
@@ -78,6 +102,9 @@ export function detectBoundaryViolations(
     (config.allowedImports ?? []).map(([from, to]) => `${from}→${to}`),
   );
 
+  // Precompile zone regexes once — avoids re-constructing RegExp objects per file path.
+  const compiledZones = compileZones(zones);
+
   const rows = db.prepare(`
     SELECT e.id, e.relation,
            ns.file_path AS src_path,
@@ -88,11 +115,22 @@ export function detectBoundaryViolations(
     WHERE ns.file_path IS NOT NULL AND nt.file_path IS NOT NULL
   `).all() as { id: string; relation: string; src_path: string; tgt_path: string }[];
 
+  // Cache per-path zone classification to avoid O(rows * zones) repeated regex tests.
+  const pathZoneCache = new Map<string, string | null>();
+  const classifyPath = (p: string): string | null => {
+    let zone = pathZoneCache.get(p);
+    if (zone === undefined) {
+      zone = classifyZoneCompiled(p, compiledZones);
+      pathZoneCache.set(p, zone);
+    }
+    return zone;
+  };
+
   const violations: BoundaryViolation[] = [];
 
   for (const row of rows) {
-    const fromZone = classifyZone(row.src_path, zones);
-    const toZone = classifyZone(row.tgt_path, zones);
+    const fromZone = classifyPath(row.src_path);
+    const toZone = classifyPath(row.tgt_path);
 
     if (fromZone === null || toZone === null) continue;
     if (fromZone === toZone) continue;

package/src/pipeline/phases/communities.ts

@@ -40,6 +40,70 @@ export function computeCohesion(
   return internalCount / maxEdges;
 }
 
+/**
+ * Compute cohesion scores for all communities in a single O(N+E) pass.
+ *
+ * This replaces calling `computeCohesion` inside a loop, which was O(K*(N+E))
+ * because each call re-scanned all memberships (O(N)) and all edges (O(E)).
+ *
+ * @param memberships - nodeId → communityId map from the clustering step
+ * @param edges - all edges used for the graph (IMPORTS + resolved)
+ * @returns Map of communityId → cohesion score ∈ [0, 1]
+ */
+export function computeAllCohesionScores(
+  memberships: Map<string, number>,
+  edges: Array<{ sourceId: string; targetId: string }>,
+): Map<number, number> {
+  // Single pass over memberships: build communityId → Set<nodeId>
+  const memberSets = new Map<number, Set<string>>();
+  for (const [nodeId, commId] of memberships) {
+    let s = memberSets.get(commId);
+    if (!s) {
+      s = new Set();
+      memberSets.set(commId, s);
+    }
+    s.add(nodeId);
+  }
+
+  // Single pass over edges: count unique undirected internal edges per community
+  const internalEdgeCounts = new Map<number, number>();
+  const seenEdgeKeys = new Map<number, Set<string>>();
+
+  for (const e of edges) {
+    const commSrc = memberships.get(e.sourceId);
+    const commTgt = memberships.get(e.targetId);
+    if (commSrc === undefined || commTgt === undefined || commSrc !== commTgt) continue;
+
+    let seen = seenEdgeKeys.get(commSrc);
+    if (!seen) {
+      seen = new Set();
+      seenEdgeKeys.set(commSrc, seen);
+    }
+    const key = e.sourceId < e.targetId
+      ? `${e.sourceId}\0${e.targetId}`
+      : `${e.targetId}\0${e.sourceId}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      internalEdgeCounts.set(commSrc, (internalEdgeCounts.get(commSrc) ?? 0) + 1);
+    }
+  }
+
+  // Compute final scores
+  const scores = new Map<number, number>();
+  for (const [commId, members] of memberSets) {
+    const n = members.size;
+    if (n <= 1) {
+      scores.set(commId, 1);
+      continue;
+    }
+    const maxEdges = (n * (n - 1)) / 2;
+    const internalCount = internalEdgeCounts.get(commId) ?? 0;
+    scores.set(commId, maxEdges > 0 ? internalCount / maxEdges : 1);
+  }
+
+  return scores;
+}
+
 export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
   name: 'communities',
   deps: ['parse', 'cross-file', 'mro'],
@@ -75,11 +139,8 @@ export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
       communityLabels.set(commId, `community-${commId}(${topNode.slice(0, 20)})`);
     }
 
-    const communityIds = new Set([...memberships.values()]);
-    const cohesionScores = new Map<number, number>();
-    for (const cid of communityIds) {
-      cohesionScores.set(cid, computeCohesion(cid, memberships, allUsedEdges));
-    }
+    // Compute all cohesion scores in one O(N+E) pass instead of O(K*(N+E))
+    const cohesionScores = computeAllCohesionScores(memberships, allUsedEdges);
 
     return { memberships, communityLabels, cohesionScores };
   },