@monoes/monograph 1.0.0 → 1.2.0

package/src/graph/statistics.ts

@@ -0,0 +1,133 @@
+import { bfsFromNode } from 'graphology-traversal/bfs.js';
+import { loadGraphFromDb } from './loader.js';
+import type { MonographDb } from '../storage/db.js';
+
+/**
+ * Graph density: ratio of actual edges to maximum possible directed edges.
+ * For a directed graph with n nodes: max = n * (n - 1).
+ * Ignores self-loops.
+ */
+export function graphDensity(db: MonographDb): number {
+  const graph = loadGraphFromDb(db);
+  const n = graph.order;
+  if (n < 2) return 0;
+  const maxEdges = n * (n - 1);
+  // Use simple directed edge count (deduplicate multi-edges for density)
+  const seen = new Set<string>();
+  graph.forEachEdge((_, _attr, src, tgt) => {
+    if (src !== tgt) seen.add(`${src}→${tgt}`);
+  });
+  return seen.size / maxEdges;
+}
+
+/**
+ * Average local clustering coefficient across all nodes.
+ * For a directed graph, the local clustering coefficient of node v is:
+ *   (triangles through v) / (directed_pairs through v)
+ * where directed_pairs = k_in * k_out - mutual_pairs
+ * We use the undirected approximation: treat edges as undirected, count triangles.
+ */
+export function clusteringCoefficient(db: MonographDb): number {
+  const graph = loadGraphFromDb(db);
+  if (graph.order === 0) return 0;
+
+  // Build undirected adjacency sets
+  const neighbors = new Map<string, Set<string>>();
+  graph.forEachNode(node => neighbors.set(node, new Set()));
+  graph.forEachEdge((_, _attr, src, tgt) => {
+    if (src !== tgt) {
+      neighbors.get(src)!.add(tgt);
+      neighbors.get(tgt)!.add(src);
+    }
+  });
+
+  let totalCoeff = 0;
+  let countWithNeighbors = 0;
+
+  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++) {
+        if (neighbors.get(nbList[i])?.has(nbList[j])) {
+          triangles++;
+        }
+      }
+    }
+
+    const possible = (k * (k - 1)) / 2;
+    totalCoeff += triangles / possible;
+    countWithNeighbors++;
+  }
+
+  if (countWithNeighbors === 0) return 0;
+  return totalCoeff / countWithNeighbors;
+}
+
+/**
+ * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
+ * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ */
+export function averagePathLength(db: MonographDb): number {
+  const graph = loadGraphFromDb(db);
+  const nodes = graph.nodes();
+  if (nodes.length < 2) return 0;
+
+  let totalLength = 0;
+  let reachablePairs = 0;
+
+  for (const source of nodes) {
+    const distances = new Map<string, number>();
+    distances.set(source, 0);
+
+    bfsFromNode(graph, source, (node, _attr, depth) => {
+      if (node !== source) {
+        distances.set(node, depth);
+      }
+    });
+
+    for (const [target, dist] of distances) {
+      if (target !== source && dist > 0) {
+        totalLength += dist;
+        reachablePairs++;
+      }
+    }
+  }
+
+  if (reachablePairs === 0) return 0;
+  return totalLength / reachablePairs;
+}
+
+/**
+ * Graph diameter: the maximum shortest path length across all reachable node pairs.
+ * Returns 0 for empty or single-node graphs.
+ */
+export function graphDiameter(db: MonographDb): number {
+  const graph = loadGraphFromDb(db);
+  const nodes = graph.nodes();
+  if (nodes.length < 2) return 0;
+
+  let maxDist = 0;
+
+  for (const source of nodes) {
+    const distances = new Map<string, number>();
+    distances.set(source, 0);
+
+    bfsFromNode(graph, source, (node, _attr, depth) => {
+      if (node !== source) {
+        distances.set(node, depth);
+      }
+    });
+
+    for (const [target, dist] of distances) {
+      if (target !== source && dist > maxDist) {
+        maxDist = dist;
+      }
+    }
+  }
+
+  return maxDist;
+}

package/src/graph/stats.ts

