@monoes/monograph 1.0.0 → 1.2.0

package/src/graph/explain.ts

@@ -0,0 +1,133 @@
+export interface RuleDef {
+  id: string;               // e.g. 'god-node', 'unreachable-file', 'circular-deps'
+  name?: string;            // human readable
+  title?: string;           // display title (alias for name)
+  description: string;      // what it detects
+  rationale?: string;       // why it matters
+  remediation?: string;     // how to fix
+  severity?: 'error' | 'warning' | 'info';
+  docsUrl?: string;
+  docs?: string;            // alias for docsUrl
+}
+
+export const CHECK_RULES: RuleDef[] = [
+  {
+    id: 'god-node',
+    name: 'God Node',
+    description: 'A file or class with too many incoming dependencies (high fan-in).',
+    rationale: 'God nodes create fragile coupling — any change ripples across many files.',
+    remediation: 'Split into smaller, focused modules. Extract shared logic into utility files.',
+    severity: 'warning',
+  },
+  {
+    id: 'unreachable-file',
+    name: 'Unreachable File',
+    description: 'A file that cannot be reached from any runtime or test entry point.',
+    rationale: 'Unreachable files are dead code — they increase build size and maintenance burden.',
+    remediation: 'Delete or connect the file to a live import chain. Check if it was accidentally disconnected.',
+    severity: 'warning',
+  },
+  {
+    id: 'circular-deps',
+    name: 'Circular Dependencies',
+    description: 'Files that form an import cycle.',
+    rationale: 'Circular imports complicate initialization order, testing, and refactoring.',
+    remediation: 'Extract shared types/utilities to a new file that neither participant imports from.',
+    severity: 'error',
+  },
+  {
+    id: 'high-coupling',
+    name: 'High Coupling Concentration',
+    description: 'A disproportionate share of imports targeting a small number of files.',
+    rationale: 'Over-coupled files become change bottlenecks — every feature touches them.',
+    remediation: 'Break up the central file using the facade pattern or dependency inversion.',
+    severity: 'warning',
+  },
+  {
+    id: 'isolated-node',
+    name: 'Isolated Node',
+    description: 'A file with no imports and no importers.',
+    rationale: 'Isolated files have no connection to the codebase — likely dead or forgotten.',
+    remediation: 'Either connect it to the dependency graph or delete it.',
+    severity: 'info',
+  },
+  {
+    id: 'boundary-violation',
+    name: 'Boundary Zone Violation',
+    description: 'An import that crosses a forbidden architectural boundary.',
+    rationale: 'Boundary violations break layer isolation and make the architecture drift over time.',
+    remediation: 'Introduce an anti-corruption layer or move the logic to the correct zone.',
+    severity: 'error',
+  },
+  {
+    id: 'low-cohesion',
+    name: 'Low Community Cohesion',
+    description: 'A module community with a low ratio of internal to possible edges.',
+    rationale: 'Low cohesion means the community is an arbitrary grouping, not a real module.',
+    remediation: 'Re-organize files so that related functionality is co-located.',
+    severity: 'info',
+  },
+];
+
+export function explainRule(ruleId: string): RuleDef | undefined {
+  return CHECK_RULES.find(r => r.id === ruleId);
+}
+
+export function listRules(): RuleDef[] {
+  return CHECK_RULES;
+}
+
+export function getRulesByFinding(findingTitle: string): RuleDef[] {
+  const lower = findingTitle.toLowerCase();
+  return CHECK_RULES.filter(r => lower.includes(r.id) || (r.name && lower.includes(r.name.toLowerCase())));
+}
+
+// ── Round 10: health + duplication rule catalogs ──────────────────────────────
+
+export interface RuleGuide {
+  rule: string;
+  checklist: string[];
+  relatedRules: string[];
+  antiPatterns: string[];
+  examples: string[];
+}
+
+export const HEALTH_RULES: RuleDef[] = [
+  { id: 'health/cyclomatic', title: 'High Cyclomatic Complexity', description: 'Function has too many independent execution paths', docs: 'https://en.wikipedia.org/wiki/Cyclomatic_complexity' },
+  { id: 'health/cognitive', title: 'High Cognitive Complexity', description: 'Function is hard to understand for human readers', docs: 'https://www.sonarsource.com/docs/CognitiveComplexity.pdf' },
+  { id: 'health/crap', title: 'High CRAP Score', description: 'Function has high complexity and low test coverage', docs: '' },
+  { id: 'health/maintainability', title: 'Low Maintainability Index', description: 'File has a low maintainability index score', docs: '' },
+  { id: 'health/large-function', title: 'Large Function', description: 'Function exceeds the maximum allowed lines of code', docs: '' },
+];
+
+export const DUPES_RULES: RuleDef[] = [
+  { id: 'duplication/clone', title: 'Code Duplication', description: 'Code block is duplicated across multiple files', docs: '' },
+];
+
+export function getRuleGuide(ruleId: string): RuleGuide | null {
+  const guides: Record<string, RuleGuide> = {
+    'health/cyclomatic': {
+      rule: 'health/cyclomatic',
+      checklist: ['Extract complex conditionals into named predicates', 'Split large functions into smaller helpers', 'Use early returns to reduce nesting'],
+      relatedRules: ['health/cognitive', 'health/crap'],
+      antiPatterns: ['Deeply nested if/else chains', 'Long switch statements without extraction'],
+      examples: ['Extract `isEligible()` from a 15-branch function'],
+    },
+    'health/crap': {
+      rule: 'health/crap',
+      checklist: ['Add tests to increase coverage', 'Refactor to reduce cyclomatic complexity', 'Break into smaller testable units'],
+      relatedRules: ['health/cyclomatic', 'health/cognitive'],
+      antiPatterns: ['Complex functions with zero test coverage'],
+      examples: [],
+    },
+  };
+  return guides[ruleId] ?? null;
+}
+
+export function healthMeta(): Record<string, unknown> {
+  return { version: 1, rules: HEALTH_RULES.map(r => ({ id: r.id, title: r.title, description: r.description })) };
+}
+
+export function dupesMeta(): Record<string, unknown> {
+  return { version: 1, rules: DUPES_RULES.map(r => ({ id: r.id, title: r.title, description: r.description })) };
+}

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

