2.0.8 • Published 6d agoCLI

universal-ast-mapper

Licence

MIT

Version

2.0.8

Deps

Size

899 kB

Vulns

Weekly

1.2K

Install scriptsThis package runs scripts during installation (preinstall/install/postinstall)

Summary Dependency Versions

AST-MCP — Universal Code Skeleton & Dependency Graph

An MCP server + CLI tool that turns source code into structured, machine-readable skeletons and symbol-level dependency graphs — so AI agents can reason about large codebases without reading every file.

Built on tree-sitter WASM grammars. Zero regex guessing — real AST parsing.

44 MCP tools / 49 CLI commands / 5 MCP prompts spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators, test-coverage mapping — plus monorepo support, an interactive graph explorer with a coupling overlay (ast-map explore), watch mode, a one-page health dashboard with test-coverage, coupling and SDP cards (ast-map report), a persistent parse cache + parallel parsing (warm re-scans skip parsing entirely), a CI quality gate (ast-map check, baseline ratchet), code smell + security scanning with AI-powered auto-patch (ast-map patch), AI test generation (ast-map testgen --ai), Mermaid diagram export (ast-map diagram), a full-featured web SPA (ast-map serve), custom lint plugins (ast-map plugins), and new in v2.0.0: persistent skeleton index, architecture import rules, TF-IDF re-ranking for semantic search, and API doc generation.

Supported languages: TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go · Rust · Java · C# · C · C++ · Kotlin · Swift · Vue · Svelte (SFC <script>) · PHP · Ruby

Capability	C	C++	Swift	PHP	Ruby
Symbol extraction
Imports parsing
Graph `imports` edges				—	—
`resolve_imports` enrich				—	—
Call graph callee origin	—	—	—	—	—
Reverse `calledBy`	—	—	—	—	—

As of v0.8.2, all four v0.8.0 languages have cross-file graph + resolver wiring: Kotlin (FQCN/package index), C/C++ (#include with headerimpl pairing), and Swift (module = directory under Sources/). Call-graph callee origin is resolved for Kotlin; for C/C++/Swift it stays limited because their imports don't name individual symbols. (PHP & Ruby landed in v1.22.0 — symbol extraction + imports; cross-file graph wiring for them is the next step. Ruby was unblocked by upgrading web-tree-sitter to 0.21.0.)

Each language uses the resolution strategy that fits it:

TS/JS/Python — relative paths (./foo, ..mod) resolved against the importing file's directory, with TS-ESM .js → .ts rewriting. Path aliases (@/* etc.) resolve via the nearest tsconfig.json/jsconfig.json (paths + baseUrl, relative extends). (v1.24.0)
Go — go.mod ancestor lookup → module path prefix → package directory → all .go files (skips _test.go).
Rust — Cargo.toml ancestor → crate:: / self:: / super:: walks; supports mod.rs + Rust-2018 sibling-dir style.
Java — project-wide FQCN index (package + "." + className → file) built lazily on first cross-lang call; supports wildcard imports.
C# — namespace-to-files index plus a <ns>.<TypeName> index so using App.Models + new Inventory() resolves to the right file.
Kotlin — project-wide FQCN index (package + "." + ClassName → file), like Java; wildcard import pkg.* pulls every file in the package.
C / C++ — #include "..." resolved against the including file's directory; headers auto-paired with same-name .c/.cpp/.cc/.cxx impl files. <system> includes stay external.

For C# and Go (where imports don't name the called symbol), reverse calledBy falls back to call-site scanning of candidate files.

Quick Start

npm install && npm run build

# CLI
ast-map --help
ast-map langs
ast-map dead src/
ast-map validate src/

# Or without installing globally
node dist/cli.js dead src/

Two Ways to Use

Mode	Entry Point	When to Use
CLI (`ast-map`)	`dist/cli.js`	Terminal, CI scripts, quick checks
MCP Server	`dist/index.js`	AI agents (Claude, Cursor, etc.)

MCP Setup — Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ast-mapper": {
      "command": "node",
      "args": ["C:\\path\\to\\AST-MCP\\dist\\index.js"],
      "env": {
        "AST_MAP_ROOT": "C:\\path\\to\\your\\project"
      }
    }
  }
}

AST_MAP_ROOT is the security boundary — the server only reads files inside this path.

Since v1.23.0 the boundary is configurable:

Multi-root — list several projects in AST_MAP_ROOT, separated by the OS path delimiter (; on Windows, : on macOS/Linux). The first root is the primary (relative paths resolve against it):

      "env": { "AST_MAP_ROOT": "C:\\proj\\app;C:\\proj\\chem_sc_su" }

Unlocked — set AST_MAP_UNLOCKED: "1" to let the server analyze any absolute path the client asks for (relative paths still resolve against the primary root). Use this for a personal "analyze anything" setup; keep it off for shared/untrusted environments:

      "env": { "AST_MAP_ROOT": "C:\\proj\\app", "AST_MAP_UNLOCKED": "1" }

CLI Reference

All commands default to cwd as root. Override with AST_MAP_ROOT=/path/to/project ast-map <cmd>.
Add --json to any command for machine-readable output.

