universal-ast-mapper 1.7.0 → 1.10.0

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to **universal-ast-mapper** (AST-MCP). Format based on
+[Keep a Changelog](https://keepachangelog.com/); this project follows semver and,
+since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
+
+---
+
+## [1.10.0] — 2026-06-01 · Source maps
+- **`read_source_map`** MCP tool + **`ast-map sourcemap <file>`** CLI: trace a
+  compiled JS/CSS file (inline `data:` or external `.map`) back to its original
+  sources; honors `sourceRoot` and reports embedded `sourcesContent`.
+- Ruby re-investigated and confirmed blocked (external-scanner grammar needs
+  web-tree-sitter ≥0.22; engine upgrade would risk the 12 working languages).
+
+## [1.9.0] — 2026-06-01 · Watch mode
+- **`ast-map watch [dir]`** — debounced, coalesced rebuild of the dependency
+  analysis (files · dead exports · cycles) on every source change; `-o file.html`
+  regenerates the live explorer too.
+- Explorer debug readout hidden by default (toggle with `d`).
+
+## [1.8.0] — 2026-06-01 · Explorer detail sidebar
+- Click a file in `ast-map explore` for a side panel: language, symbol count,
+  symbols, **Imports** and **Imported by** (each clickable to navigate the graph).
+- **1.8.1–1.8.3 (fixes):** explorer now reliably centers/fills the viewport —
+  separated orphan files into a tidy grid, clamped the force layout to stop nodes
+  being flung to huge coordinates, and sized the canvas from `innerWidth/innerHeight`.
+
+## [1.7.0] — 2026-06-01 · Web UI graph explorer
+- **`ast-map explore [dir]`** writes a self-contained, dependency-free interactive
+  HTML: a force-directed file dependency graph (drag / zoom / pan / click-to-
+  highlight / name filter). Opens in any browser, no build step.
+- **1.7.1–1.7.3 (fixes):** auto-fit and layout tuning.
+
+## [1.6.0] — 2026-06-01 · MCP resource endpoints
+- Browseable resources: **`ast://languages`**, **`ast://skeleton/{path}`**
+  (templated, one per file via `resources/list`), **`ast://graph`**. Agents can
+  list/read codebase structure as resources, not just call tools.
+
+## [1.5.0] — 2026-06-01 · `.d.ts` / ambient declarations
+- Extract `declare function/const/class`, `declare module "x"`, and
+  `declare namespace` (plus plain `namespace`); a `.d.ts` used to yield 0 symbols.
+- New `namespace` symbol kind.
+
+## [1.4.0] — 2026-06-01 · Dynamic import tracking
+- Capture dynamic `import("...")` and CommonJS `require("...")` with an
+  `isDynamic` flag; relative ones resolve and draw graph edges like static imports.
+
+## [1.3.0] — 2026-06-01 · TS/JS decorators
+- Class and method symbols carry a `decorators` field (`@Component`, `@Get(...)`),
+  in skeletons and `get_call_graph`. Extends the Python decorator support to TS/JS.
+
+## [1.2.0] — 2026-06-01 · File-level cross-package resolution
+- In a monorepo, bare imports of a workspace package (`@org/utils`, `@org/utils/sub`)
+  resolve to the real source file (prefers `src/` over `dist/`), so `resolve_imports`
+  marks them in-project and `build_symbol_graph` draws cross-package edges.
+
+## [1.1.0] — 2026-06-01 · Monorepo support
+- **`analyze_workspace`** tool + **`ast-map workspace`** CLI: discover packages
+  (npm/yarn `workspaces`, `pnpm-workspace.yaml`, `lerna.json`), map internal
+  package dependencies, and detect circular package deps.
+
+## [1.0.0] — 2026-06-01 · Stable release 🎉
+- Locked public API (MCP tool names + schemas, CLI surface) for the 1.x line.
+- Bundled **GitHub Action** (`action.yml`) running `ast-map validate` as a CI gate,
+  plus a project CI workflow.
+- 12 languages · 18 MCP tools / 17 CLI commands at release.
+
+## [0.9.0] — 2026-05-31 · Scoped type-flow tracing
+- **`trace_type`** tool + **`ast-map trace-type`** CLI: follow a named type through
+  function params, return types, typed variables, and class fields. Completes the
+  deeper-analysis suite.
+
+## [0.8.7] — 2026-05-31 · Python decorators
+- `decorators` field on Python symbols + `get_call_graph`; traces
+  `@router.get(...)` → handler and stacked decorators.
+
+## [0.8.6] — 2026-05-31 · Unused parameter detection
+- **`find_unused_params`** tool + **`ast-map unused-params`** CLI: named functions
+  whose params are never referenced (low false-positive; counts object shorthand).
+
+## [0.8.5] — 2026-05-31 · Cyclomatic complexity
+- **`get_complexity`** tool + **`ast-map complexity`** CLI: per-function score with
+  low/moderate/high/very-high ratings and directory hotspots.
+
+## [0.8.4] — 2026-05-31 · Duplicate symbol detection
+- **`find_duplicate_symbols`** tool + **`ast-map duplicates`** CLI: exported names
+  declared in 2+ files.
+
+## [0.8.3] — 2026-05-31 · TSX/React component props
+- Component symbols carry `propsType` + `props[]`; detects `React.FC<P>` and
+  JSX-returning PascalCase functions. MCP server version now read from package.json.
+
+## [0.8.2] — 2026-05-30 · Swift cross-file wiring
+- `import <Module>` → that module's files (`Sources/<Module>/`). Completes
+  cross-file graph/resolver support for all four v0.8.0 languages.
+
+## [0.8.1] — 2026-05-30 · Kotlin + C/C++ cross-file wiring
+- Kotlin FQCN/package index; C/C++ `#include` resolution with header↔impl pairing.
+- Fixes: parse-cache rel-path leak; Kotlin call-graph extraction.
+
+---
+
+## Earlier (pre-session history)
+
+- **0.8.0** — +4 languages: C · C++ · Kotlin · Swift (symbol extraction + imports).
+- **0.7.0** — Go full module resolution; C# reverse `calledBy`; 4-suite test harness.
+- **0.6.0** — +3 languages: Rust · Java · C#; cross-language resolver.
+- **0.5.x** — `/ast-map` skill auto-install; iterative DFS; barrel re-exports; parse cache; call-graph aliases; `.ast-map.config.json`.
+- **0.4.0** — `search_symbol`, `get_file_deps`, `get_top_symbols`, dead-code tiers.
+- **0.3.0** — CLI; `find_dead_code`, `find_circular_deps`, `get_change_impact`, `get_call_graph`.
+- **0.2.0** — import extraction; `resolve_imports`; `build_symbol_graph`.
+- **0.1.0** — `get_skeleton_json`, `generate_skeleton`, `get_symbol_context`, `validate_architecture`.
+
+[1.10.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.10.0
+[1.9.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.9.0
+[1.8.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.8.0
+[1.7.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.7.0
+[1.6.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.6.0
+[1.5.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.5.0
+[1.4.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.4.0
+[1.3.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.3.0
+[1.2.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.2.0
+[1.1.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.1.0
+[1.0.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.0.0
+[0.9.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v0.9.0
+[0.8.1]: https://github.com/6ixthxense/AST-MCP/releases/tag/v0.8.1

package/README.md

@@ -99,6 +99,8 @@ ast-map unused-params <path>       [alias: unused]
 ast-map trace-type <type> [dir]    [alias: flow]
 ast-map workspace [dir]            [alias: ws]
 ast-map explore   [dir]            [-o out.html]
+ast-map watch     [dir]            [-o out.html]
+ast-map sourcemap <file>
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -618,6 +620,14 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.10.0** | **Source-map support** — new `read_source_map` MCP tool + `ast-map sourcemap <file>` CLI: given a compiled JS/CSS file with an inline (`data:`) or external `sourceMappingURL`, returns the original source files it maps back to (honors `sourceRoot`). Traces `dist/` output back to source. |
+| **1.9.0** | **Watch mode** — `ast-map watch [dir]` recomputes the dependency analysis (file count · dead exports · cycles) on every source-file change, debounced; `-o file.html` also regenerates the live explorer each time. Plus: the explorer debug readout is now hidden (toggle with `d`). |
+| **1.8.2** | **Explorer stability fix** — clamp the force layout (distance floor + velocity cap) so nodes that initialize close together can't be flung to huge coordinates, which was blowing up the bounding box and shrinking the whole graph into a corner. Now reliably centers and fills. |
+| **1.8.1** | **Explorer self-heal sizing** — the explorer now re-checks canvas size every frame and re-fits, so it always centers/fills even if the canvas reports zero size at load (and survives container resizes). |
+| **1.8.0** | **Explorer detail sidebar** — click a file in `ast-map explore` to open a side panel: language, symbol count, its symbols, the files it imports, and the files that import it — each clickable to jump to that file. |
+| **1.7.3** | **Explorer layout overhaul** — only connected files are force-laid (centered + filling the viewport); orphan files with no in-scope deps are parked in a tidy grid below instead of sprawling. Verified centered at any window size. |
+| **1.7.2** | **Explorer fit, really this time** — continuous auto-fit until you interact, robust canvas sizing, and centered node init, so the graph fills the viewport instead of bunching in a corner. |
+| **1.7.1** | **Explorer fit fix** — the `ast-map explore` graph now auto-fits the viewport (spreads to fill the screen instead of clustering in the centre); double-click re-fits. |
 | **1.7.0** | **Web UI graph explorer** — `ast-map explore [dir]` writes a self-contained, dependency-free interactive HTML: a force-directed file dependency graph (drag, zoom, click-to-highlight neighbours, filter by name). No build step, no external scripts — just open it in a browser. |
 | **1.6.0** | **MCP resource endpoints** — the server now exposes browseable resources: `ast://languages`, `ast://skeleton/{path}` (templated, one per source file via `resources/list`), and `ast://graph`. Agents can list and read codebase structure as resources, not just call tools. |
 | **1.5.0** | **`.d.ts` / ambient declarations** — `declare function/const/class`, `declare module "x"`, and `declare namespace` (and plain `namespace`) are now extracted (previously a `.d.ts` yielded 0 symbols). Adds a `namespace` symbol kind; declared APIs surface as exported, nested under their module/namespace. |

package/dist/cli.js

@@ -15,6 +15,7 @@ import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
 import { discoverWorkspace, findPackageCycles } from "./workspace.js";
 import { buildExplorerHtml } from "./explorer.js";
+import { readSourceMap } from "./sourcemap.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -371,6 +372,80 @@ program
     }
     console.log();
 });
+// ─── Command: watch ───────────────────────────────────────────────────────────
+program
+    .command("watch [dir]")
+    .description("Rebuild analysis (and optionally the explorer) when files change")
+    .option("-o, --out <file>", "Also regenerate the explorer HTML on each change")
+    .action(async (dir, opts) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    let building = false;
+    let queued = false;
+    async function rebuild(reason) {
+        if (building) {
+            queued = true;
+            return;
+        }
+        building = true;
+        try {
+            const skels = await gatherSkeletons(abs);
+            const graph = buildSymbolGraph(skels, ROOT);
+            const dead = findDeadExports(graph).filter((d) => d.confidence === "high").length;
+            const cycles = findCircularDeps(graph).length;
+            let line = `${dim(new Date().toLocaleTimeString())}  ${bold(String(skels.length))} files · ${dead} dead · ${cycles} cycle(s)`;
+            if (opts.out) {
+                fs.writeFileSync(path.resolve(process.cwd(), opts.out), buildExplorerHtml(graph, abs), "utf8");
+                line += ` · ${green("explorer updated")}`;
+            }
+            line += `  ${dim(reason)}`;
+            console.log(line);
+        }
+        finally {
+            building = false;
+            if (queued) {
+                queued = false;
+                rebuild("(coalesced)");
+            }
+        }
+    }
+    header(`Watching ${rel}/  ${dim("(Ctrl+C to stop)")}`);
+    await rebuild("initial");
+    let timer = null;
+    const exts = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".rs", ".java", ".cs", ".c", ".cpp", ".h", ".hpp", ".kt", ".swift"]);
+    fs.watch(abs, { recursive: true }, (_evt, file) => {
+        if (!file)
+            return;
+        const f = String(file).split(path.sep).join("/");
+        if (/(^|\/)(node_modules|\.git|dist|\.ast-map)(\/|$)/.test(f))
+            return;
+        if (!exts.has(path.extname(f).toLowerCase()))
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => rebuild(`(${f.split("/").pop()} changed)`), 300);
+    });
+    await new Promise(() => { }); // keep the process alive
+});
+// ─── Command: sourcemap ───────────────────────────────────────────────────────
+program
+    .command("sourcemap <file>")
+    .description("Show the original sources a compiled file maps back to")
+    .option("--json", "Output as JSON")
+    .action(async (inputPath, opts) => {
+    const { abs, rel } = resolveArg(inputPath);
+    const info = readSourceMap(abs, rel);
+    if (!info)
+        die(`No source map found for "${rel}"`);
+    if (opts.json)
+        return jsonOut(info);
+    header(`Source Map — ${rel}  ${dim("(" + info.mapKind + ")")}`);
+    for (const sourceFile of info.sources)
+        console.log(indent(green("←") + " " + sourceFile));
+    console.log(`\n  ${info.sources.length} original source(s)` + (info.hasContent ? dim(" · embeds sourcesContent") : ""));
+    console.log();
+});
 // ─── Command: explore ─────────────────────────────────────────────────────────
 program
     .command("explore [dir]")

package/dist/explorer.js

@@ -1,13 +1,26 @@
 /** Derive a file-level dependency graph (nodes = files, edges = imports). */
 function deriveFileGraph(graph) {
     const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    // top-level symbol names per file (for the detail panel).
+    const fileSyms = new Map();
+    for (const n of graph.nodes) {
+        if (n.nodeType !== "symbol")
+            continue;
+        const s = n;
+        if (s.id.indexOf("::") !== s.id.lastIndexOf("::"))
+            continue; // skip nested (one :: only)
+        const arr = fileSyms.get(s.file) ?? [];
+        if (arr.length < 60)
+            arr.push(s.kind + " " + s.symbol);
+        fileSyms.set(s.file, arr);
+    }
     const nodes = [];
     for (const n of graph.nodes) {
         if (n.nodeType !== "file")
             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 });
+        nodes.push({ id: f.id, symbols: f.symbolCount, group: parts.length > 1 ? parts[0] : "(root)", lang: f.language, syms: fileSyms.get(f.id) ?? [] });
     }
     const seen = new Set();
     const links = [];
@@ -27,34 +40,58 @@ function deriveFileGraph(graph) {
     return { nodes, links };
 }
 const STYLE = "body{margin:0;font-family:system-ui,sans-serif;color:#222;background:#fafafa}" +
-    "#bar{position:fixed;top:0;left:0;right:0;height:48px;display:flex;align-items:center;gap:12px;padding:0 14px;background:#fff;border-bottom:1px solid #e5e5e5;z-index:2;box-sizing:border-box}" +
+    "#bar{position:fixed;top:0;left:0;right:0;height:48px;display:flex;align-items:center;gap:12px;padding:0 14px;background:#fff;border-bottom:1px solid #e5e5e5;z-index:4;box-sizing:border-box}" +
     "#bar h1{font-size:14px;margin:0;font-weight:600}#bar .muted{color:#888;font-size:12px}" +
-    "#q{flex:0 0 220px;padding:6px 10px;border:1px solid #ddd;border-radius:6px;font-size:13px}" +
+    "#q{flex:0 0 200px;padding:6px 10px;border:1px solid #ddd;border-radius:6px;font-size:13px}" +
     "#cv{position:fixed;top:48px;left:0;right:0;bottom:0;display:block;cursor:grab}" +
-    "#tip{position:fixed;pointer-events:none;background:#222;color:#fff;font-size:12px;padding:4px 8px;border-radius:5px;display:none;z-index:3}" +
-    "@media(prefers-color-scheme:dark){body{color:#ddd;background:#161616}#bar{background:#1e1e1e;border-color:#333}#q{background:#2a2a2a;border-color:#444;color:#ddd}}";
-const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=document.getElementById('tip');" +
-    "var W,H;function resize(){var r=devicePixelRatio||1;W=c.clientWidth;H=c.clientHeight;c.width=W*r;c.height=H*r;ctx.setTransform(r,0,0,r,0,0);}addEventListener('resize',resize);resize();" +
-    "var nodes=DATA.nodes,links=DATA.links,byId={};nodes.forEach(function(n){n.x=Math.random()*W;n.y=Math.random()*H;n.vx=0;n.vy=0;byId[n.id]=n;});" +
+    "#tip{position:fixed;pointer-events:none;background:#222;color:#fff;font-size:12px;padding:4px 8px;border-radius:5px;display:none;z-index:5}" +
+    "#panel{position:fixed;top:48px;right:0;bottom:0;width:300px;background:#fff;border-left:1px solid #e5e5e5;z-index:3;overflow-y:auto;padding:14px 16px;box-sizing:border-box;display:none;font-size:13px}" +
+    "#panel h2{font-size:14px;margin:0 0 2px;word-break:break-all}#panel .path{color:#888;font-size:11px;margin-bottom:10px;word-break:break-all}" +
+    "#panel .meta{color:#555;margin-bottom:12px}#panel h3{font-size:11px;text-transform:uppercase;letter-spacing:.04em;color:#999;margin:14px 0 6px}" +
+    "#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}}";
+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();" +
+    "function availW(){return W-(panelOpen?PANELW:0);}" +
+    "var nodes=DATA.nodes,links=DATA.links,byId={};nodes.forEach(function(n){byId[n.id]=n;n.vx=0;n.vy=0;});" +
+    "var deg={},out={},inn={};links.forEach(function(l){deg[l.source]=(deg[l.source]||0)+1;deg[l.target]=(deg[l.target]||0)+1;(out[l.source]=out[l.source]||[]).push(l.target);(inn[l.target]=inn[l.target]||[]).push(l.source);});" +
+    "var sim=nodes.filter(function(n){return deg[n.id];}),orphans=nodes.filter(function(n){return !deg[n.id];});" +
+    "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='';" +
+    "var view={x:0,y:0,k:1},sel=null,hover=null,drag=null,pan=null,q='',autofit=true;" +
     "function radius(n){return 4+Math.sqrt(n.symbols||0)*1.7;}" +
-    "function tick(){var k=0.0007;for(var i=0;i<nodes.length;i++){var a=nodes[i];a.vx+=(W/2-a.x)*k;a.vy+=(H/2-a.y)*k;for(var j=i+1;j<nodes.length;j++){var b=nodes[j];var dx=a.x-b.x,dy=a.y-b.y,d2=dx*dx+dy*dy+0.01,d=Math.sqrt(d2),f=1400/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-95)*0.012,fx=f*dx/d,fy=f*dy/d;a.vx+=fx;a.vy+=fy;b.vx-=fx;b.vy-=fy;});" +
-    "for(var i=0;i<nodes.length;i++){var n=nodes[i];if(n===drag)continue;n.vx*=0.86;n.vy*=0.86;n.x+=n.vx;n.y+=n.vy;}}" +
-    "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.7;" +
-    "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.85)':'rgba(140,140,140,0.16)';ctx.beginPath();ctx.moveTo(a.x,a.y);ctx.lineTo(b.x,b.y);ctx.stroke();});" +
-    "nodes.forEach(function(n){var dim=(sel&&n!==sel&&(adj[sel.id]||[]).indexOf(n.id)<0)||(q&&n.id.toLowerCase().indexOf(q)<0);ctx.globalAlpha=dim?0.16:1;ctx.beginPath();ctx.arc(n.x,n.y,radius(n),0,6.2832);ctx.fillStyle=color(n.group);ctx.fill();if(n===sel||n===hover){ctx.lineWidth=2;ctx.strokeStyle='#111';ctx.stroke();ctx.lineWidth=0.7;}});" +
-    "ctx.globalAlpha=1;ctx.fillStyle=getComputedStyle(document.body).color;ctx.font='11px system-ui';nodes.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(){tick();tick();draw();requestAnimationFrame(loop);}" +
+    "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;});" +
+    "for(var i=0;i<sim.length;i++){var n=sim[i];if(n===drag)continue;n.vx*=0.85;n.vy*=0.85;if(n.vx>30)n.vx=30;if(n.vx<-30)n.vx=-30;if(n.vy>30)n.vy=30;if(n.vy<-30)n.vy=-30;n.x+=n.vx;n.y+=n.vy;}}" +
+    "function bb4(arr){var a=1e9,b=1e9,c2=-1e9,d2=-1e9;for(var i=0;i<arr.length;i++){var n=arr[i];if(n.x<a)a=n.x;if(n.y<b)b=n.y;if(n.x>c2)c2=n.x;if(n.y>d2)d2=n.y;}return[a,b,c2,d2];}" +
+    "function layoutOrphans(){if(!orphans.length)return;var bb=sim.length?bb4(sim):[W*0.3,H*0.3,W*0.7,H*0.5];var left=bb[0],bottom=bb[3]+46,wide=Math.max(bb[2]-bb[0],260);var cols=Math.max(1,Math.ceil(Math.sqrt(orphans.length*1.8)));var gap=Math.max(22,wide/cols);for(var i=0;i<orphans.length;i++){orphans[i].x=left+(i%cols)*gap;orphans[i].y=bottom+Math.floor(i/cols)*22;}}" +
+    "function fitView(){var bb=bb4(nodes);var aw=availW();var bw=Math.max(bb[2]-bb[0],1),bh=Math.max(bb[3]-bb[1],1),k=Math.min(aw/(bw+70),H/(bh+70));k=Math.max(0.12,Math.min(k,2.2));view.k=k;view.x=aw/2-((bb[0]+bb[2])/2)*k;view.y=H/2-((bb[1]+bb[3])/2)*k;}" +
+    "function center(n){view.k=Math.max(view.k,0.7);view.x=availW()/2-n.x*view.k;view.y=H/2-n.y*view.k;}" +
+    "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.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;}}" +
+    "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);}" +
     "function world(e){return{x:(e.clientX-view.x)/view.k,y:(e.clientY-48-view.y)/view.k};}" +
-    "function pick(p){for(var i=nodes.length-1;i>=0;i--){var n=nodes[i];if((p.x-n.x)*(p.x-n.x)+(p.y-n.y)*(p.y-n.y)<=radius(n)*radius(n)+12)return n;}return null;}" +
-    "c.addEventListener('mousedown',function(e){var n=pick(world(e));if(n){drag=n;sel=n;}else{pan={x:e.clientX-view.x,y:e.clientY-view.y};sel=null;}});" +
-    "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+' symbols  ·  '+hover.lang;}else tip.style.display='none';}});" +
+    "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('mouseup',function(){drag=null;pan=null;});" +
-    "c.addEventListener('wheel',function(e){e.preventDefault();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();});loop();";
+    "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();});" +
+    "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) {
     const data = deriveFileGraph(graph);
@@ -64,6 +101,6 @@ export function buildExplorerHtml(graph, root) {
         "<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>" +
+        "<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>" +
         "<script>var DATA=" + dataJson + ";</script><script>" + CLIENT + "</script></body></html>");
 }

package/dist/index.js

@@ -19,6 +19,7 @@ import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
 import { discoverWorkspace, findPackageCycles } from "./workspace.js";
+import { readSourceMap } from "./sourcemap.js";
 /** Files may only be read inside this root (override with AST_MAP_ROOT). */
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
 function resolveInRoot(input) {
@@ -745,6 +746,27 @@ server.registerTool("analyze_workspace", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: read_source_map ─────────────────────────────── */
+server.registerTool("read_source_map", {
+    title: "Read a compiled file's source map",
+    description: "Given a compiled JS/CSS file with an inline (`data:`) or external `sourceMappingURL`, " +
+        "return the original source paths it maps back to. Useful for tracing built output in " +
+        "dist/ back to the real source files.",
+    inputSchema: {
+        path: z.string().describe("Compiled file path, relative to project root or absolute within it."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input);
+        const info = readSourceMap(abs, rel.split(path.sep).join("/"));
+        if (!info)
+            return errorText(`No source map found for "${input}".`);
+        return jsonText(info);
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/dist/sourcemap.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+function decodeInline(url) {
+    const b64 = url.match(/base64,(.+)$/);
+    try {
+        if (b64)
+            return JSON.parse(Buffer.from(b64[1], "base64").toString("utf8"));
+        const comma = url.indexOf(",");
+        if (comma >= 0)
+            return JSON.parse(decodeURIComponent(url.slice(comma + 1)));
+    }
+    catch { /* malformed */ }
+    return null;
+}
+/**
+ * Read the source map for a compiled JS/CSS file: handles an inline
+ * `//# sourceMappingURL=data:...` comment or an external `.map` file, and
+ * returns the original source paths it maps back to.
+ */
+export function readSourceMap(absPath, relPath) {
+    let src;
+    try {
+        src = fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const matches = [...src.matchAll(/[#@]\s*sourceMappingURL=([^\s'"]+)/g)];
+    if (matches.length === 0)
+        return null;
+    const url = matches[matches.length - 1][1];
+    let map = null;
+    let mapKind;
+    let mapFile;
+    if (url.startsWith("data:")) {
+        mapKind = "inline";
+        map = decodeInline(url);
+    }
+    else {
+        mapKind = "external";
+        mapFile = url;
+        try {
+            map = JSON.parse(fs.readFileSync(path.resolve(path.dirname(absPath), url), "utf8"));
+        }
+        catch {
+            map = null;
+        }
+    }
+    if (!map || !Array.isArray(map.sources))
+        return null;
+    const root = typeof map.sourceRoot === "string" ? map.sourceRoot.replace(/\/$/, "") : "";
+    const sources = map.sources.map((s) => root && !s.startsWith("/") ? root + "/" + s : s);
+    return {
+        file: relPath,
+        mapKind,
+        ...(mapFile ? { mapFile } : {}),
+        sources,
+        hasContent: Array.isArray(map.sourcesContent) && map.sourcesContent.length > 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "1.7.0",
+  "version": "1.10.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
     "dist",
     "scripts",
     "README.md",
+    "CHANGELOG.md",
     "BLUEPRINT.md"
   ],
   "scripts": {