@monoes/monograph 1.5.6 → 1.5.8

package/src/graph/subgraph.ts

@@ -1,162 +0,0 @@
-import Database from 'better-sqlite3';
-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;
-
-/** Cache of placeholder strings keyed by count: 1 → "?", 2 → "?,?", etc. */
-const placeholderCache = new Map<number, string>();
-function placeholders(n: number): string {
-  let ph = placeholderCache.get(n);
-  if (!ph) {
-    ph = Array(n).fill('?').join(',');
-    placeholderCache.set(n, ph);
-  }
-  return ph;
-}
-
-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 column omitted — not surfaced in InducedSubgraph
-};
-
-/**
- * Prepared-statement caches per db instance — stored on the db object to avoid
- * cross-db pollution while ensuring each unique chunk size is prepared at most once.
- */
-function getStmtCaches(db: MonographDb): {
-  nodes: Map<number, ReturnType<MonographDb['prepare']>>;
-  edges: Map<number, ReturnType<MonographDb['prepare']>>;
-} {
-  const key = '__subgraphStmtCache__';
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const dbAny = db as any;
-  if (!dbAny[key]) {
-    dbAny[key] = { nodes: new Map(), edges: new Map() };
-  }
-  return dbAny[key] as { nodes: Map<number, ReturnType<MonographDb['prepare']>>; edges: Map<number, ReturnType<MonographDb['prepare']>> };
-}
-
-export function extractInducedSubgraph(db: MonographDb, nodeIds: string[]): InducedSubgraph {
-  if (nodeIds.length === 0) return { nodes: [], edges: [] };
-
-  const stmts = getStmtCaches(db);
-
-  // Chunk helper — caches prepared statements by chunk size to avoid re-prepare per call.
-  function queryChunked<T>(ids: string[], chunkSize: number, stmtCache: Map<number, Database.Statement>, sql: (ph: string) => string): T[] {
-    const results: T[] = [];
-    for (let i = 0; i < ids.length; i += chunkSize) {
-      const chunk = ids.slice(i, i + chunkSize);
-      const ph = placeholders(chunk.length);
-      let stmt = stmtCache.get(chunk.length);
-      if (!stmt) { stmt = db.prepare(sql(ph)); stmtCache.set(chunk.length, stmt); }
-      results.push(...(stmt.all(...chunk) as T[]));
-    }
-    return results;
-  }
-
-  const rawNodes = queryChunked<RawNode>(
-    nodeIds,
-    SQLITE_VAR_LIMIT,
-    stmts.nodes,
-    ph => `SELECT id, label, name, file_path, start_line, end_line, community_id, is_exported, language, properties FROM nodes WHERE id IN (${ph})`,
-  );
-
-  // For edges: query by source_id chunks (1 bind per row), then filter target in-memory.
-  const nodeSet = new Set(nodeIds);
-  const allSourceEdges = queryChunked<RawEdge>(
-    nodeIds,
-    SQLITE_VAR_LIMIT,
-    stmts.edges,
-    // Drop unused 'evidence' column to reduce row data transfer
-    ph => `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason FROM edges WHERE source_id IN (${ph})`,
-  );
-  const rawEdges = allSourceEdges.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 };
-}
-
-/**
- * Format an InducedSubgraph as structured text for LLM consumption.
- * Groups nodes by file path and lists edges with relation + file:line hints.
- */
-export function formatInducedSubgraph(sg: InducedSubgraph): string {
-  if (sg.nodes.length === 0) return 'Subgraph is empty.';
-
-  const lines: string[] = [`Subgraph: ${sg.nodes.length} nodes, ${sg.edges.length} edges`];
-
-  // Group nodes by file
-  const byFile = new Map<string, MonographNode[]>();
-  for (const n of sg.nodes) {
-    const file = n.filePath ?? '(unknown)';
-    let list = byFile.get(file);
-    if (!list) { list = []; byFile.set(file, list); }
-    list.push(n);
-  }
-
-  lines.push('\nNodes:');
-  for (const [file, nodes] of byFile) {
-    lines.push(`  ${file}`);
-    for (const n of nodes) {
-      const loc = n.startLine ? `:${n.startLine}` : '';
-      lines.push(`    ${n.label} ${n.name}${loc}`);
-    }
-  }
-
-  if (sg.edges.length > 0) {
-    lines.push('\nEdges:');
-    for (const e of sg.edges) {
-      lines.push(`  ${e.sourceId} --[${e.relation}]--> ${e.targetId}`);
-    }
-  }
-
-  return lines.join('\n');
-}

package/src/graph/topo-sort.ts

