universal-ast-mapper 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ since 1.0.0, guarantees a stable MCP tool / CLI surface across the 1.x line.
 
 ---
 
+## [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
+  **instability** I = Ce/(Ca+Ce) on a green (0, stable) → yellow → red
+  (1, volatile) scale; orphan files stay gray.
+- **Legend** (bottom-left, shown in coupling mode) explains the scale; the hover
+  tooltip and the detail sidebar now show **Ca / Ce / I** per file.
+- Explorer nodes carry `ca` / `ce` / `inst` computed from the deduped file-level
+  import edges — same definition as `get_coupling` (Robert C. Martin metrics).
+- Still a single self-contained HTML file, dark-mode aware, zero dependencies.
+- Tests: +5 checks in `test/analysis.mjs` (144 total).
+
+## [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 +265,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** 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**
 
@@ -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,8 @@ Not part of the public API: the internal `src/` module layout and the generated
 
 | Version | What changed |
 |---------|--------------|
+| **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%. |
 | **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 +855,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/explorer.js

@@ -20,7 +20,7 @@ function deriveFileGraph(graph) {
             continue;
         const f = n;
         const parts = f.id.split("/");
-        nodes.push({ id: f.id, symbols: f.symbolCount, group: parts.length > 1 ? parts[0] : "(root)", lang: f.language, syms: fileSyms.get(f.id) ?? [] });
+        nodes.push({ id: f.id, symbols: f.symbolCount, group: parts.length > 1 ? parts[0] : "(root)", lang: f.language, syms: fileSyms.get(f.id) ?? [], ca: 0, ce: 0, inst: 0 });
     }
     const seen = new Set();
     const links = [];
@@ -37,6 +37,18 @@ function deriveFileGraph(graph) {
         seen.add(key);
         links.push({ source: e.from, target: toFile });
     }
+    // Per-file coupling (Ca = fan-in, Ce = fan-out, I = Ce/(Ca+Ce)) from the deduped links.
+    const outSet = new Map();
+    const inSet = new Map();
+    for (const l of links) {
+        (outSet.get(l.source) ?? outSet.set(l.source, new Set()).get(l.source)).add(l.target);
+        (inSet.get(l.target) ?? inSet.set(l.target, new Set()).get(l.target)).add(l.source);
+    }
+    for (const n of nodes) {
+        n.ce = outSet.get(n.id)?.size ?? 0;
+        n.ca = inSet.get(n.id)?.size ?? 0;
+        n.inst = n.ca + n.ce === 0 ? 0 : Math.round((n.ce / (n.ca + n.ce)) * 100) / 100;
+    }
     return { nodes, links };
 }
 const STYLE = "body{margin:0;font-family:system-ui,sans-serif;color:#222;background:#fafafa}" +
@@ -51,7 +63,10 @@ const STYLE = "body{margin:0;font-family:system-ui,sans-serif;color:#222;backgro
     "#panel .row{padding:3px 6px;border-radius:5px;cursor:pointer;word-break:break-all;line-height:1.5}#panel .row:hover{background:#f0f0f0}" +
     "#panel .sym{color:#444;padding:2px 6px;word-break:break-all}#panel .k{color:#999;font-size:11px}" +
     "#close{position:absolute;top:10px;right:12px;cursor:pointer;color:#999;font-size:18px;line-height:1;border:none;background:none}" +
-    "@media(prefers-color-scheme:dark){body{color:#ddd;background:#161616}#bar,#panel{background:#1e1e1e;border-color:#333}#q{background:#2a2a2a;border-color:#444;color:#ddd}#panel .row:hover{background:#2a2a2a}#panel .sym{color:#bbb}}";
+    "#mode{padding:5px 8px;border:1px solid #ddd;border-radius:6px;font-size:12px;background:#fff;color:#222}" +
+    "#leg{position:fixed;left:14px;bottom:14px;z-index:3;background:#fff;border:1px solid #e5e5e5;border-radius:8px;padding:8px 12px;font-size:11px;color:#555;display:none}" +
+    "#leg .bar{width:150px;height:8px;border-radius:4px;background:linear-gradient(90deg,hsl(120,65%,46%),hsl(60,75%,50%),hsl(0,70%,52%));margin:5px 0 3px}" +
+    "@media(prefers-color-scheme:dark){body{color:#ddd;background:#161616}#bar,#panel{background:#1e1e1e;border-color:#333}#q{background:#2a2a2a;border-color:#444;color:#ddd}#panel .row:hover{background:#2a2a2a}#panel .sym{color:#bbb}#mode{background:#2a2a2a;border-color:#444;color:#ddd}#leg{background:#1e1e1e;border-color:#333;color:#bbb}}";
 const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=document.getElementById('tip'),panel=document.getElementById('panel');" +
     "var PANELW=300,panelOpen=false;" +
     "var W,H;function resize(){var r=devicePixelRatio||1;W=innerWidth||c.clientWidth||800;H=(innerHeight-48)||c.clientHeight||600;c.width=W*r;c.height=H*r;ctx.setTransform(r,0,0,r,0,0);}addEventListener('resize',function(){resize();});resize();" +
