@monoes/monograph 1.5.5 → 1.5.7

package/src/graph/external-style-usage.ts

@@ -1,81 +0,0 @@
-// Augments the module graph with synthetic npm-package import edges for
-// style-only packages (.css/.scss/.sass under node_modules).
-
-export interface ExternalStyleImport {
-  importingFile: string;
-  stylePath: string;     // resolved path under node_modules
-  packageName: string;   // e.g. "bootstrap", "@mui/x-data-grid"
-}
-
-export interface ExternalStyleScanResult {
-  injectedEdges: ExternalStyleImport[];
-  scannedFiles: number;
-  skippedCycles: number;
-}
-
-const STYLE_EXTS = ['.css', '.scss', '.sass', '.less'];
-const AT_IMPORT_RE = /@import\s+['"]([^'"]+)['"]/g;
-
-/** Returns true if a path looks like a trackable external stylesheet. */
-export function isTrackableExternalStylePath(path: string): boolean {
-  const norm = path.replace(/\\/g, '/');
-  if (!norm.includes('node_modules/')) return false;
-  return STYLE_EXTS.some(ext => norm.endsWith(ext));
-}
-
-/** Extract the npm package name from a node_modules path. */
-export function packageNameFromPath(path: string): string {
-  const norm = path.replace(/\\/g, '/');
-  const idx = norm.lastIndexOf('node_modules/');
-  if (idx === -1) return '';
-  const rest = norm.slice(idx + 'node_modules/'.length);
-  const parts = rest.split('/');
-  if (parts[0].startsWith('@') && parts.length >= 2) return `${parts[0]}/${parts[1]}`;
-  return parts[0];
-}
-
-/** Scan @import statements in a stylesheet source, yielding resolved paths. */
-export function scanStyleImports(source: string): string[] {
-  const results: string[] = [];
-  let m: RegExpExecArray | null;
-  AT_IMPORT_RE.lastIndex = 0;
-  while ((m = AT_IMPORT_RE.exec(source)) !== null) results.push(m[1]);
-  return results;
-}
-
-/** Walk a list of resolved import paths and return synthetic external-style package edges. */
-export function augmentExternalStylePackageUsage(
-  importEdges: Array<{ importingFile: string; resolvedPath: string }>,
-  getSource?: (path: string) => string | undefined,
-): ExternalStyleScanResult {
-  const injectedEdges: ExternalStyleImport[] = [];
-  const visited = new Set<string>();
-  let scannedFiles = 0;
-  let skippedCycles = 0;
-
-  function processStyleFile(importingFile: string, stylePath: string): void {
-    if (!isTrackableExternalStylePath(stylePath)) return;
-    const packageName = packageNameFromPath(stylePath);
-    if (!packageName) return;
-
-    injectedEdges.push({ importingFile, stylePath, packageName });
-
-    if (getSource && !visited.has(stylePath)) {
-      if (visited.size > 500) { skippedCycles++; return; }
-      visited.add(stylePath);
-      scannedFiles++;
-      const src = getSource(stylePath);
-      if (src) {
-        for (const imp of scanStyleImports(src)) {
-          processStyleFile(stylePath, imp);
-        }
-      }
-    }
-  }
-
-  for (const edge of importEdges) {
-    processStyleFile(edge.importingFile, edge.resolvedPath);
-  }
-
-  return { injectedEdges, scannedFiles, skippedCycles };
-}

package/src/graph/health-score.ts

