universal-ast-mapper 1.25.0 → 1.27.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.27.0] — 2026-06-11 · Test-coverage mapping
+- **New MCP tool `get_test_coverage`** + **CLI `ast-map tests [dir]`** (alias
+  `coverage`) — structural test coverage with zero instrumentation: which source
+  files have tests at all, and which have **none**.
+- Two pairing signals:
+  - **import** — a test file imports the source file (graph edge; definitive).
+  - **name** — conventions: `auth.test.ts` → `auth.ts`, `auth_test.go`,
+    `test_utils.py` → `utils.py`, `AuthTest.java` → `Auth.java`,
+    `foo-smoke.mjs` → `foo.*`, and bare `test/<name>.*` → `<name>.*`;
+    ambiguity resolved by longest shared path prefix.
+- Test files detected by directory (`test/`, `tests/`, `__tests__/`, `spec/`, `e2e/`)
+  or basename pattern; **fixtures/mocks/testdata dirs excluded from both sides**.
+- Output: coverage ratio, test→source `links` (with `via`), `tested`,
+  **`untested` ranked by risk** (fan-in Ca, then symbol count — load-bearing
+  files with no tests first), and `orphanTests` (no source matched; usually
+  integration/e2e).
+- CLI: `-u/--untested`, `--links`, `-n/--top`, `--json`.
+- New module `testmap` (`mapTestCoverage`, `isTestFile`, `testNameTarget`,
+  `isFixtureFile`) + `test/fixtures/testmap/` fixture tree. Tests: +9 checks
+  in `test/analysis.mjs` (153 total). **30 MCP tools / 32 CLI commands.**
+
+## [1.26.0] — 2026-06-11 · Coupling overlay in the explorer
+- **`ast-map explore` color modes** — new toolbar dropdown: `color: folder`
+  (existing per-directory hues) or **`color: coupling`** — nodes shaded by
+  **instability** I = Ce/(Ca+Ce) on a green (0, stable) → yellow → red
+  (1, volatile) scale; orphan files stay gray.
+- **Legend** (bottom-left, shown in coupling mode) explains the scale; the hover
+  tooltip and the detail sidebar now show **Ca / Ce / I** per file.
+- Explorer nodes carry `ca` / `ce` / `inst` computed from the deduped file-level
+  import edges — same definition as `get_coupling` (Robert C. Martin metrics).
+- Still a single self-contained HTML file, dark-mode aware, zero dependencies.
+- Tests: +5 checks in `test/analysis.mjs` (144 total).
+
 ## [1.25.0] — 2026-06-11 · Semantic symbol search
 - **New MCP tool `semantic_search`** + **CLI `ast-map find <query> [dir]`** — find
   symbols by *meaning*, not exact name: "remove expired cache entries" →

package/README.md

