universal-ast-mapper 0.8.2 → 0.8.4

package/README.md

@@ -93,6 +93,7 @@ ast-map graph    <dir>             [-o graph.json]
 ast-map validate <path>            [--max-lines N] [--max-imports N] [--max-exports N]
 ast-map dead     <dir>
 ast-map cycles   <dir>
+ast-map duplicates <dir>           [alias: dupes]
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -260,6 +261,24 @@ Each cycle is canonicalised to avoid duplicates.
 
 ---
 
+### `find_duplicate_symbols`
+Scan a directory → find symbol names exported from **more than one file** (accidental collisions / parallel implementations). Each result lists every file + kind that declares the name.
+
+```json
+{
+  "duplicates": [
+    { "symbol": "validate", "count": 2, "locations": [
+      { "file": "src/a.ts", "kind": "function" },
+      { "file": "src/b.ts", "kind": "function" }
+    ]}
+  ]
+}
+```
+
+**Params:** `path`
+
+---
+
 ### `get_change_impact`
 Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
 
@@ -482,6 +501,8 @@ src/
 
 | Version | What changed |
 |---------|--------------|
+| **0.8.4** | **Duplicate symbol detection** — new `find_duplicate_symbols` MCP tool + `ast-map duplicates` (alias `dupes`) CLI command: finds symbol names exported from more than one file, with every file/kind that declares each name. |
+| **0.8.3** | **TSX/React component props** — component symbols now carry extracted prop fields. PascalCase functions/arrows that return JSX or are typed `React.FC<P>`/`FC<P>` get `propsType` (named props type) + `props[]` (name, type, optional), resolved from same-file `interface`/`type` declarations or inline object types. Plus: MCP server now reports its real version from `package.json` (was hardcoded `0.5.3`). |
 | **0.8.2** | **Swift cross-file wiring** — `import <Module>` resolves to that module's files (module = the `Sources/<Module>/` directory, else parent dir), wired into `build_symbol_graph` + `resolve_imports`. System modules (Foundation, UIKit, …) stay external. Completes cross-file graph/resolver support for all four v0.8.0 languages. |
 | **0.8.1** | **Cross-file graph wiring for Kotlin & C/C++** — Kotlin FQCN/package index + C/C++ `#include` resolution (with header↔impl pairing) wired into `build_symbol_graph`, `resolve_imports`, and `get_call_graph`. Fixes a parse-cache rel-path leak (stale `.file` poisoned the cross-lang index → doubled paths) and Kotlin call-graph extraction (`function_declaration` name + field-less `call_expression`). |
 | **0.8.0** | **4 new languages: C · C++ · Kotlin · Swift** — symbol extraction + imports parsing. C++ tracks access_specifier through class bodies. Kotlin handles `package`/`object`/`data class`. Swift handles `class`/`struct`/`enum` (all under `class_declaration`) and `protocol_declaration`. Ruby grammar in tree-sitter-wasms@0.1.13 is unstable — skipped. |

package/dist/cli.js

@@ -9,7 +9,7 @@ import { supportedLanguages } from "./registry.js";
 import { findSymbol, findRelatedSymbols, findServerImports, isApiRoute, findMissingTryCatch, checkGeneralRules, GENERAL_RULE_DEFAULTS } from "./analysis.js";
 import { resolveFileImports } from "./resolver.js";
 import { buildSymbolGraph } from "./graph.js";
-import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTopSymbols } from "./graph-analysis.js";
+import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTopSymbols, findDuplicateSymbols } from "./graph-analysis.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -366,6 +366,36 @@ program
     }
     console.log();
 });
