universal-ast-mapper 1.10.0 → 1.13.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.13.0] — 2026-06-08 · Context-pack
+- **`pack_context`** + **`ast-map pack <file> [symbol]`**: the minimal context to
+  work on a symbol — its source, the signatures it depends on, and its dependents
+  — with a token estimate, instead of reading whole files.
+
+## [1.12.0] — 2026-06-08 · Git-aware analysis
+- **`ast-map diff [base]`** + **`get_diff`**: changed symbols since a git ref,
+  breaking changes (removed / signature-changed exports), and blast radius.
+- **`ast-map risk`** + **`get_risk_map`**: rank files by churn × complexity.
+
+## [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 +127,9 @@ 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.13.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.13.0
+[1.12.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.12.0
+[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

@@ -4,6 +4,8 @@ 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.
 
+**24 MCP tools / 25 CLI commands** 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**, and a one-page **health dashboard** (`ast-map report`).
+
 **Supported languages:** TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go · Rust · Java · C# · C · C++ · Kotlin · Swift
 
 | Capability               | TS/JS | Python | Go  | Rust | Java | C#  | C   | C++ | Kt  | Swift |
@@ -101,6 +103,10 @@ 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 diff      [base]           [--dir <d>]   # git-aware changed symbols + impact
+ast-map risk      [dir]            [-n N]        # churn × complexity
+ast-map pack      <file> [symbol]  [--scan <d>] # minimal context pack
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -347,6 +353,67 @@ Scan a file or directory for **named functions/methods with parameters that are
 
 ---
 
+### `read_source_map`
+Given a compiled JS/CSS file with an inline (`data:`) or external `sourceMappingURL`, return the **original source files** it maps back to (honors `sourceRoot`; reports embedded `sourcesContent`).
+
+```json
+{ "file": "dist/bundle.js", "mapKind": "inline", "sources": ["../src/app.ts", "../src/util.ts"], "hasContent": true }
+```
+
+**Params:** `path`
+
+---
+
+### `get_codebase_report`
+A one-shot **codebase health summary**: file/symbol counts, language breakdown, a health **grade (A–F)** + score, complexity hotspots, god nodes, dead exports, and circular dependencies. Rendered as a premium HTML dashboard by `ast-map report`.
+
+```json
+{ "grade": "B", "score": 82, "fileCount": 120, "symbolCount": 1400,
+  "complexity": { "average": 4.1, "max": 22, "hotspots": [ … ] },
+  "godNodes": [ … ], "dead": { "count": 3, "items": [ … ] }, "cycles": { "count": 0, "items": [] } }
+```
+
+**Params:** `path` (optional, defaults to root)
+
+---
+
+### `get_diff`
+**Git-aware.** Compare the working tree to a git ref (default `HEAD`) and return which symbols were added/removed/modified per file, which changes are potentially **breaking** (removed or signature-changed exports), and the **blast radius** — files that depend on those breaking changes. Untracked new files count as additions.
+
+```json
+{ "summary": { "filesChanged": 2, "added": 1, "removed": 1, "modified": 1, "breaking": 2, "impactedFiles": 1 },
+  "breaking": [ { "file": "src/a.ts", "symbol": "foo", "reason": "signature changed" } ],
+  "impactedFiles": ["src/b.ts"] }
+```
+
+**Params:** `base` (optional), `path` (optional)
+
+---
+
+### `pack_context`
+**Token-efficient.** Assemble the *minimal* context to understand or change a symbol — its own source, the **signatures** of what it depends on (resolved imports), and the files that depend on it — instead of reading whole files. Returns a token estimate so you can see the savings.
+
+```json
+{ "primary": { "symbol": "login", "startLine": 8, "endLine": 12, "source": "…" },
+  "dependencies": [ { "file": "utils.ts", "symbols": [ { "name": "hashPassword", "signature": "…" } ] } ],
+  "dependents": [ { "file": "router.ts" } ], "tokenEstimate": 56 }
+```
+
+**Params:** `path`, `symbol` (optional), `scan` (optional)
+
+---
+
+### `get_risk_map`
+Rank files by **refactor risk = git churn × max complexity** — the files that are both frequently changed and complex (the best refactor / test targets).
+
+```json
+{ "files": [ { "file": "src/callgraph.ts", "churn": 7, "maxComplexity": 69, "risk": 483 } ] }
+```
+
+**Params:** `path` (optional)
+
+---
+
 ### `get_change_impact`
 Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
 
@@ -620,6 +687,9 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.13.0** | **Context-pack** — new `pack_context` MCP tool + `ast-map pack <file> [symbol]` CLI: the minimal context to work on a symbol (its source + the signatures it depends on + its dependents) with a token estimate, instead of reading whole files. **24 MCP tools**. |
+| **1.12.0** | **Git-aware analysis** — `ast-map diff [base]` + `get_diff` tool: changed symbols since a ref, **breaking changes** (removed / signature-changed exports), and blast radius. `ast-map risk` + `get_risk_map` tool: rank files by churn × complexity. Brings a time/history dimension. **23 MCP tools**. |
+| **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,9 @@ 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 { computeDiff, computeRisk, isGitRepo } from "./gitdiff.js";
+import { packContext } from "./contextpack.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -446,6 +449,122 @@ program
     console.log(`\n  ${info.sources.length} original source(s)` + (info.hasContent ? dim(" · embeds sourcesContent") : ""));
     console.log();
 });