ast-map langs
ast-map skeleton <path>            [-d outline|full] [--html] [--combine] [-o dir]
ast-map symbol   <file> <name>     [-k kind] [--related]
ast-map imports  <file>
ast-map graph    <dir>             [-o graph.json]
ast-map validate <path>            [--max-lines N] [--max-imports N] [--max-exports N]
ast-map dead     <dir>
ast-map cycles   <dir>
ast-map duplicates <dir>           [alias: dupes]
ast-map complexity <path>          [alias: cx] [--min N]
ast-map unused-params <path>       [alias: unused]
ast-map trace-type <type> [dir]    [alias: flow]
ast-map workspace [dir]            [alias: ws]
ast-map explore   [dir]            [-o out.html]
ast-map watch     [dir]            [-o out.html]
ast-map sourcemap <file>
ast-map report    [dir]            [-o report.html]
ast-map dashboard [dir]                          # audit KPI summary (dead/cycles/smells/risk)
ast-map history   [dir]                          # historical health trend chart
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 cache     [stats|clear]                  # persistent parse cache (.ast-map/cache)
ast-map check     [dir]            [--update-baseline] [--min-score N] [--max-cycles N] ...
ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
ast-map find     <query> [dir]     [-l N] [-k kind] [-e] [--rerank] [--api-key KEY]
ast-map tests    [dir]             [alias: coverage] [-u] [--links] [-n N]
ast-map testgen  <path>            [--framework vitest|jest|mocha|node|pytest|gotest] [--ai]
ast-map smells   [path]            [--changed-since <ref>] [--json]
ast-map security [path]            [--min-severity critical|high|medium|low] [--changed-since <ref>]
ast-map diagram  [dir]             [--type class|deps|modules] [--max-nodes N]
ast-map fix      [dir]             [--ai] [--min-priority 1|2|3] [--api-key KEY]
ast-map init                       [--defaults]  # scaffold .ast-map.json + plugin example
ast-map deps     <file>            [--scan <dir>]
ast-map top      <dir>             [-n 10]
ast-map impact   <file> <symbol>   [--scan <dir>]
ast-map calls    <file> <fn>       [--scan <dir>]
ast-map explain  <file> <symbol>   [--scan <dir>] [--ai] [--api-key KEY]
ast-map similar  [dir]             [--kinds fn,class] [--min-group N]
ast-map serve    [dir]             [--port N] [--watch]   # web SPA + REST + SSE
ast-map covmerge <report>          [--format auto|istanbul|lcov|clover|cobertura]
ast-map plugins  [dir]                           # run .ast-map/plugins/*.mjs
ast-map index    [dir]             [--force]     # build .ast-map/index.json
ast-map arch     [dir]                           # check architecture import rules (CI-friendly)
ast-map patch    [dir]             [-y] [--severity error|warning] [--smells-only] [--security-only]
ast-map doc      [dir]             [-o file] [--html] [--exported-only] [--ai] [--api-key KEY]

Examples

# What does this file export?
ast-map skeleton src/lib/auth.ts

# Show source of validateSession + related types
ast-map symbol src/lib/auth.ts validateSession --related

# Find unused exports
ast-map dead src/

# Detect circular imports
ast-map cycles src/

# Check architecture + structural health
ast-map validate src/
ast-map validate src/ --max-lines 300 --max-imports 20

# Find all symbols named like "handler" across the project
ast-map search handler src/ --exported

# Don't know the name? Search by meaning
ast-map find "remove expired cache entries" src/

# Which source files have no tests at all?
ast-map tests . --untested

# What does this file import / what imports it?
ast-map deps src/lib/auth.ts --scan src/

# Top 10 most-imported symbols (God Node detector)
ast-map top src/

# Blast radius of changing sanitize()
ast-map impact src/utils.ts sanitize --scan src/

# Full call graph for a function
ast-map calls src/graph.ts buildSymbolGraph --scan src/

# Build symbol graph, write to file (large projects)
ast-map graph src/ -o graph.json

# Machine-readable output
ast-map dead src/ --json | jq '.deadExports[] | select(.kind == "function")'

MCP Tools Reference

`list_supported_languages`

Returns all supported languages and their file extensions.

`get_skeleton_json`

Parse a single source file → return normalized JSON skeleton (no HTML written).
Use when the AI needs file structure only.

{
  "schemaVersion": "1.1",
  "file": "src/lib/auth.ts",
  "language": "typescript",
  "directives": ["use server"],
  "imports": [
    { "symbol": "prisma", "from": "./prisma", "isDefault": true }
  ],
  "symbols": [
    { "name": "validateSession", "kind": "function", "exported": true,
      "range": { "startLine": 12, "endLine": 34 } }
  ]
}

Params: path, detail ("outline" | "full")

`generate_skeleton`

Map a file or directory → compact JSON + self-contained HTML views.

Params: path, detail, emitHtml (default true), combineHtml (single index.html with sidebar + search), outputDir

`get_symbol_context`

Extract exact source lines of a named symbol. Token-efficient: a 300-line file → ~40 lines.
Use includeRelated: true to also pull related types referenced in the signature.

Params: path, symbol, kind (optional), includeRelated

`resolve_imports`

Resolve every import in a file to its target symbol with kind, signature, and params.

{
  "resolved": [
    {
      "symbol": "validateSession", "from": "../../lib/auth",
      "resolvedRel": "src/lib/auth.ts", "kind": "function",
      "signature": "async function validateSession(token: string): Promise<Session>",
      "params": "(token: string)",
      "found": true, "importKind": "relative"
    }
  ]
}

Params: path

`build_symbol_graph`

Scan a directory → build a two-layer dependency graph.

Nodes: "file" (one per source file) and "symbol" (one per function/class/type/const)
Edges: "contains" (structural hierarchy) and "imports" (cross-file dependency)

{
  "stats": { "fileCount": 42, "symbolNodeCount": 380, "edgeCount": 712 },
  "edges": [
    { "from": "src/app/route.ts", "to": "src/lib/auth.ts::validateSession", "edgeType": "imports" }
  ]
}

Use outputFile to write the graph to disk for large projects.

Params: path, detail, outputFile

`find_dead_code`

Scan a directory → find exported symbols with zero incoming import edges.

Returns two confidence tiers:

"high" — functions, classes, consts (very likely unused)
"low" — interfaces, types, enums (may be used as type annotations only)

Note: framework entry-points (Next.js pages, route handlers) are technically "dead" inside the graph — review before deleting.

Params: path, detail

`find_circular_deps`

Detect circular import chains (A → B → C → A) using DFS.
Each cycle is canonicalised to avoid duplicates.

{
  "cycles": [
    { "cycle": ["src/a.ts", "src/b.ts", "src/c.ts", "src/a.ts"], "length": 3 }
  ]
}

Params: path

`find_duplicate_symbols`

