universal-ast-mapper 0.8.4 → 0.8.6

package/README.md

@@ -94,6 +94,8 @@ ast-map validate <path>            [--max-lines N] [--max-imports N] [--max-expo
 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]
@@ -279,6 +281,34 @@ Scan a directory → find symbol names exported from **more than one file** (acc
 
 ---
 
+### `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**.
 
@@ -501,6 +531,8 @@ 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. |

package/dist/cli.js

@@ -10,6 +10,8 @@ import { findSymbol, findRelatedSymbols, findServerImports, isApiRoute, findMiss
 import { resolveFileImports } from "./resolver.js";
 import { buildSymbolGraph } from "./graph.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,91 @@ 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>")

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/index.js

@@ -15,6 +15,8 @@ import { buildSymbolGraph } from "./graph.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) {
@@ -567,6 +569,104 @@ server.registerTool("find_duplicate_symbols", {
         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.4",
+  "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",