+// ─── Command: pack ────────────────────────────────────────────────────────────
+program
+    .command("pack <file> [symbol]")
+    .description("Minimal context pack for a symbol (source + dep signatures + dependents)")
+    .option("--scan <dir>", "Directory to scan for dependents", ".")
+    .option("--json", "Output as JSON")
+    .action(async (file, symbol, opts) => {
+    const { abs, rel } = resolveArg(file);
+    if (fs.statSync(abs).isDirectory())
+        die(`"${rel}" is a directory; pass a file`);
+    const scanAbs = resolveArg(opts.scan).abs;
+    const pack = await packContext(abs, rel, ROOT, symbol, scanAbs);
+    if (opts.json)
+        return jsonOut(pack);
+    header(`Context Pack \u2014 ${rel}${symbol ? "::" + symbol : ""}  ${dim("(~" + pack.tokenEstimate + " tokens)")}`);
+    console.log(indent(bold("Primary") + dim(`  lines ${pack.primary.startLine}-${pack.primary.endLine}`)));
+    console.log();
+    console.log(indent(bold("Depends on:")));
+    if (pack.dependencies.length === 0)
+        console.log(indent(dim("(none in-project)"), 4));
+    for (const d of pack.dependencies) {
+        console.log(indent(green(d.file), 4));
+        for (const sym of d.symbols)
+            console.log(indent(dim((sym.signature || sym.name)), 6));
+    }
+    console.log();
+    console.log(indent(bold("Depended on by:")));
+    if (pack.dependents.length === 0)
+        console.log(indent(dim("(none found in scan)"), 4));
+    for (const dep of pack.dependents)
+        console.log(indent(yellow(dep.file), 4));
+    console.log();
+});
+// ─── Command: diff ────────────────────────────────────────────────────────────
+program
+    .command("diff [base]")
+    .description("Symbols changed since a git ref + breaking changes + blast radius")
+    .option("--dir <dir>", "Limit to a subdirectory", ".")
+    .option("--json", "Output as JSON")
+    .action(async (base, opts) => {
+    if (!isGitRepo(ROOT))
+        die("not a git repository (or git is unavailable)");
+    const { abs, rel } = resolveArg(opts.dir);
+    const ref = base ?? "HEAD";
+    const d = await computeDiff(abs, ROOT, ref);
+    if (opts.json)
+        return jsonOut(d);
+    header(`Diff since ${bold(ref)}  ${dim(`(${d.summary.filesChanged} file(s) · +${d.summary.added} ~${d.summary.modified} -${d.summary.removed})`)}`);
+    if (d.files.length === 0) {
+        console.log(indent(dim("No source-symbol changes.")));
+        console.log();
+        return;
+    }
+    for (const f of d.files) {
+        console.log(indent(`${bold(f.file)} ${dim("[" + f.status + "]")}`));
+        for (const a of f.added)
+            console.log(indent(green("+ ") + a.symbol + dim(a.exported ? " (exported)" : ""), 4));
+        for (const m of f.modified)
+            console.log(indent(yellow("~ ") + m.symbol + dim(m.exported ? " (exported)" : ""), 4));
+        for (const r of f.removed)
+            console.log(indent(red("- ") + r.symbol + dim(r.exported ? " (exported)" : ""), 4));
+    }
+    if (d.breaking.length > 0) {
+        console.log(`\n${indent(bold(red("\u26a0 Breaking changes (" + d.breaking.length + ")")))}`);
+        for (const b of d.breaking)
+            console.log(indent(`${red(b.symbol)}  ${dim(b.reason)}  ${dim(b.file)}`, 4));
+        console.log(`\n${indent(yellow(d.impactedFiles.length + " file(s) impacted") + dim(" by breaking changes"))}`);
+        for (const f of d.impactedFiles.slice(0, 20))
+            console.log(indent(dim(f), 4));
+    }
+    console.log();
+});
+// ─── Command: risk ────────────────────────────────────────────────────────────
+program
+    .command("risk [dir]")
+    .description("Rank files by refactor risk (git churn × complexity)")
+    .option("--json", "Output as JSON")
+    .option("-n, --top <n>", "Show top N", (v) => parseInt(v, 10), 15)
+    .action(async (dir, opts) => {
+    if (!isGitRepo(ROOT))
+        die("not a git repository (or git is unavailable)");
+    const { abs, rel } = resolveArg(dir ?? ".");
+    const files = await computeRisk(abs, ROOT);
+    if (opts.json)
+        return jsonOut({ count: files.length, files });
+    header(`Refactor Risk \u2014 ${rel}/  ${dim("(churn × max complexity)")}`);
+    if (files.length === 0) {
+        console.log(indent(green("✓ nothing risky (no churn × complexity)")));
+        console.log();
+        return;
+    }
+    table(files.slice(0, opts.top).map((f) => [String(f.risk), `${f.churn} × ${f.maxComplexity}`, f.file]), [["Risk", 7], ["churn×cx", 12], ["File", 44]]);
+    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/contextpack.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+import { resolveFileImports } from "./resolver.js";
+import { buildCallGraph } from "./callgraph.js";
+function findSym(syms, name) {
+    for (const s of syms) {
+        if (s.name === name)
+            return s;
+        const n = findSym(s.children, name);
+        if (n)
+            return n;
+    }
+    return null;
+}
+const tok = (s) => Math.round(s.length / 4);
+/**
+ * Assemble the minimal context an agent needs to understand or change a symbol:
+ * the symbol's own source, the signatures of what it depends on (resolved
+ * imports), and the files that depend on it — instead of reading whole files.
+ */
+export async function packContext(absFile, relFile, root, symbolName, scanDir) {
+    const opts = resolveOptions({ detail: "full", emitHtml: false });
+    const skel = await buildSkeleton(absFile, relFile, opts);
+    const lines = fs.readFileSync(absFile, "utf8").split(/\r?\n/);
+    let startLine = 1, endLine = lines.length;
+    if (symbolName) {
+        const sym = findSym(skel.symbols, symbolName);
+        if (sym) {
+            startLine = sym.range.startLine;
+            endLine = sym.range.endLine;
+        }
+    }
+    const source = lines.slice(startLine - 1, endLine).join("\n");
+    // Dependencies: resolved in-project imports + the target symbol signatures.
+    const refs = await resolveFileImports(skel, absFile, root);
+    const byFile = new Map();
+    for (const r of refs) {
+        if (!r.found || !r.resolvedRel)
+            continue;
+        const arr = byFile.get(r.resolvedRel) ?? [];
+        if (!arr.some((x) => x.name === r.symbol))
+            arr.push({ name: r.symbol, signature: r.signature ?? null });
+        byFile.set(r.resolvedRel, arr);
+    }
+    const dependencies = [...byFile.entries()].map(([file, symbols]) => ({ file, symbols }));
+    // Dependents: who calls the seed symbol (needs a directory scan).
+    let dependents = [];
+    if (symbolName && scanDir) {
+        const sopts = resolveOptions({ detail: "outline", emitHtml: false });
+        const skels = [];
+        for (const f of collectSourceFiles(scanDir, sopts)) {
+            const rr = path.relative(root, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, rr, sopts));
+            }
+            catch { /* skip */ }
+        }
+        const cg = await buildCallGraph(absFile, symbolName, root, skels);
+        if (cg) {
+            const seen = new Set();
+            for (const c of cg.calledBy)
+                if (!seen.has(c.file)) {
+                    seen.add(c.file);
+                    dependents.push({ file: c.file });
+                }
+        }
+    }
+    const depTok = dependencies.reduce((a, d) => a + d.symbols.reduce((b, s) => b + tok(s.signature || s.name), 0), 0);
+    return {
+        seed: { file: relFile, ...(symbolName ? { symbol: symbolName } : {}) },
+        primary: { file: relFile, ...(symbolName ? { symbol: symbolName } : {}), startLine, endLine, source },
+        dependencies,
+        dependents,
+        tokenEstimate: tok(source) + depTok,
+        note: "Read primary.source in full; for dependencies you usually only need the listed signatures, not the whole files.",
+    };
+}

