universal-ast-mapper 0.5.2

package/dist/parser.js

@@ -0,0 +1,84 @@
+import Parser from "web-tree-sitter";
+import { createRequire } from "node:module";
+import path from "node:path";
+const require = createRequire(import.meta.url);
+// `web-tree-sitter` 0.20.x ships a CommonJS class with static members that are
+// only populated after `init()`. We treat the static surface loosely.
+const P = Parser;
+let initPromise = null;
+const languageCache = new Map();
+const parserCache = new Map();
+function pkgDir(spec) {
+    return path.dirname(require.resolve(spec));
+}
+function grammarWasmPath(grammar) {
+    return path.join(pkgDir("tree-sitter-wasms/package.json"), "out", `tree-sitter-${grammar}.wasm`);
+}
+export async function initParser() {
+    if (!initPromise) {
+        const coreDir = pkgDir("web-tree-sitter/package.json");
+        initPromise = P.init({
+            locateFile(name) {
+                // The runtime requests "tree-sitter.wasm"; serve it from the package dir.
+                return path.join(coreDir, name);
+            },
+        });
+    }
+    return initPromise;
+}
+async function loadLanguage(grammar) {
+    await initParser();
+    const cached = languageCache.get(grammar);
+    if (cached)
+        return cached;
+    const lang = await P.Language.load(grammarWasmPath(grammar));
+    languageCache.set(grammar, lang);
+    return lang;
+}
+/** Parse source code with the given grammar and return the root node. */
+export async function parseSource(grammar, source) {
+    const lang = await loadLanguage(grammar);
+    let parser = parserCache.get(grammar);
+    if (!parser) {
+        parser = new P();
+        parser.setLanguage(lang);
+        parserCache.set(grammar, parser);
+    }
+    return parser.parse(source).rootNode;
+}
+/* ----------------------------- node helpers ----------------------------- */
+export function namedChildren(node) {
+    const out = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c)
+            out.push(c);
+    }
+    return out;
+}
+export function nameOf(node) {
+    const n = node.childForFieldName("name");
+    return n ? n.text : null;
+}
+/**
+ * Build a one-line "header" signature: text from the node start up to the
+ * start of its body (or the whole node if there is no body), whitespace
+ * collapsed. Works uniformly across languages.
+ */
+export function headerSignature(node, body) {
+    const src = node.text;
+    const slice = body ? src.slice(0, body.startIndex - node.startIndex) : src;
+    return slice.replace(/\s+/g, " ").trim();
+}
+/** Collect consecutive leading line/block comments immediately above a node. */
+export function leadingComment(node) {
+    const lines = [];
+    let prev = node.previousNamedSibling;
+    while (prev && prev.type === "comment") {
+        lines.unshift(prev.text);
+        prev = prev.previousNamedSibling;
+    }
+    if (lines.length === 0)
+        return null;
+    return lines.join("\n").slice(0, 500);
+}

package/dist/registry.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { extractTypeScript, extractDirectivesTS, extractImportsTS } from "./extractors/typescript.js";
+import { extractPython, extractImportsPython } from "./extractors/python.js";
+import { extractGo, extractImportsGo } from "./extractors/go.js";
+const TS_ENTRY = (language, grammar) => ({
+    language,
+    grammar,
+    extract: extractTypeScript,
+    extractDirectives: extractDirectivesTS,
+    extractImports: extractImportsTS,
+});
+/** Map of file extension -> language entry. The Factory/Strategy registry. */
+const BY_EXT = {
+    ".ts": TS_ENTRY("typescript", "typescript"),
+    ".mts": TS_ENTRY("typescript", "typescript"),
+    ".cts": TS_ENTRY("typescript", "typescript"),
+    ".tsx": TS_ENTRY("tsx", "tsx"),
+    ".js": TS_ENTRY("javascript", "javascript"),
+    ".mjs": TS_ENTRY("javascript", "javascript"),
+    ".cjs": TS_ENTRY("javascript", "javascript"),
+    ".jsx": TS_ENTRY("javascript", "tsx"),
+    ".py": { language: "python", grammar: "python", extract: extractPython, extractImports: extractImportsPython },
+    ".pyi": { language: "python", grammar: "python", extract: extractPython, extractImports: extractImportsPython },
+    ".go": { language: "go", grammar: "go", extract: extractGo, extractImports: extractImportsGo },
+};
+export function detectLanguage(filePath) {
+    return BY_EXT[path.extname(filePath).toLowerCase()] ?? null;
+}
+export function supportedExtensions() {
+    return Object.keys(BY_EXT);
+}
+export function supportedLanguages() {
+    const map = new Map();
+    for (const [ext, entry] of Object.entries(BY_EXT)) {
+        const arr = map.get(entry.language) ?? [];
+        arr.push(ext);
+        map.set(entry.language, arr);
+    }
+    return [...map.entries()].map(([language, extensions]) => ({ language, extensions }));
+}