Scan a directory → find symbol names exported from more than one file (accidental collisions / parallel implementations). Each result lists every file + kind that declares the name.

{
  "duplicates": [
    { "symbol": "validate", "count": 2, "locations": [
      { "file": "src/a.ts", "kind": "function" },
      { "file": "src/b.ts", "kind": "function" }
    ]}
  ]
}

Params: path

`get_complexity`

Compute AST-based cyclomatic complexity per function/method for a file or directory. Score = 1 + decision points (if / for / while / case / catch / ternary / && / ||), with a rating: low (≤5), moderate (≤10), high (≤20), very-high (>20). Directory scans also return the highest-complexity hotspots across all files.

{
  "file": "src/auth.ts",
  "maxComplexity": 12,
  "functions": [
    { "name": "validate", "complexity": 12, "rating": "high", "startLine": 8, "endLine": 40 }
  ]
}

Params: path

`find_unused_params`

Scan a file or directory for named functions/methods with parameters that are never used in the body. Skips _-prefixed params (conventionally intentional), anonymous callbacks, and destructured bindings — and correctly treats object-shorthand ({ id }) as a use — to keep false positives near zero.

{ "file": "src/x.ts", "functions": [ { "function": "greet", "line": 3, "unused": ["salutation"] } ] }

Params: path

`trace_type`

Scoped type-flow tracing. Find everywhere a named type flows through a directory — function parameters and return types, typed variables, and class fields. AST-based (no full type inference), so it tracks where a type is named in signatures; works best for TS/Python but resolves return/param types in any language that annotates them.

{
  "type": "Inventory",
  "byRole": { "param": 3, "return": 2, "variable": 1, "field": 1 },
  "refs": [ { "file": "src/svc.ts", "symbol": "make", "role": "return", "line": 4 } ]
}

Params: type, path

Monorepo note: once a workspace is detected, resolve_imports and build_symbol_graph resolve cross-package imports (@org/pkg) to real source files and draw cross-package edges.

`analyze_workspace`

Monorepo support. Discover the packages in a JS/TS monorepo (npm/yarn workspaces, pnpm-workspace.yaml, or lerna.json) and the dependency edges between them. Returns each package's name, directory, and workspace-internal dependencies, plus any circular dependencies between packages.

{
  "tool": "npm", "packageCount": 3,
  "packages": [ { "name": "@demo/a", "dir": "packages/a", "internalDeps": ["@demo/b"] } ],
  "edges": [ { "from": "@demo/a", "to": "@demo/b" } ],
  "packageCycles": []
}

Params: path (optional, defaults to root)