@@ -4,7 +4,7 @@ An **MCP server + CLI tool** that turns source code into structured, machine-rea
 
 Built on [tree-sitter](https://tree-sitter.github.io/) WASM grammars. Zero regex guessing — real AST parsing.
 
-**29 MCP tools / 31 CLI commands / 5 MCP prompts** spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators — plus monorepo support, an interactive **graph explorer** (`ast-map explore`), **watch mode**, a one-page **health dashboard** (`ast-map report`), a **persistent parse cache + parallel parsing** (warm re-scans skip parsing entirely), and a **CI quality gate** (`ast-map check`, baseline ratchet).
+**30 MCP tools / 32 CLI commands / 5 MCP prompts** spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators, test-coverage mapping — plus monorepo support, an interactive **graph explorer** with a **coupling overlay** (`ast-map explore`), **watch mode**, a one-page **health dashboard** (`ast-map report`), a **persistent parse cache + parallel parsing** (warm re-scans skip parsing entirely), and a **CI quality gate** (`ast-map check`, baseline ratchet).
 
 **Supported languages:** TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go · Rust · Java · C# · C · C++ · Kotlin · Swift · Vue · Svelte (SFC `<script>`) · **PHP** · **Ruby**
 
@@ -128,6 +128,7 @@ ast-map cache     [stats|clear]                  # persistent parse cache (.ast-
 ast-map check     [dir]            [--update-baseline] [--min-score N] [--max-cycles N] ...
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map find     <query> [dir]     [-l N] [-k kind] [-e]   # semantic: by meaning
+ast-map tests    [dir]             [alias: coverage] [-u] [--links] [-n N]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
 ast-map impact   <file> <symbol>   [--scan <dir>]
@@ -159,6 +160,9 @@ ast-map search handler src/ --exported
 # Don't know the name? Search by meaning
 ast-map find "remove expired cache entries" src/
 
+# Which source files have no tests at all?
+ast-map tests . --untested
+
 # What does this file import / what imports it?
 ast-map deps src/lib/auth.ts --scan src/
 
@@ -533,6 +537,17 @@ semantic_search("find unused exported code") →
 
 ---
 
+### `get_test_coverage`
+Structural test coverage: pair test files with the source files they exercise, and list source files **no test touches** — no instrumentation or test runner needed, works on a cold checkout.
+
+Two signals: a test file *importing* a source file (definitive), and naming conventions (`auth.test.ts` → `auth.ts`, `test_utils.py` → `utils.py`, `FooTest.java` → `Foo.java`, `test/<name>.*` → `<name>.*`). Fixture/mock directories are excluded from both sides. Untested files are ranked by risk (fan-in, then symbol count); unmatched test files are reported as `orphanTests` (usually integration/e2e).
+
+> File-level coverage ("does anything test this file?"), not line coverage.
+
+**Params:** `path`, `untestedOnly`
+
+---
+
 ### `get_file_deps`
 For a single file, show what it imports and what imports it (with symbol names).  
 More focused than `build_symbol_graph` — use for quick dependency lookup.
@@ -820,6 +835,8 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.27.0** | **Test-coverage mapping** — new MCP tool `get_test_coverage` + CLI `ast-map tests` (alias `coverage`): pairs test files with the sources they exercise (import edges + naming conventions) and lists **untested sources ranked by risk** (fan-in, then symbols). Fixture dirs excluded; orphan tests reported. File-level, zero instrumentation. (**30 tools / 32 commands**) |
+| **1.26.0** | **Coupling overlay in the explorer** — `ast-map explore` gains a `color: coupling` mode: nodes shaded by **instability** I = Ce/(Ca+Ce) on a green (stable) → red (volatile) scale, with a legend, and Ca / Ce / I readouts in the hover tooltip and detail sidebar. Spot load-bearing files and volatile hotspots at a glance. |
 | **1.25.0** | **Semantic symbol search** — new MCP tool `semantic_search` + CLI `ast-map find <query>`: find symbols by *meaning* ("remove expired sessions" → `clearDiskCache`). Identifier tokenization + 60-group programming thesaurus + stemming + fuzzy matching + BM25-style IDF ranking over names, docs, signatures and paths. No embeddings, no network. (**29 tools / 31 commands**) |
 | **1.24.0** | **TS path-alias resolution** — bare imports like `@/components/Button` now resolve via the **nearest** `tsconfig.json`/`jsconfig.json` (`compilerOptions.paths` + `baseUrl`, relative `extends` chains, longest-prefix matching, string-aware JSONC parser). Wired into `resolve_imports`, the symbol graph, and the call graph — on a real Next.js app this took the import graph from 31 to **324 edges** and cut false dead-exports by ~30%. |
 | **1.23.0** | **Configurable root boundary** — `AST_MAP_ROOT` accepts **multiple roots** (path-delimiter separated) and `AST_MAP_UNLOCKED=1` allows analyzing **any absolute path** on request (default stays locked). Analysis/graph/report rel-paths now computed against the matched root, so cross-root results are correct. New `roots` module + 13-check test suite. |

package/dist/cli.js

@@ -28,6 +28,7 @@ import { computeModuleCoupling } from "./modulecoupling.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 import { semanticSearch } from "./semantic.js";
+import { mapTestCoverage } from "./testmap.js";
 import { parseRootsFromEnv } from "./roots.js";
 const ROOT = parseRootsFromEnv().roots[0]; // CLI is local — no boundary, primary root only
 // Persistent parse cache (disable with AST_MAP_NO_CACHE=1 or "cache": false in config).
@@ -1130,6 +1131,47 @@ program
     }
     console.log();
 });
