universal-ast-mapper 1.0.0 → 1.1.0

package/README.md

@@ -97,6 +97,7 @@ 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 workspace [dir]            [alias: ws]
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -325,6 +326,22 @@ Scan a file or directory for **named functions/methods with parameters that are
 
 ---
 
+### `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.
+
+```json
+{
+  "tool": "npm", "packageCount": 3,
+  "packages": [ { "name": "@demo/a", "dir": "packages/a", "internalDeps": ["@demo/b"] } ],
+  "edges": [ { "from": "@demo/a", "to": "@demo/b" } ],
+  "packageCycles": []
+}
+```
+
+**Params:** `path` (optional, defaults to root)
+
+---
+
 ### `get_change_impact`
 Given a file + symbol, reverse-traverse the import graph to compute **blast radius**.
 
@@ -586,6 +603,7 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **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**. |
 | **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. |

package/dist/cli.js

@@ -13,6 +13,7 @@ import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTop
 import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
+import { discoverWorkspace, findPackageCycles } from "./workspace.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
@@ -369,6 +370,40 @@ program
     }
     console.log();
 });
+// ─── Command: workspace ───────────────────────────────────────────────────────
+program
+    .command("workspace [dir]")
+    .alias("ws")
+    .description("Discover monorepo packages and their internal dependency graph")
+    .option("--json", "Output as JSON")
+    .action(async (dir, opts) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const info = discoverWorkspace(abs);
+    const cycles = findPackageCycles(info);
+    if (opts.json) {
+        return jsonOut({ root: rel, tool: info.tool, packageCount: info.packages.length, packages: info.packages, edges: info.edges, packageCycles: cycles });
+    }
+    header(`Workspace — ${rel}/  ${dim(`(${info.tool}, ${info.packages.length} package(s))`)}`);
+    if (info.packages.length === 0) {
+        console.log(indent(dim("No workspace packages found (no workspaces/pnpm-workspace.yaml/lerna.json).")));
+    }
+    else {
+        table(info.packages.map((p) => [
+            p.name,
+            p.dir,
+            p.internalDeps.length > 0 ? yellow(`→ ${p.internalDeps.join(", ")}`) : dim("(no internal deps)"),
+        ]), [["Package", 24], ["Dir", 22], ["Internal deps", 34]]);
+        if (cycles.length > 0) {
+            console.log(`\n${indent(bold(yellow("Circular package dependencies:")))}`);
+            for (const c of cycles)
+                console.log(indent(`${yellow("↻")}  ${c.join(dim(" → "))}`));
+        }
+        console.log(`\n  ${info.edges.length} internal edge(s)` + (cycles.length ? ` · ${yellow(`${cycles.length} cycle(s)`)}` : ""));
+    }
+    console.log();
+});
 // ─── Command: trace-type ──────────────────────────────────────────────────────
 program
     .command("trace-type <type> [dir]")

package/dist/index.js

@@ -18,6 +18,7 @@ import { searchSymbols } from "./search.js";
 import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
