universal-ast-mapper 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -6,6 +6,11 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.11.0] — 2026-06-01 · Code-health dashboard
+- **`ast-map report`** writes a premium self-contained HTML dashboard: health
+  grade (A–F), stats, language breakdown, complexity hotspots, god nodes, dead
+  code, and cycles. **`get_codebase_report`** MCP tool returns the same as JSON.
+
 ## [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
@@ -112,6 +117,7 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 - **0.2.0** — import extraction; `resolve_imports`; `build_symbol_graph`.
 - **0.1.0** — `get_skeleton_json`, `generate_skeleton`, `get_symbol_context`, `validate_architecture`.
 
+[1.11.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.11.0
 [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

package/README.md

@@ -101,6 +101,7 @@ 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 report    [dir]            [-o report.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]
@@ -620,6 +621,7 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.11.0** | **Code-health dashboard** — new `ast-map report` CLI writes a premium self-contained HTML overview (grade A–F, stats, language breakdown, complexity hotspots, god nodes, dead code, cycles) + `get_codebase_report` MCP tool for the same as JSON. |
 | **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. |

package/dist/cli.js

@@ -16,6 +16,7 @@ import { traceTypeInFile } from "./typeflow.js";
 import { discoverWorkspace, findPackageCycles } from "./workspace.js";
 import { buildExplorerHtml } from "./explorer.js";
 import { readSourceMap } from "./sourcemap.js";
+import { buildReport, buildReportHtml } from "./report.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -446,6 +447,28 @@ program
     console.log(`\n  ${info.sources.length} original source(s)` + (info.hasContent ? dim(" · embeds sourcesContent") : ""));
     console.log();
 });
+// ─── Command: report ──────────────────────────────────────────────────────────
+program
+    .command("report [dir]")
+    .description("Generate a code-health dashboard (HTML)")
+    .option("-o, --out <file>", "Output HTML path", "ast-report.html")
+    .option("--json", "Print the report data as JSON")
+    .action(async (dir, opts) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const data = await buildReport(abs, ROOT);
+    if (opts.json)
+        return jsonOut(data);
+    const out = path.resolve(process.cwd(), opts.out);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, buildReportHtml(data), "utf8");
+    header(`Code Health \u2014 ${rel}/  ${dim(`(${data.fileCount} files)`)}`);
+    const gcolor = data.grade === "A" || data.grade === "B" ? green : data.grade === "C" || data.grade === "D" ? yellow : (x) => x;
+    console.log(indent(`Grade ${bold(gcolor(data.grade))}  ${dim("(" + data.score + "/100)")}  ·  ${data.dead.count} dead · ${data.cycles.count} cycles · max cx ${data.complexity.max}`));
+    console.log(indent(green("✓ wrote " + path.relative(process.cwd(), out))));
+    console.log();
+});
 // ─── Command: explore ─────────────────────────────────────────────────────────
 program
     .command("explore [dir]")

package/dist/index.js

@@ -20,6 +20,7 @@ import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
 import { discoverWorkspace, findPackageCycles } from "./workspace.js";
 import { readSourceMap } from "./sourcemap.js";
