universal-ast-mapper 1.28.0 → 2.0.1

package/dist/diagram.js

@@ -0,0 +1,264 @@
+import path from "node:path";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Replace non-word characters with underscore for Mermaid identifiers. */
+function sanitizeName(name) {
+    return name.replace(/\W/g, "_");
+}
+/** Replace path separators, dots, and dashes with underscore for Mermaid node IDs. */
+function sanitizeId(filePath) {
+    return filePath.replace(/[/.\-]/g, "_");
+}
+// ─── Class Diagram ────────────────────────────────────────────────────────────
+/**
+ * Class diagram from skeletons — shows classes, interfaces, enums and their
+ * relationships.
+ */
+export function buildClassDiagram(skeletons) {
+    const lines = ["classDiagram"];
+    const entries = [];
+    for (const skel of skeletons) {
+        for (const sym of skel.symbols) {
+            if (sym.kind === "class" || sym.kind === "interface" || sym.kind === "enum") {
+                entries.push({
+                    name: sym.name,
+                    sanitized: sanitizeName(sym.name),
+                    kind: sym.kind,
+                    node: sym,
+                });
+            }
+        }
+    }
+    // Enforce the 40-class limit.
+    const MAX_CLASSES = 40;
+    const truncated = entries.length > MAX_CLASSES;
+    const visible = truncated ? entries.slice(0, MAX_CLASSES) : entries;
+    const visibleNames = new Set(visible.map((e) => e.name));
+    let edgeCount = 0;
+    // Emit class/interface/enum blocks.
+    for (const entry of visible) {
+        const { sanitized, kind, node } = entry;
+        if (kind === "interface") {
+            lines.push(`  class ${sanitized} {`);
+            lines.push(`    <<interface>>`);
+            for (const child of node.children) {
+                if (child.kind === "method" || child.kind === "function") {
+                    const prefix = child.visibility === "private" ? "-" : "+";
+                    lines.push(`    ${prefix}${sanitizeName(child.name)}()`);
+                }
+            }
+            lines.push(`  }`);
+        }
+        else if (kind === "enum") {
+            lines.push(`  class ${sanitized} {`);
+            lines.push(`    <<enumeration>>`);
+            for (const child of node.children) {
+                lines.push(`    ${sanitizeName(child.name)}`);
+            }
+            lines.push(`  }`);
+        }
+        else {
+            // class
+            lines.push(`  class ${sanitized} {`);
+            for (const child of node.children) {
+                const prefix = child.visibility === "private" ? "-" : "+";
+                if (child.kind === "method" || child.kind === "function") {
+                    lines.push(`    ${prefix}${sanitizeName(child.name)}()`);
+                }
+                else if (child.kind === "field") {
+                    // Try to extract type from signature
+                    let fieldType = "";
+                    if (child.signature) {
+                        // Signature format: "fieldName: TypeName" or "fieldName?: TypeName"
+                        const match = child.signature.match(/:\s*(.+)$/);
+                        if (match)
+                            fieldType = sanitizeName(match[1].trim().split(/\s/)[0]) + " ";
+                    }
+                    lines.push(`    ${prefix}${fieldType}${sanitizeName(child.name)}`);
+                }
+            }
+            lines.push(`  }`);
+        }
+    }
+    // Emit "uses" edges from imports.
+    for (const skel of skeletons) {
+        if (!skel.imports)
+            continue;
+        // Find the class/interface names in this file.
+        const fileClasses = skel.symbols
+            .filter((s) => s.kind === "class" || s.kind === "interface" || s.kind === "enum")
+            .map((s) => s.name);
+        for (const fileClass of fileClasses) {
+            if (!visibleNames.has(fileClass))
+                continue;
+            const from = sanitizeName(fileClass);
+            for (const imp of skel.imports) {
+                if (imp.symbol && imp.symbol !== "*" && visibleNames.has(imp.symbol)) {
+                    const to = sanitizeName(imp.symbol);
+                    if (from !== to) {
+                        lines.push(`  ${from} --> ${to} : uses`);
+                        edgeCount++;
+                    }
+                }
+            }
+        }
+    }
+    if (truncated) {
+        lines.push(`  %% ... and ${entries.length - MAX_CLASSES} more`);
+    }
+    return {
+        type: "class",
+        mermaid: lines.join("\n"),
+        title: "Class Diagram",
+        nodeCount: visible.length,
+        edgeCount,
+    };
+}
+// ─── Deps Diagram ─────────────────────────────────────────────────────────────
+/**
+ * File dependency diagram from symbol graph.
+ */
+export function buildDepsDiagram(graph, maxNodes = 50) {
+    const lines = ["graph TD"];
+    // Collect file nodes only.
+    const fileNodes = graph.nodes.filter((n) => n.nodeType === "file");
+    const truncated = fileNodes.length > maxNodes;
+    const visibleFiles = new Set((truncated ? fileNodes.slice(0, maxNodes) : fileNodes).map((n) => n.id));
+    // Emit node labels.
+    for (const n of fileNodes) {
+        if (!visibleFiles.has(n.id))
+            continue;
+        const nodeId = sanitizeId(n.id);
+        const label = path.basename(n.id, path.extname(n.id));
+        lines.push(`  ${nodeId}["${label}"]`);
+        lines.push(`  click ${nodeId} callback "${n.id}"`);
+    }
+    // Collect import edges between visible file nodes.
+    // Build a map: symbolNodeId → file it belongs to.
+    const symbolToFile = new Map();
+    for (const n of graph.nodes) {
+        if (n.nodeType === "symbol") {
+            const sym = n;
+            symbolToFile.set(sym.id, sym.file);
+        }
+    }
+    // Deduplicate file-level edges.
+    const emittedEdges = new Set();
+    let edgeCount = 0;
+    for (const edge of graph.edges) {
+        if (edge.edgeType !== "imports")
+            continue;
+        const fromFile = edge.from;
+        // `to` may be a symbol node ID or a file node ID.
+        const toFile = symbolToFile.get(edge.to) ?? edge.to;
+        if (fromFile === toFile)
+            continue;
+        if (!visibleFiles.has(fromFile) || !visibleFiles.has(toFile))
+            continue;
+        const key = `${fromFile}→${toFile}`;
+        if (emittedEdges.has(key))
+            continue;
+        emittedEdges.add(key);
+        const fromId = sanitizeId(fromFile);
+        const toId = sanitizeId(toFile);
+        lines.push(`  ${fromId} --> ${toId}`);
+        edgeCount++;
+    }
+    if (truncated) {
+        lines.push(`  %% ... ${fileNodes.length - maxNodes} more nodes not shown`);
+    }
+    return {
+        type: "deps",
+        mermaid: lines.join("\n"),
+        title: "File Dependency Diagram",
+        nodeCount: visibleFiles.size,
+        edgeCount,
+    };
+}
+// ─── Modules Diagram ──────────────────────────────────────────────────────────
+/**
+ * Module/directory-level dependency diagram (collapsed by top-level directory).
+ */
+export function buildModulesDiagram(graph) {
+    const MAX_MODULES = 20;
+    const lines = ["graph LR"];
+    // Map each file to its top-level module (first directory component).
+    function fileToModule(fileId) {
+        const parts = fileId.split("/");
+        // If the file is at the root level (no directory), use "." as the module.
+        if (parts.length <= 1)
+            return ".";
+        // Use up to 2 path components for meaningful grouping when first segment is short
+        // (e.g. "src/auth" for "src/auth/user.ts").
+        return parts.slice(0, Math.min(2, parts.length - 1)).join("/");
+    }
+    // Build symbol-to-file lookup.
+    const symbolToFile = new Map();
+    for (const n of graph.nodes) {
+        if (n.nodeType === "symbol") {
+            const sym = n;
+            symbolToFile.set(sym.id, sym.file);
+        }
+    }
+    // Count inter-module edges.
+    const moduleEdgeCounts = new Map();
+    const moduleSet = new Set();
+    for (const n of graph.nodes) {
+        if (n.nodeType === "file") {
+            moduleSet.add(fileToModule(n.id));
+        }
+    }
+    for (const edge of graph.edges) {
+        if (edge.edgeType !== "imports")
+            continue;
+        const fromFile = edge.from;
+        const toFile = symbolToFile.get(edge.to) ?? edge.to;
+        if (fromFile === toFile)
+            continue;
+        const fromModule = fileToModule(fromFile);
+        const toModule = fileToModule(toFile);
+        if (fromModule === toModule)
+            continue;
+        const key = `${fromModule}→${toModule}`;
+        moduleEdgeCounts.set(key, (moduleEdgeCounts.get(key) ?? 0) + 1);
+    }
+    // Determine which modules are actually referenced by edges, then sort by
+    // occurrence to pick the most connected ones if we need to truncate.
+    const moduleOccurrences = new Map();
+    for (const [key, count] of moduleEdgeCounts) {
+        const [from, to] = key.split("→");
+        moduleOccurrences.set(from, (moduleOccurrences.get(from) ?? 0) + count);
+        moduleOccurrences.set(to, (moduleOccurrences.get(to) ?? 0) + count);
+    }
+    // Include all modules from the file set, sorted by occurrence descending.
+    const allModules = [...moduleSet].sort((a, b) => {
+        return (moduleOccurrences.get(b) ?? 0) - (moduleOccurrences.get(a) ?? 0);
+    });
+    const truncated = allModules.length > MAX_MODULES;
+    const visibleModules = new Set(truncated ? allModules.slice(0, MAX_MODULES) : allModules);
+    // Emit module nodes.
+    for (const mod of visibleModules) {
+        const nodeId = sanitizeName(mod);
+        lines.push(`  ${nodeId}["${mod}"]`);
+    }
+    // Emit weighted edges between visible modules.
+    let edgeCount = 0;
+    for (const [key, count] of moduleEdgeCounts) {
+        const [fromModule, toModule] = key.split("→");
+        if (!visibleModules.has(fromModule) || !visibleModules.has(toModule))
+            continue;
+        const fromId = sanitizeName(fromModule);
+        const toId = sanitizeName(toModule);
+        lines.push(`  ${fromId} -->|${count}| ${toId}`);
+        edgeCount++;
+    }
+    if (truncated) {
+        lines.push(`  %% ... ${allModules.length - MAX_MODULES} more modules not shown`);
+    }
+    return {
+        type: "modules",
+        mermaid: lines.join("\n"),
+        title: "Module Dependency Diagram",
+        nodeCount: visibleModules.size,
+        edgeCount,
+    };
+}

