universal-ast-mapper 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [1.27.0] — 2026-06-11 · Test-coverage mapping
+- **New MCP tool `get_test_coverage`** + **CLI `ast-map tests [dir]`** (alias
+  `coverage`) — structural test coverage with zero instrumentation: which source
+  files have tests at all, and which have **none**.
+- Two pairing signals:
+  - **import** — a test file imports the source file (graph edge; definitive).
+  - **name** — conventions: `auth.test.ts` → `auth.ts`, `auth_test.go`,
+    `test_utils.py` → `utils.py`, `AuthTest.java` → `Auth.java`,
+    `foo-smoke.mjs` → `foo.*`, and bare `test/<name>.*` → `<name>.*`;
+    ambiguity resolved by longest shared path prefix.
+- Test files detected by directory (`test/`, `tests/`, `__tests__/`, `spec/`, `e2e/`)
+  or basename pattern; **fixtures/mocks/testdata dirs excluded from both sides**.
+- Output: coverage ratio, test→source `links` (with `via`), `tested`,
+  **`untested` ranked by risk** (fan-in Ca, then symbol count — load-bearing
+  files with no tests first), and `orphanTests` (no source matched; usually
+  integration/e2e).
+- CLI: `-u/--untested`, `--links`, `-n/--top`, `--json`.
+- New module `testmap` (`mapTestCoverage`, `isTestFile`, `testNameTarget`,
+  `isFixtureFile`) + `test/fixtures/testmap/` fixture tree. Tests: +9 checks
+  in `test/analysis.mjs` (153 total). **30 MCP tools / 32 CLI commands.**
+
 ## [1.26.0] — 2026-06-11 · Coupling overlay in the explorer
 - **`ast-map explore` color modes** — new toolbar dropdown: `color: folder`
   (existing per-directory hues) or **`color: coupling`** — nodes shaded by

package/README.md

@@ -4,7 +4,7 @@ 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.
 