@@ -1,171 +0,0 @@
-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.
- *
- * The in-degree computation is pushed into SQL (GROUP BY aggregation) to avoid
- * materialising the full edge table into JavaScript memory.
- *
- * @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 }[];
-  if (nodeRows.length === 0) return { levels: [], cycleCount: 0 };
-
-  const nodes = nodeRows.map(r => r.id);
-
-  // Compute in-degree (on the reverse graph) via SQL aggregation.
-  // In the original graph each edge src→tgt means "src imports tgt".
-  // In the reverse graph the edge becomes tgt→src, so src gains in-degree +1.
-  // We aggregate target_id counts grouped by source_id to get reverse-in-degree per node.
-  const inDegreeRows = db
-    .prepare(
-      `SELECT source_id AS node_id, COUNT(*) AS cnt
-       FROM edges
-       WHERE source_id != target_id
-       GROUP BY source_id`,
-    )
-    .all() as { node_id: string; cnt: number }[];
-
-  const inDegree = new Map<string, number>();
-  for (const n of nodes) inDegree.set(n, 0);
-  for (const { node_id, cnt } of inDegreeRows) {
-    if (inDegree.has(node_id)) inDegree.set(node_id, cnt);
-  }
-
-  // Build reverse adjacency list — still needed for Kahn's BFS relaxation step.
-  // Fetch only what Kahn needs: target_id → [source_id, ...] (reverse direction).
-  const reverseAdj = new Map<string, string[]>();
-  for (const n of nodes) reverseAdj.set(n, []);
-
-  const edgeRows = db
-    .prepare('SELECT source_id, target_id FROM edges WHERE source_id != target_id')
-    .all() as { source_id: string; target_id: string }[];
-
-  for (const { source_id: src, target_id: tgt } of edgeRows) {
-    if (!reverseAdj.has(tgt) || !reverseAdj.has(src)) continue;
-    reverseAdj.get(tgt)!.push(src);
-  }
-
-  // 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) {
-    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 };
-}
-
-// ---------------------------------------------------------------------------
-// Structured text formatter for LLM consumption
-// ---------------------------------------------------------------------------
-
-/**
- * Format topological sort levels as structured text.
- *
- * Resolves node IDs to names and file paths so LLMs can navigate directly
- * to the source. Cycle nodes (if any) are clearly labelled.
- *
- * @param db - The MonographDb instance (for name resolution)
- * @param result - Result from topologicalLevelSort()
- * @param maxLevels - Max levels to include in output (default: all)
- * @returns Structured text suitable for injection into LLM context
- */
-export function formatTopoSort(
-  db: MonographDb,
-  result: TopoSortResult,
-  maxLevels?: number,
-): string {
-  if (result.levels.length === 0) {
-    return 'Topological sort: no nodes found.';
-  }
-
-  // Batch-resolve all node IDs
-  const allIds = result.levels.flat();
-  const CHUNK = 200;
-  const nodeInfo = new Map<string, { name: string; filePath: string | null }>();
-
-  for (let i = 0; i < allIds.length; i += CHUNK) {
-    const chunk = allIds.slice(i, i + CHUNK);
-    const ph = chunk.map(() => '?').join(',');
-    const rows = db
-      .prepare(`SELECT id, name, file_path FROM nodes WHERE id IN (${ph})`)
-      .all(...chunk) as { id: string; name: string; file_path: string | null }[];
-    for (const row of rows) {
-      nodeInfo.set(row.id, { name: row.name ?? row.id, filePath: row.file_path });
-    }
-  }
-
-  const isCycleLevelIdx =
-    result.cycleCount > 0 && result.levels.length > 0
-      ? result.levels.length - 1
-      : -1;
-
-  const displayLevels = maxLevels !== undefined ? result.levels.slice(0, maxLevels) : result.levels;
-
-  const lines: string[] = [
-    `Topological sort: ${result.levels.length - (result.cycleCount > 0 ? 1 : 0)} level${result.levels.length === 1 ? '' : 's'}` +
-      (result.cycleCount > 0 ? `, ${result.cycleCount} node${result.cycleCount === 1 ? '' : 's'} in cycles` : ''),
-    '',
-  ];
-
-  for (let li = 0; li < displayLevels.length; li++) {
-    const level = displayLevels[li];
-    const label = li === isCycleLevelIdx ? 'Cycle nodes (unresolvable order)' : `Level ${li}`;
-    lines.push(`${label} (${level.length} node${level.length === 1 ? '' : 's'}):`);
-    for (const id of level) {
-      const info = nodeInfo.get(id);
-      const name = info?.name ?? id;
-      const fp = info?.filePath;
-      lines.push(`  ${name}${fp ? ` — ${fp}` : ''}`);
-    }
-    lines.push('');
-  }
-
-  if (maxLevels !== undefined && result.levels.length > maxLevels) {
-    lines.push(`... (${result.levels.length - maxLevels} more level${result.levels.length - maxLevels === 1 ? '' : 's'} omitted)`);
-  }
-
-  return lines.join('\n').trimEnd();
-}

package/src/graph/wcc.ts

