universal-ast-mapper 1.24.0 → 1.25.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.25.0] — 2026-06-11 · Semantic symbol search
+- **New MCP tool `semantic_search`** + **CLI `ast-map find <query> [dir]`** — find
+  symbols by *meaning*, not exact name: "remove expired cache entries" →
+  `clearDiskCache`, "find unused exported code" → `findDeadExports`.
+- Pure lexical semantics — **no embeddings, no network, no model downloads**:
+  - **Identifier tokenization**: camelCase / PascalCase / snake_case / kebab-case /
+    digit and acronym boundaries (`getHTTPServerByID` → `get http server by id`).
+  - **Programming thesaurus**: 60 synonym groups (`fetch≈get≈load≈retrieve`,
+    `remove≈delete≈clear`, `unused≈dead`, `auth≈login≈session`, …).
+  - **Light stemming** (plural/gerund/past: `users`→`user`) + **fuzzy matching**
+    (edit distance ≤ 1 on tokens ≥ 4 chars).
+  - **BM25-style ranking**: corpus IDF (rare tokens weigh more), field weights
+    (name 3× > doc 2× > signature 1.5× > path/kind 1×), match-type weights
+    (direct > synonym > fuzzy), coverage bonus, and length normalization so
+    focused names (`login`) outrank composites (`handleLogin`).
+- Results include a normalized `score` (0–1) and `matchedTerms` explaining each hit
+  (`unused≈dead` = synonym, `cach~cache` = fuzzy).
+- Options: `limit` (default 20), `kind` filter, `exportedOnly`.
+- New module `semantic` (`semanticSearch`, `splitIdentifier`, `stem`). Tests: +8
+  checks in `test/analysis.mjs` (139 total). **29 MCP tools / 31 CLI commands.**
+
 ## [1.24.0] — 2026-06-10 · TS path-alias resolution
 - Bare imports like `@/components/Button` now resolve through **`tsconfig.json` /
   `jsconfig.json` `compilerOptions.paths`** (+ `baseUrl`): nearest-config lookup above
@@ -232,4 +253,36 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
   declared in 2+ files.
 
 ## [0.8.3] — 2026-05-31 · TSX/React component props
