sigmap 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [2.6.0] — upcoming · [#16](https://github.com/manojmallick/sigmap/issues/16) · branch: `feat/v2.6-research-mode`
+
+### Planned additions
+- **`benchmarks/repos/`** — register 5 real open-source repos (express, flask, gin, spring-petclinic, rails) as git submodules or clone targets for evaluation
+- **`benchmarks/tasks/retrieval-real.jsonl`** — 50 real evaluation tasks across all 5 repos; structured JSONL format compatible with the v2.1 benchmark runner
+- **`--benchmark --repo <path>` CLI flag** — run benchmark against external repository; supports any git-cloned project
+- **`--report --paper` CLI flag** — generates `benchmarks/reports/paper-metrics.md`: token reduction table (baseline vs SigMap per repo), hit@5 and MRR per repo, latency table (p50, p95, p99 in ms), LaTeX-ready table block for copy-paste into academic papers
+- **`src/eval/paper.js`** — formats paper-ready markdown + LaTeX tables; zero dependencies
+- **`test/integration/paper.test.js`** — 8 tests: `--report --paper` creates the report file, report contains all required sections, LaTeX table block present and syntactically valid, `--benchmark --repo <missing>` fails gracefully
+
+### Go / No-go criteria
+- All tests green (21 extractor + all integration suites)
+- `--report --paper` generates a valid markdown file
+- LaTeX table block present in report
+- Overall hit@5 across all repos ≥ 0.75
+- `--benchmark --repo .` completes in < 30 s on SigMap repo
+
+---
+
+## [2.5.0] — upcoming · [#14](https://github.com/manojmallick/sigmap/issues/14) · branch: `feat/v2.5-impact-layer`
+
+### Planned additions
+- **`src/map/dep-graph.js`** — reverse-dependency graph built from the existing import-graph analysis. `getImpacted(filePath, graph)` walks the graph via BFS/DFS and returns every file that transitively imports the given file.
+- **`src/map/impact.js`** — `analyzeImpact(changedFiles, cwd)` → `{ changed, impacted, totalFiles }`. Aggregates dep-graph traversal with optional signature lookup.
+- **`--impact <file>` CLI flag** — prints all files impacted by changing `<file>`, with their signatures. Supports `--impact --json` (machine-readable) and `--impact --depth <n>` (BFS depth limit).
+- **`get_impact` MCP tool** (9th tool) — `{ file: string, depth?: number }` → list of impacted files + signatures, usable live in any MCP session.
+- **`impact` config key** — `{ depth: 0, includeSigs: true }` in `gen-context.config.json`.
+- **`test/integration/impact.test.js`** — 15 tests: direct deps, transitive deps, circular deps (no infinite loop), depth limit, unknown file returns `[]`, JSON output shape, MCP tool shape.
+
+---
+
 ## [2.4.0] — 2026-04-05
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@
 
 <!-- Status -->
 [![npm version](https://img.shields.io/npm/v/sigmap?color=7c6af7&label=latest&logo=npm)](https://www.npmjs.com/package/sigmap)
-[![Tests](https://img.shields.io/badge/tests-325%20passing-22c55e)](https://github.com/manojmallick/sigmap/tree/main/test)
+[![Tests](https://img.shields.io/badge/tests-340%20passing-22c55e)](https://github.com/manojmallick/sigmap/tree/main/test)
 [![Zero deps](https://img.shields.io/badge/dependencies-zero-22c55e)](package.json)
 [![Last commit](https://img.shields.io/github/last-commit/manojmallick/sigmap?color=7c6af7)](https://github.com/manojmallick/sigmap/commits/main)
 
@@ -86,6 +86,37 @@ AI agent session starts with full context
 
 ---
 
+## 🔭 What's next — v2.5-v2.6 (in progress · [#14](https://github.com/manojmallick/sigmap/issues/14) · [#16](https://github.com/manojmallick/sigmap/issues/16))
+
+### v2.5 — Impact Layer
+
+| Feature | Description |
+|---|---|
+| **`--impact <file>`** | Show every file that transitively depends on a changed file — instant blast-radius awareness |
+| **`--impact --json`** | Machine-readable output for CI pipelines |
+| **`get_impact` MCP tool** | 9th MCP tool — `{ file, depth? }` → impacted files + signatures |
+| **`src/map/dep-graph.js`** | Reverse-dependency graph built from the import analysis; circular deps handled safely |
+| **15 new tests** | `impact.test.js` — direct deps, transitive deps, depth limit, JSON output |
+
+### v2.6 — Research Mode
+
+| Feature | Description |
+|---|---|
+| **`--benchmark --repo <path>`** | Run benchmarks against any external repository (express, flask, gin, spring-petclinic, rails) |
+| **`--report --paper`** | Generate paper-ready metrics: markdown + LaTeX tables for academic publishing |
+| **50 real eval tasks** | JSONL task file covering 5 real open-source repos — `benchmarks/tasks/retrieval-real.jsonl` |
+| **`src/eval/paper.js`** | Zero-dependency LaTeX table formatter for token reduction, hit@5, MRR, latency (p50/p95/p99) |
+| **8 new tests** | `paper.test.js` — report generation, LaTeX syntax validation, graceful failures |
+
+## 🆕 What's new in 2.4
+
+| Feature | Description |
+|---|---|
+| **Programmatic API** | `require('sigmap')` — use `extract`, `rank`, `buildSigIndex`, `scan`, `score` directly, no CLI subprocess |
+| **`packages/core/`** | New `sigmap-core` package with stable API surface for third-party integrations |
+| **`packages/cli/`** | Thin `sigmap-cli` forward-compat shim for the v3.0 adapter architecture |
+| **15 new tests** | `core-api.test.js` covers all exported functions, edge cases, and backward compat |
+
 ## 🆕 What's new in 2.3
 
 | Feature | Description |

package/gen-context.js

@@ -2462,6 +2462,182 @@ __factories["./src/map/route-table"] = function(module, exports) {
   
 };
 
+// ── ./src/graph/builder ──
+__factories["./src/graph/builder"] = function(module, exports) {
+  'use strict';
+  const fs   = require('fs');
+  const path = require('path');
+  const JS_EXTS  = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+  const PY_EXTS  = new Set(['.py', '.pyw']);
+  const GO_EXTS  = new Set(['.go']);
+  const RS_EXTS  = new Set(['.rs']);
+  const JVM_EXTS = new Set(['.java', '.kt', '.kts', '.scala', '.sc']);
+  const RB_EXTS  = new Set(['.rb', '.rake']);
+  function resolveJsPath(dir, importStr, fileSet) {
+    const base = path.resolve(dir, importStr);
+    const candidates = [base, base+'.ts', base+'.tsx', base+'.js', base+'.jsx', base+'.mjs', base+'.cjs', path.join(base,'index.ts'), path.join(base,'index.js')];
+    for (const c of candidates) { if (fileSet.has(c)) return c; }
+    return null;
+  }
+  function extractFileDeps(filePath, content, fileSet) {
+    const ext = path.extname(filePath).toLowerCase();
+    const dir = path.dirname(filePath);
+    const found = [];
+    if (JS_EXTS.has(ext)) {
+      const stripped = content.replace(/\/\/.*$/gm,'').replace(/\/\*[\s\S]*?\*\//g,'');
+      const reEs = /(?:^|[\r\n])\s*import\s+(?:[^'";\r\n]*?\s+from\s+)?['"](\.[^'"]+)['"]/g;
+      let m;
+      while ((m = reEs.exec(stripped)) !== null) { const r = resolveJsPath(dir, m[1], fileSet); if (r) found.push(r); }
+      const reCjs = /\brequire\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+      while ((m = reCjs.exec(stripped)) !== null) { const r = resolveJsPath(dir, m[1], fileSet); if (r) found.push(r); }
+    }
+    if (PY_EXTS.has(ext)) {
+      const re = /^[ \t]*from\s+(\.+[\w.]*)\s+import/gm; let m;
+      while ((m = re.exec(content)) !== null) {
+        const dotCount = (m[1].match(/^\.+/)||[''])[0].length;
+        const modPart = m[1].slice(dotCount).replace(/\./g,'/');
+        let base = dir; for (let i=1;i<dotCount;i++) base=path.dirname(base);
+        const candidate = modPart ? path.join(base,modPart+'.py') : null;
+        if (candidate && fileSet.has(candidate)) found.push(candidate);
+      }
+    }
+    if (GO_EXTS.has(ext)) {
+      const imports = []; let m;
+      const re = /import\s*\(\s*([\s\S]*?)\s*\)/g;
+      const reInline = /import\s+"([^"]+)"/g;
+      while ((m = re.exec(content)) !== null) { for (const imp of m[1].matchAll(/"([^"]+)"/g)) imports.push(imp[1]); }
+      while ((m = reInline.exec(content)) !== null) imports.push(m[1]);
+      for (const imp of imports) {
+        const suffix = imp.split('/').pop();
+        for (const f of fileSet) { if (f.endsWith(path.sep+suffix+'.go')||f.includes(path.sep+suffix+path.sep)) { found.push(f); break; } }
+      }
+    }
+    if (RS_EXTS.has(ext)) {
+      const reMod = /^\s*(?:pub\s+)?mod\s+(\w+)\s*;/gm; let m;
+      while ((m = reMod.exec(content)) !== null) {
+        const c1 = path.join(dir,m[1]+'.rs'); if (fileSet.has(c1)) found.push(c1);
+        const c2 = path.join(dir,m[1],'mod.rs'); if (fileSet.has(c2)) found.push(c2);
+      }
+    }
+    if (JVM_EXTS.has(ext)) {
+      const re = /^\s*import\s+([\w.]+)\s*;?/gm; let m;
+      while ((m = re.exec(content)) !== null) {
+        const asPath = m[1].replace(/\./g,path.sep);
+        for (const jvmExt of ['.java','.kt','.kts','.scala','.sc']) {
+          for (const f of fileSet) { if (f.endsWith(asPath+jvmExt)) { found.push(f); break; } }
+        }
+      }
+    }
+    if (RB_EXTS.has(ext)) {
+      const re = /^\s*require_relative\s+['"]([^'"]+)['"]/gm; let m;
+      while ((m = re.exec(content)) !== null) {
+        const base = path.resolve(dir,m[1]);
+        const candidate = base.endsWith('.rb') ? base : base+'.rb';
+        if (fileSet.has(candidate)) found.push(candidate);
+      }
+    }
+    return [...new Set(found)];
+  }
+  function build(files, cwd) {
+    const fileSet = new Set(files.map((f) => path.resolve(f)));
+    const forward = new Map(); const reverse = new Map();
+    for (const f of fileSet) { if (!forward.has(f)) forward.set(f,[]); if (!reverse.has(f)) reverse.set(f,[]); }
+    for (const filePath of fileSet) {
+      let content; try { content = fs.readFileSync(filePath,'utf8'); } catch(_) { continue; }
+      const deps = extractFileDeps(filePath, content, fileSet);
+      if (deps.length > 0) {
+        forward.set(filePath, deps);
+        for (const dep of deps) { if (!reverse.has(dep)) reverse.set(dep,[]); reverse.get(dep).push(filePath); }
+      }
+    }
+    return { forward, reverse };
+  }
+  function buildFromCwd(cwd, opts) {
+    const { srcDirs=['src','app','lib'], exclude=['node_modules','.git','dist','build'] } = opts||{};
+    const excludeSet = new Set(exclude);
+    function walkDir(dir,depth) {
+      if (depth>8) return [];
+      let entries; try { entries = fs.readdirSync(dir,{withFileTypes:true}); } catch(_) { return []; }
+      const out=[];
+      for (const e of entries) {
+        if (excludeSet.has(e.name)||e.name.startsWith('.')) continue;
+        const full = path.join(dir,e.name);
+        if (e.isDirectory()) out.push(...walkDir(full,depth+1));
+        else if (e.isFile()) {
+          const ext = path.extname(e.name).toLowerCase();
+          if (JS_EXTS.has(ext)||PY_EXTS.has(ext)||GO_EXTS.has(ext)||RS_EXTS.has(ext)||JVM_EXTS.has(ext)||RB_EXTS.has(ext)) out.push(full);
+        }
+      }
+      return out;
+    }
+    const files=[];
+    for (const sd of srcDirs) { const absDir=path.resolve(cwd,sd); if (fs.existsSync(absDir)) files.push(...walkDir(absDir,0)); }
+    for (const rootFile of ['gen-context.js','index.js','main.js','app.js']) {
+      const abs=path.resolve(cwd,rootFile); if (fs.existsSync(abs)) files.push(abs);
+    }
+    return build(files, cwd);
+  }
+  module.exports = { build, buildFromCwd, extractFileDeps };
+};
+
+// ── ./src/graph/impact ──
+__factories["./src/graph/impact"] = function(module, exports) {
+  'use strict';
+  const path = require('path');
+  const { buildFromCwd } = __require('./src/graph/builder');
+  const TEST_PATTERNS = [/[./\\](test|tests|spec|__tests__)[./\\]/,/\.(test|spec)\.[jt]sx?$/,/_test\.[jt]sx?$/,/_test\.py$/,/test_[^/\\]+\.py$/];
+  const ROUTE_PATTERNS = [/router?\.[jt]sx?$/i,/routes?\.[jt]sx?$/i,/controller\.[jt]sx?$/i,/views?\.[jt]sx?$/i,/handlers?\.[jt]sx?$/i];
+  function isTestFile(f) { return TEST_PATTERNS.some((re) => re.test(f.replace(/\\/g,'/'))); }
+  function isRouteFile(f) { return ROUTE_PATTERNS.some((re) => re.test(f.replace(/\\/g,'/'))); }
+  function bfs(startFile, reverseGraph, maxDepth) {
+    const direct=new Set(); const transitive=new Set(); const visited=new Set([startFile]);
+    const firstLevel = reverseGraph.get(startFile)||[];
+    for (const f of firstLevel) { if (!visited.has(f)) { direct.add(f); visited.add(f); } }
+    if (maxDepth===1) return {direct,transitive};
+    let frontier=[...direct]; let depth=1;
+    while (frontier.length>0 && (maxDepth===0||depth<maxDepth)) {
+      const nextFrontier=[];
+      for (const node of frontier) {
+        const importers=reverseGraph.get(node)||[];
+        for (const imp of importers) { if (!visited.has(imp)) { transitive.add(imp); visited.add(imp); nextFrontier.push(imp); } }
+      }
+      frontier=nextFrontier; depth++;
+    }
+    return {direct,transitive};
+  }
+  function getImpact(changedFile, graph, opts) {
+    const {depth=0,cwd=process.cwd()} = opts||{};
+    const absChanged = path.resolve(cwd,changedFile);
+    if (!graph||!graph.reverse) return {changed:changedFile,direct:[],transitive:[],tests:[],routes:[],totalImpact:0};
+    const {direct,transitive} = bfs(absChanged,graph.reverse,depth);
+    const allImpacted=[...direct,...transitive];
+    const tests=allImpacted.filter(isTestFile); const routes=allImpacted.filter(isRouteFile);
+    const toRel=(f)=>path.relative(cwd,f).replace(/\\/g,'/');
+    return {changed:toRel(absChanged),direct:[...direct].map(toRel),transitive:[...transitive].map(toRel),tests:tests.map(toRel),routes:routes.map(toRel),totalImpact:direct.size+transitive.size};
+  }
+  function analyzeImpact(changedFiles, cwd, opts) {
+    const {depth=3}=opts||{};
+    const files=Array.isArray(changedFiles)?changedFiles:[changedFiles];
+    let graph;
+    try { graph=buildFromCwd(cwd,opts); } catch(_) { graph={forward:new Map(),reverse:new Map()}; }
+    return files.map((f)=>({file:f,impact:getImpact(f,graph,{depth,cwd})}));
+  }
+  function formatImpact(result) {
+    const lines=[`## Impact: \`${result.changed}\``,``];
+    if (result.direct.length===0&&result.transitive.length===0) { lines.push('_No files import this file — zero blast radius._'); return lines.join('\n'); }
+    lines.push(`**Total impacted files:** ${result.totalImpact}`,``);
+    if (result.direct.length>0) { lines.push('### Direct importers'); for (const f of result.direct) lines.push(`- \`${f}\``); lines.push(''); }
+    if (result.transitive.length>0) { lines.push('### Transitive importers'); for (const f of result.transitive) lines.push(`- \`${f}\``); lines.push(''); }
+    if (result.tests.length>0) { lines.push('### Affected tests'); for (const f of result.tests) lines.push(`- \`${f}\``); lines.push(''); }
+    if (result.routes.length>0) { lines.push('### Affected routes / controllers'); for (const f of result.routes) lines.push(`- \`${f}\``); lines.push(''); }
+    return lines.join('\n');
+  }
+  function formatImpactJSON(result) {
+    return {changed:result.changed,direct:result.direct,transitive:result.transitive,tests:result.tests,routes:result.routes,totalImpact:result.totalImpact};
+  }
+  module.exports = { getImpact, analyzeImpact, formatImpact, formatImpactJSON };
+};
+
 // ── ./src/mcp/handlers ──
 __factories["./src/mcp/handlers"] = function(module, exports) {
   
@@ -2895,7 +3071,19 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     }
   }
   
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext };
+  function getImpact(args, cwd) {
+    if (!args || !args.file) return 'Missing required argument: file';
+    try {
+      const { analyzeImpact, formatImpact } = __require('./src/graph/impact');
+      const depth = Math.max(0, parseInt(args.depth, 10) || 3);
+      const results = analyzeImpact(args.file, cwd, { depth });
+      return results.map((r) => formatImpact(r.impact)).join('\n\n---\n\n');
+    } catch (err) {
+      return `_get_impact failed: ${err.message}_`;
+    }
+  }
+
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };
 };
 
 // ── ./src/mcp/server ──
@@ -2915,7 +3103,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const readline = require('readline');
   const { TOOLS } = __require('./src/mcp/tools');
-  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext } = __require('./src/mcp/handlers');
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact } = __require('./src/mcp/handlers');
   
   const SERVER_INFO = {
     name: 'sigmap',
@@ -2975,6 +3163,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
         else if (name === 'explain_file') text = explainFile(args, cwd);
         else if (name === 'list_modules') text = listModules(args, cwd);
         else if (name === 'query_context') text = queryContext(args, cwd);
+        else if (name === 'get_impact') text = getImpact(args, cwd);
         else {
           respondError(id, -32601, `Unknown tool: ${name}`);
           return;
@@ -3178,6 +3367,30 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         required: ['query'],
       },
     },
+    {
+      name: 'get_impact',
+      description:
+        'Show every file that is impacted when a given file changes — direct importers, ' +
+        'transitive importers, affected tests, and affected routes/controllers. ' +
+        'Gives agents instant blast-radius awareness before making a change. ' +
+        'Handles circular dependencies safely (no infinite loops).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description:
+              'Relative path from the project root of the file that changed ' +
+              '(e.g. "src/extractors/python.js"). Use forward slashes.',
+          },
+          depth: {
+            type: 'number',
+            description: 'BFS traversal depth limit (default: 3). Use 0 for unlimited.',
+          },
+        },
+        required: ['file'],
+      },
+    },
   ];
   
   module.exports = { TOOLS };
@@ -4091,7 +4304,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '2.4.0';
+const VERSION = '2.5.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -5307,6 +5520,9 @@ Usage:
   node gen-context.js --query "<text>"                  Rank files by relevance to a query
   node gen-context.js --query "<text>" --json           Ranked results as JSON
   node gen-context.js --query "<text>" --top <n>        Limit results to top N files (default 10)
+  node gen-context.js --impact <file>                   Show every file impacted by changing <file>
+  node gen-context.js --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
+  node gen-context.js --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
   node gen-context.js --init                            Write example config + .contextignore scaffold
   node gen-context.js --help                            Show this message
   node gen-context.js --version                         Show version
@@ -5625,6 +5841,35 @@ function main() {
     process.exit(0);
   }
 
+  // ── --impact <file> ────────────────────────────────────────────────────────
+  if (args.includes('--impact')) {
+    try {
+      const impIdx = args.indexOf('--impact');
+      const targetFile = (args[impIdx + 1] || '').trim();
+      if (!targetFile || targetFile.startsWith('--')) {
+        console.error('[sigmap] --impact requires a file path');
+        console.error('  Example: node gen-context.js --impact src/extractors/python.js');
+        process.exit(1);
+      }
+      const { analyzeImpact, formatImpact, formatImpactJSON } = requireSourceOrBundled('./src/graph/impact');
+      const depthIdx = args.indexOf('--depth');
+      const depth = depthIdx >= 0 ? Math.max(0, parseInt(args[depthIdx + 1], 10) || 3) : ((config && config.impact && config.impact.depth) || 3);
+      const results = analyzeImpact(targetFile, cwd, { depth });
+      if (args.includes('--json')) {
+        const out = results.map((r) => formatImpactJSON(r.impact));
+        process.stdout.write(JSON.stringify(out.length === 1 ? out[0] : out) + '\n');
+      } else {
+        for (const r of results) {
+          process.stdout.write(formatImpact(r.impact) + '\n');
+        }
+      }
+    } catch (err) {
+      console.error(`[sigmap] impact error: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
   if (args.includes('--report')) {
     if (args.includes('--history')) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {

package/packages/core/README.md

@@ -128,6 +128,14 @@ const health = score('/path/to/project');
 
 All existing CLI flags (`--generate`, `--watch`, `--mcp`, `--query`, `--analyze`, `--benchmark`, `--health`, …) are unchanged.
 
+## What's next — v2.5-v2.6
+
+v2.5 adds `analyzeImpact(changedFiles, cwd)` to `packages/core` — given a list of changed files, it returns every file that transitively imports them. See [issue #14](https://github.com/manojmallick/sigmap/issues/14).
+
+v2.6 adds benchmark and paper reporting capabilities — run evaluations against external repos and export metrics in LaTeX format for academic papers. See [issue #16](https://github.com/manojmallick/sigmap/issues/16).
+
+See the full [roadmap](https://manojmallick.github.io/sigmap/roadmap.html).
+
 ## Zero dependencies
 
 This package has zero runtime npm dependencies. It uses only Node.js built-ins: `fs`, `path`.

package/src/config/defaults.js

@@ -100,6 +100,14 @@ const DEFAULTS = {
     // Multiplier applied to recently-changed files (>1 boosts them up)
     recencyBoost: 1.5,
   },
+
+  // Impact layer settings (v2.5)
+  impact: {
+    // BFS traversal depth limit for --impact (0 = unlimited)
+    depth: 3,
+    // Include signatures of impacted files in --impact output
+    includeSigs: true,
+  },
 };
 
 module.exports = { DEFAULTS };

package/src/graph/builder.js

@@ -0,0 +1,259 @@
+'use strict';
+
+/**
+ * Dependency graph builder (v2.5).
+ *
+ * Builds a forward and reverse dependency graph by resolving import/require
+ * statements across JS/TS, Python, Go, Rust, Java, Kotlin, and Ruby files.
+ *
+ * @module src/graph/builder
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Language-specific import extractors
+// ---------------------------------------------------------------------------
+
+const JS_EXTS  = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const PY_EXTS  = new Set(['.py', '.pyw']);
+const GO_EXTS  = new Set(['.go']);
+const RS_EXTS  = new Set(['.rs']);
+const JVM_EXTS = new Set(['.java', '.kt', '.kts', '.scala', '.sc']);
+const RB_EXTS  = new Set(['.rb', '.rake']);
+
+/**
+ * Resolve a JS/TS relative import string to an absolute path in fileSet.
+ * @param {string} dir - directory of the importing file
+ * @param {string} importStr - raw import string (e.g. './utils', '../store')
+ * @param {Set<string>} fileSet
+ * @returns {string|null}
+ */
+function resolveJsPath(dir, importStr, fileSet) {
+  const base = path.resolve(dir, importStr);
+  const candidates = [
+    base,
+    base + '.ts', base + '.tsx',
+    base + '.js', base + '.jsx', base + '.mjs', base + '.cjs',
+    path.join(base, 'index.ts'),
+    path.join(base, 'index.js'),
+  ];
+  for (const c of candidates) {
+    if (fileSet.has(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Extract absolute dependency paths from a single file.
+ * @param {string} filePath - absolute path to the file
+ * @param {string} content  - file source content
+ * @param {Set<string>} fileSet - set of all known absolute file paths
+ * @returns {string[]} resolved absolute paths this file imports
+ */
+function extractFileDeps(filePath, content, fileSet) {
+  const ext = path.extname(filePath).toLowerCase();
+  const dir = path.dirname(filePath);
+  const found = [];
+
+  // ── JS / TS ───────────────────────────────────────────────────────────────
+  if (JS_EXTS.has(ext)) {
+    const stripped = content
+      .replace(/\/\/.*$/gm, '')
+      .replace(/\/\*[\s\S]*?\*\//g, '');
+
+    // ES imports:   import ... from './foo'  or  import './side-effect'
+    const reEs = /(?:^|[\r\n])\s*import\s+(?:[^'";\r\n]*?\s+from\s+)?['"](\.[^'"]+)['"]/g;
+    let m;
+    while ((m = reEs.exec(stripped)) !== null) {
+      const r = resolveJsPath(dir, m[1], fileSet);
+      if (r) found.push(r);
+    }
+    // CommonJS: require('./foo')
+    const reCjs = /\brequire\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+    while ((m = reCjs.exec(stripped)) !== null) {
+      const r = resolveJsPath(dir, m[1], fileSet);
+      if (r) found.push(r);
+    }
+  }
+
+  // ── Python ────────────────────────────────────────────────────────────────
+  if (PY_EXTS.has(ext)) {
+    // from .module import ...  /  from ..pkg import ...
+    const re = /^[ \t]*from\s+(\.+[\w.]*)\s+import/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const dotCount = (m[1].match(/^\.+/) || [''])[0].length;
+      const modPart  = m[1].slice(dotCount).replace(/\./g, '/');
+      let base = dir;
+      for (let i = 1; i < dotCount; i++) base = path.dirname(base);
+      const candidate = modPart
+        ? path.join(base, modPart + '.py')
+        : null;
+      if (candidate && fileSet.has(candidate)) found.push(candidate);
+    }
+  }
+
+  // ── Go ────────────────────────────────────────────────────────────────────
+  // Go uses module paths, not relative file paths — we match same-module paths
+  // by checking if any known file's relative path matches the imported suffix.
+  if (GO_EXTS.has(ext)) {
+    const re = /import\s*\(\s*([\s\S]*?)\s*\)/g;
+    const reInline = /import\s+"([^"]+)"/g;
+    const imports = [];
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      for (const imp of m[1].matchAll(/"([^"]+)"/g)) imports.push(imp[1]);
+    }
+    while ((m = reInline.exec(content)) !== null) imports.push(m[1]);
+
+    for (const imp of imports) {
+      const suffix = imp.split('/').pop();
+      for (const f of fileSet) {
+        if (f.endsWith(path.sep + suffix + '.go') ||
+            f.includes(path.sep + suffix + path.sep)) {
+          found.push(f);
+          break;
+        }
+      }
+    }
+  }
+
+  // ── Rust ──────────────────────────────────────────────────────────────────
+  // Match `mod foo;` and `use crate::foo::bar` — resolve to sibling .rs files
+  if (RS_EXTS.has(ext)) {
+    const reMod = /^\s*(?:pub\s+)?mod\s+(\w+)\s*;/gm;
+    let m;
+    while ((m = reMod.exec(content)) !== null) {
+      const candidate = path.join(dir, m[1] + '.rs');
+      if (fileSet.has(candidate)) found.push(candidate);
+      // Also try mod/mod.rs
+      const candidate2 = path.join(dir, m[1], 'mod.rs');
+      if (fileSet.has(candidate2)) found.push(candidate2);
+    }
+  }
+
+  // ── Java / Kotlin / Scala ─────────────────────────────────────────────────
+  // Match same-project import statements by matching package-relative paths
+  if (JVM_EXTS.has(ext)) {
+    const re = /^\s*import\s+([\w.]+)\s*;?/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      // Convert com.example.utils.StringHelper → com/example/utils/StringHelper.java
+      const asPath = m[1].replace(/\./g, path.sep);
+      for (const jvmExt of ['.java', '.kt', '.kts', '.scala', '.sc']) {
+        for (const f of fileSet) {
+          if (f.endsWith(asPath + jvmExt)) { found.push(f); break; }
+        }
+      }
+    }
+  }
+
+  // ── Ruby ──────────────────────────────────────────────────────────────────
+  if (RB_EXTS.has(ext)) {
+    const re = /^\s*require_relative\s+['"]([^'"]+)['"]/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const base = path.resolve(dir, m[1]);
+      const candidate  = base.endsWith('.rb') ? base : base + '.rb';
+      if (fileSet.has(candidate)) found.push(candidate);
+    }
+  }
+
+  return [...new Set(found)];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a forward and reverse dependency graph for all given files.
+ *
+ * @param {string[]} files - absolute file paths to analyze
+ * @param {string}   cwd   - project root (used only for error reporting)
+ * @returns {{ forward: Map<string,string[]>, reverse: Map<string,string[]> }}
+ */
+function build(files, cwd) {
+  const fileSet = new Set(files.map((f) => path.resolve(f)));
+  const forward = new Map();
+  const reverse = new Map();
+
+  // Initialise every known file in both maps (ensures isolated files appear)
+  for (const f of fileSet) {
+    if (!forward.has(f)) forward.set(f, []);
+    if (!reverse.has(f)) reverse.set(f, []);
+  }
+
+  for (const filePath of fileSet) {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (_) {
+      continue;
+    }
+
+    const deps = extractFileDeps(filePath, content, fileSet);
+    if (deps.length > 0) {
+      forward.set(filePath, deps);
+      for (const dep of deps) {
+        if (!reverse.has(dep)) reverse.set(dep, []);
+        reverse.get(dep).push(filePath);
+      }
+    }
+  }
+
+  return { forward, reverse };
+}
+
+/**
+ * Build a dependency graph scoped to a single cwd by walking all JS/TS/Py/Go
+ * files under srcDirs. Useful for the MCP tool handler.
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string[]} [opts.srcDirs]
+ * @param {string[]} [opts.exclude]
+ * @returns {{ forward: Map<string,string[]>, reverse: Map<string,string[]> }}
+ */
+function buildFromCwd(cwd, opts) {
+  const { srcDirs = ['src', 'app', 'lib'], exclude = ['node_modules', '.git', 'dist', 'build'] } = opts || {};
+  const excludeSet = new Set(exclude);
+
+  function walkDir(dir, depth) {
+    if (depth > 8) return [];
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return []; }
+    const out = [];
+    for (const e of entries) {
+      if (excludeSet.has(e.name) || e.name.startsWith('.')) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        out.push(...walkDir(full, depth + 1));
+      } else if (e.isFile()) {
+        const ext = path.extname(e.name).toLowerCase();
+        if (JS_EXTS.has(ext) || PY_EXTS.has(ext) || GO_EXTS.has(ext) ||
+            RS_EXTS.has(ext) || JVM_EXTS.has(ext) || RB_EXTS.has(ext)) {
+          out.push(full);
+        }
+      }
+    }
+    return out;
+  }
+
+  const files = [];
+  for (const sd of srcDirs) {
+    const absDir = path.resolve(cwd, sd);
+    if (fs.existsSync(absDir)) files.push(...walkDir(absDir, 0));
+  }
+  // Also include root-level entry files
+  for (const rootFile of ['gen-context.js', 'index.js', 'main.js', 'app.js']) {
+    const abs = path.resolve(cwd, rootFile);
+    if (fs.existsSync(abs)) files.push(abs);
+  }
+
+  return build(files, cwd);
+}
+
+module.exports = { build, buildFromCwd, extractFileDeps };

package/src/graph/impact.js

@@ -0,0 +1,235 @@
+'use strict';
+
+/**
+ * Impact radius calculator (v2.5).
+ *
+ * Given a changed file and a dependency graph, finds every file that
+ * transitively imports it using BFS. Handles circular dependencies safely.
+ *
+ * @module src/graph/impact
+ */
+
+const path = require('path');
+const { buildFromCwd } = require('./builder');
+
+// ---------------------------------------------------------------------------
+// Core BFS traversal
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk the reverse graph from `startFile` using BFS up to `maxDepth` levels.
+ * Returns separate sets for direct and transitive dependents.
+ *
+ * @param {string} startFile - absolute path of file that changed
+ * @param {Map<string,string[]>} reverseGraph
+ * @param {number} maxDepth  - 0 = unlimited
+ * @returns {{ direct: Set<string>, transitive: Set<string> }}
+ */
+function bfs(startFile, reverseGraph, maxDepth) {
+  const direct     = new Set();
+  const transitive = new Set();
+  const visited    = new Set([startFile]);
+
+  // Level 1 — direct importers
+  const firstLevel = reverseGraph.get(startFile) || [];
+  for (const f of firstLevel) {
+    if (!visited.has(f)) {
+      direct.add(f);
+      visited.add(f);
+    }
+  }
+
+  if (maxDepth === 1) return { direct, transitive };
+
+  // BFS for deeper levels
+  let frontier = [...direct];
+  let depth = 1;
+
+  while (frontier.length > 0 && (maxDepth === 0 || depth < maxDepth)) {
+    const nextFrontier = [];
+    for (const node of frontier) {
+      const importers = reverseGraph.get(node) || [];
+      for (const imp of importers) {
+        if (!visited.has(imp)) {
+          transitive.add(imp);
+          visited.add(imp);
+          nextFrontier.push(imp);
+        }
+      }
+    }
+    frontier = nextFrontier;
+    depth++;
+  }
+
+  return { direct, transitive };
+}
+
+// ---------------------------------------------------------------------------
+// Helper: classify impacted files into tests / routes / other
+// ---------------------------------------------------------------------------
+
+const TEST_PATTERNS = [
+  /[./\\](test|tests|spec|__tests__)[./\\]/,
+  /\.(test|spec)\.[jt]sx?$/,
+  /_test\.[jt]sx?$/,
+  /_test\.py$/,
+  /test_[^/\\]+\.py$/,
+];
+
+const ROUTE_PATTERNS = [
+  /router?\.[jt]sx?$/i,
+  /routes?\.[jt]sx?$/i,
+  /controller\.[jt]sx?$/i,
+  /views?\.[jt]sx?$/i,
+  /handlers?\.[jt]sx?$/i,
+];
+
+function isTestFile(f)  { return TEST_PATTERNS.some((re) => re.test(f.replace(/\\/g, '/'))); }
+function isRouteFile(f) { return ROUTE_PATTERNS.some((re) => re.test(f.replace(/\\/g, '/'))); }
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the impact of changing `changedFile`.
+ *
+ * @param {string} changedFile - absolute or cwd-relative path
+ * @param {{ forward: Map<string,string[]>, reverse: Map<string,string[]> }} graph
+ * @param {object} [opts]
+ * @param {number} [opts.depth=0]   - BFS depth limit (0 = unlimited)
+ * @param {string} [opts.cwd]       - project root for relative path display
+ * @returns {{
+ *   changed:     string,
+ *   direct:      string[],
+ *   transitive:  string[],
+ *   tests:       string[],
+ *   routes:      string[],
+ *   totalImpact: number
+ * }}
+ */
+function getImpact(changedFile, graph, opts) {
+  const { depth = 0, cwd = process.cwd() } = opts || {};
+
+  const absChanged = path.resolve(cwd, changedFile);
+
+  // Bail gracefully if file not in graph
+  if (!graph || !graph.reverse) {
+    return { changed: changedFile, direct: [], transitive: [], tests: [], routes: [], totalImpact: 0 };
+  }
+
+  const { direct, transitive } = bfs(absChanged, graph.reverse, depth);
+
+  const allImpacted = [...direct, ...transitive];
+  const tests  = allImpacted.filter(isTestFile);
+  const routes = allImpacted.filter(isRouteFile);
+
+  const toRel = (f) => path.relative(cwd, f).replace(/\\/g, '/');
+
+  return {
+    changed:     toRel(absChanged),
+    direct:      [...direct].map(toRel),
+    transitive:  [...transitive].map(toRel),
+    tests:       tests.map(toRel),
+    routes:      routes.map(toRel),
+    totalImpact: direct.size + transitive.size,
+  };
+}
+
+/**
+ * Analyse the impact of one or more changed files, building the graph from cwd.
+ * This is the high-level convenience function used by the CLI and MCP tool.
+ *
+ * @param {string|string[]} changedFiles
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {number} [opts.depth=3]
+ * @param {string[]} [opts.srcDirs]
+ * @param {string[]} [opts.exclude]
+ * @returns {{ file: string, impact: object }[]}
+ */
+function analyzeImpact(changedFiles, cwd, opts) {
+  const { depth = 3 } = opts || {};
+  const files = Array.isArray(changedFiles) ? changedFiles : [changedFiles];
+
+  let graph;
+  try {
+    graph = buildFromCwd(cwd, opts);
+  } catch (_) {
+    graph = { forward: new Map(), reverse: new Map() };
+  }
+
+  return files.map((f) => ({
+    file: f,
+    impact: getImpact(f, graph, { depth, cwd }),
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format an impact result as a readable markdown string.
+ *
+ * @param {object} result - return value of getImpact()
+ * @returns {string}
+ */
+function formatImpact(result) {
+  const lines = [];
+  lines.push(`## Impact: \`${result.changed}\``);
+  lines.push('');
+
+  if (result.direct.length === 0 && result.transitive.length === 0) {
+    lines.push('_No files import this file — zero blast radius._');
+    return lines.join('\n');
+  }
+
+  lines.push(`**Total impacted files:** ${result.totalImpact}`);
+  lines.push('');
+
+  if (result.direct.length > 0) {
+    lines.push('### Direct importers');
+    for (const f of result.direct) lines.push(`- \`${f}\``);
+    lines.push('');
+  }
+
+  if (result.transitive.length > 0) {
+    lines.push('### Transitive importers');
+    for (const f of result.transitive) lines.push(`- \`${f}\``);
+    lines.push('');
+  }
+
+  if (result.tests.length > 0) {
+    lines.push('### Affected tests');
+    for (const f of result.tests) lines.push(`- \`${f}\``);
+    lines.push('');
+  }
+
+  if (result.routes.length > 0) {
+    lines.push('### Affected routes / controllers');
+    for (const f of result.routes) lines.push(`- \`${f}\``);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format an impact result as a JSON-serialisable object.
+ *
+ * @param {object} result - return value of getImpact()
+ * @returns {object}
+ */
+function formatImpactJSON(result) {
+  return {
+    changed:     result.changed,
+    direct:      result.direct,
+    transitive:  result.transitive,
+    tests:       result.tests,
+    routes:      result.routes,
+    totalImpact: result.totalImpact,
+  };
+}
+
+module.exports = { getImpact, analyzeImpact, formatImpact, formatImpactJSON };

package/src/mcp/handlers.js

@@ -457,4 +457,24 @@ function queryContext(args, cwd) {
   }
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext };
+/**
+ * get_impact({ file, depth? }) → string
+ *
+ * Returns a formatted markdown impact report for the given file:
+ * direct importers, transitive importers, affected tests, affected routes.
+ */
+function getImpact(args, cwd) {
+  if (!args || !args.file) return 'Missing required argument: file';
+
+  try {
+    const { analyzeImpact, formatImpact } = require('../graph/impact');
+    const depth = Math.max(0, parseInt(args.depth, 10) || 3);
+    const results = analyzeImpact(args.file, cwd, { depth });
+    if (results.length === 0) return `No impact data for: ${args.file}`;
+    return results.map((r) => formatImpact(r.impact)).join('\n\n---\n\n');
+  } catch (err) {
+    return `_get_impact failed: ${err.message}_`;
+  }
+}
+
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact };

package/src/mcp/server.js

@@ -14,11 +14,11 @@
 
 const readline = require('readline');
 const { TOOLS } = require('./tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '2.4.0',
+  version: '2.5.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -74,6 +74,7 @@ function dispatch(msg, cwd) {
       else if (name === 'explain_file') text = explainFile(args, cwd);
       else if (name === 'list_modules') text = listModules(args, cwd);
       else if (name === 'query_context') text = queryContext(args, cwd);
+      else if (name === 'get_impact') text = getImpact(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -144,6 +144,30 @@ const TOOLS = [
       required: ['query'],
     },
   },
+  {
+    name: 'get_impact',
+    description:
+      'Show every file that is impacted when a given file changes — direct importers, ' +
+      'transitive importers, affected tests, and affected routes/controllers. ' +
+      'Gives agents instant blast-radius awareness before making a change. ' +
+      'Handles circular dependencies safely (no infinite loops).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          description:
+            'Relative path from the project root of the file that changed ' +
+            '(e.g. "src/extractors/python.js"). Use forward slashes.',
+        },
+        depth: {
+          type: 'number',
+          description: 'BFS traversal depth limit (default: 3). Use 0 for unlimited.',
+        },
+      },
+      required: ['file'],
+    },
+  },
 ];
 
 module.exports = { TOOLS };