@maxgfr/codeindex 2.8.0 → 2.9.0

package/README.md

@@ -59,9 +59,9 @@ import { scanRepo, ENGINE_VERSION } from "@maxgfr/codeindex";
 const scan = scanRepo("/path/to/repo");
 ```
 
-The CLI ships in the same package (`npm i -g @maxgfr/codeindex`, see below).
-Skills should still prefer vendoring: it keeps their own bundle single-file and
-pinned to an exact commit without an npm dependency.
+The CLI ships in the same package — see **Use as a CLI** below for the global
+install command. Skills should still prefer vendoring: it keeps their own
+bundle single-file and pinned to an exact commit without an npm dependency.
 
 ## Use as a CLI
 
@@ -75,6 +75,20 @@ codeindex callers --repo .                    # per-symbol caller index
 codeindex grep    'pattern' --repo .
 ```
 
+## Search
+
+`codeindex search "<query>" --repo .` ranks files with keyless BM25 over symbol
+names, path segments, markdown headings and summaries. A query term that
+matches nothing in the corpus (zero document frequency) gets a deterministic
+**trigram fuzzy fallback** — typo tolerance without embeddings: the term is
+compared to the corpus vocabulary by character-trigram Dice similarity
+(threshold 0.6, top-3 candidates, contribution scaled by the Dice score so a
+near-miss always ranks below an exact hit). Terms that already match anything
+are never touched, so an existing query stays byte-identical. Enabled by
+default; disable with `--no-fuzzy` (CLI) or `fuzzy: false` (library/MCP
+`SearchOptions.fuzzy`); results carry an additive `fuzzyTerms` field when the
+fallback contributed.
+
 ## Use as an MCP server
 
 `codeindex mcp` (or `node scripts/cli.mjs mcp`) serves the engine over stdio —
@@ -99,6 +113,19 @@ into their own CLIs); `cli.mjs` is the thin standalone CLI/MCP wrapper.
 `buildGraph`/`buildIndexArtifacts` accept `meta: { version, schemaVersion }` so
 a consumer can stamp its own identity into artifacts it persists.
 