@@ -62,7 +77,8 @@ const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=d
     "sim.forEach(function(n){n.x=W/2+(Math.random()-0.5)*240;n.y=H/2+(Math.random()-0.5)*240;});" +
     "var groups={},gi=0;function color(g){if(groups[g]==null)groups[g]=gi++;return 'hsl('+((groups[g]*67)%360)+',58%,55%)';}" +
     "var adj={};links.forEach(function(l){(adj[l.source]=adj[l.source]||[]).push(l.target);(adj[l.target]=adj[l.target]||[]).push(l.source);});" +
-    "var view={x:0,y:0,k:1},sel=null,hover=null,drag=null,pan=null,q='',autofit=true;" +
+    "var view={x:0,y:0,k:1},sel=null,hover=null,drag=null,pan=null,q='',autofit=true,mode='group';" +
+    "function instColor(i){return 'hsl('+Math.round((1-i)*120)+',65%,'+Math.round(46+i*8)+'%)';}" +
     "function radius(n){return 4+Math.sqrt(n.symbols||0)*1.7;}" +
     "function tick(){if(!sim.length)return;var k=0.0016;for(var i=0;i<sim.length;i++){var a=sim[i];a.vx+=(W/2-a.x)*k;a.vy+=(H/2-a.y)*k;for(var j=i+1;j<sim.length;j++){var b=sim[j];var dx=a.x-b.x,dy=a.y-b.y,d2=dx*dx+dy*dy;if(d2<100)d2=100;var d=Math.sqrt(d2),f=2200/d2,fx=f*dx/d,fy=f*dy/d;a.vx+=fx;a.vy+=fy;b.vx-=fx;b.vy-=fy;}}" +
     "links.forEach(function(l){var a=byId[l.source],b=byId[l.target];if(!a||!b)return;var dx=b.x-a.x,dy=b.y-a.y,d=Math.sqrt(dx*dx+dy*dy)+0.01,f=(d-90)*0.02,fx=f*dx/d,fy=f*dy/d;a.vx+=fx;a.vy+=fy;b.vx-=fx;b.vy-=fy;});" +
@@ -74,12 +90,12 @@ const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=d
     "function esc(t){return String(t).replace(/&/g,'&amp;').replace(/</g,'&lt;');}" +
     "function rowList(ids){if(!ids||!ids.length)return '<div class=\"sym\" style=\"color:#aaa\">none</div>';return ids.slice().sort().map(function(id){return '<div class=\"row\" data-id=\"'+esc(id)+'\">'+esc(id)+'</div>';}).join('');}" +
     "function showPanel(n){sel=n;panelOpen=true;var imp=out[n.id]||[],impBy=inn[n.id]||[];var syms=(n.syms||[]).map(function(s){var i=s.indexOf(' ');return '<div class=\"sym\"><span class=\"k\">'+esc(s.slice(0,i))+'</span> '+esc(s.slice(i+1))+'</div>';}).join('')||'<div class=\"sym\" style=\"color:#aaa\">none</div>';" +