@@ -1,179 +0,0 @@
-import type Database from 'better-sqlite3';
-
-export interface HealthScorePenalties {
-  unreachableFilePct: number;   // % of file nodes unreachable
-  godNodePct: number;           // % of nodes that are god nodes (degree > p95)
-  circularEdgePct: number;      // % of edges that form cycles
-  hotspotPct: number;           // % of files with churnScore > 0.5
-  isolatedNodePct: number;      // % of nodes with degree 0
-  crossCommunityEdgePct: number; // % of edges crossing community boundaries
-}
-
-export interface HealthScoreResult {
-  score: number;       // 0-100
-  grade: 'A' | 'B' | 'C' | 'D' | 'F';
-  penalties: HealthScorePenalties;
-  summary: string;
-}
-
-export function letterGrade(score: number): 'A' | 'B' | 'C' | 'D' | 'F' {
-  if (score >= 90) return 'A';
-  if (score >= 80) return 'B';
-  if (score >= 70) return 'C';
-  if (score >= 60) return 'D';
-  return 'F';
-}
-
-export function computeHealthScore(db: Database.Database): HealthScoreResult {
-  // ── Total file nodes ──────────────────────────────────────────────────────
-  const totalFilesRow = db.prepare(
-    "SELECT COUNT(*) as c FROM nodes WHERE label = 'File'"
-  ).get() as { c: number };
-  const totalFiles = totalFilesRow.c;
-
-  // ── Unreachable file nodes ────────────────────────────────────────────────
-  const unreachableRow = db.prepare(
-    "SELECT COUNT(*) as c FROM nodes WHERE label = 'File' AND json_extract(properties, '$.unreachable') = 1"
-  ).get() as { c: number };
-  const unreachableFiles = unreachableRow.c;
-
-  // ── Total nodes ───────────────────────────────────────────────────────────
-  const totalNodesRow = db.prepare('SELECT COUNT(*) as c FROM nodes').get() as { c: number };
-  const totalNodes = totalNodesRow.c;
-
-  // ── p95 degree (god nodes) ────────────────────────────────────────────────
-  // 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
-    ? degreeRows.filter(r => r.degree > p95Degree).length
-    : 0;
-
-  // ── Circular edges (bidirectional import pairs) ───────────────────────────
-  const totalEdgesRow = db.prepare('SELECT COUNT(*) as c FROM edges').get() as { c: number };
-  const totalEdges = totalEdgesRow.c;
-
-  const circularRow = db.prepare(`
-    SELECT COUNT(*) as c FROM edges e1
-    JOIN edges e2 ON e1.source_id = e2.target_id AND e1.target_id = e2.source_id
-    WHERE e1.relation = 'IMPORTS' AND e2.relation = 'IMPORTS'
-      AND e1.source_id < e1.target_id
-  `).get() as { c: number };
-  // Each circular pair is counted once; each pair has 2 edges contributing
-  const circularEdges = circularRow.c * 2;
-
-  // ── Hotspot files (churnScore > 0.5 in properties) ───────────────────────
-  // Push the numeric filter into SQLite via json_extract() — avoids O(N) JS JSON.parse loop
-  const hotspotRow = db.prepare(`
-    SELECT COUNT(*) as c FROM nodes
-    WHERE label = 'File'
-      AND CAST(json_extract(properties, '$.churnScore') AS REAL) > 0.5
-  `).get() as { c: number };
-  const hotspotCount = hotspotRow.c;
-
-  // ── Isolated nodes (degree = 0) ───────────────────────────────────────────
-  const isolatedRow = db.prepare(`
-    SELECT COUNT(*) as c FROM nodes n
-    WHERE NOT EXISTS (SELECT 1 FROM edges e WHERE e.source_id = n.id OR e.target_id = n.id)
-  `).get() as { c: number };
-  const isolatedNodes = isolatedRow.c;
-
-  // ── Cross-community edges ─────────────────────────────────────────────────
-  const crossCommRow = db.prepare(`
-    SELECT COUNT(*) as c FROM edges e
-    JOIN nodes n1 ON n1.id = e.source_id
-    JOIN nodes n2 ON n2.id = e.target_id
-    WHERE n1.community_id IS NOT NULL
-      AND n2.community_id IS NOT NULL
-      AND n1.community_id != n2.community_id
-  `).get() as { c: number };
-  const crossCommunityEdges = crossCommRow.c;
-
-  // ── Compute percentages ───────────────────────────────────────────────────
-  const pct = (count: number, total: number): number =>
-    total > 0 ? (count / total) * 100 : 0;
-
-  const penalties: HealthScorePenalties = {
-    unreachableFilePct: pct(unreachableFiles, totalFiles),
-    godNodePct: pct(godNodeCount, totalNodes),
-    circularEdgePct: pct(circularEdges, totalEdges),
-    hotspotPct: pct(hotspotCount, totalFiles),
-    isolatedNodePct: pct(isolatedNodes, totalNodes),
-    crossCommunityEdgePct: pct(crossCommunityEdges, totalEdges),
-  };
-
-  // ── Score formula ─────────────────────────────────────────────────────────
-  let score = 100;
-  score -= Math.min(penalties.unreachableFilePct * 0.25, 25);
-  score -= Math.min(penalties.godNodePct * 0.20, 20);
-  score -= Math.min(penalties.circularEdgePct * 0.20, 20);
-  score -= Math.min(penalties.hotspotPct * 0.15, 15);
-  score -= Math.min(penalties.isolatedNodePct * 0.10, 10);
-  score -= Math.min(penalties.crossCommunityEdgePct * 0.10, 10);
-  score = Math.max(0, Math.round(score * 10) / 10);
-
-  const grade = letterGrade(score);
-
-  const fmt = (pct: number, penalty: number) => `${pct.toFixed(1)}% (-${penalty.toFixed(1)})`;
-  const summary = [
-    `Grade: ${grade} (score: ${score}/100)`,
-    `Penalties:`,
-    `  unreachable files: ${fmt(penalties.unreachableFilePct, Math.min(penalties.unreachableFilePct * 0.25, 25))}`,
-    `  god nodes: ${fmt(penalties.godNodePct, Math.min(penalties.godNodePct * 0.20, 20))}`,
-    `  circular edges: ${fmt(penalties.circularEdgePct, Math.min(penalties.circularEdgePct * 0.20, 20))}`,
-    `  hotspot files: ${fmt(penalties.hotspotPct, Math.min(penalties.hotspotPct * 0.15, 15))}`,
-    `  isolated nodes: ${fmt(penalties.isolatedNodePct, Math.min(penalties.isolatedNodePct * 0.10, 10))}`,
-    `  cross-community edges: ${fmt(penalties.crossCommunityEdgePct, Math.min(penalties.crossCommunityEdgePct * 0.10, 10))}`,
-  ].join('\n');
-
-  return { score, grade, penalties, summary };
-}
-
-/**
- * Format a HealthScoreResult as structured text for LLM navigation.
- * Provides a concise grade breakdown that an LLM can parse and act on.
- *
- * @param result - HealthScoreResult from computeHealthScore()
- * @returns structured text suitable for LLM consumption
- */
-export function formatHealthScore(result: HealthScoreResult): string {
-  const { score, grade, penalties } = result;
-
-  const fmt = (val: number): string => val.toFixed(1);
-
-  const lines: string[] = [
-    `health_score: ${score}/100  grade: ${grade}`,
-    '',
-    'penalties:',
-    `  unreachable_files:     ${fmt(penalties.unreachableFilePct)}%  (max -25)`,
-    `  god_nodes:             ${fmt(penalties.godNodePct)}%  (max -20)`,
-    `  circular_edges:        ${fmt(penalties.circularEdgePct)}%  (max -20)`,
-    `  hotspot_files:         ${fmt(penalties.hotspotPct)}%  (max -15)`,
-    `  isolated_nodes:        ${fmt(penalties.isolatedNodePct)}%  (max -10)`,
-    `  cross_community_edges: ${fmt(penalties.crossCommunityEdgePct)}%  (max -10)`,
-    '',
-  ];
-
-  // Actionable guidance for grades below B
-  if (grade === 'F' || grade === 'D') {
-    lines.push('action_required: yes');
-    if (penalties.circularEdgePct > 5) lines.push('  - break circular import cycles (monograph_context for file dependencies)');
-    if (penalties.godNodePct > 5) lines.push('  - split god nodes (monograph_god_nodes for candidates)');
-    if (penalties.unreachableFilePct > 10) lines.push('  - investigate unreachable files (monograph_detect_changes to surface dead paths)');
-  } else if (grade === 'C') {
-    lines.push('action_suggested: yes');
-    if (penalties.hotspotPct > 10) lines.push('  - reduce churn on hotspot files');
-    if (penalties.isolatedNodePct > 10) lines.push('  - connect or remove isolated nodes');
-  }
-
-  return lines.join('\n');
-}

