universal-ast-mapper 2.0.0 → 2.0.2

package/dist/complexity.js

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import { parseSource } from "./parser.js";
+import { detectLanguage } from "./registry.js";
+import { buildSkeleton } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+// ─── Decision points ───────────────────────────────────────────────────────────
+/**
+ * Node types that introduce a branch (each adds 1 to cyclomatic complexity).
+ * This is a deliberately broad cross-language union; languages that use a node
+ * type not listed here simply undercount rather than miscount.
+ */
+const DECISION_TYPES = new Set([
+    // conditionals
+    "if_statement", "if_expression", "elif_clause", "else_if_clause",
+    // loops
+    "for_statement", "for_in_statement", "for_of_statement", "enhanced_for_statement",
+    "for_expression", "while_statement", "while_expression", "do_statement", "loop_statement",
+    // switch / match arms (the default/else arm is intentionally excluded)
+    "switch_case", "expression_case", "type_case", "case_clause", "when_entry",
+    "when_clause", "match_arm", "case_statement",
+    // exception handlers
+    "catch_clause", "except_clause", "rescue_clause",
+    // ternary
+    "ternary_expression", "conditional_expression",
+    // python `and` / `or`
+    "boolean_operator",
+]);
+const FN_KINDS = new Set(["function", "method"]);
+function rate(c) {
+    if (c <= 5)
+        return "low";
+    if (c <= 10)
+        return "moderate";
+    if (c <= 20)
+        return "high";
+    return "very-high";
+}
+/** Collect the start line of every decision point in the tree. */
+function collectDecisionLines(node, out) {
+    const t = node.type;
+    if (DECISION_TYPES.has(t)) {
+        out.push(node.startPosition.row + 1);
+    }
+    else if (t === "binary_expression") {
+        // Short-circuit operators add a branch; arithmetic operators do not.
+        const op = node.childForFieldName("operator");
+        if (op && (op.text === "&&" || op.text === "||"))
+            out.push(node.startPosition.row + 1);
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c)
+            collectDecisionLines(c, out);
+    }
+}
+function flatten(symbols, acc = []) {
+    for (const s of symbols) {
+        acc.push(s);
+        flatten(s.children, acc);
+    }
+    return acc;
+}
+/**
+ * Compute cyclomatic complexity for every function/method in a file.
+ * Complexity is attributed by line range, so a function's score includes the
+ * control flow of any closures/nested functions declared inside it.
+ */
+export async function computeFileComplexity(absPath, relPath) {
+    const lang = detectLanguage(absPath);
+    if (!lang)
+        return null;
+    const source = fs.readFileSync(absPath, "utf8");
+    const root = await parseSource(lang.grammar, source);
+    const decisionLines = [];
+    collectDecisionLines(root, decisionLines);
+    const opts = resolveOptions({ detail: "outline", emitHtml: false });
+    const skel = await buildSkeleton(absPath, relPath, opts);
+    const functions = flatten(skel.symbols)
+        .filter((s) => FN_KINDS.has(s.kind))
+        .map((s) => {
+        const count = decisionLines.filter((l) => l >= s.range.startLine && l <= s.range.endLine).length;
+        const complexity = 1 + count;
+        return {
+            name: s.name,
+            kind: s.kind,
+            startLine: s.range.startLine,
+            endLine: s.range.endLine,
+            complexity,
+            rating: rate(complexity),
+        };
+    })
+        .sort((a, b) => b.complexity - a.complexity);
+    const maxComplexity = functions.reduce((m, f) => Math.max(m, f.complexity), 0);
+    const averageComplexity = functions.length === 0
+        ? 0
+        : Math.round((functions.reduce((s, f) => s + f.complexity, 0) / functions.length) * 10) / 10;
+    return { file: skel.file, functions, maxComplexity, averageComplexity };
+}