@@ -0,0 +1,122 @@
+import type Database from 'better-sqlite3';
+
+export type RiskBin = 'low' | 'medium' | 'high' | 'critical';
+
+export interface RiskProfile {
+  low: number;
+  medium: number;
+  high: number;
+  critical: number;
+  lowPct: number;
+  mediumPct: number;
+  highPct: number;
+  criticalPct: number;
+}
+
+export interface CouplingProfile {
+  p50FanIn: number;
+  p75FanIn: number;
+  p90FanIn: number;
+  p95FanIn: number;
+  couplingHighPct: number;
+  fanInProfile: RiskProfile;
+  fanOutProfile: RiskProfile;
+  totalFiles: number;
+}
+
+export interface GraphStatsSummary {
+  nodeCount: number;
+  edgeCount: number;
+  communityCount: number;
+  fileCount: number;
+  couplingProfile: CouplingProfile;
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.floor((p / 100) * sorted.length);
+  return sorted[Math.min(idx, sorted.length - 1)];
+}
+
+function buildRiskProfile(values: number[]): RiskProfile {
+  const total = values.length;
+  let low = 0, medium = 0, high = 0, critical = 0;
+  for (const v of values) {
+    if (v < 5) low++;
+    else if (v <= 15) medium++;
+    else if (v <= 30) high++;
+    else critical++;
+  }
+  const pct = (n: number) => total > 0 ? Math.round((n / total) * 100) : 0;
+  return {
+    low,
+    medium,
+    high,
+    critical,
+    lowPct: pct(low),
+    mediumPct: pct(medium),
+    highPct: pct(high),
+    criticalPct: pct(critical),
+  };
+}
+
+/**
+ * Compute full coupling profile from SQLite.
+ */
+export function computeCouplingProfile(db: Database.Database): CouplingProfile {
+  const fanInRows = db.prepare(
+    'SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id'
+  ).all() as { target_id: string; c: number }[];
+
+  const fanOutRows = db.prepare(
+    'SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id'
+  ).all() as { source_id: string; c: number }[];
+
+  const totalFiles = (db.prepare(
+    "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'"
+  ).get() as { n: number }).n;
+
+  const fanInValues = fanInRows.map(r => r.c).sort((a, b) => a - b);
+  const fanOutValues = fanOutRows.map(r => r.c).sort((a, b) => a - b);
+
+  const p95FanIn = percentile(fanInValues, 95);
+  const couplingHighCount = fanInValues.filter(v => v > p95FanIn).length;
+  const couplingHighPct = fanInValues.length > 0
+    ? Math.round((couplingHighCount / fanInValues.length) * 100)
+    : 0;
+
+  return {
+    p50FanIn: percentile(fanInValues, 50),
+    p75FanIn: percentile(fanInValues, 75),
+    p90FanIn: percentile(fanInValues, 90),
+    p95FanIn,
+    couplingHighPct,
+    fanInProfile: buildRiskProfile(fanInValues),
+    fanOutProfile: buildRiskProfile(fanOutValues),
+    totalFiles,
+  };
+}
+
+/**
+ * Quick stats summary (extends existing stats from monograph_stats MCP tool).
+ */
+export function computeGraphStats(db: Database.Database): GraphStatsSummary {
+  const nodeCount = (db.prepare('SELECT COUNT(*) as n FROM nodes').get() as { n: number }).n;
+  const edgeCount = (db.prepare('SELECT COUNT(*) as n FROM edges').get() as { n: number }).n;
+  const communityCount = (db.prepare(
+    "SELECT COUNT(DISTINCT community_id) as n FROM nodes WHERE community_id IS NOT NULL"
+  ).get() as { n: number }).n;
+  const fileCount = (db.prepare(
+    "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'"
+  ).get() as { n: number }).n;
+
+  const couplingProfile = computeCouplingProfile(db);
+
+  return {
+    nodeCount,
+    edgeCount,
+    communityCount,
+    fileCount,
+    couplingProfile,
+  };
+}

package/src/graph/subgraph.ts