+// ─── Command: tests (coverage map) ───────────────────────────────────────────
+program
+    .command("tests [dir]")
+    .alias("coverage")
+    .description("Map test files to the sources they cover; list untested sources")
+    .option("-u, --untested", "Only show untested source files")
+    .option("--links", "Show every test→source link")
+    .option("-n, --top <n>", "Max untested files to show", (v) => parseInt(v, 10), 25)
+    .option("--json", "Output as JSON")
+    .action(async (dir, opts) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const skeletons = await gatherSkeletons(abs);
+    const map = mapTestCoverage(buildSymbolGraph(skeletons, ROOT));
+    if (opts.json)
+        return jsonOut({ directory: rel, ...map });
+    header(`Test Coverage — ${rel}/  ${dim(`(${map.testFiles} test files · ${map.sourceFiles} sources)`)}`);
+    const pct = Math.round(map.coverageRatio * 100);
+    const pcolor = pct >= 70 ? green : pct >= 40 ? yellow : red;
+    console.log(indent(`${bold("Covered:")} ${pcolor(`${map.testedSources}/${map.sourceFiles} (${pct}%)`)} of source files have at least one test`));
+    if (!opts.untested && opts.links && map.links.length > 0) {
+        console.log(`\n${indent(bold("Links:"))}`);
+        table(map.links.map((l) => [l.via === "import" ? green(l.via) : yellow(l.via), l.test, "→ " + l.source]), [["Via", 7], ["Test", 38], ["Source", 40]]);
+    }
+    if (map.untested.length > 0) {
+        console.log(`\n${indent(`${bold("Untested sources")} ${dim("(by risk: fan-in, then symbols)")}`)}`);
+        table(map.untested.slice(0, opts.top).map((u) => [String(u.afferent), String(u.symbols), u.file]), [["Ca", 4], ["Syms", 5], ["File", 52]]);
+        if (map.untested.length > opts.top)
+            console.log(indent(dim(`… ${map.untested.length - opts.top} more (use -n)`)));
+    }
+    else if (map.sourceFiles > 0) {
+        console.log(indent(green("✓ every source file has at least one test")));
+    }
+    if (!opts.untested && map.orphanTests.length > 0) {
+        console.log(`\n${indent(`${bold("Orphan tests")} ${dim("(no source matched — integration/e2e?)")}`)}`);
+        for (const t of map.orphanTests.slice(0, 10))
+            console.log(indent(dim(t), 4));
+    }
+    console.log();
+});
 // ─── Command: deps ────────────────────────────────────────────────────────────
 program
     .command("deps <file>")

package/dist/explorer.js

@@ -20,7 +20,7 @@ function deriveFileGraph(graph) {
             continue;
         const f = n;
         const parts = f.id.split("/");
-        nodes.push({ id: f.id, symbols: f.symbolCount, group: parts.length > 1 ? parts[0] : "(root)", lang: f.language, syms: fileSyms.get(f.id) ?? [] });
+        nodes.push({ id: f.id, symbols: f.symbolCount, group: parts.length > 1 ? parts[0] : "(root)", lang: f.language, syms: fileSyms.get(f.id) ?? [], ca: 0, ce: 0, inst: 0 });
     }
     const seen = new Set();
     const links = [];
@@ -37,6 +37,18 @@ function deriveFileGraph(graph) {
         seen.add(key);
         links.push({ source: e.from, target: toFile });
     }
+    // Per-file coupling (Ca = fan-in, Ce = fan-out, I = Ce/(Ca+Ce)) from the deduped links.
+    const outSet = new Map();
+    const inSet = new Map();
+    for (const l of links) {
+        (outSet.get(l.source) ?? outSet.set(l.source, new Set()).get(l.source)).add(l.target);
+        (inSet.get(l.target) ?? inSet.set(l.target, new Set()).get(l.target)).add(l.source);
+    }
+    for (const n of nodes) {
+        n.ce = outSet.get(n.id)?.size ?? 0;
+        n.ca = inSet.get(n.id)?.size ?? 0;
+        n.inst = n.ca + n.ce === 0 ? 0 : Math.round((n.ce / (n.ca + n.ce)) * 100) / 100;
+    }
     return { nodes, links };
 }
 const STYLE = "body{margin:0;font-family:system-ui,sans-serif;color:#222;background:#fafafa}" +
@@ -51,7 +63,10 @@ const STYLE = "body{margin:0;font-family:system-ui,sans-serif;color:#222;backgro
     "#panel .row{padding:3px 6px;border-radius:5px;cursor:pointer;word-break:break-all;line-height:1.5}#panel .row:hover{background:#f0f0f0}" +
     "#panel .sym{color:#444;padding:2px 6px;word-break:break-all}#panel .k{color:#999;font-size:11px}" +
     "#close{position:absolute;top:10px;right:12px;cursor:pointer;color:#999;font-size:18px;line-height:1;border:none;background:none}" +
