universal-ast-mapper 1.11.0 → 1.18.0

package/CHANGELOG.md

@@ -6,6 +6,65 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.18.0] — 2026-06-09 · Vue & Svelte SFC support
+- `.vue` and `.svelte` **single-file components** are now first-class inputs. The
+  `<script>` / `<script setup>` block is lifted out and parsed with the TS/JS extractor
+  (grammar chosen from `lang="ts"`), so component symbols and imports are extracted and
+  wired into the dependency graph — including edges from a component into a plain `.ts`
+  module, and into other components.
+- Offsets are preserved: everything outside the script is blank-padded, so every symbol
+  range still points at the exact line/column in the original SFC.
+- New languages `vue` and `svelte` (extensions `.vue`, `.svelte`); resolver now resolves
+  imports of `.vue` / `.svelte` files. **14 languages.**
+- Tests: 8 new assertions (127 total) + Vue/Svelte fixtures — symbol extraction, import
+  capture, and cross-file graph edges for both.
+
+## [1.17.0] — 2026-06-09 · MCP prompts
+- The server now registers **MCP prompts** — named, parameterized workflows a client
+  can invoke from its prompt/slash menu, each returning a ready-to-run instruction that
+  chains the right tools: `architecture_audit` (dir?), `safe_refactor` (file, symbol),
+  `dead_code_cleanup` (dir?), `health_check` (dir?), `onboard_codebase` (dir?).
+- The Cookbook recipes become first-class, discoverable, and one call away — no pasting.
+- New `test/prompts-smoke.mjs` (12 checks): `prompts/list` returns all 5, argument
+  interpolation works, and rendered prompts reference real tools. Wired into CI.
+
+## [1.16.0] — 2026-06-09 · Module coupling
+- **`get_module_coupling`** + **`ast-map modules`** (alias `mods`): aggregates the
+  file-level import graph up to the **directory/module level** — per-module afferent
+  (Ca) / efferent (Ce) coupling and instability, plus the weighted inter-module edges.
+  Intra-module imports (files importing siblings in the same directory) are ignored;
+  only cross-module dependencies count. The architectural view above per-file coupling.
+- Tests: 5 new assertions (119 total) — a three-module ui→api→core gradient with the
+  expected stability ordering and edge count.
+
+## [1.15.0] — 2026-06-09 · Layer-violation detection
+- **`get_layer_violations`** + **`ast-map layers`** (alias `sdp`): detect violations of
+  Robert C. Martin's **Stable Dependencies Principle** — a stable file (low instability)
+  that imports a more volatile one (high instability). Such dependencies point "uphill"
+  on the stability gradient and drag stable code along every time the volatile file churns.
+  Sorted by severity (the instability gap crossed). `minGap` filters small gaps.
+- Builds directly on the v1.14.0 coupling metrics.
+- Tests: 5 new assertions (114 total) — clean fixture yields none, a synthetic
+  stable→volatile graph yields exactly one with the correct severity.
+
+## [1.14.0] — 2026-06-09 · Coupling metrics
+- **`get_coupling`** + **`ast-map coupling [dir]`**: Robert C. Martin's per-file
+  coupling metrics — afferent coupling (Ca, fan-in), efferent coupling (Ce,
+  fan-out), and instability I = Ce/(Ca+Ce). High-Ca files are load-bearing (break
+  carefully); high-instability files change freely. Derived from the import graph.
+- Tests: 4 new assertions (109 total) verifying stable/unstable/middle files and
+  the [0,1] instability bound.
+
+## [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
@@ -93,41 +152,4 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
   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.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