package/dist/config.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_IGNORE = [
+    "node_modules",
+    "vendor",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "out",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".ast-map",
+];
+let _configCache = null;
+/**
+ * Load .ast-map.config.json from the project root.
+ * Cached per root path + file mtime so live edits are picked up without restarting.
+ * Returns an empty config if no file is found.
+ */
+export function loadProjectConfig(root) {
+    const configPath = path.join(root, ".ast-map.config.json");
+    let mtime = 0;
+    try {
+        mtime = fs.statSync(configPath).mtimeMs;
+    }
+    catch { /* file absent */ }
+    if (_configCache?.root === root && _configCache.mtime === mtime)
+        return _configCache.config;
+    let config = {};
+    try {
+        const raw = fs.readFileSync(configPath, "utf8");
+        config = JSON.parse(raw);
+    }
+    catch {
+        // No config file or parse error — use defaults
+    }
+    _configCache = { root, mtime, config };
+    return config;
+}
+export function resolveOptions(opts = {}, projectConfig = {}) {
+    const extraIgnore = projectConfig.ignore ?? [];
+    const mergedIgnore = [...new Set([...DEFAULT_IGNORE, ...extraIgnore])];
+    return {
+        detail: opts.detail ?? "outline",
+        emitHtml: opts.emitHtml ?? true,
+        combineHtml: opts.combineHtml ?? false,
+        outputDir: opts.outputDir ?? projectConfig.outputDir,
+        ignore: opts.ignore ?? mergedIgnore,
+        maxFileBytes: opts.maxFileBytes ?? projectConfig.maxFileBytes ?? 2_000_000,
+    };
+}

package/dist/contextpack.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+import { resolveFileImports } from "./resolver.js";
+import { buildCallGraph } from "./callgraph.js";
+function findSym(syms, name) {
+    for (const s of syms) {
+        if (s.name === name)
+            return s;
+        const n = findSym(s.children, name);
+        if (n)
+            return n;
+    }
+    return null;
+}
+const tok = (s) => Math.round(s.length / 4);
+/**
+ * Assemble the minimal context an agent needs to understand or change a symbol:
+ * the symbol's own source, the signatures of what it depends on (resolved
+ * imports), and the files that depend on it — instead of reading whole files.
+ */
+export async function packContext(absFile, relFile, root, symbolName, scanDir) {
+    const opts = resolveOptions({ detail: "full", emitHtml: false });
+    const skel = await buildSkeleton(absFile, relFile, opts);
+    const lines = fs.readFileSync(absFile, "utf8").split(/\r?\n/);
+    let startLine = 1, endLine = lines.length;
+    if (symbolName) {
+        const sym = findSym(skel.symbols, symbolName);
+        if (sym) {
+            startLine = sym.range.startLine;
+            endLine = sym.range.endLine;
+        }
+    }
+    const source = lines.slice(startLine - 1, endLine).join("\n");
+    // Dependencies: resolved in-project imports + the target symbol signatures.
+    const refs = await resolveFileImports(skel, absFile, root);
+    const byFile = new Map();
+    for (const r of refs) {
+        if (!r.found || !r.resolvedRel)
+            continue;
+        const arr = byFile.get(r.resolvedRel) ?? [];
+        if (!arr.some((x) => x.name === r.symbol))
+            arr.push({ name: r.symbol, signature: r.signature ?? null });
+        byFile.set(r.resolvedRel, arr);
+    }
+    const dependencies = [...byFile.entries()].map(([file, symbols]) => ({ file, symbols }));
+    // Dependents: who calls the seed symbol (needs a directory scan).
+    let dependents = [];
+    if (symbolName && scanDir) {
+        const sopts = resolveOptions({ detail: "outline", emitHtml: false });
+        const skels = [];
+        for (const f of collectSourceFiles(scanDir, sopts)) {
+            const rr = path.relative(root, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, rr, sopts));
+            }
+            catch { /* skip */ }
+        }
+        const cg = await buildCallGraph(absFile, symbolName, root, skels);
+        if (cg) {
+            const seen = new Set();
+            for (const c of cg.calledBy)
+                if (!seen.has(c.file)) {
+                    seen.add(c.file);
+                    dependents.push({ file: c.file });
+                }
+        }
+    }
+    const depTok = dependencies.reduce((a, d) => a + d.symbols.reduce((b, s) => b + tok(s.signature || s.name), 0), 0);
+    return {
+        seed: { file: relFile, ...(symbolName ? { symbol: symbolName } : {}) },
+        primary: { file: relFile, ...(symbolName ? { symbol: symbolName } : {}), startLine, endLine, source },
+        dependencies,
+        dependents,
+        tokenEstimate: tok(source) + depTok,
+        note: "Read primary.source in full; for dependencies you usually only need the listed signatures, not the whole files.",
+    };
+}

package/dist/coupling.js