package/dist/gitdiff.js

@@ -0,0 +1,178 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+import { buildSymbolGraph } from "./graph.js";
+import { getChangeImpact } from "./graph-analysis.js";
+import { detectLanguage } from "./registry.js";
+import { computeFileComplexity } from "./complexity.js";
+function git(args, cwd) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+}
+export function isGitRepo(root) {
+    try {
+        git(["rev-parse", "--is-inside-work-tree"], root);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function changedFiles(root, base) {
+    let out;
+    try {
+        out = git(["diff", "--name-status", base, "--"], root);
+    }
+    catch {
+        return [];
+    }
+    const res = [];
+    for (const line of out.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const m = line.match(/^([AMD])\t(.+)$/);
+        if (m) {
+            res.push({ status: m[1], file: m[2] });
+            continue;
+        }
+        const r = line.match(/^R\d+\t\S+\t(.+)$/); // rename → treat new path as modified
+        if (r)
+            res.push({ status: "M", file: r[1] });
+    }
+    // Untracked files are new since any ref — treat them as added.
+    try {
+        const untracked = git(["ls-files", "--others", "--exclude-standard"], root);
+        for (const f of untracked.split(/\r?\n/)) {
+            if (f.trim() && !res.some((x) => x.file === f))
+                res.push({ status: "A", file: f });
+        }
+    }
+    catch { /* ignore */ }
+    return res.filter((f) => detectLanguage(f.file));
+}
+function oldContent(root, base, rel) {
+    try {
+        return git(["show", `${base}:${rel}`], root);
+    }
+    catch {
+        return null;
+    }
+}
+async function skeletonFromSource(source, rel) {
+    const ext = path.extname(rel);
+    const tmp = path.join(os.tmpdir(), `astdiff-${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`);
+    try {
+        fs.writeFileSync(tmp, source);
+        return await buildSkeleton(tmp, rel, resolveOptions({ detail: "full", emitHtml: false }));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+    }
+}
+function flatten(syms, prefix, acc) {
+    for (const s of syms) {
+        const q = prefix ? prefix + "." + s.name : s.name;
+        acc.set(q, s);
+        flatten(s.children, q, acc);
+    }
+    return acc;
+}
+const sc = (s) => ({ symbol: s.name, kind: s.kind, exported: s.exported ?? false });
+export async function computeDiff(absDir, root, base) {
+    const absDirNorm = path.resolve(absDir);
+    const changed = changedFiles(root, base).filter((f) => path.resolve(root, f.file).startsWith(absDirNorm));
+    const files = [];
+    const breaking = [];
+    for (const cf of changed) {
+        const rel = cf.file;
+        const newSkel = cf.status === "D" ? null : await safeBuildFromDisk(path.resolve(root, rel), rel);
+        const oldSrc = cf.status === "A" ? null : oldContent(root, base, rel);
+        const oldSkel = oldSrc != null ? await skeletonFromSource(oldSrc, rel) : null;
+        const oldMap = oldSkel ? flatten(oldSkel.symbols, "", new Map()) : new Map();
+        const newMap = newSkel ? flatten(newSkel.symbols, "", new Map()) : new Map();
+        const added = [], removed = [], modified = [];
+        for (const [q, s] of newMap)
+            if (!oldMap.has(q))
+                added.push(sc(s));
+        for (const [q, s] of oldMap)
+            if (!newMap.has(q))
+                removed.push(sc(s));
+        for (const [q, s] of newMap) {
+            const o = oldMap.get(q);
+            if (o && (o.signature ?? "") !== (s.signature ?? ""))
+                modified.push(sc(s));
+        }
+        const status = cf.status === "A" ? "added" : cf.status === "D" ? "deleted" : "modified";
+        files.push({ file: rel, status, added, removed, modified });
+        for (const r of removed)
+            if (r.exported && !r.symbol.includes(" ")) {
+                breaking.push({ file: rel, symbol: r.symbol, reason: cf.status === "D" ? "file deleted" : "export removed" });
+            }
+        for (const m of modified)
+            if (m.exported)
+                breaking.push({ file: rel, symbol: m.symbol, reason: "signature changed" });
+    }
+    // Blast radius of breaking changes (top-level symbols only).
+    const impacted = new Set();
+    if (breaking.length > 0) {
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const skels = [];
+        for (const f of collectSourceFiles(absDirNorm, opts)) {
+            const r = path.relative(root, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, r, opts));
+            }
+            catch { /* skip */ }
+        }
+        const graph = buildSymbolGraph(skels, root);
+        for (const b of breaking) {
+            const imp = getChangeImpact(graph, `${b.file}::${b.symbol}`);
+            if (imp)
+                for (const d of [...imp.direct, ...imp.transitive])
+                    if (d.file !== b.file)
+                        impacted.add(d.file);
+        }
+    }
+    const sum = files.reduce((a, f) => ({ added: a.added + f.added.length, removed: a.removed + f.removed.length, modified: a.modified + f.modified.length }), { added: 0, removed: 0, modified: 0 });
+    return {
+        base,
+        files,
+        breaking,
+        impactedFiles: [...impacted].sort(),
+        summary: { filesChanged: files.length, ...sum, breaking: breaking.length, impactedFiles: impacted.size },
+    };
+}
+async function safeBuildFromDisk(abs, rel) {
+    try {
+        return await buildSkeleton(abs, rel, resolveOptions({ detail: "full", emitHtml: false }));
+    }
+    catch {
+        return null;
+    }
+}
+export async function computeRisk(absDir, root) {
+    const opts = resolveOptions({ detail: "outline", emitHtml: false });
+    const out = [];
+    for (const f of collectSourceFiles(absDir, opts)) {
+        const rel = path.relative(root, f).split(path.sep).join("/");
+        let churn = 0;
+        try {
+            churn = parseInt(git(["rev-list", "--count", "HEAD", "--", rel], root).trim(), 10) || 0;
+        }
+        catch {
+            churn = 0;
+        }
+        const fc = await computeFileComplexity(f, rel);
+        const maxC = fc ? fc.maxComplexity : 0;
+        out.push({ file: rel, churn, maxComplexity: maxC, risk: churn * maxC });
+    }
+    return out.filter((r) => r.risk > 0).sort((a, b) => b.risk - a.risk);
+}