-    "@media(prefers-color-scheme:dark){body{color:#ddd;background:#161616}#bar,#panel{background:#1e1e1e;border-color:#333}#q{background:#2a2a2a;border-color:#444;color:#ddd}#panel .row:hover{background:#2a2a2a}#panel .sym{color:#bbb}}";
+    "#mode{padding:5px 8px;border:1px solid #ddd;border-radius:6px;font-size:12px;background:#fff;color:#222}" +
+    "#leg{position:fixed;left:14px;bottom:14px;z-index:3;background:#fff;border:1px solid #e5e5e5;border-radius:8px;padding:8px 12px;font-size:11px;color:#555;display:none}" +
+    "#leg .bar{width:150px;height:8px;border-radius:4px;background:linear-gradient(90deg,hsl(120,65%,46%),hsl(60,75%,50%),hsl(0,70%,52%));margin:5px 0 3px}" +
+    "@media(prefers-color-scheme:dark){body{color:#ddd;background:#161616}#bar,#panel{background:#1e1e1e;border-color:#333}#q{background:#2a2a2a;border-color:#444;color:#ddd}#panel .row:hover{background:#2a2a2a}#panel .sym{color:#bbb}#mode{background:#2a2a2a;border-color:#444;color:#ddd}#leg{background:#1e1e1e;border-color:#333;color:#bbb}}";
 const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=document.getElementById('tip'),panel=document.getElementById('panel');" +
     "var PANELW=300,panelOpen=false;" +
     "var W,H;function resize(){var r=devicePixelRatio||1;W=innerWidth||c.clientWidth||800;H=(innerHeight-48)||c.clientHeight||600;c.width=W*r;c.height=H*r;ctx.setTransform(r,0,0,r,0,0);}addEventListener('resize',function(){resize();});resize();" +
@@ -62,7 +77,8 @@ const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=d
     "sim.forEach(function(n){n.x=W/2+(Math.random()-0.5)*240;n.y=H/2+(Math.random()-0.5)*240;});" +
     "var groups={},gi=0;function color(g){if(groups[g]==null)groups[g]=gi++;return 'hsl('+((groups[g]*67)%360)+',58%,55%)';}" +
     "var adj={};links.forEach(function(l){(adj[l.source]=adj[l.source]||[]).push(l.target);(adj[l.target]=adj[l.target]||[]).push(l.source);});" +
-    "var view={x:0,y:0,k:1},sel=null,hover=null,drag=null,pan=null,q='',autofit=true;" +
+    "var view={x:0,y:0,k:1},sel=null,hover=null,drag=null,pan=null,q='',autofit=true,mode='group';" +
+    "function instColor(i){return 'hsl('+Math.round((1-i)*120)+',65%,'+Math.round(46+i*8)+'%)';}" +
     "function radius(n){return 4+Math.sqrt(n.symbols||0)*1.7;}" +
     "function tick(){if(!sim.length)return;var k=0.0016;for(var i=0;i<sim.length;i++){var a=sim[i];a.vx+=(W/2-a.x)*k;a.vy+=(H/2-a.y)*k;for(var j=i+1;j<sim.length;j++){var b=sim[j];var dx=a.x-b.x,dy=a.y-b.y,d2=dx*dx+dy*dy;if(d2<100)d2=100;var d=Math.sqrt(d2),f=2200/d2,fx=f*dx/d,fy=f*dy/d;a.vx+=fx;a.vy+=fy;b.vx-=fx;b.vy-=fy;}}" +
     "links.forEach(function(l){var a=byId[l.source],b=byId[l.target];if(!a||!b)return;var dx=b.x-a.x,dy=b.y-a.y,d=Math.sqrt(dx*dx+dy*dy)+0.01,f=(d-90)*0.02,fx=f*dx/d,fy=f*dy/d;a.vx+=fx;a.vy+=fy;b.vx-=fx;b.vy-=fy;});" +
@@ -74,12 +90,12 @@ const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=d
     "function esc(t){return String(t).replace(/&/g,'&amp;').replace(/</g,'&lt;');}" +
     "function rowList(ids){if(!ids||!ids.length)return '<div class=\"sym\" style=\"color:#aaa\">none</div>';return ids.slice().sort().map(function(id){return '<div class=\"row\" data-id=\"'+esc(id)+'\">'+esc(id)+'</div>';}).join('');}" +
     "function showPanel(n){sel=n;panelOpen=true;var imp=out[n.id]||[],impBy=inn[n.id]||[];var syms=(n.syms||[]).map(function(s){var i=s.indexOf(' ');return '<div class=\"sym\"><span class=\"k\">'+esc(s.slice(0,i))+'</span> '+esc(s.slice(i+1))+'</div>';}).join('')||'<div class=\"sym\" style=\"color:#aaa\">none</div>';" +
