universal-ast-mapper 0.8.2 → 0.8.6

package/README.md

@@ -93,6 +93,9 @@ 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 complexity <path>          [alias: cx] [--min N]
+ast-map unused-params <path>       [alias: unused]
 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 +263,52 @@ 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_complexity`
+Compute **AST-based cyclomatic complexity** per function/method for a file or directory. Score = `1 + decision points` (if / for / while / case / catch / ternary / `&&` / `||`), with a rating: `low` (≤5), `moderate` (≤10), `high` (≤20), `very-high` (>20). Directory scans also return the highest-complexity **hotspots** across all files.
+
+```json
+{
+  "file": "src/auth.ts",
+  "maxComplexity": 12,
+  "functions": [
+    { "name": "validate", "complexity": 12, "rating": "high", "startLine": 8, "endLine": 40 }
+  ]
+}
+```
+
+**Params:** `path`
+
+---
+
+### `find_unused_params`
+Scan a file or directory for **named functions/methods with parameters that are never used** in the body. Skips `_`-prefixed params (conventionally intentional), anonymous callbacks, and destructured bindings — and correctly treats object-shorthand (`{ id }`) as a use — to keep false positives near zero.
+
+```json
+{ "file": "src/x.ts", "functions": [ { "function": "greet", "line": 3, "unused": ["salutation"] } ] }
+```
+
+**Params:** `path`
+
+---
+
 ### `get_change_impact`
 Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
 
@@ -482,6 +531,10 @@ src/
 
 | Version | What changed |
 |---------|--------------|
+| **0.8.6** | **Unused parameter detection** — new `find_unused_params` MCP tool + `ast-map unused-params` (alias `unused`) CLI: named functions whose params are never referenced. Skips `_`-prefixed/destructured/anonymous and treats object-shorthand as a use (low false-positive). Server now 17 tools. |
+| **0.8.5** | **Cyclomatic complexity** — new `get_complexity` MCP tool + `ast-map complexity` (alias `cx`, `--min N`) CLI: per-function AST-based complexity score (`1 + if/for/while/case/catch/ternary/&&/\|\|`) with low/moderate/high/very-high ratings and directory hotspots. Server now 16 tools. |
+| **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,9 @@ 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 { computeFileComplexity } from "./complexity.js";
+import { findUnusedParams } from "./unused-params.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -366,6 +368,121 @@ program
     }
     console.log();
 });
+// ─── Command: unused-params ───────────────────────────────────────────────────
+program
+    .command("unused-params <path>")
+    .alias("unused")
+    .description("Find function parameters that are never used in the body")
+    .option("--json", "Output as JSON")
+    .action(async (inputPath, opts) => {
+    const { abs, rel } = resolveArg(inputPath);
+    const stat = fs.statSync(abs);
+    const results = [];
+    if (stat.isDirectory()) {
+        const sopts = resolveOptions({ detail: "outline", emitHtml: false });
+        for (const file of collectSourceFiles(abs, sopts)) {
+            const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+            const r = await findUnusedParams(file, fileRel);
+            if (r && r.functions.length > 0)
+                results.push(r);
+        }
+    }
+    else {
+        const r = await findUnusedParams(abs, rel);
+        if (!r)
+            die(`Unsupported file type: ${rel}`);
+        if (r.functions.length > 0)
+            results.push(r);
+    }
+    const rows = results.flatMap((r) => r.functions.map((f) => ({ file: r.file, ...f })));
+    if (opts.json)
+        return jsonOut({ path: rel, count: rows.length, functions: rows });
+    header(`Unused Parameters — ${rel}`);
+    if (rows.length === 0) {
+        console.log(indent(green("✓ No unused parameters found.")));
+    }
+    else {
+        table(rows.map((f) => [f.function, yellow(f.unused.join(", ")), f.file]), [["Function", 26], ["Unused params", 28], ["File", 36]]);
+        const totalP = rows.reduce((a, f) => a + f.unused.length, 0);
+        console.log(`\n  ${yellow(`${totalP} unused parameter(s)`)} in ${rows.length} function(s)`);
+    }
+    console.log();
+});
+// ─── Command: complexity ──────────────────────────────────────────────────────
+program
+    .command("complexity <path>")
+    .alias("cx")
+    .description("Cyclomatic complexity per function (file or directory)")
+    .option("--json", "Output as JSON")
+    .option("--min <n>", "Only show functions with complexity >= n", (v) => parseInt(v, 10))
+    .action(async (inputPath, opts) => {
+    const { abs, rel } = resolveArg(inputPath);
+    const stat = fs.statSync(abs);
+    const min = opts.min ?? 1;
+    const fileResults = [];
+    if (stat.isDirectory()) {
+        const sopts = resolveOptions({ detail: "outline", emitHtml: false });
+        for (const file of collectSourceFiles(abs, sopts)) {
+            const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+            const fc = await computeFileComplexity(file, fileRel);
+            if (fc)
+                fileResults.push(fc);
+        }
+    }
+    else {
+        const fc = await computeFileComplexity(abs, rel);
+        if (!fc)
+            die(`Unsupported file type: ${rel}`);
+        fileResults.push(fc);
+    }
+    const rows = fileResults
+        .flatMap((r) => r.functions.map((f) => ({ file: r.file, ...f })))
+        .filter((f) => f.complexity >= min)
+        .sort((a, b) => b.complexity - a.complexity);
+    if (opts.json)
+        return jsonOut({ path: rel, functionCount: rows.length, functions: rows });
+    header(`Cyclomatic Complexity — ${rel}  ${dim(`(${fileResults.length} file(s))`)}`);
+    if (rows.length === 0) {
+        console.log(indent(green("✓ No functions found.")));
+    }
+    else {
+        const colorFor = (r) => (r === "very-high" || r === "high" ? yellow : r === "moderate" ? bold : dim);
+        table(rows.slice(0, 40).map((f) => [String(f.complexity), colorFor(f.rating)(f.rating), f.name, f.file]), [["Cx", 4], ["Rating", 11], ["Function", 26], ["File", 38]]);
+        const high = rows.filter((f) => f.complexity > 10).length;
+        console.log(`\n  ${rows.length} function(s)` + (high > 0 ? ` · ${yellow(`${high} above 10`)}` : ""));
+    }
+    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 +709,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/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/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,9 +12,11 @@ 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";
+import { computeFileComplexity } from "./complexity.js";
+import { findUnusedParams } from "./unused-params.js";
 /** Files may only be read inside this root (override with AST_MAP_ROOT). */
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
 function resolveInRoot(input) {
@@ -44,9 +47,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 +525,148 @@ 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_complexity ──────────────────────────────── */
+server.registerTool("get_complexity", {
+    title: "Get cyclomatic complexity per function",
+    description: "Compute AST-based cyclomatic complexity for every function/method in a FILE or DIRECTORY. " +
+        "Each function gets a score (1 + decision points: if / for / while / case / catch / ternary / && / ||) " +
+        "and a rating (low <=5, moderate <=10, high <=20, very-high >20). For a directory, returns per-file " +
+        "results plus the highest-complexity hotspots across the scan.",
+    inputSchema: {
+        path: z.string().describe("File or directory, relative to project root or absolute within it."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input);
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory()) {
+            const opts = resolveOptions({ detail: "outline", emitHtml: false });
+            const files = collectSourceFiles(abs, opts);
+            const results = [];
+            const errors = [];
+            for (const file of files) {
+                const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+                try {
+                    const fc = await computeFileComplexity(file, fileRel);
+                    if (fc)
+                        results.push(fc);
+                }
+                catch (err) {
+                    errors.push({ file: fileRel, error: describeError(err) });
+                }
+            }
+            const hotspots = results
+                .flatMap((r) => r.functions.map((f) => ({ file: r.file, ...f })))
+                .sort((a, b) => b.complexity - a.complexity)
+                .slice(0, 15);
+            return jsonText({
+                directory: rel.split(path.sep).join("/"),
+                scanned: files.length,
+                ...(errors.length > 0 ? { errors } : {}),
+                hotspots,
+                files: results,
+            });
+        }
+        const fc = await computeFileComplexity(abs, rel.split(path.sep).join("/"));
+        if (!fc)
+            return errorText(`Unsupported file type: ${input}`);
+        return jsonText(fc);
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
+/* ─────────────────── tool: find_unused_params ──────────────────────────── */
+server.registerTool("find_unused_params", {
+    title: "Find unused function parameters",
+    description: "Scan a FILE or DIRECTORY for named functions/methods that declare parameters never " +
+        "referenced in their body. Skips `_`-prefixed params (conventionally intentional), " +
+        "anonymous callbacks, and destructured bindings to avoid false positives.",
+    inputSchema: {
+        path: z.string().describe("File or directory, relative to project root or absolute within it."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input);
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory()) {
+            const opts = resolveOptions({ detail: "outline", emitHtml: false });
+            const files = collectSourceFiles(abs, opts);
+            const results = [];
+            const errors = [];
+            for (const file of files) {
+                const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+                try {
+                    const r = await findUnusedParams(file, fileRel);
+                    if (r && r.functions.length > 0)
+                        results.push(r);
+                }
+                catch (err) {
+                    errors.push({ file: fileRel, error: describeError(err) });
+                }
+            }
+            const unusedParamCount = results.reduce((sum, r) => sum + r.functions.reduce((a, f) => a + f.unused.length, 0), 0);
+            return jsonText({
+                directory: rel.split(path.sep).join("/"),
+                scanned: files.length,
+                ...(errors.length > 0 ? { errors } : {}),
+                unusedParamCount,
+                files: results,
+            });
+        }
+        const r = await findUnusedParams(abs, rel.split(path.sep).join("/"));
+        if (!r)
+            return errorText(`Unsupported file type: ${input}`);
+        return jsonText(r);
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/dist/unused-params.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import { parseSource } from "./parser.js";
+import { detectLanguage } from "./registry.js";
+// Named function-like nodes across the supported languages. Anonymous arrows /
+// lambdas are intentionally skipped: they're usually callbacks where an unused
+// parameter is required by the caller's signature (event handlers, map indices).
+const FN_TYPES = new Set([
+    "function_declaration",
+    "generator_function_declaration",
+    "function_definition", // Python / C / C++
+    "async_function_definition", // Python
+    "method_definition", // TS/JS class member
+    "method_declaration", // Go / Java / C#
+    "constructor_declaration", // Java / C#
+    "function_item", // Rust
+]);
+const PARAM_CONTAINERS = new Set([
+    "formal_parameters", "parameters", "parameter_list", "function_value_parameters",
+]);
+const ID_TYPES = new Set(["identifier", "simple_identifier"]);
+// Identifier-like nodes that count as a *usage* of a name. Includes object
+// shorthand (`{ foo }` references `foo`), which is ubiquitous in JS/TS.
+const USE_TYPES = new Set([
+    "identifier", "simple_identifier",
+    "shorthand_property_identifier", "shorthand_property_identifier_pattern",
+]);
+// Binding shapes we do NOT try to resolve to a single name (avoid false positives).
+const SKIP_PARAM = /splat|rest|spread|object_pattern|array_pattern|tuple_pattern|object_type/;
+function fnName(node) {
+    const nm = node.childForFieldName("name");
+    if (nm)
+        return nm.text;
+    // Kotlin/Swift function_declaration: name is the first simple_identifier child.
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c && c.type === "simple_identifier")
+            return c.text;
+    }
+    return "(anonymous)";
+}
+function paramsNode(fn) {
+    const p = fn.childForFieldName("parameters");
+    if (p)
+        return p;
+    for (let i = 0; i < fn.namedChildCount; i++) {
+        const c = fn.namedChild(i);
+        if (c && PARAM_CONTAINERS.has(c.type))
+            return c;
+    }
+    return null;
+}
+/** Best-effort binding names for one parameter node (may be empty when unsure). */
+function paramNames(p) {
+    if (ID_TYPES.has(p.type))
+        return [p.text];
+    if (SKIP_PARAM.test(p.type))
+        return [];
+    const pat = p.childForFieldName("pattern");
+    if (pat)
+        return ID_TYPES.has(pat.type) ? [pat.text] : [];
+    const nm = p.childForFieldName("name");
+    if (nm && ID_TYPES.has(nm.type))
+        return [nm.text];
+    // Go: `a, b int` → several identifier children before the type.
+    const ids = [];
+    for (let i = 0; i < p.namedChildCount; i++) {
+        const c = p.namedChild(i);
+        if (c && c.type === "identifier")
+            ids.push(c.text);
+    }
+    return ids;
+}
+/** Collect every bare identifier reference in the subtree (not member/field names). */
+function collectIdentifierUses(node, out) {
+    if (USE_TYPES.has(node.type))
+        out.add(node.text);
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c)
+            collectIdentifierUses(c, out);
+    }
+}
+function unusedInFunction(fn) {
+    const pnode = paramsNode(fn);
+    const body = fn.childForFieldName("body");
+    if (!pnode || !body)
+        return [];
+    const names = [];
+    for (let i = 0; i < pnode.namedChildCount; i++) {
+        const p = pnode.namedChild(i);
+        if (p)
+            names.push(...paramNames(p));
+    }
+    if (names.length === 0)
+        return [];
+    const used = new Set();
+    collectIdentifierUses(body, used);
+    // Skip `_`-prefixed (conventionally intentional) and `this`/`self`.
+    return names.filter((n) => n !== "_" && !n.startsWith("_") && n !== "this" && n !== "self" && !used.has(n));
+}
+export async function findUnusedParams(absPath, relPath) {
+    const lang = detectLanguage(absPath);
+    if (!lang)
+        return null;
+    const source = fs.readFileSync(absPath, "utf8");
+    const root = await parseSource(lang.grammar, source);
+    const functions = [];
+    const walk = (node) => {
+        if (FN_TYPES.has(node.type)) {
+            const unused = unusedInFunction(node);
+            if (unused.length > 0) {
+                functions.push({
+                    function: fnName(node),
+                    line: node.startPosition.row + 1,
+                    unused,
+                });
+            }
+        }
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const c = node.namedChild(i);
+            if (c)
+                walk(c);
+        }
+    };
+    walk(root);
+    return { file: relPath, functions };
+}

package/package.json

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