-**29 MCP tools / 31 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** with a **coupling overlay** (`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).
+**30 MCP tools / 32 CLI commands / 5 MCP prompts** spanning skeletons, dependency graphs, and deep analysis — dead code, cycles, change-impact, complexity, duplicates, unused params, type-flow, decorators, test-coverage mapping — plus monorepo support, an interactive **graph explorer** with a **coupling overlay** (`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>`) · **PHP** · **Ruby**
 
@@ -128,6 +128,7 @@ ast-map cache     [stats|clear]                  # persistent parse cache (.ast-
 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 find     <query> [dir]     [-l N] [-k kind] [-e]   # semantic: by meaning
+ast-map tests    [dir]             [alias: coverage] [-u] [--links] [-n N]
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
 ast-map impact   <file> <symbol>   [--scan <dir>]
@@ -159,6 +160,9 @@ ast-map search handler src/ --exported
 # Don't know the name? Search by meaning
 ast-map find "remove expired cache entries" src/
 
+# Which source files have no tests at all?
+ast-map tests . --untested
+
 # What does this file import / what imports it?
 ast-map deps src/lib/auth.ts --scan src/
 
@@ -533,6 +537,17 @@ semantic_search("find unused exported code") →
 
 ---
 
+### `get_test_coverage`
+Structural test coverage: pair test files with the source files they exercise, and list source files **no test touches** — no instrumentation or test runner needed, works on a cold checkout.
+
+Two signals: a test file *importing* a source file (definitive), and naming conventions (`auth.test.ts` → `auth.ts`, `test_utils.py` → `utils.py`, `FooTest.java` → `Foo.java`, `test/<name>.*` → `<name>.*`). Fixture/mock directories are excluded from both sides. Untested files are ranked by risk (fan-in, then symbol count); unmatched test files are reported as `orphanTests` (usually integration/e2e).
+
+> File-level coverage ("does anything test this file?"), not line coverage.
+
+**Params:** `path`, `untestedOnly`
+
+---
+
 ### `get_file_deps`
 For a single file, show what it imports and what imports it (with symbol names).  
 More focused than `build_symbol_graph` — use for quick dependency lookup.
@@ -820,6 +835,7 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **1.27.0** | **Test-coverage mapping** — new MCP tool `get_test_coverage` + CLI `ast-map tests` (alias `coverage`): pairs test files with the sources they exercise (import edges + naming conventions) and lists **untested sources ranked by risk** (fan-in, then symbols). Fixture dirs excluded; orphan tests reported. File-level, zero instrumentation. (**30 tools / 32 commands**) |
 | **1.26.0** | **Coupling overlay in the explorer** — `ast-map explore` gains a `color: coupling` mode: nodes shaded by **instability** I = Ce/(Ca+Ce) on a green (stable) → red (volatile) scale, with a legend, and Ca / Ce / I readouts in the hover tooltip and detail sidebar. Spot load-bearing files and volatile hotspots at a glance. |
 | **1.25.0** | **Semantic symbol search** — new MCP tool `semantic_search` + CLI `ast-map find <query>`: find symbols by *meaning* ("remove expired sessions" → `clearDiskCache`). Identifier tokenization + 60-group programming thesaurus + stemming + fuzzy matching + BM25-style IDF ranking over names, docs, signatures and paths. No embeddings, no network. (**29 tools / 31 commands**) |
 | **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%. |

package/dist/cli.js

@@ -28,6 +28,7 @@ import { computeModuleCoupling } from "./modulecoupling.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 import { semanticSearch } from "./semantic.js";
+import { mapTestCoverage } from "./testmap.js";
 import { parseRootsFromEnv } from "./roots.js";
 const ROOT = parseRootsFromEnv().roots[0]; // CLI is local — no boundary, primary root only
 // Persistent parse cache (disable with AST_MAP_NO_CACHE=1 or "cache": false in config).
@@ -1130,6 +1131,47 @@ program
     }
     console.log();
 });
+// ─── Command: tests (coverage map) ───────────────────────────────────────────
+program
+    .command("tests [dir]")
+    .alias("coverage")
+    .description("Map test files to the sources they cover; list untested sources")
+    .option("-u, --untested", "Only show untested source files")
+    .option("--links", "Show every test→source link")
+    .option("-n, --top <n>", "Max untested files to show", (v) => parseInt(v, 10), 25)
+    .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 skeletons = await gatherSkeletons(abs);
+    const map = mapTestCoverage(buildSymbolGraph(skeletons, ROOT));
+    if (opts.json)
+        return jsonOut({ directory: rel, ...map });
+    header(`Test Coverage — ${rel}/  ${dim(`(${map.testFiles} test files · ${map.sourceFiles} sources)`)}`);
+    const pct = Math.round(map.coverageRatio * 100);
+    const pcolor = pct >= 70 ? green : pct >= 40 ? yellow : red;
+    console.log(indent(`${bold("Covered:")} ${pcolor(`${map.testedSources}/${map.sourceFiles} (${pct}%)`)} of source files have at least one test`));
+    if (!opts.untested && opts.links && map.links.length > 0) {
+        console.log(`\n${indent(bold("Links:"))}`);
+        table(map.links.map((l) => [l.via === "import" ? green(l.via) : yellow(l.via), l.test, "→ " + l.source]), [["Via", 7], ["Test", 38], ["Source", 40]]);
+    }
+    if (map.untested.length > 0) {
+        console.log(`\n${indent(`${bold("Untested sources")} ${dim("(by risk: fan-in, then symbols)")}`)}`);
+        table(map.untested.slice(0, opts.top).map((u) => [String(u.afferent), String(u.symbols), u.file]), [["Ca", 4], ["Syms", 5], ["File", 52]]);
+        if (map.untested.length > opts.top)
+            console.log(indent(dim(`… ${map.untested.length - opts.top} more (use -n)`)));
+    }
+    else if (map.sourceFiles > 0) {
+        console.log(indent(green("✓ every source file has at least one test")));
+    }
+    if (!opts.untested && map.orphanTests.length > 0) {
+        console.log(`\n${indent(`${bold("Orphan tests")} ${dim("(no source matched — integration/e2e?)")}`)}`);
+        for (const t of map.orphanTests.slice(0, 10))
+            console.log(indent(dim(t), 4));
+    }
+    console.log();
+});
 // ─── Command: deps ────────────────────────────────────────────────────────────
 program
     .command("deps <file>")

package/dist/index.js

@@ -18,6 +18,7 @@ import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTop
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
 import { semanticSearch } from "./semantic.js";
+import { mapTestCoverage } from "./testmap.js";
 import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
@@ -1191,6 +1192,45 @@ server.registerTool("semantic_search", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: get_test_coverage ───────────────────────────── */
+server.registerTool("get_test_coverage", {
+    title: "Test-coverage map (tests ↔ sources)",
+    description: "Structural test coverage: pair test files with the source files they exercise and list " +
+        "source files no test touches. Two signals: a test file *importing* a source file " +
+        "(definitive) and naming conventions (auth.test.ts → auth.ts, test_utils.py → utils.py). " +
+        "No instrumentation or test runner needed. Untested files are ranked by risk " +
+        "(fan-in, then symbol count). This is file-level coverage, not line coverage.",
+    inputSchema: {
+        path: z.string().optional().describe("Directory to scan (should include the test files). Default project root."),
+        untestedOnly: z.boolean().optional().describe("Return only the untested-sources list. Default false."),
+    },
+}, async ({ path: input, untestedOnly }) => {
+    try {
+        const { abs, rel, root } = resolveInRoot(input ?? ".");
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. get_test_coverage requires a directory.`);
+        }
+        const opts = resolveOptions({ detail: "outline", emitHtml: false });
+        const files = collectSourceFiles(abs, opts);
+        const skels = [];
+        for (const f of files) {
+            const r = path.relative(root, f).split(path.sep).join("/");
+            try {
+                skels.push(await buildSkeleton(f, r, opts));
+            }
+            catch { /* skip */ }
+        }
+        const map = mapTestCoverage(buildSymbolGraph(skels, root));
+        const dir = rel.split(path.sep).join("/") || ".";
+        if (untestedOnly) {
+            return jsonText({ directory: dir, untestedSources: map.untestedSources, coverageRatio: map.coverageRatio, untested: map.untested });
+        }
+        return jsonText({ directory: dir, ...map });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_file_deps ───────────────────────────────── */
 server.registerTool("get_file_deps", {
     title: "Get file-level import dependencies",

package/dist/testmap.js

@@ -0,0 +1,167 @@
+/**
+ * Test-coverage mapping — pair test files with the source files they exercise,
+ * and surface source files no test touches.
+ *
+ * This is *structural* coverage (which files have tests at all), not line
+ * coverage — no instrumentation, no test runner, works on a cold checkout.
+ *
+ * Two matching signals, strongest first:
+ *   1. import  — a test file imports the source file (graph edge; definitive).
+ *   2. name    — naming convention pairs them ("auth.test.ts" → "auth.ts",
+ *                "test_utils.py" → "utils.py", "FooTest.java" → "Foo.java"),
+ *                resolved to the candidate sharing the longest path prefix.
+ */
+// ─── Test-file detection ───────────────────────────────────────────────────────
+const TEST_DIRS = new Set(["test", "tests", "__tests__", "spec", "specs", "testing", "e2e", "integration-tests"]);
+/** Support material, not tests and not production source: excluded from both sides. */
+const FIXTURE_DIRS = new Set(["fixtures", "fixture", "__fixtures__", "__mocks__", "mocks", "testdata", "snapshots", "__snapshots__"]);
+/** True when a rel path lives under a fixtures/mocks/testdata directory. */
+export function isFixtureFile(rel) {
+    return rel.split("/").slice(0, -1).some((d) => FIXTURE_DIRS.has(d.toLowerCase()));
+}
+const TEST_BASENAME_PATTERNS = [
+    /\.(test|spec)\.[^.]+$/i, // auth.test.ts, auth.spec.js
+    /[_-](test|tests|spec)\.[^.]+$/i, // auth_test.go, auth-test.js, auth_spec.rb
+    /^(test|spec)[_-]/i, // test_auth.py, spec_auth.rb
+    /Tests?\.(java|cs|kt|kts|swift|scala)$/, // AuthTest.java, AuthTests.cs
+    /Spec\.(java|cs|kt|kts|swift|scala)$/, // AuthSpec.kt
+];
+/** True when a rel path (forward-slashed) looks like a test file. */
+export function isTestFile(rel) {
+    const parts = rel.split("/");
+    const base = parts[parts.length - 1];
+    if (parts.slice(0, -1).some((d) => TEST_DIRS.has(d.toLowerCase())))
+        return true;
+    return TEST_BASENAME_PATTERNS.some((re) => re.test(base));
+}
+/**
+ * Derive the source basename a test file's name points at, or null when the
+ * name carries no convention ("smoke.mjs" in a test dir → null).
+ * "auth.test.ts" → "auth" · "test_utils.py" → "utils" · "AuthTest.java" → "Auth"
+ */
+export function testNameTarget(rel) {
+    const base = rel.split("/").pop();
+    const noExt = base.replace(/\.[^.]+$/, "");
+    let t = noExt
+        .replace(/\.(test|spec)$/i, "")
+        .replace(/[_-](test|tests|spec|smoke)$/i, "")
+        .replace(/\.(smoke)$/i, "")
+        .replace(/^(test|spec)[_-]/i, "")
+        .replace(/(Test|Tests|Spec)$/, "");
+    if (t === noExt || t.length === 0)
+        return null;
+    return t;
+}
+// ─── Mapping ───────────────────────────────────────────────────────────────────
+function commonPrefixLen(a, b) {
+    const pa = a.split("/");
+    const pb = b.split("/");
+    let i = 0;
+    while (i < pa.length - 1 && i < pb.length - 1 && pa[i] === pb[i])
+        i++;
+    return i;
+}
+function baseNoExt(rel) {
+    return rel.split("/").pop().replace(/\.[^.]+$/, "");
+}
+/**
+ * Build the test↔source coverage map from a symbol graph
+ * (use `buildSymbolGraph` over a directory that includes the test files).
+ */
+export function mapTestCoverage(graph) {
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    const allFiles = graph.nodes.filter((n) => n.nodeType === "file");
+    const fixtureCount = allFiles.filter((f) => isFixtureFile(f.id)).length;
+    const files = allFiles.filter((f) => !isFixtureFile(f.id));
+    const testFiles = files.filter((f) => isTestFile(f.id));
+    const sourceFiles = files.filter((f) => !isTestFile(f.id));
+    const isTest = new Set(testFiles.map((f) => f.id));
+    const sourceByBase = new Map();
+    for (const s of sourceFiles) {
+        const b = baseNoExt(s.id).toLowerCase();
+        (sourceByBase.get(b) ?? sourceByBase.set(b, []).get(b)).push(s.id);
+    }
+    // Signal 1: import edges test → source. Also count source-side fan-in (Ca).
+    const links = [];
+    const seen = new Set();
+    const afferent = new Map(); // source ← importers (non-test)
+    for (const e of graph.edges) {
+        if (e.edgeType !== "imports")
+            continue;
+        const to = nodeMap.get(e.to);
+        const toFile = to ? (to.nodeType === "file" ? to.id : to.file) : null;
+        if (!toFile || e.from === toFile)
+            continue;
+        if (isTest.has(e.from) && !isTest.has(toFile)) {
+            const key = e.from + "|" + toFile;
+            if (!seen.has(key)) {
+                seen.add(key);
+                links.push({ test: e.from, source: toFile, via: "import" });
+            }
+        }
+        else if (!isTest.has(e.from) && !isTest.has(toFile)) {
+            (afferent.get(toFile) ?? afferent.set(toFile, new Set()).get(toFile)).add(e.from);
+        }
+    }
+    // Signal 2: naming convention, for test files with no import link yet.
+    const linkedTests = new Set(links.map((l) => l.test));
+    for (const t of testFiles) {
+        if (linkedTests.has(t.id))
+            continue;
+        // Explicit marker in the name, else (for files inside test dirs, where the
+        // dir itself is the marker) the plain basename: test/analysis.mjs → "analysis".
+        const target = testNameTarget(t.id) ?? baseNoExt(t.id);
+        const candidates = sourceByBase.get(target.toLowerCase());
+        if (!candidates || candidates.length === 0)
+            continue;
+        // Prefer the candidate sharing the longest directory prefix with the test.
+        let best = [];
+        let bestScore = -1;
+        for (const c of candidates) {
+            const s = commonPrefixLen(t.id, c);
+            if (s > bestScore) {
+                bestScore = s;
+                best = [c];
+            }
+            else if (s === bestScore)
+                best.push(c);
+        }
+        for (const c of best) {
+            const key = t.id + "|" + c;
+            if (!seen.has(key)) {
+                seen.add(key);
+                links.push({ test: t.id, source: c, via: "name" });
+            }
+        }
+    }
+    // Aggregate.
+    const testsBySource = new Map();
+    for (const l of links) {
+        (testsBySource.get(l.source) ?? testsBySource.set(l.source, []).get(l.source)).push(l.test);
+    }
+    const tested = [];
+    const untested = [];
+    for (const s of sourceFiles) {
+        const tests = testsBySource.get(s.id);
+        if (tests)
+            tested.push({ file: s.id, tests: [...new Set(tests)].sort() });
+        else
+            untested.push({ file: s.id, symbols: s.symbolCount, afferent: afferent.get(s.id)?.size ?? 0 });
+    }
+    tested.sort((a, b) => a.file.localeCompare(b.file));
+    untested.sort((a, b) => b.afferent - a.afferent || b.symbols - a.symbols || a.file.localeCompare(b.file));
+    const covered = new Set(links.map((l) => l.test));
+    const orphanTests = testFiles.map((f) => f.id).filter((id) => !covered.has(id)).sort();
+    return {
+        sourceFiles: sourceFiles.length,
+        testFiles: testFiles.length,
+        fixtureFiles: fixtureCount,
+        testedSources: tested.length,
+        untestedSources: untested.length,
+        coverageRatio: sourceFiles.length === 0 ? 0 : Math.round((tested.length / sourceFiles.length) * 100) / 100,
+        links,
+        tested,
+        untested,
+        orphanTests,
+    };
+}

package/package.json

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