@@ -0,0 +1,90 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+export interface InducedSubgraph {
+  nodes: MonographNode[];
+  edges: MonographEdge[];
+}
+
+/**
+ * Extract the induced subgraph for the given set of node ids.
+ *
+ * The induced subgraph contains:
+ * - Only the nodes whose ids are in `nodeIds` (and exist in the DB)
+ * - Only the edges where both source and target are in `nodeIds`
+ *
+ * @param db - The MonographDb instance
+ * @param nodeIds - The subset of node ids to include
+ * @returns An object with `nodes` and `edges` arrays
+ */
+// SQLite SQLITE_MAX_VARIABLE_NUMBER limit (32766). Edge query binds nodeIds once
+// (source_id IN chunk), then filters target in-memory — full limit available per chunk.
+const SQLITE_VAR_LIMIT = 32766;
+
+export function extractInducedSubgraph(db: MonographDb, nodeIds: string[]): InducedSubgraph {
+  if (nodeIds.length === 0) return { nodes: [], edges: [] };
+
+  // Chunk helper to stay within SQLITE_MAX_VARIABLE_NUMBER
+  function queryChunked<T>(ids: string[], chunkSize: number, query: (ph: string, chunk: string[]) => T[]): T[] {
+    const results: T[] = [];
+    for (let i = 0; i < ids.length; i += chunkSize) {
+      const chunk = ids.slice(i, i + chunkSize);
+      const ph = chunk.map(() => '?').join(',');
+      results.push(...query(ph, chunk));
+    }
+    return results;
+  }
+
+  type RawNode = {
+    id: string; label: string; name: string; norm_label?: string | null; file_path: string | null;
+    start_line: number | null; end_line: number | null; community_id: number | null;
+    is_exported: number; language: string | null; properties: string | null;
+  };
+  type RawEdge = {
+    id: string; source_id: string; target_id: string; relation: string;
+    confidence: string; confidence_score: number; reason: string | null; evidence: string | null;
+  };
+
+  const rawNodes = queryChunked<RawNode>(nodeIds, SQLITE_VAR_LIMIT, (ph, chunk) =>
+    db.prepare(
+      `SELECT id, label, name, file_path, start_line, end_line, community_id, is_exported, language, properties
+       FROM nodes WHERE id IN (${ph})`
+    ).all(...chunk) as RawNode[]
+  );
+
+  // For edges: query by source_id chunks (1 bind per row), then filter target in-memory.
+  // Querying by both source+target would miss cross-chunk edges and requires 2× bind slots.
+  const nodeSet = new Set(nodeIds);
+  const rawEdges = queryChunked<RawEdge>(nodeIds, SQLITE_VAR_LIMIT, (ph, chunk) =>
+    (db.prepare(
+      `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason, evidence
+       FROM edges WHERE source_id IN (${ph})`
+    ).all(...chunk) as RawEdge[]).filter(e => nodeSet.has(e.target_id))
+  );
+
+  const nodes: MonographNode[] = rawNodes.map(n => ({
+    id: n.id,
+    label: n.label as MonographNode['label'],
+    name: n.name,
+    normLabel: (n.norm_label ?? n.name ?? '').toLowerCase(),
+    filePath: n.file_path ?? undefined,
+    startLine: n.start_line ?? undefined,
+    endLine: n.end_line ?? undefined,
+    communityId: n.community_id ?? undefined,
+    isExported: n.is_exported === 1,
+    language: n.language ?? undefined,
+    properties: n.properties ? (JSON.parse(n.properties) as Record<string, unknown>) : undefined,
+  }));
+
+  const edges: MonographEdge[] = rawEdges.map(e => ({
+    id: e.id,
+    sourceId: e.source_id,
+    targetId: e.target_id,
+    relation: e.relation as MonographEdge['relation'],
+    confidence: e.confidence as MonographEdge['confidence'],
+    confidenceScore: e.confidence_score,
+    reason: e.reason ?? undefined,
+  }));
+
+  return { nodes, edges };
+}

package/src/graph/topo-sort.ts