+// ─── Command: duplicates ──────────────────────────────────────────────────────
+program
+    .command("duplicates <dir>")
+    .alias("dupes")
+    .description("Find symbol names exported from more than one file")
+    .option("--json", "Output as JSON")
+    .action(async (inputPath, opts) => {
+    const { abs, rel } = resolveArg(inputPath);
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const skeletons = await gatherSkeletons(abs);
+    const graph = buildSymbolGraph(skeletons, ROOT);
+    const duplicates = findDuplicateSymbols(graph);
+    if (opts.json)
+        return jsonOut({ directory: rel, scanned: skeletons.length, duplicateCount: duplicates.length, duplicates });
+    header(`Duplicate Symbols — ${rel}/  ${dim(`(${skeletons.length} files scanned)`)}`);
+    if (duplicates.length === 0) {
+        console.log(indent(green("✓ No duplicate exported symbols found.")));
+    }
+    else {
+        for (const d of duplicates) {
+            console.log(indent(`${yellow(d.symbol)} ${dim(`— exported from ${d.count} files`)}`));
+            for (const loc of d.locations) {
+                console.log(indent(`${dim(col(loc.kind, 10))} ${loc.file}`, 5));
+            }
+        }
+        console.log(`\n  ${yellow(`${duplicates.length} duplicated name(s)`)}`);
+    }
+    console.log();
+});
 // ─── Command: cycles ──────────────────────────────────────────────────────────
 program
     .command("cycles <dir>")
@@ -592,24 +622,24 @@ program
     .name("ast-map")
     .description("CLI for universal-ast-mapper — structural code analysis tools")
     .version("0.5.3")