-[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
+- Component s

package/README.md

@@ -4,7 +4,9 @@ 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.
 
-**Supported languages:** TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go · Rust · Java · C# · C · C++ · Kotlin · Swift
+**27 MCP tools / 28 CLI commands / 5 MCP prompts** spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators — plus monorepo support, an interactive **graph explorer** (`ast-map explore`), **watch mode**, 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 · **Vue** · **Svelte** (SFC `<script>`)
 
 | Capability               | TS/JS | Python | Go  | Rust | Java | C#  | C   | C++ | Kt  | Swift |
 |--------------------------|:-----:|:------:|:---:|:----:|:----:|:---:|:---:|:---:|:---:|:-----:|
@@ -102,6 +104,12 @@ 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 coupling  [dir]            [-n N]        # Ca / Ce / instability per file
+ast-map layers    [dir]            [-g gap]      # SDP: stable→volatile violations
+ast-map modules   [dir]                          # directory-level coupling + edges
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -348,6 +356,103 @@ 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_coupling`
+Per-file **coupling metrics** (Robert C. Martin): afferent coupling **Ca** (fan-in), efferent coupling **Ce** (fan-out), and **instability** I = Ce/(Ca+Ce) (0 = stable / load-bearing, 1 = unstable / volatile).
+
+```json
+{ "files": [ { "file": "src/types.ts", "afferent": 27, "efferent": 0, "instability": 0 } ] }
+```
+
+**Params:** `path` (optional)
+
+---
+
+### `get_layer_violations`
+Find dependencies that point **the wrong way on the stability gradient** — a stable file (low instability) importing a more volatile one (high instability), violating Martin's **Stable Dependencies Principle**. Sorted by severity (the instability gap crossed).
+
+```json
+{ "violations": [ { "from": "src/skeleton.ts", "to": "src/registry.ts", "fromInstability": 0.36, "toInstability": 0.6, "severity": 0.24 } ] }
+```
+
+**Params:** `path` (optional), `minGap` (optional, 0–1)
+
+---
+
+### `get_module_coupling`
+Aggregate the import graph up to the **directory/module level** — per-module Ca / Ce / instability plus the weighted inter-module edges. Intra-module imports are ignored, so this is the architectural bird's-eye view above per-file coupling.
+
+```json
+{
+  "modules": [ { "module": "src/extractors", "files": 11, "afferent": 1, "efferent": 1, "instability": 0.5 } ],
+  "edges": [ { "from": "src/extractors", "to": "src", "weight": 75 } ]
+}
+```
+
+**Params:** `path` (optional)
+
+---
+
 ### `get_change_impact`
 Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
 
@@ -578,6 +683,20 @@ Beyond tools, the server exposes the codebase as **browseable MCP resources**, s
 
 ---
 
+## MCP prompts — one-call recipes
+
+The server also registers **prompts**: named, parameterized workflows an MCP client can invoke directly (they show up in the client's prompt/slash menu). Each returns a ready-to-run instruction that chains the right tools, so you don't paste the recipe by hand.
+
+| Prompt | Args | What it does |
+|--------|------|--------------|
+| `architecture_audit` | `dir?` | God Nodes → cycles → rule violations → module coupling → SDP breaks, then a prioritized summary |
+| `safe_refactor` | `file`, `symbol` | blast radius → call graph → minimal context before changing a symbol |
+| `dead_code_cleanup` | `dir?` | unused exports, each verified zero-impact before deletion |
+| `health_check` | `dir?` | grade A–F → risk map → layer violations, with the 3 files to fix first |
+| `onboard_codebase` | `dir?` | languages → structure → core symbols → module map, as a "start here" guide |
+
+---
+
 ## GitHub Action — architecture gate in CI
 
 Use AST-MCP as a CI check with the bundled composite action (`action.yml`):
@@ -621,6 +740,13 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.18.0** | **Vue & Svelte SFC support** — `.vue` and `.svelte` single-file components are now parsed: the `<script>` / `<script setup>` block is lifted out (TS or JS) and its symbols + imports extracted, with cross-file graph edges into plain modules. Blank-padding keeps every symbol's line numbers pointing at the original SFC. **14 languages**. |
+| **1.17.0** | **MCP prompts** — the server now registers 5 parameterized **prompts** (`architecture_audit`, `safe_refactor`, `dead_code_cleanup`, `health_check`, `onboard_codebase`): named workflows a client can invoke from its prompt menu, each chaining the right tools. The Cookbook recipes, one call away. |
+| **1.16.0** | **Module coupling** — new `get_module_coupling` MCP tool + `ast-map modules` (alias `mods`) CLI: aggregates the import graph to the **directory/module level** — per-module Ca / Ce / instability plus weighted inter-module edges (intra-module imports ignored). The bird's-eye view above per-file coupling. **27 MCP tools**. |
+| **1.15.0** | **Layer-violation detection** — new `get_layer_violations` MCP tool + `ast-map layers` (alias `sdp`) CLI: flags dependencies that break Martin's **Stable Dependencies Principle** — a stable file (low instability) importing a more volatile one — sorted by the instability gap. Builds directly on the coupling metrics. **26 MCP tools**. |
+| **1.14.0** | **Coupling metrics** — new `get_coupling` MCP tool + `ast-map coupling [dir]` CLI: per-file afferent (Ca) / efferent (Ce) coupling and **instability** I = Ce/(Ca+Ce), the way to spot load-bearing files (high Ca) vs. volatile ones (high I). **25 MCP tools**. |
+| **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`). |
@@ -641,19 +767,4 @@ Not part of the public API: the internal `src/` module layout and the generated
 | **0.9.0** | **Scoped type-flow tracing** — new `trace_type` MCP tool + `ast-map trace-type` (alias `flow`) CLI: follow a named type through function params, return types, typed variables, and class fields across a directory. Completes the deeper-analysis suite (dead code · cycles · impact · complexity · duplicates · unused params · type flow). **18 MCP tools**. |
 | **0.8.7** | **Python decorators in the call graph** — function/method symbols now carry a `decorators` field (`@router.get("/x")` → `router.get("/x")`), surfaced in skeletons (outline + full) and in `get_call_graph`. Traces framework wiring like FastAPI/Flask routes and `@staticmethod`/`@property` stacks to their handler. |
 | **0.8.6** | **Unused parameter detection** — new `find_unused_params` MCP tool + `ast-map unused-params` (alias `unused`) CLI: named functions whose params are never referenced. Skips `_`-prefixed/destructured/anonymous and treats object-shorthand as a use (low false-positive). Server now 17 tools. |