@@ -0,0 +1,86 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface TopoSortResult {
+  /** Groups of nodes that can be processed independently at each level.
+   *  Level 0 = leaves (nodes with no outgoing IMPORTS edges on the reverse graph).
+   *  Higher levels depend on previous levels. Cycle nodes are appended last. */
+  levels: string[][];
+  /** Number of nodes that are part of a cycle and could not be sorted. */
+  cycleCount: number;
+}
+
+/**
+ * Topological level sort using Kahn's algorithm on the *reverse* import graph.
+ *
+ * In the reverse graph, an edge A→B in the original (A imports B) becomes B→A.
+ * Files with no incoming edges on the reverse graph (i.e., no one imports them)
+ * are leaves and appear in level 0.
+ *
+ * @param db - The MonographDb instance
+ * @returns Object with `levels` (array of independent groups, leaf-first) and `cycleCount`.
+ */
+export function topologicalLevelSort(db: MonographDb): TopoSortResult {
+  const nodeRows = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
+  const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
+    source_id: string;
+    target_id: string;
+  }[];
+
+  if (nodeRows.length === 0) return { levels: [], cycleCount: 0 };
+
+  const nodes = nodeRows.map(r => r.id);
+
+  // Build reverse graph: original edge src→tgt becomes tgt→src in reverse
+  // In-degree in the reverse graph = number of nodes that tgt imports (out-degree in original)
+  const reverseAdj = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+
+  for (const n of nodes) {
+    reverseAdj.set(n, []);
+    inDegree.set(n, 0);
+  }
+
+  for (const { source_id: src, target_id: tgt } of edgeRows) {
+    if (src === tgt) continue; // skip self-loops
+    if (!reverseAdj.has(tgt) || !reverseAdj.has(src)) continue;
+    reverseAdj.get(tgt)!.push(src);
+    inDegree.set(src, (inDegree.get(src) ?? 0) + 1);
+  }
+
+  // Kahn's BFS on the reverse graph
+  const queue: string[] = [];
+  for (const [node, deg] of inDegree) {
+    if (deg === 0) queue.push(node);
+  }
+
+  const levels: string[][] = [];
+  const visited = new Set<string>();
+
+  while (queue.length > 0) {
+    // All nodes currently at in-degree 0 form one level
+    const level = [...queue];
+    queue.length = 0;
+    levels.push(level);
+
+    for (const node of level) {
+      visited.add(node);
+      for (const neighbor of reverseAdj.get(node) ?? []) {
+        if (visited.has(neighbor)) continue;
+        const newDeg = (inDegree.get(neighbor) ?? 0) - 1;
+        inDegree.set(neighbor, newDeg);
+        if (newDeg === 0) queue.push(neighbor);
+      }
+    }
+  }
+
+  // Remaining unvisited nodes are in cycles
+  const cycleNodes = nodes.filter(n => !visited.has(n));
+  let cycleCount = 0;
+
+  if (cycleNodes.length > 0) {
+    cycleCount = cycleNodes.length;
+    levels.push(cycleNodes);
+  }
+
+  return { levels, cycleCount };
+}

package/src/graph/wcc.ts

@@ -0,0 +1,78 @@
+import type { MonographDb } from '../storage/db.js';
+
+/**
+ * Find all weakly connected components (WCCs) of the graph.
+ *
+ * Treats the directed graph as undirected: an edge A→B connects A and B
+ * regardless of direction. Uses union-find (disjoint-set) for O(α·n) performance.
+ *
+ * @param db - The MonographDb instance
+ * @returns Array of components; each component is an array of node ids.
+ *          Sorted so the largest component comes first.
+ */
+export function weaklyConnectedComponents(db: MonographDb): string[][] {
+  const nodeRows = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
+  const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
+    source_id: string;
+    target_id: string;
+  }[];
+
+  if (nodeRows.length === 0) return [];
+
+  const nodes = nodeRows.map(r => r.id);
+
+  // Union-Find
+  const parent = new Map<string, string>();
+  const rank = new Map<string, number>();
+
+  for (const n of nodes) {
+    parent.set(n, n);
+    rank.set(n, 0);
+  }
+
+  function find(x: string): string {
+    let root = x;
+    while (parent.get(root) !== root) root = parent.get(root)!;
+    // Path compression
+    let cur = x;
+    while (cur !== root) {
+      const next = parent.get(cur)!;
+      parent.set(cur, root);
+      cur = next;
+    }
+    return root;
+  }
+
+  function union(a: string, b: string): void {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra === rb) return;
+    const rankA = rank.get(ra) ?? 0;
+    const rankB = rank.get(rb) ?? 0;
+    if (rankA < rankB) {
+      parent.set(ra, rb);
+    } else if (rankA > rankB) {
+      parent.set(rb, ra);
+    } else {
+      parent.set(rb, ra);
+      rank.set(ra, rankA + 1);
+    }
+  }
+
+  for (const { source_id: src, target_id: tgt } of edgeRows) {
+    if (src === tgt) continue;
+    if (!parent.has(src) || !parent.has(tgt)) continue;
+    union(src, tgt);
+  }
+
+  // Group nodes by root
+  const components = new Map<string, string[]>();
+  for (const n of nodes) {
+    const root = find(n);
+    if (!components.has(root)) components.set(root, []);
+    components.get(root)!.push(n);
+  }
+
+  // Return sorted by size descending
+  return [...components.values()].sort((a, b) => b.length - a.length);
+}