-    "panel.innerHTML='<button id=\"close\">&times;</button>'+'<h2>'+esc(n.id.split('/').pop())+'</h2><div class=\"path\">'+esc(n.id)+'</div>'+'<div class=\"meta\">'+esc(n.lang)+' &middot; '+(n.symbols||0)+' symbols'+(deg[n.id]?'':' &middot; no in-scope deps')+'</div>'+'<h3>Imports ('+imp.length+')</h3>'+rowList(imp)+'<h3>Imported by ('+impBy.length+')</h3>'+rowList(impBy)+'<h3>Symbols</h3>'+syms;" +
+    "panel.innerHTML='<button id=\"close\">&times;</button>'+'<h2>'+esc(n.id.split('/').pop())+'</h2><div class=\"path\">'+esc(n.id)+'</div>'+'<div class=\"meta\">'+esc(n.lang)+' &middot; '+(n.symbols||0)+' symbols'+(deg[n.id]?' &middot; Ca '+(n.ca||0)+' &middot; Ce '+(n.ce||0)+' &middot; I '+(n.inst||0):' &middot; no in-scope deps')+'</div>'+'<h3>Imports ('+imp.length+')</h3>'+rowList(imp)+'<h3>Imported by ('+impBy.length+')</h3>'+rowList(impBy)+'<h3>Symbols</h3>'+syms;" +
     "panel.style.display='block';}" +
     "panel.addEventListener('click',function(e){if(e.target.id==='close'){panelOpen=false;sel=null;panel.style.display='none';autofit=true;return;}var id=e.target.getAttribute('data-id');if(id&&byId[id]){showPanel(byId[id]);center(byId[id]);}});" +
     "function draw(){ctx.clearRect(0,0,W,H);ctx.save();ctx.translate(view.x,view.y);ctx.scale(view.k,view.k);ctx.lineWidth=0.8;" +
     "links.forEach(function(l){var a=byId[l.source],b=byId[l.target];if(!a||!b)return;var on=sel&&(l.source===sel.id||l.target===sel.id);ctx.strokeStyle=on?'rgba(110,110,240,0.9)':'rgba(150,150,150,0.18)';ctx.beginPath();ctx.moveTo(a.x,a.y);ctx.lineTo(b.x,b.y);ctx.stroke();});" +
-    "function dot(n,orphan){var dim=(sel&&n!==sel&&(adj[sel.id]||[]).indexOf(n.id)<0)||(q&&n.id.toLowerCase().indexOf(q)<0);ctx.globalAlpha=dim?0.14:(orphan?0.55:1);ctx.beginPath();ctx.arc(n.x,n.y,orphan?3.2:radius(n),0,6.2832);ctx.fillStyle=color(n.group);ctx.fill();if(n===sel||n===hover){ctx.lineWidth=2;ctx.strokeStyle='#fff';ctx.stroke();ctx.lineWidth=0.8;}}" +
+    "function dot(n,orphan){var dim=(sel&&n!==sel&&(adj[sel.id]||[]).indexOf(n.id)<0)||(q&&n.id.toLowerCase().indexOf(q)<0);ctx.globalAlpha=dim?0.14:(orphan?0.55:1);ctx.beginPath();ctx.arc(n.x,n.y,orphan?3.2:radius(n),0,6.2832);ctx.fillStyle=mode==='inst'?(deg[n.id]?instColor(n.inst):'#999'):color(n.group);ctx.fill();if(n===sel||n===hover){ctx.lineWidth=2;ctx.strokeStyle='#fff';ctx.stroke();ctx.lineWidth=0.8;}}" +
     "orphans.forEach(function(n){dot(n,true);});sim.forEach(function(n){dot(n,false);});" +
     "ctx.globalAlpha=1;ctx.fillStyle=getComputedStyle(document.body).color;ctx.font='11px system-ui';sim.forEach(function(n){if(n===sel||n===hover||n.symbols>=14){ctx.fillText(n.id.split('/').pop(),n.x+radius(n)+3,n.y+3);}});ctx.restore();}" +
     "function loop(){var w=innerWidth,hh=innerHeight-48;if(w&&hh&&(w!==W||hh!==H))resize();tick();tick();layoutOrphans();if(autofit)fitView();draw();var bx=bb4(nodes);document.getElementById(\"dbg\").textContent=\"W=\"+W+\" H=\"+H+\" iw=\"+innerWidth+\"x\"+innerHeight+\" dpr=\"+(devicePixelRatio||1)+\" k=\"+view.k.toFixed(2)+\" vx=\"+Math.round(view.x)+\" vy=\"+Math.round(view.y)+\" fit=\"+autofit+\" sim=\"+sim.length+\" orph=\"+orphans.length+\" worldBox=\"+Math.round(bx[0])+\",\"+Math.round(bx[1])+\"..\"+Math.round(bx[2])+\",\"+Math.round(bx[3]);requestAnimationFrame(loop);}" +
@@ -87,10 +103,11 @@ const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=d
     "function pick(p){var all=sim.concat(orphans);for(var i=all.length-1;i>=0;i--){var n=all[i];var r=(deg[n.id]?radius(n):3.2)+5;if((p.x-n.x)*(p.x-n.x)+(p.y-n.y)*(p.y-n.y)<=r*r)return n;}return null;}" +
     "c.addEventListener('mousedown',function(e){autofit=false;var n=pick(world(e));if(n){drag=n;showPanel(n);}else{pan={x:e.clientX-view.x,y:e.clientY-view.y};}});" +
     "c.addEventListener('dblclick',function(){panelOpen=false;sel=null;panel.style.display='none';autofit=true;});" +
