universal-ast-mapper 1.1.0 → 1.3.0

package/README.md

@@ -326,6 +326,8 @@ Scan a file or directory for **named functions/methods with parameters that are
 
 ---
 
+> **Monorepo note:** once a workspace is detected, `resolve_imports` and `build_symbol_graph` resolve cross-package imports (`@org/pkg`) to real source files and draw cross-package edges.
+
 ### `analyze_workspace`
 **Monorepo support.** Discover the packages in a JS/TS monorepo (npm/yarn `workspaces`, `pnpm-workspace.yaml`, or `lerna.json`) and the dependency edges between them. Returns each package's name, directory, and workspace-internal dependencies, plus any circular dependencies between packages.
 
@@ -603,6 +605,8 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.3.0** | **TS/JS decorators** — class and method symbols now carry a `decorators` field (`@Component({...})`, `@Injectable()`, `@Get("/x")`), in skeletons and `get_call_graph`. Extends the Python decorator support (v0.8.7) to TypeScript/JavaScript — traces Angular/NestJS-style framework wiring to its class/handler. |
+| **1.2.0** | **File-level cross-package resolution** — in a monorepo, bare imports of a workspace package (`@org/utils`, `@org/utils/sub`) now resolve to the actual source file (preferring `src/` over built `dist/`), so `resolve_imports` marks them in-project and `build_symbol_graph` draws cross-package edges. Builds on the v1.1.0 workspace discovery. |
 | **1.1.0** | **Monorepo support** — new `analyze_workspace` MCP tool + `ast-map workspace` (alias `ws`) CLI: discovers packages from npm/yarn `workspaces`, `pnpm-workspace.yaml`, or `lerna.json`, maps internal package dependencies, and flags circular package deps. **19 MCP tools**. |
 | **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**. |

package/dist/extractors/typescript.js