package/dist/resolver.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { buildSkeleton } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+import { findSymbol } from "./analysis.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)
+        return null;
+    let depth = 0;
+    for (let i = start; i < sig.length; i++) {
+        if (sig[i] === "(")
+            depth++;
+        else if (sig[i] === ")") {
+            depth--;
+            if (depth === 0)
+                return sig.slice(start, i + 1);
+        }
+    }
+    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"],
+    ".mjs": [".mts", ".mjs"],
+    ".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).
+ * Returns null for external packages or when the file cannot be found.
+ */
+export function resolveImportPath(importFrom, fromAbs) {
+    if (!importFrom.startsWith("."))
+        return null;
+    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]) {
+            const p = base + ext;
+            if (fs.existsSync(p))
+                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
+    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))
+            return p;
+    }
+    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.
+ */
+export async function resolveFileImports(skel, absPath, root) {
+    if (!skel.imports || skel.imports.length === 0)
+        return [];
+    const opts = resolveOptions({ detail: "full", emitHtml: false });
+    const results = [];
+    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
+            }
+        }
+        else if (resolvedAbs) {
+            // Namespace import or side-effect: file exists = success
+            found = true;
+        }
+        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/dist/search.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
+import { resolveOptions, loadProjectConfig } from "./config.js";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Recursively yield every symbol in a file, including nested ones. */
+function* flattenSymbols(symbols, file, parentName) {
+    for (const sym of symbols) {
+        const fullName = parentName ? `${parentName}.${sym.name}` : sym.name;
+        yield {
+            file,
+            symbol: fullName,
+            kind: sym.kind,
+            exported: sym.exported ?? false,
+            range: sym.range,
+            ...(sym.signature ? { signature: sym.signature } : {}),
+        };
+        if (sym.children.length > 0) {
+            yield* flattenSymbols(sym.children, file, fullName);
+        }
+    }
+}
+function makeMatcher(pattern, matchType) {
+    if (matchType === "exact") {
+        return (name) => name === pattern || name.endsWith(`.${pattern}`);
+    }
+    if (matchType === "regex") {
+        const re = new RegExp(pattern, "i");
+        return (name) => re.test(name);
+    }
+    // contains (default) — case-insensitive
+    const lower = pattern.toLowerCase();
+    return (name) => name.toLowerCase().includes(lower);
+}
+/**
+ * Search for symbols by name pattern across all source files in a directory.
+ * Traverses nested symbols (methods inside classes, etc.) with dot-notation names.
+ *
+ * @param dirAbs    Absolute path of directory to scan.
+ * @param pattern   Name to search for (matched per `matchType`).
+ * @param root      Project root (for relative paths in results).
+ * @param options   matchType, kind filter, exportedOnly, detail level.
+ */
+export async function searchSymbols(dirAbs, pattern, root, options = {}) {
+    const { matchType = "contains", kind, exportedOnly = false, detail = "outline" } = options;
+    const test = makeMatcher(pattern, matchType);
+    const opts = resolveOptions({ detail, emitHtml: false }, loadProjectConfig(root));
+    const files = collectSourceFiles(dirAbs, opts);
+    const results = [];
+    for (const file of files) {
+        const fileRel = path.relative(root, file).split(path.sep).join("/");
+        try {
+            const skel = await buildSkeleton(file, fileRel, opts);
+            for (const match of flattenSymbols(skel.symbols, skel.file)) {
+                if (!test(match.symbol))
+                    continue;
+                if (kind && match.kind !== kind)
+                    continue;
+                if (exportedOnly && !match.exported)
+                    continue;
+                results.push(match);
+            }
+        }
+        catch {
+            // skip unreadable / unparseable files
+        }
+    }
+    return results;
+}

