universal-ast-mapper 0.8.4 → 1.0.0

package/README.md

@@ -94,6 +94,9 @@ 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 trace-type <type> [dir]    [alias: flow]
 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 +282,49 @@ 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`
+
+---
+
+### `trace_type`
+**Scoped type-flow tracing.** Find everywhere a named type flows through a directory — function **parameters** and **return types**, typed **variables**, and class **fields**. AST-based (no full type inference), so it tracks where a type is *named* in signatures; works best for TS/Python but resolves return/param types in any language that annotates them.
+
+```json
+{
+  "type": "Inventory",
+  "byRole": { "param": 3, "return": 2, "variable": 1, "field": 1 },
+  "refs": [ { "file": "src/svc.ts", "symbol": "make", "role": "return", "line": 4 } ]
+}
+```
+
+**Params:** `type`, `path`
+
+---
+
 ### `get_change_impact`
 Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
 
@@ -497,10 +543,54 @@ src/
 
 ---
 
+## GitHub Action — architecture gate in CI
+
+Use AST-MCP as a CI check with the bundled composite action (`action.yml`):
+
+```yaml
+# .github/workflows/architecture.yml
+name: Architecture
+on: [pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: 6ixthxense/AST-MCP@v1.0.0
+        with:
+          path: src
+          max-lines: "400"
+          max-imports: "20"
+          max-exports: "15"
+```
+
+The action runs `ast-map validate` and fails the job on threshold violations. You can also call any CLI command directly with `npx -p universal-ast-mapper ast-map <command>`.
+
+---
+
+## Stability (1.0)
+
+As of **v1.0.0**, the public surface is stable across the `1.x` line:
+
+- **MCP tool names and input schemas** — no breaking changes; new tools and new *optional* inputs may be added.
+- **CLI commands and flags** — stable; new commands/flags may be added.
+- **Skeleton JSON** — `schemaVersion` follows additive-compatible evolution; new *optional* fields (e.g. `props`, `decorators`) may appear without a major bump.
+
+Not part of the public API: the internal `src/` module layout and the generated HTML markup.
+
+---
+
 ## Changelog
 
 | Version | What changed |
 |---------|--------------|
+| **1.0.0** | **Stable release.** Locks the public API (MCP tool names + schemas, CLI surface) for the 1.x line. Adds a **GitHub Action** (`action.yml`) to run `ast-map validate` as a CI architecture gate, plus a project CI workflow. Caps a 12-language engine with 18 MCP tools / 17 CLI commands spanning skeletons, dependency graphs, and deep analysis (dead code · cycles · impact · complexity · duplicates · unused params · decorators · type flow). |
+| **0.9.0** | **Scoped type-flow tracing** — new `trace_type` MCP tool + `ast-map trace-type` (alias `flow`) CLI: follow a named type through function params, return types, typed variables, and class fields across a directory. Completes the deeper-analysis suite (dead code · cycles · impact · complexity · duplicates · unused params · type flow). **18 MCP tools**. |
+| **0.8.7** | **Python decorators in the call graph** — function/method symbols now carry a `decorators` field (`@router.get("/x")` → `router.get("/x")`), surfaced in skeletons (outline + full) and in `get_call_graph`. Traces framework wiring like FastAPI/Flask routes and `@staticmethod`/`@property` stacks to their handler. |
+| **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/callgraph.js

@@ -243,6 +243,17 @@ async function fileCallsSymbol(fileAbs, funcName) {
     return false;
 }
 // ─── Public API ───────────────────────────────────────────────────────────────
+/** Recursively find the first symbol with the given name and return its decorators. */
+function findDecorators(symbols, name) {
+    for (const s of symbols) {
+        if (s.name === name && s.decorators && s.decorators.length > 0)
+            return s.decorators;
+        const nested = findDecorators(s.children, name);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
 export async function buildCallGraph(filePath, funcName, root, allSkeletons) {
     const langEntry = detectLanguage(filePath);
     if (!langEntry)
@@ -427,6 +438,7 @@ export async function buildCallGraph(filePath, funcName, root, allSkeletons) {
             }
         }
     }
+    const decorators = findDecorators(skel.symbols, funcName);
     return {
         file: relPath,
         function: funcName,
@@ -434,6 +446,7 @@ export async function buildCallGraph(filePath, funcName, root, allSkeletons) {
             startLine: funcNode.startPosition.row + 1,
             endLine: funcNode.endPosition.row + 1,
         },
+        ...(decorators ? { decorators } : {}),
         calls,
         calledBy,
     };

package/dist/cli.js

@@ -10,6 +10,9 @@ 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 { traceTypeInFile } from "./typeflow.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -366,6 +369,124 @@ program
     }
     console.log();
 });
+// ─── Command: trace-type ──────────────────────────────────────────────────────
+program
+    .command("trace-type <type> [dir]")
+    .alias("flow")
+    .description("Trace a type through params, returns, variables and fields")
+    .option("--json", "Output as JSON")
+    .action(async (typeName, dir, opts) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const sopts = resolveOptions({ detail: "outline", emitHtml: false });
+    const refs = [];
+    for (const file of collectSourceFiles(abs, sopts)) {
+        const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+        refs.push(...(await traceTypeInFile(file, fileRel, typeName)));
+    }
+    if (opts.json)
+        return jsonOut({ type: typeName, dir: rel, refCount: refs.length, refs });
+    header(`Type Flow: ${bold(typeName)} — ${rel}/  ${dim(`(${refs.length} ref(s))`)}`);
+    if (refs.length === 0) {
+        console.log(indent(dim(`No references to type "${typeName}" found in signatures.`)));
+    }
+    else {
+        const roleColor = (r) => (r === "return" ? green : r === "param" ? yellow : dim);
+        table(refs.map((r) => [
+            roleColor(r.role)(r.role),
+            r.symbol + (r.detail ? `(${r.detail})` : ""),
+            `:${r.line}`,
+            r.file,
+        ]), [["Role", 9], ["Symbol", 24], ["Line", 6], ["File", 34]]);
+    }
+    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/extractors/common.js

@@ -49,6 +49,8 @@ export function toOutline(symbols) {
         };
         if (s.exported !== undefined)
             out.exported = s.exported;
+        if (s.decorators)
+            out.decorators = s.decorators;
         return out;
     });
 }

package/dist/extractors/python.js

@@ -15,7 +15,18 @@ function collect(nodes, insideClass) {
 function handle(node, insideClass) {
     if (node.type === "decorated_definition") {
         const inner = innerDefinition(node);
-        return inner ? handle(inner, insideClass) : null;
+        if (!inner)
+            return null;
+        const sym = handle(inner, insideClass);
+        if (sym) {
+            const decs = namedChildren(node)
+                .filter((c) => c.type === "decorator")
+                .map((d) => d.text.replace(/^@\s*/, "").replace(/\s+/g, " ").trim())
+                .filter((t) => t.length > 0);
+            if (decs.length > 0)
+                sym.decorators = decs;
+        }
+        return sym;
     }
     if (node.type === "class_definition") {
         const name = nameOf(node) ?? "(class)";

package/dist/index.js

@@ -15,6 +15,9 @@ 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";
+import { traceTypeInFile } from "./typeflow.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 +570,150 @@ 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: trace_type ──────────────────────────────────── */
+server.registerTool("trace_type", {
+    title: "Trace a type through the code",
+    description: "Find everywhere a named type flows through a directory: function parameters and return " +
+        "types, typed variables, and class fields. A scoped, AST-based type-flow view (best for " +
+        "TS/Python) \u2014 no full type inference, so it tracks where the type is *named* in signatures.",
+    inputSchema: {
+        type: z.string().describe('Type name to trace, e.g. "Inventory".'),
+        path: z.string().describe("Directory to scan, relative to project root or absolute within it."),
+    },
+}, async ({ type: typeName, path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input);
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. trace_type requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const refs = [];
+        const errors = [];
+        for (const file of files) {
+            const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
+            try {
+                refs.push(...(await traceTypeInFile(file, fileRel, typeName)));
+            }
+            catch (err) {
+                errors.push({ file: fileRel, error: describeError(err) });
+            }
+        }
+        const byRole = { param: 0, return: 0, variable: 0, field: 0 };
+        for (const r of refs)
+            byRole[r.role]++;
+        return jsonText({
+            type: typeName,
+            directory: rel.split(path.sep).join("/"),
+            scanned: files.length,
+            refCount: refs.length,
+            byRole,
+            ...(errors.length > 0 ? { errors } : {}),
+            refs,
+        });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/dist/typeflow.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import { parseSource } from "./parser.js";
+import { detectLanguage } from "./registry.js";
+const FN_TYPES = new Set([
+    "function_declaration", "generator_function_declaration", "function_definition",
+    "async_function_definition", "method_definition", "method_declaration",
+    "constructor_declaration", "function_item",
+]);
+const ID_TYPES = new Set(["identifier", "simple_identifier"]);
+const TYPE_ID_TYPES = new Set(["type_identifier", "identifier"]);
+const PARAM_CONTAINERS = new Set([
+    "formal_parameters", "parameters", "parameter_list", "function_value_parameters",
+]);
+function fnName(node) {
+    const nm = node.childForFieldName("name");
+    if (nm)
+        return nm.text;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c && c.type === "simple_identifier")
+            return c.text;
+    }
+    return "(anonymous)";
+}
+/** Does this type-annotation subtree reference the bare type name `name`? */
+function typeRefsName(node, name) {
+    if (!node)
+        return false;
+    let hit = false;
+    const walk = (n) => {
+        if (hit)
+            return;
+        if (TYPE_ID_TYPES.has(n.type) && n.text === name) {
+            hit = true;
+            return;
+        }
+        for (let i = 0; i < n.namedChildCount; i++) {
+            const c = n.namedChild(i);
+            if (c)
+                walk(c);
+        }
+    };
+    walk(node);
+    return hit;
+}
+function paramName(p) {
+    if (ID_TYPES.has(p.type))
+        return p.text;
+    const pat = p.childForFieldName("pattern");
+    if (pat && ID_TYPES.has(pat.type))
+        return pat.text;
+    const nm = p.childForFieldName("name");
+    if (nm && ID_TYPES.has(nm.type))
+        return nm.text;
+    return undefined;
+}
+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;
+}
+export async function traceTypeInFile(absPath, relPath, typeName) {
+    const lang = detectLanguage(absPath);
+    if (!lang)
+        return [];
+    const source = fs.readFileSync(absPath, "utf8");
+    const root = await parseSource(lang.grammar, source);
+    const refs = [];
+    const walk = (node) => {
+        if (FN_TYPES.has(node.type)) {
+            const name = fnName(node);
+            // return type
+            const rt = node.childForFieldName("return_type");
+            if (typeRefsName(rt, typeName)) {
+                refs.push({ file: relPath, symbol: name, role: "return", line: node.startPosition.row + 1 });
+            }
+            // params
+            const pnode = paramsNode(node);
+            if (pnode) {
+                for (let i = 0; i < pnode.namedChildCount; i++) {
+                    const p = pnode.namedChild(i);
+                    if (!p)
+                        continue;
+                    const ty = p.childForFieldName("type");
+                    if (typeRefsName(ty, typeName)) {
+                        const pn = paramName(p);
+                        refs.push({
+                            file: relPath, symbol: name, role: "param",
+                            ...(pn ? { detail: pn } : {}),
+                            line: p.startPosition.row + 1,
+                        });
+                    }
+                }
+            }
+        }
+        else if (node.type === "variable_declarator") {
+            const ty = node.childForFieldName("type");
+            const nm = node.childForFieldName("name");
+            if (ty && nm && typeRefsName(ty, typeName)) {
+                refs.push({ file: relPath, symbol: nm.text, role: "variable", line: node.startPosition.row + 1 });
+            }
+        }
+        else if (node.type === "public_field_definition" || node.type === "field_definition") {
+            const ty = node.childForFieldName("type");
+            const nm = node.childForFieldName("name");
+            if (ty && nm && typeRefsName(ty, typeName)) {
+                refs.push({ file: relPath, symbol: nm.text, role: "field", line: node.startPosition.row + 1 });
+            }
+        }
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const c = node.namedChild(i);
+            if (c)
+                walk(c);
+        }
+    };
+    walk(root);
+    return refs;
+}

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": "1.0.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",