+import { discoverWorkspace, findPackageCycles } from "./workspace.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) {
@@ -714,6 +715,36 @@ server.registerTool("trace_type", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: analyze_workspace ───────────────────────────── */
+server.registerTool("analyze_workspace", {
+    title: "Analyze a monorepo workspace",
+    description: "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.",
+    inputSchema: {
+        path: z.string().optional().describe("Workspace root directory. Defaults to the project root."),
+    },
+}, async ({ path: input }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. analyze_workspace requires a directory.`);
+        }
+        const info = discoverWorkspace(abs);
+        const cycles = findPackageCycles(info);
+        return jsonText({
+            root: rel.split(path.sep).join("/") || ".",
+            tool: info.tool,
+            packageCount: info.packages.length,
+            packages: info.packages,
+            edges: info.edges,
+            packageCycles: cycles,
+        });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_change_impact ───────────────────────────── */
 server.registerTool("get_change_impact", {
     title: "Get change impact (blast radius)",

package/dist/workspace.js

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage"]);
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Minimal `packages:` list reader for pnpm-workspace.yaml (no YAML dep). */
+function readPnpmPatterns(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    let inPackages = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, "");
+        if (/^packages\s*:/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages) {
+            const m = line.match(/^\s*-\s*['"]?([^'"]+?)['"]?\s*$/);
+            if (m)
+                out.push(m[1].trim());
+            else if (/^\S/.test(line))
+                break; // next top-level key
+        }
+    }
+    return out;
+}
+/** Expand a workspace glob pattern to package directories containing package.json. */
+function expandPattern(rootAbs, pattern) {
+    const clean = pattern.replace(/\/+$/, "");
+    const dirs = [];
+    const hasPkg = (dir) => fs.existsSync(path.join(dir, "package.json"));
+    if (!clean.includes("*")) {
+        const abs = path.resolve(rootAbs, clean);
+        if (hasPkg(abs))
+            dirs.push(abs);
+        return dirs;
+    }
+    if (clean.endsWith("/**")) {
+        const base = path.resolve(rootAbs, clean.slice(0, -3));
+        walkForPackages(base, dirs, 6);
+        return dirs;
+    }
+    // `prefix/*` — immediate subdirectories.
+    if (clean.endsWith("/*")) {
+        const base = path.resolve(rootAbs, clean.slice(0, -2));
+        let entries = [];
+        try {
+            entries = fs.readdirSync(base, { withFileTypes: true });
+        }
+        catch {
+            return dirs;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !IGNORE_DIRS.has(e.name) && hasPkg(path.join(base, e.name))) {
+                dirs.push(path.join(base, e.name));
+            }
+        }
+        return dirs;
+    }
+    // Fallback: bounded recursive scan under the non-glob prefix.
+    const prefix = clean.split("*")[0];
+    walkForPackages(path.resolve(rootAbs, prefix), dirs, 6);
+    return dirs;
+}
+function walkForPackages(base, out, depth) {
+    if (depth < 0)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    if (fs.existsSync(path.join(base, "package.json")))
+        out.push(base);
+    for (const e of entries) {
+        if (e.isDirectory() && !IGNORE_DIRS.has(e.name)) {
+            walkForPackages(path.join(base, e.name), out, depth - 1);
+        }
+    }
+}
+function depNames(pkg) {
+    const out = new Set();
+    for (const key of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const d = pkg?.[key];
+        if (d && typeof d === "object")
+            for (const k of Object.keys(d))
+                out.add(k);
+    }
+    return [...out];
+}
+/**
+ * Discover the packages in a JS/TS monorepo and the dependency edges between
+ * them. Supports npm/yarn `workspaces`, pnpm-workspace.yaml, and lerna.json.
+ */
+export function discoverWorkspace(rootAbs) {
+    const rootPkg = readJson(path.join(rootAbs, "package.json"));
+    let tool = "none";
+    const patterns = [];
+    // npm / yarn workspaces
+    const ws = rootPkg?.workspaces;
+    if (Array.isArray(ws)) {
+        patterns.push(...ws);
+        tool = "npm";
+    }
+    else if (ws && Array.isArray(ws.packages)) {
+        patterns.push(...ws.packages);
+        tool = "npm";
+    }
+    // pnpm
+    const pnpmFile = path.join(rootAbs, "pnpm-workspace.yaml");
+    if (fs.existsSync(pnpmFile)) {
+        patterns.push(...readPnpmPatterns(pnpmFile));
+        tool = "pnpm";
+    }
+    // lerna
+    const lerna = readJson(path.join(rootAbs, "lerna.json"));
+    if (lerna && Array.isArray(lerna.packages)) {
+        patterns.push(...lerna.packages);
+        if (tool === "none")
+            tool = "lerna";
+    }
+    // Dedupe patterns, expand to package dirs.
+    const dirSet = new Set();
+    for (const p of [...new Set(patterns)]) {
+        for (const d of expandPattern(rootAbs, p))
+            dirSet.add(d);
+    }
+    const packages = [];
+    const nameToPkg = new Map();
+    const pending = [];
+    for (const dirAbs of [...dirSet].sort()) {
+        const pj = readJson(path.join(dirAbs, "package.json"));
+        if (!pj || !pj.name)
+            continue;
+        const rel = path.relative(rootAbs, dirAbs).split(path.sep).join("/");
+        const allDeps = depNames(pj);
+        const wp = { name: pj.name, dir: rel || ".", internalDeps: [], allDeps };
+        packages.push(wp);
+        nameToPkg.set(pj.name, wp);
+        pending.push({ pkg: wp, deps: allDeps });
+    }
+    // Resolve internal deps now that all package names are known.
+    const edges = [];
+    for (const { pkg, deps } of pending) {
+        for (const d of deps) {
+            if (nameToPkg.has(d) && d !== pkg.name) {
+                pkg.internalDeps.push(d);
+                edges.push({ from: pkg.name, to: d });
+            }
+        }
+        pkg.internalDeps.sort();
+    }
+    return { root: rootAbs, tool, packages, edges };
+}
+/** Detect circular dependencies among workspace packages (package-level). */
+export function findPackageCycles(info) {
+    const adj = new Map();
+    for (const p of info.packages)
+        adj.set(p.name, p.internalDeps.slice());
+    const color = new Map();
+    for (const k of adj.keys())
+        color.set(k, "white");
+    const cycles = [];
+    const seen = new Set();
+    const path = [];
+    const dfs = (node) => {
+        color.set(node, "gray");
+        path.push(node);
+        for (const next of adj.get(node) ?? []) {
+            const c = color.get(next);
+            if (c === "gray") {
+                const start = path.indexOf(next);
+                const raw = path.slice(start);
+                const min = raw.reduce((b, n, i) => (n < raw[b] ? i : b), 0);
+                const canon = [...raw.slice(min), ...raw.slice(0, min)];
+                const key = canon.join(">");
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    cycles.push([...canon, canon[0]]);
+                }
+            }
+            else if (c === "white") {
+                dfs(next);
+            }
+        }
+        path.pop();
+        color.set(node, "black");
+    };
+    for (const k of adj.keys())
+        if (color.get(k) === "white")
+            dfs(k);
+    return cycles;
+}

package/package.json

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