@@ -0,0 +1,35 @@
+/**
+ * Compute Robert C. Martin's coupling metrics per file from the symbol graph's
+ * file-level import edges: afferent (fan-in), efferent (fan-out), and instability.
+ */
+export function computeCoupling(graph) {
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    const out = new Map(); // file -> set of files it imports
+    const inc = new Map(); // file -> set of files that import it
+    const files = new Set();
+    for (const n of graph.nodes)
+        if (n.nodeType === "file")
+            files.add(n.id);
+    for (const e of graph.edges) {
+        if (e.edgeType !== "imports")
+            continue;
+        const to = nodeMap.get(e.to);
+        const toFile = to ? (to.nodeType === "file" ? to.id : to.file) : null;
+        const fromFile = e.from;
+        if (!toFile || fromFile === toFile)
+            continue;
+        files.add(fromFile);
+        files.add(toFile);
+        (out.get(fromFile) ?? out.set(fromFile, new Set()).get(fromFile)).add(toFile);
+        (inc.get(toFile) ?? inc.set(toFile, new Set()).get(toFile)).add(fromFile);
+    }
+    const metrics = [];
+    for (const f of files) {
+        const ce = out.get(f)?.size ?? 0;
+        const ca = inc.get(f)?.size ?? 0;
+        const instability = ca + ce === 0 ? 0 : Math.round((ce / (ca + ce)) * 100) / 100;
+        metrics.push({ file: f, afferent: ca, efferent: ce, instability });
+    }
+    // Sort by total coupling desc (most-connected first).
+    return metrics.sort((a, b) => (b.afferent + b.efferent) - (a.afferent + a.efferent) || a.file.localeCompare(b.file));
+}

