universal-ast-mapper 2.0.0 → 2.0.1

package/dist/plugins.js

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+// ─── Loader ───────────────────────────────────────────────────────────────────
+const PLUGINS_DIR = ".ast-map/plugins";
+/** Load all `.mjs` / `.js` plugin files from `<root>/.ast-map/plugins/`. */
+export async function loadPlugins(root) {
+    const dir = path.join(root, PLUGINS_DIR);
+    if (!fs.existsSync(dir))
+        return [];
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith(".mjs") || f.endsWith(".js"));
+    const plugins = [];
+    for (const file of files) {
+        const abs = path.resolve(dir, file);
+        try {
+            const mod = await import(abs);
+            const plugin = "default" in mod && isPlugin(mod.default) ? mod.default
+                : "plugin" in mod && isPlugin(mod.plugin) ? mod.plugin
+                    : isPlugin(mod) ? mod
+                        : undefined;
+            if (plugin)
+                plugins.push(plugin);
+            else
+                process.stderr.write(`[ast-map plugins] ${file}: no valid default/plugin export\n`);
+        }
+        catch (e) {
+            process.stderr.write(`[ast-map plugins] failed to load ${file}: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    return plugins;
+}
+function isPlugin(v) {
+    return typeof v === "object" && v !== null && "id" in v && "run" in v && typeof v.run === "function";
+}
+/** Run all loaded plugins against the given skeletons. */
+export async function runPlugins(plugins, ctx) {
+    const results = [];
+    for (const plugin of plugins) {
+        try {
+            const violations = await plugin.run(ctx);
+            results.push({ pluginId: plugin.id, description: plugin.description, violations });
+        }
+        catch (e) {
+            results.push({
+                pluginId: plugin.id,
+                description: plugin.description,
+                violations: [],
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    return results;
+}
+// ─── Example plugin scaffolding (written to disk by ast-map init) ─────────────
+export const EXAMPLE_PLUGIN = `/**
+ * Example ast-map plugin: no-console-in-lib
+ *
+ * Reports any "console.log/warn/error" usage in library source files.
+ * Adapt the logic to define your own custom rules.
+ *
+ * Export your plugin as the default export.
+ * @type {import('universal-ast-mapper').AstMapPlugin}
+ */
+export default {
+  id: "no-console-in-lib",
+  description: "Disallow console.* calls in library code",
+
+  run({ skeletons }) {
+    const violations = [];
+    for (const skel of skeletons) {
+      // Only apply to files under src/ (adjust as needed)
+      if (!skel.file.startsWith("src/")) continue;
+      for (const sym of skel.symbols) {
+        if (sym.name.startsWith("console")) {
+          violations.push({
+            rule: "no-console-in-lib",
+            file: skel.file,
+            line: sym.range?.startLine,
+            symbol: sym.name,
+            severity: "warning",
+            message: \`console.\${sym.name} should not be used in library code\`,
+          });
+        }
+      }
+    }
+    return violations;
+  },
+};
+`;

package/dist/pool.js

@@ -0,0 +1,114 @@
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { buildSkeleton } from "./skeleton.js";
+import { computeFileComplexity } from "./complexity.js";
+import { diskCacheDir } from "./diskcache.js";
+/** Batches smaller than this are parsed sequentially (worker startup costs more). */
+const MIN_BATCH = 64;
+const MAX_WORKERS = 8;
+function envWorkers() {
+    const env = process.env.AST_MAP_WORKERS;
+    if (env === undefined || env === "")
+        return null;
+    const v = Number.parseInt(env, 10);
+    return Number.isNaN(v) ? null : Math.max(0, Math.min(v, MAX_WORKERS));
+}
+function plannedWorkers(n) {
+    const forced = envWorkers();
+    if (forced !== null)
+        return forced;
+    const cpus = os.cpus().length;
+    return Math.min(Math.max(cpus - 1, 0), MAX_WORKERS, Math.ceil(n / MIN_BATCH));
+}
+async function buildSequential(items, opts, withComplexity, out) {
+    for (let i = 0; i < items.length; i++) {
+        if (out[i] !== undefined)
+            continue; // already produced by a worker
+        try {
+            const skel = await buildSkeleton(items[i].abs, items[i].rel, opts);
+            const complexity = withComplexity
+                ? await computeFileComplexity(items[i].abs, items[i].rel)
+                : undefined;
+            out[i] = { skel, complexity };
+        }
+        catch {
+            out[i] = null; // unparsable / unsupported — callers skip nulls
+        }
+    }
+}
+/**
+ * Build skeletons for many files, in parallel when it pays off.
+ * Returns one entry per input item (null = failed/unsupported file).
+ */
+export async function buildSkeletonsBulk(items, opts, withComplexity = false) {
+    const out = new Array(items.length);
+    const workers = plannedWorkers(items.length);
+    const workerFile = path.join(path.dirname(fileURLToPath(import.meta.url)), "worker.js");
+    // An explicit AST_MAP_WORKERS >= 2 bypasses the batch-size gate.
+    const smallBatch = items.length < MIN_BATCH && envWorkers() === null;
+    if (smallBatch || workers <= 1 || !fs.existsSync(workerFile)) {
+        await buildSequential(items, opts, withComplexity, out);
+        return out;
+    }
+    let failed = false;
+    await new Promise((resolve) => {
+        let next = 0;
+        let done = 0;
+        let open = 0;
+        const pool = [];
+        const finish = () => {
+            for (const w of pool)
+                void w.terminate();
+            resolve();
+        };
+        const dispatch = (w) => {
+            if (failed || next >= items.length) {
+                return;
+            }
+            const id = next++;
+            w.postMessage({ id, abs: items[id].abs, rel: items[id].rel, opts, withComplexity });
+        };
+        for (let i = 0; i < workers; i++) {
+            let w;
+            try {
+                w = new Worker(workerFile, { workerData: { cacheDir: diskCacheDir() } });
+            }
+            catch {
+                failed = true;
+                break;
+            }
+            open++;
+            pool.push(w);
+            w.on("message", (msg) => {
+                out[msg.id] = msg.ok && msg.skel ? { skel: msg.skel, complexity: msg.complexity } : null;
+                done++;
+                if (done >= items.length || failed)
+                    finish();
+                else
+                    dispatch(w);
+            });
+            w.on("error", () => {
+                failed = true;
+                finish();
+            });
+            dispatch(w);
+            // prime a second task per worker to hide round-trip latency
+            dispatch(w);
+        }
+        if (pool.length === 0)
+            resolve();
+        else if (open === 0)
+            resolve();
+    });
+    // Fill any gaps (worker failure, early termination) sequentially.
+    for (let i = 0; i < items.length; i++) {
+        if (out[i] === undefined) {
+            await buildSequential(items, opts, withComplexity, out);
+            break;
+        }
+    }
+    return out;
+}

package/dist/prompts.js

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

package/dist/registry.js

@@ -0,0 +1,87 @@
+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";
+import { extractRust, extractImportsRust } from "./extractors/rust.js";
+import { extractJava, extractDirectivesJava, extractImportsJava } from "./extractors/java.js";
+import { extractCSharp, extractDirectivesCSharp, extractImportsCSharp } from "./extractors/csharp.js";
+import { extractC, extractImportsC } from "./extractors/c.js";
+import { extractCpp, extractImportsCpp } from "./extractors/cpp.js";
+import { extractKotlin, extractDirectivesKotlin, extractImportsKotlin } from "./extractors/kotlin.js";
+import { extractSwift, extractImportsSwift } from "./extractors/swift.js";
+import { extractPhp, extractImportsPhp } from "./extractors/php.js";
+import { extractRuby, extractImportsRuby } from "./extractors/ruby.js";
+const TS_ENTRY = (language, grammar) => ({
+    language,
+    grammar,
+    extract: extractTypeScript,
+    extractDirectives: extractDirectivesTS,
+    extractImports: extractImportsTS,
+});
+const SFC_ENTRY = (language) => ({
+    language,
+    grammar: "typescript", // overridden per-file after detecting lang="ts" vs js
+    extract: extractTypeScript,
+    extractDirectives: extractDirectivesTS,
+    extractImports: extractImportsTS,
+    sfc: true,
+});
+const BY_EXT = {
+    ".ts": TS_ENTRY("typescript", "typescript"),
+    ".mts": TS_ENTRY("typescript", "typescript"),
+    ".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 },
+    ".rs": { language: "rust", grammar: "rust", extract: extractRust, extractImports: extractImportsRust },
+    ".java": {
+        language: "java", grammar: "java",
+        extract: extractJava, extractDirectives: extractDirectivesJava, extractImports: extractImportsJava,
+    },
+    ".cs": {
+        language: "csharp", grammar: "c_sharp",
+        extract: extractCSharp, extractDirectives: extractDirectivesCSharp, extractImports: extractImportsCSharp,
+    },
+    ".c": { language: "c", grammar: "c", extract: extractC, extractImports: extractImportsC },
+    ".h": { language: "c", grammar: "c", extract: extractC, extractImports: extractImportsC },
+    ".cpp": { language: "cpp", grammar: "cpp", extract: extractCpp, extractImports: extractImportsCpp },
+    ".cxx": { language: "cpp", grammar: "cpp", extract: extractCpp, extractImports: extractImportsCpp },
+    ".cc": { language: "cpp", grammar: "cpp", extract: extractCpp, extractImports: extractImportsCpp },
+    ".hpp": { language: "cpp", grammar: "cpp", extract: extractCpp, extractImports: extractImportsCpp },
+    ".hxx": { language: "cpp", grammar: "cpp", extract: extractCpp, extractImports: extractImportsCpp },
+    ".hh": { language: "cpp", grammar: "cpp", extract: extractCpp, extractImports: extractImportsCpp },
+    ".kt": {
+        language: "kotlin", grammar: "kotlin",
+        extract: extractKotlin, extractDirectives: extractDirectivesKotlin, extractImports: extractImportsKotlin,
+    },
+    ".kts": {
+        language: "kotlin", grammar: "kotlin",
+        extract: extractKotlin, extractDirectives: extractDirectivesKotlin, extractImports: extractImportsKotlin,
+    },
+    ".swift": { language: "swift", grammar: "swift", extract: extractSwift, extractImports: extractImportsSwift },
+    ".php": { language: "php", grammar: "php", extract: extractPhp, extractImports: extractImportsPhp },
+    ".rb": { language: "ruby", grammar: "ruby", extract: extractRuby, extractImports: extractImportsRuby },
+    ".rake": { language: "ruby", grammar: "ruby", extract: extractRuby, extractImports: extractImportsRuby },
+    ".vue": SFC_ENTRY("vue"),
+    ".svelte": SFC_ENTRY("svelte"),
+};
+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 }));
+}