+## Benchmarks
+
+Measured against 01x-in/codeindex, universal-ctags and scip-typescript with a
+reproducible harness (`scripts/bench/`); full methodology, fairness notes and
+all scenarios in [BENCHMARKS.md](./BENCHMARKS.md).
+
+| Metric | codeindex | Context |
+| --- | --- | --- |
+| `socialgouv/code-du-travail-numerique` — cold index | 1,746 ms | vs ctags 371 ms, 01x init 13,409 ms |
+| `socialgouv/code-du-travail-numerique` — warm rerun | 339 ms | |
+| `vercel/next.js` — cold index | 9,398 ms | vs ctags 3,431 ms |
+| `socialgouv/code-du-travail-numerique` — token ratio (measured) | 32.9× | structured index vs raw grep, single-symbol lookup |
+
 ## Development
 
 ```sh

package/docs/MIGRATION.md

@@ -55,6 +55,15 @@ does; nobody else should).
 `meta: { version, schemaVersion }` so a consumer stamps its own identity into
 artifacts it persists (ultraindex does this to keep its graph.json lineage).
 
+## v2.9.0 — `search` trigram fuzzy fallback
+
+New, purely additive: `SearchOptions.fuzzy?: boolean` (default `true`) and
+`SearchResult.fuzzyTerms?: string[]` (present only when the fallback
+contributed). A query term is only ever expanded when it has zero document
+frequency in the corpus, so any query where every term already matched keeps
+producing byte-identical output — **no re-pin required**, no action needed
+from existing consumers. Pass `fuzzy: false` (or CLI `--no-fuzzy`) to opt out.
+
 ## Per-skill mapping (what to replace with what)
 
 | Skill | Replace | With (engine export) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Self-contained, deterministic repo-indexing engine: walk + language detection + symbol/import extraction (tree-sitter AST with regex fallback) + import resolution + typed cross-file link-graph + analytics. Ships as a single zero-dependency engine.mjs that consumer tools vendor.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/engine.d.mts

@@ -1,4 +1,4 @@
-declare const ENGINE_VERSION = "2.8.0";
+declare const ENGINE_VERSION = "2.9.0";
 declare const SCHEMA_VERSION = 4;
 declare const EXTRACTOR_VERSION = 6;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
@@ -417,6 +417,7 @@ declare function renderGraphJson(graph: Graph): string;
 
 interface RenderScipOptions {
     projectRoot?: string;
+    toolVersion?: string;
 }
 declare function renderScip(scan: RepoScan, opts?: RenderScipOptions): Uint8Array;
 
@@ -486,12 +487,14 @@ declare function grepRepo(root: string, pattern: string, opts?: GrepOptions): Se
 
 interface SearchOptions {
     limit?: number;
+    fuzzy?: boolean;
 }
 interface SearchResult {
     file: string;
     score: number;
     matchedTerms: string[];
     topSymbols: string[];
+    fuzzyTerms?: string[];
 }
 declare function subtokens(raw: string): string[];
 declare function searchIndex(scan: RepoScan, query: string, opts?: SearchOptions): SearchResult[];

package/scripts/engine.mjs

@@ -14,7 +14,7 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.8.0";
+    ENGINE_VERSION = "2.9.0";
     SCHEMA_VERSION = 4;
     EXTRACTOR_VERSION = 6;
   }
@@ -9210,6 +9210,27 @@ function buildDocs(scan2) {
   }
   return docs;
 }
+function charTrigrams(term) {
+  const padded = `^^${term}$$`;
+  const grams = /* @__PURE__ */ new Set();
+  for (let i2 = 0; i2 + 3 <= padded.length; i2++) grams.add(padded.slice(i2, i2 + 3));
+  return grams;
+}
+function diceCoefficient(a, b) {
+  if (!a.size || !b.size) return 0;
+  let inter = 0;
+  for (const g of a) if (b.has(g)) inter++;
+  return 2 * inter / (a.size + b.size);
+}
+function buildTrigramIndex(docs) {
+  const index = /* @__PURE__ */ new Map();
+  for (const d of docs) {
+    for (const term of d.tf.keys()) {
+      if (!index.has(term)) index.set(term, charTrigrams(term));
+    }
+  }
+  return index;
+}
 function searchIndex(scan2, query, opts = {}) {
   const terms = [];
   const seen = /* @__PURE__ */ new Set();
@@ -9233,35 +9254,81 @@ function searchIndex(scan2, query, opts = {}) {
     for (const d of docs) if (d.tf.has(t)) count++;
     df.set(t, count);
   }
+  const fuzzyEnabled = opts.fuzzy ?? true;
+  const fuzzyCandidates = /* @__PURE__ */ new Map();
+  if (fuzzyEnabled) {
+    const unmatched = terms.filter((t) => df.get(t) === 0);
+    if (unmatched.length) {
+      const trigramIndex = buildTrigramIndex(docs);
+      for (const t of unmatched) {
+        const grams = charTrigrams(t);
+        const candidates = [];
+        for (const [vocabTerm, vocabGrams] of trigramIndex) {
+          const dice = diceCoefficient(grams, vocabGrams);
+          if (dice >= FUZZY_DICE_THRESHOLD) candidates.push({ term: vocabTerm, dice });
+        }
+        candidates.sort((a, b) => b.dice - a.dice || byStr(a.term, b.term));
+        fuzzyCandidates.set(t, candidates.slice(0, FUZZY_CAP));
+      }
+    }
+  }
+  const vocabDf = /* @__PURE__ */ new Map();
+  const dfOfVocabTerm = (term) => {
+    const known = df.get(term) ?? vocabDf.get(term);
+    if (known !== void 0) return known;
+    let count = 0;
+    for (const d of docs) if (d.tf.has(term)) count++;
+    vocabDf.set(term, count);
+    return count;
+  };
   const results = [];
   for (const d of docs) {
     let score = 0;
     const matched = [];
+    const symbolTerms = /* @__PURE__ */ new Set();
+    const fuzzyHit = /* @__PURE__ */ new Set();
     for (const t of terms) {
       const tf = d.tf.get(t);
-      if (!tf) continue;
-      matched.push(t);
-      const idf = Math.log(1 + (n - df.get(t) + 0.5) / (df.get(t) + 0.5));
-      score += idf * (tf * (K1 + 1)) / (tf + K1 * (1 - B + B * d.len / avgLen));
+      if (tf) {
+        matched.push(t);
+        symbolTerms.add(t);
+        const idf = Math.log(1 + (n - df.get(t) + 0.5) / (df.get(t) + 0.5));
+        score += idf * (tf * (K1 + 1)) / (tf + K1 * (1 - B + B * d.len / avgLen));
+        continue;
+      }
+      const candidates = fuzzyCandidates.get(t);
+      if (!candidates) continue;
+      for (const cand of candidates) {
+        const ctf = d.tf.get(cand.term);
+        if (!ctf) continue;
+        const cdf = dfOfVocabTerm(cand.term);
+        const idf = Math.log(1 + (n - cdf + 0.5) / (cdf + 0.5));
+        const contribution = idf * (ctf * (K1 + 1)) / (ctf + K1 * (1 - B + B * d.len / avgLen));
+        score += contribution * cand.dice;
+        symbolTerms.add(cand.term);
+        fuzzyHit.add(t);
+      }
     }
-    if (!matched.length) continue;
+    if (!matched.length && !fuzzyHit.size) continue;
     const scored = d.symbols.map((name2) => {
       const toks = new Set(subtokens(name2));
       let hits = 0;
-      for (const t of matched) if (toks.has(t)) hits++;
+      for (const t of symbolTerms) if (toks.has(t)) hits++;
       return { name: name2, hits };
     }).filter((s) => s.hits > 0).sort((a, b) => b.hits - a.hits || byStr(a.name, b.name));
-    results.push({
+    const result = {
       file: d.file,
       score: Number(score.toFixed(4)),
       matchedTerms: matched.sort(byStr),
       topSymbols: scored.slice(0, TOP_SYMBOLS).map((s) => s.name)
-    });
+    };
+    if (fuzzyHit.size) result.fuzzyTerms = [...fuzzyHit].sort(byStr);
+    results.push(result);
   }
   results.sort((a, b) => b.score - a.score || byStr(a.file, b.file));
   return results.slice(0, opts.limit ?? DEFAULT_LIMIT);
 }
-var K1, B, DEFAULT_LIMIT, TOP_SYMBOLS;
+var K1, B, DEFAULT_LIMIT, TOP_SYMBOLS, FUZZY_DICE_THRESHOLD, FUZZY_CAP;
 var init_bm25 = __esm({
   "src/bm25.ts"() {
     "use strict";
@@ -9271,6 +9338,8 @@ var init_bm25 = __esm({
     B = 0.75;
     DEFAULT_LIMIT = 20;
     TOP_SYMBOLS = 5;
+    FUZZY_DICE_THRESHOLD = 0.6;
+    FUZZY_CAP = 3;
   }
 });
 
@@ -9803,7 +9872,8 @@ function callTool(name2, args2) {
     const query = str(args2.query);
     if (!query) throw new Error("`query` is required");
     const results = searchIndex(scanRepo(repo, scanOpts), query, {
-      limit: typeof args2.limit === "number" ? args2.limit : void 0
+      limit: typeof args2.limit === "number" ? args2.limit : void 0,
+      fuzzy: typeof args2.fuzzy === "boolean" ? args2.fuzzy : void 0
     });
     return JSON.stringify(results, null, 2);
   }
@@ -10105,14 +10175,18 @@ var init_mcp = __esm({
       },
       {
         name: "search",
-        description: 'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings \u2014 deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols.',
+        description: 'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings \u2014 deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`.',
         inputSchema: {
           type: "object",
           properties: {
             ...repoProp,
             ...scopeProps,
             query: { type: "string", description: "Natural-language or identifier query" },
-            limit: { type: "number", description: "Max results (default 20)" }
+            limit: { type: "number", description: "Max results (default 20)" },
+            fuzzy: {
+              type: "boolean",
+              description: "Trigram fuzzy fallback for query terms with zero document frequency (default true)"
+            }
           },
           required: ["repo", "query"]
         }