-    "addEventListener('mousemove',function(e){var p=world(e);if(drag){drag.x=p.x;drag.y=p.y;drag.vx=0;drag.vy=0;}else if(pan){view.x=e.clientX-pan.x;view.y=e.clientY-pan.y;}else{hover=pick(p);if(hover){tip.style.display='block';tip.style.left=(e.clientX+12)+'px';tip.style.top=(e.clientY+12)+'px';tip.textContent=hover.id+'  ·  '+(hover.symbols||0)+' symbols  ·  '+hover.lang;}else tip.style.display='none';}});" +
+    "addEventListener('mousemove',function(e){var p=world(e);if(drag){drag.x=p.x;drag.y=p.y;drag.vx=0;drag.vy=0;}else if(pan){view.x=e.clientX-pan.x;view.y=e.clientY-pan.y;}else{hover=pick(p);if(hover){tip.style.display='block';tip.style.left=(e.clientX+12)+'px';tip.style.top=(e.clientY+12)+'px';tip.textContent=hover.id+'  ·  '+(hover.symbols||0)+' symbols  ·  '+hover.lang+(deg[hover.id]?'  ·  Ca '+hover.ca+' Ce '+hover.ce+' I '+hover.inst:'');}else tip.style.display='none';}});" +
     "addEventListener('mouseup',function(){drag=null;pan=null;});" +
     "c.addEventListener('wheel',function(e){e.preventDefault();autofit=false;var s=e.deltaY<0?1.1:0.9;var mx=e.clientX,my=e.clientY-48;view.x=mx-(mx-view.x)*s;view.y=my-(my-view.y)*s;view.k*=s;},{passive:false});" +
     "document.getElementById('q').addEventListener('input',function(e){q=e.target.value.toLowerCase();});" +