@@ -1,187 +0,0 @@
-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);
-  const { parent, rank } = buildUnionFind(nodes);
-
-  for (const { source_id: src, target_id: tgt } of edgeRows) {
-    if (src === tgt) continue;
-    if (!parent.has(src) || !parent.has(tgt)) continue;
-    ufUnion(parent, rank, src, tgt);
-  }
-
-  return groupByRoot(nodes, parent);
-}
-
-// ---------------------------------------------------------------------------
-// Summary stats — avoids name resolution and component array materialisation
-// ---------------------------------------------------------------------------
-
-export interface WccStats {
-  /** Total number of weakly connected components */
-  componentCount: number;
-  /** Size of the largest component */
-  largestSize: number;
-  /** Size of the smallest component */
-  smallestSize: number;
-  /** Mean component size */
-  meanSize: number;
-  /** Number of isolated nodes (component size = 1) */
-  isolatedNodeCount: number;
-}
-
-/**
- * Lightweight summary statistics for all WCCs.
- * Does not materialise component arrays — returns aggregate numbers only.
- */
-export function wccStats(db: MonographDb): WccStats {
-  const components = weaklyConnectedComponents(db);
-  if (components.length === 0) {
-    return { componentCount: 0, largestSize: 0, smallestSize: 0, meanSize: 0, isolatedNodeCount: 0 };
-  }
-
-  const sizes = components.map(c => c.length);
-  const total = sizes.reduce((a, b) => a + b, 0);
-  return {
-    componentCount: sizes.length,
-    largestSize: sizes[0], // already sorted descending
-    smallestSize: sizes[sizes.length - 1],
-    meanSize: Math.round((total / sizes.length) * 100) / 100,
-    isolatedNodeCount: sizes.filter(s => s === 1).length,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Structured text formatter for LLM consumption
-// ---------------------------------------------------------------------------
-
-/**
- * Format WCC results as structured text for LLM consumption.
- *
- * Resolves node IDs to names and file paths for the top-N largest components.
- * Small/isolated components are summarised in aggregate to avoid token waste.
- *
- * @param db - The MonographDb instance (for name resolution)
- * @param components - Result of weaklyConnectedComponents()
- * @param topN - Number of largest components to detail (default: 5)
- * @returns Structured text string suitable for LLM context injection
- */
-export function formatWcc(db: MonographDb, components: string[][], topN = 5): string {
-  if (components.length === 0) {
-    return 'Weakly connected components: no nodes found.';
-  }
-
-  const isolatedCount = components.filter(c => c.length === 1).length;
-  const nonTrivial = components.filter(c => c.length > 1);
-  const display = nonTrivial.slice(0, topN);
-
-  // Batch-resolve all node IDs in the displayed components
-  const allIds = display.flat();
-  const CHUNK = 200;
-  const nodeInfo = new Map<string, { name: string; filePath: string | null }>();
-
-  for (let i = 0; i < allIds.length; i += CHUNK) {
-    const chunk = allIds.slice(i, i + CHUNK);
-    const ph = chunk.map(() => '?').join(',');
-    const rows = db
-      .prepare(`SELECT id, name, file_path FROM nodes WHERE id IN (${ph})`)
-      .all(...chunk) as { id: string; name: string; file_path: string | null }[];
-    for (const row of rows) nodeInfo.set(row.id, { name: row.name ?? row.id, filePath: row.file_path });
-  }
-
-  const lines: string[] = [
-    `Weakly connected components: ${components.length} total` +
-      (isolatedCount > 0 ? ` (${isolatedCount} isolated node${isolatedCount === 1 ? '' : 's'})` : ''),
-    '',
-  ];
-
-  for (let ci = 0; ci < display.length; ci++) {
-    const comp = display[ci];
-    lines.push(`Component ${ci + 1} (${comp.length} nodes):`);
-    for (const id of comp) {
-      const info = nodeInfo.get(id);
-      const name = info?.name ?? id;
-      const fp = info?.filePath;
-      lines.push(`  ${name}${fp ? ` — ${fp}` : ''}`);
-    }
-    if (ci < display.length - 1) lines.push('');
-  }
-
-  if (nonTrivial.length > topN) {
-    lines.push('');
-    lines.push(`... (${nonTrivial.length - topN} more non-trivial component${nonTrivial.length - topN === 1 ? '' : 's'} omitted)`);
-  }
-
-  return lines.join('\n');
-}
-
-// ---------------------------------------------------------------------------
-// Internal union-find helpers
-// ---------------------------------------------------------------------------
-
-function buildUnionFind(nodes: string[]): { parent: Map<string, string>; rank: Map<string, number> } {
-  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);
-  }
-  return { parent, rank };
-}
-
-function ufFind(parent: Map<string, string>, 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 ufUnion(parent: Map<string, string>, rank: Map<string, number>, a: string, b: string): void {
-  const ra = ufFind(parent, a);
-  const rb = ufFind(parent, 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);
-  }
-}
-
-function groupByRoot(nodes: string[], parent: Map<string, string>): string[][] {
-  const components = new Map<string, string[]>();
-  for (const n of nodes) {
-    const root = ufFind(parent, n);
-    if (!components.has(root)) components.set(root, []);
-    components.get(root)!.push(n);
-  }
-  return [...components.values()].sort((a, b) => b.length - a.length);
-}

package/src/groups/contract-bridge.ts

@@ -1,103 +0,0 @@
-/**
- * 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;
-}