@@ -0,0 +1,81 @@
+// 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

@@ -0,0 +1,152 @@
+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 properties LIKE '%\"unreachable\"%'"
+  ).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) ────────────────────────────────────────────────
+  const degreesRows = db.prepare(`
+    SELECT source_id as node_id, COUNT(*) as deg FROM edges GROUP BY source_id
+    UNION ALL
+    SELECT target_id as node_id, COUNT(*) as deg FROM edges GROUP BY target_id
+  `).all() as { node_id: string; deg: number }[];
+
+  // Sum degrees per node
+  const degMap = new Map<string, number>();
+  for (const row of degreesRows) {
+    degMap.set(row.node_id, (degMap.get(row.node_id) ?? 0) + row.deg);
+  }
+  const degrees = [...degMap.values()].sort((a, b) => a - b);
+  const p95Index = Math.floor(degrees.length * 0.95);
+  const p95Degree = degrees[p95Index] ?? 0;
+
+  const godNodeCount = p95Degree > 0
+    ? [...degMap.values()].filter(d => d > 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) ───────────────────────
+  // Files where properties contain a churnScore > 0.5
+  // We detect presence of churnScore via LIKE and then evaluate in JS
+  const hotspotCandidates = db.prepare(
+    "SELECT properties FROM nodes WHERE label = 'File' AND properties LIKE '%churnScore%'"
+  ).all() as { properties: string | null }[];
+
+  let hotspotCount = 0;
+  for (const row of hotspotCandidates) {
+    if (!row.properties) continue;
+    try {
+      const props = JSON.parse(row.properties) as Record<string, unknown>;
+      const churn = props['churnScore'];
+      if (typeof churn === 'number' && churn > 0.5) hotspotCount++;
+    } catch {
+      // ignore malformed JSON
+    }
+  }
+
+  // ── 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 };
+}

package/src/graph/hotspots.ts

@@ -0,0 +1,166 @@
+import { execSync } from 'child_process';
+import type Database from 'better-sqlite3';
+
+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 ────────────────────────────────────────
+  // Format: ISO-date\tfile-path (one per changed file per commit)
+  let gitOutput = '';
+  try {
+    gitOutput = execSync(
+      `git log --since="${windowDays} days ago" --name-only --pretty=format:"%ci" -- .`,
+      { cwd: projectDir, maxBuffer: 10 * 1024 * 1024 },
+    ).toString();
+  } 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,
+           COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) as degree
+    FROM nodes n
+    LEFT JOIN edges e1 ON e1.source_id = n.id
+    LEFT JOIN edges e2 ON e2.target_id = n.id
+    WHERE n.label = 'File' AND n.file_path IS NOT NULL
+    GROUP BY n.id
+  `).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);
+}

package/src/graph/import-chain.ts

@@ -0,0 +1,78 @@
+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 BFS/DFS with cycle detection. 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;
+
+  const nodeRows = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
+  if (nodeRows.length === 0) return [];
+
+  const nodeSet = new Set(nodeRows.map(r => r.id));
+  if (!nodeSet.has(sourceId) || !nodeSet.has(targetId)) return [];
+  if (sourceId === targetId) return [[sourceId]];
+
+  const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
+    source_id: string;
+    target_id: string;
+  }[];
+
+  // Build adjacency
+  const adj = new Map<string, string[]>();
+  for (const n of nodeSet) adj.set(n, []);
+  for (const { source_id: src, target_id: tgt } of edgeRows) {
+    if (src === tgt) continue;
+    if (!adj.has(src) || !adj.has(tgt)) continue;
+    adj.get(src)!.push(tgt);
+  }
+
+  // DFS with path tracking
+  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 adj.get(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;
+}