`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).

{ "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, circular dependencies, module coupling (per-directory instability), and layer violations (SDP). Rendered as a premium HTML dashboard by ast-map report.

{ "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.

{ "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.

{ "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).

{ "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).

{ "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).

{ "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.

{
  "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.

{
  "targetNodeId": "src/lib/auth.ts::validateSession",
  "direct": [{ "file": "src/app/login/page.tsx", "symbol": "validateSession" }],
  "transitive": [{ "file": "src/middleware.ts" }],
  "totalFiles": 5
}

Params: path, symbol, scanDir

`get_call_graph`

Parse a function body → extract every call expression, resolve callees via the import map, find reverse importers.

{
  "calls": [
    { "callee": "prisma.session.findUnique", "line": 15, "calleeFileRel": "src/lib/prisma.ts" },
    { "callee": "jwt.verify", "line": 20, "isExternal": true, "calleeFileRel": "jsonwebtoken" }
  ],
  "calledBy": [
    { "file": "src/app/api/auth/route.ts" }
  ]
}

Supports all 8 languages with per-language call extraction (TS/JS member_expression, Rust field_expression/scoped_identifier, Java method_invocation, C# invocation_expression, etc.) and constructor calls (new Foo).
Handles TS/JS destructured aliases (const { sign } = jwt), Java FQCN imports, C# using namespaces (via project-wide type index), Rust use crate::path::Item, Go pkg.Func (via go.mod module path), Kotlin FQCN/package imports, C/C++ #include, and Swift module imports (import <Module> → files under Sources/<Module>/). Reverse calledBy uses call-site scanning for C# and Go where import statements don't name the called symbol.

Params: path, function, scanDir

`search_symbol`

Find symbols by name across all source files in a directory.

Params: path, name, matchType ("contains" | "exact" | "regex"), kind, exportedOnly

`semantic_search`

Find symbols by meaning, not exact name — for when you know what the code does but not what it's called.

No embeddings, no network: identifier tokenization (camelCase / snake_case / acronyms), a built-in programming thesaurus (fetch≈get≈load, remove≈delete≈clear, unused≈dead, …), light stemming, fuzzy matching, and BM25-style IDF ranking over symbol names, doc comments, signatures and file paths. Results carry a normalized score and matchedTerms explaining why each symbol matched.

semantic_search("find unused exported code") →
  1.000  findDeadExports    (find, unused≈dead, export)
  0.557  DeadExport         (unused≈dead, export)

Params: path, query, limit (default 20), kind, exportedOnly

`get_test_coverage`

Structural test coverage: pair test files with the source files they exercise, and list source files no test touches — no instrumentation or test runner needed, works on a cold checkout.

Two signals: a test file importing a source file (definitive), and naming conventions (auth.test.ts → auth.ts, test_utils.py → utils.py, FooTest.java → Foo.java, test/<name>.* → <name>.*). Fixture/mock directories are excluded from both sides. Untested files are ranked by risk (fan-in, then symbol count); unmatched test files are reported as orphanTests (usually integration/e2e).

File-level coverage ("does anything test this file?"), not line coverage.

Params: path, untestedOnly

`get_file_deps`

For a single file, show what it imports and what imports it (with symbol names).
More focused than build_symbol_graph — use for quick dependency lookup.

Params: path, scanDir

`validate_architecture`

Scan for architecture violations across two rule sets.

Next.js App Router rules:

client-server-boundary — "use client" file importing a server-only module (error)
api-missing-try-catch — API route handler with no try/catch (warning)

General structural rules (any project):

large-file — file exceeds maxLines (default 500) (warning)
too-many-imports — file has more than maxImports imports (default 15) (warning)
god-export — file exports more than maxExports symbols (default 10) (warning)

Thresholds can be set per-call or in .ast-map.config.json.

Params: path, maxLines, maxImports, maxExports

`check_quality_gate`

Run the CI quality gate: absolute thresholds (from .ast-map.config.json → "check") plus a baseline ratchet against .ast-map.baseline.json — fails when cycles, dead exports, SDP violations, very-high-complexity functions rise, or the health score drops. Set updateBaseline to re-anchor at the current metrics. Same engine as ast-map check.

Params: path, baseline, updateBaseline

`get_top_symbols`

Return the N most-imported symbols — your codebase's "God Nodes" where a breaking change has maximum blast radius.

Params: path, limit (default 10)

`detect_code_smells`

Scan a file or directory for structural code smells: god classes (too many public methods/fields), long methods, long parameter lists, primitive obsession, and shallow wrappers. Returns per-file smell lists with file, line, symbol, severity, and message.

{ "path": "src/", "scanned": 42, "total": 7, "smells": [
  { "file": "src/auth.ts", "kind": "long-method", "symbol": "validate",
    "line": 8, "severity": "warning", "message": "Method exceeds 60 lines (82)" }
]}

Params: path, max_methods (default 10), max_fields (default 8), max_method_lines (default 60), max_params (default 4)

`scan_security`

Static security scan across 12 rules: eval, innerHTML, dangerouslySetInnerHTML, child_process, shell-exec, weak-crypto, hardcoded-secret, sql-injection, http-url, no-rate-limit, prototype-pollution. Returns issues with file, rule, severity, line, and snippet.

{ "path": "src/", "scanned": 42, "total": 2, "issues": [
  { "file": "src/db.ts", "rule": "sql-injection", "severity": "critical",
    "line": 14, "snippet": "db.query(`SELECT * FROM users WHERE id = ${id}`)" }
]}

Params: path, min_severity ("critical" | "high" | "medium" | "low")

`generate_diagram`

Generate a Mermaid diagram of the codebase.

type=class — classDiagram of classes, interfaces, enums and their relationships
type=deps — file dependency graph (graph TD)
type=modules — collapsed module-level graph (graph LR)

Returns a mermaid string you can paste into any Mermaid renderer or GitHub markdown.

Params: path, type ("class" | "deps" | "modules"), max_nodes (default 50)

`get_fix_suggestions`

Return actionable, prioritized fix suggestions derived from dead exports, code smells, and security issues. Each suggestion carries a kind, file, line, description, before/after snippet, and priority (1 = must fix, 2 = should fix, 3 = nice to have).

{ "path": "src/", "scanned": 42, "total": 5, "suggestions": [
  { "kind": "security", "priority": 1, "file": "src/db.ts", "line": 14,
    "description": "SQL injection via template literal",
    "before": "db.query(`SELECT * WHERE id=${id}`)",
    "after": "db.query('SELECT * WHERE id=?', [id])" }
]}

Params: path, min_priority (1–3, default 3 = all)

`generate_tests`

Generate test stubs for a source file using its AST skeleton. Supports vitest, jest, mocha, node:test, pytest, and gotest. Returns the generated test file content plus metadata: testCount, framework, testFilePath.

`generate_tests_ai`

Same as generate_tests but enhances stubs with real assertions via Claude — no more TODO placeholders. Falls back gracefully to stubs when the API key is absent. Requires ANTHROPIC_API_KEY or explicit api_key.

Params: path, framework, api_key, model

`ai_refactor`

Send the smells or security issues found in a file to Claude and receive concrete refactored code. Returns before/after code blocks plus an explanation for each issue. Requires ANTHROPIC_API_KEY or explicit api_key.

{ "path": "src/auth.ts", "total": 2, "results": [
  { "kind": "smell", "before": "function auth(u,p,t,r,o,c) {...}",
    "after": "function auth({ user, pass, token }: AuthParams) {...}",
    "explanation": "Replaced long parameter list with a typed options object." }
]}

Params: path, kind ("smell" | "security" | "both"), api_key, model, limit (default 3)

`explain_symbol`

Structural explanation of any named symbol: what it does, who calls it, what it depends on, detected smells, cyclomatic complexity rating, and estimated change risk. With ai: true, Claude writes a prose explanation using the structural data.

{ "symbol": "validateSession", "file": "src/auth.ts",
  "calledBy": [{ "file": "src/middleware.ts" }],
  "calls": [{ "callee": "prisma.session.findUnique" }],
  "smells": [], "complexity": "low", "changeRisk": "medium",
  "explanation": "Validates an incoming JWT, looks up the session …" }

Params: path, symbol, scanDir, ai (default false), api_key, model

`find_similar`

Find groups of functions, methods, or classes that share the same structural fingerprint (param count, async, return type, size, nesting) across a directory — duplication and consolidation candidates, no AI or text comparison needed.

{ "directory": "src/", "groupCount": 3, "groups": [
  { "fingerprint": "fn|2|async|void|small", "size": 3,
    "members": [
      { "file": "src/a.ts", "name": "fetchUser" },
      { "file": "src/b.ts", "name": "fetchPost" }
    ]}
]}

Params: path, kinds (default ["function","method","class"]), min_group_size (default 2)

`merge_coverage`

Enrich the structural test coverage map with actual line/branch percentages from a real coverage report. Supports Istanbul JSON, lcov, Clover XML, and Cobertura XML. Returns enriched per-file coverage, dead tests (tested but 0% actual coverage), and uncovered files.

Params: report (path to coverage file), path (project dir), format ("auto" | "istanbul" | "lcov" | "clover" | "cobertura")

`run_plugins`

Load and run all .mjs/.js plugins from <root>/.ast-map/plugins/ against the current skeletons. Each plugin exports an AstMapPlugin with an id and a run(ctx) function that returns violations. Returns per-plugin violation lists with file, line, symbol, severity, and message.

Params: path (optional, defaults to root)

`build_index`

Build or refresh the persistent skeleton index at .ast-map/index.json. Subsequent CLI commands and the check_arch_rules tool read from this index (SHA-1 hash verified) for 10–100× faster analysis on warm runs.

Params: dir (optional), force (ignore cached hashes and rebuild all)

`check_arch_rules`

Enforce forbidden/required import rules declared in .ast-map.json under arch.rules. Returns structured violations with file, rule name, and severity (error | warning). Uses the persistent index when available.

{ "ruleCount": 2, "violationCount": 1, "violations": [
  { "rule": "no-ui-in-domain", "severity": "error",
    "from": "src/domain/order.ts", "to": "src/ui/Button.tsx",
    "message": "Domain layer must not import UI layer" }
]}

Params: dir (optional)

`generate_docs`

Generate Markdown or HTML API documentation from the skeleton of a directory. Optionally enhance symbol descriptions with Claude (ai: true). When exportedOnly is true (default), only exported symbols are included.

Params: dir (optional), format ("markdown" | "html"), exportedOnly (default true), ai (default false), apiKey

Project Config — `.ast-map.config.json`

Place in your project root. All fields optional.

{
  "ignore": ["dist", "coverage", ".turbo"],
  "maxFileBytes": 500000,
  "outputDir": ".ast-map",
  "cache": true,
  "rules": {
    "large-file":       { "maxLines": 400 },
    "too-many-imports": { "maxImports": 20 },
    "god-export":       { "maxExports": 15 }
  },
  "check": {
    "maxCycles": 0,
    "maxSdpViolations": 10,
    "minScore": 70
  },
  "arch": {
    "rules": [
      {
        "name": "no-ui-in-domain",
        "from": "src/domain/**",
        "forbidImport": "src/ui/**",
        "severity": "error",
        "message": "Domain layer must not import UI layer"
      },
      {
        "name": "services-must-use-repo",
        "from": "src/services/**",
        "requireImport": "src/repositories/**",
        "severity": "warning"
      }
    ]
  }
}

cache — persistent parse cache in <root>/.ast-map/cache (default true; also disabled by AST_MAP_NO_CACHE=1). Inspect/clear with ast-map cache [stats|clear].
check — default thresholds for ast-map check / check_quality_gate; CLI flags override per run.
arch.rules — declarative import rules enforced by ast-map arch / check_arch_rules. Each rule has a from glob, a forbidImport or requireImport glob, optional name, severity ("error" | "warning"), and message. ast-map arch exits non-zero on errors (CI-friendly). Globs support ** (any depth), * (single segment), and ? (single char).

The config is read live — changes take effect on the next call without restarting the MCP server.

Performance — cache & parallel parsing

Since v1.20.0, bulk scans are fast twice over:

Persistent parse cache — every parsed file's skeleton is stored under <root>/.ast-map/cache, keyed by a SHA-1 of its content + detail + schema/grammar versions. A changed file hashes to a new key, so entries are never stale by construction, and the cache survives across processes — a re-run on an unchanged repo skips parsing entirely (warm hits on large files ≈ 60× faster).
Worker-thread parallel parsing — batches of ≥ 64 files are distributed over a pool sized from your CPU count (max 8); smaller batches stay sequential so there's no startup-cost penalty. Any worker failure falls back to sequential parsing.

Env var	Effect
`AST_MAP_NO_CACHE=1`	disable the disk cache for this run
`AST_MAP_WORKERS=0`	force sequential parsing
`AST_MAP_WORKERS=N`	force a pool of N workers (bypasses the batch-size gate)

ast-map cache shows entry count + size; ast-map cache clear wipes it. .ast-map/ is already in the default ignore list — add it to .gitignore if it isn't.

Power Prompts

Full Architecture Audit

Use build_symbol_graph on src/, then:
1. get_top_symbols — find the 5 God Nodes
2. find_circular_deps — any cycles?
3. validate_architecture — architecture violations + structural warnings
4. For the worst issue, show source with get_symbol_context

Safe Refactor Checklist

Before refactoring [functionName] in [file]:
1. get_change_impact — who depends on it?
2. get_call_graph — what does it call?
3. get_symbol_context with includeRelated=true — show me the full signature + types
4. Summarise what needs to change alongside the refactor

Dead Code Cleanup

Run find_dead_code on src/.
Show high-confidence results grouped by file.
For each candidate, use get_change_impact to confirm it's truly unreachable,
then show the source with get_symbol_context so I can verify before deleting.

Adding a Language

Pick a grammar from tree-sitter-wasms (~36 bundled grammars).
Write src/extractors/<lang>.ts — export extract() and extractImports().
Add one entry to src/registry.ts.

No changes to the core pipeline or any MCP tool.

Schema Reference

`SymbolNode`

interface SymbolNode {
  name: string
  kind: "class" | "interface" | "struct" | "function" | "method"
       | "type" | "enum" | "const" | "var" | "field"
  visibility: "public" | "private"
  exported?: boolean
  signature?: string          // full detail only
  doc?: string                // full detail only
  range: { startLine: number; endLine: number }
  children: SymbolNode[]
}

`ImportRef`

interface ImportRef {
  symbol: string              // imported name, or "*"
  from: string                // module specifier as written in source
  alias?: string              // import { Foo as Bar } → "Bar"
  isTypeOnly?: boolean
  isNamespaceImport?: boolean
  isDefault?: boolean
  isSideEffect?: boolean
}

`SkeletonFile` (schema v1.1)

interface SkeletonFile {
  schemaVersion: "1.1"
  file: string                // relative path, forward-slashed
  language: string
  generatedAt: string
  parser: { engine: "tree-sitter"; grammar: string }
  symbolCount: number
  directives?: string[]       // e.g. ["use client"]
  imports?: ImportRef[]
  symbols: SymbolNode[]
}

Project Layout

src/
├── index.ts            — MCP server + 44 tool registrations
├── cli.ts              — ast-map CLI (49 commands)
├── lsp.ts              — JSON-RPC 2.0 LSP server (diagnostics + code lens)
├── types.ts            — SkeletonFile, SymbolNode, ImportRef
├── config.ts           — SkeletonOptions, resolveOptions(), loadProjectConfig() + arch rules type
├── registry.ts         — language detection + extractor registry
├── parser.ts           — tree-sitter WASM loader + AST node helpers
├── skeleton.ts         — buildSkeleton(), collectSourceFiles() + parse cache
├── resolver.ts         — resolveImportPath(), resolveFileImports() (TS/JS/Python relative)
├── tsconfig.ts         — TS/JS path-alias resolution via tsconfig.json / jsconfig.json
├── crosslang.ts        — Java FQCN / C# namespace / Rust crate / Go module resolvers
├── roots.ts            — multi-root + unlocked-mode boundary resolution
├── graph.ts            — buildSymbolGraph() (language-aware second pass)
├── graph-analysis.ts   — findDeadExports(), findCircularDeps(), getChangeImpact(), getTopSymbols()
├── callgraph.ts        — buildCallGraph() — AST-level call extraction
├── analysis.ts         — findSymbol(), validate helpers, checkGeneralRules()
├── html.ts             — renderHtml(), renderCombinedHtml()
├── search.ts           — searchSymbols()
├── semantic.ts         — semanticSearch(), identifier tokenization, programming thesaurus
├── diskcache.ts        — persistent parse cache (SHA-1 keyed, .ast-map/cache)
├── pool.ts             — worker-thread parallel parsing pool
├── worker.ts           — per-worker parse + skeleton build
├── coupling.ts         — computeCoupling() (Ca / Ce / instability)
├── layers.ts           — findLayerViolations() (SDP)
├── modulecoupling.ts   — computeModuleCoupling() (directory-level)
├── gitdiff.ts          — getChangedFiles(), computeRisk()
├── contextpack.ts      — packContext() — minimal context for a symbol
├── sourcemap.ts        — readSourceMap() — inline + external source map parsing
├── workspace.ts        — analyzeWorkspace() — monorepo package discovery
├── typeflow.ts         — traceType() — type-flow tracing across a directory
├── complexity.ts       — computeFileComplexity() — cyclomatic complexity
├── unused-params.ts    — findUnusedParams() — unused function parameters
├── graph-analysis.ts   — findDuplicateSymbols(), getFileDeps()
├── testmap.ts          — mapTestCoverage() — structural test coverage
├── check.ts            — runQualityGate() — baseline ratchet + absolute thresholds
├── report.ts           — generateReport() — premium HTML health dashboard
├── dashboard.ts        — buildDashboard() — audit KPI summary
├── history.ts          — buildHistory() — historical health trend
├── explorer.ts         — renderExplorer() — force-directed file graph HTML
├── sfc.ts              — Vue / Svelte SFC <script> block extraction
├── smells.ts           — detectSmells() — 6 structural smell patterns
├── security.ts         — scanFileForSecurityIssues() — 12 static security rules
├── diagram.ts          — buildClassDiagram(), buildDepsDiagram(), buildModulesDiagram()
├── fix.ts              — buildFixSuggestions() — prioritised fix list
├── testgen.ts          — generateTestFile() — test stubs (6 frameworks)
├── ai-testgen.ts       — tryAiEnhanceTests() — Claude-enhanced test assertions
├── ai-refactor.ts      — callClaude(), aiRefactorBatch() — AI refactoring
├── explain.ts          — buildExplainResult(), aiExplain() — symbol explanation
├── similar.ts          — findSimilar() — structural fingerprint groups
├── incremental.ts      — content-hash state, filterToGitChanged(), detectChanges()
├── covmerge.ts         — mergeCoverage() — 4-format coverage parser + structural merge
├── plugins.ts          — loadPlugins(), runPlugins() — custom lint plugin runner
├── serve.ts            — startServe() — HTTP server + REST endpoints + SSE /events
├── webapp.ts           — self-contained SPA template (D3.js, dark theme, 8 pages)
├── indexstore.ts       — buildIndex(), loadIndex(), isIndexFresh(), getSkeletons()
├── arch-rules.ts       — checkArchRules(), loadArchRules(), globToRegex()
├── patch.ts            — generatePatch(), interactivePatch(), colored unified diff
├── docgen.ts           — buildDocOutput(), renderMarkdown(), renderDocHtml(), aiEnhanceDocs()
├── embeddings.ts       — buildTfIdfVectors(), cosineSearch(), rerankWithClaude()
├── prompts.ts          — 5 MCP prompt definitions
└── extractors/
    ├── common.ts       — makeSymbol(), toOutline()
    ├── typescript.ts   — TS/JS/TSX: symbols + imports + re-exports + decorators
    ├── python.ts       — Python: symbols + relative import resolution + decorators
    ├── go.ts           — Go: symbols + imports
    ├── rust.ts         — Rust: struct/trait/enum/impl + `use` imports
    ├── java.ts         — Java: class/interface/enum/method/field + FQCN
    ├── csharp.ts       — C#: namespace recursion + class/struct/interface + `using`
    ├── kotlin.ts       — Kotlin: FQCN / package index
    ├── swift.ts        — Swift: module = directory under Sources/
    ├── c.ts            — C: functions + `#include` with header↔impl pairing
    ├── cpp.ts          — C++: classes + `#include`
    ├── php.ts          — PHP: classes/interfaces/traits/enums + `use` + require/include
    └── ruby.ts         — Ruby: classes/modules/methods + require/require_relative