-- Component s
+- Component symbols carry `propsType` + `props[]`; detects `React.FC<P>` and
+  JSX-returning PascalCase functions. MCP server version now read from package.json.
+
+## [0.8.2] — 2026-05-30 · Swift cross-file wiring
+- `import <Module>` → that module's files (`Sources/<Module>/`). Completes
+  cross-file graph/resolver support for all four v0.8.0 languages.
+
+## [0.8.1] — 2026-05-30 · Kotlin + C/C++ cross-file wiring
+- Kotlin FQCN/package index; C/C++ `#include` resolution with header↔impl pairing.
+- Fixes: parse-cache rel-path leak; Kotlin call-graph extraction.
+
+---
+
+## Earlier (pre-session history)
+
+- **0.8.0** — +4 languages: C · C++ · Kotlin · Swift (symbol extraction + imports).
+- **0.7.0** — Go full module resolution; C# reverse `calledBy`; 4-suite test harness.
+- **0.6.0** — +3 languages: Rust · Java · C#; cross-language resolver.
+- **0.5.x** — `/ast-map` skill auto-install; iterative DFS; barrel re-exports; parse cache; call-graph aliases; `.ast-map.config.json`.
+- **0.4.0** — `search_symbol`, `get_file_deps`, `get_top_symbols`, dead-code tiers.
+- **0.3.0** — CLI; `find_dead_code`, `find_circular_deps`, `get_change_impact`, `get_call_graph`.
+- **0.2.0** — import extraction; `resolve_imports`; `build_symbol_graph`.
+- **0.1.0** — `get_skeleton_json`, `generate_skeleton`, `get_symbol_context`, `validate_architecture`.
+
+[1.13.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.13.0
+[1.12.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.12.0
+[1.11.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.11.0
+[1.10.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.10.0
+[1.9.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.9.0
+[1.8.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.8.0
+[1.7.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.7.0
+[1.6.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.6.0
+[1.5.0]: https://github.com/6ixthxense/AST-MCP/releases/tag/v1.5.0

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.
 
-**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).
+**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** (`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**
 
@@ -127,6 +127,7 @@ ast-map modules   [dir]                          # directory-level coupling + ed
 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 find     <query> [dir]     [-l N] [-k kind] [-e]   # semantic: by meaning
 ast-map deps     <file>            [--scan <dir>]
 ast-map top      <dir>             [-n 10]
 ast-map impact   <file> <symbol>   [--scan <dir>]
@@ -155,6 +156,9 @@ ast-map validate src/ --max-lines 300 --max-imports 20
 # Find all symbols named like "handler" across the project
 ast-map search handler src/ --exported
 
+# Don't know the name? Search by meaning
+ast-map find "remove expired cache entries" src/
+
 # What does this file import / what imports it?
 ast-map deps src/lib/auth.ts --scan src/
 
@@ -514,6 +518,21 @@ Find symbols by name across all source files in a directory.
 
 ---
 
+### `semantic_search`
+Find symbols by **meaning**, not exact name — for when you know what the code *does* but not what it's called.
+
+No embeddings, no network: identifier tokenization (camelCase / snake_case / acronyms), a built-in programming thesaurus (`fetch≈get≈load`, `remove≈delete≈clear`, `unused≈dead`, …), light stemming, fuzzy matching, and BM25-style IDF ranking over symbol names, doc comments, signatures and file paths. Results carry a normalized `score` and `matchedTerms` explaining *why* each symbol matched.
+
+```
+semantic_search("find unused exported code") →
+  1.000  findDeadExports    (find, unused≈dead, export)
+  0.557  DeadExport         (unused≈dead, export)
+```
+
+**Params:** `path`, `query`, `limit` (default 20), `kind`, `exportedOnly`
+
+---
+
 ### `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.
@@ -801,6 +820,7 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **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%. |
 | **1.23.0** | **Configurable root boundary** — `AST_MAP_ROOT` accepts **multiple roots** (path-delimiter separated) and `AST_MAP_UNLOCKED=1` allows analyzing **any absolute path** on request (default stays locked). Analysis/graph/report rel-paths now computed against the matched root, so cross-root results are correct. New `roots` module + 13-check test suite. |
 | **1.22.0** | **PHP & Ruby support** — `.php` (classes, interfaces, traits, enums, methods with visibility, `use` imports incl. grouped, require/include) and `.rb`/`.rake` (classes, modules, methods, `self.` singleton methods, `private` section tracking, require/require_relative). Unblocked by upgrading `web-tree-sitter` 0.20.8 → 0.21.0 (all existing grammars re-verified). **16 languages**. |
@@ -834,4 +854,7 @@ Not part of the public API: the internal `src/` module layout and the generated
 | **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. |
 | **0.8.6** | **Unused parameter detection** — new `find_unused_params` MCP tool + `ast-map unused-params` (alias `unused`) CLI: named functions whose params are never referenced. Skips `_`-prefixed/destructured/anonymous and treats object-shorthand as a use (low false-positive). Server now 17 tools. |
-| **0.8.5** | **Cyclomatic complexity** — new `get_complexity` MCP tool + `ast-map complex
+| **0.8.5** | **Cyclomatic complexity** — new `get_complexity` MCP tool + `ast-map complexity` (alias `cx`) CLI: per-function cyclomatic complexity with low/moderate/high/very-high ratings, file or directory scope. |
+| **0.8.4** | **Duplicate symbol detection** — `find_duplicate_symbols` / `ast-map duplicates` (alias `dupes`): symbol names exported from more than one file. |
+| **0.8.1–0.8.3** | Kotlin + C/C++ cross-file wiring · Swift module resolution (`Sources/<Module>/`) · TSX/React component props (`propsType` + `props[]`, `React.FC<P>` detection). |
+| **0.1.0–0.8.0** | Foundation: skeleton extraction (`get_skeleton_json`, `generate_skeleton`, `get_symbol_context`, `validate_architecture`) · import resolution + symbol graph · dead code / cycles / impact / call graph · CLI · 12 languages (+Rust · Java · C# · Go · C · C++ · Kotlin · Swift) · `/ast-map` skill auto-install · barrel re-exports · parse cache. |

package/dist/cli.js

@@ -27,6 +27,7 @@ import { findLayerViolations } from "./layers.js";
 import { computeModuleCoupling } from "./modulecoupling.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
+import { semanticSearch } from "./semantic.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).
@@ -1092,6 +1093,43 @@ program
     }
     console.log();
 });
+// ─── Command: find (semantic search) ─────────────────────────────────────────
+program
+    .command("find <query> [dir]")
+    .description("Semantic symbol search — find symbols by meaning, not exact name")
+    .option("-l, --limit <n>", "Max results (default 20)", "20")
+    .option("-k, --kind <kind>", "Filter by kind: function, class, interface, type, method, const…")
+    .option("-e, --exported", "Only show exported symbols")
+    .option("--json", "Output as JSON")
+    .action(async (query, dir, opts) => {
+    const searchDir = dir ?? ".";
+    const { abs, rel } = resolveArg(searchDir);
+    if (!fs.statSync(abs).isDirectory())
+        die(`"${rel}" is not a directory`);
+    const limit = Math.max(1, parseInt(opts.limit ?? "20", 10) || 20);
+    const matches = await semanticSearch(abs, query, ROOT, {
+        limit,
+        kind: opts.kind,
+        exportedOnly: opts.exported,
+    });
+    if (opts.json)
+        return jsonOut({ directory: rel, query, matchCount: matches.length, matches });
+    header(`Semantic Search — ${bold(`"${query}"`)} in ${rel}/`);
+    if (matches.length === 0) {
+        console.log(indent(dim("No matches found.")));
+    }
+    else {
+        table(matches.map(m => [
+            m.score.toFixed(3),
+            m.file,
+            m.symbol,
+            m.kind,
+            m.matchedTerms.slice(0, 4).join(", "),
+        ]), [["Score", 6], ["File", 34], ["Symbol", 26], ["Kind", 10], ["Matched", 30]]);
+        console.log(`\n  ${matches.length} match(es)`);
+    }
+    console.log();
+});
 // ─── Command: deps ────────────────────────────────────────────────────────────
 program
     .command("deps <file>")

package/dist/index.js

@@ -17,6 +17,7 @@ import { buildSymbolGraph } from "./graph.js";
 import { findDeadExports, findCircularDeps, getChangeImpact, getFileDeps, getTopSymbols, findDuplicateSymbols } from "./graph-analysis.js";
 import { buildCallGraph } from "./callgraph.js";
 import { searchSymbols } from "./search.js";
+import { semanticSearch } from "./semantic.js";
 import { computeFileComplexity } from "./complexity.js";
 import { findUnusedParams } from "./unused-params.js";
 import { traceTypeInFile } from "./typeflow.js";
@@ -1146,6 +1147,50 @@ server.registerTool("search_symbol", {
         return errorText(describeError(err));
     }
 });
+/* ─────────────────── tool: semantic_search ─────────────────────── */
+server.registerTool("semantic_search", {
+    title: "Search symbols by meaning",
+    description: "Find symbols by *meaning*, not exact name. Tokenizes identifiers (camelCase/snake_case), " +
+        "expands programming synonyms (fetch≈get≈load, remove≈delete≈destroy, …), applies light " +
+        "stemming and fuzzy matching, and ranks with BM25-style IDF weighting over symbol names, " +
+        "doc comments, signatures and file paths.\n" +
+        'Use when you know what code *does* but not what it\'s called: "remove expired sessions", ' +
+        '"parse config file", "validate user input".',
+    inputSchema: {
+        path: z
+            .string()
+            .describe("Directory to search in, relative to project root or absolute within it."),
+        query: z
+            .string()
+            .describe('What the code does, e.g. "delete old cache entries" or "load user settings".'),
+        limit: z.number().int().min(1).max(100).optional().describe("Max results. Default 20."),
+        kind: z
+            .enum(["function", "class", "interface", "type", "method", "const", "var", "enum", "struct", "field"])
+            .optional()
+            .describe("Filter by symbol kind."),
+        exportedOnly: z
+            .boolean()
+            .optional()
+            .describe("Only return exported symbols. Default false."),
+    },
+}, async ({ path: input, query, limit, kind, exportedOnly }) => {
+    try {
+        const { abs, rel, root } = resolveInRoot(input);
+        if (!fs.statSync(abs).isDirectory()) {
+            return errorText(`"${input}" is not a directory. semantic_search requires a directory.`);
+        }
+        const matches = await semanticSearch(abs, query, root, { limit, kind, exportedOnly });
+        return jsonText({
+            directory: rel.split(path.sep).join("/"),
+            query,
+            matchCount: matches.length,
+            matches,
+        });
+    }
+    catch (err) {
+        return errorText(describeError(err));
+    }
+});
 /* ─────────────────── tool: get_file_deps ───────────────────────────────── */
 server.registerTool("get_file_deps", {
     title: "Get file-level import dependencies",

package/dist/semantic.js

@@ -0,0 +1,365 @@
+/**
+ * Semantic symbol search — find symbols by *meaning*, not exact name.
+ *
+ * No embeddings, no network, no model downloads. Pure lexical semantics:
+ *   1. Identifier tokenization  — camelCase / PascalCase / snake_case /
+ *      kebab-case / digits / acronym boundaries ("HTTPServer" → http, server).
+ *   2. Concept expansion        — a built-in thesaurus of programming
+ *      synonym groups (fetch≈get≈load≈retrieve, remove≈delete≈destroy, …).
+ *   3. Light stemming           — plural/gerund/past suffixes folded so
+ *      "parsing" matches "parse", "users" matches "user".
+ *   4. BM25-style ranking       — rare tokens weigh more (IDF over the
+ *      scanned corpus); name hits outweigh doc/signature/path hits;
+ *      direct hits outweigh synonym hits outweigh fuzzy hits.
+ */
+import path from "node:path";
+import { buildSkeleton, collectSourceFiles } from "./skeleton.js";
+import { resolveOptions, loadProjectConfig } from "./config.js";
+// ─── Synonym groups (programming thesaurus) ────────────────────────────────────
+// Tokens in the same group are considered semantically equivalent (at a small
+// penalty vs. a direct match). Keep each group tight — over-broad groups cause
+// noisy results.
+const SYNONYM_GROUPS = [
+    ["get", "fetch", "load", "retrieve", "read", "lookup", "resolve"],
+    ["set", "update", "write", "assign", "put", "patch", "modify", "change", "edit"],
+    ["create", "make", "build", "new", "generate", "construct", "init", "initialize", "spawn"],
+    ["delete", "remove", "destroy", "drop", "clear", "purge", "erase"],
+    ["find", "search", "query", "locate", "match", "scan", "discover"],
+    ["send", "dispatch", "emit", "publish", "post", "broadcast", "notify"],
+    ["receive", "consume", "subscribe", "listen", "handle", "process"],
+    ["start", "begin", "launch", "run", "execute", "invoke", "trigger"],
+    ["stop", "end", "halt", "kill", "terminate", "cancel", "abort", "shutdown", "close"],
+    ["check", "validate", "verify", "test", "assert", "ensure", "confirm"],
+    ["parse", "decode", "deserialize", "unmarshal", "extract", "tokenize"],
+    ["format", "encode", "serialize", "marshal", "stringify", "render", "print"],
+    ["convert", "transform", "map", "translate", "cast", "normalize"],
+    ["user", "account", "member", "person", "profile", "customer"],
+    ["auth", "authenticate", "login", "signin", "authorize", "session", "credential"],
+    ["config", "configuration", "settings", "options", "preferences", "setup"],
+    ["error", "exception", "fault", "failure", "err", "panic"],
+    ["log", "logger", "logging", "trace", "audit"],
+    ["cache", "memo", "memoize", "store", "buffer"],
+    ["list", "enumerate", "all", "collection", "array", "items"],
+    ["count", "total", "sum", "aggregate", "tally"],
+    ["file", "document", "path", "filename"],
+    ["dir", "directory", "folder"],
+    ["request", "req", "call", "http"],
+    ["response", "res", "reply", "result", "output"],
+    ["message", "msg", "event", "signal"],
+    ["connect", "connection", "link", "attach", "bind", "join"],
+    ["disconnect", "detach", "unbind", "release", "unsubscribe"],
+    ["save", "persist", "commit", "flush", "sync"],
+    ["copy", "clone", "duplicate", "snapshot"],
+    ["merge", "combine", "concat", "union", "join"],
+    ["split", "divide", "partition", "chunk", "segment"],
+    ["sort", "order", "rank", "arrange"],
+    ["filter", "select", "exclude", "where"],
+    ["compare", "diff", "equal", "equals", "cmp"],
+    ["compute", "calculate", "calc", "derive", "evaluate", "measure"],
+    ["watch", "observe", "monitor", "track", "poll"],
+    ["wait", "sleep", "delay", "debounce", "throttle", "defer"],
+    ["retry", "attempt", "backoff"],
+    ["lock", "mutex", "semaphore", "guard"],
+    ["queue", "stack", "heap", "pool", "buffer"],
+    ["graph", "tree", "node", "edge", "vertex"],
+    ["dependency", "dep", "import", "require"],
+    ["token", "symbol", "identifier", "ident", "name"],
+    ["database", "db", "storage", "repository", "repo", "dao"],
+    ["key", "id", "identifier", "uuid", "guid"],
+    ["string", "str", "text", "char"],
+    ["number", "num", "int", "integer", "float", "numeric"],
+    ["boolean", "bool", "flag", "toggle"],
+    ["helper", "util", "utility", "utils", "tool", "common"],
+    ["test", "spec", "mock", "stub", "fixture"],
+    ["render", "draw", "paint", "display", "show", "view"],
+    ["hide", "conceal", "mask", "suppress"],
+    ["enable", "activate", "on"],
+    ["disable", "deactivate", "off"],
+    ["add", "insert", "append", "push", "register"],
+    ["pop", "shift", "dequeue", "take"],
+    ["circular", "cycle", "cyclic", "loop", "recursive"],
+    ["dead", "unused", "orphan", "unreachable", "stale"],
+    ["complexity", "complex", "cyclomatic", "cognitive"],
+    ["coupling", "cohesion", "instability", "afferent", "efferent"],
+];
+const GROUP_OF = new Map();
+SYNONYM_GROUPS.forEach((group, gi) => {
+    for (const word of group) {
+        // Register both raw and stemmed forms so stemmed corpus/query tokens
+        // ("setting", "item") still hit groups declared as "settings", "items".
+        for (const form of new Set([word, stem(word)])) {
+            const list = GROUP_OF.get(form);
+            if (list) {
+                if (!list.includes(gi))
+                    list.push(gi);
+            }
+            else {
+                GROUP_OF.set(form, [gi]);
+            }
+        }
+    }
+});
+// ─── Tokenization ──────────────────────────────────────────────────────────────
+/** Light stemmer: fold common English suffixes so "parsing"→"parse", "users"→"user". */
+export function stem(word) {
+    let w = word;
+    if (w.length > 4 && w.endsWith("ies"))
+        return w.slice(0, -3) + "y";
+    if (w.length > 4 && w.endsWith("ing")) {
+        w = w.slice(0, -3);
+        // "mapping" → "mapp" → "map"; "parsing" → "pars" → add back "e"? keep both simple:
+        if (w.length > 2 && w[w.length - 1] === w[w.length - 2])
+            w = w.slice(0, -1);
+        return w;
+    }
+    if (w.length > 4 && w.endsWith("ed")) {
+        w = w.slice(0, -2);
+        if (w.length > 2 && w[w.length - 1] === w[w.length - 2])
+            w = w.slice(0, -1);
+        return w;
+    }
+    if (w.length > 3 && w.endsWith("es"))
+        return w.slice(0, -2);
+    if (w.length > 3 && w.endsWith("s") && !w.endsWith("ss"))
+        return w.slice(0, -1);
+    return w;
+}
+/**
+ * Split an identifier into lowercase word tokens.
+ * Handles camelCase, PascalCase, snake_case, kebab-case, dots, digits and
+ * acronym boundaries: "getHTTPServerByID" → [get, http, server, by, id].
+ */
+export function splitIdentifier(identifier) {
+    const out = [];
+    for (const chunk of identifier.split(/[^A-Za-z0-9]+/)) {
+        if (!chunk)
+            continue;
+        // Insert boundaries: aA | AAa (acronym→word) | letter↔digit
+        const spaced = chunk
+            .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+            .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+            .replace(/([A-Za-z])([0-9])/g, "$1 $2")
+            .replace(/([0-9])([A-Za-z])/g, "$1 $2");
+        for (const word of spaced.split(" ")) {
+            if (word)
+                out.push(word.toLowerCase());
+        }
+    }
+    return out;
+}
+/** Levenshtein distance with early exit when > max. */
+function editDistance(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    const prev = new Array(b.length + 1);
+    const curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        let rowMin = curr[0];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+            if (curr[j] < rowMin)
+                rowMin = curr[j];
+        }
+        if (rowMin > max)
+            return max + 1;
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j];
+    }
+    return prev[b.length];
+}
+function sharesGroup(a, b) {
+    const ga = GROUP_OF.get(a);
+    if (!ga)
+        return false;
+    const gb = GROUP_OF.get(b);
+    if (!gb)
+        return false;
+    return ga.some((g) => gb.includes(g));
+}
+const FIELD_WEIGHT = { name: 3, doc: 2, signature: 1.5, path: 1, kind: 1 };
+function addToken(doc, raw, weight) {
+    const t = stem(raw);
+    if (t.length < 2)
+        return;
+    const existing = doc.tokens.get(t);
+    if (existing === undefined || weight > existing)
+        doc.tokens.set(t, weight);
+}
+function* flattenDocs(symbols, file, parentName) {
+    for (const sym of symbols) {
+        const fullName = parentName ? `${parentName}.${sym.name}` : sym.name;
+        yield { sym, fullName };
+        if (sym.children.length > 0)
+            yield* flattenDocs(sym.children, file, fullName);
+    }
+}
+function buildDoc(sym, fullName, file) {
+    const doc = {
+        match: {
+            file,
+            symbol: fullName,
+            kind: sym.kind,
+            exported: sym.exported ?? false,
+            range: sym.range,
+            ...(sym.signature ? { signature: sym.signature } : {}),
+        },
+        tokens: new Map(),
+        nameTokens: new Set(),
+    };
+    for (const t of splitIdentifier(fullName)) {
+        addToken(doc, t, FIELD_WEIGHT.name);
+        doc.nameTokens.add(stem(t));
+    }
+    addToken(doc, sym.kind, FIELD_WEIGHT.kind);
+    if (sym.doc) {
+        for (const t of splitIdentifier(sym.doc))
+            addToken(doc, t, FIELD_WEIGHT.doc);
+    }
+    if (sym.signature) {
+        for (const t of splitIdentifier(sym.signature))
+            addToken(doc, t, FIELD_WEIGHT.signature);
+    }
+    for (const seg of file.split("/")) {
+        for (const t of splitIdentifier(seg))
+            addToken(doc, t, FIELD_WEIGHT.path);
+    }
+    return doc;
+}
+// ─── Scoring ───────────────────────────────────────────────────────────────────
+const MATCH_WEIGHT = { direct: 1, synonym: 0.7, fuzzy: 0.45 };
+// English/query stopwords — ignored as query concepts.
+const STOPWORDS = new Set([
+    "a", "an", "the", "of", "in", "on", "for", "to", "with", "that", "this",
+    "is", "are", "be", "and", "or", "by", "from", "at", "it", "its", "as",
+    "do", "does", "how", "what", "which", "where", "when", "i", "we", "you",
+    "function", "method", "code", "thing", "stuff", "something",
+]);
+/**
+ * Search for symbols by meaning across all source files in a directory.
+ *
+ * @param dirAbs   Absolute path of directory to scan.
+ * @param query    Natural-language-ish query, e.g. "remove expired sessions".
+ * @param root     Project root (for relative paths in results).
+ * @param options  limit, kind filter, exportedOnly.
+ */
+export async function semanticSearch(dirAbs, query, root, options = {}) {
+    const { limit = 20, kind, exportedOnly = false } = options;
+    // Query concepts: tokenized, stopword-filtered, stemmed (dedup, keep order).
+    const concepts = [];
+    for (const raw of splitIdentifier(query)) {
+        if (STOPWORDS.has(raw))
+            continue;
+        const t = stem(raw);
+        if (t.length >= 2 && !concepts.includes(t))
+            concepts.push(t);
+    }
+    if (concepts.length === 0)
+        return [];
+    // Build corpus (detail "full" so doc comments and signatures are available).
+    const opts = resolveOptions({ detail: "full", emitHtml: false }, loadProjectConfig(root));
+    const files = collectSourceFiles(dirAbs, opts);
+    const docs = [];
+    for (const file of files) {
+        const fileRel = path.relative(root, file).split(path.sep).join("/");
+        try {
+            const skel = await buildSkeleton(file, fileRel, opts);
+            for (const { sym, fullName } of flattenDocs(skel.symbols, skel.file)) {
+                if (kind && sym.kind !== kind)
+                    continue;
+                if (exportedOnly && !(sym.exported ?? false))
+                    continue;
+                docs.push(buildDoc(sym, fullName, skel.file));
+            }
+        }
+        catch {
+            // skip unreadable / unparseable files
+        }
+    }
+    if (docs.length === 0)
+        return [];
+    // Document frequency per concept (direct-token presence) → BM25-ish IDF.
+    const N = docs.length;
+    const idf = new Map();
+    for (const concept of concepts) {
+        let df = 0;
+        for (const doc of docs)
+            if (doc.tokens.has(concept))
+                df++;
+        idf.set(concept, Math.log(1 + (N - df + 0.5) / (df + 0.5)));
+    }
+    const scored = [];
+    for (const doc of docs) {
+        let score = 0;
+        const matchedTerms = [];
+        let nameHits = 0;
+        for (const concept of concepts) {
+            let best = 0;
+            let how = null;
+            for (const [token, fieldWeight] of doc.tokens) {
+                let mw = 0;
+                let label = null;
+                if (token === concept) {
+                    mw = MATCH_WEIGHT.direct;
+                    label = concept;
+                }
+                else if (sharesGroup(token, concept)) {
+                    mw = MATCH_WEIGHT.synonym;
+                    label = `${concept}≈${token}`;
+                }
+                else if (concept.length >= 4 &&
+                    token.length >= 4 &&
+                    editDistance(token, concept, 1) <= 1) {
+                    mw = MATCH_WEIGHT.fuzzy;
+                    label = `${concept}~${token}`;
+                }
+                const contribution = mw * fieldWeight;
+                if (contribution > best) {
+                    best = contribution;
+                    how = label;
+                    if (fieldWeight >= FIELD_WEIGHT.name && mw === MATCH_WEIGHT.direct)
+                        break; // can't beat this
+                }
+            }
+            if (best > 0 && how) {
+                score += best * (idf.get(concept) ?? 1);
+                matchedTerms.push(how);
+                if (doc.nameTokens.has(concept))
+                    nameHits++;
+            }
+        }
+        if (matchedTerms.length === 0)
+            continue;
+        // Bonuses: all concepts matched; full query substring of name; coverage ratio.
+        const coverage = matchedTerms.length / concepts.length;
+        score *= 0.5 + 0.5 * coverage;
+        if (nameHits === concepts.length)
+            score *= 1.25;
+        const flatQuery = concepts.join("");
+        if (doc.match.symbol.toLowerCase().includes(flatQuery))
+            score *= 1.2;
+        // Length normalization: prefer focused names — "login" beats "handleLogin"
+        // when both match the same concepts. Penalize name tokens no concept explains.
+        let unmatchedNameTokens = 0;
+        for (const t of doc.nameTokens) {
+            const explained = concepts.some((c) => t === c ||
+                sharesGroup(t, c) ||
+                (c.length >= 4 && t.length >= 4 && editDistance(t, c, 1) <= 1));
+            if (!explained)
+                unmatchedNameTokens++;
+        }
+        score /= 1 + 0.15 * unmatchedNameTokens;
+        scored.push({ ...doc.match, score, matchedTerms });
+    }
+    scored.sort((a, b) => b.score - a.score || a.symbol.localeCompare(b.symbol));
+    const top = scored.slice(0, limit);
+    // Normalize scores to 0–1 within the result set.
+    const max = top.length > 0 ? top[0].score : 1;
+    if (max > 0)
+        for (const m of top)
+            m.score = Math.round((m.score / max) * 1000) / 1000;
+    return top;
+}

package/package.json

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