@monoes/monograph 1.2.0 → 1.2.1

package/src/analysis/project-state.ts

@@ -1,5 +1,3 @@
-import * as path from 'node:path';
-
 export interface ProjectFile {
   fileId: number;
   path: string;
@@ -16,16 +14,25 @@ export interface WorkspaceEntry {
 export interface ProjectState {
   files: ProjectFile[];
   pathToId: Map<string, number>;
+  /** O(1) lookup by numeric fileId */
+  idToFile: Map<number, ProjectFile>;
   workspaces: WorkspaceEntry[];
 }
 
 export function makeProjectState(files: ProjectFile[], workspaces: WorkspaceEntry[]): ProjectState {
-  const pathToId = new Map(files.map(f => [f.path, f.fileId]));
-  return { files, pathToId, workspaces };
+  // Build both lookup maps in a single pass to avoid intermediate arrays
+  const pathToId = new Map<string, number>();
+  const idToFile = new Map<number, ProjectFile>();
+  for (const f of files) {
+    pathToId.set(f.path, f.fileId);
+    idToFile.set(f.fileId, f);
+  }
+  return { files, pathToId, idToFile, workspaces };
 }
 
 export function fileById(state: ProjectState, fileId: number): ProjectFile | undefined {
-  return state.files.find(f => f.fileId === fileId);
+  // O(1) lookup via idToFile map instead of O(N) linear scan
+  return state.idToFile.get(fileId);
 }
 
 export function idForPath(state: ProjectState, filePath: string): number | undefined {
@@ -62,10 +69,13 @@ export class PackageResolver {
   private entries: Array<{ root: string; name: string }>;
 
   constructor(workspaces: WorkspaceEntry[]) {
-    this.entries = workspaces
-      .filter(w => w.name)
-      .map(w => ({ root: w.root, name: w.name! }))
-      .sort((a, b) => b.root.length - a.root.length);
+    // Combine filter + map into a single for-of loop to avoid 2 intermediate arrays
+    const named: Array<{ root: string; name: string }> = [];
+    for (const w of workspaces) {
+      if (w.name) named.push({ root: w.root, name: w.name });
+    }
+    named.sort((a, b) => b.root.length - a.root.length);
+    this.entries = named;
   }
 
   resolvePackage(filePath: string): string | undefined {

package/src/analysis/suppressions.ts

@@ -15,6 +15,9 @@ export const NON_CORE_KINDS: SuppressionKind[] = [
   'code-duplication',
 ];
 
+// Set for O(1) membership check in findStale hot path
+const NON_CORE_KINDS_SET = new Set<SuppressionKind>(NON_CORE_KINDS);
+
 export interface Suppression {
   path: string;
   line: number;
@@ -58,7 +61,7 @@ export function findStale(ctx: SuppressionContext): StaleSuppression[] {
     .filter((s) => {
       const key = suppressionKey(s);
       const isConsumed = ctx.consumed.has(key);
-      const isNonCore = NON_CORE_KINDS.includes(s.kind);
+      const isNonCore = NON_CORE_KINDS_SET.has(s.kind);
       // Keep (return as stale) if NOT consumed AND NOT a non-core kind
       return !isConsumed && !isNonCore;
     })

package/src/analysis/trace.ts

@@ -49,7 +49,7 @@ export interface CloneTrace {
   groupId?: number;
 }
 
-interface GraphNode {
+export interface GraphNode {
   id: string;
   filePath?: string;
   name: string;
@@ -68,12 +68,27 @@ interface Graph {
   edges: GraphEdge[];
 }
 
-export function traceExport(graph: Graph, file: string, exportName: string): ExportTrace {
+/** Build an O(1) id→node index. Pass to the trace functions when calling multiple times on the same graph. */
+export function buildNodeIndex(graph: Graph): Map<string, GraphNode> {
+  const index = new Map<string, GraphNode>();
+  for (const n of graph.nodes) index.set(n.id, n);
+  return index;
+}
+
+export function traceExport(
+  graph: Graph,
+  file: string,
+  exportName: string,
+  nodeIndex?: Map<string, GraphNode>,
+): ExportTrace {
+  // Build index once if not supplied — O(N) amortised when caller reuses it
+  const idx = nodeIndex ?? buildNodeIndex(graph);
+
   // Find nodes in the target file matching exportName
-  const targetNodes = graph.nodes.filter(
-    (n) => n.filePath === file && n.name === exportName,
-  );
-  const targetIds = new Set(targetNodes.map((n) => n.id));
+  const targetIds = new Set<string>();
+  for (const n of graph.nodes) {
+    if (n.filePath === file && n.name === exportName) targetIds.add(n.id);
+  }
 
   // Find CALLS or IMPORTS edges pointing to these nodes from other files
   const directReferences: ReferenceLocation[] = [];
@@ -82,7 +97,7 @@ export function traceExport(graph: Graph, file: string, exportName: string): Exp
   for (const edge of graph.edges) {
     if (!targetIds.has(edge.targetId)) continue;
 
-    const sourceNode = graph.nodes.find((n) => n.id === edge.sourceId);
+    const sourceNode = idx.get(edge.sourceId);
     if (!sourceNode) continue;
 
     // Skip self-references (same file)
@@ -127,66 +142,70 @@ export function traceExport(graph: Graph, file: string, exportName: string): Exp
   };
 }
 
-export function traceFile(graph: Graph, file: string): FileTrace {
+export function traceFile(
+  graph: Graph,
+  file: string,
+  nodeIndex?: Map<string, GraphNode>,
+): FileTrace {
+  // Build index once if not supplied
+  const idx = nodeIndex ?? buildNodeIndex(graph);
+
   // Find all nodes in this file
   const fileNodes = graph.nodes.filter((n) => n.filePath === file);
   const fileNodeIds = new Set(fileNodes.map((n) => n.id));
 
-  // Build exports list
-  const exports = fileNodes
-    .filter((n) => n.isExported)
-    .map((n) => {
-      // Check if any external node references this node
-      const hasReferences = graph.edges.some(
-        (e) =>
-          e.targetId === n.id &&
-          (e.relation === 'CALLS' || e.relation === 'IMPORTS') &&
-          !fileNodeIds.has(e.sourceId),
-      );
-      return {
-        name: n.name,
-        isUsed: hasReferences,
-        line: n.startLine ?? 0,
-      };
-    });
-
-  // Find files this file imports from (outgoing IMPORTS edges from file nodes)
+  // Pre-compute which target node ids have external references in one edge pass
+  // to avoid O(exported_nodes * edges) in the map below.
+  const externallyReferenced = new Set<string>();
   const importsFromSet = new Set<string>();
+  const importedBySet = new Set<string>();
+  const reExports: Array<{ name: string; fromFile: string }> = [];
+
   for (const edge of graph.edges) {
-    if (!fileNodeIds.has(edge.sourceId)) continue;
-    if (edge.relation !== 'IMPORTS') continue;
-    const targetNode = graph.nodes.find((n) => n.id === edge.targetId);
-    if (targetNode?.filePath && targetNode.filePath !== file) {
-      importsFromSet.add(targetNode.filePath);
+    const srcInFile = fileNodeIds.has(edge.sourceId);
+    const tgtInFile = fileNodeIds.has(edge.targetId);
+
+    if (edge.relation === 'IMPORTS') {
+      if (srcInFile) {
+        const targetNode = idx.get(edge.targetId);
+        if (targetNode?.filePath && targetNode.filePath !== file) {
+          importsFromSet.add(targetNode.filePath);
+        }
+      }
+      if (tgtInFile) {
+        const sourceNode = idx.get(edge.sourceId);
+        if (sourceNode?.filePath && sourceNode.filePath !== file) {
+          importedBySet.add(sourceNode.filePath);
+        }
+      }
+      // External IMPORTS into a file node → that node is externally referenced
+      if (tgtInFile && !srcInFile) {
+        externallyReferenced.add(edge.targetId);
+      }
     }
-  }
 
-  // Find files that import this file (incoming IMPORTS edges to file nodes)
-  const importedBySet = new Set<string>();
-  for (const edge of graph.edges) {
-    if (!fileNodeIds.has(edge.targetId)) continue;
-    if (edge.relation !== 'IMPORTS') continue;
-    const sourceNode = graph.nodes.find((n) => n.id === edge.sourceId);
-    if (sourceNode?.filePath && sourceNode.filePath !== file) {
-      importedBySet.add(sourceNode.filePath);
+    if (edge.relation === 'CALLS' && tgtInFile && !srcInFile) {
+      externallyReferenced.add(edge.targetId);
     }
-  }
 
-  // Find re-exports (RE_EXPORTS edges going out from file nodes)
-  const reExports: Array<{ name: string; fromFile: string }> = [];
-  for (const edge of graph.edges) {
-    if (!fileNodeIds.has(edge.sourceId)) continue;
-    if (edge.relation !== 'RE_EXPORTS') continue;
-    const sourceNode = graph.nodes.find((n) => n.id === edge.sourceId);
-    const targetNode = graph.nodes.find((n) => n.id === edge.targetId);
-    if (sourceNode && targetNode?.filePath) {
-      reExports.push({
-        name: sourceNode.name,
-        fromFile: targetNode.filePath,
-      });
+    if (edge.relation === 'RE_EXPORTS' && srcInFile) {
+      const sourceNode = idx.get(edge.sourceId);
+      const targetNode = idx.get(edge.targetId);
+      if (sourceNode && targetNode?.filePath) {
+        reExports.push({ name: sourceNode.name, fromFile: targetNode.filePath });
+      }
     }
   }
 
+  // Build exports list using pre-computed set — O(exported_nodes) not O(exported_nodes * edges)
+  const exports = fileNodes
+    .filter((n) => n.isExported)
+    .map((n) => ({
+      name: n.name,
+      isUsed: externallyReferenced.has(n.id),
+      line: n.startLine ?? 0,
+    }));
+
   return {
     file,
     exports,

package/src/analysis/unused-class-members.ts

@@ -38,9 +38,16 @@ export function isClassMemberSuppressed(
   return false;
 }
 
+// Cache compiled glob regexes to avoid re-compilation on repeated allowlist checks
+const _globReCache = new Map<string, RegExp>();
+
 function memberGlobMatch(name: string, pattern: string): boolean {
   if (!pattern.includes('*')) return name === pattern;
-  const re = new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$');
+  let re = _globReCache.get(pattern);
+  if (!re) {
+    re = new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$');
+    _globReCache.set(pattern, re);
+  }
   return re.test(name);
 }
 

package/src/analysis/worker-pool.ts

@@ -8,29 +8,61 @@ export interface WorkerPoolOptions {
   stackSizeMb?: number;
 }
 
+interface QueuedTask {
+  script: string;
+  input: unknown;
+  resolve: (value: unknown) => void;
+  reject: (reason: unknown) => void;
+}
+
 let _globalPool: WorkerPool | null = null;
 
 export class WorkerPool {
   readonly threads: number;
   readonly stackSizeMb: number;
 
+  private _active = 0;
+  private readonly _queue: QueuedTask[] = [];
+
   constructor(opts: WorkerPoolOptions = {}) {
     this.threads = opts.threads ?? cpus().length;
     this.stackSizeMb = opts.stackSizeMb ?? DEFAULT_STACK_SIZE_MB;
   }
 
   run<T>(workerScript: string, input: unknown): Promise<T> {
-    return new Promise((resolve, reject) => {
-      const worker = new Worker(workerScript, {
-        workerData: input,
+    return new Promise<T>((resolve, reject) => {
+      this._queue.push({ script: workerScript, input, resolve: resolve as (v: unknown) => void, reject });
+      this._drain();
+    });
+  }
+
+  private _drain(): void {
+    while (this._active < this.threads && this._queue.length > 0) {
+      const task = this._queue.shift()!;
+      this._active++;
+      const worker = new Worker(task.script, {
+        workerData: task.input,
         resourceLimits: { stackSizeMb: this.stackSizeMb },
       });
-      worker.on('message', (v: T) => resolve(v));
-      worker.on('error', reject);
-      worker.on('exit', code => {
-        if (code !== 0) reject(new Error(`Worker exited with code ${code}`));
+      const cleanup = () => {
+        this._active--;
+        this._drain();
+      };
+      worker.on('message', (v: unknown) => {
+        task.resolve(v);
+        cleanup();
       });
-    });
+      worker.on('error', (err: unknown) => {
+        task.reject(err);
+        cleanup();
+      });
+      worker.on('exit', (code: number) => {
+        if (code !== 0) {
+          task.reject(new Error(`Worker exited with code ${code}`));
+          cleanup();
+        }
+      });
+    }
   }
 }
 

package/src/cli/augment.ts

@@ -89,14 +89,21 @@ export async function augmentContext(options: AugmentContextOptions): Promise<st
     );
   }
 
-  // Markdown format
+  // Markdown format — include file:line navigation hints so LLMs can jump directly to code.
   const lines: string[] = ['## Relevant Code Context', ''];
 
   for (const r of results) {
     const label = r.label ?? 'Symbol';
     const name = r.name ?? r.id;
-    const location = r.filePath ? `${r.filePath}` : null;
-    const heading = location ? `### ${label}: \`${name}\` (${location})` : `### ${label}: \`${name}\``;
+    // Build a file:line reference when available so the LLM can navigate directly.
+    let location: string | null = null;
+    if (r.filePath) {
+      location = r.startLine != null ? `${r.filePath}:${r.startLine}` : r.filePath;
+    }
+    const scoreHint = `score=${r.score.toFixed(3)}`;
+    const heading = location
+      ? `### ${label}: \`${name}\` — \`${location}\` (${scoreHint})`
+      : `### ${label}: \`${name}\` (${scoreHint})`;
     lines.push(heading);
     lines.push('');
   }

package/src/export/sarif.ts

@@ -38,35 +38,35 @@ const SARIF_RULES: SarifRule[] = [
     name: 'GodNode',
     shortDescription: { text: 'High-centrality node (god node) exceeds fan-in threshold' },
     fullDescription: { text: 'A file or module has an unusually high number of incoming dependencies, making it a central point of coupling. Consider splitting this module into smaller, more focused units.' },
-    helpUri: 'https://github.com/nokhodian/monomind/blob/main/docs/rules/god-node.md',
+    helpUri: 'https://github.com/monoes/monomind/blob/main/docs/rules/god-node.md',
   },
   {
     id: 'monograph/unreachable-file',
     name: 'UnreachableFile',
     shortDescription: { text: 'File node unreachable from any entry point' },
     fullDescription: { text: 'A file is not reachable from any known entry point. It may be dead code that can be safely removed.' },
-    helpUri: 'https://github.com/nokhodian/monomind/blob/main/docs/rules/unreachable-file.md',
+    helpUri: 'https://github.com/monoes/monomind/blob/main/docs/rules/unreachable-file.md',
   },
   {
     id: 'monograph/circular-import',
     name: 'CircularImport',
     shortDescription: { text: 'Circular import detected' },
     fullDescription: { text: 'A circular import chain was detected between files. Circular imports can cause initialization order issues and make the codebase harder to understand.' },
-    helpUri: 'https://github.com/nokhodian/monomind/blob/main/docs/rules/circular-import.md',
+    helpUri: 'https://github.com/monoes/monomind/blob/main/docs/rules/circular-import.md',
   },
   {
     id: 'monograph/bridge-node',
     name: 'BridgeNode',
     shortDescription: { text: 'Bridge node — high cross-community coupling' },
     fullDescription: { text: 'A file acts as a bridge between multiple community clusters, creating high cross-community coupling. This may indicate architectural boundaries are not being respected.' },
-    helpUri: 'https://github.com/nokhodian/monomind/blob/main/docs/rules/bridge-node.md',
+    helpUri: 'https://github.com/monoes/monomind/blob/main/docs/rules/bridge-node.md',
   },
   {
     id: 'monograph/hotspot',
     name: 'Hotspot',
     shortDescription: { text: 'File is both frequently changed and highly connected' },
     fullDescription: { text: 'A file is both a churn hotspot (frequently modified) and highly connected in the dependency graph. Changes here have wide blast radius and high risk of regression.' },
-    helpUri: 'https://github.com/nokhodian/monomind/blob/main/docs/rules/hotspot.md',
+    helpUri: 'https://github.com/monoes/monomind/blob/main/docs/rules/hotspot.md',
   },
 ];
 

package/src/graph/analyzer.ts

@@ -4,13 +4,37 @@ import type Graph from 'graphology';
 import type { MonographDb } from '../storage/db.js';
 import { loadGraphFromDb } from './loader.js';
 
+// ── TTL graph cache ───────────────────────────────────────────────────────────
+// Avoids loading the full graph from the DB multiple times in the same request
+// window (e.g. when getShortestPath and getBetweennessCentrality are called
+// back-to-back on the same DB instance).
+
+const GRAPH_CACHE_TTL_MS = 30_000;
+
+interface CachedGraph {
+  graph: Graph;
+  expiresAt: number;
+}
+
+const graphCache = new WeakMap<object, CachedGraph>();
+
+function getOrLoadGraph(db: MonographDb): Graph {
+  const cached = graphCache.get(db);
+  if (cached && Date.now() < cached.expiresAt) return cached.graph;
+  const graph = loadGraphFromDb(db);
+  graphCache.set(db, { graph, expiresAt: Date.now() + GRAPH_CACHE_TTL_MS });
+  return graph;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 export function getShortestPath(
   db: MonographDb,
   sourceId: string,
   targetId: string,
   maxDepth = 6,
 ): string[] | null {
-  const graph = loadGraphFromDb(db);
+  const graph = getOrLoadGraph(db);
   if (!graph.hasNode(sourceId) || !graph.hasNode(targetId)) return null;
   try {
     const path = bidirectional(graph, sourceId, targetId);
@@ -30,7 +54,7 @@ export function getShortestPath(
  * structural bridges — refactoring them has wide blast radius.
  */
 export function getBetweennessCentrality(db: MonographDb): Map<string, number> {
-  const graph = loadGraphFromDb(db);
+  const graph = getOrLoadGraph(db);
   if (graph.order === 0) return new Map();
   const scores = betweennessCentrality(graph, { normalized: true });
   return new Map(Object.entries(scores));

package/src/graph/author-analytics.ts

@@ -76,16 +76,22 @@ export function computeAuthorAnalytics(repoPath: string, db: MonographDb): Autho
   if (commitCount.size === 0) return EMPTY_REPORT;
 
   // ── File ownership ─────────────────────────────────────────────────────────
-  // Get File nodes with degree > 2
+  // Get File nodes with degree > 2 — use JOIN+GROUP BY instead of correlated subquery
   const fileRows = db.prepare(`
     SELECT n.id, n.name, n.file_path
     FROM nodes n
+    JOIN (
+      SELECT id, COUNT(*) AS deg
+      FROM (
+        SELECT source_id AS id FROM edges
+        UNION ALL
+        SELECT target_id AS id FROM edges
+      )
+      GROUP BY id
+      HAVING COUNT(*) > 2
+    ) deg_tbl ON deg_tbl.id = n.id
     WHERE n.label = 'File'
       AND n.file_path IS NOT NULL
-      AND (
-        SELECT COUNT(*) FROM edges e
-        WHERE e.source_id = n.id OR e.target_id = n.id
-      ) > 2
     LIMIT 200
   `).all() as { id: string; name: string; file_path: string }[];
 
@@ -175,3 +181,37 @@ export function computeAuthorAnalytics(repoPath: string, db: MonographDb): Autho
 
   return { authors, topOwners, botAuthors, unownedFiles };
 }
+
+/** Format AuthorAnalyticsReport as structured text for LLM navigation. */
+export function formatAuthorAnalytics(report: AuthorAnalyticsReport): string {
+  if (report.authors.length === 0) {
+    return 'Author analytics: no commit history found.';
+  }
+
+  const lines: string[] = [
+    `Author analytics: ${report.authors.length} contributor(s), ${report.unownedFiles} unowned file(s).`,
+    '',
+  ];
+
+  if (report.topOwners.length > 0) {
+    lines.push('Top file owners (non-bot):');
+    for (const a of report.topOwners) {
+      const trend = a.churnTrend === 'accelerating' ? ' [↑ accelerating]'
+        : a.churnTrend === 'declining' ? ' [↓ declining]' : '';
+      lines.push(`  ${a.author}  files:${a.filesOwned}  commits:${a.commitCount}  recent30d:${a.recentCommits}${trend}`);
+    }
+    lines.push('');
+  }
+
+  if (report.botAuthors.length > 0) {
+    lines.push(`Bot/automation authors (${report.botAuthors.length}): ${report.botAuthors.join(', ')}`);
+    lines.push('');
+  }
+
+  if (report.unownedFiles > 0) {
+    lines.push(`Unowned files: ${report.unownedFiles} file(s) have no majority author (> 50% commits).`);
+    lines.push('Consider adding CODEOWNERS entries for these files.');
+  }
+
+  return lines.join('\n').trimEnd();
+}