-    "panel.innerHTML='<button id=\"close\">&times;</button>'+'<h2>'+esc(n.id.split('/').pop())+'</h2><div class=\"path\">'+esc(n.id)+'</div>'+'<div class=\"meta\">'+esc(n.lang)+' &middot; '+(n.symbols||0)+' symbols'+(deg[n.id]?'':' &middot; no in-scope deps')+'</div>'+'<h3>Imports ('+imp.length+')</h3>'+rowList(imp)+'<h3>Imported by ('+impBy.length+')</h3>'+rowList(impBy)+'<h3>Symbols</h3>'+syms;" +
+    "panel.innerHTML='<button id=\"close\">&times;</button>'+'<h2>'+esc(n.id.split('/').pop())+'</h2><div class=\"path\">'+esc(n.id)+'</div>'+'<div class=\"meta\">'+esc(n.lang)+' &middot; '+(n.symbols||0)+' symbols'+(deg[n.id]?' &middot; Ca '+(n.ca||0)+' &middot; Ce '+(n.ce||0)+' &middot; I '+(n.inst||0):' &middot; no in-scope deps')+'</div>'+'<h3>Imports ('+imp.length+')</h3>'+rowList(imp)+'<h3>Imported by ('+impBy.length+')</h3>'+rowList(impBy)+'<h3>Symbols</h3>'+syms;" +
     "panel.style.display='block';}" +
     "panel.addEventListener('click',function(e){if(e.target.id==='close'){panelOpen=false;sel=null;panel.style.display='none';autofit=true;return;}var id=e.target.getAttribute('data-id');if(id&&byId[id]){showPanel(byId[id]);center(byId[id]);}});" +
     "function draw(){ctx.clearRect(0,0,W,H);ctx.save();ctx.translate(view.x,view.y);ctx.scale(view.k,view.k);ctx.lineWidth=0.8;" +
     "links.forEach(function(l){var a=byId[l.source],b=byId[l.target];if(!a||!b)return;var on=sel&&(l.source===sel.id||l.target===sel.id);ctx.strokeStyle=on?'rgba(110,110,240,0.9)':'rgba(150,150,150,0.18)';ctx.beginPath();ctx.moveTo(a.x,a.y);ctx.lineTo(b.x,b.y);ctx.stroke();});" +
-    "function dot(n,orphan){var dim=(sel&&n!==sel&&(adj[sel.id]||[]).indexOf(n.id)<0)||(q&&n.id.toLowerCase().indexOf(q)<0);ctx.globalAlpha=dim?0.14:(orphan?0.55:1);ctx.beginPath();ctx.arc(n.x,n.y,orphan?3.2:radius(n),0,6.2832);ctx.fillStyle=color(n.group);ctx.fill();if(n===sel||n===hover){ctx.lineWidth=2;ctx.strokeStyle='#fff';ctx.stroke();ctx.lineWidth=0.8;}}" +
+    "function dot(n,orphan){var dim=(sel&&n!==sel&&(adj[sel.id]||[]).indexOf(n.id)<0)||(q&&n.id.toLowerCase().indexOf(q)<0);ctx.globalAlpha=dim?0.14:(orphan?0.55:1);ctx.beginPath();ctx.arc(n.x,n.y,orphan?3.2:radius(n),0,6.2832);ctx.fillStyle=mode==='inst'?(deg[n.id]?instColor(n.inst):'#999'):color(n.group);ctx.fill();if(n===sel||n===hover){ctx.lineWidth=2;ctx.strokeStyle='#fff';ctx.stroke();ctx.lineWidth=0.8;}}" +
     "orphans.forEach(function(n){dot(n,true);});sim.forEach(function(n){dot(n,false);});" +
     "ctx.globalAlpha=1;ctx.fillStyle=getComputedStyle(document.body).color;ctx.font='11px system-ui';sim.forEach(function(n){if(n===sel||n===hover||n.symbols>=14){ctx.fillText(n.id.split('/').pop(),n.x+radius(n)+3,n.y+3);}});ctx.restore();}" +
     "function loop(){var w=innerWidth,hh=innerHeight-48;if(w&&hh&&(w!==W||hh!==H))resize();tick();tick();layoutOrphans();if(autofit)fitView();draw();var bx=bb4(nodes);document.getElementById(\"dbg\").textContent=\"W=\"+W+\" H=\"+H+\" iw=\"+innerWidth+\"x\"+innerHeight+\" dpr=\"+(devicePixelRatio||1)+\" k=\"+view.k.toFixed(2)+\" vx=\"+Math.round(view.x)+\" vy=\"+Math.round(view.y)+\" fit=\"+autofit+\" sim=\"+sim.length+\" orph=\"+orphans.length+\" worldBox=\"+Math.round(bx[0])+\",\"+Math.round(bx[1])+\"..\"+Math.round(bx[2])+\",\"+Math.round(bx[3]);requestAnimationFrame(loop);}" +