MCP resources

Beyond tools, the server exposes the codebase as browseable MCP resources, so an agent (or MCP client UI) can list and read structure directly:

URI	What
`ast://languages`	supported languages + extensions
`ast://skeleton/{path}`	the skeleton for one source file (templated; `resources/list` enumerates every file)
`ast://graph`	the whole-root symbol dependency graph (guarded by file count)

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):

# .github/workflows/architecture.yml
name: Architecture
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20" }
      - uses: 6ixthxense/AST-MCP@v1
        with:
          path: src
          max-lines: "400"
          max-imports: "20"
          max-exports: "15"

The action runs ast-map validate and fails the job on threshold violations.

Since v1.21.0 the action can also run the quality gate (baseline ratchet + thresholds). Commit a baseline once (ast-map check src --update-baseline), then:

      - uses: 6ixthxense/AST-MCP@v1
        with:
          path: src
          mode: check                 # validate | check | both
          check-args: "--min-score 70 --max-cycles 0"

The job fails whenever cycles, dead exports, SDP violations, or complexity regress past the committed .ast-map.baseline.json. You can also call any CLI command directly with npx -p universal-ast-mapper ast-map <command>.

Stability (1.0)

As of v1.0.0, the public surface is stable across the 1.x line:

MCP tool names and input schemas — no breaking changes; new tools and new optional inputs may be added.
CLI commands and flags — stable; new commands/flags may be added.
Skeleton JSON — schemaVersion follows additive-compatible evolution; new optional fields (e.g. props, decorators) may appear without a major bump.

