universal-ast-mapper 0.5.2 → 0.7.0

package/dist/resolver.js

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { buildSkeleton } from "./skeleton.js";
+import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
 import { resolveOptions } from "./config.js";
 import { findSymbol } from "./analysis.js";
+import { buildCrossLangIndex, resolveCrossLangTarget, } from "./crosslang.js";
 const SRC_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
-/** Extract the outermost balanced parenthesised group from a signature string. */
 function extractParams(sig) {
     const start = sig.indexOf("(");
     if (start === -1)
@@ -21,8 +21,6 @@ function extractParams(sig) {
     }
     return null;
 }
-// TypeScript ESM: `import from "./foo.js"` actually means `./foo.ts` on disk.
-// Map each JS-family extension to the TS-family equivalents we should try first.
 const JS_TO_TS = {
     ".js": [".ts", ".tsx", ".js"],
     ".jsx": [".tsx", ".jsx"],
@@ -30,8 +28,7 @@ const JS_TO_TS = {
     ".cjs": [".cts", ".cjs"],
 };
 /**
- * Resolve a relative import path from a source file to an absolute path on disk.
- * Handles TypeScript ESM convention (`.js` in source → `.ts` on disk).
+ * Resolve a TS/JS-style relative import path to an absolute file path.
  * Returns null for external packages or when the file cannot be found.
  */
 export function resolveImportPath(importFrom, fromAbs) {
@@ -40,7 +37,6 @@ export function resolveImportPath(importFrom, fromAbs) {
     const fromDir = path.dirname(fromAbs);
     const candidate = path.resolve(fromDir, importFrom);
     const declaredExt = path.extname(candidate).toLowerCase();
-    // If the import has a JS-family extension, try the TS equivalents first
     if (declaredExt && JS_TO_TS[declaredExt]) {
         const base = candidate.slice(0, candidate.length - declaredExt.length);
         for (const ext of JS_TO_TS[declaredExt]) {
@@ -49,22 +45,17 @@ export function resolveImportPath(importFrom, fromAbs) {
                 return p;
         }
     }
-    // Exact match (already has extension or points to a file)
     try {
         const stat = fs.statSync(candidate);
         if (stat.isFile())
             return candidate;
     }
-    catch {
-        // not found — try with extensions
-    }
-    // Try appending source extensions
+    catch { /* not found */ }
     for (const ext of SRC_EXTS) {
         const p = candidate + ext;
         if (fs.existsSync(p))
             return p;
     }
-    // Try index file inside the directory
     for (const ext of SRC_EXTS) {
         const p = path.join(candidate, `index${ext}`);
         if (fs.existsSync(p))
@@ -72,60 +63,126 @@ export function resolveImportPath(importFrom, fromAbs) {
     }
     return null;
 }
-/**
- * For each import in `skel`, resolve the target file and look up the symbol.
- * Returns enriched Reference Objects with resolved path, signature, and params.
- */
+/* ─── Cross-language index cache ──────────────────────────────────────────── */
+// Java/C# need a project-wide index to resolve fully-qualified imports.
+// Built lazily on first cross-language resolve, then reused for the process
+// lifetime (the MCP server is per-root, so this is safe).
+const indexCache = new Map();
+export async function getOrBuildCrossLangIndex(root) {
+    const key = path.resolve(root);
+    let p = indexCache.get(key);
+    if (p)
+        return p;
+    p = (async () => {
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(key, opts);
+        const skels = [];
+        for (const abs of files) {
+            const ext = path.extname(abs).toLowerCase();
+            // Only Java/C# contribute to the index (Rust resolves via direct
+            // module-path walk against the filesystem, no index needed).
+            if (ext !== ".java" && ext !== ".cs")
+                continue;
+            const rel = path.relative(key, abs).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(abs, rel, opts));
+            }
+            catch { /* skip unparsable files */ }
+        }
+        return buildCrossLangIndex(skels);
+    })();
+    indexCache.set(key, p);
+    return p;
+}
+/** Test/debug hook: drop the cached index (rebuilds on next call). */
+export function clearCrossLangIndexCache() {
+    indexCache.clear();
+}
+async function lookupSymbolInTarget(targetAbs, targetRel, symbol) {
+    const opts = resolveOptions({ detail: "full", emitHtml: false });
+    try {
+        const targetSkel = await buildSkeleton(targetAbs, targetRel, opts);
+        const sym = findSymbol(targetSkel.symbols, symbol);
+        if (sym) {
+            const signature = sym.signature ?? null;
+            const out = { found: true, kind: sym.kind };
+            if (signature !== undefined)
+                out.signature = signature;
+            if (signature) {
+                const params = extractParams(signature);
+                if (params)
+                    out.params = params;
+            }
+            return out;
+        }
+    }
+    catch { /* unresolvable / parse error */ }
+    return { found: false };
+}
+async function enrichRelativeImport(imp, fromAbs, root) {
+    const isExternal = !imp.from.startsWith(".");
+    const resolvedAbs = isExternal ? null : resolveImportPath(imp.from, fromAbs);
+    const resolvedRel = resolvedAbs
+        ? path.relative(root, resolvedAbs).split(path.sep).join("/")
+        : null;
+    let enrichment = { found: false };
+    if (resolvedAbs && !imp.isSideEffect && !imp.isNamespaceImport && imp.symbol !== "*") {
+        enrichment = await lookupSymbolInTarget(resolvedAbs, resolvedRel, imp.symbol);
+    }
+    else if (resolvedAbs) {
+        enrichment = { found: true };
+    }
+    return assembleResolved(imp, resolvedAbs, resolvedRel, isExternal, enrichment);
+}
+async function enrichCrossLangImport(imp, skel, fromAbs, root, index) {
+    const target = resolveCrossLangTarget(imp, skel, fromAbs, root, index);
+    if (!target) {
+        return assembleResolved(imp, null, null, true, { found: false });
+    }
+    if (target.kind === "file") {
+        // Namespace-style (Java wildcard / C# using). Point to the first file —
+        // useful for navigation; the symbol itself isn't a specific declaration.
+        const firstRel = target.files[0];
+        const firstAbs = path.resolve(root, firstRel);
+        return assembleResolved(imp, firstAbs, firstRel, false, { found: true });
+    }
+    // Symbol-level (Java FQCN, Rust crate::path::Item)
+    const targetAbs = path.resolve(root, target.file);
+    const enrichment = await lookupSymbolInTarget(targetAbs, target.file, target.symbol);
+    return assembleResolved(imp, targetAbs, target.file, false, enrichment);
+}
+function assembleResolved(imp, resolvedAbs, resolvedRel, isExternal, enrichment) {
+    const out = {
+        ...imp,
+        resolvedPath: resolvedAbs,
+        resolvedRel,
+        found: enrichment.found,
+        importKind: isExternal ? "external" : "relative",
+    };
+    if (enrichment.kind !== undefined)
+        out.kind = enrichment.kind;
+    if (enrichment.signature !== undefined)
+        out.signature = enrichment.signature;
+    if (enrichment.params !== undefined)
+        out.params = enrichment.params;
+    return out;
+}
+/* ─── Public entry point ──────────────────────────────────────────────────── */
+const CROSS_LANG = new Set(["java", "csharp", "rust", "go"]);
 export async function resolveFileImports(skel, absPath, root) {
     if (!skel.imports || skel.imports.length === 0)
         return [];
-    const opts = resolveOptions({ detail: "full", emitHtml: false });
     const results = [];
+    // Lazy-build the cross-lang index only when actually needed.
+    let indexPromise = null;
+    const getIndex = () => (indexPromise ??= getOrBuildCrossLangIndex(root));
     for (const imp of skel.imports) {
-        const isExternal = !imp.from.startsWith(".");
-        const resolvedAbs = isExternal ? null : resolveImportPath(imp.from, absPath);
-        const resolvedRel = resolvedAbs
-            ? path.relative(root, resolvedAbs).split(path.sep).join("/")
-            : null;
-        let found = false;
-        let kind;
-        let signature;
-        let params;
-        if (resolvedAbs && !imp.isSideEffect && !imp.isNamespaceImport && imp.symbol !== "*") {
-            try {
-                const targetSkel = await buildSkeleton(resolvedAbs, resolvedRel, opts);
-                const targetSym = findSymbol(targetSkel.symbols, imp.symbol);
-                if (targetSym) {
-                    found = true;
-                    kind = targetSym.kind;
-                    signature = targetSym.signature ?? null;
-                    if (signature) {
-                        params = extractParams(signature);
-                    }
-                }
-            }
-            catch {
-                // target file unresolvable or parse error — leave found=false
-            }
+        if (CROSS_LANG.has(skel.language)) {
+            results.push(await enrichCrossLangImport(imp, skel, absPath, root, await getIndex()));
         }
-        else if (resolvedAbs) {
-            // Namespace import or side-effect: file exists = success
-            found = true;
+        else {
+            results.push(await enrichRelativeImport(imp, absPath, root));
         }
-        const resolved = {
-            ...imp,
-            resolvedPath: resolvedAbs,
-            resolvedRel,
-            found,
-            importKind: isExternal ? "external" : "relative",
-        };
-        if (kind !== undefined)
-            resolved.kind = kind;
-        if (signature !== undefined)
-            resolved.signature = signature;
-        if (params !== undefined)
-            resolved.params = params;
-        results.push(resolved);
     }
     return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "scripts",
     "README.md",
     "BLUEPRINT.md"
   ],
@@ -17,7 +18,8 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "smoke": "node test/smoke.mjs",
-    "test": "node test/smoke.mjs && node test/analysis.mjs"
+    "test": "node test/smoke.mjs && node test/analysis.mjs",
+    "postinstall": "node scripts/install-skill.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/install-skill.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Postinstall: copies the /ast-map Claude Code skill to ~/.claude/skills/ast-map/
+ * so it appears in the / command palette automatically after install.
+ * Skips silently if Claude Code is not installed or if running in CI.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// ─── Skip in CI / non-interactive environments ────────────────────────────────
+if (
+  process.env.CI ||
+  process.env.CONTINUOUS_INTEGRATION ||
+  process.env.npm_config_ci ||
+  process.env.GITHUB_ACTIONS ||
+  process.env.GITLAB_CI
+) {
+  process.exit(0);
+}
+
+// ─── Skill content ────────────────────────────────────────────────────────────
+
+const SKILL_MD = `---
+name: ast-map
+description: "AST-based code analysis using universal-ast-mapper. Use to understand codebase structure, find dead code, detect circular deps, check blast radius, validate architecture. Works on TypeScript, JavaScript, Python, Go."
+trigger: /ast-map
+---
+
+# /ast-map
+
+Run AST-based code analysis on the current project using universal-ast-mapper (tree-sitter).
+
+## Usage
+
+\`\`\`
+/ast-map                          # architecture overview: dead code + cycles + top symbols
+/ast-map dead [dir]               # find unused exports
+/ast-map cycles [dir]             # detect circular import chains
+/ast-map validate [path]          # architecture + structural violations
+/ast-map skeleton <file>          # show a file's symbols and imports
+/ast-map top [dir]                # top N most-imported symbols (God Nodes)
+/ast-map impact <file> <symbol>   # blast radius of changing a symbol
+/ast-map calls <file> <fn>        # call graph for a function
+/ast-map search <name> [dir]      # find a symbol across all files
+/ast-map deps <file>              # what this file imports / what imports it
+\`\`\`
+
+If no path is given, use \`.\` (current working directory). Do not ask the user for a path.
+
+---
+
+## What You Must Do When Invoked
+
+### Step 1 — Determine mode
+
+Parse the arguments after \`/ast-map\`:
+
+| Command | Action |
+|---------|--------|
+| _(no args)_ | Run full overview: dead + cycles + validate |
+| \`dead [dir]\` | Find dead exports |
+| \`cycles [dir]\` | Find circular deps |
+| \`validate [path]\` | Architecture + structural check |
+| \`skeleton <file>\` | File skeleton |
+| \`top [dir]\` | Top imported symbols |
+| \`impact <file> <symbol>\` | Change impact |
+| \`calls <file> <fn>\` | Call graph |
+| \`search <name> [dir]\` | Symbol search |
+| \`deps <file>\` | File dependencies |
+
+### Step 2 — Choose execution method
+
+**Prefer MCP tools** (faster, no subprocess). If \`mcp__ast-mapper__*\` tools are available in the current session, use them. Otherwise fall back to CLI.
+
+**MCP tool → CLI command mapping:**
+
+| Command | MCP Tool | CLI fallback |
+|---------|----------|-------------|
+| dead | \`find_dead_code\` | \`ast-map dead <dir>\` |
+| cycles | \`find_circular_deps\` | \`ast-map cycles <dir>\` |
+| validate | \`validate_architecture\` | \`ast-map validate <path>\` |
+| skeleton | \`get_skeleton_json\` | \`ast-map skeleton <file>\` |
+| top | \`get_top_symbols\` | \`ast-map top <dir>\` |
+| impact | \`get_change_impact\` | \`ast-map impact <file> <symbol>\` |
+| calls | \`get_call_graph\` | \`ast-map calls <file> <fn>\` |
+| search | \`search_symbol\` | \`ast-map search <name> <dir>\` |
+| deps | \`get_file_deps\` | \`ast-map deps <file>\` |
+
+### Step 3 — Full overview (no args)
+
+If no command was given, run a 3-part overview and present a unified report:
+
+1. **Dead code** — find high-confidence unused exports
+2. **Circular deps** — detect import cycles
+3. **Top symbols** — list the 5 most-imported symbols
+
+Then summarise:
+\`\`\`
+AST-MCP Overview — [directory]
+Scanned: N files
+
+Dead Code (high confidence): X symbols
+  [list, grouped by file]
+
+Circular Dependencies: Y cycles
+  [list each cycle as A → B → C → A]
+
+God Nodes (top 5 most imported):
+  1. symbolName (file) — imported by N files
+  ...
+
+Recommendation: [1-2 sentences on what to look at first]
+\`\`\`
+
+### Step 4 — Present results clearly
+
+- **Dead code**: group by file, show symbol name + kind. Note if 0 ("No dead exports found ✓")
+- **Cycles**: show each cycle as \`A.ts → B.ts → C.ts → A.ts\`. Note length.
+- **validate**: group by severity (errors first, then warnings). Show file + rule + message.
+- **skeleton**: show symbols as a tree with line ranges.
+- **impact**: show direct and transitive file lists + totalFiles count.
+- **calls**: show call list with line numbers + whether external.
+- **search**: show file + symbol + kind + line range.
+
+Always end with a relevant follow-up offer:
+- Found dead code? → "Want me to verify each one with \`impact\` before deleting?"
+- Found cycles? → "Want me to show which import to break to resolve the shortest cycle?"
+- Found God Nodes? → "Want me to check the blast radius of the top one?"
+
+---
+
+## Examples
+
+### /ast-map
+Runs dead + cycles + top on the current directory — a 30-second architecture health check.
+
+### /ast-map dead src/
+Finds all exported symbols in \`src/\` that are never imported by any other file.
+
+### /ast-map validate src/ --max-lines 300
+Checks for boundary violations, API routes missing try/catch, files over 300 lines.
+
+### /ast-map impact src/lib/auth.ts validateSession
+Shows every file that directly or transitively depends on \`validateSession\`.
+`;
+
+// ─── CLAUDE.md entry ──────────────────────────────────────────────────────────
+
+const CLAUDE_MD_ENTRY = `
+# ast-map
+- **ast-map** (\`~/.claude/skills/ast-map/SKILL.md\`) - AST-based code analysis: dead code, circular deps, blast radius, architecture validation, symbol search. Trigger: \`/ast-map\`
+When the user types \`/ast-map\`, invoke the Skill tool with \`skill: "ast-map"\` before doing anything else.
+`;
+
+// ─── Install ──────────────────────────────────────────────────────────────────
+
+function main() {
+  const claudeDir = path.join(os.homedir(), ".claude");
+
+  // Only install if Claude Code config directory exists
+  if (!fs.existsSync(claudeDir)) return;
+
+  try {
+    // 1. Write SKILL.md
+    const skillDir = path.join(claudeDir, "skills", "ast-map");
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), SKILL_MD, "utf8");
+
+    // 2. Update CLAUDE.md — idempotent (skip if entry already present)
+    const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
+    const existing = fs.existsSync(claudeMdPath)
+      ? fs.readFileSync(claudeMdPath, "utf8")
+      : "";
+
+    if (!existing.includes('skill: "ast-map"')) {
+      fs.writeFileSync(claudeMdPath, existing.trimEnd() + "\n" + CLAUDE_MD_ENTRY, "utf8");
+    }
+
+    console.log("✓ /ast-map skill installed to Claude Code (~/.claude/skills/ast-map/)");
+    console.log('  Type /ast-map in any Claude Code session to run code analysis.');
+  } catch {
+    // Non-fatal — skill install is best-effort, don't break npm install
+  }
+}
+
+main();