feat: add Mermaid output to diff-impact command

Add --format mermaid flag to diff-impact for generating ready-to-use
Mermaid flowcharts showing changed functions, transitive callers, and
blast radius in a single command.

- Enhance diffImpactData BFS to return depth-structured levels, edges,
  and newFiles detection (backward-compatible additions)
- Add diffImpactMermaid function that builds flowchart TB diagrams with
  color-coded subgraphs (green=new, orange=modified, purple=blast radius)
- Add --format option to CLI diff-impact command (text/mermaid/json)
- Add format property to MCP diff_impact tool schema
- Export diffImpactMermaid from index.js
- Add unit tests for levels/edges, new file detection, and Mermaid output
- Update llm-integration.md with PR impact graph roadmap

Impact: 6 functions changed, 5 affected

Author: github-actions[bot]

docs/llm-integration.md

@@ -55,6 +55,44 @@ Code changes → codegraph build (+ LLM enrichment) → SQLite DB with semantic
 - Returns: what changed, what's affected, risk assessment, suggested review focus areas
 - MCP tool: `review_diff <ref>` — structured review the consuming AI can relay to the user
 
+#### "Show me a visual impact graph for this PR"
+- **Foundation (implemented):** `codegraph diff-impact <base> --format mermaid -T` generates a Mermaid flowchart showing changed functions, transitive callers, and blast radius — color-coded by new/modified/blast-radius
+- **CI automation:** GitHub Action that runs on every PR:
+  1. `codegraph build .` (incremental, fast on CI cache)
+  2. `codegraph diff-impact $BASE_REF --format mermaid -T` to generate the graph
+  3. Post as a PR comment — GitHub renders Mermaid natively in markdown
+  4. Update on new pushes (edit the existing comment)
+- **LLM-enriched annotations:** Overlay the graph with semantic context:
+  - For each changed function: one-line summary of WHAT changed (from diff hunks)
+  - For each affected caller: WHY it's affected — what behavior might change downstream
+  - Risk labels per node: `low` (cosmetic / internal), `medium` (behavior change), `high` (breaking / public API)
+  - Node colors shift from green → yellow → red based on risk, replacing the static new/modified styling
+- **Diff-aware narrative:** LLM reads the diff + graph and generates a structured PR summary:
+  - "What changed and why it matters" per function
+  - Potential breaking changes and side effects (from `side_effects` metadata)
+  - Overall PR risk score (aggregate of node risks weighted by centrality)
+- **Review focus:** Prioritize reviewer attention:
+  - Rank affected files by risk × blast radius — "review this file first"
+  - Highlight critical paths: the shortest path from a changed function to a high-fan-in entry point
+  - Flag test coverage gaps for affected code (cross-reference with test file graph edges)
+- **Historical context overlay:**
+  - Annotate nodes with churn data: "this function changed 12 times in the last 30 days"
+  - Highlight fragile nodes: high churn + high fan-in = high breakage risk
+  - Track blast radius trends over time: "this PR's blast radius is 2× larger than your average"
+- **Interactive rendering (stretch):**
+  - Render as SVG with clickable nodes linking to file:line in the PR diff view
+  - Collapse/expand depth levels to manage large graphs
+  - Filter by risk level or file path
+
+**Infrastructure needed:**
+| What | Where | Depends on |
+|------|-------|------------|
+| GitHub Action workflow | `.github/workflows/impact-graph.yml` | `diff-impact --format mermaid` (done) |
+| LLM diff summarizer | `llm.js` + `queries.js` | LLM provider abstraction, `summaries` table |
+| Risk scoring per node | `nodes` table column | LLM assessment + graph centrality metrics |
+| Churn tracking | `metadata` table | Git log integration at build time |
+| SVG renderer | New module or external tool | Mermaid CLI (`mmdc`) or D3-based renderer |
+
 ---
 
 ### Refactoring Assistance

src/cli.js

@@ -216,13 +216,15 @@ program
   .option('--depth <n>', 'Max transitive caller depth', '3')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
+  .option('-f, --format <format>', 'Output format: text, mermaid, json', 'text')
   .action((ref, opts) => {
     diffImpact(opts.db, {
       ref,
       staged: opts.staged,
       depth: parseInt(opts.depth, 10),
       noTests: !opts.tests,
       json: opts.json,
+      format: opts.format,
     });
   });
 

src/index.js

@@ -41,6 +41,7 @@ export {
   ALL_SYMBOL_KINDS,
   contextData,
   diffImpactData,
+  diffImpactMermaid,
   explainData,
   FALSE_POSITIVE_CALLER_THRESHOLD,
   FALSE_POSITIVE_NAMES,

src/mcp.js

@@ -8,7 +8,7 @@
 import { createRequire } from 'node:module';
 import { findCycles } from './cycles.js';
 import { findDbPath } from './db.js';
-import { ALL_SYMBOL_KINDS } from './queries.js';
+import { ALL_SYMBOL_KINDS, diffImpactMermaid } from './queries.js';
 
 const REPO_PROP = {
   repo: {
@@ -201,6 +201,11 @@ const BASE_TOOLS = [
         ref: { type: 'string', description: 'Git ref to diff against (default: HEAD)' },
         depth: { type: 'number', description: 'Transitive caller depth', default: 3 },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        format: {
+          type: 'string',
+          enum: ['json', 'mermaid'],
+          description: 'Output format (default: json)',
+        },
       },
     },
   },
@@ -467,12 +472,21 @@ export async function startMCPServer(customDbPath, options = {}) {
           });
           break;
         case 'diff_impact':
