universal-ast-mapper 1.28.0 → 2.0.1

package/dist/serve.js

@@ -0,0 +1,185 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { collectSourceFiles } from "./skeleton.js";
+import { resolveOptions } from "./config.js";
+import { buildSymbolGraph } from "./graph.js";
+import { findDeadExports, findCircularDeps, getTopSymbols } from "./graph-analysis.js";
+import { buildReport } from "./report.js";
+import { loadHistory } from "./history.js";
+import { detectSmells } from "./smells.js";
+import { scanFileForSecurityIssues } from "./security.js";
+import { buildSkeletonsBulk } from "./pool.js";
+import { webAppHtml } from "./webapp.js";
+export async function startServe(opts) {
+    const root = opts.root;
+    const scanDir = opts.scanDir ?? root;
+    const port = opts.port ?? 7337;
+    // SSE client registry
+    const sseClients = new Set();
+    function broadcastChange() {
+        for (const client of sseClients) {
+            try {
+                client.write("event: change\ndata: {}\n\n");
+            }
+            catch {
+                sseClients.delete(client);
+            }
+        }
+    }
+    // fs.watch for live reload
+    if (opts.watch) {
+        try {
+            fs.watch(scanDir, { recursive: true }, (_event, filename) => {
+                if (!filename || filename.includes(".ast-map"))
+                    return;
+                cache = null;
+                broadcastChange();
+            });
+        }
+        catch { /* watch not supported on all platforms */ }
+    }
+    let cache = null;
+    const CACHE_TTL = 5000;
+    async function getSkeletons() {
+        if (cache && Date.now() - cache.ts < CACHE_TTL)
+            return cache.skeletons;
+        const skOpts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(scanDir, skOpts);
+        const items = files.map((f) => ({
+            abs: f,
+            rel: path.relative(root, f).split(path.sep).join("/"),
+        }));
+        const built = await buildSkeletonsBulk(items, skOpts);
+        const skeletons = built.filter(Boolean).map((r) => r.skel);
+        cache = { skeletons, ts: Date.now() };
+        return skeletons;
+    }
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+        const pathname = url.pathname;
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+        try {
+            if (pathname === "/" || pathname === "/index.html") {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(webAppHtml(port));
+                return;
+            }
+            if (pathname === "/api/report") {
+                const skeletons = await getSkeletons();
+                const graph = buildSymbolGraph(skeletons, root);
+                const history = loadHistory(root);
+                const report = await buildReport(scanDir, root);
+                const smellsAll = [];
+                const securityAll = [];
+                for (const skel of skeletons) {
+                    const fileAbs = path.resolve(root, skel.file);
+                    try {
+                        const src = fs.readFileSync(fileAbs, "utf8");
+                        smellsAll.push(...detectSmells(skel, src.split("\n").length));
+                        securityAll.push(...scanFileForSecurityIssues(src, skel.file));
+                    }
+                    catch { /* skip */ }
+                }
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ ...report, smells: smellsAll, security: securityAll, history }, null, 2));
+                return;
+            }
+            if (pathname === "/api/graph") {
+                const skeletons = await getSkeletons();
+                const graph = buildSymbolGraph(skeletons, root);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(graph, null, 2));
+                return;
+            }
+            if (pathname === "/api/dead") {
+                const skeletons = await getSkeletons();
+                const graph = buildSymbolGraph(skeletons, root);
+                const dead = findDeadExports(graph);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(dead, null, 2));
+                return;
+            }
+            if (pathname === "/api/top") {
+                const skeletons = await getSkeletons();
+                const graph = buildSymbolGraph(skeletons, root);
+                const top = getTopSymbols(graph, 20);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(top, null, 2));
+                return;
+            }
+            if (pathname === "/api/cycles") {
+                const skeletons = await getSkeletons();
+                const graph = buildSymbolGraph(skeletons, root);
+                const cycles = findCircularDeps(graph);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(cycles, null, 2));
+                return;
+            }
+            if (pathname === "/api/history") {
+                const history = loadHistory(root);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(history, null, 2));
+                return;
+            }
+            if (pathname === "/api/skeletons") {
+                const skeletons = await getSkeletons();
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(skeletons, null, 2));
+                return;
+            }
+            if (pathname === "/events") {
+                res.writeHead(200, {
+                    "Content-Type": "text/event-stream",
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                    "Access-Control-Allow-Origin": "*",
+                });
+                res.write("event: connected\ndata: {}\n\n");
+                sseClients.add(res);
+                req.on("close", () => sseClients.delete(res));
+                return;
+            }
+            if (pathname === "/api/smells") {
+                const skeletons = await getSkeletons();
+                const all = [];
+                for (const skel of skeletons) {
+                    const fileAbs = path.resolve(root, skel.file);
+                    try {
+                        const src = fs.readFileSync(fileAbs, "utf8");
+                        all.push(...detectSmells(skel, src.split("\n").length));
+                    }
+                    catch { /* skip */ }
+                }
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(all, null, 2));
+                return;
+            }
+            if (pathname === "/api/security") {
+                const skeletons = await getSkeletons();
+                const all = [];
+                for (const skel of skeletons) {
+                    const fileAbs = path.resolve(root, skel.file);
+                    try {
+                        const src = fs.readFileSync(fileAbs, "utf8");
+                        all.push(...scanFileForSecurityIssues(src, skel.file));
+                    }
+                    catch { /* skip */ }
+                }
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(all, null, 2));
+                return;
+            }
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not found");
+        }
+        catch (e) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+        }
+    });
+    return new Promise((resolve) => {
+        server.listen(port, () => resolve(server));
+    });
+}

