sigmap 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -6,6 +6,61 @@ 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
+- **`packages/core/`** — new `sigmap-core` package exposing a stable programmatic API: `{ extract, rank, buildSigIndex, scan, score }`. Third-party tools can now `require('sigmap')` and use all extraction/retrieval/security/health APIs without spawning a CLI process.
+- **`packages/cli/`** — new `sigmap-cli` thin wrapper that exposes `{ CLI_ENTRY, run }` for programmatic CLI invocation and forward-compat with the v3.0 adapter architecture.
+- **`packages/core/README.md`** — full programmatic API reference with usage examples for all five exported functions.
+- **`exports` field in `package.json`** — `require('sigmap')` resolves to `packages/core/index.js`; `require('sigmap/cli')` resolves to `packages/cli/index.js`.
+- **`test/integration/core-api.test.js`** — 15 integration tests covering: all exports present, `extract` for JS/TS/Python, file-path extension detection, unknown language returns `[]`, never throws on bad input, `rank` with empty map, `rank` sorted shape, `scan` clean/redact, `score` shape, `buildSigIndex` returns Map, CLI `--version` backward compat, CLI `--help` no crash.
+
+### Changed
+- `package.json` `"version"` bumped to `2.4.0`.
+- `package.json` `"files"` — added `"packages/"` so `sigmap-core` and `sigmap-cli` are published with the root package.
+- `gen-context.js` `VERSION` constant bumped to `2.4.0`.
+- `src/mcp/server.js` `SERVER_INFO.version` bumped to `2.4.0`.
+
+### Validation gate
+- 21/21 extractor unit tests passed
+- 21/21 integration suites passed (0 failures, including new `core-api.test.js`)
+- `node gen-context.js --version` → `2.4.0`
+- `node -e "const { extract } = require('.'); console.log(extract('function hello(){}', 'javascript').length > 0 ? 'OK' : 'FAIL')"` → `OK`
+- `require('sigmap')` works from any directory
+
+---
+
 ## [2.3.0] — 2026-04-07
 
 ### 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-262%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)
 
