universal-ast-mapper 0.8.6 → 1.0.0

package/README.md

@@ -96,6 +96,7 @@ 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]
@@ -309,6 +310,21 @@ Scan a file or directory for **named functions/methods with parameters that are
 
 ---
 
+### `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**.
 
@@ -527,10 +543,52 @@ 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. |

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

@@ -12,6 +12,7 @@ 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());
@@ -368,6 +369,39 @@ 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>")

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

@@ -17,6 +17,7 @@ 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) {
@@ -667,6 +668,52 @@ server.registerTool("find_unused_params", {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "0.8.6",
+  "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",