package/src/groups/contract-bridge.ts

@@ -0,0 +1,103 @@
+/**
+ * Contract Bridge Detection
+ *
+ * Finds shared type definitions (Interface, Type, Class) that appear across
+ * multiple repos in a group — these are potential contract bridges.
+ */
+
+import { join } from 'path';
+import { existsSync } from 'fs';
+import Database from 'better-sqlite3';
+import type { GroupConfig } from './group-config.js';
+
+export interface ContractBridge {
+  /** Shared type name */
+  name: string;
+  /** Repo names that define this type */
+  repos: string[];
+  /** Node labels (Interface, Type, Class, etc.) */
+  labels: string[];
+}
+
+interface TypeRow {
+  name: string;
+  label: string;
+}
+
+function getRepoDbPath(repoPath: string): string {
+  return join(repoPath, '.monomind', 'monograph.db');
+}
+
+/**
+ * Fetch all Interface, Type, and Class nodes from a repo DB.
+ */
+function fetchTypeNodes(dbPath: string, repoName: string): TypeRow[] {
+  if (!existsSync(dbPath)) {
+    console.warn(`[contract-bridge] Skipping repo "${repoName}": DB not found at ${dbPath}`);
+    return [];
+  }
+
+  let db: Database.Database | null = null;
+  try {
+    db = new Database(dbPath, { readonly: true });
+    const rows = db
+      .prepare(`SELECT name, label FROM nodes WHERE label IN ('Interface', 'Type', 'Class')`)
+      .all() as TypeRow[];
+    return rows;
+  } catch (err) {
+    console.warn(`[contract-bridge] Error reading repo "${repoName}": ${err}`);
+    return [];
+  } finally {
+    db?.close();
+  }
+}
+
+/**
+ * Detect contract bridges: type names shared across >= 2 repos.
+ * Results sorted by number of repos descending.
+ *
+ * @param groupConfig - Parsed group configuration
+ * @returns List of ContractBridge entries
+ */
+export async function detectContractBridges(
+  groupConfig: GroupConfig,
+): Promise<ContractBridge[]> {
+  // Map from type name -> { repos: Set<string>, labels: Set<string> }
+  const typeMap = new Map<string, { repos: Set<string>; labels: Set<string> }>();
+
+  for (const repo of groupConfig.repos) {
+    const dbPath = getRepoDbPath(repo.path);
+    const rows = fetchTypeNodes(dbPath, repo.name);
+
+    for (const row of rows) {
+      if (!row.name) continue;
+      const key = row.name;
+      const existing = typeMap.get(key);
+      if (existing) {
+        existing.repos.add(repo.name);
+        existing.labels.add(row.label);
+      } else {
+        typeMap.set(key, {
+          repos: new Set([repo.name]),
+          labels: new Set([row.label]),
+        });
+      }
+    }
+  }
+
+  const bridges: ContractBridge[] = [];
+  for (const [name, { repos, labels }] of typeMap) {
+    if (repos.size >= 2) {
+      bridges.push({
+        name,
+        repos: [...repos],
+        labels: [...labels],
+      });
+    }
+  }
+
+  // Sort by number of repos descending, then alphabetically
+  bridges.sort((a, b) => b.repos.length - a.repos.length || a.name.localeCompare(b.name));
+
+  return bridges;
+}