universal-ast-mapper 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.24.0] — 2026-06-10 · TS path-alias resolution
+- Bare imports like `@/components/Button` now resolve through **`tsconfig.json` /
+  `jsconfig.json` `compilerOptions.paths`** (+ `baseUrl`): nearest-config lookup above
+  the importing file (monorepo-safe, per-process cached), relative `extends` chains
+  (child `paths` replace the parent's, per TS semantics), longest-prefix pattern
+  matching, candidate probing with the usual extension/index logic.
+- **String-aware JSONC parser** — comments/trailing commas are stripped with a
+  character walk, not regex (naive stripping corrupts Next.js configs where `"@/*"`
+  pairs with the `*/` inside `"**/*.ts"` include globs).
+- Wired into `resolve_imports` (aliased imports report `importKind: "relative"` +
+  resolved file), `build_symbol_graph` (alias edges before workspace-package fallback),
+  and the call graph (callee origin + reverse `calledBy`).
+- Real-world effect (Next.js app, 186 files): import graph 31 → **324 edges**;
+  dead exports 210 → 153; god nodes now reflect true usage.
+- New module `tsconfig` (`aliasCandidates`, `clearAliasCaches`) + `resolveAliasedImport`
+  in the resolver. Tests: new `test/tsalias-smoke.mjs` (15 checks), wired into `npm test`.
+
 ## [1.23.0] — 2026-06-10 · Configurable root boundary (multi-root + unlocked)
 - **`AST_MAP_ROOT` accepts multiple roots**, separated by the OS path delimiter
   (`;` Windows / `:` POSIX). The first root is primary; absolute paths inside any

package/README.md

@@ -20,7 +20,7 @@ Built on [tree-sitter](https://tree-sitter.github.io/) WASM grammars. Zero regex
 > As of v0.8.2, all four v0.8.0 languages have **cross-file graph + resolver** wiring: Kotlin (FQCN/package index), C/C++ (`#include` with header↔impl pairing), and Swift (module = directory under `Sources/`). Call-graph callee origin is resolved for Kotlin; for C/C++/Swift it stays limited because their imports don't name individual symbols. (PHP & Ruby landed in v1.22.0 — symbol extraction + imports; cross-file graph wiring for them is the next step. Ruby was unblocked by upgrading `web-tree-sitter` to 0.21.0.)
 
 Each language uses the resolution strategy that fits it:
-- **TS/JS/Python** — relative paths (`./foo`, `..mod`) resolved against the importing file's directory, with TS-ESM `.js` → `.ts` rewriting.
+- **TS/JS/Python** — relative paths (`./foo`, `..mod`) resolved against the importing file's directory, with TS-ESM `.js` → `.ts` rewriting. **Path aliases** (`@/*` etc.) resolve via the nearest `tsconfig.json`/`jsconfig.json` (`paths` + `baseUrl`, relative `extends`). *(v1.24.0)*
 - **Go** — `go.mod` ancestor lookup → module path prefix → package directory → all `.go` files (skips `_test.go`).
 - **Rust** — `Cargo.toml` ancestor → `crate::` / `self::` / `super::` walks; supports `mod.rs` + Rust-2018 sibling-dir style.
 - **Java** — project-wide FQCN index (`package + "." + className → file`) built lazily on first cross-lang call; supports wildcard imports.
@@ -801,6 +801,7 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.24.0** | **TS path-alias resolution** — bare imports like `@/components/Button` now resolve via the **nearest** `tsconfig.json`/`jsconfig.json` (`compilerOptions.paths` + `baseUrl`, relative `extends` chains, longest-prefix matching, string-aware JSONC parser). Wired into `resolve_imports`, the symbol graph, and the call graph — on a real Next.js app this took the import graph from 31 to **324 edges** and cut false dead-exports by ~30%. |
 | **1.23.0** | **Configurable root boundary** — `AST_MAP_ROOT` accepts **multiple roots** (path-delimiter separated) and `AST_MAP_UNLOCKED=1` allows analyzing **any absolute path** on request (default stays locked). Analysis/graph/report rel-paths now computed against the matched root, so cross-root results are correct. New `roots` module + 13-check test suite. |
 | **1.22.0** | **PHP & Ruby support** — `.php` (classes, interfaces, traits, enums, methods with visibility, `use` imports incl. grouped, require/include) and `.rb`/`.rake` (classes, modules, methods, `self.` singleton methods, `private` section tracking, require/require_relative). Unblocked by upgrading `web-tree-sitter` 0.20.8 → 0.21.0 (all existing grammars re-verified). **16 languages**. |
 | **1.21.0** | **Quality gate** — `ast-map check` fails CI when quality regresses: **baseline ratchet** vs `.ast-map.baseline.json` (cycles · dead exports · SDP · very-high complexity · score; `--update-baseline` re-anchors) + absolute thresholds (flags or config `"check"`). New MCP tool `check_quality_gate` (**28 tools**); GitHub Action gains `mode: check`. |

package/dist/callgraph.js

@@ -4,7 +4,7 @@ import { parseSource } from "./parser.js";
 import { buildSkeleton } from "./skeleton.js";
 import { resolveOptions, loadProjectConfig } from "./config.js";
 import { detectLanguage } from "./registry.js";
-import { resolveImportPath, getOrBuildCrossLangIndex } from "./resolver.js";
+import { resolveImportPath, resolveAliasedImport, getOrBuildCrossLangIndex } from "./resolver.js";
 import { resolveCrossLangTarget } from "./crosslang.js";
 const CROSS_LANG = new Set(["java", "csharp", "rust", "go", "kotlin", "c", "cpp", "swift"]);
 function pushCall(out, callee, anchor) {
@@ -313,8 +313,14 @@ export async function buildCallGraph(filePath, funcName, root, allSkeletons) {
                 }
             }
             else {
-                call.isExternal = true;
-                call.calleeFileRel = importRef.from;
+                const aliasAbs = resolveAliasedImport(importRef.from, filePath);
+                if (aliasAbs) {
+                    call.calleeFileRel = path.relative(root, aliasAbs).split(path.sep).join("/");
+                }
+                else {
+                    call.isExternal = true;
+                    call.calleeFileRel = importRef.from;
+                }
             }
         }
         else if (aliasOrigin) {
@@ -326,8 +332,14 @@ export async function buildCallGraph(filePath, funcName, root, allSkeletons) {
                 }
             }
             else {
-                call.isExternal = true;
-                call.calleeFileRel = aliasOrigin;
+                const aliasAbs = resolveAliasedImport(aliasOrigin, filePath);
+                if (aliasAbs) {
+                    call.calleeFileRel = path.relative(root, aliasAbs).split(path.sep).join("/");
+                }
+                else {
+                    call.isExternal = true;
+                    call.calleeFileRel = aliasOrigin;
+                }
             }
         }
         else if (crossIndex && skel.language === "csharp") {
@@ -387,8 +399,10 @@ export async function buildCallGraph(filePath, funcName, root, allSkeletons) {
                         break;
                     }
                 }