@@ -10434,6 +10508,7 @@ function findWord(line, name2) {
 }
 function renderScip(scan2, opts = {}) {
   const projectRoot = opts.projectRoot ?? "file://" + scan2.root.replace(/\\/g, "/");
+  const toolVersion = opts.toolVersion ?? ENGINE_VERSION;
   const docs = scan2.files.filter((f) => f.kind === "code" && f.symbols.length > 0);
   const docDefs = /* @__PURE__ */ new Map();
   const defByName = /* @__PURE__ */ new Map();
@@ -10514,7 +10589,7 @@ function renderScip(scan2, opts = {}) {
   }
   const toolInfo = [];
   pushString(toolInfo, F_TOOL_NAME, "codeindex");
-  pushString(toolInfo, F_TOOL_VERSION, ENGINE_VERSION);
+  pushString(toolInfo, F_TOOL_VERSION, toolVersion);
   const metadata2 = [];
   pushLenDelim(metadata2, F_META_TOOL_INFO, toolInfo);
   pushString(metadata2, F_META_PROJECT_ROOT, projectRoot);
@@ -10605,12 +10680,14 @@ Flags:
   --no-ast            Skip tree-sitter grammars even when present (regex tier)
   --config <file>     Rules config for \`rules\` (JSON: [{name, from, to, \u2026}])
   --limit <n>         Max results for \`search\` (default 20)
+  --no-fuzzy          \`search\`: disable trigram fuzzy fallback for query terms
+                      with zero document frequency (default: enabled)
   --recall            \`callers\`: recall-oriented binding (issue #7) \u2014 relaxes
                       the JS/TS import gate to unique repo-wide names and labels
                       each site corroborated|unique-name
 `;
 function parseFlags(args2) {
-  const flags2 = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false };
+  const flags2 = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false, fuzzy: true };
   for (let i2 = 0; i2 < args2.length; i2++) {
     const a = args2[i2];
     const next = () => {
@@ -10642,6 +10719,7 @@ function parseFlags(args2) {
     else if (a === "--since") flags2.since = next();
     else if (a === "--config") flags2.config = resolve(next());
     else if (a === "--limit") flags2.limit = num();
+    else if (a === "--no-fuzzy") flags2.fuzzy = false;
     else if (a === "--recall") flags2.recall = true;
     else if (!a.startsWith("--") && flags2.positional === void 0) flags2.positional = a;
     else throw new Error(`unknown flag: ${a}`);
@@ -10744,7 +10822,7 @@ async function runCli(argv) {
   } else if (cmd === "search") {
     if (!flags2.positional) throw new Error('search needs a query: cli.mjs search "<query>" --repo <dir>');
     const scan2 = scanRepo(flags2.repo, scanOptions(flags2));
-    const results = searchIndex(scan2, flags2.positional, { limit: flags2.limit });
+    const results = searchIndex(scan2, flags2.positional, { limit: flags2.limit, fuzzy: flags2.fuzzy });
     emit(JSON.stringify(results, null, 2) + "\n", flags2.out);
   } else if (cmd === "rules") {
     if (!flags2.config) throw new Error("rules needs --config <codeindex.rules.json>");

package/src/bm25.ts

@@ -8,6 +8,14 @@
 // the query reuses util keywords, so query and haystack always tokenize alike.
 // Deterministic: files are scored in scan order (sorted by rel), scores are
 // fixed to 4 decimal places, and ties break by path.
+//
+// Trigram fuzzy fallback (v2.9.0): a query term that matches NOTHING in the
+// corpus (document frequency == 0 — checked STRICTLY, so any term that
+// already matches anywhere is never touched) is expanded against the corpus
+// vocabulary via character-trigram Dice similarity (threshold 0.6, top-3
+// candidates, deterministic tie-break). This keeps every currently-matching
+// query byte-identical: the expansion only ever engages on terms that would
+// otherwise contribute nothing.
 import type { RepoScan } from "./scan.js";
 import { foldText, keywords } from "./util.js";
 import { byStr } from "./sort.js";
@@ -16,10 +24,17 @@ const K1 = 1.2;
 const B = 0.75;
 const DEFAULT_LIMIT = 20;
 const TOP_SYMBOLS = 5;
+const FUZZY_DICE_THRESHOLD = 0.6;
+const FUZZY_CAP = 3;
 
 export interface SearchOptions {
   // Maximum results returned (default 20).
   limit?: number;
+  // Trigram fuzzy fallback for query terms with zero document frequency
+  // (default true). Safe as an always-on default: the df==0 gate means it
+  // only ever engages on terms that would otherwise match nothing, so a
+  // query where every term already hits is completely unaffected.
+  fuzzy?: boolean;
 }
 
 export interface SearchResult {
@@ -27,6 +42,10 @@ export interface SearchResult {
   score: number; // BM25 score, fixed to 4 decimal places
   matchedTerms: string[]; // query tokens present in this file's document, sorted
   topSymbols: string[]; // symbols whose name matches the most query tokens (cap 5)
+  // Query terms (df==0) resolved via trigram fuzzy fallback that contributed
+  // to this result, sorted. Present only when >=1 term used the fallback —
+  // purely additive, never present for an all-exact-match result.
+  fuzzyTerms?: string[];
 }
 
 // Split an identifier/phrase into lowercase, diacritic-folded subtokens:
@@ -87,6 +106,39 @@ function buildDocs(scan: RepoScan): Doc[] {
   return docs;
 }
 
+// Character trigrams of a token, padded with two boundary sentinels on each
+// side (pg_trgm-style: "^^t…m$$") so short prefix/suffix runs still produce
+// shared grams. Deduplicated into a Set — a repeated gram doesn't inflate
+// Dice similarity.
+export function charTrigrams(term: string): Set<string> {
+  const padded = `^^${term}$$`;
+  const grams = new Set<string>();
+  for (let i = 0; i + 3 <= padded.length; i++) grams.add(padded.slice(i, i + 3));
+  return grams;
+}
+
+// Dice coefficient between two trigram sets: 2|A∩B| / (|A|+|B|). 0 when
+// either side is empty (no divide-by-zero).
+export function diceCoefficient(a: ReadonlySet<string>, b: ReadonlySet<string>): number {
+  if (!a.size || !b.size) return 0;
+  let inter = 0;
+  for (const g of a) if (b.has(g)) inter++;
+  return (2 * inter) / (a.size + b.size);
+}
+
+// Trigram index of the corpus vocabulary: every distinct doc token mapped to
+// its trigram set. Built LAZILY by searchIndex — only when >=1 query term has
+// df==0 — so a fully-matched query never pays this cost.
+function buildTrigramIndex(docs: Doc[]): Map<string, Set<string>> {
+  const index = new Map<string, Set<string>>();
+  for (const d of docs) {
+    for (const term of d.tf.keys()) {
+      if (!index.has(term)) index.set(term, charTrigrams(term));
+    }
+  }
+  return index;
+}
+
 // Rank the scanned files against a natural-language (or identifier) query.
 // Pure and deterministic: same scan + query → the same results, byte-for-byte.
 export function searchIndex(scan: RepoScan, query: string, opts: SearchOptions = {}): SearchResult[] {
@@ -118,36 +170,93 @@ export function searchIndex(scan: RepoScan, query: string, opts: SearchOptions =
     df.set(t, count);
   }
 
+  // Fuzzy fallback: STRICT df==0 gate — a term that matches anywhere, even
+  // once, is never expanded. The trigram index of the corpus vocabulary is
+  // built lazily, only when at least one term needs it, so a fully-matched
+  // query (the common case) pays zero extra cost and stays byte-identical.
+  const fuzzyEnabled = opts.fuzzy ?? true;
+  const fuzzyCandidates = new Map<string, { term: string; dice: number }[]>();
+  if (fuzzyEnabled) {
+    const unmatched = terms.filter((t) => df.get(t) === 0);
+    if (unmatched.length) {
+      const trigramIndex = buildTrigramIndex(docs);
+      for (const t of unmatched) {
+        const grams = charTrigrams(t);
+        const candidates: { term: string; dice: number }[] = [];
+        for (const [vocabTerm, vocabGrams] of trigramIndex) {
+          const dice = diceCoefficient(grams, vocabGrams);
+          if (dice >= FUZZY_DICE_THRESHOLD) candidates.push({ term: vocabTerm, dice });
+        }
+        // Deterministic: similarity desc, then vocab term asc.
+        candidates.sort((a, b) => b.dice - a.dice || byStr(a.term, b.term));
+        fuzzyCandidates.set(t, candidates.slice(0, FUZZY_CAP));
+      }
+    }
+  }
+  // df cache for expanded vocab terms (distinct from query-term df above).
+  const vocabDf = new Map<string, number>();
+  const dfOfVocabTerm = (term: string): number => {
+    const known = df.get(term) ?? vocabDf.get(term);
+    if (known !== undefined) return known;
+    let count = 0;
+    for (const d of docs) if (d.tf.has(term)) count++;
+    vocabDf.set(term, count);
+    return count;
+  };
+
   const results: SearchResult[] = [];
   for (const d of docs) {
     let score = 0;
     const matched: string[] = [];
+    const symbolTerms = new Set<string>(); // matched ∪ fuzzy-expanded vocab terms, for topSymbols ranking
+    const fuzzyHit = new Set<string>(); // original query terms resolved via fuzzy fallback, for this doc
     for (const t of terms) {
       const tf = d.tf.get(t);
-      if (!tf) continue;
-      matched.push(t);
-      const idf = Math.log(1 + (n - df.get(t)! + 0.5) / (df.get(t)! + 0.5));
-      score += (idf * (tf * (K1 + 1))) / (tf + K1 * (1 - B + (B * d.len) / avgLen));
+      if (tf) {
+        matched.push(t);
+        symbolTerms.add(t);
+        const idf = Math.log(1 + (n - df.get(t)! + 0.5) / (df.get(t)! + 0.5));
+        score += (idf * (tf * (K1 + 1))) / (tf + K1 * (1 - B + (B * d.len) / avgLen));
+        continue;
+      }
+      // Only ever reached for a term with df==0 (or absent from THIS doc but
+      // matched elsewhere — fuzzyCandidates has no entry for those, so the
+      // lookup below is a no-op and behavior is identical to before v2.9.0).
+      const candidates = fuzzyCandidates.get(t);
+      if (!candidates) continue;
+      for (const cand of candidates) {
+        const ctf = d.tf.get(cand.term);
+        if (!ctf) continue;
+        const cdf = dfOfVocabTerm(cand.term);
+        const idf = Math.log(1 + (n - cdf + 0.5) / (cdf + 0.5));
+        const contribution = (idf * (ctf * (K1 + 1))) / (ctf + K1 * (1 - B + (B * d.len) / avgLen));
+        score += contribution * cand.dice; // near-miss always scores below an exact hit (dice < 1)
+        symbolTerms.add(cand.term);
+        fuzzyHit.add(t);
+      }
     }
-    if (!matched.length) continue;
+    if (!matched.length && !fuzzyHit.size) continue;
 
-    // Symbols ranked by how many query tokens their name carries, then by name.
+    // Symbols ranked by how many query tokens (exact or fuzzy-expanded) their
+    // name carries, then by name.
     const scored = d.symbols
       .map((name) => {
         const toks = new Set(subtokens(name));
         let hits = 0;
-        for (const t of matched) if (toks.has(t)) hits++;
+        for (const t of symbolTerms) if (toks.has(t)) hits++;
         return { name, hits };
       })
       .filter((s) => s.hits > 0)
       .sort((a, b) => b.hits - a.hits || byStr(a.name, b.name));
 
-    results.push({
+    const result: SearchResult = {
       file: d.file,
       score: Number(score.toFixed(4)),
       matchedTerms: matched.sort(byStr),
       topSymbols: scored.slice(0, TOP_SYMBOLS).map((s) => s.name),
-    });
+    };
+    if (fuzzyHit.size) result.fuzzyTerms = [...fuzzyHit].sort(byStr);
+    results.push(result);
   }
 
   // Rounded score first (so 4-dp ties resolve stably), then path.

package/src/engine-cli.ts

@@ -63,6 +63,8 @@ Flags:
   --no-ast            Skip tree-sitter grammars even when present (regex tier)
   --config <file>     Rules config for \`rules\` (JSON: [{name, from, to, …}])
   --limit <n>         Max results for \`search\` (default 20)
+  --no-fuzzy          \`search\`: disable trigram fuzzy fallback for query terms
+                      with zero document frequency (default: enabled)
   --recall            \`callers\`: recall-oriented binding (issue #7) — relaxes
                       the JS/TS import gate to unique repo-wide names and labels
                       each site corroborated|unique-name
@@ -84,13 +86,14 @@ interface CliFlags {
   budgetTokens?: number;
   config?: string; // rules config path
   limit?: number; // search result cap
+  fuzzy: boolean; // search: trigram fuzzy fallback for df==0 terms (default true)
   recall?: boolean; // callers: recall-oriented binding
   projectRoot?: string; // scip: override Metadata.project_root
   positional?: string; // e.g. the grep pattern or search query
 }
 
 function parseFlags(args: string[]): CliFlags {
-  const flags: CliFlags = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false };
+  const flags: CliFlags = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false, fuzzy: true };
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     const next = (): string => {
@@ -122,6 +125,7 @@ function parseFlags(args: string[]): CliFlags {
     else if (a === "--since") flags.since = next();
     else if (a === "--config") flags.config = resolve(next());
     else if (a === "--limit") flags.limit = num();
+    else if (a === "--no-fuzzy") flags.fuzzy = false;
     else if (a === "--recall") flags.recall = true;
     else if (!a.startsWith("--") && flags.positional === undefined) flags.positional = a;
     else throw new Error(`unknown flag: ${a}`);
@@ -234,7 +238,7 @@ export async function runCli(argv: string[]): Promise<void> {
   } else if (cmd === "search") {
     if (!flags.positional) throw new Error('search needs a query: cli.mjs search "<query>" --repo <dir>');
     const scan = scanRepo(flags.repo, scanOptions(flags));
-    const results = searchIndex(scan, flags.positional, { limit: flags.limit });
+    const results = searchIndex(scan, flags.positional, { limit: flags.limit, fuzzy: flags.fuzzy });
     emit(JSON.stringify(results, null, 2) + "\n", flags.out);
   } else if (cmd === "rules") {
     if (!flags.config) throw new Error("rules needs --config <codeindex.rules.json>");

package/src/mcp.ts

@@ -266,7 +266,7 @@ const TOOLS = [
   {
     name: "search",
     description:
-      'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings — deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols.',
+      'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings — deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`.',
     inputSchema: {
       type: "object",
       properties: {
@@ -274,6 +274,11 @@ const TOOLS = [
         ...scopeProps,
         query: { type: "string", description: "Natural-language or identifier query" },
         limit: { type: "number", description: "Max results (default 20)" },
+        fuzzy: {
+          type: "boolean",
+          description:
+            "Trigram fuzzy fallback for query terms with zero document frequency (default true)",
+        },
       },
       required: ["repo", "query"],
     },
@@ -437,6 +442,7 @@ function callTool(name: string, args: Record<string, unknown>): string {
     if (!query) throw new Error("`query` is required");
     const results = searchIndex(scanRepo(repo, scanOpts), query, {
       limit: typeof args.limit === "number" ? args.limit : undefined,
+      fuzzy: typeof args.fuzzy === "boolean" ? args.fuzzy : undefined,
     });
     return JSON.stringify(results, null, 2);
   }

package/src/render/scip.ts

@@ -24,6 +24,10 @@ export interface RenderScipOptions {
   // Overridable so a build is byte-reproducible regardless of the machine's
   // checkout path; defaults to `file://` + the posix repo root.
   projectRoot?: string;
+  // Metadata.tool_info.version. Overridable so a byte-golden fixture can pin a
+  // fixed string and stay stable across ENGINE_VERSION release bumps; defaults
+  // to the live ENGINE_VERSION (the CLI never overrides this — no flag for it).
+  toolVersion?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -246,6 +250,7 @@ interface DefEntry {
 // ---------------------------------------------------------------------------
 export function renderScip(scan: RepoScan, opts: RenderScipOptions = {}): Uint8Array {
   const projectRoot = opts.projectRoot ?? "file://" + scan.root.replace(/\\/g, "/");
+  const toolVersion = opts.toolVersion ?? ENGINE_VERSION;
 
   // One Document per `code` file that declares ≥1 symbol, in scan order (already
   // sorted by rel).
@@ -353,7 +358,7 @@ export function renderScip(scan: RepoScan, opts: RenderScipOptions = {}): Uint8A
   // Metadata { tool_info, project_root, text_document_encoding }.
   const toolInfo: Bytes = [];
   pushString(toolInfo, F_TOOL_NAME, "codeindex");
-  pushString(toolInfo, F_TOOL_VERSION, ENGINE_VERSION);
+  pushString(toolInfo, F_TOOL_VERSION, toolVersion);
 
   const metadata: Bytes = [];
   pushLenDelim(metadata, F_META_TOOL_INFO, toolInfo);

package/src/types.ts

@@ -1,7 +1,7 @@
 // Single source of truth for the engine version the bundle reports. Kept in
 // lockstep with package.json by the release pipeline. Do not edit by hand
 // outside a release.
-export const ENGINE_VERSION = "2.8.0";
+export const ENGINE_VERSION = "2.9.0";
 
 // Bumped whenever the on-disk artifact shape changes, so a consumer can reject
 // an index written by an incompatible engine instead of misreading it. The