-          result = diffImpactData(dbPath, {
-            staged: args.staged,
-            ref: args.ref,
-            depth: args.depth,
-            noTests: args.no_tests,
-          });
+          if (args.format === 'mermaid') {
+            result = diffImpactMermaid(dbPath, {
+              staged: args.staged,
+              ref: args.ref,
+              depth: args.depth,
+              noTests: args.no_tests,
+            });
+          } else {
+            result = diffImpactData(dbPath, {
+              staged: args.staged,
+              ref: args.ref,
+              depth: args.depth,
+              noTests: args.no_tests,
+            });
+          }
           break;
         case 'semantic_search': {
           const { searchData } = await import('./embedder.js');

src/queries.js

@@ -608,16 +608,34 @@ export function diffImpactData(customDbPath, opts = {}) {
 
   if (!diffOutput.trim()) {
     db.close();
-    return { changedFiles: 0, affectedFunctions: [], affectedFiles: [], summary: null };
+    return {
+      changedFiles: 0,
+      newFiles: [],
+      affectedFunctions: [],
+      affectedFiles: [],
+      summary: null,
+    };
   }
 
   const changedRanges = new Map();
+  const newFiles = new Set();
   let currentFile = null;
+  let prevIsDevNull = false;
   for (const line of diffOutput.split('\n')) {
+    if (line.startsWith('--- /dev/null')) {
+      prevIsDevNull = true;
+      continue;
+    }
+    if (line.startsWith('--- ')) {
+      prevIsDevNull = false;
+      continue;
+    }
     const fileMatch = line.match(/^\+\+\+ b\/(.+)/);
     if (fileMatch) {
       currentFile = fileMatch[1];
       if (!changedRanges.has(currentFile)) changedRanges.set(currentFile, []);
+      if (prevIsDevNull) newFiles.add(currentFile);
+      prevIsDevNull = false;
       continue;
     }
     const hunkMatch = line.match(/^@@ .+ \+(\d+)(?:,(\d+))? @@/);
@@ -630,7 +648,13 @@ export function diffImpactData(customDbPath, opts = {}) {
 
   if (changedRanges.size === 0) {
     db.close();
-    return { changedFiles: 0, affectedFunctions: [], affectedFiles: [], summary: null };
+    return {
+      changedFiles: 0,
+      newFiles: [],
+      affectedFunctions: [],
+      affectedFiles: [],
+      summary: null,
+    };
   }
 
   const affectedFunctions = [];
@@ -658,6 +682,10 @@ export function diffImpactData(customDbPath, opts = {}) {
     const visited = new Set([fn.id]);
     let frontier = [fn.id];
     let totalCallers = 0;
+    const levels = {};
+    const edges = [];
+    const idToKey = new Map();
+    idToKey.set(fn.id, `${fn.file}::${fn.name}:${fn.line}`);
     for (let d = 1; d <= maxDepth; d++) {
       const nextFrontier = [];
       for (const fid of frontier) {
@@ -673,6 +701,11 @@ export function diffImpactData(customDbPath, opts = {}) {
             visited.add(c.id);
             nextFrontier.push(c.id);
             allAffected.add(`${c.file}:${c.name}`);
+            const callerKey = `${c.file}::${c.name}:${c.line}`;
+            idToKey.set(c.id, callerKey);
+            if (!levels[d]) levels[d] = [];
+            levels[d].push({ name: c.name, kind: c.kind, file: c.file, line: c.line });
+            edges.push({ from: idToKey.get(fid), to: callerKey });
             totalCallers++;
           }
         }
@@ -686,6 +719,8 @@ export function diffImpactData(customDbPath, opts = {}) {
       file: fn.file,
       line: fn.line,
       transitiveCallers: totalCallers,
+      levels,
+      edges,
     };
   });
 
@@ -695,6 +730,7 @@ export function diffImpactData(customDbPath, opts = {}) {
   db.close();
   return {
     changedFiles: changedRanges.size,
+    newFiles: [...newFiles],
     affectedFunctions: functionResults,
     affectedFiles: [...affectedFiles],
     summary: {
@@ -705,6 +741,120 @@ export function diffImpactData(customDbPath, opts = {}) {
   };
 }
 
+export function diffImpactMermaid(customDbPath, opts = {}) {
+  const data = diffImpactData(customDbPath, opts);
+  if (data.error) return data.error;
+  if (data.changedFiles === 0 || data.affectedFunctions.length === 0) {
+    return 'flowchart TB\n    none["No impacted functions detected"]';
+  }
+
+  const newFileSet = new Set(data.newFiles || []);
+  const lines = ['flowchart TB'];
+
+  // Assign stable Mermaid node IDs
+  let nodeCounter = 0;
+  const nodeIdMap = new Map();
+  const nodeLabels = new Map();
+  function nodeId(key, label) {
+    if (!nodeIdMap.has(key)) {
+      nodeIdMap.set(key, `n${nodeCounter++}`);
+      if (label) nodeLabels.set(key, label);
+    }
+    return nodeIdMap.get(key);
+  }
+
+  // Register all nodes (changed functions + their callers)
+  for (const fn of data.affectedFunctions) {
+    nodeId(`${fn.file}::${fn.name}:${fn.line}`, fn.name);
+    for (const callers of Object.values(fn.levels || {})) {
+      for (const c of callers) {
+        nodeId(`${c.file}::${c.name}:${c.line}`, c.name);
+      }
+    }
+  }
+
+  // Collect all edges and determine blast radius
+  const allEdges = new Set();
+  const edgeFromNodes = new Set();
+  const edgeToNodes = new Set();
+  const changedKeys = new Set();
+
+  for (const fn of data.affectedFunctions) {
+    changedKeys.add(`${fn.file}::${fn.name}:${fn.line}`);
+    for (const edge of fn.edges || []) {
+      const edgeKey = `${edge.from}|${edge.to}`;
+      if (!allEdges.has(edgeKey)) {
+        allEdges.add(edgeKey);
+        edgeFromNodes.add(edge.from);
+        edgeToNodes.add(edge.to);
+      }
+    }
+  }
+
+  // Blast radius: caller nodes that are never a source (leaf nodes of the impact tree)
+  const blastRadiusKeys = new Set();
+  for (const key of edgeToNodes) {
+    if (!edgeFromNodes.has(key) && !changedKeys.has(key)) {
+      blastRadiusKeys.add(key);
+    }
+  }
+
+  // Intermediate callers: not changed, not blast radius
+  const intermediateKeys = new Set();
+  for (const key of edgeToNodes) {
+    if (!changedKeys.has(key) && !blastRadiusKeys.has(key)) {
+      intermediateKeys.add(key);
+    }
+  }
+
+  // Group changed functions by file
+  const fileGroups = new Map();
+  for (const fn of data.affectedFunctions) {
+    if (!fileGroups.has(fn.file)) fileGroups.set(fn.file, []);
+    fileGroups.get(fn.file).push(fn);
+  }
+
+  // Emit changed-file subgraphs
+  let sgCounter = 0;
+  for (const [file, fns] of fileGroups) {
+    const isNew = newFileSet.has(file);
+    const tag = isNew ? 'new' : 'modified';
+    const sgId = `sg${sgCounter++}`;
+    lines.push(`    subgraph ${sgId}["${file} **(${tag})**"]`);
+    for (const fn of fns) {
+      const key = `${fn.file}::${fn.name}:${fn.line}`;
+      lines.push(`        ${nodeIdMap.get(key)}["${fn.name}"]`);
+    }
+    lines.push('    end');
+    const style = isNew ? 'fill:#e8f5e9,stroke:#4caf50' : 'fill:#fff3e0,stroke:#ff9800';
+    lines.push(`    style ${sgId} ${style}`);
+  }
+
+  // Emit intermediate caller nodes (outside subgraphs)
+  for (const key of intermediateKeys) {
+    lines.push(`    ${nodeIdMap.get(key)}["${nodeLabels.get(key)}"]`);
+  }
+
+  // Emit blast radius subgraph
+  if (blastRadiusKeys.size > 0) {
+    const sgId = `sg${sgCounter++}`;
+    lines.push(`    subgraph ${sgId}["Callers **(blast radius)**"]`);
+    for (const key of blastRadiusKeys) {
+      lines.push(`        ${nodeIdMap.get(key)}["${nodeLabels.get(key)}"]`);
+    }
+    lines.push('    end');
+    lines.push(`    style ${sgId} fill:#f3e5f5,stroke:#9c27b0`);
+  }
+
+  // Emit edges (impact flows from changed fn toward callers)
+  for (const edgeKey of allEdges) {
+    const [from, to] = edgeKey.split('|');
+    lines.push(`    ${nodeIdMap.get(from)} --> ${nodeIdMap.get(to)}`);
+  }
+
+  return lines.join('\n');
+}
+
 export function listFunctionsData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
   const noTests = opts.noTests || false;
@@ -2079,8 +2229,12 @@ export function fnImpact(name, customDbPath, opts = {}) {
 }
 
 export function diffImpact(customDbPath, opts = {}) {
+  if (opts.format === 'mermaid') {
+    console.log(diffImpactMermaid(customDbPath, opts));
+    return;
+  }
   const data = diffImpactData(customDbPath, opts);
-  if (opts.json) {
+  if (opts.json || opts.format === 'json') {
     console.log(JSON.stringify(data, null, 2));
     return;
   }