universal-ast-mapper 1.19.0 → 1.22.1

package/CHANGELOG.md

@@ -6,6 +6,45 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.22.1] — 2026-06-10 · Docs
+- README refreshed to match v1.20–1.22: 28 tools / 30 commands, PHP+Ruby capability
+  columns, `cache`/`check` CLI + config + env-var docs, `check_quality_gate` reference,
+  Action `mode: check` example, new Performance section. No code changes.
+
+## [1.22.0] — 2026-06-10 · PHP & Ruby support
+- **PHP** (`.php`): classes/interfaces/traits/enums, methods with visibility modifiers,
+  class consts + properties, namespaces; imports from `use` (incl. grouped `use A\{B, C}`
+  and aliases) and `require`/`include` (side-effect).
+- **Ruby** (`.rb`, `.rake`): classes, modules (→ namespace), methods, `self.` singleton
+  methods, constants; **section-style visibility** (`private`/`protected`/`public`);
+  imports from `require` / `require_relative`.
+- **web-tree-sitter 0.20.8 → 0.21.0** — unblocks the Ruby grammar (external-scanner
+  crash on the old runtime); no API change, all grammars + suites re-verified.
+- Tests: `Sample.php` + `sample.rb` fixtures, 30 new smoke assertions. **16 languages.**
+
+## [1.21.0] — 2026-06-10 · Quality gate (`ast-map check`)
+- **`ast-map check [dir]`** — CI quality gate with two mechanisms: a **baseline ratchet**
+  (vs a committed `.ast-map.baseline.json`; fails when cycles, dead exports, SDP violations,
+  very-high-complexity functions rise or the health score drops; `--update-baseline`
+  re-anchors) and **absolute thresholds** (CLI flags or `.ast-map.config.json` → `"check"`).
+  Non-zero exit on failure; `--json` for tooling.
+- New MCP tool **`check_quality_gate`** (28 tools) — same gate for agents.
+- **GitHub Action**: `mode: validate | check | both` + `check-args` inputs.
+- New module `check` (`runQualityGate`, `metricsFromReport`); `AstMapConfig.check`.
+- Tests: new `test/check-smoke.mjs` (13 checks), wired into `npm test`.
+
+## [1.20.0] — 2026-06-10 · Incremental cache + parallel parsing
+- **Persistent parse cache**: skeletons are cached on disk under `<root>/.ast-map/cache`,
+  keyed by content hash + detail + schema/grammar versions — never stale by construction,
+  survives across processes (warm hits on large files ~60× faster than a re-parse).
+  On by default; disable with `AST_MAP_NO_CACHE=1` or `"cache": false` in config.
+- **Parallel parsing**: bulk scans distribute work over a worker-thread pool
+  (auto-sized, engages at ≥ 64 files, `AST_MAP_WORKERS` override, sequential fallback
+  on any worker failure). `report` computes per-file complexity in the workers too.
+- New CLI command `ast-map cache [stats|clear]`.
+- New modules `diskcache` and `pool` (`buildSkeletonsBulk`); `AstMapConfig.cache`.
+- Tests: new `test/cache-smoke.mjs` (18 checks), wired into `npm test`.
+
 ## [1.19.0] — 2026-06-09 · Dashboard: coupling + SDP
 - The health dashboard (`ast-map report` / `get_codebase_report`) now surfaces the
   v1.14–1.16 architecture metrics: a **Module coupling** card (per-directory instability

package/README.md

@@ -4,20 +4,20 @@ An **MCP server + CLI tool** that turns source code into structured, machine-rea
 
 Built on [tree-sitter](https://tree-sitter.github.io/) WASM grammars. Zero regex guessing — real AST parsing.
 
-**27 MCP tools / 28 CLI commands / 5 MCP prompts** spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators — plus monorepo support, an interactive **graph explorer** (`ast-map explore`), **watch mode**, and a one-page **health dashboard** (`ast-map report`).
+**28 MCP tools / 30 CLI commands / 5 MCP prompts** spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators — plus monorepo support, an interactive **graph explorer** (`ast-map explore`), **watch mode**, a one-page **health dashboard** (`ast-map report`), a **persistent parse cache + parallel parsing** (warm re-scans skip parsing entirely), and a **CI quality gate** (`ast-map check`, baseline ratchet).
 
-**Supported languages:** TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go · Rust · Java · C# · C · C++ · Kotlin · Swift · **Vue** · **Svelte** (SFC `<script>`)
+**Supported languages:** TypeScript · TSX · JavaScript (ESM/CJS) · Python · Go · Rust · Java · C# · C · C++ · Kotlin · Swift · Vue · Svelte (SFC `<script>`) · **PHP** · **Ruby**
 
-| Capability               | TS/JS | Python | Go  | Rust | Java | C#  | C   | C++ | Kt  | Swift |
-|--------------------------|:-----:|:------:|:---:|:----:|:----:|:---:|:---:|:---:|:---:|:-----:|
-| Symbol extraction        | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    |
-| Imports parsing          | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    |
-| Graph `imports` edges    | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    |
-| `resolve_imports` enrich | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    |
-| Call graph callee origin | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | —   | —   | ✅  | —     |
-| Reverse `calledBy`       | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | —   | —   | ✅  | —     |
+| Capability               | TS/JS | Python | Go  | Rust | Java | C#  | C   | C++ | Kt  | Swift | PHP | Ruby |
+|--------------------------|:-----:|:------:|:---:|:----:|:----:|:---:|:---:|:---:|:---:|:-----:|:---:|:----:|
+| Symbol extraction        | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    | ✅  | ✅   |
+| Imports parsing          | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    | ✅  | ✅   |
+| Graph `imports` edges    | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    | —   | —    |
+| `resolve_imports` enrich | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | ✅  | ✅  | ✅  | ✅    | —   | —    |
+| Call graph callee origin | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | —   | —   | ✅  | —     | —   | —    |
+| Reverse `calledBy`       | ✅    | ✅     | ✅  | ✅   | ✅   | ✅  | —   | —   | ✅  | —     | —   | —    |
 
-> 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. (Ruby grammar in `tree-sitter-wasms@0.1.13` is unstable and was skipped.)
+> 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.
@@ -110,6 +110,8 @@ ast-map pack      <file> [symbol]  [--scan <d>] # minimal context pack
 ast-map coupling  [dir]            [-n N]        # Ca / Ce / instability per file
 ast-map layers    [dir]            [-g gap]      # SDP: stable→volatile violations
 ast-map modules   [dir]                          # directory-level coupling + edges
+ast-map cache     [stats|clear]                  # persistent parse cache (.ast-map/cache)
+ast-map check     [dir]            [--update-baseline] [--min-score N] [--max-cycles N] ...
 ast-map search   <pattern> [dir]   [-m contains|exact|regex] [-k kind] [-e]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
@@ -524,6 +526,13 @@ Thresholds can be set per-call or in `.ast-map.config.json`.
 
 ---
 
+### `check_quality_gate`
+Run the CI quality gate: **absolute thresholds** (from `.ast-map.config.json` → `"check"`) plus a **baseline ratchet** against `.ast-map.baseline.json` — fails when cycles, dead exports, SDP violations, very-high-complexity functions rise, or the health score drops. Set `updateBaseline` to re-anchor at the current metrics. Same engine as `ast-map check`.
+
+**Params:** `path`, `baseline`, `updateBaseline`
+
+---
+
 ### `get_top_symbols`
 Return the N most-imported symbols — your codebase's "God Nodes" where a breaking change has maximum blast radius.
 
@@ -540,18 +549,44 @@ Place in your project root. All fields optional.
   "ignore": ["dist", "coverage", ".turbo"],
   "maxFileBytes": 500000,
   "outputDir": ".ast-map",
+  "cache": true,
   "rules": {
     "large-file":       { "maxLines": 400 },
     "too-many-imports": { "maxImports": 20 },
     "god-export":       { "maxExports": 15 }
+  },
+  "check": {
+    "maxCycles": 0,
+    "maxSdpViolations": 10,
+    "minScore": 70
   }
 }
 ```
 
+- `cache` — persistent parse cache in `<root>/.ast-map/cache` (default `true`; also disabled by `AST_MAP_NO_CACHE=1`). Inspect/clear with `ast-map cache [stats|clear]`.
+- `check` — default thresholds for `ast-map check` / `check_quality_gate`; CLI flags override per run.
+
 The config is read live — changes take effect on the next call without restarting the MCP server.
 
 ---
 
+## Performance — cache & parallel parsing
+
+Since **v1.20.0**, bulk scans are fast twice over:
+
+- **Persistent parse cache** — every parsed file's skeleton is stored under `<root>/.ast-map/cache`, keyed by a SHA-1 of its content + detail + schema/grammar versions. A changed file hashes to a new key, so entries are **never stale by construction**, and the cache survives across processes — a re-run on an unchanged repo skips parsing entirely (warm hits on large files ≈ 60× faster).
+- **Worker-thread parallel parsing** — batches of ≥ 64 files are distributed over a pool sized from your CPU count (max 8); smaller batches stay sequential so there's no startup-cost penalty. Any worker failure falls back to sequential parsing.
+
+| Env var | Effect |
+|---------|--------|
+| `AST_MAP_NO_CACHE=1` | disable the disk cache for this run |
+| `AST_MAP_WORKERS=0`  | force sequential parsing |
+| `AST_MAP_WORKERS=N`  | force a pool of N workers (bypasses the batch-size gate) |
+
+`ast-map cache` shows entry count + size; `ast-map cache clear` wipes it. `.ast-map/` is already in the default ignore list — add it to `.gitignore` if it isn't.
+
+---
+
 ## Power Prompts
 
 ### Full Architecture Audit
@@ -712,7 +747,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: "20" }
-      - uses: 6ixthxense/AST-MCP@v1.0.0
+      - uses: 6ixthxense/AST-MCP@v1
         with:
           path: src
           max-lines: "400"
@@ -720,7 +755,19 @@ jobs:
           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>`.
+The action runs `ast-map validate` and fails the job on threshold violations.
+
+Since **v1.21.0** the action can also run the **quality gate** (baseline ratchet + thresholds). Commit a baseline once (`ast-map check src --update-baseline`), then:
+
+```yaml
+      - uses: 6ixthxense/AST-MCP@v1
+        with:
+          path: src
+          mode: check                 # validate | check | both
+          check-args: "--min-score 70 --max-cycles 0"
+```
+
+The job fails whenever cycles, dead exports, SDP violations, or complexity regress past the committed `.ast-map.baseline.json`. You can also call any CLI command directly with `npx -p universal-ast-mapper ast-map <command>`.
 
 ---
 
@@ -740,6 +787,9 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **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`. |
+| **1.20.0** | **Incremental cache + parallel parsing** — persistent content-hash parse cache in `.ast-map/cache` (on by default, never stale, warm hits ~60× faster on large files; `ast-map cache stats|clear`, `AST_MAP_NO_CACHE`, `"cache": false`) + worker-thread **parallel parsing** for bulk scans (auto-sized, `AST_MAP_WORKERS` override, sequential fallback). |
 | **1.19.0** | **Dashboard: coupling + SDP** — `ast-map report` / `get_codebase_report` now include **module coupling** (per-directory instability bars) and **layer violations** (stable→volatile, SDP) cards, plus an SDP stat; SDP inversions also factor into the health score. The v1.14–1.16 metrics are now visual. |
 | **1.18.0** | **Vue & Svelte SFC support** — `.vue` and `.svelte` single-file components are now parsed: the `<script>` / `<script setup>` block is lifted out (TS or JS) and its symbols + imports extracted, with cross-file graph edges into plain modules. Blank-padding keeps every symbol's line numbers pointing at the original SFC. **14 languages**. |
 | **1.17.0** | **MCP prompts** — the server now registers 5 parameterized **prompts** (`architecture_audit`, `safe_refactor`, `dead_code_cleanup`, `health_check`, `onboard_codebase`): named workflows a client can invoke from its prompt menu, each chaining the right tools. The Cookbook recipes, one call away. |

package/dist/check.js

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { buildReport } from "./report.js";
+export const BASELINE_FILENAME = ".ast-map.baseline.json";
+export function metricsFromReport(r) {
+    return {
+        fileCount: r.fileCount,
+        symbolCount: r.symbolCount,
+        cycles: r.cycles.count,
+        deadExports: r.dead.count,
+        sdpViolations: r.layerViolations.count,
+        veryHighComplexity: r.complexity.hotspots.filter((h) => h.complexity > 20).length,
+        maxComplexity: r.complexity.max,
+        score: r.score,
+        grade: r.grade,
+    };
+}
+function readBaseline(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        return raw.metrics ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function checkThresholds(m, t, out) {
+    const rules = [
+        ["maxCycles", "cycles", "max"],
+        ["maxDeadExports", "deadExports", "max"],
+        ["maxSdpViolations", "sdpViolations", "max"],
+        ["maxVeryHighComplexity", "veryHighComplexity", "max"],
+        ["maxComplexity", "maxComplexity", "max"],
+        ["minScore", "score", "min"],
+    ];
+    for (const [tKey, mKey, dir] of rules) {
+        const limit = t[tKey];
+        if (limit === undefined)
+            continue;
+        const actual = m[mKey];
+        const bad = dir === "max" ? actual > limit : actual < limit;
+        if (bad) {
+            out.push({
+                kind: "threshold",
+                metric: mKey,
+                limit,
+                actual,
+                message: `${mKey} is ${actual}, ${dir === "max" ? "exceeds max" : "below min"} ${limit}`,
+            });
+        }
+    }
+}
+/** Metrics where an increase vs the baseline is a regression. */
+const RATCHET_UP = [
+    "cycles",
+    "deadExports",
+    "sdpViolations",
+    "veryHighComplexity",
+];
+function checkBaseline(m, base, out) {
+    for (const key of RATCHET_UP) {
+        const was = base[key];
+        const now = m[key];
+        if (now > was) {
+            out.push({
+                kind: "regression",
+                metric: key,
+                limit: was,
+                actual: now,
+                message: `${key} regressed: ${was} → ${now} (baseline ratchet)`,
+            });
+        }
+    }
+    if (m.score < base.score) {
+        out.push({
+            kind: "regression",
+            metric: "score",
+            limit: base.score,
+            actual: m.score,
+            message: `health score regressed: ${base.score} → ${m.score}`,
+        });
+    }
+}
+export async function runQualityGate(absDir, root, opts = {}) {
+    const report = await buildReport(absDir, root);
+    const metrics = metricsFromReport(report);
+    const baselinePath = path.resolve(root, opts.baselinePath ?? BASELINE_FILENAME);
+    const baseline = readBaseline(baselinePath);
+    const failures = [];
+    if (opts.thresholds)
+        checkThresholds(metrics, opts.thresholds, failures);
+    if (baseline)
+        checkBaseline(metrics, baseline, failures);
+    let baselineUpdated = false;
+    if (opts.updateBaseline) {
+        const doc = {
+            tool: "universal-ast-mapper",
+            updatedAt: new Date().toISOString(),
+            metrics,
+        };
+        fs.writeFileSync(baselinePath, JSON.stringify(doc, null, 2) + "\n", "utf8");
+        baselineUpdated = true;
+    }
+    return {
+        passed: failures.length === 0,
+        metrics,
+        baseline,
+        baselinePath,
+        baselineUpdated,
+        failures,
+    };
+}

package/dist/cli.js

@@ -5,6 +5,8 @@ import fs from "node:fs";
 import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
 import { renderHtml, renderCombinedHtml } from "./html.js";
 import { resolveOptions, loadProjectConfig } from "./config.js";
+import { initDiskCache, defaultCacheDir, diskCacheStats, clearDiskCache } from "./diskcache.js";
+import { buildSkeletonsBulk } from "./pool.js";
 import { supportedLanguages } from "./registry.js";
 import { findSymbol, findRelatedSymbols, findServerImports, isApiRoute, findMissingTryCatch, checkGeneralRules, GENERAL_RULE_DEFAULTS } from "./analysis.js";
 import { resolveFileImports } from "./resolver.js";
@@ -17,6 +19,7 @@ import { discoverWorkspace, findPackageCycles } from "./workspace.js";
 import { buildExplorerHtml } from "./explorer.js";
 import { readSourceMap } from "./sourcemap.js";
 import { buildReport, buildReportHtml } from "./report.js";
+import { runQualityGate, BASELINE_FILENAME } from "./check.js";
 import { computeDiff, computeRisk, isGitRepo } from "./gitdiff.js";
 import { packContext } from "./contextpack.js";
 import { computeCoupling } from "./coupling.js";
@@ -25,6 +28,10 @@ import { computeModuleCoupling } from "./modulecoupling.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 const ROOT = path.resolve(process.env.AST_MAP_ROOT ?? process.cwd());
+// Persistent parse cache (disable with AST_MAP_NO_CACHE=1 or "cache": false in config).
+if (process.env.AST_MAP_NO_CACHE !== "1" && loadProjectConfig(ROOT).cache !== false) {
+    initDiskCache(defaultCacheDir(ROOT));
+}
 // ─── ANSI colours (disabled when not a TTY) ───────────────────────────────────
 const tty = process.stdout.isTTY ?? false;
 const esc = (code) => (s) => tty ? `\x1b[${code}m${s}\x1b[0m` : s;
@@ -65,20 +72,38 @@ function resolveArg(p) {
 async function gatherSkeletons(dirAbs, detail = "outline") {
     const opts = resolveOptions({ detail, emitHtml: false });
     const files = collectSourceFiles(dirAbs, opts);
-    const skeletons = [];
-    for (const file of files) {
-        const fr = path.relative(ROOT, file).split(path.sep).join("/");
-        try {
-            skeletons.push(await buildSkeleton(file, fr, opts));
-        }
-        catch { /* skip parse errors */ }
-    }
-    return skeletons;
+    const items = files.map((f) => ({ abs: f, rel: path.relative(ROOT, f).split(path.sep).join("/") }));
+    const built = await buildSkeletonsBulk(items, opts);
+    return built.filter((r) => r !== null).map((r) => r.skel);
 }
 function die(msg) {
     console.error(red("✗") + " " + msg);
     process.exit(1);
 }
+// ─── Command: cache ───────────────────────────────────────────────────────────
+program
+    .command("cache [action]")
+    .description("Inspect or clear the persistent parse cache (actions: stats, clear)")
+    .option("--json", "Output as JSON")
+    .action((action, opts) => {
+    const dir = defaultCacheDir(ROOT);
+    if (action === "clear") {
+        const removed = clearDiskCache(dir);
+        if (opts.json)
+            jsonOut({ dir, removed });
+        else
+            console.log(green("\u2713") + ` cleared ${removed} cached ${removed === 1 ? "entry" : "entries"} (${dir})`);
+        return;
+    }
+    const stats = diskCacheStats(dir);
+    if (opts.json)
+        jsonOut(stats);
+    else {
+        console.log(bold("Parse cache") + "  " + dim(stats.dir));
+        console.log(`  entries: ${stats.entries}`);
+        console.log(`  size:    ${(stats.bytes / 1024).toFixed(1)} KB`);
+    }
+});
 // ─── Command: langs ───────────────────────────────────────────────────────────
 program
     .command("langs")
@@ -651,6 +676,69 @@ program
     console.log(indent(green("✓ wrote " + path.relative(process.cwd(), out))));
     console.log();
 });
+// ─── Command: check ───────────────────────────────────────────────────────────
+const num = (v) => Number.parseFloat(v);
+program
+    .command("check [dir]")
+    .description("CI quality gate: absolute thresholds + baseline ratchet (cycles, dead exports, SDP, complexity, score)")
+    .option("--baseline <file>", `Baseline file (default ${BASELINE_FILENAME})`)
+    .option("--update-baseline", "Write current metrics as the new baseline")
+    .option("--max-cycles <n>", "Fail when circular dependencies exceed n", num)
+    .option("--max-dead-exports <n>", "Fail when dead exports exceed n", num)
+    .option("--max-sdp-violations <n>", "Fail when SDP/layer violations exceed n", num)
+    .option("--max-very-high-complexity <n>", "Fail when functions with complexity > 20 exceed n", num)
+    .option("--max-complexity <n>", "Fail when any function's complexity exceeds n", num)
+    .option("--min-score <n>", "Fail when the health score drops below n", num)
+    .option("--json", "Output the gate result as JSON")
+    .action(async (dir, o) => {
+    const { abs, rel } = resolveArg(dir ?? ".");
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const fromConfig = loadProjectConfig(ROOT).check ?? {};
+    const thresholds = {
+        maxCycles: o.maxCycles ?? fromConfig.maxCycles,
+        maxDeadExports: o.maxDeadExports ?? fromConfig.maxDeadExports,
+        maxSdpViolations: o.maxSdpViolations ?? fromConfig.maxSdpViolations,
+        maxVeryHighComplexity: o.maxVeryHighComplexity ?? fromConfig.maxVeryHighComplexity,
+        maxComplexity: o.maxComplexity ?? fromConfig.maxComplexity,
+        minScore: o.minScore ?? fromConfig.minScore,
+    };
+    const result = await runQualityGate(abs, ROOT, {
+        baselinePath: o.baseline,
+        thresholds,
+        updateBaseline: o.updateBaseline,
+    });
+    if (o.json) {
+        jsonOut(result);
+        if (!result.passed)
+            process.exit(1);
+        return;
+    }
+    header(`Quality gate \u2014 ${rel}/`);
+    const m = result.metrics;
+    const b = result.baseline;
+    const delta = (key) => b ? dim(` (baseline ${String(b[key])})`) : "";
+    console.log(indent(`score ${bold(String(m.score))}/100 (${m.grade})${delta("score")}`));
+    console.log(indent(`cycles ${m.cycles}${delta("cycles")} · dead exports ${m.deadExports}${delta("deadExports")} · SDP ${m.sdpViolations}${delta("sdpViolations")}`));
+    console.log(indent(`complexity: max ${m.maxComplexity} · very-high (>20) ${m.veryHighComplexity}${delta("veryHighComplexity")}`));
+    if (result.baselineUpdated) {
+        console.log(indent(green("\u2713") + " baseline updated: " + path.relative(process.cwd(), result.baselinePath)));
+    }
+    else if (!b) {
+        console.log(indent(dim(`no baseline (${path.relative(process.cwd(), result.baselinePath)}) \u2014 run with --update-baseline to create one`)));
+    }
+    if (result.failures.length > 0) {
+        console.log();
+        for (const f of result.failures) {
+            console.log(indent(red("\u2717") + ` [${f.kind}] ${f.message}`));
+        }
+        console.log();
+        console.log(indent(red(`gate FAILED \u2014 ${result.failures.length} violation(s)`)));
+        process.exit(1);
+    }
+    console.log(indent(green("\u2713 gate passed")));
+    console.log();
+});
 // ─── Command: explore ─────────────────────────────────────────────────────────
 program
     .command("explore [dir]")

package/dist/diskcache.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+// ─── Persistent (on-disk) parse cache ─────────────────────────────────────────
+// Content-hash keyed: the key embeds schemaVersion + grammar source + detail +
+// the file's raw bytes, so entries never go stale — a changed file simply maps
+// to a new key. Stored as sharded JSON files under <root>/.ast-map/cache.
+// Enabled by calling initDiskCache() once at startup (CLI / MCP server / worker).
+let cacheDir = null;
+/** Enable (or disable with null) the disk cache for this process. */
+export function initDiskCache(dir) {
+    cacheDir = dir;
+}
+/** The currently active cache directory, or null when disabled. */
+export function diskCacheDir() {
+    return cacheDir;
+}
+/** Conventional cache location for a project root. */
+export function defaultCacheDir(root) {
+    return path.join(root, ".ast-map", "cache");
+}
+/** Stable cache key for a (source, detail, schema, grammar) tuple. */
+export function diskCacheKey(source, detail, schemaVersion, grammarSource) {
+    return crypto
+        .createHash("sha1")
+        .update(`${schemaVersion}\0${grammarSource}\0${detail}\0`)
+        .update(source)
+        .digest("hex");
+}
+function shardPath(dir, key) {
+    return path.join(dir, key.slice(0, 2), key.slice(2) + ".json");
+}
+/** Read a cached skeleton, or null on miss / disabled / corrupt entry. */
+export function diskCacheGet(key) {
+    if (!cacheDir)
+        return null;
+    try {
+        const raw = fs.readFileSync(shardPath(cacheDir, key), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.skel ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist a skeleton under the given key (best-effort, never throws). */
+export function diskCachePut(key, skel) {
+    if (!cacheDir)
+        return;
+    try {
+        const file = shardPath(cacheDir, key);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = file + "." + process.pid + ".tmp";
+        fs.writeFileSync(tmp, JSON.stringify({ skel }));
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        /* cache write failures are non-fatal */
+    }
+}
+/** Count entries + total size of a cache directory. */
+export function diskCacheStats(dir) {
+    let entries = 0;
+    let bytes = 0;
+    const walk = (d) => {
+        let names = [];
+        try {
+            names = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of names) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.name.endsWith(".json")) {
+                entries++;
+                try {
+                    bytes += fs.statSync(p).size;
+                }
+                catch { /* skip */ }
+            }
+        }
+    };
+    walk(dir);
+    return { dir, entries, bytes };
+}
+/** Remove every entry in a cache directory. Returns how many were removed. */
+export function clearDiskCache(dir) {
+    const { entries } = diskCacheStats(dir);
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+    return entries;
+}

package/dist/extractors/php.js

@@ -0,0 +1,208 @@
+import { namedChildren, nameOf, headerSignature, leadingComment } from "../parser.js";
+import { makeSymbol } from "./common.js";
+// ─── PHP extractor (tree-sitter-php) ──────────────────────────────────────────
+export function extractPhp(root, _source) {
+    return collect(namedChildren(root));
+}
+function collect(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        const sym = handle(n);
+        if (sym)
+            out.push(sym);
+        else if (n.type === "namespace_definition") {
+            // `namespace Foo;` (no braces) — siblings follow; emit the namespace marker.
+            const name = nameOf(n)?.replace(/\s+/g, "") ?? namespaceName(n);
+            if (name) {
+                out.push(makeSymbol({ name, kind: "namespace", node: n, rawKind: n.type }));
+            }
+            const body = n.childForFieldName("body");
+            if (body)
+                out[out.length - 1].children = collect(namedChildren(body));
+        }
+        else if (n.type === "expression_statement" || n.type === "if_statement") {
+            // skip — top-level statements
+        }
+    }
+    return out;
+}
+function namespaceName(n) {
+    for (const c of namedChildren(n)) {
+        if (c.type === "namespace_name")
+            return c.text.replace(/\s+/g, "");
+    }
+    return null;
+}
+function phpVisibility(node) {
+    for (const c of namedChildren(node)) {
+        if (c.type === "visibility_modifier") {
+            const t = c.text;
+            if (t === "private" || t === "protected")
+                return "private";
+            return "public";
+        }
+    }
+    return "public";
+}
+function classLike(node, kind) {
+    const name = nameOf(node) ?? "(class)";
+    const body = node.childForFieldName("body") ?? findChild(node, "declaration_list");
+    return makeSymbol({
+        name,
+        kind,
+        node,
+        rawKind: node.type,
+        signature: headerSignature(node, body),
+        doc: leadingComment(node),
+        children: body ? collect(namedChildren(body)) : [],
+    });
+}
+function findChild(node, type) {
+    for (const c of namedChildren(node))
+        if (c.type === type)
+            return c;
+    return null;
+}
+function handle(node) {
+    switch (node.type) {
+        case "class_declaration":
+        case "trait_declaration":
+            return classLike(node, "class");
+        case "interface_declaration":
+            return classLike(node, "interface");
+        case "enum_declaration": {
+            const body = findChild(node, "enum_declaration_list");
+            return makeSymbol({
+                name: nameOf(node) ?? "(enum)",
+                kind: "enum",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                doc: leadingComment(node),
+                children: body
+                    ? namedChildren(body)
+                        .filter((c) => c.type === "enum_case")
+                        .map((c) => makeSymbol({ name: nameOf(c) ?? c.text, kind: "const", node: c, rawKind: c.type }))
+                    : [],
+            });
+        }
+        case "function_definition": {
+            const body = node.childForFieldName("body") ?? findChild(node, "compound_statement");
+            return makeSymbol({
+                name: nameOf(node) ?? "(function)",
+                kind: "function",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                doc: leadingComment(node),
+            });
+        }
+        case "method_declaration": {
+            const body = node.childForFieldName("body") ?? findChild(node, "compound_statement");
+            const vis = phpVisibility(node);
+            return makeSymbol({
+                name: nameOf(node) ?? "(method)",
+                kind: "method",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                visibility: vis,
+                exported: vis === "public",
+                doc: leadingComment(node),
+            });
+        }
+        case "const_declaration": {
+            const el = findChild(node, "const_element");
+            const name = el ? namedChildren(el)[0]?.text : null;
+            if (!name)
+                return null;
+            const vis = phpVisibility(node);
+            return makeSymbol({
+                name,
+                kind: "const",
+                node,
+                rawKind: node.type,
+                visibility: vis,
+                exported: vis === "public",
+            });
+        }
+        case "property_declaration": {
+            const decl = findChild(node, "property_element");
+            const name = decl?.text.replace(/\s*=.*$/, "").trim();
+            if (!name)
+                return null;
+            const vis = phpVisibility(node);
+            return makeSymbol({
+                name,
+                kind: "field",
+                node,
+                rawKind: node.type,
+                visibility: vis,
+                exported: vis === "public",
+            });
+        }
+        default:
+            return null;
+    }
+}
+// ─── Import extraction ────────────────────────────────────────────────────────
+// `use App\Models\User;`, grouped `use App\{A, B};`, and require/include calls.
+export function extractImportsPhp(root, _source) {
+    const imports = [];
+    walk(root, imports, 0);
+    return imports;
+}
+function walk(node, out, depth) {
+    if (depth > 4)
+        return;
+    for (const c of namedChildren(node)) {
+        if (c.type === "namespace_use_declaration")
+            parseUse(c, out);
+        else if (c.type === "require_expression" ||
+            c.type === "require_once_expression" ||
+            c.type === "include_expression" ||
+            c.type === "include_once_expression") {
+            const str = findString(c);
+            if (str)
+                out.push({ symbol: "*", from: str, isSideEffect: true });
+        }
+        else {
+            walk(c, out, depth + 1);
+        }
+    }
+}
+function findString(node) {
+    for (const c of namedChildren(node)) {
+        if (c.type === "string")
+            return c.text.replace(/^['"]|['"]$/g, "");
+        const deep = findString(c);
+        if (deep)
+            return deep;
+    }
+    return null;
+}
+function parseUse(node, out) {
+    let groupBase = null;
+    for (const c of namedChildren(node)) {
+        if (c.type === "namespace_name")
+            groupBase = c.text.replace(/\s+/g, "");
+        else if (c.type === "namespace_use_clause") {
+            const qn = c.text.replace(/\s+as\s+.*$/, "").replace(/\s+/g, "");
+            const alias = /\s+as\s+(\w+)/.exec(c.text)?.[1];
+            const leaf = qn.split("\\").pop() ?? qn;
+            const imp = { symbol: leaf, from: qn };
+            if (alias)
+                imp.alias = alias;
+            out.push(imp);
+        }
+        else if (c.type === "namespace_use_group") {
+            for (const g of namedChildren(c)) {
+                if (g.type !== "namespace_use_group_clause")
+                    continue;
+                const txt = g.text.replace(/\s+/g, "");
+                const leaf = txt.split("\\").pop() ?? txt;
+                out.push({ symbol: leaf, from: groupBase ? `${groupBase}\\${txt}` : txt });
+            }
+        }
+    }
+}

package/dist/extractors/ruby.js

@@ -0,0 +1,146 @@
+import { namedChildren, nameOf, headerSignature, leadingComment } from "../parser.js";
+import { makeSymbol } from "./common.js";
+// ─── Ruby extractor (tree-sitter-ruby) ────────────────────────────────────────
+// Tracks `private` / `protected` visibility sections inside class bodies.
+export function extractRuby(root, _source) {
+    return collect(namedChildren(root), false);
+}
+function collect(nodes, insideClass) {
+    const out = [];
+    let visibility = "public";
+    for (const n of nodes) {
+        // Bare `private` / `protected` / `public` switches the section.
+        if (n.type === "identifier") {
+            if (n.text === "private" || n.text === "protected")
+                visibility = "private";
+            else if (n.text === "public")
+                visibility = "public";
+            continue;
+        }
+        const sym = handle(n, insideClass, visibility);
+        if (sym)
+            out.push(sym);
+    }
+    return out;
+}
+function bodyOf(node) {
+    const byField = node.childForFieldName("body");
+    if (byField)
+        return byField;
+    for (const c of namedChildren(node)) {
+        if (c.type === "body_statement")
+            return c;
+    }
+    return null;
+}
+function handle(node, insideClass, visibility) {
+    switch (node.type) {
+        case "class": {
+            const body = bodyOf(node);
+            return makeSymbol({
+                name: nameOf(node) ?? "(class)",
+                kind: "class",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                doc: leadingComment(node),
+                children: body ? collect(namedChildren(body), true) : [],
+            });
+        }
+        case "module": {
+            const body = bodyOf(node);
+            return makeSymbol({
+                name: nameOf(node) ?? "(module)",
+                kind: "namespace",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                doc: leadingComment(node),
+                children: body ? collect(namedChildren(body), true) : [],
+            });
+        }
+        case "method": {
+            const body = bodyOf(node);
+            const name = nameOf(node) ?? "(method)";
+            return makeSymbol({
+                name,
+                kind: insideClass ? "method" : "function",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                visibility,
+                exported: visibility === "public",
+                doc: leadingComment(node),
+            });
+        }
+        case "singleton_method": {
+            const body = bodyOf(node);
+            const name = nameOf(node) ?? "(method)";
+            return makeSymbol({
+                name: `self.${name}`,
+                kind: insideClass ? "method" : "function",
+                node,
+                rawKind: node.type,
+                signature: headerSignature(node, body),
+                visibility,
+                exported: visibility === "public",
+                doc: leadingComment(node),
+            });
+        }
+        case "assignment": {
+            // Top-level / class-level CONSTANT = ...
+            const left = namedChildren(node)[0];
+            if (left?.type === "constant") {
+                return makeSymbol({
+                    name: left.text,
+                    kind: "const",
+                    node,
+                    rawKind: node.type,
+                });
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+// ─── Import extraction ────────────────────────────────────────────────────────
+// `require 'x'` (external) and `require_relative './x'` (relative).
+export function extractImportsRuby(root, _source) {
+    const imports = [];
+    for (const n of namedChildren(root))
+        collectRequire(n, imports, 0);
+    return imports;
+}
+function collectRequire(node, out, depth) {
+    if (depth > 3)
+        return;
+    if (node.type === "call") {
+        const fn = namedChildren(node)[0];
+        if (fn?.type === "identifier" && (fn.text === "require" || fn.text === "require_relative")) {
+            const args = node.childForFieldName("arguments") ?? findArgs(node);
+            const str = args ? firstString(args) : null;
+            if (str) {
+                const from = fn.text === "require_relative" && !str.startsWith(".") ? `./${str}` : str;
+                out.push({ symbol: "*", from, isSideEffect: true });
+            }
+            return;
+        }
+    }
+    for (const c of namedChildren(node))
+        collectRequire(c, out, depth + 1);
+}
+function findArgs(node) {
+    for (const c of namedChildren(node))
+        if (c.type === "argument_list")
+            return c;
+    return null;
+}
+function firstString(args) {
+    for (const c of namedChildren(args)) {
+        if (c.type === "string") {
+            return c.text.replace(/^['"]|['"]$/g, "");
+        }
+    }
+    return null;
+}

package/dist/index.js

@@ -6,6 +6,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { fileURLToPath } from "node:url";
 import { resolveOptions, loadProjectConfig } from "./config.js";
+import { initDiskCache, defaultCacheDir } from "./diskcache.js";
+import { buildSkeletonsBulk } from "./pool.js";
 import { buildSkeleton, collectSourceFiles, UnsupportedLanguageError, } from "./skeleton.js";
 import { renderHtml, renderCombinedHtml } from "./html.js";
 import { supportedLanguages } from "./registry.js";
@@ -21,6 +23,7 @@ import { traceTypeInFile } from "./typeflow.js";
 import { discoverWorkspace, findPackageCycles } from "./workspace.js";
 import { readSourceMap } from "./sourcemap.js";
 import { buildReport } from "./report.js";
+import { runQualityGate } from "./check.js";
 import { computeDiff, computeRisk, isGitRepo } from "./gitdiff.js";
 import { packContext } from "./contextpack.js";
 import { computeCoupling } from "./coupling.js";
@@ -29,6 +32,10 @@ import { computeModuleCoupling } from "./modulecoupling.js";
 import { registerPrompts } from "./prompts.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());
+// Persistent parse cache (disable with AST_MAP_NO_CACHE=1 or "cache": false in config).
+if (process.env.AST_MAP_NO_CACHE !== "1" && loadProjectConfig(ROOT).cache !== false) {
+    initDiskCache(defaultCacheDir(ROOT));
+}
 function resolveInRoot(input) {
     const abs = path.resolve(ROOT, input);
     const rel = path.relative(ROOT, abs);
@@ -135,12 +142,17 @@ server.registerTool("generate_skeleton", {
             const results = [];
             const successSkeletons = [];
             let totalSymbols = 0;
-            for (const file of files) {
-                const fileRel = path.relative(ROOT, file).split(path.sep).join("/");
-                try {
-                    const skel = await buildSkeleton(file, fileRel, opts);
+            const items = files.map((file) => ({
+                abs: file,
+                rel: path.relative(ROOT, file).split(path.sep).join("/"),
+            }));
+            const built = await buildSkeletonsBulk(items, opts);
+            for (let i = 0; i < built.length; i++) {
+                const r = built[i];
+                if (r) {
+                    const skel = r.skel;
                     totalSymbols += skel.symbolCount;
-                    const htmlPath = opts.emitHtml ? writeHtml(skel, fileRel, opts) : null;
+                    const htmlPath = opts.emitHtml ? writeHtml(skel, items[i].rel, opts) : null;
                     successSkeletons.push(skel);
                     results.push({
                         file: skel.file,
@@ -149,8 +161,8 @@ server.registerTool("generate_skeleton", {
                         htmlPath,
                     });
                 }
-                catch (err) {
-                    results.push({ file: fileRel.split(path.sep).join("/"), error: describeError(err) });
+                else {
+                    results.push({ file: items[i].rel, error: "parse failed or unsupported file type" });
                 }
             }
             let combinedHtmlPath = null;
@@ -797,6 +809,37 @@ server.registerTool("get_codebase_report", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: check_quality_gate ──────────────────────────── */
+server.registerTool("check_quality_gate", {
+    title: "Quality gate (thresholds + baseline ratchet)",
+    description: "Run the CI quality gate over a directory: evaluates absolute thresholds (from " +
+        "`.ast-map.config.json` \u2192 `check`) and a **baseline ratchet** against " +
+        "`.ast-map.baseline.json` \u2014 fails when cycles, dead exports, SDP violations, " +
+        "very-high-complexity functions, or the health score regress. " +
+        "Set updateBaseline to re-anchor the baseline at the current metrics.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to gate. Defaults to the project root."),
+        baseline: z.string().optional().describe("Baseline file path. Default .ast-map.baseline.json."),
+        updateBaseline: z.boolean().optional().describe("Write current metrics as the new baseline."),
+    },
+}, async ({ path: input, baseline, updateBaseline }) => {
+    try {
+        const { abs, rel } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. check_quality_gate requires a directory.`);
+        }
+        const thresholds = loadProjectConfig(ROOT).check;
+        const result = await runQualityGate(abs, ROOT, {
+            baselinePath: baseline,
+            thresholds,
+            updateBaseline,
+        });
+        return jsonText({ directory: rel.split(path.sep).join("/") || ".", ...result });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_diff ────────────────────────────────────── */
 server.registerTool("get_diff", {
     title: "Git-aware change diff + blast radius",

package/dist/pool.js

@@ -0,0 +1,114 @@
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { buildSkeleton } from "./skeleton.js";
+import { computeFileComplexity } from "./complexity.js";
+import { diskCacheDir } from "./diskcache.js";
+/** Batches smaller than this are parsed sequentially (worker startup costs more). */
+const MIN_BATCH = 64;
+const MAX_WORKERS = 8;
+function envWorkers() {
+    const env = process.env.AST_MAP_WORKERS;
+    if (env === undefined || env === "")
+        return null;
+    const v = Number.parseInt(env, 10);
+    return Number.isNaN(v) ? null : Math.max(0, Math.min(v, MAX_WORKERS));
+}
+function plannedWorkers(n) {
+    const forced = envWorkers();
+    if (forced !== null)
+        return forced;
+    const cpus = os.cpus().length;
+    return Math.min(Math.max(cpus - 1, 0), MAX_WORKERS, Math.ceil(n / MIN_BATCH));
+}
+async function buildSequential(items, opts, withComplexity, out) {
+    for (let i = 0; i < items.length; i++) {
+        if (out[i] !== undefined)
+            continue; // already produced by a worker
+        try {
+            const skel = await buildSkeleton(items[i].abs, items[i].rel, opts);
+            const complexity = withComplexity
+                ? await computeFileComplexity(items[i].abs, items[i].rel)
+                : undefined;
+            out[i] = { skel, complexity };
+        }
+        catch {
+            out[i] = null; // unparsable / unsupported — callers skip nulls
+        }
+    }
+}
+/**
+ * Build skeletons for many files, in parallel when it pays off.
+ * Returns one entry per input item (null = failed/unsupported file).
+ */
+export async function buildSkeletonsBulk(items, opts, withComplexity = false) {
+    const out = new Array(items.length);
+    const workers = plannedWorkers(items.length);
+    const workerFile = path.join(path.dirname(fileURLToPath(import.meta.url)), "worker.js");
+    // An explicit AST_MAP_WORKERS >= 2 bypasses the batch-size gate.
+    const smallBatch = items.length < MIN_BATCH && envWorkers() === null;
+    if (smallBatch || workers <= 1 || !fs.existsSync(workerFile)) {
+        await buildSequential(items, opts, withComplexity, out);
+        return out;
+    }
+    let failed = false;
+    await new Promise((resolve) => {
+        let next = 0;
+        let done = 0;
+        let open = 0;
+        const pool = [];
+        const finish = () => {
+            for (const w of pool)
+                void w.terminate();
+            resolve();
+        };
+        const dispatch = (w) => {
+            if (failed || next >= items.length) {
+                return;
+            }
+            const id = next++;
+            w.postMessage({ id, abs: items[id].abs, rel: items[id].rel, opts, withComplexity });
+        };
+        for (let i = 0; i < workers; i++) {
+            let w;
+            try {
+                w = new Worker(workerFile, { workerData: { cacheDir: diskCacheDir() } });
+            }
+            catch {
+                failed = true;
+                break;
+            }
+            open++;
+            pool.push(w);
+            w.on("message", (msg) => {
+                out[msg.id] = msg.ok && msg.skel ? { skel: msg.skel, complexity: msg.complexity } : null;
+                done++;
+                if (done >= items.length || failed)
+                    finish();
+                else
+                    dispatch(w);
+            });
+            w.on("error", () => {
+                failed = true;
+                finish();
+            });
+            dispatch(w);
+            // prime a second task per worker to hide round-trip latency
+            dispatch(w);
+        }
+        if (pool.length === 0)
+            resolve();
+        else if (open === 0)
+            resolve();
+    });
+    // Fill any gaps (worker failure, early termination) sequentially.
+    for (let i = 0; i < items.length; i++) {
+        if (out[i] === undefined) {
+            await buildSequential(items, opts, withComplexity, out);
+            break;
+        }
+    }
+    return out;
+}

package/dist/registry.js

@@ -9,6 +9,8 @@ import { extractC, extractImportsC } from "./extractors/c.js";
 import { extractCpp, extractImportsCpp } from "./extractors/cpp.js";
 import { extractKotlin, extractDirectivesKotlin, extractImportsKotlin } from "./extractors/kotlin.js";
 import { extractSwift, extractImportsSwift } from "./extractors/swift.js";
+import { extractPhp, extractImportsPhp } from "./extractors/php.js";
+import { extractRuby, extractImportsRuby } from "./extractors/ruby.js";
 const TS_ENTRY = (language, grammar) => ({
     language,
     grammar,
@@ -62,6 +64,9 @@ const BY_EXT = {
         extract: extractKotlin, extractDirectives: extractDirectivesKotlin, extractImports: extractImportsKotlin,
     },
     ".swift": { language: "swift", grammar: "swift", extract: extractSwift, extractImports: extractImportsSwift },
+    ".php": { language: "php", grammar: "php", extract: extractPhp, extractImports: extractImportsPhp },
+    ".rb": { language: "ruby", grammar: "ruby", extract: extractRuby, extractImports: extractImportsRuby },
+    ".rake": { language: "ruby", grammar: "ruby", extract: extractRuby, extractImports: extractImportsRuby },
     ".vue": SFC_ENTRY("vue"),
     ".svelte": SFC_ENTRY("svelte"),
 };

package/dist/report.js

@@ -1,9 +1,9 @@
 import path from "node:path";
-import { collectSourceFiles, buildSkeleton } from "./skeleton.js";
+import { collectSourceFiles } from "./skeleton.js";
+import { buildSkeletonsBulk } from "./pool.js";
 import { resolveOptions } from "./config.js";
 import { buildSymbolGraph } from "./graph.js";
 import { findDeadExports, findCircularDeps, getTopSymbols } from "./graph-analysis.js";
-import { computeFileComplexity } from "./complexity.js";
 import { findLayerViolations } from "./layers.js";
 import { computeModuleCoupling } from "./modulecoupling.js";
 function gradeFor(score) {
@@ -25,24 +25,27 @@ export async function buildReport(absDir, root) {
     let symbolCount = 0;
     const hotspots = [];
     let cxSum = 0, cxN = 0, cxMax = 0;
-    for (const file of files) {
-        const rel = path.relative(root, file).split(path.sep).join("/");
-        try {
-            const skel = await buildSkeleton(file, rel, opts);
-            skeletons.push(skel);
-            symbolCount += skel.symbolCount;
-            langCount.set(skel.language, (langCount.get(skel.language) ?? 0) + 1);
-            const fc = await computeFileComplexity(file, rel);
-            if (fc) {
-                for (const f of fc.functions) {
-                    hotspots.push({ ...f, file: rel });
-                    cxSum += f.complexity;
-                    cxN++;
-                    cxMax = Math.max(cxMax, f.complexity);
-                }
+    const items = files.map((file) => ({
+        abs: file,
+        rel: path.relative(root, file).split(path.sep).join("/"),
+    }));
+    const built = await buildSkeletonsBulk(items, opts, true);
+    for (let i = 0; i < built.length; i++) {
+        const r = built[i];
+        if (!r)
+            continue; // skip unparsable
+        const rel = items[i].rel;
+        skeletons.push(r.skel);
+        symbolCount += r.skel.symbolCount;
+        langCount.set(r.skel.language, (langCount.get(r.skel.language) ?? 0) + 1);
+        if (r.complexity) {
+            for (const f of r.complexity.functions) {
+                hotspots.push({ ...f, file: rel });
+                cxSum += f.complexity;
+                cxN++;
+                cxMax = Math.max(cxMax, f.complexity);
             }
         }
-        catch { /* skip unparsable */ }
     }
     const graph = buildSymbolGraph(skeletons, root);
     const dead = findDeadExports(graph).filter((d) => d.confidence === "high");

package/dist/skeleton.js

@@ -4,6 +4,7 @@ import { detectLanguage, supportedExtensions } from "./registry.js";
 import { parseSource } from "./parser.js";
 import { countSymbols, toOutline } from "./extractors/common.js";
 import { extractScript } from "./sfc.js";
+import { diskCacheKey, diskCacheGet, diskCachePut } from "./diskcache.js";
 export const SCHEMA_VERSION = "1.1";
 export const GRAMMAR_SOURCE = "tree-sitter-wasms@0.1.13";
 const parseCache = new Map();
@@ -58,7 +59,19 @@ export async function buildSkeleton(absPath, relPath, opts) {
         const wantFile = relPath.split(path.sep).join("/");
         return cached.file === wantFile ? cached : { ...cached, file: wantFile };
     }
-    let source = fs.readFileSync(absPath, "utf8");
+    const rawSource = fs.readFileSync(absPath, "utf8");
+    // Persistent cache (content-hash keyed, see diskcache.ts). A hit skips
+    // parsing entirely; entries can never be stale because the key embeds the
+    // file's bytes + detail + schema/grammar versions.
+    const dKey = diskCacheKey(rawSource, opts.detail, SCHEMA_VERSION, GRAMMAR_SOURCE);
+    const fromDisk = diskCacheGet(dKey);
+    if (fromDisk) {
+        const wantFile = relPath.split(path.sep).join("/");
+        const hit = fromDisk.file === wantFile ? fromDisk : { ...fromDisk, file: wantFile };
+        setCached(absPath, opts.detail, hit);
+        return hit;
+    }
+    let source = rawSource;
     let grammar = entry.grammar;
     if (entry.sfc) {
         const script = extractScript(source);
@@ -83,6 +96,7 @@ export async function buildSkeleton(absPath, relPath, opts) {
         symbols,
     };
     setCached(absPath, opts.detail, result);
+    diskCachePut(dKey, result);
     return result;
 }
 /** Recursively collect supported source files under a directory. */

package/dist/worker.js

@@ -0,0 +1,27 @@
+// Worker-thread entry: builds skeletons (and optionally per-file complexity)
+// off the main thread. Spawned by pool.ts with { cacheDir } as workerData.
+import { parentPort, workerData } from "node:worker_threads";
+import { buildSkeleton } from "./skeleton.js";
+import { computeFileComplexity } from "./complexity.js";
+import { initDiskCache } from "./diskcache.js";
+const data = (workerData ?? {});
+if (data.cacheDir)
+    initDiskCache(data.cacheDir);
+parentPort.on("message", (msg) => {
+    void (async () => {
+        try {
+            const skel = await buildSkeleton(msg.abs, msg.rel, msg.opts);
+            const complexity = msg.withComplexity
+                ? await computeFileComplexity(msg.abs, msg.rel)
+                : undefined;
+            parentPort.postMessage({ id: msg.id, ok: true, skel, complexity });
+        }
+        catch (e) {
+            parentPort.postMessage({
+                id: msg.id,
+                ok: false,
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    })();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-ast-mapper",
-  "version": "1.19.0",
+  "version": "1.22.1",
   "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",
+    "test": "node test/smoke.mjs && node test/analysis.mjs && node test/cache-smoke.mjs && node test/check-smoke.mjs",
     "postinstall": "node scripts/install-skill.mjs"
   },
   "engines": {
@@ -37,7 +37,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.3",
     "tree-sitter-wasms": "0.1.13",
-    "web-tree-sitter": "0.20.8",
+    "web-tree-sitter": "0.21.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {