@monoes/monograph 1.1.0 → 1.2.1

package/src/graph/dependency-closure.ts

@@ -0,0 +1,126 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface DepClosureResult {
+  nodeId: string;
+  name: string;
+  filePath: string | null;
+  directDeps: string[];           // IDs of directly imported nodes
+  transitiveDeps: string[];       // IDs of all transitively imported nodes
+  depDepth: number;               // max dependency chain depth
+  unusedTransitiveDeps: string[]; // transitive deps that are never directly referenced by any file in the project
+}
+
+export interface DepClosureReport {
+  nodes: DepClosureResult[];
+  avgDepDepth: number;
+  maxDepDepth: number;
+  deepDependencyFiles: DepClosureResult[];   // files with depDepth > 5
+}
+
+const SQLITE_VAR_LIMIT = 200; // safe batch size for IN clauses
+
+export function computeDependencyClosure(db: MonographDb, maxNodes = 100): DepClosureReport {
+  // Get File nodes sorted by degree (most connected first)
+  const fileNodes = (db.prepare(`
+    SELECT n.id, n.name, n.file_path,
+      (SELECT COUNT(*) FROM edges e WHERE e.source_id = n.id OR e.target_id = n.id) AS degree
+    FROM nodes n
+    WHERE n.label = 'File'
+    ORDER BY degree DESC
+    LIMIT ?
+  `).all(maxNodes) as Array<{ id: string; name: string; file_path: string | null; degree: number }>);
+
+  // Build a set of all file_paths that have any IMPORTS edge pointing to them (are imported by someone)
+  const importedFilePaths = new Set<string>(
+    (db.prepare(`
+      SELECT DISTINCT n.file_path
+      FROM edges e
+      JOIN nodes n ON n.id = e.target_id
+      WHERE e.relation = 'IMPORTS' AND n.file_path IS NOT NULL
+    `).all() as Array<{ file_path: string }>).map(r => r.file_path)
+  );
+
+  // Hoist prepared statement outside the per-node BFS loop to avoid recompiling
+  // on every iteration (N×maxNodes calls previously).
+  const edgeStmt = db.prepare(
+    `SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`,
+  );
+
+  const results: DepClosureResult[] = [];
+
+  for (const fileNode of fileNodes) {
+    // BFS forward (following IMPORTS edges from this node)
+    const directDeps: string[] = [];
+    const transitiveDeps: string[] = [];
+    const visited = new Set<string>([fileNode.id]);
+    let frontier = [fileNode.id];
+    let depth = 0;
+    let maxDepth = 0;
+
+    while (frontier.length > 0) {
+      depth++;
+      const next: string[] = [];
+      for (const id of frontier) {
+        const edges = edgeStmt.all(id) as Array<{ target_id: string }>;
+        for (const e of edges) {
+          if (!visited.has(e.target_id)) {
+            visited.add(e.target_id);
+            next.push(e.target_id);
+            if (depth === 1) {
+              directDeps.push(e.target_id);
+            } else {
+              transitiveDeps.push(e.target_id);
+            }
+            maxDepth = depth;
+          }
+        }
+      }
+      frontier = next;
+    }
+
+    // Batch-resolve file_paths for all transitive deps in one chunked SQL query
+    // instead of one SELECT per dep (N+1 → O(deps/CHUNK) queries).
+    const depFilePathMap = new Map<string, string | null>();
+    for (let i = 0; i < transitiveDeps.length; i += SQLITE_VAR_LIMIT) {
+      const chunk = transitiveDeps.slice(i, i + SQLITE_VAR_LIMIT);
+      const ph = chunk.map(() => '?').join(',');
+      const rows = db
+        .prepare(`SELECT id, file_path FROM nodes WHERE id IN (${ph})`)
+        .all(...chunk) as Array<{ id: string; file_path: string | null }>;
+      for (const row of rows) depFilePathMap.set(row.id, row.file_path);
+    }
+
+    // unusedTransitiveDeps: transitive deps whose file_path is NOT in importedFilePaths
+    const unusedTransitiveDeps = transitiveDeps.filter(depId => {
+      const fp = depFilePathMap.get(depId);
+      if (!fp) return false;
+      return !importedFilePaths.has(fp);
+    });
+
+    results.push({
+      nodeId: fileNode.id,
+      name: fileNode.name,
+      filePath: fileNode.file_path,
+      directDeps,
+      transitiveDeps,
+      depDepth: maxDepth,
+      unusedTransitiveDeps,
+    });
+  }
+
+  // Sort by depDepth descending
+  results.sort((a, b) => b.depDepth - a.depDepth);
+
+  const avgDepDepth = results.length > 0
+    ? results.reduce((sum, r) => sum + r.depDepth, 0) / results.length
+    : 0;
+  const maxDepDepth = results.length > 0 ? results[0].depDepth : 0;
+  const deepDependencyFiles = results.filter(r => r.depDepth > 5);
+
+  return {
+    nodes: results,
+    avgDepDepth: Math.round(avgDepDepth * 100) / 100,
+    maxDepDepth,
+    deepDependencyFiles,
+  };
+}

