universal-ast-mapper 1.5.0 → 1.7.0

package/README.md

@@ -98,6 +98,7 @@ ast-map complexity <path>          [alias: cx] [--min N]
 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 search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -562,6 +563,18 @@ src/
 
 ---
 
+## MCP resources
+
+Beyond tools, the server exposes the codebase as **browseable MCP resources**, so an agent (or MCP client UI) can list and read structure directly:
+
+| URI | What |
+|-----|------|
+| `ast://languages` | supported languages + extensions |
+| `ast://skeleton/{path}` | the skeleton for one source file (templated; `resources/list` enumerates every file) |
+| `ast://graph` | the whole-root symbol dependency graph (guarded by file count) |
+
+---
+
 ## GitHub Action — architecture gate in CI
 
 Use AST-MCP as a CI check with the bundled composite action (`action.yml`):
@@ -605,6 +618,8 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **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. |
 | **1.4.0** | **Dynamic import tracking** — dynamic `import("...")` and CommonJS `require("...")` calls (anywhere in a file) are now captured as imports with an `isDynamic` flag. Relative dynamic imports resolve and draw graph edges like static ones, so lazy-loaded routes/modules show up in the dependency graph. |
 | **1.3.0** | **TS/JS decorators** — class and method symbols now carry a `decorators` field (`@Component({...})`, `@Injectable()`, `@Get("/x")`), in skeletons and `get_call_graph`. Extends the Python decorator support (v0.8.7) to TypeScript/JavaScript — traces Angular/NestJS-style framework wiring to its class/handler. |

package/dist/cli.js

@@ -14,6 +14,7 @@ import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
 import { discoverWorkspace, findPackageCycles } from "./workspace.js";
+import { buildExplorerHtml } from "./explorer.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -370,6 +371,28 @@ program
     }
     console.log();
 });
+// ─── Command: explore ─────────────────────────────────────────────────────────
+program
+    .command("explore [dir]")
+    .description("Generate an interactive HTML dependency-graph explorer")
+    .option("-o, --out <file>", "Output HTML path")
+    .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 graph = buildSymbolGraph(skeletons, ROOT);
+    const html = buildExplorerHtml(graph, abs);
+    const outPath = opts.out
+        ? path.resolve(process.cwd(), opts.out)
+        : path.join(abs, "ast-explorer.html");
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, html, "utf8");
+    header(`Graph Explorer — ${rel}/  ${dim(`(${skeletons.length} files)`)}`);
+    console.log(indent(green("✓ wrote " + path.relative(process.cwd(), outPath))));
+    console.log(indent(dim("open it in a browser — drag nodes, scroll to zoom, click to highlight, filter by name")));
+    console.log();
+});
 // ─── Command: workspace ───────────────────────────────────────────────────────
 program
     .command("workspace [dir]")

package/dist/explorer.js

@@ -0,0 +1,69 @@
+/** Derive a file-level dependency graph (nodes = files, edges = imports). */
+function deriveFileGraph(graph) {
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    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 });
+    }
+    const seen = new Set();
+    const links = [];
+    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;
+        const key = e.from + "|" + toFile;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        links.push({ source: e.from, target: toFile });
+    }
+    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 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}" +
+    "#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;});" +
+    "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='';" +
+    "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 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';}});" +
+    "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();";
+/** Build a self-contained, dependency-free HTML graph explorer. */
+export function buildExplorerHtml(graph, root) {
+    const data = deriveFileGraph(graph);
+    const dataJson = JSON.stringify(data);
+    const title = root.split(/[\\/]/).filter(Boolean).pop() || "project";
+    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>" +
+        "<script>var DATA=" + dataJson + ";</script><script>" + CLIENT + "</script></body></html>");
+}

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { fileURLToPath } from "node:url";
@@ -983,6 +983,71 @@ function describeError(err) {
     }
     return err instanceof Error ? err.message : String(err);
 }
+/* ─────────────────── MCP resources (browseable structure) ──────────────── */
+server.registerResource("languages", "ast://languages", {
+    title: "Supported languages",
+    description: "Languages and file extensions this server can map.",
+    mimeType: "application/json",
+}, async (uri) => ({
+    contents: [{
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify({ root: ROOT, languages: supportedLanguages() }, null, 2),
+        }],
+}));
+server.registerResource("skeleton", new ResourceTemplate("ast://skeleton/{+path}", {
+    list: async () => {
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(ROOT, opts);
+        return {
+            resources: files.map((f) => {
+                const rel = path.relative(ROOT, f).split(path.sep).join("/");
+                return { uri: `ast://skeleton/${rel}`, name: rel, mimeType: "application/json" };
+            }),
+        };
+    },
+}), {
+    title: "File skeleton",
+    description: "Normalized code skeleton (symbols, imports, ranges) for one source file.",
+    mimeType: "application/json",
+}, async (uri, variables) => {
+    const rel = decodeURIComponent(String(variables.path)).split(path.sep).join("/");
+    const { abs, rel: safeRel } = resolveInRoot(rel);
+    const opts = resolveOptions({ detail: "outline", emitHtml: false });
+    const skel = await buildSkeleton(abs, safeRel.split(path.sep).join("/"), opts);
+    return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(skel, null, 2) }],
+    };
+});
+server.registerResource("graph", "ast://graph", {
+    title: "Symbol dependency graph",
+    description: "Symbol-level dependency graph for the whole root (guarded by node count).",
+    mimeType: "application/json",
+}, async (uri) => {
+    const opts = resolveOptions({ detail: "outline", emitHtml: false });
+    const files = collectSourceFiles(ROOT, opts);
+    if (files.length > 1500) {
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({ note: `Too large to inline (${files.length} files). Use build_symbol_graph on a subdirectory.`, files: files.length }, null, 2),
+                }],
+        };
+    }
+    const skels = [];
+    for (const file of files) {
+        const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+        try {
+            skels.push(await buildSkeleton(file, fileRel, opts));
+        }
+        catch { /* skip */ }
+    }
+    const graph = buildSymbolGraph(skels, ROOT);
+    return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(graph, null, 2) }],
+    };
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

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