Not part of the public API: the internal src/ module layout and the generated HTML markup.

Changelog

Version	What changed
2.0.0	6 major features — Persistent skeleton index (`ast-map index`, `build_index`): `.ast-map/index.json` hash-based incremental rebuild, 10–100× warm speed; SSE live reload (`ast-map serve --watch`, `/events` endpoint): EventSource client auto-refreshes the web SPA on file changes; TF-IDF re-ranking (`ast-map find --rerank`): cosine similarity pre-rank + optional Claude API re-ranking; Auto-patch (`ast-map patch`, `generatePatch`): colored unified diff with Claude-generated before/after, readline y/N prompt per issue; Architecture rules (`ast-map arch`, `check_arch_rules`): forbidden/required import rules in `.ast-map.json` `arch.rules`, glob patterns, CI exit code; Doc generation (`ast-map doc`, `generate_docs`): Markdown + HTML API reference, `--ai` flag for Claude descriptions. 44 MCP tools / 49 CLI commands.
1.35.0	Web SPA + symbol explanation + similar + coverage merge + plugins — new `ast-map serve [dir]` launches a dark-theme web app at `:7337` (D3 dependency graph, all analysis pages, 10 REST endpoints); new `ast-map explain <file> <symbol>` structural explanation with optional `--ai` prose (callers, deps, smells, complexity, risk); new `ast-map similar [dir]` AST fingerprint groups (7-component, no AI); new `ast-map covmerge <report>` merges Istanbul/lcov/Clover/Cobertura with the structural map; new `ast-map plugins [dir]` runs custom `.mjs` lint plugins from `.ast-map/plugins/`. New MCP tools: `explain_symbol`, `find_similar`, `merge_coverage`, `run_plugins`. 41 MCP tools / 45 CLI commands.
1.34.0	Code intelligence suite + AI refactor + LSP + init — 7 new MCP tools: `detect_code_smells` (6 patterns), `scan_security` (12 rules), `generate_diagram` (Mermaid class/deps/modules), `get_fix_suggestions` (P1–P3 prioritized), `generate_tests` (6 frameworks), `generate_tests_ai` (Claude-enhanced assertions), `ai_refactor` (before/after patches from Claude). Full JSON-RPC 2.0 LSP server (`ast-map-lsp`): dead-export warnings, security-issue errors, complexity code lenses. `ast-map init` scaffolds `.ast-map.json` + plugin example. 37 MCP tools / 41 CLI commands.
1.33.0	AI test generation + VS Code extension — `ast-map testgen --ai` sends source + stubs to Claude and returns tests with real assertions (graceful fallback to stubs). New VS Code extension: complexity code lens, dead-export diagnostics, security diagnostics, Issues Tree View, commands (Generate Tests, Scan Security, Show Diagram, Open Report), status-bar health score.
1.28.0	Test coverage in the dashboard — `ast-map report` / `get_codebase_report` gain a Test coverage card (coverage bar + untested sources ranked by risk with Ca/symbols) and stat tile; structural coverage now factors into the health score (capped penalty). Reporting on `src/` only? Test files are pulled in from the project root automatically.
1.27.0	Test-coverage mapping — new MCP tool `get_test_coverage` + CLI `ast-map tests` (alias `coverage`): pairs test files with the sources they exercise (import edges + naming conventions) and lists untested sources ranked by risk (fan-in, then symbols). Fixture dirs excluded; orphan tests reported. File-level, zero instrumentation. (30 tools / 32 commands)
1.26.0	Coupling overlay in the explorer — `ast-map explore` gains a `color: coupling` mode: nodes shaded by instability I = Ce/(Ca+Ce) on a green (stable) → red (volatile) scale, with a legend, and Ca / Ce / I readouts in the hover tooltip and detail sidebar. Spot load-bearing files and volatile hotspots at a glance.
1.25.0	Semantic symbol search — new MCP tool `semantic_search` + CLI `ast-map find <query>`: find symbols by meaning ("remove expired sessions" → `clearDiskCache`). Identifier tokenization + 60-group programming thesaurus + stemming + fuzzy matching + BM25-style IDF ranking over names, docs, signatures and paths. No embeddings, no network. (29 tools / 31 commands)
1.24.0	TS path-alias resolution — bare imports like `@/components/Button` now resolve via the nearest `tsconfig.json`/`jsconfig.json` (`compilerOptions.paths` + `baseUrl`, relative `extends` chains, longest-prefix matching, string-aware JSONC parser). Wired into `resolve_imports`, the symbol graph, and the call graph — on a real Next.js app this took the import graph from 31 to 324 edges and cut false dead-exports by ~30%.
1.23.0	Configurable root boundary — `AST_MAP_ROOT` accepts multiple roots (path-delimiter separated) and `AST_MAP_UNLOCKED=1` allows analyzing any absolute path on request (default stays locked). Analysis/graph/report rel-paths now computed against the matched root, so cross-root results are correct. New `roots` module + 13-check test suite.
1.22.0	PHP & Ruby support — `.php` (classes, interfaces, traits, enums, methods with visibility, `use` imports incl. grouped, require/include) and `.rb`/`.rake` (classes, modules, methods, `self.` singleton methods, `private` section tracking, require/require_relative). Unblocked by upgrading `web-tree-sitter` 0.20.8 → 0.21.0 (all existing grammars re-verified). 16 languages.
1.21.0	Quality gate — `ast-map check` fails CI when quality regresses: baseline ratchet vs `.ast-map.baseline.json` (cycles · dead exports · SDP · very-high complexity · score; `--update-baseline` re-anchors) + absolute thresholds (flags or config `"check"`). New MCP tool `check_quality_gate` (28 tools); GitHub Action gains `mode: check`.
1.20.0	Incremental cache + parallel parsing — persistent content-hash parse cache in `.ast-map/cache` (on by default, never stale, warm hits ~60× faster on large files; `ast-map cache stats
1.19.0	Dashboard: coupling + SDP — `ast-map report` / `get_codebase_report` now include module coupling (per-directory instability bars) and layer violations (stable→volatile, SDP) cards, plus an SDP stat; SDP inversions also factor into the health score. The v1.14–1.16 metrics are now visual.
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`).
1.8.2	Explorer stability fix — clamp the force layout (distance floor + velocity cap) so nodes that initialize close together can't be flung to huge coordinates, which was blowing up the bounding box and shrinking the whole graph into a corner. Now reliably centers and fills.
1.8.1	Explorer self-heal sizing — the explorer now re-checks canvas size every frame and re-fits, so it always centers/fills even if the canvas reports zero size at load (and survives container resizes).
1.8.0	Explorer detail sidebar — click a file in `ast-map explore` to open a side panel: language, symbol count, its symbols, the files it imports, and the files that import it — each clickable to jump to that file.
1.7.3	Explorer layout overhaul — only connected files are force-laid (centered + filling the viewport); orphan files with no in-scope deps are parked in a tidy grid below instead of sprawling. Verified centered at any window size.
1.7.2	Explorer fit, really this time — continuous auto-fit until you interact, robust canvas sizing, and centered node init, so the graph fills the viewport instead of bunching in a corner.
1.7.1	Explorer fit fix — the `ast-map explore` graph now auto-fits the viewport (spreads to fill the screen instead of clustering in the centre); double-click re-fits.
1.7.0	Web UI graph explorer — `ast-map explore [dir]` writes a self-contained, dependency-free interactive HTML: a force-directed file dependency graph (drag, zoom, click-to-highlight neighbours, filter by name). No build step, no external scripts — just open it in a browser.
1.6.0	MCP resource endpoints — the server now exposes browseable resources: `ast://languages`, `ast://skeleton/{path}` (templated, one per source file via `resources/list`), and `ast://graph`. Agents can list and read codebase structure as resources, not just call tools.
1.5.0	`.d.ts` / ambient declarations — `declare function/const/class`, `declare module "x"`, and `declare namespace` (and plain `namespace`) are now extracted (previously a `.d.ts` yielded 0 symbols). Adds a `namespace` symbol kind; declared APIs surface as exported, nested under their module/namespace.
1.4.0	Dynamic import tracking — dynamic `import("...")` and CommonJS `require("...")` calls (anywhere in a file) are now captured as imports with an `isDynamic` flag. Relative dynamic imports resolve and draw graph edges like static ones, so lazy-loaded routes/modules show up in the dependency graph.
1.3.0	TS/JS decorators — class and method symbols now carry a `decorators` field (`@Component({...})`, `@Injectable()`, `@Get("/x")`), in skeletons and `get_call_graph`. Extends the Python decorator support (v0.8.7) to TypeScript/JavaScript — traces Angular/NestJS-style framework wiring to its class/handler.
1.2.0	File-level cross-package resolution — in a monorepo, bare imports of a workspace package (`@org/utils`, `@org/utils/sub`) now resolve to the actual source file (preferring `src/` over built `dist/`), so `resolve_imports` marks them in-project and `build_symbol_graph` draws cross-package edges. Builds on the v1.1.0 workspace discovery.
1.1.0	Monorepo support — new `analyze_workspace` MCP tool + `ast-map workspace` (alias `ws`) CLI: discovers packages from npm/yarn `workspaces`, `pnpm-workspace.yaml`, or `lerna.json`, maps internal package dependencies, and flags circular package deps. 19 MCP tools.
1.0.0	Stable release. Locks the public API (MCP tool names + schemas, CLI surface) for the 1.x line. Adds a GitHub Action (`action.yml`) to run `ast-map validate` as a CI architecture gate, plus a project CI workflow. Caps a 12-language engine with 18 MCP tools / 17 CLI commands spanning skeletons, dependency graphs, and deep analysis (dead code · cycles · impact · complexity · duplicates · unused params · decorators · type flow).
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`) CLI: per-function cyclomatic complexity with low/moderate/high/very-high ratings, file or directory scope.
0.8.4	Duplicate symbol detection — `find_duplicate_symbols` / `ast-map duplicates` (alias `dupes`): symbol names exported from more than one file.
0.8.1–0.8.3	Kotlin + C/C++ cross-file wiring · Swift module resolution (`Sources/<Module>/`) · TSX/React component props (`propsType` + `props[]`, `React.FC<P>` detection).
0.1.0–0.8.0	Foundation: skeleton extraction (`get_skeleton_json`, `generate_skeleton`, `get_symbol_context`, `validate_architecture`) · import resolution + symbol graph · dead code / cycles / impact / call graph · CLI · 12 languages (+Rust · Java · C# · Go · C · C++ · Kotlin · Swift) · `/ast-map` skill auto-install · barrel re-exports · parse cache.

Keywords

mcp ast tree-sitter code-map skeleton