-    .addHelpText("after", `
-${bold("Examples:")}
-  ast-map langs
-  ast-map skeleton src/
-  ast-map symbol src/utils.ts sanitize --related
-  ast-map imports src/pages/login.tsx
-  ast-map graph src/ -o graph.json
-  ast-map validate src/
-  ast-map dead src/
-  ast-map cycles src/
-  ast-map search validateSession src/ --exported
-  ast-map deps src/lib/auth.ts --scan src/
-  ast-map top src/ -n 15
-  ast-map impact src/utils.ts sanitize --scan src/
-  ast-map calls src/utils.ts buildCallGraph --scan src/
-
-${bold("Root:")}
-  Defaults to cwd. Override with AST_MAP_ROOT=<path> or run from your project root.
+    .addHelpText("after", `
+${bold("Examples:")}
+  ast-map langs
+  ast-map skeleton src/
+  ast-map symbol src/utils.ts sanitize --related
+  ast-map imports src/pages/login.tsx
+  ast-map graph src/ -o graph.json
+  ast-map validate src/
+  ast-map dead src/
+  ast-map cycles src/
+  ast-map search validateSession src/ --exported
+  ast-map deps src/lib/auth.ts --scan src/
+  ast-map top src/ -n 15
+  ast-map impact src/utils.ts sanitize --scan src/
+  ast-map calls src/utils.ts buildCallGraph --scan src/
+
+${bold("Root:")}
+  Defaults to cwd. Override with AST_MAP_ROOT=<path> or run from your project root.
 `);
 program.parseAsync(process.argv).catch(err => {
     console.error(red("Fatal: ") + (err instanceof Error ? err.message : String(err)));

package/dist/extractors/typescript.js

@@ -22,17 +22,14 @@ export function extractDirectivesTS(root, _source) {
     }
     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);
+    const typeIndex = buildTypeIndex(root);
+    return collect(namedChildren(root), false, typeIndex);
 }
-function collect(nodes, exported) {
+function collect(nodes, exported, typeIndex) {
     const out = [];
     for (const n of nodes) {
-        const res = handle(n, exported);
+        const res = handle(n, exported, typeIndex);
         if (Array.isArray(res))
             out.push(...res);
         else if (res)
@@ -40,16 +37,16 @@ function collect(nodes, exported) {
     }
     return out;
 }
-function handle(node, exported) {
+function handle(node, exported, typeIndex) {
     switch (node.type) {
         case "export_statement":
             // `export <decl>` / `export default <decl>` — mark the inner declarations exported.
-            return collect(namedChildren(node), true);
+            return collect(namedChildren(node), true, typeIndex);
         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) : [];
+            const children = body ? collect(namedChildren(body), false, typeIndex) : [];
             return makeSymbol({
                 name,
                 kind: "class",
@@ -63,7 +60,7 @@ function handle(node, exported) {
         case "interface_declaration": {
             const name = nameOf(node) ?? "(anonymous interface)";
             const body = node.childForFieldName("body");
-            const children = body ? collect(namedChildren(body), false) : [];
+            const children = body ? collect(namedChildren(body), false, typeIndex) : [];
             return makeSymbol({
                 name,
                 kind: "interface",
@@ -78,7 +75,7 @@ function handle(node, exported) {
         case "generator_function_declaration": {
             const name = nameOf(node) ?? "(anonymous function)";
             const body = node.childForFieldName("body");
-            return makeSymbol({
+            const fnSym = makeSymbol({
                 name,
                 kind: "function",
                 node,
@@ -87,6 +84,8 @@ function handle(node, exported) {
                 exported,
                 doc: leadingComment(node),
             });
+            attachComponentInfo(fnSym, node, null, name, typeIndex);
+            return fnSym;
         }
         case "type_alias_declaration":
             return makeSymbol({
@@ -109,7 +108,7 @@ function handle(node, exported) {
             });
         case "lexical_declaration":
         case "variable_declaration":
-            return fromVariableDeclaration(node, exported);
+            return fromVariableDeclaration(node, exported, typeIndex);
         case "method_definition":
         case "method_signature":
         case "abstract_method_signature": {
@@ -148,7 +147,7 @@ function handle(node, exported) {
             return null;
     }
 }
-function fromVariableDeclaration(node, exported) {
+function fromVariableDeclaration(node, exported, typeIndex) {
     const out = [];
     for (const decl of namedChildren(node)) {
         if (decl.type !== "variable_declarator")
@@ -159,7 +158,7 @@ function fromVariableDeclaration(node, exported) {
             continue;
         if (value && (value.type === "arrow_function" || value.type === "function" || value.type === "function_expression")) {
             const body = value.childForFieldName("body");
-            out.push(makeSymbol({
+            const arrowSym = makeSymbol({
                 name,
                 kind: "function",
                 node: decl,
@@ -167,12 +166,14 @@ function fromVariableDeclaration(node, exported) {
                 signature: headerSignature(value, body),
                 exported,
                 doc: leadingComment(node),
-            }));
+            });
+            attachComponentInfo(arrowSym, value, decl, name, typeIndex);
+            out.push(arrowSym);
         }
         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) : [];
+            const children = body ? collect(namedChildren(body), false, typeIndex) : [];
             out.push(makeSymbol({
                 name,
                 kind: "class",
@@ -318,3 +319,138 @@ function memberVisibility(node) {
         return "private";
     return "public";
 }
+// ─── React/TSX component prop extraction ──────────────────────────────────────
+const JSX_NODES = new Set(["jsx_element", "jsx_self_closing_element", "jsx_fragment"]);
+function firstNamed(node) {
+    return node.namedChildCount > 0 ? node.namedChild(0) : null;
+}
+/**
+ * Index every top-level (and exported) interface / object-type alias by name,
+ * mapping it to its prop fields. Used to resolve a component's named props type
+ * (e.g. `ButtonProps`) back to its individual props.
+ */
+function buildTypeIndex(root) {
+    const idx = new Map();
+    const visit = (nodes) => {
+        for (const n of nodes) {
+            if (n.type === "export_statement") {
+                visit(namedChildren(n));
+                continue;
+            }
+            if (n.type === "interface_declaration") {
+                const name = nameOf(n);
+                const body = n.childForFieldName("body");
+                if (name && body)
+                    idx.set(name, propsFromMembers(body));
+            }
+            else if (n.type === "type_alias_declaration") {
+                const name = nameOf(n);
+                const val = n.childForFieldName("value");
+                if (name && val && val.type === "object_type")
+                    idx.set(name, propsFromMembers(val));
+            }
+        }
+    };
+    visit(namedChildren(root));
+    return idx;
+}
+/** Read `property_signature` members out of an interface_body / object_type. */
+function propsFromMembers(container) {
+    const props = [];
+    for (const m of namedChildren(container)) {
+        if (m.type !== "property_signature")
+            continue;
+        const nameNode = m.childForFieldName("name");
+        if (!nameNode)
+            continue;
+        const info = { name: nameNode.text };
+        const typeAnn = m.childForFieldName("type");
+        const typeNode = typeAnn ? firstNamed(typeAnn) : null;
+        if (typeNode)
+            info.type = typeNode.text.replace(/\s+/g, " ").trim();
+        const colon = m.text.indexOf(":");
+        const head = colon >= 0 ? m.text.slice(0, colon) : m.text;
+        if (head.includes("?"))
+            info.optional = true;
+        props.push(info);
+    }
+    return props;
+}
+/** Walk a function body looking for any JSX node (marks it a React component). */
+function returnsJSX(node) {
+    if (!node)
+        return false;
+    let found = false;
+    const walk = (n) => {
+        if (found)
+            return;
+        if (JSX_NODES.has(n.type)) {
+            found = true;
+            return;
+        }
+        for (let i = 0; i < n.namedChildCount; i++) {
+            const c = n.namedChild(i);
+            if (c)
+                walk(c);
+        }
+    };
+    walk(node);
+    return found;
+}
+/**
+ * If `typeNode` is `FC<P>` / `React.FC<P>` / `FunctionComponent<P>` (or the
+ * React-qualified form), return the first type argument node (the props type).
+ */
+function fcTypeArgument(typeNode) {
+    if (!typeNode || typeNode.type !== "generic_type")
+        return null;
+    const base = typeNode.childForFieldName("name");
+    const baseText = base ? base.text : "";
+    if (!/(^|\.)(FC|FunctionComponent)$/.test(baseText))
+        return null;
+    for (let i = 0; i < typeNode.namedChildCount; i++) {
+        const c = typeNode.namedChild(i);
+        if (c && c.type === "type_arguments")
+            return firstNamed(c);
+    }
+    return null;
+}
+/**
+ * Detect a React component (PascalCase + returns JSX, or typed as FC) and
+ * attach its props. `funcNode` is the function/arrow; `declNode` is the
+ * variable_declarator when the component is `const X: React.FC<P> = ...`.
+ */
+function attachComponentInfo(sym, funcNode, declNode, name, idx) {
+    if (!/^[A-Z]/.test(name))
+        return; // components are PascalCase
+    let propsTypeNode = null;
+    let fc = false;
+    if (declNode) {
+        const ta = declNode.childForFieldName("type");
+        const arg = ta ? fcTypeArgument(firstNamed(ta)) : null;
+        if (arg) {
+            propsTypeNode = arg;
+            fc = true;
+        }
+    }
+    if (!fc && !returnsJSX(funcNode.childForFieldName("body")))
+        return; // not a component
+    if (!propsTypeNode) {
+        const params = funcNode.childForFieldName("parameters");
+        const first = params ? firstNamed(params) : null; // required/optional_parameter
+        const ta = first ? first.childForFieldName("type") : null;
+        if (ta)
+            propsTypeNode = firstNamed(ta);
+    }
+    if (!propsTypeNode)
+        return; // component, but untyped props — nothing to extract
+    if (propsTypeNode.type === "object_type") {
+        sym.props = propsFromMembers(propsTypeNode);
+        return;
+    }
+    const typeName = propsTypeNode.text.replace(/\s+/g, " ").trim();
+    sym.propsType = typeName;
+    const resolved = idx.get(typeName);
+    if (resolved)
+        sym.props = resolved;
+}

package/dist/graph-analysis.js

@@ -241,3 +241,39 @@ export function getTopSymbols(graph, limit = 10) {
     }
     return results.sort((a, b) => b.importCount - a.importCount).slice(0, limit);
 }
+/**
+ * Find symbol names that are exported from more than one file. These are often
+ * accidental collisions (copy-paste, parallel implementations) that make a
+ * codebase harder to navigate and can cause the wrong import to be auto-suggested.
+ *
+ * Only exported symbols are considered, and a name must appear in at least two
+ * distinct files to count as a duplicate.
+ */
+export function findDuplicateSymbols(graph) {
+    const byName = new Map();
+    for (const node of graph.nodes) {
+        if (node.nodeType !== "symbol")
+            continue;
+        const sym = node;
+        if (!sym.exported)
+            continue;
+        const arr = byName.get(sym.symbol) ?? [];
+        arr.push(sym);
+        byName.set(sym.symbol, arr);
+    }
+    const out = [];
+    for (const [name, syms] of byName) {
+        // Collapse to one location per file (a file may declare the name once).
+        const perFile = new Map();
+        for (const s of syms)
+            if (!perFile.has(s.file))
+                perFile.set(s.file, s);
+        if (perFile.size < 2)
+            continue;
+        const locations = [...perFile.values()]
+            .map((s) => ({ file: s.file, kind: s.kind, nodeId: s.id }))
+            .sort((a, b) => a.file.localeCompare(b.file));
+        out.push({ symbol: name, count: perFile.size, locations });
+    }
+    return out.sort((a, b) => b.count - a.count || a.symbol.localeCompare(b.symbol));
+}

package/dist/index.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { fileURLToPath } from "node:url";
 import { resolveOptions, loadProjectConfig } from "./config.js";
 import { buildSkeleton, collectSourceFiles, UnsupportedLanguageError, } from "./skeleton.js";
 import { renderHtml, renderCombinedHtml } from "./html.js";
@@ -11,7 +12,7 @@ import { supportedLanguages } from "./registry.js";
 import { findSymbol, findRelatedSymbols, findServerImports, isApiRoute, findMissingTryCatch, checkGeneralRules, GENERAL_RULE_DEFAULTS, } from "./analysis.js";
 import { resolveFileImports } from "./resolver.js";
 import { buildSymbolGraph } from "./graph.js";
-import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTopSymbols } from "./graph-analysis.js";
+import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTopSymbols, findDuplicateSymbols } from "./graph-analysis.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 /** Files may only be read inside this root (override with AST_MAP_ROOT). */
@@ -44,9 +45,19 @@ function errorText(message) {
         content: [{ type: "text", text: message }],
     };
 }
+/** Read the package version at runtime so it never drifts from package.json. */
+const PKG_VERSION = (() => {
+    try {
+        const dir = path.dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(fs.readFileSync(path.join(dir, "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 const server = new McpServer({
     name: "universal-ast-mapper",
-    version: "0.5.3",
+    version: PKG_VERSION,
 });
 /* ----------------------- tool: list_supported_languages ----------------------- */
 server.registerTool("list_supported_languages", {
@@ -512,6 +523,50 @@ server.registerTool("find_circular_deps", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: find_duplicate_symbols ──────────────────────── */
+server.registerTool("find_duplicate_symbols", {
+    title: "Find duplicate exported symbols",
+    description: "Scan a directory and return symbol names that are exported from more than one file. " +
+        "These are often accidental collisions (copy-paste, parallel implementations) that make " +
+        "a codebase harder to navigate. Each result lists every file/kind that declares the name.",
+    inputSchema: {
+        path: z
+            .string()
+            .describe("Directory to scan, relative to project root or absolute within it."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input);
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. find_duplicate_symbols requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const skeletons = [];
+        const errors = [];
+        for (const file of files) {
+            const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+            try {
+                skeletons.push(await buildSkeleton(file, fileRel, opts));
+            }
+            catch (err) {
+                errors.push({ file: fileRel, error: describeError(err) });
+            }
+        }
+        const graph = buildSymbolGraph(skeletons, ROOT);
+        const duplicates = findDuplicateSymbols(graph);
+        return jsonText({
+            directory: rel.split(path.sep).join("/"),
+            scanned: files.length,
+            duplicateCount: duplicates.length,
+            ...(errors.length > 0 ? { errors } : {}),
+            duplicates,
+        });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",