-                else if (imp.from.startsWith(".")) {
-                    const resolvedAbs = resolveImportPath(imp.from, otherAbs);
+                else {
+                    const resolvedAbs = imp.from.startsWith(".")
+                        ? resolveImportPath(imp.from, otherAbs)
+                        : resolveAliasedImport(imp.from, otherAbs);
                     if (!resolvedAbs)
                         continue;
                     const resolvedRel = path.relative(root, resolvedAbs).split(path.sep).join("/");

package/dist/graph.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { resolveImportPath } from "./resolver.js";
+import { resolveImportPath, resolveAliasedImport } from "./resolver.js";
 import { resolveWorkspaceImportCached } from "./workspace.js";
 import { buildCrossLangIndex, resolveCrossLangTarget, } from "./crosslang.js";
 // ─── Internal helpers ─────────────────────────────────────────────────────────
@@ -38,7 +38,7 @@ function wirePathImport(skel, imp, fromFileAbs, root, exportedSymbolMap, edges)
     // Relative import → path resolve; bare specifier → monorepo workspace package.
     const resolvedAbs = imp.from.startsWith(".")
         ? resolveImportPath(imp.from, fromFileAbs)
-        : resolveWorkspaceImportCached(imp.from, root);
+        : resolveAliasedImport(imp.from, fromFileAbs) ?? resolveWorkspaceImportCached(imp.from, root);
     if (!resolvedAbs)
         return;
     const resolvedRel = path.relative(root, resolvedAbs).split(path.sep).join("/");

package/dist/resolver.js

@@ -5,6 +5,7 @@ import { resolveOptions } from "./config.js";
 import { findSymbol } from "./analysis.js";
 import { buildCrossLangIndex, resolveCrossLangTarget, } from "./crosslang.js";
 import { resolveWorkspaceImportCached } from "./workspace.js";
+import { aliasCandidates } from "./tsconfig.js";
 const SRC_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".vue", ".svelte"];
 function extractParams(sig) {
     const start = sig.indexOf("(");
@@ -46,6 +47,10 @@ export function resolveImportPath(importFrom, fromAbs) {
                 return p;
         }
     }
+    return probeCandidate(candidate);
+}
+/** Probe a path base: exact file → +extensions → /index.<ext>. */
+function probeCandidate(candidate) {
     try {
         const stat = fs.statSync(candidate);
         if (stat.isFile())
@@ -64,6 +69,28 @@ export function resolveImportPath(importFrom, fromAbs) {
     }
     return null;
 }
+/**
+ * Resolve a tsconfig/jsconfig path-aliased bare import (e.g. `@/components/X`
+ * with `"@/*": ["./src/*"]`) to an absolute file path, using the nearest
+ * config above the importing file. Returns null when not an alias.
+ */
+export function resolveAliasedImport(importFrom, fromAbs) {
+    for (const base of aliasCandidates(importFrom, fromAbs)) {
+        const declaredExt = path.extname(base).toLowerCase();
+        if (declaredExt && JS_TO_TS[declaredExt]) {
+            const stem = base.slice(0, base.length - declaredExt.length);
+            for (const ext of JS_TO_TS[declaredExt]) {
+                const p = stem + ext;
+                if (fs.existsSync(p))
+                    return p;
+            }
+        }
+        const hit = probeCandidate(base);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
 /* ─── Cross-language index cache ──────────────────────────────────────────── */
 // Java/C# need a project-wide index to resolve fully-qualified imports.
 // Built lazily on first cross-language resolve, then reused for the process
@@ -124,6 +151,8 @@ async function enrichRelativeImport(imp, fromAbs, root) {
     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 = resolveAliasedImport(imp.from, fromAbs);
     if (!resolvedAbs && isBare)
         resolvedAbs = resolveWorkspaceImportCached(imp.from, root);
     const treatedExternal = isBare && !resolvedAbs;

package/dist/tsconfig.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG_NAMES = ["tsconfig.json", "jsconfig.json"];
+/**
+ * Tolerant JSONC parse. String-aware: comments and trailing commas are removed
+ * with a character walk, never with regex — naive stripping corrupts configs
+ * whose strings contain comment-like text (e.g. Next.js `"include": ["**\/*.ts"]`
+ * pairs the `/*` inside `"@/*"` with the `*\/` inside the glob).
+ */
+function parseJsonc(raw) {
+    let out = "";
+    let i = 0;
+    let inStr = false;
+    while (i < raw.length) {
+        const c = raw[i];
+        if (inStr) {
+            out += c;
+            if (c === "\\") {
+                out += raw[i + 1] ?? "";
+                i += 2;
+                continue;
+            }
+            if (c === '"')
+                inStr = false;
+            i++;
+        }
+        else if (c === '"') {
+            inStr = true;
+            out += c;
+            i++;
+        }
+        else if (c === "/" && raw[i + 1] === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i++;
+        }
+        else if (c === "/" && raw[i + 1] === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i++;
+            i += 2;
+        }
+        else if (c === ",") {
+            // trailing comma: skip when the next non-whitespace char closes a scope
+            let j = i + 1;
+            while (j < raw.length && /\s/.test(raw[j]))
+                j++;
+            if (raw[j] === "}" || raw[j] === "]")
+                i++; // drop the comma
+            else {
+                out += c;
+                i++;
+            }
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    try {
+        return JSON.parse(out);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read a config file, following relative `extends` (child overrides parent). */
+function readConfigChain(configPath, depth = 0) {
+    if (depth > 5)
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const json = parseJsonc(raw);
+    if (!json || typeof json !== "object")
+        return null;
+    const dir = path.dirname(configPath);
+    let baseUrl;
+    let paths;
+    let baseDir = dir;
+    const ext = json.extends;
+    if (typeof ext === "string" && ext.startsWith(".")) {
+        let parentPath = path.resolve(dir, ext);
+        if (!parentPath.endsWith(".json"))
+            parentPath += ".json";
+        const parent = readConfigChain(parentPath, depth + 1);
+        if (parent) {
+            baseUrl = parent.baseUrl;
+            paths = parent.paths;
+            baseDir = parent.dir; // paths in a parent resolve against the parent's dir
+        }
+    }
+    const co = json.compilerOptions;
+    if (co && typeof co === "object") {
+        if (typeof co.baseUrl === "string") {
+            baseUrl = co.baseUrl;
+            baseDir = dir;
+        }
+        if (co.paths && typeof co.paths === "object") {
+            paths = co.paths;
+            baseDir = dir;
+        }
+    }
+    return { baseUrl, paths, dir: baseDir };
+}
+function buildAliasConfig(configPath) {
+    const merged = readConfigChain(configPath);
+    if (!merged || !merged.paths)
+        return null;
+    const base = path.resolve(merged.dir, merged.baseUrl ?? ".");
+    const patterns = [];
+    for (const [key, targets] of Object.entries(merged.paths)) {
+        if (!Array.isArray(targets) || targets.length === 0)
+            continue;
+        const star = key.indexOf("*");
+        const abs = targets
+            .filter((t) => typeof t === "string")
+            .map((t) => path.resolve(base, t));
+        if (abs.length === 0)
+            continue;
+        if (star === -1) {
+            patterns.push({ prefix: key, suffix: "", exact: true, targets: abs });
+        }
+        else {
+            patterns.push({ prefix: key.slice(0, star), suffix: key.slice(star + 1), exact: false, targets: abs });
+        }
+    }
+    // Longest prefix wins (TypeScript's matching rule).
+    patterns.sort((a, b) => b.prefix.length - a.prefix.length);
+    return patterns.length > 0 ? { patterns } : null;
+}
+// dir → config path (or null when none found up the tree)
+const configPathCache = new Map();
+// config path → parsed alias config (or null when it has no paths)
+const aliasCache = new Map();
+function findNearestConfig(fromDir) {
+    const cached = configPathCache.get(fromDir);
+    if (cached !== undefined)
+        return cached;
+    let dir = fromDir;
+    let result = null;
+    const visited = [];
+    for (;;) {
+        const hit = configPathCache.get(dir);
+        if (hit !== undefined) {
+            result = hit;
+            break;
+        }
+        visited.push(dir);
+        let found = null;
+        for (const name of CONFIG_NAMES) {
+            const p = path.join(dir, name);
+            if (fs.existsSync(p)) {
+                found = p;
+                break;
+            }
+        }
+        if (found) {
+            result = found;
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir || dir.includes("node_modules")) {
+            result = null;
+            break;
+        }
+        dir = parent;
+    }
+    for (const d of visited)
+        configPathCache.set(d, result);
+    return result;
+}
+/** Test-only: clear the per-process caches. */
+export function clearAliasCaches() {
+    configPathCache.clear();
+    aliasCache.clear();
+}
+/**
+ * Map an aliased bare import to absolute candidate base paths (no extension
+ * probing). Empty array = not an alias / no config / no pattern match.
+ */
+export function aliasCandidates(importFrom, fromAbs) {
+    if (importFrom.startsWith(".") || path.isAbsolute(importFrom))
+        return [];
+    const configPath = findNearestConfig(path.dirname(fromAbs));
+    if (!configPath)
+        return [];
+    let cfg = aliasCache.get(configPath);
+    if (cfg === undefined) {
+        cfg = buildAliasConfig(configPath);
+        aliasCache.set(configPath, cfg);
+    }
+    if (!cfg)
+        return [];
+    for (const p of cfg.patterns) {
+        if (p.exact) {
+            if (importFrom === p.prefix)
+                return p.targets;
+            continue;
+        }
+        if (importFrom.length >= p.prefix.length + p.suffix.length &&
+            importFrom.startsWith(p.prefix) &&
+            importFrom.endsWith(p.suffix)) {
+            const star = importFrom.slice(p.prefix.length, importFrom.length - p.suffix.length);
+            return p.targets.map((t) => t.replace("*", star));
+        }
+    }
+    return [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "smoke": "node test/smoke.mjs",
-    "test": "node test/smoke.mjs && node test/analysis.mjs && node test/cache-smoke.mjs && node test/check-smoke.mjs && node test/roots-smoke.mjs",
+    "test": "node test/smoke.mjs && node test/analysis.mjs && node test/cache-smoke.mjs && node test/check-smoke.mjs && node test/roots-smoke.mjs && node test/tsalias-smoke.mjs",
     "postinstall": "node scripts/install-skill.mjs"
   },
   "engines": {