package/dist/skeleton.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { detectLanguage, supportedExtensions } from "./registry.js";
+import { parseSource } from "./parser.js";
+import { countSymbols, toOutline } from "./extractors/common.js";
+export const SCHEMA_VERSION = "1.1";
+export const GRAMMAR_SOURCE = "tree-sitter-wasms@0.1.13";
+const parseCache = new Map();
+function cacheKey(absPath, detail) { return `${absPath}|${detail}`; }
+function getCached(absPath, detail) {
+    try {
+        const entry = parseCache.get(cacheKey(absPath, detail));
+        if (!entry)
+            return null;
+        const mtime = fs.statSync(absPath).mtimeMs;
+        return entry.mtime === mtime ? entry.result : null;
+    }
+    catch {
+        return null;
+    }
+}
+function setCached(absPath, detail, result) {
+    try {
+        const mtime = fs.statSync(absPath).mtimeMs;
+        parseCache.set(cacheKey(absPath, detail), { mtime, result });
+    }
+    catch { /* skip if stat fails */ }
+}
+export class UnsupportedLanguageError extends Error {
+    ext;
+    constructor(ext) {
+        super(`Unsupported file type "${ext}". Supported: ${supportedExtensions().join(", ")}`);
+        this.ext = ext;
+        this.name = "UnsupportedLanguageError";
+    }
+}
+/**
+ * Build a skeleton for a single file.
+ * @param absPath absolute path on disk (already validated to be within root)
+ * @param relPath path relative to root, used as the displayed `file`
+ */
+export async function buildSkeleton(absPath, relPath, opts) {
+    const ext = path.extname(absPath).toLowerCase();
+    const entry = detectLanguage(absPath);
+    if (!entry)
+        throw new UnsupportedLanguageError(ext);
+    const stat = fs.statSync(absPath);
+    if (stat.size > opts.maxFileBytes) {
+        throw new Error(`File is ${stat.size} bytes, exceeds maxFileBytes (${opts.maxFileBytes}). Increase the limit to parse it.`);
+    }
+    // Return cached result if file hasn't changed
+    const cached = getCached(absPath, opts.detail);
+    if (cached)
+        return cached;
+    const source = fs.readFileSync(absPath, "utf8");
+    const root = await parseSource(entry.grammar, source);
+    let symbols = entry.extract(root, source);
+    if (opts.detail === "outline")
+        symbols = toOutline(symbols);
+    const directives = entry.extractDirectives ? entry.extractDirectives(root, source) : [];
+    const imports = entry.extractImports ? entry.extractImports(root, source) : [];
+    const result = {
+        schemaVersion: SCHEMA_VERSION,
+        file: relPath.split(path.sep).join("/"),
+        language: entry.language,
+        generatedAt: new Date().toISOString(),
+        parser: { engine: "tree-sitter", grammar: `${entry.grammar} (${GRAMMAR_SOURCE})` },
+        symbolCount: countSymbols(symbols),
+        ...(directives.length > 0 ? { directives } : {}),
+        ...(imports.length > 0 ? { imports } : {}),
+        symbols,
+    };
+    setCached(absPath, opts.detail, result);
+    return result;
+}
+/** Recursively collect supported source files under a directory. */
+export function collectSourceFiles(absDir, opts) {
+    const supported = new Set(supportedExtensions());
+    const ignore = new Set(opts.ignore);
+    const results = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".")) {
+                if (e.isDirectory())
+                    continue;
+            }
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!ignore.has(e.name))
+                    walk(full);
+            }
+            else if (e.isFile() && supported.has(path.extname(e.name).toLowerCase())) {
+                results.push(full);
+            }
+        }
+    };
+    walk(absDir);
+    return results.sort();
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Standard Skeleton JSON schema — the shared "interlingua" that every
+ * language extractor must produce, regardless of the source language.
+ */
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "universal-ast-mapper",
+  "version": "0.5.2",
+  "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "universal-ast-mapper": "dist/index.js",
+    "ast-map": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "BLUEPRINT.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "smoke": "node test/smoke.mjs",
+    "test": "node test/smoke.mjs && node test/analysis.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "ast",
+    "tree-sitter",
+    "code-map",
+    "skeleton"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.3",
+    "tree-sitter-wasms": "0.1.13",
+    "web-tree-sitter": "0.20.8",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}