universal-ast-mapper 0.5.2

package/dist/extractors/typescript.js

@@ -0,0 +1,320 @@
+import { namedChildren, nameOf, headerSignature, leadingComment } from "../parser.js";
+import { makeSymbol } from "./common.js";
+/**
+ * Extract "use client" / "use server" directives from the top of a TS/TSX/JS file.
+ * Directives are string-literal expression statements that appear before any other code.
+ */
+export function extractDirectivesTS(root, _source) {
+    const directives = [];
+    for (const child of namedChildren(root)) {
+        if (child.type !== "expression_statement")
+            break;
+        const expr = child.namedChild(0);
+        if (!expr || expr.type !== "string")
+            break;
+        const val = expr.text.replace(/^['"`]|['"`]$/g, "");
+        if (val === "use client" || val === "use server") {
+            directives.push(val);
+        }
+        else {
+            break;
+        }
+    }
+    return directives;
+}
+/**
+ * Extractor shared by TypeScript, TSX and JavaScript.
+ * TS-only node types (interface/type/enum) simply never appear in JS sources.
+ */
+export function extractTypeScript(root, _source) {
+    return collect(namedChildren(root), false);
+}
+function collect(nodes, exported) {
+    const out = [];
+    for (const n of nodes) {
+        const res = handle(n, exported);
+        if (Array.isArray(res))
+            out.push(...res);
+        else if (res)
+            out.push(res);
+    }
+    return out;
+}
+function handle(node, exported) {
+    switch (node.type) {
+        case "export_statement":
+            // `export <decl>` / `export default <decl>` — mark the inner declarations exported.
+            return collect(namedChildren(node), true);
+        case "class_declaration":
+        case "abstract_class_declaration": {
+            const name = nameOf(node) ?? "(anonymous class)";
+            const body = node.childForFieldName("body");
+            const children = body ? collect(namedChildren(body), false) : [];
+            return makeSymbol({
+                name,
+                kind: "class",
+                node,
+                rawKind: node.type,
+                exported,
+                doc: leadingComment(node),
+                children,
+            });
+        }
+        case "interface_declaration": {
+            const name = nameOf(node) ?? "(anonymous interface)";
+            const body = node.childForFieldName("body");
+            const children = body ? collect(namedChildren(body), false) : [];
+            return makeSymbol({
+                name,
+                kind: "interface",
+                node,
+                rawKind: node.type,
+                exported,
+                doc: leadingComment(node),
+                children,
+            });
+        }
+        case "function_declaration":
+        case "generator_function_declaration": {
+            const name = nameOf(node) ?? "(anonymous function)";
+            const body = node.childForFieldName("body");
+            return makeSymbol({
+                name,
+                kind: "function",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                exported,
+                doc: leadingComment(node),
+            });
+        }
+        case "type_alias_declaration":
+            return makeSymbol({
+                name: nameOf(node) ?? "(type)",
+                kind: "type",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, null),
+                exported,
+                doc: leadingComment(node),
+            });
+        case "enum_declaration":
+            return makeSymbol({
+                name: nameOf(node) ?? "(enum)",
+                kind: "enum",
+                node,
+                rawKind: node.type,
+                exported,
+                doc: leadingComment(node),
+            });
+        case "lexical_declaration":
+        case "variable_declaration":
+            return fromVariableDeclaration(node, exported);
+        case "method_definition":
+        case "method_signature":
+        case "abstract_method_signature": {
+            const name = nameOf(node) ?? "(method)";
+            const body = node.childForFieldName("body");
+            return makeSymbol({
+                name,
+                kind: "method",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                visibility: memberVisibility(node),
+                doc: leadingComment(node),
+            });
+        }
+        case "public_field_definition":
+        case "field_definition": {
+            // Only surface fields that hold an arrow/function (i.e. behave like methods).
+            const value = node.childForFieldName("value");
+            if (value && (value.type === "arrow_function" || value.type === "function" || value.type === "function_expression")) {
+                const name = nameOf(node) ?? "(method)";
+                const body = value.childForFieldName("body");
+                return makeSymbol({
+                    name,
+                    kind: "method",
+                    node,
+                    rawKind: node.type,
+                    signature: headerSignature(node, body),
+                    visibility: memberVisibility(node),
+                    doc: leadingComment(node),
+                });
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+function fromVariableDeclaration(node, exported) {
+    const out = [];
+    for (const decl of namedChildren(node)) {
+        if (decl.type !== "variable_declarator")
+            continue;
+        const value = decl.childForFieldName("value");
+        const name = nameOf(decl);
+        if (!name)
+            continue;
+        if (value && (value.type === "arrow_function" || value.type === "function" || value.type === "function_expression")) {
+            const body = value.childForFieldName("body");
+            out.push(makeSymbol({
+                name,
+                kind: "function",
+                node: decl,
+                rawKind: `${node.type}>arrow`,
+                signature: headerSignature(value, body),
+                exported,
+                doc: leadingComment(node),
+            }));
+        }
+        else if (value && (value.type === "class_expression" || value.type === "class")) {
+            // const MyClass = class { ... }
+            const body = value.childForFieldName("body");
+            const children = body ? collect(namedChildren(body), false) : [];
+            out.push(makeSymbol({
+                name,
+                kind: "class",
+                node: decl,
+                rawKind: `${node.type}>class`,
+                exported,
+                doc: leadingComment(node),
+                children,
+            }));
+        }
+        else if (exported && value) {
+            // export const FOO = <any non-function value> — track for dead code detection
+            out.push(makeSymbol({
+                name,
+                kind: "const",
+                node: decl,
+                rawKind: `${node.type}>const`,
+                signature: decl.text.replace(/\s+/g, " ").trim().slice(0, 120),
+                exported: true,
+                doc: leadingComment(node),
+            }));
+        }
+    }
+    return out;
+}
+// ─── Import extraction ────────────────────────────────────────────────────────
+export function extractImportsTS(root, _source) {
+    const imports = [];
+    for (const child of namedChildren(root)) {
+        if (child.type === "import_statement")
+            parseImportStatement(child, imports);
+        // Re-exports: `export { X } from './foo'` or `export * from './foo'`
+        else if (child.type === "export_statement")
+            parseReExportStatement(child, imports);
+    }
+    return imports;
+}
+function parseReExportStatement(node, out) {
+    const source = extractModulePath(node.text);
+    if (!source)
+        return; // no `from` clause — local re-export, not an import
+    const isTypeOnly = /^export\s+type\b/.test(node.text);
+    // export * from './foo'  or  export * as Foo from './foo'
+    if (/^export\s+\*/.test(node.text)) {
+        out.push({ symbol: "*", from: source, isNamespaceImport: true });
+        return;
+    }
+    // export { X, Y as Z } from './foo'
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (!c || c.type !== "export_clause")
+            continue;
+        for (let j = 0; j < c.namedChildCount; j++) {
+            const spec = c.namedChild(j);
+            if (!spec || spec.type !== "export_specifier")
+                continue;
+            const nameNode = spec.childForFieldName("name");
+            const aliasNode = spec.childForFieldName("alias");
+            if (nameNode) {
+                const imp = { symbol: nameNode.text, from: source };
+                if (aliasNode)
+                    imp.alias = aliasNode.text;
+                if (isTypeOnly)
+                    imp.isTypeOnly = true;
+                out.push(imp);
+            }
+        }
+    }
+}
+function parseImportStatement(node, out) {
+    const isTypeOnly = /^import\s+type\b/.test(node.text);
+    const from = extractModulePath(node.text);
+    if (!from)
+        return;
+    let clauseNode = null;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c && c.type === "import_clause") {
+            clauseNode = c;
+            break;
+        }
+    }
+    if (!clauseNode) {
+        out.push({ symbol: "*", from, isSideEffect: true });
+        return;
+    }
+    for (let i = 0; i < clauseNode.namedChildCount; i++) {
+        const c = clauseNode.namedChild(i);
+        if (!c)
+            continue;
+        if (c.type === "identifier") {
+            const imp = { symbol: c.text, from, isDefault: true };
+            if (isTypeOnly)
+                imp.isTypeOnly = true;
+            out.push(imp);
+        }
+        else if (c.type === "namespace_import") {
+            const id = c.namedChild(0);
+            if (id) {
+                const imp = { symbol: id.text, from, isNamespaceImport: true };
+                if (isTypeOnly)
+                    imp.isTypeOnly = true;
+                out.push(imp);
+            }
+        }
+        else if (c.type === "named_imports") {
+            for (let j = 0; j < c.namedChildCount; j++) {
+                const spec = c.namedChild(j);
+                if (!spec || spec.type !== "import_specifier")
+                    continue;
+                const nameNode = spec.childForFieldName("name");
+                const aliasNode = spec.childForFieldName("alias");
+                if (nameNode) {
+                    const imp = { symbol: nameNode.text, from };
+                    if (aliasNode)
+                        imp.alias = aliasNode.text;
+                    if (isTypeOnly)
+                        imp.isTypeOnly = true;
+                    out.push(imp);
+                }
+            }
+        }
+    }
+}
+function extractModulePath(importText) {
+    const m = importText.match(/from\s+['"`]([^'"`\n]+)['"`]/);
+    if (m)
+        return m[1];
+    const m2 = importText.match(/^import\s+(?:type\s+)?['"`]([^'"`\n]+)['"`]/);
+    return m2 ? m2[1] : null;
+}
+// ─── Member visibility ────────────────────────────────────────────────────────
+function memberVisibility(node) {
+    for (let i = 0; i < node.childCount; i++) {
+        const c = node.child(i);
+        if (c && c.type === "accessibility_modifier") {
+            return c.text === "private" || c.text === "protected" ? "private" : "public";
+        }
+    }
+    // `#name` ES private fields/methods
+    const name = node.childForFieldName("name");
+    if (name && name.type === "private_property_identifier")
+        return "private";
+    return "public";
+}

package/dist/graph-analysis.js

@@ -0,0 +1,243 @@
+// ─── Dead Code Detection ──────────────────────────────────────────────────────
+/**
+ * "High" confidence = functions / classes / consts that are unlikely to be
+ * used purely as type annotations.
+ * "Low" confidence = interfaces / types / enums — these are often imported
+ * implicitly through the TypeScript type system without an explicit import
+ * statement, so they may appear "dead" even when they're actively used.
+ */
+const HIGH_CONFIDENCE_KINDS = new Set(["function", "class", "const", "var", "method"]);
+/**
+ * Return exported symbols that have no incoming "imports" edges within the
+ * scanned directory — i.e. nothing inside the scan root depends on them.
+ */
+export function findDeadExports(graph) {
+    const importedIds = new Set();
+    for (const edge of graph.edges) {
+        if (edge.edgeType === "imports")
+            importedIds.add(edge.to);
+    }
+    const dead = [];
+    for (const node of graph.nodes) {
+        if (node.nodeType !== "symbol")
+            continue;
+        const sym = node;
+        if (sym.exported && !importedIds.has(sym.id)) {
+            dead.push({
+                file: sym.file,
+                symbol: sym.symbol,
+                kind: sym.kind,
+                nodeId: sym.id,
+                confidence: HIGH_CONFIDENCE_KINDS.has(sym.kind) ? "high" : "low",
+            });
+        }
+    }
+    return dead;
+}
+/**
+ * Detect circular import dependencies among the scanned files using DFS.
+ * Each reported cycle is canonicalised (rotated to start at the
+ * lexicographically smallest node) to avoid duplicates.
+ *
+ * Re-uses the graph's already-resolved import edges — no path re-resolution needed.
+ */
+export function findCircularDeps(graph) {
+    const nodeMap = new Map(graph.nodes.map(n => [n.id, n]));
+    // Build deduplicated file-level adjacency from the graph's "imports" edges
+    const adjSets = new Map();
+    for (const node of graph.nodes) {
+        if (node.nodeType === "file")
+            adjSets.set(node.id, new Set());
+    }
+    for (const edge of graph.edges) {
+        if (edge.edgeType !== "imports")
+            continue;
+        const toNode = nodeMap.get(edge.to);
+        if (!toNode)
+            continue;
+        const toFile = toNode.nodeType === "file" ? toNode.id : toNode.file;
+        if (edge.from !== toFile)
+            adjSets.get(edge.from)?.add(toFile);
+    }
+    const adj = new Map();
+    for (const [k, v] of adjSets)
+        adj.set(k, [...v]);
+    const color = new Map();
+    for (const f of adj.keys())
+        color.set(f, "white");
+    const cycles = [];
+    const cycleKeys = new Set();
+    for (const startNode of adj.keys()) {
+        if (color.get(startNode) !== "white")
+            continue;
+        const stack = [{ node: startNode, nextIdx: 0 }];
+        const path = [startNode];
+        color.set(startNode, "gray");
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = adj.get(frame.node) ?? [];
+            if (frame.nextIdx >= neighbors.length) {
+                stack.pop();
+                path.pop();
+                color.set(frame.node, "black");
+                continue;
+            }
+            const neighbor = neighbors[frame.nextIdx++];
+            const nc = color.get(neighbor);
+            if (nc === "gray") {
+                const start = path.indexOf(neighbor);
+                const raw = path.slice(start);
+                const canonical = rotateCycle(raw);
+                const key = canonical.join("→");
+                if (!cycleKeys.has(key)) {
+                    cycleKeys.add(key);
+                    cycles.push({ cycle: [...canonical, canonical[0]], length: canonical.length });
+                }
+            }
+            else if (nc === "white") {
+                color.set(neighbor, "gray");
+                path.push(neighbor);
+                stack.push({ node: neighbor, nextIdx: 0 });
+            }
+        }
+    }
+    return cycles;
+}
+function rotateCycle(nodes) {
+    const minIdx = nodes.reduce((best, n, i) => (n < nodes[best] ? i : best), 0);
+    return [...nodes.slice(minIdx), ...nodes.slice(0, minIdx)];
+}
+/**
+ * Compute the blast radius of changing a symbol: traverse the import graph in
+ * reverse to find every file/symbol that directly or transitively depends on
+ * the given node ID.
+ *
+ * Returns null if the target node ID is not found in the graph.
+ */
+export function getChangeImpact(graph, targetNodeId) {
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    if (!nodeMap.has(targetNodeId))
+        return null;
+    // Reverse adjacency: target → [nodes that import it]
+    const reverseAdj = new Map();
+    for (const edge of graph.edges) {
+        if (edge.edgeType === "imports") {
+            if (!reverseAdj.has(edge.to))
+                reverseAdj.set(edge.to, new Set());
+            reverseAdj.get(edge.to).add(edge.from);
+        }
+    }
+    const visited = new Set([targetNodeId]);
+    const directSet = new Set();
+    for (const dep of reverseAdj.get(targetNodeId) ?? []) {
+        if (!visited.has(dep)) {
+            visited.add(dep);
+            directSet.add(dep);
+        }
+    }
+    const transitiveSet = new Set();
+    const queue = [...directSet];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const dep of reverseAdj.get(current) ?? []) {
+            if (!visited.has(dep)) {
+                visited.add(dep);
+                transitiveSet.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    function toImpactNode(id) {
+        const n = nodeMap.get(id);
+        if (!n)
+            return { nodeId: id, file: id };
+        if (n.nodeType === "file")
+            return { nodeId: id, file: n.id };
+        const sym = n;
+        return { nodeId: id, file: sym.file, symbol: sym.symbol };
+    }
+    const direct = [...directSet].map(toImpactNode);
+    const transitive = [...transitiveSet].map(toImpactNode);
+    const allFiles = new Set([...direct.map((e) => e.file), ...transitive.map((e) => e.file)]);
+    return { targetNodeId, direct, transitive, totalFiles: allFiles.size };
+}
+/**
+ * Show the import relationships for a single file:
+ *   - `imports`    — what this file pulls in (outgoing edges)
+ *   - `importedBy` — who depends on this file (incoming edges)
+ *
+ * Returns null if the file node is not in the graph.
+ */
+export function getFileDeps(graph, fileId) {
+    if (!graph.nodes.some((n) => n.id === fileId && n.nodeType === "file"))
+        return null;
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    // fileId → set of imported symbol names
+    const outgoing = new Map();
+    // fileId → set of symbols they import from us
+    const incoming = new Map();
+    for (const edge of graph.edges) {
+        if (edge.edgeType !== "imports")
+            continue;
+        const toNode = nodeMap.get(edge.to);
+        if (!toNode)
+            continue;
+        const toFile = toNode.nodeType === "file"
+            ? toNode.id
+            : toNode.file;
+        const symbolName = toNode.nodeType === "symbol"
+            ? toNode.symbol
+            : null;
+        if (edge.from === fileId && toFile !== fileId) {
+            if (!outgoing.has(toFile))
+                outgoing.set(toFile, new Set());
+            if (symbolName)
+                outgoing.get(toFile).add(symbolName);
+        }
+        if (toFile === fileId && edge.from !== fileId) {
+            if (!incoming.has(edge.from))
+                incoming.set(edge.from, new Set());
+            if (symbolName)
+                incoming.get(edge.from).add(symbolName);
+        }
+    }
+    return {
+        file: fileId,
+        imports: [...outgoing.entries()].map(([file, syms]) => ({ file, symbols: [...syms].sort() })),
+        importedBy: [...incoming.entries()].map(([file, syms]) => ({ file, symbols: [...syms].sort() })),
+    };
+}
+/**
+ * Return the most-imported symbols in the graph, sorted descending by
+ * the number of distinct files that depend on them. These are "God Nodes" —
+ * high-risk symbols where a breaking change has maximum blast radius.
+ */
+export function getTopSymbols(graph, limit = 10) {
+    // nodeId → set of importing file IDs
+    const importers = new Map();
+    for (const edge of graph.edges) {
+        if (edge.edgeType !== "imports")
+            continue;
+        if (!importers.has(edge.to))
+            importers.set(edge.to, new Set());
+        importers.get(edge.to).add(edge.from);
+    }
+    const results = [];
+    for (const node of graph.nodes) {
+        if (node.nodeType !== "symbol")
+            continue;
+        const sym = node;
+        const fileImporters = importers.get(sym.id);
+        if (!fileImporters || fileImporters.size === 0)
+            continue;
+        results.push({
+            nodeId: sym.id,
+            file: sym.file,
+            symbol: sym.symbol,
+            kind: sym.kind,
+            importCount: fileImporters.size,
+            importedByFiles: [...fileImporters].sort(),
+        });
+    }
+    return results.sort((a, b) => b.importCount - a.importCount).slice(0, limit);
+}

package/dist/graph.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { resolveImportPath } from "./resolver.js";
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function collectSymbolNodes(symbols, parentId, file, nodes, edges) {
+    for (const sym of symbols) {
+        // Nested symbols use dot-notation: "src/foo.ts::MyClass.methodName"
+        const nodeId = `${parentId}.${sym.name}`;
+        nodes.push({
+            id: nodeId,
+            nodeType: "symbol",
+            file,
+            symbol: sym.name,
+            kind: sym.kind,
+            exported: sym.exported ?? false,
+            range: sym.range,
+            ...(sym.signature ? { signature: sym.signature } : {}),
+        });
+        edges.push({ from: parentId, to: nodeId, edgeType: "contains" });
+        if (sym.children.length > 0) {
+            collectSymbolNodes(sym.children, nodeId, file, nodes, edges);
+        }
+    }
+}
+// ─── Public builder ──────────────────────────────────────────────────────────
+/**
+ * Build a symbol-level dependency graph from an array of pre-parsed skeletons.
+ *
+ * Node IDs:
+ *   - File node:   "<relPath>"                       e.g. "src/utils.ts"
+ *   - Top symbol:  "<relPath>::<Name>"               e.g. "src/utils.ts::sanitize"
+ *   - Nested:      "<relPath>::<Parent>.<Child>"     e.g. "src/utils.ts::MyClass.render"
+ *
+ * Edge types:
+ *   - "contains"  file → symbol (and parent-symbol → child-symbol)
+ *   - "imports"   importing-file → imported-symbol-node
+ */
+export function buildSymbolGraph(skeletons, root) {
+    const nodes = [];
+    const edges = [];
+    // exportedSymbolMap: relFile → (symbolName → nodeId)
+    // Used in the second pass to resolve import targets.
+    const exportedSymbolMap = new Map();
+    // ── First pass: build all file + symbol nodes ────────────────────────────
+    for (const skel of skeletons) {
+        // File node
+        nodes.push({
+            id: skel.file,
+            nodeType: "file",
+            language: skel.language,
+            symbolCount: skel.symbolCount,
+        });
+        const fileExports = new Map();
+        exportedSymbolMap.set(skel.file, fileExports);
+        for (const sym of skel.symbols) {
+            const nodeId = `${skel.file}::${sym.name}`;
+            nodes.push({
+                id: nodeId,
+                nodeType: "symbol",
+                file: skel.file,
+                symbol: sym.name,
+                kind: sym.kind,
+                exported: sym.exported ?? false,
+                range: sym.range,
+                ...(sym.signature ? { signature: sym.signature } : {}),
+            });
+            edges.push({ from: skel.file, to: nodeId, edgeType: "contains" });
+            if (sym.exported)
+                fileExports.set(sym.name, nodeId);
+            // Collect nested symbols
+            if (sym.children.length > 0) {
+                const childNodes = [];
+                const childEdges = [];
+                collectSymbolNodes(sym.children, nodeId, skel.file, childNodes, childEdges);
+                nodes.push(...childNodes);
+                edges.push(...childEdges);
+            }
+        }
+    }
+    // ── Second pass: wire import edges ───────────────────────────────────────
+    for (const skel of skeletons) {
+        if (!skel.imports || skel.imports.length === 0)
+            continue;
+        const fromFileAbs = path.resolve(root, skel.file);
+        for (const imp of skel.imports) {
+            if (!imp.from.startsWith("."))
+                continue; // skip external packages
+            if (imp.isSideEffect)
+                continue;
+            const resolvedAbs = resolveImportPath(imp.from, fromFileAbs);
+            if (!resolvedAbs)
+                continue;
+            const resolvedRel = path.relative(root, resolvedAbs).split(path.sep).join("/");
+            if (imp.isNamespaceImport || imp.symbol === "*") {
+                // Namespace import — link to the file node itself
+                if (exportedSymbolMap.has(resolvedRel)) {
+                    edges.push({ from: skel.file, to: resolvedRel, edgeType: "imports" });
+                }
+            }
+            else {
+                const fileExports = exportedSymbolMap.get(resolvedRel);
+                const targetNodeId = fileExports?.get(imp.symbol);
+                if (targetNodeId) {
+                    edges.push({ from: skel.file, to: targetNodeId, edgeType: "imports" });
+                }
+            }
+        }
+    }
+    const symbolNodeCount = nodes.filter((n) => n.nodeType === "symbol").length;
+    return {
+        nodes,
+        edges,
+        stats: {
+            fileCount: skeletons.length,
+            symbolNodeCount,
+            edgeCount: edges.length,
+        },
+    };
+}