package/dist/docgen.js

@@ -0,0 +1,156 @@
+import https from "node:https";
+function flattenSymbols(symbols, file) {
+    const result = [];
+    for (const sym of symbols) {
+        result.push({
+            file,
+            name: sym.name,
+            kind: sym.kind,
+            signature: sym.signature,
+            exported: sym.exported !== false,
+            lineStart: sym.range.startLine,
+            description: sym.doc ?? undefined,
+        });
+        if (sym.children.length > 0) {
+            result.push(...flattenSymbols(sym.children, file));
+        }
+    }
+    return result;
+}
+export function buildDocOutput(skeletons, opts = {}) {
+    const files = [];
+    let totalSymbols = 0;
+    let exportedSymbols = 0;
+    for (const skel of skeletons) {
+        let syms = flattenSymbols(skel.symbols, skel.file);
+        if (opts.exportedOnly)
+            syms = syms.filter(s => s.exported);
+        if (syms.length === 0)
+            continue;
+        totalSymbols += syms.length;
+        exportedSymbols += syms.filter(s => s.exported).length;
+        files.push({ file: skel.file, language: skel.language, symbols: syms });
+    }
+    return { files, totalSymbols, exportedSymbols };
+}
+function htmlEsc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function renderMarkdown(output) {
+    const lines = [
+        "# API Reference",
+        "",
+        `> ${output.exportedSymbols} exported symbols across ${output.files.length} files`,
+        "",
+    ];
+    for (const f of output.files) {
+        lines.push(`## \`${f.file}\``, "");
+        for (const sym of f.symbols) {
+            const expMark = sym.exported ? "" : " _(internal)_";
+            lines.push(`### \`${sym.name}\` _(${sym.kind})_${expMark}`, "");
+            if (sym.signature)
+                lines.push("```", sym.signature, "```", "");
+            if (sym.description)
+                lines.push(sym.description, "");
+            lines.push(`_Line ${sym.lineStart}_`, "");
+        }
+    }
+    return lines.join("\n");
+}
+export function renderDocHtml(output) {
+    const rows = output.files.flatMap(f => f.symbols.map(s => `<tr><td><code>${htmlEsc(f.file)}</code></td><td><code>${htmlEsc(s.name)}</code></td><td>${s.kind}</td><td>${s.exported ? "✓" : ""}</td><td><code>${htmlEsc(s.signature ?? "")}</code></td><td>${htmlEsc(s.description ?? "")}</td></tr>`)).join("\n");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>API Reference</title>
+<style>body{font-family:sans-serif;padding:2rem;max-width:1200px;margin:0 auto}table{border-collapse:collapse;width:100%}th,td{border:1px solid #ddd;padding:6px 10px;text-align:left;vertical-align:top}th{background:#f5f5f5;font-size:.8em;text-transform:uppercase}code{font-family:monospace;font-size:.9em;background:#f0f0f0;padding:1px 3px;border-radius:2px}h1{margin-bottom:4px}p{color:#666;margin-bottom:1.5rem}</style>
+</head>
+<body>
+<h1>API Reference</h1>
+<p>${output.exportedSymbols} exported symbols &bull; ${output.files.length} files</p>
+<table>
+<thead><tr><th>File</th><th>Name</th><th>Kind</th><th>Exp</th><th>Signature</th><th>Description</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+</body></html>`;
+}
+// ─── AI enhancement ───────────────────────────────────────────────────────────
+async function callClaude(prompt, opts) {
+    const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        throw new Error("No Anthropic API key — set ANTHROPIC_API_KEY or pass --api-key");
+    const body = JSON.stringify({
+        model: opts.model ?? "claude-sonnet-4-6",
+        max_tokens: opts.maxTokens ?? 1024,
+        messages: [{ role: "user", content: prompt }],
+    });
+    return new Promise((resolve, reject) => {
+        const req = https.request({
+            hostname: "api.anthropic.com",
+            path: "/v1/messages",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-length": Buffer.byteLength(body),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                const raw = Buffer.concat(chunks).toString("utf8");
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (parsed.error)
+                        reject(new Error(`Anthropic API: ${parsed.error.message}`));
+                    else
+                        resolve(parsed.content?.[0]?.text ?? "");
+                }
+                catch {
+                    reject(new Error("Unexpected API response"));
+                }
+            });
+        });
+        req.on("error", reject);
+        req.write(body);
+        req.end();
+    });
+}
+export async function aiEnhanceDocs(output, opts = {}) {
+    const enhanced = {
+        ...output,
+        files: output.files.map(f => ({ ...f, symbols: f.symbols.map(s => ({ ...s })) })),
+    };
+    for (const docFile of enhanced.files) {
+        const toEnhance = docFile.symbols.filter(s => s.exported && !s.description);
+        if (toEnhance.length === 0)
+            continue;
+        const batch = toEnhance.slice(0, 20);
+        const symbolList = batch.map(s => `- ${s.name} (${s.kind})${s.signature ? `: ${s.signature}` : ""}`).join("\n");
+        const prompt = `You are a technical writer generating concise JSDoc-style descriptions for API symbols.
+
+File: ${docFile.file}
+Language: ${docFile.language}
+
+For each symbol below, write a single short sentence (max 20 words) describing what it does.
+Respond ONLY as JSON: {"symbolName": "description", ...}
+
+Symbols:
+${symbolList}`;
+        try {
+            const raw = await callClaude(prompt, opts);
+            const jsonMatch = raw.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const descriptions = JSON.parse(jsonMatch[0]);
+                for (const sym of docFile.symbols) {
+                    if (descriptions[sym.name])
+                        sym.description = descriptions[sym.name];
+                }
+            }
+        }
+        catch { /* skip on error */ }
+    }
+    return enhanced;
+}

package/dist/embeddings.js

@@ -0,0 +1,136 @@
+import https from "node:https";
+// ─── Tokenize ─────────────────────────────────────────────────────────────────
+function tokenize(text) {
+    return text
+        .replace(/([A-Z])/g, " $1")
+        .replace(/[_\-().:<>{}[\],]/g, " ")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(t => t.length > 1);
+}
+// ─── TF-IDF vectors ───────────────────────────────────────────────────────────
+export function buildTfIdfVectors(skeletons) {
+    const docs = [];
+    for (const skel of skeletons) {
+        for (const sym of skel.symbols) {
+            const text = [sym.name, sym.signature ?? "", sym.kind].join(" ");
+            docs.push({ file: skel.file, symbol: sym.name, kind: sym.kind, tokens: tokenize(text) });
+        }
+    }
+    if (docs.length === 0)
+        return [];
+    const df = new Map();
+    for (const doc of docs) {
+        for (const term of new Set(doc.tokens)) {
+            df.set(term, (df.get(term) ?? 0) + 1);
+        }
+    }
+    const N = docs.length;
+    const vectors = [];
+    for (const doc of docs) {
+        const tf = new Map();
+        for (const term of doc.tokens)
+            tf.set(term, (tf.get(term) ?? 0) + 1);
+        const terms = {};
+        for (const [term, count] of tf.entries()) {
+            const idf = Math.log(N / (df.get(term) ?? 1));
+            terms[term] = (count / doc.tokens.length) * idf;
+        }
+        const norm = Math.sqrt(Object.values(terms).reduce((s, v) => s + v * v, 0));
+        vectors.push({ file: doc.file, symbol: doc.symbol, kind: doc.kind, terms, norm });
+    }
+    return vectors;
+}
+// ─── Cosine search ────────────────────────────────────────────────────────────
+export function cosineSearch(vectors, query, limit = 20) {
+    const qTokens = tokenize(query);
+    if (qTokens.length === 0)
+        return [];
+    const qTf = new Map();
+    for (const t of qTokens)
+        qTf.set(t, (qTf.get(t) ?? 0) + 1);
+    const qNorm = Math.sqrt([...qTf.values()].reduce((s, v) => s + (v / qTokens.length) ** 2, 0));
+    if (qNorm === 0)
+        return [];
+    const scores = [];
+    for (const vec of vectors) {
+        if (vec.norm === 0)
+            continue;
+        let dot = 0;
+        for (const [term, qCount] of qTf.entries()) {
+            const qTfidf = qCount / qTokens.length;
+            const dTfidf = vec.terms[term] ?? 0;
+            dot += qTfidf * dTfidf;
+        }
+        const score = dot / (qNorm * vec.norm);
+        if (score > 0)
+            scores.push({ file: vec.file, symbol: vec.symbol, kind: vec.kind, score });
+    }
+    return scores.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+// ─── Claude re-ranking ────────────────────────────────────────────────────────
+export async function rerankWithClaude(matches, query, opts = {}) {
+    if (matches.length === 0)
+        return matches;
+    const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        return matches;
+    const list = matches.map((m, i) => `${i + 1}. ${m.symbol} (${m.kind}) in ${m.file}`).join("\n");
+    const prompt = `You are helping re-rank code search results for the query: "${query}"
+
+Results:
+${list}
+
+Re-rank these by relevance to the query. Respond ONLY with a JSON array of 1-based indices in order of relevance, e.g. [3, 1, 5, 2, 4].`;
+    const body = JSON.stringify({
+        model: opts.model ?? "claude-sonnet-4-6",
+        max_tokens: 256,
+        messages: [{ role: "user", content: prompt }],
+    });
+    try {
+        const raw = await new Promise((resolve, reject) => {
+            const req = https.request({
+                hostname: "api.anthropic.com",
+                path: "/v1/messages",
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-api-key": apiKey,
+                    "anthropic-version": "2023-06-01",
+                    "content-length": Buffer.byteLength(body),
+                },
+            }, (res) => {
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => {
+                    const text = Buffer.concat(chunks).toString("utf8");
+                    try {
+                        const parsed = JSON.parse(text);
+                        resolve(parsed.content?.[0]?.text ?? "");
+                    }
+                    catch {
+                        resolve("");
+                    }
+                });
+            });
+            req.on("error", reject);
+            req.write(body);
+            req.end();
+        });
+        const arrMatch = raw.match(/\[[\d,\s]+\]/);
+        if (arrMatch) {
+            const indices = JSON.parse(arrMatch[0]);
+            const reranked = indices
+                .filter(i => i >= 1 && i <= matches.length)
+                .map(i => matches[i - 1]);
+            const covered = new Set(indices);
+            for (let i = 1; i <= matches.length; i++) {
+                if (!covered.has(i))
+                    reranked.push(matches[i - 1]);
+            }
+            return reranked;
+        }
+    }
+    catch { /* fall through */ }
+    return matches;
+}

package/dist/explain.js

@@ -0,0 +1,123 @@
+import https from "node:https";
+// ─── Structural analysis ──────────────────────────────────────────────────────
+export function buildExplainResult(symbolName, skel, graph, impact, smells, complexityRating) {
+    // Find the symbol node in the skeleton
+    const sym = findSymbolNode(skel.symbols, symbolName);
+    // Callers = files that transitively depend on this symbol
+    const callerFiles = impact
+        ? [...new Set([...impact.direct, ...impact.transitive].map((n) => n.file))]
+        : [];
+    // Dependencies = what this file imports that relate to this symbol
+    const dependsOn = (skel.imports ?? [])
+        .filter((imp) => imp.symbol || imp.from)
+        .map((imp) => imp.symbol ? `${imp.symbol} from ${imp.from}` : imp.from)
+        .slice(0, 10);
+    const lineCount = sym ? sym.range.endLine - sym.range.startLine + 1 : 0;
+    const isAsync = !!(sym?.signature?.includes("async "));
+    const isExported = sym?.exported !== false;
+    return {
+        symbol: symbolName,
+        file: skel.file,
+        kind: sym?.kind ?? "unknown",
+        signature: sym?.signature,
+        summary: {
+            callerFiles: callerFiles.slice(0, 20),
+            callerCount: impact ? impact.totalFiles : 0,
+            dependsOn,
+            childCount: sym?.children.length ?? 0,
+            lineCount,
+            isExported,
+            isAsync,
+        },
+        smells,
+        complexityRating,
+    };
+}
+function findSymbolNode(symbols, name) {
+    for (const sym of symbols) {
+        if (sym.name === name)
+            return sym;
+        const child = findSymbolNode(sym.children, name);
+        if (child)
+            return child;
+    }
+    return undefined;
+}
+// ─── AI explanation ───────────────────────────────────────────────────────────
+function buildPrompt(result, sourceCode) {
+    const callers = result.summary.callerFiles.slice(0, 8).join(", ") || "none detected";
+    const deps = result.summary.dependsOn.slice(0, 6).join(", ") || "none";
+    const smellsStr = result.smells.length ? result.smells.join(", ") : "none";
+    return `You are a senior software engineer explaining a codebase symbol to a teammate.
+
+## Symbol: \`${result.symbol}\`
+- Kind: ${result.kind}
+- File: ${result.file}
+- Signature: ${result.signature ?? "(no signature)"}
+- Exported: ${result.summary.isExported}
+- Async: ${result.summary.isAsync}
+- Line count: ${result.summary.lineCount}
+- Complexity rating: ${result.complexityRating ?? "unknown"}
+- Code smells: ${smellsStr}
+- Depends on: ${deps}
+- Used by (${result.summary.callerCount} files): ${callers}
+
+## Source snippet (first 60 lines):
+\`\`\`
+${sourceCode.split("\n").slice(0, 60).join("\n")}
+\`\`\`
+
+Explain this symbol in 3–5 concise sentences covering:
+1. What it does (purpose, not implementation)
+2. When/why callers use it
+3. Key dependencies or side effects worth knowing
+4. Change risk: what breaks if this symbol is modified or removed
+
+Do NOT include code. Plain prose only. Be specific, not generic.`;
+}
+async function callClaude(prompt, opts) {
+    const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        throw new Error("No Anthropic API key — set ANTHROPIC_API_KEY or pass --api-key");
+    const body = JSON.stringify({
+        model: opts.model ?? "claude-sonnet-4-6",
+        max_tokens: opts.maxTokens ?? 1024,
+        messages: [{ role: "user", content: prompt }],
+    });
+    return new Promise((resolve, reject) => {
+        const req = https.request({
+            hostname: "api.anthropic.com",
+            path: "/v1/messages",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-length": Buffer.byteLength(body),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                const raw = Buffer.concat(chunks).toString("utf8");
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (parsed.error)
+                        reject(new Error(`Anthropic API: ${parsed.error.message}`));
+                    else
+                        resolve(parsed.content?.[0]?.text ?? "");
+                }
+                catch {
+                    reject(new Error(`Unexpected API response`));
+                }
+            });
+        });
+        req.on("error", reject);
+        req.write(body);
+        req.end();
+    });
+}
+export async function aiExplain(result, sourceCode, opts = {}) {
+    const aiExplanation = await callClaude(buildPrompt(result, sourceCode), opts);
+    return { ...result, aiExplanation };
+}