@@ -87,10 +103,11 @@ const CLIENT = "var c=document.getElementById('cv'),ctx=c.getContext('2d'),tip=d
     "function pick(p){var all=sim.concat(orphans);for(var i=all.length-1;i>=0;i--){var n=all[i];var r=(deg[n.id]?radius(n):3.2)+5;if((p.x-n.x)*(p.x-n.x)+(p.y-n.y)*(p.y-n.y)<=r*r)return n;}return null;}" +
     "c.addEventListener('mousedown',function(e){autofit=false;var n=pick(world(e));if(n){drag=n;showPanel(n);}else{pan={x:e.clientX-view.x,y:e.clientY-view.y};}});" +
     "c.addEventListener('dblclick',function(){panelOpen=false;sel=null;panel.style.display='none';autofit=true;});" +
-    "addEventListener('mousemove',function(e){var p=world(e);if(drag){drag.x=p.x;drag.y=p.y;drag.vx=0;drag.vy=0;}else if(pan){view.x=e.clientX-pan.x;view.y=e.clientY-pan.y;}else{hover=pick(p);if(hover){tip.style.display='block';tip.style.left=(e.clientX+12)+'px';tip.style.top=(e.clientY+12)+'px';tip.textContent=hover.id+'  ·  '+(hover.symbols||0)+' symbols  ·  '+hover.lang;}else tip.style.display='none';}});" +
+    "addEventListener('mousemove',function(e){var p=world(e);if(drag){drag.x=p.x;drag.y=p.y;drag.vx=0;drag.vy=0;}else if(pan){view.x=e.clientX-pan.x;view.y=e.clientY-pan.y;}else{hover=pick(p);if(hover){tip.style.display='block';tip.style.left=(e.clientX+12)+'px';tip.style.top=(e.clientY+12)+'px';tip.textContent=hover.id+'  ·  '+(hover.symbols||0)+' symbols  ·  '+hover.lang+(deg[hover.id]?'  ·  Ca '+hover.ca+' Ce '+hover.ce+' I '+hover.inst:'');}else tip.style.display='none';}});" +
     "addEventListener('mouseup',function(){drag=null;pan=null;});" +
     "c.addEventListener('wheel',function(e){e.preventDefault();autofit=false;var s=e.deltaY<0?1.1:0.9;var mx=e.clientX,my=e.clientY-48;view.x=mx-(mx-view.x)*s;view.y=my-(my-view.y)*s;view.k*=s;},{passive:false});" +
     "document.getElementById('q').addEventListener('input',function(e){q=e.target.value.toLowerCase();});" +
+    "document.getElementById('mode').addEventListener('change',function(e){mode=e.target.value;document.getElementById('leg').style.display=mode==='inst'?'block':'none';});" +
     "addEventListener('keydown',function(e){if(e.key==='d'&&e.target.tagName!=='INPUT'){var x=document.getElementById('dbg');x.style.display=x.style.display==='none'?'block':'none';}});loop();";
 /** Build a self-contained, dependency-free HTML graph explorer. */
 export function buildExplorerHtml(graph, root) {
@@ -100,7 +117,7 @@ export function buildExplorerHtml(graph, root) {
     return ("<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">" +
         "<title>AST-MCP — " + title + " graph</title><style>" + STYLE + "</style></head><body>" +
         "<div id=\"bar\"><h1>AST-MCP graph</h1><span class=\"muted\">" + data.nodes.length + " files · " + data.links.length + " edges · drag / scroll / click</span>" +
-        "<input id=\"q\" placeholder=\"filter files…\" /></div>" +
-        "<canvas id=\"cv\"></canvas><div id=\"tip\"></div><div id=\"panel\"></div><div id=\"dbg\" style=\"position:fixed;left:8px;bottom:8px;font:11px monospace;color:#e07;z-index:6;pointer-events:none;white-space:pre;display:none\"></div>" +
+        "<input id=\"q\" placeholder=\"filter files…\" /><select id=\"mode\"><option value=\"group\">color: folder</option><option value=\"inst\">color: coupling</option></select></div>" +
+        "<canvas id=\"cv\"></canvas><div id=\"tip\"></div><div id=\"panel\"></div><div id=\"leg\"><b>Instability I = Ce/(Ca+Ce)</b><div class=\"bar\"></div><div style=\"display:flex;justify-content:space-between\"><span>0 = stable</span><span>1 = volatile</span></div></div><div id=\"dbg\" style=\"position:fixed;left:8px;bottom:8px;font:11px monospace;color:#e07;z-index:6;pointer-events:none;white-space:pre;display:none\"></div>" +
         "<script>var DATA=" + dataJson + ";</script><script>" + CLIENT + "</script></body></html>");
 }

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.26.0",
   "description": "MCP server that maps source files into a normalized code skeleton (JSON + HTML) using tree-sitter.",
   "type": "module",
   "main": "dist/index.js",