universal-ast-mapper 0.5.2

package/README.md

@@ -0,0 +1,465 @@
+# 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](https://tree-sitter.github.io/) WASM grammars. Zero regex guessing — real AST parsing.
+
+**Supported languages:** TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go
+
+---
+
+## Quick Start
+
+```bash
+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`
+
+```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.
+
+---
+
+## 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 search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
+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>]
+```
+
+### Examples
+
+```bash
+# 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
+
+# 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.
+
+```json
+{
+  "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.
+
+```json
+{
+  "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)
+
+```json
+{
+  "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.
+
+```json
+{
+  "cycles": [
+    { "cycle": ["src/a.ts", "src/b.ts", "src/c.ts", "src/a.ts"], "length": 3 }
+  ]
+}
+```
+
+**Params:** `path`
+
+---
+
+### `get_change_impact`
+Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
+
+```json
+{
+  "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.
+
+```json
+{
+  "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 TypeScript, JavaScript, Python, Go.  
+Handles destructured aliases: `const { sign } = jwt` → `sign` correctly resolves to `jsonwebtoken`.
+
+**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`
+
+---
+
+### `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`
+
+---
+
+### `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)
+
+---
+
+## Project Config — `.ast-map.config.json`
+
+Place in your project root. All fields optional.
+
+```json
+{
+  "ignore": ["dist", "coverage", ".turbo"],
+  "maxFileBytes": 500000,
+  "outputDir": ".ast-map",
+  "rules": {
+    "large-file":       { "maxLines": 400 },
+    "too-many-imports": { "maxImports": 20 },
+    "god-export":       { "maxExports": 15 }
+  }
+}
+```
+
+The config is read live — changes take effect on the next call without restarting the MCP server.
+
+---
+
+## 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
+
+1. Pick a grammar from `tree-sitter-wasms` (~36 bundled grammars).
+2. Write `src/extractors/<lang>.ts` — export `extract()` and `extractImports()`.
+3. Add one entry to `src/registry.ts`.
+
+No changes to the core pipeline or any MCP tool.
+
+---
+
+## Schema Reference
+
+### `SymbolNode`
+```typescript
+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`
+```typescript
+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)
+```typescript
+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 + all 14 tool registrations
+├── cli.ts              — ast-map CLI (13 commands)
+├── types.ts            — SkeletonFile, SymbolNode, ImportRef
+├── config.ts           — SkeletonOptions, resolveOptions(), loadProjectConfig()
+├── 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()
+├── graph.ts            — buildSymbolGraph()
+├── graph-analysis.ts   — findDeadExports(), findCircularDeps(), getChangeImpact(),
+│                         getFileDeps(), getTopSymbols()
+├── callgraph.ts        — buildCallGraph() — AST-level call extraction
+├── analysis.ts         — findSymbol(), validate helpers, checkGeneralRules()
+├── html.ts             — renderHtml(), renderCombinedHtml()
+├── search.ts           — searchSymbols()
+└── extractors/
+    ├── common.ts       — makeSymbol(), toOutline()
+    ├── typescript.ts   — TS/JS/TSX: symbols + imports + re-exports
+    ├── python.ts       — Python: symbols + relative import resolution
+    └── go.ts           — Go: symbols + imports
+```
+
+---
+
+## Changelog
+
+| Version | What changed |
+|---------|--------------|
+| **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` |

package/dist/analysis.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+// ─── Symbol lookup ────────────────────────────────────────────────────────────
+/** Recursively search for a symbol by name and optional kind. */
+export function findSymbol(symbols, name, kind) {
+    for (const sym of symbols) {
+        if (sym.name === name && (!kind || sym.kind === kind))
+            return sym;
+        const found = findSymbol(sym.children, name, kind);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * Given a target symbol with a signature, find related type/interface/enum
+ * symbols referenced in that signature and return their source code blocks.
+ */
+export function findRelatedSymbols(symbols, target, sourceLines) {
+    if (!target.signature)
+        return [];
+    const seen = new Set([target.name]);
+    // PascalCase identifiers in the signature are likely type references
+    const typeRefs = [...target.signature.matchAll(/\b([A-Z][a-zA-Z0-9_]*)\b/g)]
+        .map((m) => m[1])
+        .filter((v) => !seen.has(v) && (seen.add(v), true));
+    const related = [];
+    for (const typeName of typeRefs) {
+        const sym = findSymbol(symbols, typeName);
+        if (sym && (sym.kind === "interface" || sym.kind === "type" || sym.kind === "enum")) {
+            const code = sourceLines.slice(sym.range.startLine - 1, sym.range.endLine).join("\n");
+            related.push({ name: sym.name, kind: sym.kind, range: sym.range, code });
+        }
+    }
+    return related;
+}
+// ─── Architecture validation ──────────────────────────────────────────────────
+/** True if the first 500 chars of source contain the given directive literal. */
+export function hasDirective(source, directive) {
+    const head = source.slice(0, 500);
+    return head.includes(`"${directive}"`) || head.includes(`'${directive}'`);
+}
+/** Patterns that flag server-only imports in a "use client" file. */
+const SERVER_IMPORT_PATTERNS = [
+    { pattern: /from\s+['"]server-only['"]/, label: "server-only" },
+    { pattern: /from\s+['"][^'"]*\/prisma['"]/, label: "prisma client" },
+    { pattern: /from\s+['"][^'"]*lib\/prisma['"]/, label: "lib/prisma" },
+    { pattern: /from\s+['"]next\/headers['"]/, label: "next/headers" },
+    { pattern: /from\s+['"]next\/cookies['"]/, label: "next/cookies" },
+    { pattern: /from\s+['"][^'"]*lib\/auth['"]/, label: "lib/auth" },
+    { pattern: /from\s+['"][^'"]*lib\/auditLog['"]/, label: "lib/auditLog" },
+    { pattern: /from\s+['"][^'"]*lib\/apiAuth['"]/, label: "lib/apiAuth" },
+];
+/** Scan source lines for server-only imports (called on "use client" files). */
+export function findServerImports(source) {
+    const lines = source.split("\n");
+    const violations = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const { pattern, label } of SERVER_IMPORT_PATTERNS) {
+            if (pattern.test(line)) {
+                const match = line.match(/from\s+['"]([^'"]+)['"]/);
+                violations.push({ module: match ? match[1] : line.trim(), label, line: i + 1 });
+                break;
+            }
+        }
+    }
+    return violations;
+}
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
+/** True if the relative path looks like a Next.js App Router API route file. */
+export function isApiRoute(relPath) {
+    const norm = relPath.split(path.sep).join("/");
+    return /app\/api\/.+\/route\.(ts|js|tsx|jsx)$/.test(norm);
+}
+/**
+ * Find exported HTTP handler functions that have no try/catch.
+ * A simple but effective heuristic: look for the `try {` keyword in the body.
+ */
+export function findMissingTryCatch(symbols, sourceLines) {
+    const missing = [];
+    for (const sym of symbols) {
+        if (!HTTP_METHODS.has(sym.name) || sym.exported === false)
+            continue;
+        const bodyText = sourceLines.slice(sym.range.startLine - 1, sym.range.endLine).join("\n");
+        if (!/\btry\s*\{/.test(bodyText))
+            missing.push(sym);
+    }
+    return missing;
+}
+export const GENERAL_RULE_DEFAULTS = {
+    largeFileLines: 500,
+    tooManyImports: 15,
+    godExportCount: 10,
+};
+/**
+ * Run general-purpose structural rules against a source file.
+ * Returns violations for any threshold exceeded.
+ */
+export function checkGeneralRules(fileRel, source, symbols, importCount, thresholds = GENERAL_RULE_DEFAULTS) {
+    const violations = [];
+    const lineCount = source.split("\n").length;
+    if (lineCount > thresholds.largeFileLines) {
+        violations.push({
+            file: fileRel,
+            rule: "large-file",
+            severity: "warning",
+            message: `File has ${lineCount} lines (threshold: ${thresholds.largeFileLines}) — consider splitting`,
+            value: lineCount,
+            threshold: thresholds.largeFileLines,
+        });
+    }
+    if (importCount > thresholds.tooManyImports) {
+        violations.push({
+            file: fileRel,
+            rule: "too-many-imports",
+            severity: "warning",
+            message: `File has ${importCount} imports (threshold: ${thresholds.tooManyImports}) — high coupling`,
+            value: importCount,
+            threshold: thresholds.tooManyImports,
+        });
+    }
+    const exportedCount = symbols.filter((s) => s.exported).length;
+    if (exportedCount > thresholds.godExportCount) {
+        violations.push({
+            file: fileRel,
+            rule: "god-export",
+            severity: "warning",
+            message: `File exports ${exportedCount} symbols (threshold: ${thresholds.godExportCount}) — potential God File`,
+            value: exportedCount,
+            threshold: thresholds.godExportCount,
+        });
+    }
+    return violations;
+}