package/dist/covmerge.js

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+// ─── Format detection ─────────────────────────────────────────────────────────
+export function detectFormat(reportPath) {
+    const ext = path.extname(reportPath).toLowerCase();
+    const base = path.basename(reportPath).toLowerCase();
+    if (ext === ".json") {
+        try {
+            const raw = JSON.parse(fs.readFileSync(reportPath, "utf8"));
+            if ("total" in raw && typeof raw.total === "object")
+                return "istanbul";
+            if ("version" in raw)
+                return "clover";
+        }
+        catch { /* fall through */ }
+        return "istanbul";
+    }
+    if (ext === ".lcov" || base.endsWith(".info") || base === "lcov.info")
+        return "lcov";
+    if (base.includes("clover"))
+        return "clover";
+    if (base.includes("cobertura"))
+        return "cobertura";
+    return "istanbul";
+}
+function parseIstanbul(reportPath) {
+    const raw = JSON.parse(fs.readFileSync(reportPath, "utf8"));
+    const results = [];
+    for (const [file, data] of Object.entries(raw)) {
+        if (file === "total")
+            continue;
+        const d = data;
+        results.push({
+            file: normalizeFile(file),
+            lineCoverage: (d.lines?.pct ?? 0) / 100,
+            branchCoverage: d.branches ? d.branches.pct / 100 : undefined,
+            functionCoverage: d.functions ? d.functions.pct / 100 : undefined,
+            lines: d.lines?.total,
+            coveredLines: d.lines?.covered,
+        });
+    }
+    return results;
+}
+// ─── lcov parser ─────────────────────────────────────────────────────────────
+function parseLcov(reportPath) {
+    const text = fs.readFileSync(reportPath, "utf8");
+    const results = [];
+    let file = "";
+    let linesFound = 0, linesHit = 0, branchFound = 0, branchHit = 0;
+    for (const line of text.split("\n")) {
+        const l = line.trim();
+        if (l.startsWith("SF:")) {
+            file = normalizeFile(l.slice(3));
+        }
+        else if (l.startsWith("LF:")) {
+            linesFound = parseInt(l.slice(3), 10) || 0;
+        }
+        else if (l.startsWith("LH:")) {
+            linesHit = parseInt(l.slice(3), 10) || 0;
+        }
+        else if (l.startsWith("BRF:")) {
+            branchFound = parseInt(l.slice(4), 10) || 0;
+        }
+        else if (l.startsWith("BRH:")) {
+            branchHit = parseInt(l.slice(4), 10) || 0;
+        }
+        else if (l === "end_of_record" && file) {
+            results.push({
+                file,
+                lineCoverage: linesFound > 0 ? linesHit / linesFound : 0,
+                branchCoverage: branchFound > 0 ? branchHit / branchFound : undefined,
+                lines: linesFound,
+                coveredLines: linesHit,
+            });
+            file = "";
+            linesFound = 0;
+            linesHit = 0;
+            branchFound = 0;
+            branchHit = 0;
+        }
+    }
+    return results;
+}
+// ─── Cobertura / Clover XML parser (minimal) ──────────────────────────────────
+function parseXmlCoverage(reportPath) {
+    const text = fs.readFileSync(reportPath, "utf8");
+    const results = [];
+    // Match <class filename="..." line-rate="..." branch-rate="...">
+    const classRe = /(?:filename|name)="([^"]+)"[^>]*(?:line-rate|lineRate)="([^"]+)"(?:[^>]*(?:branch-rate|branchRate)="([^"]+)")?/g;
+    let m;
+    while ((m = classRe.exec(text)) !== null) {
+        results.push({
+            file: normalizeFile(m[1]),
+            lineCoverage: parseFloat(m[2]) || 0,
+            branchCoverage: m[3] ? parseFloat(m[3]) : undefined,
+        });
+    }
+    return results;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function normalizeFile(f) {
+    return f.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function parseReport(reportPath, format) {
+    const effectiveFormat = format === "auto" ? detectFormat(reportPath) : format;
+    if (effectiveFormat === "lcov")
+        return parseLcov(reportPath);
+    if (effectiveFormat === "clover" || effectiveFormat === "cobertura")
+        return parseXmlCoverage(reportPath);
+    return parseIstanbul(reportPath);
+}
+// ─── Merge ────────────────────────────────────────────────────────────────────
+export function mergeCoverage(reportPath, structuralMap, root, format = "auto") {
+    const actual = parseReport(reportPath, format === "auto" ? detectFormat(reportPath) : format);
+    const effectiveFormat = format === "auto" ? detectFormat(reportPath) : format;
+    // Index actual by normalised file path
+    const actualByFile = new Map();
+    for (const fc of actual) {
+        // Try multiple key forms: absolute, root-relative, basename
+        actualByFile.set(fc.file, fc);
+        actualByFile.set(path.relative(root, fc.file).replace(/\\/g, "/"), fc);
+        actualByFile.set(path.basename(fc.file), fc);
+    }
+    const testedSet = new Set(structuralMap.tested.map((f) => f.file));
+    const untestedSet = new Set(structuralMap.untested.map((f) => f.file));
+    const enriched = [];
+    const deadTests = [];
+    const uncovered = [];
+    for (const src of structuralMap.tested) {
+        const fc = actualByFile.get(src.file)
+            ?? actualByFile.get(path.relative(root, src.file))
+            ?? actualByFile.get(path.basename(src.file));
+        const lineCov = fc?.lineCoverage ?? 0;
+        if (lineCov === 0 && fc)
+            deadTests.push(src.file);
+        enriched.push({
+            file: src.file,
+            hasTests: true,
+            lineCoverage: lineCov,
+            branchCoverage: fc?.branchCoverage,
+        });
+    }
+    for (const src of structuralMap.untested) {
+        const fc = actualByFile.get(src.file)
+            ?? actualByFile.get(path.relative(root, src.file))
+            ?? actualByFile.get(path.basename(src.file));
+        enriched.push({
+            file: src.file,
+            hasTests: false,
+            lineCoverage: fc?.lineCoverage ?? 0,
+            branchCoverage: fc?.branchCoverage,
+        });
+        if (!fc || fc.lineCoverage === 0)
+            uncovered.push(src.file);
+    }
+    const totalLines = actual.reduce((s, f) => s + (f.lineCoverage ?? 0), 0);
+    const avgLineCoverage = actual.length > 0 ? totalLines / actual.length : 0;
+    const branchEntries = actual.filter((f) => f.branchCoverage !== undefined);
+    const avgBranchCoverage = branchEntries.length > 0
+        ? branchEntries.reduce((s, f) => s + (f.branchCoverage ?? 0), 0) / branchEntries.length
+        : undefined;
+    return {
+        format: effectiveFormat,
+        reportPath,
+        actual,
+        summary: {
+            totalFiles: actual.length,
+            coveredFiles: actual.filter((f) => f.lineCoverage > 0).length,
+            avgLineCoverage,
+            avgBranchCoverage,
+        },
+        enriched,
+        deadTests,
+        uncovered,
+    };
+}