-| **0.8.5** | **Cyclomatic complexity** — new `get_complexity` MCP tool + `ast-map complexity` (alias `cx`, `--min N`) CLI: per-function AST-based complexity score (`1 + if/for/while/case/catch/ternary/&&/\|\|`) with low/moderate/high/very-high ratings and directory hotspots. Server now 16 tools. |
-| **0.8.4** | **Duplicate symbol detection** — new `find_duplicate_symbols` MCP tool + `ast-map duplicates` (alias `dupes`) CLI command: finds symbol names exported from more than one file, with every file/kind that declares each name. |
-| **0.8.3** | **TSX/React component props** — component symbols now carry extracted prop fields. PascalCase functions/arrows that return JSX or are typed `React.FC<P>`/`FC<P>` get `propsType` (named props type) + `props[]` (name, type, optional), resolved from same-file `interface`/`type` declarations or inline object types. Plus: MCP server now reports its real version from `package.json` (was hardcoded `0.5.3`). |
-| **0.8.2** | **Swift cross-file wiring** — `import <Module>` resolves to that module's files (module = the `Sources/<Module>/` directory, else parent dir), wired into `build_symbol_graph` + `resolve_imports`. System modules (Foundation, UIKit, …) stay external. Completes cross-file graph/resolver support for all four v0.8.0 languages. |
-| **0.8.1** | **Cross-file graph wiring for Kotlin & C/C++** — Kotlin FQCN/package index + C/C++ `#include` resolution (with header↔impl pairing) wired into `build_symbol_graph`, `resolve_imports`, and `get_call_graph`. Fixes a parse-cache rel-path leak (stale `.file` poisoned the cross-lang index → doubled paths) and Kotlin call-graph extraction (`function_declaration` name + field-less `call_expression`). |
-| **0.8.0** | **4 new languages: C · C++ · Kotlin · Swift** — symbol extraction + imports parsing. C++ tracks access_specifier through class bodies. Kotlin handles `package`/`object`/`data class`. Swift handles `class`/`struct`/`enum` (all under `class_declaration`) and `protocol_declaration`. Ruby grammar in tree-sitter-wasms@0.1.13 is unstable — skipped. |
-| **0.7.0** | Go full resolution (reads `go.mod`, resolves package-as-directory) · C# reverse `calledBy` via call-site scanning · `csharpTypes` index lets `using` directives resolve to specific types · 4-suite test harness (smoke + graph-smoke + resolver-smoke + callgraph-smoke) |
-| **0.6.0** | **3 new languages: Rust · Java · C#** (extractors + import parsing) · cross-language resolver in `crosslang.ts` (Java FQCN index, C# namespace index, Rust `crate::` module walk) · symbol-graph `imports` edges + `resolveFileImports` enrichment + `get_call_graph` callee resolution rewired through it · Java `package` and C# `namespace` captured as directives |
-| **0.5.3** | Auto-install `/ast-map` Claude Code skill on `npm install` · `postinstall` writes `~/.claude/skills/ast-map/SKILL.md` + registers trigger in `CLAUDE.md` (idempotent, CI-safe) |
-| **0.5.2** | Iterative DFS in `findCircularDeps` (eliminates stack overflow on large codebases) · `build_symbol_graph` inline size guard (>2000 nodes → stats + warning) · integration test suite (`test/analysis.mjs`) |
-| **0.5.1** | Re-export tracking (`export { X } from './foo'`, barrel files) · `export const` surfaced as symbols · `const X = class {}` support · Python relative import fix · parser instance cache |
-| **0.5.0** | Call graph destructuring aliases · in-process parse cache · `.ast-map.config.json` · general validation rules (large-file, too-many-imports, god-export) |
-| **0.4.0** | `search_symbol` · `get_file_deps` · `get_top_symbols` · dead code confidence tiers · 3 new CLI commands |
-| **0.3.0** | `ast-map` 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` |
+| **0.8.5** | **Cyclomatic complexity** — new `get_complexity` MCP tool + `ast-map complex