package/dist/similar.js

@@ -0,0 +1,98 @@
+// ─── Fingerprinting ────────────────────────────────────────────────────────────
+/**
+ * Build a structural fingerprint for a symbol.
+ * Two symbols with the same fingerprint are structurally similar (not textually identical).
+ */
+function fingerprint(sym) {
+    const kind = sym.kind;
+    if (!["function", "method", "class", "struct"].includes(kind))
+        return null;
+    const sig = sym.signature ?? "";
+    // Param count from signature
+    const paramMatch = sig.match(/\(([^)]*)\)/);
+    const paramStr = paramMatch?.[1]?.trim() ?? "";
+    const paramCount = paramStr === "" ? 0 : paramStr.split(",").length;
+    // Presence of return type annotation
+    const hasReturnType = sig.includes("): ") || sig.includes(") :") || sig.includes("->");
+    // Async?
+    const isAsync = sig.includes("async ") || sig.includes("suspend ") || sig.includes("async def ");
+    // Visibility
+    const visibility = sym.visibility;
+    // Child count bucket for classes
+    const childCount = sym.children.length;
+    const childBucket = childCount === 0 ? "0" : childCount <= 3 ? "1-3" : childCount <= 8 ? "4-8" : "9+";
+    // Line length bucket
+    const lineCount = sym.range.endLine - sym.range.startLine + 1;
+    const sizeBucket = lineCount <= 5 ? "xs" : lineCount <= 20 ? "sm" : lineCount <= 60 ? "md" : "lg";
+    // Has nested functions?
+    const hasNested = sym.children.some((c) => c.kind === "function" || c.kind === "method");
+    if (kind === "class" || kind === "struct") {
+        return `${kind}|children:${childBucket}|vis:${visibility}|size:${sizeBucket}`;
+    }
+    return `${kind}|params:${paramCount}|async:${isAsync}|ret:${hasReturnType}|vis:${visibility}|size:${sizeBucket}|nested:${hasNested}`;
+}
+// ─── Collector ────────────────────────────────────────────────────────────────
+function collect(symbols, file, kinds, out) {
+    for (const sym of symbols) {
+        if (kinds.has(sym.kind)) {
+            const fp = fingerprint(sym);
+            if (fp) {
+                out.push({
+                    file,
+                    symbol: sym.name,
+                    kind: sym.kind,
+                    line: sym.range.startLine,
+                    signature: sym.signature,
+                    fingerprint: fp,
+                });
+            }
+        }
+        if (sym.children.length > 0)
+            collect(sym.children, file, kinds, out);
+    }
+}
+// ─── Human-readable description ───────────────────────────────────────────────
+function describeFingerprint(fp) {
+    const parts = Object.fromEntries(fp.split("|").map((p) => p.split(":")));
+    const kind = fp.split("|")[0];
+    const segments = [`${kind}s`];
+    if (parts.params)
+        segments.push(`${parts.params} param(s)`);
+    if (parts.async === "true")
+        segments.push("async");
+    if (parts.ret === "true")
+        segments.push("typed return");
+    if (parts.children)
+        segments.push(`${parts.children} children`);
+    if (parts.size)
+        segments.push(`size:${parts.size}`);
+    if (parts.vis)
+        segments.push(parts.vis);
+    return segments.join(", ");
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/** Find groups of structurally similar symbols across multiple skeleton files. */
+export function findSimilar(skeletons, opts = {}) {
+    const minGroupSize = opts.minGroupSize ?? 2;
+    const kinds = new Set(opts.kinds ?? ["function", "method", "class", "struct"]);
+    const entries = [];
+    for (const skel of skeletons) {
+        collect(skel.symbols, skel.file, kinds, entries);
+    }
+    // Group by fingerprint
+    const groups = new Map();
+    for (const entry of entries) {
+        const g = groups.get(entry.fingerprint) ?? [];
+        g.push(entry);
+        groups.set(entry.fingerprint, g);
+    }
+    return [...groups.entries()]
+        .filter(([, g]) => g.length >= minGroupSize)
+        .map(([fp, g]) => ({
+        fingerprint: fp,
+        description: describeFingerprint(fp),
+        count: g.length,
+        entries: g.sort((a, b) => a.file.localeCompare(b.file) || a.symbol.localeCompare(b.symbol)),
+    }))
+        .sort((a, b) => b.count - a.count);
+}

package/dist/smells.js

@@ -0,0 +1,285 @@
+// ─── Parameter counting ───────────────────────────────────────────────────────
+/**
+ * Count the number of parameters in a signature string by finding the first
+ * `(...)` group and splitting by comma. Handles `...rest` as 1 param.
+ * Returns -1 when no parameter list can be found.
+ */
+function countParams(signature) {
+    if (!signature)
+        return -1;
+    // Find the first balanced parenthesis group
+    const start = signature.indexOf("(");
+    if (start === -1)
+        return -1;
+    let depth = 0;
+    let end = -1;
+    for (let i = start; i < signature.length; i++) {
+        if (signature[i] === "(")
+            depth++;
+        else if (signature[i] === ")") {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end === -1)
+        return -1;
+    const inner = signature.slice(start + 1, end).trim();
+    if (inner === "")
+        return 0;
+    // Split by top-level commas only (ignore generics / nested parens)
+    const parts = [];
+    let buf = "";
+    let nested = 0;
+    for (const ch of inner) {
+        if (ch === "(" || ch === "<" || ch === "[" || ch === "{") {
+            nested++;
+            buf += ch;
+        }
+        else if (ch === ")" || ch === ">" || ch === "]" || ch === "}") {
+            nested--;
+            buf += ch;
+        }
+        else if (ch === "," && nested === 0) {
+            parts.push(buf.trim());
+            buf = "";
+        }
+        else {
+            buf += ch;
+        }
+    }
+    if (buf.trim())
+        parts.push(buf.trim());
+    // Filter out empty strings and `this` parameters
+    const filtered = parts.filter((p) => p.length > 0 && p !== "this" && !p.startsWith("this:"));
+    return filtered.length;
+}
+/**
+ * Determine whether a signature's parameter list consists exclusively of
+ * primitive types (string, number, boolean). Returns true only when there are
+ * more than 3 params AND every param type annotation is a primitive (or a
+ * union of primitives).
+ */
+function isPrimitiveObsession(signature, paramCount) {
+    if (!signature || paramCount <= 3)
+        return false;
+    const start = signature.indexOf("(");
+    if (start === -1)
+        return false;
+    let depth = 0;
+    let end = -1;
+    for (let i = start; i < signature.length; i++) {
+        if (signature[i] === "(")
+            depth++;
+        else if (signature[i] === ")") {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end === -1)
+        return false;
+    const inner = signature.slice(start + 1, end).trim();
+    if (!inner)
+        return false;
+    // Remove `this` param
+    const withoutThis = inner.replace(/^this\s*:[^,]+,?\s*/, "");
+    // Strip parameter names — keep only the type annotation portion
+    // Handles: `name: type`, `name?: type`, `...rest: type`
+    // We check the extracted type annotations against known primitives
+    const PRIMITIVE_RE = /^(string|number|boolean)(\s*\|\s*(string|number|boolean))*(\[\])?(\s*\|\s*null|\s*\|\s*undefined)*$/;
+    // Extract type annotations: split by top-level comma, then grab the part after `:`
+    const parts = [];
+    let buf = "";
+    let nested2 = 0;
+    for (const ch of withoutThis) {
+        if (ch === "(" || ch === "<" || ch === "[" || ch === "{") {
+            nested2++;
+            buf += ch;
+        }
+        else if (ch === ")" || ch === ">" || ch === "]" || ch === "}") {
+            nested2--;
+            buf += ch;
+        }
+        else if (ch === "," && nested2 === 0) {
+            parts.push(buf.trim());
+            buf = "";
+        }
+        else {
+            buf += ch;
+        }
+    }
+    if (buf.trim())
+        parts.push(buf.trim());
+    const meaningful = parts.filter((p) => p.length > 0 && p !== "this" && !p.startsWith("this:"));
+    if (meaningful.length === 0)
+        return false;
+    for (const param of meaningful) {
+        // Strip leading `...` for rest params
+        const stripped = param.replace(/^\.\.\./, "");
+        // Get the type annotation after `:`
+        const colonIdx = stripped.indexOf(":");
+        if (colonIdx === -1) {
+            // No explicit type — treat as unknown (non-primitive)
+            return false;
+        }
+        const typeAnnotation = stripped.slice(colonIdx + 1).trim().replace(/\s*=\s*.*$/, ""); // remove default value
+        if (!PRIMITIVE_RE.test(typeAnnotation))
+            return false;
+    }
+    return true;
+}
+// ─── Individual smell detectors ───────────────────────────────────────────────
+function checkGodClass(sym, file, maxMethods, maxFields) {
+    if (sym.kind !== "class")
+        return null;
+    const publicMethods = sym.children.filter((c) => (c.kind === "method" || c.kind === "function") && c.visibility === "public");
+    const fields = sym.children.filter((c) => c.kind === "field");
+    if (publicMethods.length > maxMethods) {
+        return {
+            file,
+            smell: "god-class",
+            symbol: sym.name,
+            severity: "warning",
+            message: `Class "${sym.name}" has ${publicMethods.length} public methods (threshold: ${maxMethods})`,
+            line: sym.range.startLine,
+        };
+    }
+    if (fields.length > maxFields) {
+        return {
+            file,
+            smell: "god-class",
+            symbol: sym.name,
+            severity: "warning",
+            message: `Class "${sym.name}" has ${fields.length} fields (threshold: ${maxFields})`,
+            line: sym.range.startLine,
+        };
+    }
+    return null;
+}
+function checkLongMethod(sym, file, maxLines) {
+    if (sym.kind !== "function" && sym.kind !== "method")
+        return null;
+    const length = sym.range.endLine - sym.range.startLine;
+    if (length > maxLines) {
+        return {
+            file,
+            smell: "long-method",
+            symbol: sym.name,
+            severity: "warning",
+            message: `"${sym.name}" is ${length} lines long (threshold: ${maxLines})`,
+            line: sym.range.startLine,
+        };
+    }
+    return null;
+}
+function checkLongParamList(sym, file, maxParams) {
+    if (sym.kind !== "function" && sym.kind !== "method")
+        return null;
+    const count = countParams(sym.signature);
+    if (count > maxParams) {
+        return {
+            file,
+            smell: "long-param-list",
+            symbol: sym.name,
+            severity: "warning",
+            message: `"${sym.name}" has ${count} parameters (threshold: ${maxParams})`,
+            line: sym.range.startLine,
+        };
+    }
+    return null;
+}
+function checkPrimitiveObsession(sym, file) {
+    if (sym.kind !== "function" && sym.kind !== "method")
+        return null;
+    const count = countParams(sym.signature);
+    if (count > 3 && isPrimitiveObsession(sym.signature, count)) {
+        return {
+            file,
+            smell: "primitive-obsession",
+            symbol: sym.name,
+            severity: "info",
+            message: `"${sym.name}" has ${count} parameters all of primitive types — consider a parameter object`,
+            line: sym.range.startLine,
+        };
+    }
+    return null;
+}
+function checkShallowWrapper(sym, file) {
+    if (sym.kind !== "class")
+        return null;
+    const publicMethods = sym.children.filter((c) => (c.kind === "method" || c.kind === "function") && c.visibility === "public");
+    if (publicMethods.length !== 1)
+        return null;
+    const method = publicMethods[0];
+    const methodLines = method.range.endLine - method.range.startLine;
+    if (methodLines <= 5) {
+        return {
+            file,
+            smell: "shallow-wrapper",
+            symbol: sym.name,
+            severity: "info",
+            message: `Class "${sym.name}" has exactly 1 public method "${method.name}" (${methodLines} lines) — may be a thin wrapper`,
+            line: sym.range.startLine,
+        };
+    }
+    return null;
+}
+// ─── Walk helpers ─────────────────────────────────────────────────────────────
+/**
+ * Recursively walk top-level symbols and their children, collecting smells.
+ * `exported` is propagated from the parent class when checking methods.
+ */
+function walkSymbols(symbols, file, maxMethods, maxFields, maxMethodLines, maxParams, results, parentExported) {
+    for (const sym of symbols) {
+        const isExported = sym.exported ?? parentExported;
+        // Only check exported (or publicly accessible) symbols
+        if (isExported || parentExported) {
+            // class-level smells
+            const godClass = checkGodClass(sym, file, maxMethods, maxFields);
+            if (godClass)
+                results.push(godClass);
+            const shallowWrapper = checkShallowWrapper(sym, file);
+            if (shallowWrapper)
+                results.push(shallowWrapper);
+            // function/method smells
+            const longMethod = checkLongMethod(sym, file, maxMethodLines);
+            if (longMethod)
+                results.push(longMethod);
+            const longParam = checkLongParamList(sym, file, maxParams);
+            if (longParam)
+                results.push(longParam);
+            const primitiveObs = checkPrimitiveObsession(sym, file);
+            if (primitiveObs)
+                results.push(primitiveObs);
+        }
+        // Recurse into children (methods inside a class inherit the parent's exported status)
+        if (sym.children.length > 0) {
+            walkSymbols(sym.children, file, maxMethods, maxFields, maxMethodLines, maxParams, results, isExported);
+        }
+    }
+}
+// ─── Main entry ───────────────────────────────────────────────────────────────
+export function detectSmells(skel, sourceLineCount, opts) {
+    const maxMethods = opts?.maxMethods ?? 10;
+    const maxFields = opts?.maxFields ?? 8;
+    const maxMethodLines = opts?.maxMethodLines ?? 60;
+    const maxParams = opts?.maxParams ?? 4;
+    const results = [];
+    // ── large-file ────────────────────────────────────────────────────────────
+    if (sourceLineCount > 500) {
+        results.push({
+            file: skel.file,
+            smell: "large-file",
+            severity: "warning",
+            message: `File has ${sourceLineCount} lines (threshold: 500)`,
+        });
+    }
+    // ── symbol-level smells ───────────────────────────────────────────────────
+    walkSymbols(skel.symbols, skel.file, maxMethods, maxFields, maxMethodLines, maxParams, results, false);
+    return results;
+}