package/src/graph/dfs.ts

@@ -0,0 +1,118 @@
+export interface DfsNode {
+  id: string;
+  depth: number;
+}
+
+export interface DfsOptions {
+  maxDepth?: number;
+}
+
+export interface DfsResult {
+  visited: DfsNode[];
+  maxDepth: number;
+  nodeCount: number;
+}
+
+export function dfsTraversal(
+  startId: string,
+  adjacency: Map<string, string[]>,
+  visitor: (node: DfsNode) => void,
+  options: DfsOptions = {},
+): void {
+  if (!adjacency.has(startId)) return;
+
+  const { maxDepth = Infinity } = options;
+  const visited = new Set<string>();
+  const stack: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+
+  while (stack.length > 0) {
+    const { id, depth } = stack.pop()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+
+    visitor({ id, depth });
+
+    if (depth < maxDepth) {
+      const neighbors = adjacency.get(id) ?? [];
+      // Push in reverse order so left-most neighbor is processed first (DFS left-to-right order)
+      for (let i = neighbors.length - 1; i >= 0; i--) {
+        const neighbor = neighbors[i]!;
+        if (!visited.has(neighbor)) {
+          stack.push({ id: neighbor, depth: depth + 1 });
+        }
+      }
+    }
+  }
+}
+
+/** Collect all reachable nodes from startId via DFS, returning structured result. */
+export function dfsCollect(
+  startId: string,
+  adjacency: Map<string, string[]>,
+  options: DfsOptions = {},
+): DfsResult {
+  const visited: DfsNode[] = [];
+  let maxReachedDepth = 0;
+  dfsTraversal(startId, adjacency, (node) => {
+    visited.push(node);
+    if (node.depth > maxReachedDepth) maxReachedDepth = node.depth;
+  }, options);
+  return { visited, maxDepth: maxReachedDepth, nodeCount: visited.length };
+}
+
+/** BFS level-order traversal — useful when shortest-path distance matters more than DFS order. */
+export function bfsTraversal(
+  startId: string,
+  adjacency: Map<string, string[]>,
+  visitor: (node: DfsNode) => void,
+  options: DfsOptions = {},
+): void {
+  if (!adjacency.has(startId)) return;
+
+  const { maxDepth = Infinity } = options;
+  const visited = new Set<string>([startId]);
+  const queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+    visitor({ id, depth });
+
+    if (depth < maxDepth) {
+      const neighbors = adjacency.get(id) ?? [];
+      for (let i = 0; i < neighbors.length; i++) {
+        const neighbor = neighbors[i]!;
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          queue.push({ id: neighbor, depth: depth + 1 });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Format a DfsResult as structured text for LLM consumption.
+ * Groups nodes by depth level for easy reading.
+ */
+export function formatDfsResult(result: DfsResult, startId: string): string {
+  if (result.nodeCount === 0) return `No nodes reachable from "${startId}".`;
+
+  const byDepth = new Map<number, string[]>();
+  for (const node of result.visited) {
+    let bucket = byDepth.get(node.depth);
+    if (!bucket) { bucket = []; byDepth.set(node.depth, bucket); }
+    bucket.push(node.id);
+  }
+
+  const lines: string[] = [
+    `DFS from "${startId}": ${result.nodeCount} nodes, max depth ${result.maxDepth}`,
+    '',
+  ];
+  // Iterate in depth order
+  const depths = Array.from(byDepth.keys()).sort((a, b) => a - b);
+  for (const depth of depths) {
+    const ids = byDepth.get(depth)!;
+    lines.push(`  depth ${depth}: ${ids.join(', ')}`);
+  }
+  return lines.join('\n');
+}

package/src/graph/diff.ts

@@ -12,23 +12,50 @@ export interface GraphDiff {
   newEdges: MonographEdge[];
   removedEdges: MonographEdge[];
   modifiedNodes: Array<{ before: MonographNode; after: MonographNode }>;
+  /** Human-readable summary, e.g. "3 new nodes, 5 new edges, 1 node removed". */
+  summary: string;
+}
+
+function buildDiffSummary(
+  newNodes: MonographNode[],
+  removedNodes: MonographNode[],
+  newEdges: MonographEdge[],
+  removedEdges: MonographEdge[],
+  modifiedNodes: Array<{ before: MonographNode; after: MonographNode }>,
+): string {
+  const parts: string[] = [];
+  if (newNodes.length > 0) parts.push(`${newNodes.length} new node${newNodes.length !== 1 ? 's' : ''}`);
+  if (newEdges.length > 0) parts.push(`${newEdges.length} new edge${newEdges.length !== 1 ? 's' : ''}`);
+  if (removedNodes.length > 0) parts.push(`${removedNodes.length} node${removedNodes.length !== 1 ? 's' : ''} removed`);
+  if (removedEdges.length > 0) parts.push(`${removedEdges.length} edge${removedEdges.length !== 1 ? 's' : ''} removed`);
+  if (modifiedNodes.length > 0) parts.push(`${modifiedNodes.length} node${modifiedNodes.length !== 1 ? 's' : ''} modified`);
+  return parts.length > 0 ? parts.join(', ') : 'no changes';
 }
 
 export function diffSnapshots(before: GraphSnapshot, after: GraphSnapshot): GraphDiff {
   const beforeNodeIds = new Map(before.nodes.map(n => [n.id, n]));
   const afterNodeIds = new Map(after.nodes.map(n => [n.id, n]));
-  const beforeEdgeIds = new Set(before.edges.map(e => e.id));
-  const afterEdgeIds = new Set(after.edges.map(e => e.id));
+  // Key edges by sourceId+relation+targetId — stable across snapshots regardless of synthetic id
+  const edgeKey = (e: MonographEdge) => `${e.sourceId}|${e.relation}|${e.targetId}`;
+  const beforeEdgeKeys = new Set(before.edges.map(edgeKey));
+  const afterEdgeKeys = new Set(after.edges.map(edgeKey));
+
+  const newNodes = after.nodes.filter(n => !beforeNodeIds.has(n.id));
+  const removedNodes = before.nodes.filter(n => !afterNodeIds.has(n.id));
+  const newEdges = after.edges.filter(e => !beforeEdgeKeys.has(edgeKey(e)));
+  const removedEdges = before.edges.filter(e => !afterEdgeKeys.has(edgeKey(e)));
+  const modifiedNodes = after.nodes
+    .filter(n => beforeNodeIds.has(n.id))
+    .filter(n => JSON.stringify(n) !== JSON.stringify(beforeNodeIds.get(n.id)))
+    .map(n => ({ before: beforeNodeIds.get(n.id)!, after: n }));
 
   return {
-    newNodes: after.nodes.filter(n => !beforeNodeIds.has(n.id)),
-    removedNodes: before.nodes.filter(n => !afterNodeIds.has(n.id)),
-    newEdges: after.edges.filter(e => !beforeEdgeIds.has(e.id)),
-    removedEdges: before.edges.filter(e => !afterEdgeIds.has(e.id)),
-    modifiedNodes: after.nodes
-      .filter(n => beforeNodeIds.has(n.id))
-      .filter(n => JSON.stringify(n) !== JSON.stringify(beforeNodeIds.get(n.id)))
-      .map(n => ({ before: beforeNodeIds.get(n.id)!, after: n })),
+    newNodes,
+    removedNodes,
+    newEdges,
+    removedEdges,
+    modifiedNodes,
+    summary: buildDiffSummary(newNodes, removedNodes, newEdges, removedEdges, modifiedNodes),
   };
 }
 

package/src/graph/duplication-stats.ts

@@ -0,0 +1,79 @@
+export interface DuplicationStats {
+  totalFiles: number;
+  filesWithClones: number;
+  totalLines: number;
+  duplicatedLines: number;
+  totalTokens: number;
+  duplicatedTokens: number;
+  cloneGroups: number;
+  cloneInstances: number;
+  duplicationPct: number;
+}
+
+export interface CloneGroupInput {
+  instances: Array<{
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    tokenCount?: number;
+  }>;
+}
+
+export function computeDuplicationStats(
+  groups: CloneGroupInput[],
+  allFilePaths: string[],
+  totalLines: number,
+  totalTokens: number,
+): DuplicationStats {
+  // Per-file deduplicated line sets to avoid double-counting
+  const fileLines = new Map<string, Set<number>>();
+  let cloneInstances = 0;
+
+  for (const group of groups) {
+    for (const inst of group.instances) {
+      cloneInstances++;
+      if (!fileLines.has(inst.filePath)) fileLines.set(inst.filePath, new Set());
+      const set = fileLines.get(inst.filePath)!;
+      for (let l = inst.startLine; l <= inst.endLine; l++) set.add(l);
+    }
+  }
+
+  const filesWithClones = fileLines.size;
+  // Single-pass line count — avoids spread allocation over all file Sets
+  let duplicatedLines = 0;
+  for (const set of fileLines.values()) duplicatedLines += set.size;
+  // Single-pass token sum — avoids nested reduce and intermediate arrays
+  let rawTokens = 0;
+  for (const group of groups) {
+    for (const inst of group.instances) rawTokens += inst.tokenCount ?? 0;
+  }
+  const duplicatedTokens = Math.min(totalTokens, rawTokens);
+
+  return {
+    totalFiles: allFilePaths.length,
+    filesWithClones,
+    totalLines,
+    duplicatedLines,
+    totalTokens,
+    duplicatedTokens,
+    cloneGroups: groups.length,
+    cloneInstances,
+    duplicationPct: totalLines > 0 ? (duplicatedLines / totalLines) * 100 : 0,
+  };
+}
+
+export function formatDuplicationStats(stats: DuplicationStats): string {
+  const pct = stats.duplicationPct;
+  const grade = pct < 5 ? 'A' : pct < 10 ? 'B' : pct < 20 ? 'C' : pct < 30 ? 'D' : 'F';
+  const tokenPct = stats.totalTokens > 0
+    ? ((stats.duplicatedTokens / stats.totalTokens) * 100).toFixed(1)
+    : '0.0';
+  return [
+    `Duplication grade: ${grade} (${pct.toFixed(1)}% duplicated lines)`,
+    `Clone groups:      ${stats.cloneGroups}`,
+    `Clone instances:   ${stats.cloneInstances}`,
+    `Files with clones: ${stats.filesWithClones} / ${stats.totalFiles}`,
+    `Duplicated lines:  ${stats.duplicatedLines} / ${stats.totalLines} (${pct.toFixed(1)}%)`,
+    `Duplicated tokens: ${stats.duplicatedTokens} / ${stats.totalTokens} (${tokenPct}%)`,
+  ].join('\n');
+}

package/src/graph/edge-filter.ts

@@ -0,0 +1,117 @@
+import type { MonographEdge, EdgeRelation, EdgeConfidence } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+// ── Filter options ─────────────────────────────────────────────────────────────
+
+export interface EdgeFilterOptions {
+  /** Only return edges whose relation matches one of these values. */
+  relations?: EdgeRelation[];
+  /** Only return edges whose confidence label matches one of these values. */
+  confidences?: EdgeConfidence[];
+  /** Only return edges with a confidence_score >= this value (0–1). */
+  minConfidenceScore?: number;
+  /** Only return edges with a confidence_score <= this value (0–1). */
+  maxConfidenceScore?: number;
+}
+
+// ── DB-backed filter ───────────────────────────────────────────────────────────
+
+/**
+ * Query edges from a MonographDb with optional relation / confidence filters.
+ * All filters are combined with AND.
+ */
+export function filterEdges(
+  db: MonographDb,
+  options: EdgeFilterOptions = {},
+): MonographEdge[] {
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (options.relations && options.relations.length > 0) {
+    const ph = options.relations.map(() => '?').join(',');
+    conditions.push(`relation IN (${ph})`);
+    params.push(...options.relations);
+  }
+
+  if (options.confidences && options.confidences.length > 0) {
+    const ph = options.confidences.map(() => '?').join(',');
+    conditions.push(`confidence IN (${ph})`);
+    params.push(...options.confidences);
+  }
+
+  if (options.minConfidenceScore !== undefined) {
+    conditions.push('confidence_score >= ?');
+    params.push(options.minConfidenceScore);
+  }
+
+  if (options.maxConfidenceScore !== undefined) {
+    conditions.push('confidence_score <= ?');
+    params.push(options.maxConfidenceScore);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  const sql = `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason, evidence
+               FROM edges ${where}`;
+
+  const rows = db.prepare(sql).all(...params) as {
+    id: string;
+    source_id: string;
+    target_id: string;
+    relation: string;
+    confidence: string;
+    confidence_score: number;
+    reason: string | null;
+    evidence: string | null;
+  }[];
+
+  return rows.map(r => ({
+    id: r.id,
+    sourceId: r.source_id,
+    targetId: r.target_id,
+    relation: r.relation as EdgeRelation,
+    confidence: r.confidence as EdgeConfidence,
+    confidenceScore: r.confidence_score,
+    reason: r.reason ?? undefined,
+  }));
+}
+
+// ── In-memory filter ───────────────────────────────────────────────────────────
+
+/**
+ * Filter an already-loaded array of edges in memory.
+ * Useful when the caller already has edges and does not need a DB round-trip.
+ */
+export function filterEdgesInMemory(
+  edges: MonographEdge[],
+  options: EdgeFilterOptions = {},
+): MonographEdge[] {
+  // Convert arrays to Sets once before the loop for O(1) membership checks
+  const relationSet = options.relations && options.relations.length > 0
+    ? new Set(options.relations) : null;
+  const confidenceSet = options.confidences && options.confidences.length > 0
+    ? new Set(options.confidences) : null;
+  const minScore = options.minConfidenceScore;
+  const maxScore = options.maxConfidenceScore;
+
+  return edges.filter(e => {
+    if (relationSet && !relationSet.has(e.relation)) return false;
+    if (confidenceSet && !confidenceSet.has(e.confidence)) return false;
+    if (minScore !== undefined && e.confidenceScore < minScore) return false;
+    if (maxScore !== undefined && e.confidenceScore > maxScore) return false;
+    return true;
+  });
+}
+
+// ── Formatting ─────────────────────────────────────────────────────────────────
+
+/** Format a list of filtered edges as structured text for LLM consumption. */
+export function formatFilteredEdges(edges: MonographEdge[]): string {
+  if (edges.length === 0) return 'No edges match the filter.';
+  const lines: string[] = [`Filtered edges (${edges.length}):`];
+  for (const e of edges) {
+    const score = e.confidenceScore !== undefined ? ` [${e.confidenceScore.toFixed(2)}]` : '';
+    const reason = e.reason ? ` — ${e.reason}` : '';
+    lines.push(`  ${e.sourceId} -[${e.relation}/${e.confidence}${score}]-> ${e.targetId}${reason}`);
+  }
+  return lines.join('\n');
+}

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 })) };
+}