package/dist/cli.js

@@ -17,6 +17,11 @@ 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 { computeCoupling } from "./coupling.js";
+import { findLayerViolations } from "./layers.js";
+import { computeModuleCoupling } from "./modulecoupling.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -447,6 +452,183 @@ 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: coupling ────────────────────────────────────────────────────────
+program
+    .command("coupling [dir]")
+    .description("Per-file coupling metrics: afferent (Ca), efferent (Ce), instability")
+    .option("--json", "Output as JSON")
+    .option("-n, --top <n>", "Show top N by total coupling", (v) => parseInt(v, 10), 25)
+    .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 metrics = computeCoupling(buildSymbolGraph(skeletons, ROOT));
+    if (opts.json)
+        return jsonOut({ count: metrics.length, files: metrics });
+    header(`Coupling \u2014 ${rel}/  ${dim("(Ca = fan-in, Ce = fan-out, I = instability)")}`);
+    if (metrics.length === 0) {
+        console.log(indent(dim("No import edges found.")));
+        console.log();
+        return;
+    }
+    const icolor = (i) => (i >= 0.8 ? red : i <= 0.2 ? green : yellow);
+    table(metrics.slice(0, opts.top).map((m) => [String(m.afferent), String(m.efferent), icolor(m.instability)(m.instability.toFixed(2)), m.file]), [["Ca", 4], ["Ce", 4], ["I", 6], ["File", 46]]);
+    console.log(indent(dim("high Ca = load-bearing (break carefully) · high I = volatile")));
+    console.log();
+});
+// ─── Command: layers ──────────────────────────────────────────────────────────
+program
+    .command("layers [dir]")
+    .alias("sdp")
+    .description("Stable Dependencies Principle: stable files that depend on volatile ones")
+    .option("--json", "Output as JSON")
+    .option("-g, --min-gap <n>", "Only show violations with instability gap > n", (v) => parseFloat(v), 0)
+    .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 violations = findLayerViolations(buildSymbolGraph(skeletons, ROOT), opts.minGap);
+    if (opts.json)
+        return jsonOut({ count: violations.length, violations });
+    header(`Layer Violations \u2014 ${rel}/  ${dim("(stable \u2192 volatile dependencies, SDP)")}`);
+    if (violations.length === 0) {
+        console.log(indent(green("\u2713 No SDP violations \u2014 dependencies flow toward stability.")));
+        console.log();
+        return;
+    }
+    for (const v of violations) {
+        const sev = v.severity >= 0.4 ? red : v.severity >= 0.2 ? yellow : dim;
+        console.log(indent(`${sev(v.severity.toFixed(2))}  ${bold(v.from)} ${dim(`(I=${v.fromInstability})`)} ${red("\u2192")} ${v.to} ${dim(`(I=${v.toInstability})`)}`));
+    }
+    console.log();
+    console.log(indent(dim(`${violations.length} stable file(s) depend on more volatile ones \u2014 they churn when those do`)));
+    console.log();
+});
+// ─── Command: modules ─────────────────────────────────────────────────────────
+program
+    .command("modules [dir]")
+    .alias("mods")
+    .description("Directory/module-level coupling: per-module Ca / Ce / instability + edges")
+    .option("--json", "Output as JSON")
+    .action(async (dir, opts) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const skeletons = await gatherSkeletons(abs);
+    const mc = computeModuleCoupling(buildSymbolGraph(skeletons, ROOT));
+    if (opts.json)
+        return jsonOut(mc);
+    header(`Module Coupling \u2014 ${rel}/  ${dim("(directory-level Ca / Ce / instability)")}`);
+    if (mc.modules.length === 0) {
+        console.log(indent(dim("No cross-module imports found.")));
+        console.log();
+        return;
+    }
+    const icolor = (i) => (i >= 0.8 ? red : i <= 0.2 ? green : yellow);
+    table(mc.modules.map((m) => [String(m.files), String(m.afferent), String(m.efferent), icolor(m.instability)(m.instability.toFixed(2)), m.module]), [["Files", 6], ["Ca", 4], ["Ce", 4], ["I", 6], ["Module", 40]]);
+    if (mc.edges.length) {
+        console.log(indent(bold("Inter-module dependencies:")));
+        for (const e of mc.edges.slice(0, 20))
+            console.log(indent(`  ${e.from} ${dim("\u2192")} ${e.to} ${dim(`(${e.weight})`)}`));
+    }
+    console.log();
+});
 // ─── Command: report ──────────────────────────────────────────────────────────
 program
     .command("report [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/coupling.js

@@ -0,0 +1,35 @@
+/**
+ * Compute Robert C. Martin's coupling metrics per file from the symbol graph's
+ * file-level import edges: afferent (fan-in), efferent (fan-out), and instability.
+ */
+export function computeCoupling(graph) {
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    const out = new Map(); // file -> set of files it imports
+    const inc = new Map(); // file -> set of files that import it
+    const files = new Set();
+    for (const n of graph.nodes)
+        if (n.nodeType === "file")
+            files.add(n.id);
+    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;
+        const fromFile = e.from;
+        if (!toFile || fromFile === toFile)
+            continue;
+        files.add(fromFile);
+        files.add(toFile);
+        (out.get(fromFile) ?? out.set(fromFile, new Set()).get(fromFile)).add(toFile);
+        (inc.get(toFile) ?? inc.set(toFile, new Set()).get(toFile)).add(fromFile);
+    }
+    const metrics = [];
+    for (const f of files) {
+        const ce = out.get(f)?.size ?? 0;
+        const ca = inc.get(f)?.size ?? 0;
+        const instability = ca + ce === 0 ? 0 : Math.round((ce / (ca + ce)) * 100) / 100;
+        metrics.push({ file: f, afferent: ca, efferent: ce, instability });
+    }
+    // Sort by total coupling desc (most-connected first).
+    return metrics.sort((a, b) => (b.afferent + b.efferent) - (a.afferent + a.efferent) || a.file.localeCompare(b.file));
+}

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/graph.js