package/src/graph/hotspots.ts

@@ -1,219 +0,0 @@
-import { execSync } from 'child_process';
-import type Database from 'better-sqlite3';
-
-// ── Process-scoped TTL cache for expensive git log calls ─────────────────────
-// Key: `${projectDir}:${windowDays}` → { output, ts }
-const GIT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const gitLogCache = new Map<string, { output: string; ts: number }>();
-
-export interface HotspotResult {
-  nodeId: string;
-  nodeName: string;
-  filePath: string;
-  label: string;
-  communityId: number | null;
-  /** Recency-weighted commit count (exponential decay, half-life 90 days) */
-  churnScore: number;
-  /** Raw commit count in the analysis window */
-  rawCommitCount: number;
-  /** Graph centrality: in+out degree */
-  centralityScore: number;
-  /** Combined hotspot score: churnScore * centralityScore */
-  hotspotScore: number;
-  /** Trend based on recent vs older half of window */
-  trend: 'accelerating' | 'stable' | 'cooling';
-  /** Last commit date for this file */
-  lastCommitDate: string | null;
-}
-
-/**
- * Compute hotspot scores for all file nodes in the graph.
- * Combines recency-weighted git churn (half-life 90 days) with
- * graph centrality (in+out degree) to identify high-risk files.
- *
- * @param db - monograph database
- * @param projectDir - repo root (for git log)
- * @param options.windowDays - git log window (default 365)
- * @param options.limit - max results (default 20)
- * @param options.minCommits - filter files with fewer commits (default 2)
- */
-export function computeHotspots(
-  db: Database.Database,
-  projectDir: string,
-  options: {
-    windowDays?: number;
-    limit?: number;
-    minCommits?: number;
-  } = {},
-): HotspotResult[] {
-  const windowDays = options.windowDays ?? 365;
-  const limit = options.limit ?? 20;
-  const minCommits = options.minCommits ?? 2;
-  const now = Date.now();
-  const HALF_LIFE_DAYS = 90;
-
-  // ── Step 1: Get git log with dates (TTL-cached per projectDir+window) ────
-  // Format: ISO-date\tfile-path (one per changed file per commit)
-  let gitOutput = '';
-  const cacheKey = `${projectDir}:${windowDays}`;
-  const cached = gitLogCache.get(cacheKey);
-  if (cached && now - cached.ts < GIT_CACHE_TTL_MS) {
-    gitOutput = cached.output;
-  } else {
-    try {
-      gitOutput = execSync(
-        `git log --since="${windowDays} days ago" --name-only --pretty=format:"%ci" -- .`,
-        { cwd: projectDir, maxBuffer: 10 * 1024 * 1024 },
-      ).toString();
-      gitLogCache.set(cacheKey, { output: gitOutput, ts: now });
-    } catch {
-      return []; // not a git repo or git not available
-    }
-  }
-
-  // ── Step 2: Parse git log and compute churn scores ────────────────────────
-  // Map: filePath → { weightedScore, rawCount, recentCount, oldCount, lastDate }
-  type FileChurn = {
-    weightedScore: number;
-    rawCount: number;
-    recentCount: number;   // commits in first half of window
-    oldCount: number;      // commits in second half of window
-    lastDate: string | null;
-  };
-  const churnMap = new Map<string, FileChurn>();
-
-  const halfWindowMs = (windowDays / 2) * 24 * 60 * 60 * 1000;
-  let currentDate = '';
-
-  for (const line of gitOutput.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    // Detect date line (ISO format from %ci: "YYYY-MM-DD HH:MM:SS +ZZZZ")
-    // Full-format match prevents dated filenames like "2026-01-01-notes.md" from
-    // being misidentified as commit timestamps and poisoning subsequent churn scores.
-    if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{4}$/.test(trimmed)) {
-      currentDate = trimmed.slice(0, 10); // YYYY-MM-DD
-      continue;
-    }
-    // File path line
-    if (currentDate && trimmed && !trimmed.startsWith('diff')) {
-      const filePath = trimmed;
-      const commitDate = new Date(currentDate).getTime();
-      const ageMs = now - commitDate;
-      const ageDays = ageMs / (24 * 60 * 60 * 1000);
-      // Exponential decay: weight = 2^(-ageDays/halfLife)
-      const weight = Math.pow(2, -ageDays / HALF_LIFE_DAYS);
-
-      if (!churnMap.has(filePath)) {
-        churnMap.set(filePath, { weightedScore: 0, rawCount: 0, recentCount: 0, oldCount: 0, lastDate: null });
-      }
-      const entry = churnMap.get(filePath)!;
-      entry.weightedScore += weight;
-      entry.rawCount += 1;
-      if (!entry.lastDate || currentDate > entry.lastDate) entry.lastDate = currentDate;
-      // Recent vs old split for trend
-      if (ageMs <= halfWindowMs) {
-        entry.recentCount += 1;
-      } else {
-        entry.oldCount += 1;
-      }
-    }
-  }
-
-  // ── 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,
-           COALESCE(d.deg, 0) as degree
-    FROM nodes n
-    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
-  `).all() as { id: string; name: string; file_path: string; label: string; community_id: number | null; degree: number }[];
-
-  // ── Step 4: Join churn + centrality ──────────────────────────────────────
-  const results: HotspotResult[] = [];
-
-  for (const node of fileNodes) {
-    // Try to match by relative file path
-    const relPath = node.file_path
-      .replace(projectDir + '/', '')
-      .replace(projectDir + '\\', '');
-    const churn = churnMap.get(relPath) ?? churnMap.get(node.file_path);
-    if (!churn || churn.rawCount < minCommits) continue;
-
-    const centralityScore = Math.log1p(node.degree); // log scale to normalize
-
-    // Trend: accelerating if recent half > 1.5x old half (normalized by window)
-    let trend: 'accelerating' | 'stable' | 'cooling' = 'stable';
-    if (churn.oldCount === 0 && churn.recentCount > 0) {
-      trend = 'accelerating';
-    } else if (churn.recentCount > 0 && churn.oldCount > 0) {
-      const ratio = churn.recentCount / churn.oldCount;
-      if (ratio > 1.5) trend = 'accelerating';
-      else if (ratio < 0.5) trend = 'cooling';
-    } else if (churn.recentCount === 0 && churn.oldCount > 0) {
-      trend = 'cooling';
-    }
-
-    results.push({
-      nodeId: node.id,
-      nodeName: node.name,
-      filePath: node.file_path,
-      label: node.label,
-      communityId: node.community_id,
-      churnScore: churn.weightedScore,
-      rawCommitCount: churn.rawCount,
-      centralityScore,
-      hotspotScore: churn.weightedScore * centralityScore,
-      trend,
-      lastCommitDate: churn.lastDate,
-    });
-  }
-
-  // Sort by hotspotScore descending, return top N
-  return results
-    .sort((a, b) => b.hotspotScore - a.hotspotScore)
-    .slice(0, limit);
-}
-
-/**
- * Format hotspot results as structured text with file:line hints for LLM navigation.
- *
- * @param hotspots - Results from computeHotspots()
- * @returns structured text suitable for LLM consumption
- */
-export function formatHotspots(hotspots: HotspotResult[]): string {
-  if (hotspots.length === 0) {
-    return 'hotspots: none found (insufficient git history or no matching file nodes)\n';
-  }
-
-  const trendMark = (t: HotspotResult['trend']): string => {
-    if (t === 'accelerating') return '+';
-    if (t === 'cooling') return '-';
-    return '~';
-  };
-
-  const lines: string[] = [
-    `hotspots: ${hotspots.length} high-risk files (churn x centrality)`,
-    '',
-  ];
-
-  hotspots.forEach((h, i) => {
-    lines.push(`[${i + 1}] ${h.nodeName}  trend:${trendMark(h.trend)}`);
-    lines.push(`  file: ${h.filePath}:1`);
-    lines.push(`  score: ${h.hotspotScore.toFixed(2)}  churn: ${h.churnScore.toFixed(2)}  centrality: ${h.centralityScore.toFixed(2)}`);
-    lines.push(`  commits: ${h.rawCommitCount}  last: ${h.lastCommitDate ?? 'unknown'}`);
-    lines.push('');
-  });
-
-  const accelerating = hotspots.filter(h => h.trend === 'accelerating').length;
-  const cooling = hotspots.filter(h => h.trend === 'cooling').length;
-  lines.push(`summary: ${accelerating} accelerating, ${cooling} cooling, ${hotspots.length - accelerating - cooling} stable`);
-
-  return lines.join('\n');
-}

package/src/graph/import-chain.ts

@@ -1,148 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export interface ImportChainOptions {
-  /** Maximum path depth. Default: 10 */
-  maxDepth?: number;
-  /** Maximum number of paths to return (prevents explosion). Default: 100 */
-  maxPaths?: number;
-}
-
-/**
- * Trace all import chains (paths) from `sourceId` to `targetId`.
- *
- * Uses frontier-based BFS with lazy edge loading: only fetches outgoing edges
- * for nodes as they are visited, avoiding loading the full edge table when
- * the graph is large.  Returns all simple paths up to `maxDepth`.
- *
- * @param db - The MonographDb instance
- * @param sourceId - Starting node id
- * @param targetId - Destination node id
- * @param options - Optional tuning parameters
- * @returns Array of paths; each path is an ordered array of node ids from source to target.
- */
-export function traceImportChain(
-  db: MonographDb,
-  sourceId: string,
-  targetId: string,
-  options: ImportChainOptions = {},
-): string[][] {
-  const { maxDepth = 10, maxPaths = 100 } = options;
-
-  // Quick existence check — avoids loading any edge data for invalid IDs
-  const exists = db.prepare('SELECT 1 FROM nodes WHERE id = ? LIMIT 1');
-  if (!exists.get(sourceId) || !exists.get(targetId)) return [];
-  if (sourceId === targetId) return [[sourceId]];
-
-  // Lazy adjacency cache: only loaded for nodes we actually visit
-  const adjCache = new Map<string, string[]>();
-  const edgeStmt = db.prepare(
-    'SELECT target_id FROM edges WHERE source_id = ? AND source_id != target_id',
-  );
-
-  function getNeighbors(nodeId: string): string[] {
-    let neighbors = adjCache.get(nodeId);
-    if (neighbors === undefined) {
-      neighbors = (edgeStmt.all(nodeId) as { target_id: string }[]).map(r => r.target_id);
-      adjCache.set(nodeId, neighbors);
-    }
-    return neighbors;
-  }
-
-  // DFS with path tracking (iterative to avoid stack overflow on deep graphs)
-  const results: string[][] = [];
-  const stack: Array<{ node: string; path: string[]; visited: Set<string> }> = [
-    { node: sourceId, path: [sourceId], visited: new Set([sourceId]) },
-  ];
-
-  while (stack.length > 0 && results.length < maxPaths) {
-    const { node, path, visited } = stack.pop()!;
-    // depth = path.length - 1 (edges from source). Stop exploring when at the limit;
-    // the target would require one more edge which would exceed maxDepth.
-    if (path.length - 1 >= maxDepth) continue;
-
-    for (const neighbor of getNeighbors(node)) {
-      if (visited.has(neighbor)) continue;
-      if (neighbor === targetId) {
-        results.push([...path, neighbor]);
-        if (results.length >= maxPaths) break;
-      } else {
-        stack.push({
-          node: neighbor,
-          path: [...path, neighbor],
-          visited: new Set([...visited, neighbor]),
-        });
-      }
-    }
-  }
-
-  return results;
-}
-
-// ---------------------------------------------------------------------------
-// Structured text formatter for LLM consumption
-// ---------------------------------------------------------------------------
-
-/**
- * Format import-chain paths as structured text.
- *
- * Resolves node IDs to human-readable names (name + file_path) for LLM
- * context injection.  Each path is printed as an arrow chain with file:line
- * hints where available.
- *
- * @param db - The MonographDb instance (used for name resolution)
- * @param paths - Result of traceImportChain()
- * @param sourceId - Source node id (for summary line)
- * @param targetId - Target node id (for summary line)
- * @returns Structured text string
- */
-export function formatImportChain(
-  db: MonographDb,
-  paths: string[][],
-  sourceId: string,
-  targetId: string,
-): string {
-  if (paths.length === 0) {
-    return `Import chain: no path found from ${sourceId} to ${targetId}.`;
-  }
-
-  // Batch-resolve all node IDs in the result set
-  const allIds = [...new Set(paths.flat())];
-  const placeholders = allIds.map(() => '?').join(',');
-  const nodeRows = db
-    .prepare(
-      `SELECT id, name, file_path, start_line FROM nodes WHERE id IN (${placeholders})`,
-    )
-    .all(...allIds) as {
-    id: string;
-    name: string;
-    file_path: string | null;
-    start_line: number | null;
-  }[];
-
-  const nodeInfo = new Map<string, { name: string; loc: string }>();
-  for (const row of nodeRows) {
-    const loc =
-      row.file_path != null
-        ? row.start_line != null
-          ? `${row.file_path}:${row.start_line}`
-          : row.file_path
-        : row.id;
-    nodeInfo.set(row.id, { name: row.name ?? row.id, loc });
-  }
-
-  const lines: string[] = [
-    `Import chain: ${paths.length} path${paths.length === 1 ? '' : 's'} from ${nodeInfo.get(sourceId)?.name ?? sourceId} to ${nodeInfo.get(targetId)?.name ?? targetId}`,
-    '',
-  ];
-
-  for (let i = 0; i < paths.length; i++) {
-    lines.push(`Path ${i + 1} (${paths[i].length} node${paths[i].length === 1 ? '' : 's'}):`);
-    for (const id of paths[i]) {
-      const info = nodeInfo.get(id);
-      lines.push(`  ${info?.name ?? id} — ${info?.loc ?? id}`);
-    }
-    if (i < paths.length - 1) lines.push('');
-  }
-
-  return lines.join('\n');
-}

package/src/graph/loader.ts

@@ -1,44 +0,0 @@
-import Graph from 'graphology';
-import type { MonographEdge } from '../types.js';
-
-export function loadGraphFromEdges(edges: MonographEdge[]): Graph {
-  const graph = new Graph({ multi: true, type: 'directed' });
-  for (const edge of edges) {
-    if (!graph.hasNode(edge.sourceId)) graph.addNode(edge.sourceId);
-    if (!graph.hasNode(edge.targetId)) graph.addNode(edge.targetId);
-    try {
-      graph.addEdge(edge.sourceId, edge.targetId, {
-        id: edge.id, relation: edge.relation,
-        confidence: edge.confidence, confidenceScore: edge.confidenceScore,
-      });
-    } catch { /* duplicate edge */ }
-  }
-  return graph;
-}
-
-export function loadGraphFromDb(db: import('../storage/db.js').MonographDb): Graph {
-  const nodes = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
-  // Explicitly select only the columns used here — avoids fetching reason/evidence blobs
-  const edges = db.prepare(
-    'SELECT id, source_id, target_id, relation, confidence, confidence_score FROM edges'
-  ).all() as {
-    id: string; source_id: string; target_id: string; relation: string;
-    confidence: string; confidence_score: number;
-  }[];
-
-  const graph = new Graph({ multi: true, type: 'directed' });
-  // Seed known nodes first; edges below may reference node ids not in the nodes table
-  // (defensive: addNode is a no-op guard here, has-check avoided to reduce overhead)
-  for (const n of nodes) graph.mergeNode(n.id);
-  for (const e of edges) {
-    graph.mergeNode(e.source_id);
-    graph.mergeNode(e.target_id);
-    try {
-      graph.addEdge(e.source_id, e.target_id, {
-        id: e.id, relation: e.relation,
-        confidence: e.confidence, confidenceScore: e.confidence_score,
-      });
-    } catch { /* skip duplicate edges */ }
-  }
-  return graph;
-}