package/dist/index.js

@@ -20,6 +20,9 @@ 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";
+import { computeDiff, computeRisk, isGitRepo } from "./gitdiff.js";
+import { packContext } from "./contextpack.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 +770,95 @@ 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_diff ────────────────────────────────────── */
+server.registerTool("get_diff", {
+    title: "Git-aware change diff + blast radius",
+    description: "Compare the working tree against a git ref (default HEAD) and return which symbols were " +
+        "added/removed/modified per file, which changes are potentially **breaking** (removed or " +
+        "signature-changed exports), and the **blast radius** \u2014 files that depend on those breaking changes.",
+    inputSchema: {
+        base: z.string().optional().describe("Git ref to compare against. Default HEAD."),
+        path: z.string().optional().describe("Limit to a subdirectory. Default project root."),
+    },
+}, async ({ base, path: input }) => {
+    try {
+        if (!isGitRepo(ROOT))
+            return errorText("Not a git repository (or git is unavailable).");
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        const data = await computeDiff(abs, ROOT, base ?? "HEAD");
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", ...data });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
+/* ─────────────────── tool: get_risk_map ────────────────────────────────── */
+server.registerTool("get_risk_map", {
+    title: "Refactor risk map (churn \u00d7 complexity)",
+    description: "Rank files by refactor risk = git churn (number of commits touching the file) \u00d7 the file's " +
+        "max function complexity. Surfaces the files that are both frequently changed and complex \u2014 " +
+        "the most valuable refactor / test targets.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan. Default project root."),
+    },
+}, async ({ path: input }) => {
+    try {
+        if (!isGitRepo(ROOT))
+            return errorText("Not a git repository (or git is unavailable).");
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        const files = await computeRisk(abs, ROOT);
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", count: files.length, files: files.slice(0, 50) });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
+/* ─────────────────── tool: pack_context ────────────────────────────────── */
+server.registerTool("pack_context", {
+    title: "Minimal context pack for a symbol",
+    description: "Assemble the *minimal* context needed to understand or change a symbol \u2014 the symbol's own " +
+        "source, the signatures of what it depends on (resolved imports), and the files that depend on " +
+        "it \u2014 instead of reading whole files. Returns a token estimate so you can see the savings.",
+    inputSchema: {
+        path: z.string().describe("File containing the symbol (relative to root or absolute within it)."),
+        symbol: z.string().optional().describe("Symbol name to centre the pack on. Omit for the whole file."),
+        scan: z.string().optional().describe("Directory to scan for dependents. Default: project root."),
+    },
+}, async ({ path: input, symbol, scan }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input);
+        if (fs.statSync(abs).isDirectory())
+            return errorText(`"${input}" is a directory; pass a file.`);
+        const scanAbs = scan ? resolveInRoot(scan).abs : ROOT;
+        const pack = await packContext(abs, rel.split(path.sep).join("/"), ROOT, symbol, scanAbs);
+        return jsonText(pack);
+    }
+    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.13.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",