@@ -47,7 +47,7 @@ function handle(node, exported, typeIndex) {
             const name = nameOf(node) ?? "(anonymous class)";
             const body = node.childForFieldName("body");
             const children = body ? collect(namedChildren(body), false, typeIndex) : [];
-            return makeSymbol({
+            const clsSym = makeSymbol({
                 name,
                 kind: "class",
                 node,
@@ -56,6 +56,8 @@ function handle(node, exported, typeIndex) {
                 doc: leadingComment(node),
                 children,
             });
+            attachDecorators(clsSym, node);
+            return clsSym;
         }
         case "interface_declaration": {
             const name = nameOf(node) ?? "(anonymous interface)";
@@ -114,7 +116,7 @@ function handle(node, exported, typeIndex) {
         case "abstract_method_signature": {
             const name = nameOf(node) ?? "(method)";
             const body = node.childForFieldName("body");
-            return makeSymbol({
+            const mSym = makeSymbol({
                 name,
                 kind: "method",
                 node,
@@ -123,6 +125,8 @@ function handle(node, exported, typeIndex) {
                 visibility: memberVisibility(node),
                 doc: leadingComment(node),
             });
+            attachDecorators(mSym, node);
+            return mSym;
         }
         case "public_field_definition":
         case "field_definition": {
@@ -454,3 +458,34 @@ function attachComponentInfo(sym, funcNode, declNode, name, idx) {
     if (resolved)
         sym.props = resolved;
 }
+// ─── TS/JS decorators ─────────────────────────────────────────────────────────
+/** Strip the leading `@` and collapse whitespace from a decorator node. */
+function decoratorText(node) {
+    return node.text.replace(/^@\s*/, "").replace(/\s+/g, " ").trim();
+}
+/**
+ * Attach decorators to a class/method symbol. TS decorators appear either as
+ * preceding sibling `decorator` nodes (classes, methods) or as leading child
+ * decorators (some grammars) — collect both.
+ */
+function attachDecorators(sym, node) {
+    const decs = [];
+    // leading child decorators
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c && c.type === "decorator")
+            decs.push(decoratorText(c));
+        else if (c && c.type !== "decorator")
+            break;
+    }
+    // preceding sibling decorators (most common for classes/methods)
+    let prev = node.previousNamedSibling;
+    const lead = [];
+    while (prev && prev.type === "decorator") {
+        lead.unshift(decoratorText(prev));
+        prev = prev.previousNamedSibling;
+    }
+    const all = [...lead, ...decs].filter((t) => t.length > 0);
+    if (all.length > 0)
+        sym.decorators = all;
+}

package/dist/graph.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { resolveImportPath } from "./resolver.js";
+import { resolveWorkspaceImportCached } from "./workspace.js";
 import { buildCrossLangIndex, resolveCrossLangTarget, } from "./crosslang.js";
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 function collectSymbolNodes(symbols, parentId, file, nodes, edges) {
@@ -30,11 +31,12 @@ function isPathBasedLanguage(language) {
 }
 // Wire one TS/JS/Python-style relative import.
 function wirePathImport(skel, imp, fromFileAbs, root, exportedSymbolMap, edges) {
-    if (!imp.from.startsWith("."))
-        return;
     if (imp.isSideEffect)
         return;
-    const resolvedAbs = resolveImportPath(imp.from, fromFileAbs);
+    // Relative import → path resolve; bare specifier → monorepo workspace package.
+    const resolvedAbs = imp.from.startsWith(".")
+        ? resolveImportPath(imp.from, fromFileAbs)
+        : resolveWorkspaceImportCached(imp.from, root);
     if (!resolvedAbs)
         return;
     const resolvedRel = path.relative(root, resolvedAbs).split(path.sep).join("/");

package/dist/resolver.js

@@ -4,6 +4,7 @@ import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
 import { resolveOptions } from "./config.js";
 import { findSymbol } from "./analysis.js";
 import { buildCrossLangIndex, resolveCrossLangTarget, } from "./crosslang.js";
+import { resolveWorkspaceImportCached } from "./workspace.js";
 const SRC_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
 function extractParams(sig) {
     const start = sig.indexOf("(");
@@ -120,8 +121,12 @@ async function lookupSymbolInTarget(targetAbs, targetRel, symbol) {
     return { found: false };
 }
 async function enrichRelativeImport(imp, fromAbs, root) {
-    const isExternal = !imp.from.startsWith(".");
-    const resolvedAbs = isExternal ? null : resolveImportPath(imp.from, fromAbs);
+    const isBare = !imp.from.startsWith(".");
+    // Relative import → path resolve; bare specifier → try monorepo workspace.
+    let resolvedAbs = isBare ? null : resolveImportPath(imp.from, fromAbs);
+    if (!resolvedAbs && isBare)
+        resolvedAbs = resolveWorkspaceImportCached(imp.from, root);
+    const treatedExternal = isBare && !resolvedAbs;
     const resolvedRel = resolvedAbs
         ? path.relative(root, resolvedAbs).split(path.sep).join("/")
         : null;
@@ -132,7 +137,7 @@ async function enrichRelativeImport(imp, fromAbs, root) {
     else if (resolvedAbs) {
         enrichment = { found: true };
     }
-    return assembleResolved(imp, resolvedAbs, resolvedRel, isExternal, enrichment);
+    return assembleResolved(imp, resolvedAbs, resolvedRel, treatedExternal, enrichment);
 }
 async function enrichCrossLangImport(imp, skel, fromAbs, root, index) {
     const target = resolveCrossLangTarget(imp, skel, fromAbs, root, index);

package/dist/workspace.js

@@ -205,3 +205,126 @@ export function findPackageCycles(info) {
             dfs(k);
     return cycles;
 }
+/* ─── File-level cross-package import resolution ───────────────────────────── */
+const SRC_EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const JS_TO_SRC = {
+    ".js": [".ts", ".tsx", ".js"],
+    ".jsx": [".tsx", ".jsx"],
+    ".mjs": [".mts", ".mjs"],
+    ".cjs": [".cts", ".cjs"],
+};
+function existsFileSync(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a candidate path (file, extensionless, or directory) to a real source
+ * file, preferring TS sources over the declared `.js` build output.
+ */
+function resolveSourceFile(candidate) {
+    const ext = path.extname(candidate).toLowerCase();
+    if (ext && JS_TO_SRC[ext]) {
+        const base = candidate.slice(0, candidate.length - ext.length);
+        for (const e of JS_TO_SRC[ext]) {
+            if (existsFileSync(base + e))
+                return base + e;
+        }
+    }
+    if (existsFileSync(candidate))
+        return candidate;
+    for (const e of SRC_EXTS)
+        if (existsFileSync(candidate + e))
+            return candidate + e;
+    for (const e of SRC_EXTS) {
+        const idx = path.join(candidate, `index${e}`);
+        if (existsFileSync(idx))
+            return idx;
+    }
+    return null;
+}
+/** Pick the source entry file of a package, preferring real source over dist. */
+function packageEntry(pkgDir, pkg) {
+    const candidates = [];
+    // explicit source-ish fields first
+    for (const f of [pkg?.source, pkg?.module, pkg?.types, pkg?.typings, pkg?.main]) {
+        if (typeof f === "string")
+            candidates.push(f);
+    }
+    // exports["."] as a string or { source/import/default/types }
+    const dot = pkg?.exports?.["."] ?? pkg?.exports;
+    if (typeof dot === "string")
+        candidates.push(dot);
+    else if (dot && typeof dot === "object") {
+        for (const k of ["source", "import", "default", "types"]) {
+            if (typeof dot[k] === "string")
+                candidates.push(dot[k]);
+        }
+    }
+    // conventional source roots
+    candidates.push("src/index.ts", "src/index.tsx", "src/index.js", "index.ts", "index.tsx", "index.js");
+    for (const c of candidates) {
+        const resolved = resolveSourceFile(path.resolve(pkgDir, c));
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+/**
+ * Resolve a bare import specifier to an in-monorepo source file when it targets
+ * a workspace package. Handles exact package imports (`@org/utils`) and subpaths
+ * (`@org/utils/helpers`). Returns null for non-workspace (external) specifiers.
+ */
+export function resolveWorkspaceImport(importFrom, rootAbs, info) {
+    if (importFrom.startsWith("."))
+        return null; // relative, not a package import
+    let match = null;
+    let subpath = "";
+    for (const p of info.packages) {
+        if (importFrom === p.name) {
+            match = p;
+            subpath = "";
+            break;
+        }
+        if (importFrom.startsWith(p.name + "/")) {
+            match = p;
+            subpath = importFrom.slice(p.name.length + 1);
+            break;
+        }
+    }
+    if (!match)
+        return null;
+    const pkgDir = path.resolve(rootAbs, match.dir);
+    const pj = readJson(path.join(pkgDir, "package.json"));
+    const entry = packageEntry(pkgDir, pj);
+    if (!subpath)
+        return entry;
+    // Subpath import (`@org/utils/helpers`): resolve against the source root
+    // (the entry file's directory, typically `src/`) first, then the package dir.
+    const srcRoot = entry ? path.dirname(entry) : pkgDir;
+    return (resolveSourceFile(path.resolve(srcRoot, subpath)) ??
+        resolveSourceFile(path.resolve(pkgDir, subpath)));
+}
+/* ─── Cached per-root workspace index (for resolvers) ──────────────────────── */
+const workspaceCache = new Map();
+/** Discover (and cache) the workspace for a root, then resolve a package import. */
+export function resolveWorkspaceImportCached(importFrom, rootAbs) {
+    if (importFrom.startsWith("."))
+        return null;
+    const key = path.resolve(rootAbs);
+    let info = workspaceCache.get(key);
+    if (!info) {
+        info = discoverWorkspace(key);
+        workspaceCache.set(key, info);
+    }
+    if (info.packages.length === 0)
+        return null;
+    return resolveWorkspaceImport(importFrom, key, info);
+}
+/** Test/debug hook: drop the cached workspace index. */
+export function clearWorkspaceCache() {
+    workspaceCache.clear();
+}

package/package.json

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