+import { buildReport } from "./report.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) {
@@ -767,6 +768,28 @@ server.registerTool("read_source_map", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: get_codebase_report ─────────────────────────── */
+server.registerTool("get_codebase_report", {
+    title: "Codebase health report",
+    description: "Scan a directory and return a one-shot health summary: file/symbol counts, language " +
+        "breakdown, a health grade (A\u2013F) and score, complexity hotspots, god nodes (most-imported " +
+        "symbols), dead exports, and circular dependencies. The `ast-map report` CLI renders this as HTML.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan. Defaults to the project root."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. get_codebase_report requires a directory.`);
+        }
+        const data = await buildReport(abs, ROOT);
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", ...data });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/dist/report.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { collectSourceFiles, buildSkeleton } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+import { buildSymbolGraph } from "./graph.js";
+import { findDeadExports, findCircularDeps, getTopSymbols } from "./graph-analysis.js";
+import { computeFileComplexity } from "./complexity.js";
+function gradeFor(score) {
+    if (score >= 90)
+        return "A";
+    if (score >= 80)
+        return "B";
+    if (score >= 70)
+        return "C";
+    if (score >= 60)
+        return "D";
+    return "F";
+}
+export async function buildReport(absDir, root) {
+    const opts = resolveOptions({ detail: "outline", emitHtml: false });
+    const files = collectSourceFiles(absDir, opts);
+    const skeletons = [];
+    const langCount = new Map();
+    let symbolCount = 0;
+    const hotspots = [];
+    let cxSum = 0, cxN = 0, cxMax = 0;
+    for (const file of files) {
+        const rel = path.relative(root, file).split(path.sep).join("/");
+        try {
+            const skel = await buildSkeleton(file, rel, opts);
+            skeletons.push(skel);
+            symbolCount += skel.symbolCount;
+            langCount.set(skel.language, (langCount.get(skel.language) ?? 0) + 1);
+            const fc = await computeFileComplexity(file, rel);
+            if (fc) {
+                for (const f of fc.functions) {
+                    hotspots.push({ ...f, file: rel });
+                    cxSum += f.complexity;
+                    cxN++;
+                    cxMax = Math.max(cxMax, f.complexity);
+                }
+            }
+        }
+        catch { /* skip unparsable */ }
+    }
+    const graph = buildSymbolGraph(skeletons, root);
+    const dead = findDeadExports(graph).filter((d) => d.confidence === "high");
+    const cycles = findCircularDeps(graph);
+    const god = getTopSymbols(graph, 8);
+    hotspots.sort((a, b) => b.complexity - a.complexity);
+    const veryHigh = hotspots.filter((f) => f.complexity > 20).length;
+    const high = hotspots.filter((f) => f.complexity > 10 && f.complexity <= 20).length;
+    // Health score: start at 100, subtract weighted penalties.
+    let score = 100;
+    score -= Math.min(20, dead.length * 1.5);
+    score -= Math.min(22, cycles.length * 6);
+    score -= Math.min(28, veryHigh * 4 + high * 1);
+    score -= Math.min(12, god.filter((g) => g.importCount >= 8).length * 4);
+    score = Math.max(0, Math.round(score));
+    const languages = [...langCount.entries()]
+        .map(([lang, f]) => ({ lang, files: f }))
+        .sort((a, b) => b.files - a.files);
+    return {
+        project: absDir.split(/[\\/]/).filter(Boolean).pop() || "project",
+        generatedAt: new Date().toISOString(),
+        fileCount: skeletons.length,
+        symbolCount,
+        edgeCount: graph.edges.filter((e) => e.edgeType === "imports").length,
+        languages,
+        score,
+        grade: gradeFor(score),
+        dead: { count: dead.length, items: dead.slice(0, 25).map((d) => ({ file: d.file, symbol: d.symbol, kind: d.kind })) },
+        cycles: { count: cycles.length, items: cycles.slice(0, 12).map((c) => c.cycle) },
+        godNodes: god.map((g) => ({ symbol: g.symbol, file: g.file, importCount: g.importCount })),
+        complexity: { average: cxN ? Math.round((cxSum / cxN) * 10) / 10 : 0, max: cxMax, hotspots: hotspots.slice(0, 12) },
+    };
+}
+/* ─── Premium HTML dashboard ───────────────────────────────────────────────── */
+const GRADE_COLOR = {
+    A: "#1d9e75", B: "#1d9e75", C: "#ba7517", D: "#d85a30", F: "#e24b4a",
+};
+function esc(s) {
+    return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function ratingColor(r) {
+    return r === "very-high" ? "#e24b4a" : r === "high" ? "#d85a30" : r === "moderate" ? "#ba7517" : "#1d9e75";
+}
+function statCard(label, value, accent) {
+    return `<div class="stat"><div class="sv"${accent ? ` style="color:${accent}"` : ""}>${value}</div><div class="sl">${label}</div></div>`;
+}
+function bar(label, value, max, color, right) {
+    const pct = max > 0 ? Math.round((value / max) * 100) : 0;
+    return `<div class="row"><div class="rl">${esc(label)}</div><div class="track"><div class="fill" style="width:${pct}%;background:${color}"></div></div><div class="rr">${right}</div></div>`;
+}
+export function buildReportHtml(d) {
+    const gc = GRADE_COLOR[d.grade] ?? "#888";
+    const maxLang = d.languages[0]?.files ?? 1;
+    const langs = d.languages.map((l) => bar(l.lang, l.files, maxLang, "#534ab7", `${l.files}`)).join("");
+    const maxCx = d.complexity.hotspots[0]?.complexity ?? 1;
+    const hotspots = d.complexity.hotspots.length
+        ? d.complexity.hotspots.map((h) => bar(`${h.name}  ·  ${h.file}`, h.complexity, maxCx, ratingColor(h.rating), `<b>${h.complexity}</b>`)).join("")
+        : `<div class="empty">No functions found.</div>`;
+    const god = d.godNodes.length
+        ? d.godNodes.map((g) => `<div class="li"><span class="mono">${esc(g.symbol)}</span><span class="dim">${esc(g.file)}</span><span class="pill">${g.importCount} importers</span></div>`).join("")
+        : `<div class="empty">None.</div>`;
+    const dead = d.dead.count
+        ? d.dead.items.map((x) => `<div class="li"><span class="kbadge">${esc(x.kind)}</span><span class="mono">${esc(x.symbol)}</span><span class="dim">${esc(x.file)}</span></div>`).join("")
+            + (d.dead.count > d.dead.items.length ? `<div class="more">+${d.dead.count - d.dead.items.length} more…</div>` : "")
+        : `<div class="ok">✓ No high-confidence dead exports</div>`;
+    const cycles = d.cycles.count
+        ? d.cycles.items.map((c) => `<div class="li"><span class="mono">${esc(c.join("  →  "))}</span></div>`).join("")
+        : `<div class="ok">✓ No circular dependencies</div>`;
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(d.project)} — code health</title><style>
+:root{--bg:#fafaf8;--card:#fff;--bd:#e7e5df;--tx:#2b2b28;--dim:#8a8880;--soft:#f1efe9}
+@media(prefers-color-scheme:dark){:root{--bg:#161613;--card:#1e1e1b;--bd:#33332e;--tx:#e6e4dd;--dim:#9a988f;--soft:#26261f}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--tx);font-family:system-ui,-apple-system,sans-serif;line-height:1.5}
+.wrap{max-width:980px;margin:0 auto;padding:32px 24px 60px}
+.hero{display:flex;align-items:center;gap:24px;margin-bottom:28px}
+.badge{width:104px;height:104px;border-radius:24px;display:flex;flex-direction:column;align-items:center;justify-content:center;color:#fff;flex:0 0 auto}
+.badge .g{font-size:46px;font-weight:700;line-height:1}.badge .s{font-size:12px;opacity:.9}
+.h1{font-size:26px;font-weight:650;margin:0}.sub{color:var(--dim);font-size:13px;margin-top:4px}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(110px,1fr));gap:12px;margin-bottom:30px}
+.stat{background:var(--card);border:1px solid var(--bd);border-radius:14px;padding:14px 16px}
+.sv{font-size:24px;font-weight:650}.sl{font-size:12px;color:var(--dim);margin-top:2px}
+.card{background:var(--card);border:1px solid var(--bd);border-radius:16px;padding:18px 20px;margin-bottom:18px}
+.card h2{font-size:14px;font-weight:600;margin:0 0 14px;letter-spacing:.02em;text-transform:uppercase;color:var(--dim)}
+.row{display:flex;align-items:center;gap:12px;margin:7px 0;font-size:13px}
+.rl{flex:0 0 46%;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.track{flex:1;height:8px;background:var(--soft);border-radius:5px;overflow:hidden}.fill{height:100%;border-radius:5px}
+.rr{flex:0 0 auto;color:var(--dim);min-width:32px;text-align:right}
+.li{display:flex;align-items:center;gap:10px;padding:5px 0;font-size:13px;border-top:1px solid var(--bd)}.li:first-child{border-top:none}
+.mono{font-family:ui-monospace,monospace;font-weight:550}.dim{color:var(--dim);font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.pill{margin-left:auto;background:var(--soft);border-radius:20px;padding:2px 10px;font-size:11px;color:var(--dim);flex:0 0 auto}
+.kbadge{font-size:11px;color:var(--dim);background:var(--soft);border-radius:5px;padding:1px 7px;flex:0 0 auto}
+.ok{color:#1d9e75;font-size:13px}.empty{color:var(--dim);font-size:13px}.more{color:var(--dim);font-size:12px;padding-top:6px}
+.two{display:grid;grid-template-columns:1fr 1fr;gap:18px}@media(max-width:720px){.two{grid-template-columns:1fr}.rl{flex-basis:42%}}
+.foot{color:var(--dim);font-size:11px;text-align:center;margin-top:24px}
+</style></head><body><div class="wrap">
+<div class="hero">
+  <div class="badge" style="background:${gc}"><div class="g">${d.grade}</div><div class="s">${d.score}/100</div></div>
+  <div><h1 class="h1">${esc(d.project)} — code health</h1>
+  <div class="sub">${d.fileCount} files · ${d.symbolCount} symbols · ${d.languages.length} language(s) · ${esc(d.generatedAt.slice(0, 10))}</div></div>
+</div>
+<div class="grid">
+  ${statCard("Files", d.fileCount)}
+  ${statCard("Symbols", d.symbolCount)}
+  ${statCard("Import edges", d.edgeCount)}
+  ${statCard("Avg complexity", d.complexity.average)}
+  ${statCard("Max complexity", d.complexity.max, ratingColor(d.complexity.max > 20 ? "very-high" : d.complexity.max > 10 ? "high" : "low"))}
+  ${statCard("Dead exports", d.dead.count, d.dead.count ? "#d85a30" : "#1d9e75")}
+  ${statCard("Cycles", d.cycles.count, d.cycles.count ? "#e24b4a" : "#1d9e75")}
+</div>
+<div class="card"><h2>Language breakdown</h2>${langs}</div>
+<div class="card"><h2>Complexity hotspots</h2>${hotspots}</div>
+<div class="two">
+  <div class="card"><h2>God nodes (most imported)</h2>${god}</div>
+  <div class="card"><h2>Circular dependencies</h2>${cycles}</div>
+</div>
+<div class="card"><h2>Dead exports (high confidence)</h2>${dead}</div>
+<div class="foot">Generated by AST-MCP · universal-ast-mapper</div>
+</div></body></html>`;
+}

package/package.json

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