@@ -41,7 +41,7 @@
 | [VS Code extension](#-vs-code-extension) | Status bar, stale alerts, commands |
 | [Languages supported](#-languages-supported) | 21 languages |
 | [Context strategies](#-context-strategies) | full / per-module / hot-cold |
-| [MCP server](#-mcp-server) | 7 on-demand tools |
+| [MCP server](#-mcp-server) | 8 on-demand tools |
 | [CLI reference](#-cli-reference) | All flags |
 | [Configuration](#-configuration) | Config file + .contextignore |
 | [Observability](#-observability) | Health score, reports, CI |
@@ -86,20 +86,49 @@ AI agent session starts with full context
 
 ---
 
-## 🆕 What's new in 2.0
+## 🔭 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 |
 |---|---|
-| **Enriched signatures** | Return types, type hints, and schema field collapse (Python `@dataclass` / `BaseModel`) |
-| **Dependency map** | Compact import dependency section at the top of output (~50–100 extra tokens) |
-| **TODO/FIXME section** | Auto-harvested TODO/FIXME/HACK/XXX comments (max 20 entries) |
-| **Recent changes section** | Git-based recent changes summary in output |
-| **Test coverage markers** | Per-function `✓`/`✗` hints by scanning test directories |
-| **Structural diff mode** | `--diff <base-ref>` writes a signature-level diff section |
-| **Impact radius hints** | Reverse dependency annotations (used by: ...) |
-| **New helper extractors** | `deps.js`, `todos.js`, `coverage.js`, `prdiff.js` |
+| **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 |
 
-Several v2 enhancements (deps map, TODOs, recent changes) are enabled by default. All v2 sections can be tuned or disabled via `gen-context.config.json`.
+## 🆕 What's new in 2.3
+
+| Feature | Description |
+|---|---|
+| **`--query "<text>"` CLI** | Rank all context files by relevance to a free-text query — scored table + top-3 signature blocks |
+| **`--query --json`** | Machine-readable ranked results (`{ query, results[], totalResults }`) |
+| **`--query --top <n>`** | Limit results (default 10, configurable via `retrieval.topK`) |
+| **`query_context` MCP tool** | 8th MCP tool — `{ query, topK? }` returns ranked file list, usable live in any MCP session |
+| **`--analyze` / `--diagnose-extractors`** | Per-file breakdown of sigs/tokens/extractor/coverage; self-tests all 21 extractors (v2.2) |
+| **`--benchmark` / `--eval`** | Measure hit@5 and MRR retrieval quality against a JSONL task file (v2.1) |
+
+> **Previous v2.0 additions:** enriched signatures, dependency map, TODO/FIXME section, test coverage markers, structural diff mode, impact radius hints. See [CHANGELOG.md](CHANGELOG.md) for the full history.
 
 ---
 
@@ -258,7 +287,7 @@ Recently committed files are **hot** (auto-injected). Everything else is **cold*
 
 ## 🔌 MCP server
 
-> Introduced in v0.3, expanded to 7 tools through v1.4.
+> Introduced in v0.3, expanded to 8 tools through v2.3.
 
 Start the MCP server on stdio:
 
@@ -277,6 +306,7 @@ node gen-context.js --mcp
 | `list_modules` | — | Token-count table of all top-level module directories |
 | `create_checkpoint` | `{ summary: string }` | Write a session checkpoint to `.context/` |
 | `get_routing` | — | Full model routing table |
+| `query_context` | `{ query: string, topK?: number }` | Files ranked by relevance to the query (v2.3) |
 
 Reads files on every call — no stale state, no restart needed.
 
@@ -296,6 +326,19 @@ node gen-context.js --diff                    Generate context for git-changed f
 node gen-context.js --diff --staged           Staged files only (pre-commit check)
 node gen-context.js --mcp                     Start MCP server on stdio
 
+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 --analyze                 Per-file breakdown (sigs / tokens / extractor / coverage)
+node gen-context.js --analyze --json          Analysis as JSON
+node gen-context.js --analyze --slow          Include extraction timing per file
+node gen-context.js --diagnose-extractors     Self-test all 21 extractors against fixtures
+
+node gen-context.js --benchmark               Run retrieval quality benchmark (hit@5 / MRR)
+node gen-context.js --benchmark --json        Benchmark results as JSON
+node gen-context.js --eval                    Alias for --benchmark
+
 node gen-context.js --report                  Token reduction stats
 node gen-context.js --report --json           Structured JSON report (exits 1 if over budget)
 node gen-context.js --report --history        Usage log summary
@@ -435,6 +478,31 @@ node gen-context.js --format cache
 
 ---
 
+## 📦 Programmatic API (v2.4+)
+
+Use SigMap as a library — no CLI subprocess needed:
+
+```js
+const { extract, rank, buildSigIndex, scan, score } = require('sigmap');
+
+// Extract signatures from source code
+const sigs = extract('function hello() {}', 'javascript');
+
+// Build an index and rank files by query
+const index = buildSigIndex('/path/to/project');
+const results = rank('authentication middleware', index);
+
+// Scan signatures for secrets before storing
+const { safe, redacted } = scan(sigs, 'src/config.ts');
+
+// Get a composite health score for a project
+const health = score('/path/to/project');
+```
+
+📖 Full API reference: [packages/core/README.md](packages/core/README.md)
+
+---
+
 ## 🧪 Testing
 
 ```bash
@@ -464,7 +532,7 @@ grep "require(" gen-context.js | grep -v "^.*//.*require"
 
 # Gate 3 — MCP server responds correctly
 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node gen-context.js --mcp
-# Expected: valid JSON with 7 tools
+# Expected: valid JSON with 8 tools
 
 # Gate 4 — npm artifact is clean
 npm pack --dry-run
@@ -481,9 +549,16 @@ sigmap/
 ├── gen-context.js               ← PRIMARY ENTRY POINT — single file, zero deps
 ├── gen-project-map.js           ← import graph, class hierarchy, route table
 │
+├── packages/
+│   ├── core/                    ← programmatic API — require('sigmap') (v2.4)
+│   │   └── index.js             ← extract, rank, buildSigIndex, scan, score
+│   └── cli/                     ← thin CLI wrapper / v3 compat shim (v2.4)
+│
 ├── src/
 │   ├── extractors/              ← 21 language extractors (one file per language)
-│   ├── mcp/                     ← MCP stdio server — 7 tools
+│   ├── retrieval/               ← query-aware ranker + tokenizer (v2.3)
+│   ├── eval/                    ← benchmark runner + scorer (v2.1), analyzer (v2.2)
+│   ├── mcp/                     ← MCP stdio server — 8 tools
 │   ├── security/                ← secret scanner — 10 patterns
 │   ├── routing/                 ← model routing hints
 │   ├── tracking/                ← NDJSON usage logger
@@ -499,7 +574,7 @@ sigmap/
 │   ├── fixtures/                ← one source file per language
 │   ├── expected/                ← expected extractor output
 │   ├── run.js                   ← zero-dep test runner
-│   └── integration/             ← 17 integration test files (241 tests)
+│   └── integration/             ← 20 integration test files (304 tests)
 │
 ├── docs/                        ← documentation site (GitHub Pages)
 │   ├── index.html               ← homepage

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.3.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,8 +1,13 @@
 {
   "name": "sigmap",
-  "version": "2.3.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": {
+    ".": "./packages/core/index.js",
+    "./cli": "./packages/cli/index.js",
+    "./core": "./packages/core/index.js"
+  },
   "bin": {
     "sigmap": "./gen-context.js",
     "gen-context": "./gen-context.js",
@@ -26,6 +31,7 @@
     "gen-context.js",
     "gen-project-map.js",
     "src/",
+    "packages/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/packages/cli/index.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * sigmap-cli — thin CLI wrapper around sigmap-core.
+ *
+ * This module is required by the root gen-context.js entry point.
+ * All --flag handling lives here; business logic lives in src/ or packages/core.
+ *
+ * NOTE: This file intentionally does NOT duplicate business logic.
+ * It re-exports the entry-point function from gen-context.js so that
+ * `require('sigmap-cli')` can be used by tooling that wraps SigMap.
+ *
+ * In v2.4 the root gen-context.js is kept fully intact for backward compat.
+ * packages/cli is a forward-compat shim for the v3.0 adapter architecture.
+ */
+
+const path = require('path');
+
+/**
+ * The CLI entry point path.
+ * External tools can use this to spawn the CLI as a child process.
+ */
+const CLI_ENTRY = path.resolve(__dirname, '..', '..', 'gen-context.js');
+
+/**
+ * Run the SigMap CLI programmatically with the given argv array.
+ *
+ * @param {string[]} [argv]  - Arguments to pass (default: process.argv)
+ * @param {string}   [cwd]   - Working directory (default: process.cwd())
+ * @returns {void}
+ *
+ * @example
+ *   const { run } = require('sigmap-cli');
+ *   run(['--report'], '/path/to/project');
+ */
+function run(argv, cwd) {
+  const origArgv = process.argv;
+  const origCwd = process.cwd();
+
+  if (cwd) {
+    try { process.chdir(cwd); } catch (_) {}
+  }
+
+  if (argv) {
+    process.argv = [process.argv[0], CLI_ENTRY, ...argv];
+  }
+
+  try {
+    require(CLI_ENTRY);
+  } finally {
+    process.argv = origArgv;
+    if (cwd) {
+      try { process.chdir(origCwd); } catch (_) {}
+    }
+  }
+}
+
+module.exports = {
+  /** Absolute path to the gen-context.js entry point */
+  CLI_ENTRY,
+  /** Run the SigMap CLI programmatically */
+  run,
+};

package/packages/cli/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "sigmap-cli",
+  "version": "2.4.0",
+  "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
+  "main": "index.js",
+  "keywords": [
+    "sigmap",
+    "cli",
+    "ai-context",
+    "code-signatures"
+  ],
+  "author": {
+    "name": "Manoj Mallick",
+    "url": "https://github.com/manojmallick"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manojmallick/sigmap.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://manojmallick.github.io/sigmap/",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}