@@ -27,7 +27,9 @@ function isPathBasedLanguage(language) {
     return (language === "typescript" ||
         language === "tsx" ||
         language === "javascript" ||
-        language === "python");
+        language === "python" ||
+        language === "vue" ||
+        language === "svelte");
 }
 // Wire one TS/JS/Python-style relative import.
 function wirePathImport(skel, imp, fromFileAbs, root, exportedSymbolMap, edges) {

package/dist/index.js

@@ -21,6 +21,12 @@ 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";
+import { computeCoupling } from "./coupling.js";
+import { findLayerViolations } from "./layers.js";
+import { computeModuleCoupling } from "./modulecoupling.js";
+import { registerPrompts } from "./prompts.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) {
@@ -65,6 +71,7 @@ const server = new McpServer({
     name: "universal-ast-mapper",
     version: PKG_VERSION,
 });
+registerPrompts(server);
 /* ----------------------- tool: list_supported_languages ----------------------- */
 server.registerTool("list_supported_languages", {
     title: "List supported languages",
@@ -790,6 +797,172 @@ server.registerTool("get_codebase_report", {
         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_coupling ────────────────────────────────── */
+server.registerTool("get_coupling", {
+    title: "Coupling metrics (afferent / efferent / instability)",
+    description: "Compute Robert C. Martin's coupling metrics per file from the import graph: afferent coupling " +
+        "(Ca, fan-in), efferent coupling (Ce, fan-out), and instability I = Ce/(Ca+Ce) (0 = stable, " +
+        "1 = unstable). High-Ca files are load-bearing; high-instability files change freely.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan. Default project root."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. get_coupling requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const skels = [];
+        for (const f of files) {
+            const r = path.relative(ROOT, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, r, opts));
+            }
+            catch { /* skip */ }
+        }
+        const metrics = computeCoupling(buildSymbolGraph(skels, ROOT));
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", count: metrics.length, files: metrics });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
+/* ─────────────────── tool: get_layer_violations ────────────────────────── */
+server.registerTool("get_layer_violations", {
+    title: "Layer violations (Stable Dependencies Principle)",
+    description: "Find dependencies that point the wrong way on the stability gradient: a stable file " +
+        "(low instability) that imports a more volatile file (high instability). Per Robert C. Martin's " +
+        "Stable Dependencies Principle, stable code should not depend on volatile code — it gets dragged " +
+        "along every time the volatile file churns. Results are sorted by severity (the instability gap).",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan. Default project root."),
+        minGap: z.number().optional().describe("Only report violations whose instability gap exceeds this (0-1). Default 0."),
+    },
+}, async ({ path: input, minGap }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. get_layer_violations requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const skels = [];
+        for (const f of files) {
+            const r = path.relative(ROOT, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, r, opts));
+            }
+            catch { /* skip */ }
+        }
+        const violations = findLayerViolations(buildSymbolGraph(skels, ROOT), minGap ?? 0);
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", count: violations.length, violations });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
+/* ─────────────────── tool: get_module_coupling ─────────────────────────── */
+server.registerTool("get_module_coupling", {
+    title: "Module coupling (directory-level Ca / Ce / instability)",
+    description: "Aggregate the import graph up to the directory/module level: per-module afferent (Ca) / " +
+        "efferent (Ce) coupling and instability, plus the weighted inter-module edges. Intra-module " +
+        "imports (files importing siblings in the same directory) are ignored — only cross-module " +
+        "dependencies count. The architectural bird's-eye view above per-file coupling.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan. Default project root."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. get_module_coupling requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const skels = [];
+        for (const f of files) {
+            const r = path.relative(ROOT, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, r, opts));
+            }
+            catch { /* skip */ }
+        }
+        const mc = computeModuleCoupling(buildSymbolGraph(skels, ROOT));
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", moduleCount: mc.modules.length, ...mc });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/dist/layers.js

@@ -0,0 +1,36 @@
+import { computeCoupling } from "./coupling.js";
+/**
+ * Detect violations of Robert C. Martin's Stable Dependencies Principle (SDP):
+ * a module should depend only on modules at least as stable as itself. A "stable"
+ * file (low instability) that imports a "volatile" file (high instability) is a
+ * violation — volatile code changes often and will keep dragging the stable code
+ * with it. Severity is the instability gap the dependency crosses.
+ */
+export function findLayerViolations(graph, minGap = 0) {
+    const inst = new Map(computeCoupling(graph).map((m) => [m.file, m.instability]));
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    const seen = new Set();
+    const violations = [];
+    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;
+        const fromFile = e.from;
+        if (!toFile || fromFile === toFile)
+            continue;
+        const fi = inst.get(fromFile);
+        const ti = inst.get(toFile);
+        if (fi === undefined || ti === undefined)
+            continue;
+        const severity = Math.round((ti - fi) * 100) / 100;
+        if (severity <= minGap)
+            continue; // only "uphill" dependencies (stable -> volatile)
+        const key = fromFile + " " + toFile;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        violations.push({ from: fromFile, to: toFile, fromInstability: fi, toInstability: ti, severity });
+    }
+    return violations.sort((a, b) => b.severity - a.severity || a.from.localeCompare(b.from));
+}

package/dist/prompts.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/** GetPromptResult helper — a single user-role text message. */
+function userPrompt(text) {
+    return { messages: [{ role: "user", content: { type: "text", text } }] };
+}
+const dirArg = { dir: z.string().optional().describe("Directory to analyze, relative to the project root. Default 'src'.") };
+const d = (dir) => (dir && dir.trim() ? dir.trim() : "src");
+/**
+ * Register the Cookbook recipes as MCP prompts so clients can invoke a whole
+ * AST-MCP workflow (a chain of tool calls) by name, instead of the user pasting
+ * the recipe text. Each prompt returns a ready-to-run instruction that references
+ * the server's own tools.
+ */
+export function registerPrompts(server) {
+    server.registerPrompt("architecture_audit", {
+        title: "Architecture audit",
+        description: "Full structural audit of a directory: God Nodes, cycles, rule violations, and module coupling.",
+        argsSchema: dirArg,
+    }, ({ dir }) => userPrompt(`Run a full architecture audit of \`${d(dir)}\` using the ast-mapper tools, in this order:\n\n` +
+        `1. \`build_symbol_graph\` on \`${d(dir)}\` to load the dependency graph.\n` +
+        `2. \`get_top_symbols\` — identify the 5 most-imported symbols (the "God Nodes").\n` +
+        `3. \`find_circular_deps\` — report any circular import chains.\n` +
+        `4. \`validate_architecture\` — list structural rule violations (large files, too many imports, god exports).\n` +
+        `5. \`get_module_coupling\` — which directories are load-bearing (high Ca) vs. volatile (high I)?\n` +
+        `6. \`get_layer_violations\` — any stable code depending on volatile code (SDP breaks)?\n\n` +
+        `Then write a short prioritized summary: the top 3 architectural risks and a concrete first step for each.`));
+    server.registerPrompt("safe_refactor", {
+        title: "Safe refactor checklist",
+        description: "Everything you need to know before changing a specific symbol: blast radius, callees, and minimal context.",
+        argsSchema: {
+            file: z.string().describe("File containing the symbol, relative to the project root."),
+            symbol: z.string().describe("Name of the function/class/symbol you intend to change."),
+        },
+    }, ({ file, symbol }) => userPrompt(`Before refactoring \`${symbol}\` in \`${file}\`, gather the impact using the ast-mapper tools:\n\n` +
+        `1. \`get_change_impact\` for \`${file}\` / \`${symbol}\` — who depends on it (the blast radius)?\n` +
+        `2. \`get_call_graph\` — what does \`${symbol}\` call, and what calls it?\n` +
+        `3. \`pack_context\` for \`${file}\` / \`${symbol}\` — the minimal context (its source + the signatures it depends on).\n\n` +
+        `Then summarize: what will break if the signature changes, which call sites need updating, and a safe step-by-step refactor order.`));
+    server.registerPrompt("dead_code_cleanup", {
+        title: "Dead-code cleanup",
+        description: "Find unused exports and verify each is safe to delete before removing it.",
+        argsSchema: dirArg,
+    }, ({ dir }) => userPrompt(`Help me remove dead code from \`${d(dir)}\` using the ast-mapper tools:\n\n` +
+        `1. \`find_dead_code\` on \`${d(dir)}\` — list exported symbols nobody imports.\n` +
+        `2. For each HIGH-confidence result, double-check with \`get_change_impact\` (should be empty).\n` +
+        `3. Before suggesting deletion, show the symbol's source with \`get_symbol_context\`.\n\n` +
+        `Produce a deletion checklist: only symbols that are high-confidence AND have zero impact. Flag anything dynamic (string-referenced, re-exported) as "verify manually".`));
+    server.registerPrompt("health_check", {
+        title: "Codebase health check",
+        description: "A one-pass health report: overall grade, riskiest files, and stability inversions.",
+        argsSchema: dirArg,
+    }, ({ dir }) => userPrompt(`Give me a health check of \`${d(dir)}\` using the ast-mapper tools:\n\n` +
+        `1. \`get_codebase_report\` on \`${d(dir)}\` — overall grade A–F, hotspots, god nodes, dead code, cycles.\n` +
+        `2. \`get_risk_map\` — the files with the highest churn × complexity (best refactor / test targets).\n` +
+        `3. \`get_layer_violations\` — stable files depending on volatile ones.\n\n` +
+        `Summarize as: the grade, the single biggest problem, and the 3 files I should touch first to improve it.`));
+    server.registerPrompt("onboard_codebase", {
+        title: "Onboard to a codebase",
+        description: "Get oriented in an unfamiliar directory: languages, structure, the core symbols, and how modules connect.",
+        argsSchema: dirArg,
+    }, ({ dir }) => userPrompt(`I'm new to this codebase. Walk me through \`${d(dir)}\` using the ast-mapper tools:\n\n` +
+        `1. \`list_supported_languages\` then \`generate_skeleton\` on \`${d(dir)}\` — what languages and overall shape?\n` +
+        `2. \`get_top_symbols\` — the most-depended-on symbols are the concepts to learn first.\n` +
+        `3. \`get_module_coupling\` — how do the directories relate; what's the stable core?\n` +
+        `4. For the top God Node, \`get_symbol_context\` with related symbols to see how it's used.\n\n` +
+        `Then write a 5-bullet "start here" orientation: what this code does, its core abstractions, and where to begin reading.`));
+}

package/dist/registry.js

@@ -16,6 +16,14 @@ const TS_ENTRY = (language, grammar) => ({
     extractDirectives: extractDirectivesTS,
     extractImports: extractImportsTS,
 });
+const SFC_ENTRY = (language) => ({
+    language,
+    grammar: "typescript", // overridden per-file after detecting lang="ts" vs js
+    extract: extractTypeScript,
+    extractDirectives: extractDirectivesTS,
+    extractImports: extractImportsTS,
+    sfc: true,
+});
 const BY_EXT = {
     ".ts": TS_ENTRY("typescript", "typescript"),
     ".mts": TS_ENTRY("typescript", "typescript"),
@@ -54,6 +62,8 @@ const BY_EXT = {
         extract: extractKotlin, extractDirectives: extractDirectivesKotlin, extractImports: extractImportsKotlin,
     },
     ".swift": { language: "swift", grammar: "swift", extract: extractSwift, extractImports: extractImportsSwift },
+    ".vue": SFC_ENTRY("vue"),
+    ".svelte": SFC_ENTRY("svelte"),
 };
 export function detectLanguage(filePath) {
     return BY_EXT[path.extname(filePath).toLowerCase()] ?? null;

package/dist/resolver.js

@@ -5,7 +5,7 @@ import { resolveOptions } from "./config.js";
 import { findSymbol } from "./analysis.js";
 import { buildCrossLangIndex, resolveCrossLangTarget, } from "./crosslang.js";
 import { resolveWorkspaceImportCached } from "./workspace.js";
-const SRC_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+const SRC_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".vue", ".svelte"];
 function extractParams(sig) {
     const start = sig.indexOf("(");
     if (start === -1)

package/dist/sfc.js

@@ -0,0 +1,27 @@
+const SCRIPT_RE = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+export function isSfcExt(ext) {
+    return ext === ".vue" || ext === ".svelte";
+}
+export function extractScript(source) {
+    // Start from an all-blank canvas the same shape as the source (newlines kept,
+    // every other character turned into a space) to preserve line/column offsets.
+    let out = source.replace(/[^\n]/g, " ");
+    let hasScript = false;
+    let lang = "js";
+    let m;
+    SCRIPT_RE.lastIndex = 0;
+    while ((m = SCRIPT_RE.exec(source)) !== null) {
+        hasScript = true;
+        const attrs = m[1] ?? "";
+        if (/lang\s*=\s*["'](ts|typescript)["']/i.test(attrs))
+            lang = "ts";
+        const inner = m[2] ?? "";
+        const innerStart = m.index + m[0].indexOf(inner, m[1] ? m[1].length : 0);
+        out = out.slice(0, innerStart) + inner + out.slice(innerStart + inner.length);
+    }
+    return {
+        code: hasScript ? out : "",
+        grammar: lang === "ts" ? "typescript" : "javascript",
+        hasScript,
+    };
+}

package/dist/skeleton.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { detectLanguage, supportedExtensions } from "./registry.js";
 import { parseSource } from "./parser.js";
 import { countSymbols, toOutline } from "./extractors/common.js";
+import { extractScript } from "./sfc.js";
 export const SCHEMA_VERSION = "1.1";
 export const GRAMMAR_SOURCE = "tree-sitter-wasms@0.1.13";
 const parseCache = new Map();
@@ -57,8 +58,14 @@ export async function buildSkeleton(absPath, relPath, opts) {
         const wantFile = relPath.split(path.sep).join("/");
         return cached.file === wantFile ? cached : { ...cached, file: wantFile };
     }
-    const source = fs.readFileSync(absPath, "utf8");
-    const root = await parseSource(entry.grammar, source);
+    let source = fs.readFileSync(absPath, "utf8");
+    let grammar = entry.grammar;
+    if (entry.sfc) {
+        const script = extractScript(source);
+        source = script.code; // blank-padded script-only source (offsets preserved)
+        grammar = script.grammar;
+    }
+    const root = await parseSource(grammar, source);
     let symbols = entry.extract(root, source);
     if (opts.detail === "outline")
         symbols = toOutline(symbols);
@@ -69,7 +76,7 @@ export async function buildSkeleton(absPath, relPath, opts) {
         file: relPath.split(path.sep).join("/"),
         language: entry.language,
         generatedAt: new Date().toISOString(),
-        parser: { engine: "tree-sitter", grammar: `${entry.grammar} (${GRAMMAR_SOURCE})` },
+        parser: { engine: "tree-sitter", grammar: `${grammar} (${GRAMMAR_SOURCE})` },
         symbolCount: countSymbols(symbols),
         ...(directives.length > 0 ? { directives } : {}),
         ...(imports.length > 0 ? { imports } : {}),

package/package.json

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