+    "document.getElementById('mode').addEventListener('change',function(e){mode=e.target.value;document.getElementById('leg').style.display=mode==='inst'?'block':'none';});" +
     "addEventListener('keydown',function(e){if(e.key==='d'&&e.target.tagName!=='INPUT'){var x=document.getElementById('dbg');x.style.display=x.style.display==='none'?'block':'none';}});loop();";
 /** Build a self-contained, dependency-free HTML graph explorer. */
 export function buildExplorerHtml(graph, root) {
@@ -100,7 +117,7 @@ export function buildExplorerHtml(graph, root) {
     return ("<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">" +
         "<title>AST-MCP — " + title + " graph</title><style>" + STYLE + "</style></head><body>" +
         "<div id=\"bar\"><h1>AST-MCP graph</h1><span class=\"muted\">" + data.nodes.length + " files · " + data.links.length + " edges · drag / scroll / click</span>" +
-        "<input id=\"q\" placeholder=\"filter files…\" /></div>" +
-        "<canvas id=\"cv\"></canvas><div id=\"tip\"></div><div id=\"panel\"></div><div id=\"dbg\" style=\"position:fixed;left:8px;bottom:8px;font:11px monospace;color:#e07;z-index:6;pointer-events:none;white-space:pre;display:none\"></div>" +
+        "<input id=\"q\" placeholder=\"filter files…\" /><select id=\"mode\"><option value=\"group\">color: folder</option><option value=\"inst\">color: coupling</option></select></div>" +
+        "<canvas id=\"cv\"></canvas><div id=\"tip\"></div><div id=\"panel\"></div><div id=\"leg\"><b>Instability I = Ce/(Ca+Ce)</b><div class=\"bar\"></div><div style=\"display:flex;justify-content:space-between\"><span>0 = stable</span><span>1 = volatile</span></div></div><div id=\"dbg\" style=\"position:fixed;left:8px;bottom:8px;font:11px monospace;color:#e07;z-index:6;pointer-events:none;white-space:pre;display:none\"></div>" +
         "<script>var DATA=" + dataJson + ";</script><script>" + CLIENT + "</script></body></html>");
 }

package/dist/index.js

@@ -18,6 +18,7 @@ import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTop
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 import { semanticSearch } from "./semantic.js";
+import { mapTestCoverage } from "./testmap.js";
 import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
@@ -1191,6 +1192,45 @@ server.registerTool("semantic_search", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: get_test_coverage ───────────────────────────── */
+server.registerTool("get_test_coverage", {
+    title: "Test-coverage map (tests ↔ sources)",
+    description: "Structural test coverage: pair test files with the source files they exercise and list " +
+        "source files no test touches. Two signals: a test file *importing* a source file " +
+        "(definitive) and naming conventions (auth.test.ts → auth.ts, test_utils.py → utils.py). " +
+        "No instrumentation or test runner needed. Untested files are ranked by risk " +
+        "(fan-in, then symbol count). This is file-level coverage, not line coverage.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan (should include the test files). Default project root."),
+        untestedOnly: z.boolean().optional().describe("Return only the untested-sources list. Default false."),
+    },
+}, async ({ path: input, untestedOnly }) => {
+    try {
+        const { abs, rel, root } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. get_test_coverage requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const skels = [];
+        for (const f of files) {
+            const r = path.relative(root, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, r, opts));
+            }
+            catch { /* skip */ }
+        }
+        const map = mapTestCoverage(buildSymbolGraph(skels, root));
+        const dir = rel.split(path.sep).join("/") || ".";
+        if (untestedOnly) {
+            return jsonText({ directory: dir, untestedSources: map.untestedSources, coverageRatio: map.coverageRatio, untested: map.untested });
+        }
+        return jsonText({ directory: dir, ...map });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_file_deps ───────────────────────────────── */
 server.registerTool("get_file_deps", {
     title: "Get file-level import dependencies",

package/dist/testmap.js

@@ -0,0 +1,167 @@
+/**
+ * Test-coverage mapping — pair test files with the source files they exercise,
+ * and surface source files no test touches.
+ *
+ * This is *structural* coverage (which files have tests at all), not line
+ * coverage — no instrumentation, no test runner, works on a cold checkout.
+ *
+ * Two matching signals, strongest first:
+ *   1. import  — a test file imports the source file (graph edge; definitive).
+ *   2. name    — naming convention pairs them ("auth.test.ts" → "auth.ts",
+ *                "test_utils.py" → "utils.py", "FooTest.java" → "Foo.java"),
+ *                resolved to the candidate sharing the longest path prefix.
+ */
+// ─── Test-file detection ───────────────────────────────────────────────────────
+const TEST_DIRS = new Set(["test", "tests", "__tests__", "spec", "specs", "testing", "e2e", "integration-tests"]);
+/** Support material, not tests and not production source: excluded from both sides. */
+const FIXTURE_DIRS = new Set(["fixtures", "fixture", "__fixtures__", "__mocks__", "mocks", "testdata", "snapshots", "__snapshots__"]);
+/** True when a rel path lives under a fixtures/mocks/testdata directory. */
+export function isFixtureFile(rel) {
+    return rel.split("/").slice(0, -1).some((d) => FIXTURE_DIRS.has(d.toLowerCase()));
+}
+const TEST_BASENAME_PATTERNS = [
+    /\.(test|spec)\.[^.]+$/i, // auth.test.ts, auth.spec.js
+    /[_-](test|tests|spec)\.[^.]+$/i, // auth_test.go, auth-test.js, auth_spec.rb
+    /^(test|spec)[_-]/i, // test_auth.py, spec_auth.rb
+    /Tests?\.(java|cs|kt|kts|swift|scala)$/, // AuthTest.java, AuthTests.cs
+    /Spec\.(java|cs|kt|kts|swift|scala)$/, // AuthSpec.kt
+];
+/** True when a rel path (forward-slashed) looks like a test file. */
+export function isTestFile(rel) {
+    const parts = rel.split("/");
+    const base = parts[parts.length - 1];
+    if (parts.slice(0, -1).some((d) => TEST_DIRS.has(d.toLowerCase())))
+        return true;
+    return TEST_BASENAME_PATTERNS.some((re) => re.test(base));
+}
+/**
+ * Derive the source basename a test file's name points at, or null when the
+ * name carries no convention ("smoke.mjs" in a test dir → null).
+ * "auth.test.ts" → "auth" · "test_utils.py" → "utils" · "AuthTest.java" → "Auth"
+ */
+export function testNameTarget(rel) {
+    const base = rel.split("/").pop();
+    const noExt = base.replace(/\.[^.]+$/, "");
+    let t = noExt
+        .replace(/\.(test|spec)$/i, "")
+        .replace(/[_-](test|tests|spec|smoke)$/i, "")
+        .replace(/\.(smoke)$/i, "")
+        .replace(/^(test|spec)[_-]/i, "")
+        .replace(/(Test|Tests|Spec)$/, "");
+    if (t === noExt || t.length === 0)
+        return null;
+    return t;
+}
+// ─── Mapping ───────────────────────────────────────────────────────────────────
+function commonPrefixLen(a, b) {
+    const pa = a.split("/");
+    const pb = b.split("/");
+    let i = 0;
+    while (i < pa.length - 1 && i < pb.length - 1 && pa[i] === pb[i])
+        i++;
+    return i;
+}
+function baseNoExt(rel) {
+    return rel.split("/").pop().replace(/\.[^.]+$/, "");
+}
+/**
+ * Build the test↔source coverage map from a symbol graph
+ * (use `buildSymbolGraph` over a directory that includes the test files).
+ */
+export function mapTestCoverage(graph) {
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    const allFiles = graph.nodes.filter((n) => n.nodeType === "file");
+    const fixtureCount = allFiles.filter((f) => isFixtureFile(f.id)).length;
+    const files = allFiles.filter((f) => !isFixtureFile(f.id));
+    const testFiles = files.filter((f) => isTestFile(f.id));
+    const sourceFiles = files.filter((f) => !isTestFile(f.id));
+    const isTest = new Set(testFiles.map((f) => f.id));
+    const sourceByBase = new Map();
+    for (const s of sourceFiles) {
+        const b = baseNoExt(s.id).toLowerCase();
+        (sourceByBase.get(b) ?? sourceByBase.set(b, []).get(b)).push(s.id);
+    }
+    // Signal 1: import edges test → source. Also count source-side fan-in (Ca).
+    const links = [];
+    const seen = new Set();
+    const afferent = new Map(); // source ← importers (non-test)
+    for (const e of graph.edges) {
+        if (e.edgeType !== "imports")
+            continue;
+        const to = nodeMap.get(e.to);
+        const toFile = to ? (to.nodeType === "file" ? to.id : to.file) : null;
+        if (!toFile || e.from === toFile)
+            continue;
+        if (isTest.has(e.from) && !isTest.has(toFile)) {
+            const key = e.from + "|" + toFile;
+            if (!seen.has(key)) {
+                seen.add(key);
+                links.push({ test: e.from, source: toFile, via: "import" });
+            }
+        }
+        else if (!isTest.has(e.from) && !isTest.has(toFile)) {
+            (afferent.get(toFile) ?? afferent.set(toFile, new Set()).get(toFile)).add(e.from);
+        }
+    }
+    // Signal 2: naming convention, for test files with no import link yet.
+    const linkedTests = new Set(links.map((l) => l.test));
+    for (const t of testFiles) {
+        if (linkedTests.has(t.id))
+            continue;
+        // Explicit marker in the name, else (for files inside test dirs, where the
+        // dir itself is the marker) the plain basename: test/analysis.mjs → "analysis".
+        const target = testNameTarget(t.id) ?? baseNoExt(t.id);
+        const candidates = sourceByBase.get(target.toLowerCase());
+        if (!candidates || candidates.length === 0)
+            continue;
+        // Prefer the candidate sharing the longest directory prefix with the test.
+        let best = [];
+        let bestScore = -1;
+        for (const c of candidates) {
+            const s = commonPrefixLen(t.id, c);
+            if (s > bestScore) {
+                bestScore = s;
+                best = [c];
+            }
+            else if (s === bestScore)
+                best.push(c);
+        }
+        for (const c of best) {
+            const key = t.id + "|" + c;
+            if (!seen.has(key)) {
+                seen.add(key);
+                links.push({ test: t.id, source: c, via: "name" });
+            }
+        }
+    }
+    // Aggregate.
+    const testsBySource = new Map();
+    for (const l of links) {
+        (testsBySource.get(l.source) ?? testsBySource.set(l.source, []).get(l.source)).push(l.test);
+    }
+    const tested = [];
+    const untested = [];
+    for (const s of sourceFiles) {
+        const tests = testsBySource.get(s.id);
+        if (tests)
+            tested.push({ file: s.id, tests: [...new Set(tests)].sort() });
+        else
+            untested.push({ file: s.id, symbols: s.symbolCount, afferent: afferent.get(s.id)?.size ?? 0 });
+    }
+    tested.sort((a, b) => a.file.localeCompare(b.file));
+    untested.sort((a, b) => b.afferent - a.afferent || b.symbols - a.symbols || a.file.localeCompare(b.file));
+    const covered = new Set(links.map((l) => l.test));
+    const orphanTests = testFiles.map((f) => f.id).filter((id) => !covered.has(id)).sort();
+    return {
+        sourceFiles: sourceFiles.length,
+        testFiles: testFiles.length,
+        fixtureFiles: fixtureCount,
+        testedSources: tested.length,
+        untestedSources: untested.length,
+        coverageRatio: sourceFiles.length === 0 ? 0 : Math.round((tested.length / sourceFiles.length) * 100) / 100,
+        links,
+        tested,
+        untested,
+        orphanTests,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",