@maxgfr/codeindex 2.12.0 → 2.13.0

package/README.md

@@ -129,9 +129,13 @@ and the `embeddings.bin` artifact are byte-identical across builds and platforms
 It is **opt-in by asset**: with no model on disk the engine silently stays
 lexical, and `--semantic` without a model returns lexical results on **exit 0**
 (a stderr note only). Models are **never** shipped in the package; a model is
-resolved from `CODEINDEX_EMBED_DIR` or `<repo>/.codeindex/models/`.
+resolved from `CODEINDEX_EMBED_DIR` or `<repo>/.codeindex/models/`. Getting one
+is zero-config: `codeindex embed pull` fetches the official `embed-model-v1`
+release asset, sha256-verified before anything is written.
 
 ```sh
+codeindex embed pull   --repo .              # fetch the official model asset into
+                                             # CODEINDEX_EMBED_DIR (or <repo>/.codeindex/models/); sha256-verified
 codeindex embed status --repo .              # effective mode + reachability (JSON)
 codeindex embed build  --repo . --out .codeindex   # write embeddings.bin
 codeindex search "http client retry" --repo . --semantic

package/docs/MIGRATION.md

@@ -93,6 +93,43 @@ embeddings live in a separate `embeddings.bin` sidecar keyed by a dedicated
 `--semantic` without a model degrades to lexical results on **exit 0** (a stderr
 note only) — so wiring it on is safe before an asset exists.
 
+## v2.12.0 — two return-shape changes (check your call sites)
+
+Not additive: two public return shapes changed in this release without a
+compat flag, so a consumer re-pinning across v2.12.0 must check both call
+sites. Artifact schemas are untouched (`SCHEMA_VERSION` / `EMBED_VERSION`
+unchanged) — this is API shape only.
+
+- `resolveEmbedPullUrl()` now returns an `EmbedPullTarget`
+  (`{ url: string; sha256?: string }`) — it previously returned
+  `string | undefined`. It always resolves: `CODEINDEX_EMBED_URL` wins
+  outright and carries **no** `sha256` (a custom mirror keeps the
+  un-verified behavior); with no env it falls back to the built-in official
+  asset **with** its pinned `sha256` so `embed pull` verifies the default
+  download. Replace `const url = resolveEmbedPullUrl()` with
+  `const { url, sha256 } = resolveEmbedPullUrl()`. The `EmbedPullTarget`
+  type is exported from the barrel.
+- MCP `search` with `semantic: true` now returns
+  `{ results, tier, degradedReason? }` — it previously returned the bare
+  ranked array. `tier` is `"endpoint" | "static" | "lexical"` and
+  `degradedReason` is present only when the semantic tier degraded to
+  lexical, so a caller can tell "fusion happened" apart from "degraded".
+  Plain lexical `search` (no `semantic: true`) still returns the bare
+  array, byte-compatible with existing consumers.
+
+## v2.13.0 — `.codeindex` excluded from the walk
+
+`.codeindex/` — the engine's own output directory (index artifacts, pulled
+models, MCP memories) — joined `IGNORE_DIRS`, so `walk`/`scanRepo` no longer
+descend into it and memories stop entering BM25/embedding results (previously
+every `write_memory` also churned the scan fingerprint, busting the MCP
+server's memoized embedding index). Access memories through the MCP memory
+tools (`read_memory` / `list_memories` / `delete_memory`), never `search`.
+This is a file-set change only — extraction shape and `SCHEMA_VERSION` are
+untouched, so **no re-pin is required**; a consumer that deliberately wants
+`.codeindex` walked can pass `ignoreDirs` (replace semantics, also new in
+this release) with its own set.
+
 ## Per-skill mapping (what to replace with what)
 
 | Skill | Replace | With (engine export) |

package/docs/SEMANTIC.md

@@ -78,7 +78,7 @@ rows at one global scale. The download is **sha256-verified** against
 `EMBED_ASSET_SHA256` (`src/embed/model.ts`) before it is written; a mismatch
 fails the pull and writes nothing. The asset is **never** committed to git or
 shipped in the npm tarball — it lives only in the release. Reproduce it
-byte-for-byte with the pinned toolchain in [`scripts/embed-asset/`](../scripts/embed-asset/).
+byte-for-byte with the pinned toolchain in [`scripts/embed-asset/`](https://github.com/maxgfr/codeindex/tree/main/scripts/embed-asset).
 
 ## CLI
 
@@ -110,13 +110,20 @@ codeindex search "http client retry" --repo <dir> --semantic
 
 ## Artifact: `embeddings.bin`
 
+### Layout (the `deserializeEmbeddings` contract)
+
 ```
-"CIE1"                     4-byte ASCII magic
-uint32 LE header length
-UTF-8 JSON header          { embedVersion, modelId, dim, count, records:[{file,symbol,line}] }
-int8 body                  count × dim signed bytes (row-major)
+offset 0            "CIE1"            4-byte ASCII magic
+offset 4            uint32 LE         header length (headerLen)
+offset 8            UTF-8 JSON header { embedVersion, modelId, dim, count, records:[{file,symbol,line}] }
+offset 8+headerLen  int8 body         count × dim signed bytes (row-major)
 ```
 
+This is exactly what `deserializeEmbeddings` (`src/embed/index.ts`) reads back:
+it throws on a bad magic (a corrupt or foreign file fails loudly instead of
+being misread), parses the JSON header, and slices the packed body at
+`8 + headerLen`.
+
 The header carries **no absolute path and no timestamp**; records follow scan
 order (files sorted by `rel`, symbols in declaration order). Two builds of an
 unchanged repo produce byte-identical `embeddings.bin`. A dedicated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.12.0",
+  "version": "2.13.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,6 +1,6 @@
-declare const ENGINE_VERSION = "2.12.0";
+declare const ENGINE_VERSION = "2.13.0";
 declare const SCHEMA_VERSION = 4;
-declare const EXTRACTOR_VERSION = 9;
+declare const EXTRACTOR_VERSION = 10;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
 type EdgeKind = "contains" | "doc-link" | "import" | "call" | "use" | "mention";
 type Tier = 0 | 1 | 2;
@@ -121,6 +121,7 @@ interface WalkOptions {
     maxFileBytes?: number;
     maxFiles?: number;
     gitignore?: boolean;
+    ignoreDirs?: string[];
 }
 interface WalkedFile {
     rel: string;
@@ -153,8 +154,10 @@ interface ScanOptions {
     exclude?: string[];
     scope?: string;
     gitignore?: boolean;
+    ignoreDirs?: string[];
     maxBytes?: number;
     maxFiles?: number;
+    maxCallsPerFile?: number;
     out?: string;
     cache?: Map<string, {
         hash: string;
@@ -202,7 +205,9 @@ interface CodeInfo {
     }[];
     importedNames?: string[];
 }
-declare function extractCode(rel: string, ext: string, content: string): CodeInfo;
+declare function extractCode(rel: string, ext: string, content: string, opts?: {
+    maxCallsPerFile?: number;
+}): CodeInfo;
 
 interface MarkdownInfo {
     title?: string;
@@ -229,7 +234,9 @@ interface AstResult {
     }[];
     importedNames: string[];
 }
-declare function extractAst(rel: string, ext: string, content: string): AstResult | undefined;
+declare function extractAst(rel: string, ext: string, content: string, opts?: {
+    maxCalls?: number;
+}): AstResult | undefined;
 
 type Resolution = {
     kind: "resolved";
@@ -705,4 +712,4 @@ declare function rrf<T>(lists: T[][], keyOf: (item: T) => string, k?: number): M
 
 declare function runCli(argv: string[]): Promise<void>;
 
-export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractMarkdown, extractSymbols, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, wordpiece, writeMemory };
+export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractMarkdown, extractSymbols, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, wordpiece, writeMemory };

package/scripts/engine.mjs

@@ -14,9 +14,9 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.12.0";
+    ENGINE_VERSION = "2.13.0";
     SCHEMA_VERSION = 4;
-    EXTRACTOR_VERSION = 9;
+    EXTRACTOR_VERSION = 10;
   }
 });
 
@@ -320,6 +320,7 @@ function walk(root, opts = {}) {
   const maxFileBytes = opts.maxFileBytes ?? 1024 * 1024;
   const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES;
   const useGitignore = opts.gitignore !== false;
+  const ignoreDirs = opts.ignoreDirs ? new Set(opts.ignoreDirs) : IGNORE_DIRS;
   const out2 = [];
   let capped = false;
   let excluded = 0;
@@ -368,7 +369,7 @@ function walk(root, opts = {}) {
         continue;
       }
       if (st.isDirectory()) {
-        if (IGNORE_DIRS.has(name2)) continue;
+        if (ignoreDirs.has(name2)) continue;
         if (isLink) continue;
         if (useGitignore && rules.length && isIgnored(rules, rel, true)) continue;
         stack.push({ dir: abs, rel, rules });
@@ -463,6 +464,7 @@ var init_walk = __esm({
       ".cache",
       "tmp",
       ".ultraindex",
+      ".codeindex",
       "Pods",
       "DerivedData",
       ".terraform",
@@ -901,7 +903,7 @@ var init_js_ts = __esm({
     RULES = [
       { re: /^\s*export\s+(?:async\s+)?function\s+(?<name>[\w$]+)/, kind: "function", exported: true },
       { re: /^\s*export\s+default\s+(?:async\s+)?function\s+(?<name>[\w$]+)/, kind: "function", exported: true },
-      { re: /^\s*export\s+default\s+(?:abstract\s+)?class\s+(?<name>[\w$]+)/, kind: "class", exported: true },
+      { re: /^\s*export\s+default\s+(?:abstract\s+)?class\s+(?!extends\b)(?<name>[\w$]+)/, kind: "class", exported: true },
       { re: /^\s*(?:async\s+)?function\s+(?<name>[\w$]+)/, kind: "function", exported: false },
       { re: /^\s*export\s+(?:abstract\s+)?class\s+(?<name>[\w$]+)/, kind: "class", exported: true },
       { re: /^\s*(?:abstract\s+)?class\s+(?<name>[\w$]+)/, kind: "class", exported: false },
@@ -5718,7 +5720,7 @@ function readReceiver(node) {
   const name2 = obj ? readName(obj) : void 0;
   return name2 && /^[A-Za-z_]\w*$/.test(name2) ? name2 : void 0;
 }
-function collectCalls(root, spec) {
+function collectCalls(root, spec, maxCalls = MAX_CALLS) {
   if (!spec.calls) return [];
   const out2 = [];
   const seen = /* @__PURE__ */ new Set();
@@ -5749,7 +5751,7 @@ function collectCalls(root, spec) {
   };
   visit(root);
   out2.sort((a, b) => byStr(a.name, b.name) || a.line - b.line);
-  return out2.slice(0, MAX_CALLS);
+  return out2.slice(0, maxCalls);
 }
 function collectImportedNames(root, spec) {
   if (!spec.imports?.import_statement) return [];
@@ -5776,7 +5778,7 @@ function collectImportedNames(root, spec) {
   visit(root);
   return [...found].sort(byStr).slice(0, MAX_IMPORTED_NAMES);
 }
-function extractAst(rel, ext, content) {
+function extractAst(rel, ext, content, opts = {}) {
   const key = grammarKeyForExt(ext);
   if (!key || !grammarReady(key)) return void 0;
   const spec = SPECS[key];
@@ -5962,7 +5964,7 @@ function extractAst(rel, ext, content) {
     }
     const refs = collectImports(root, spec);
     const idents = collectRefIdents(root, new Set(symbols.map((s) => s.name)));
-    const calls = collectCalls(root, spec);
+    const calls = collectCalls(root, spec, opts.maxCalls);
     const importedNames = collectImportedNames(root, spec);
     let pkg;
     if (spec.lang === "java") {
@@ -6398,12 +6400,12 @@ function extractImports(ext, content) {
   }
   return [...specs].map((spec) => ({ kind: "import", spec }));
 }
-function collectCallsRegex(content, symbols = []) {
+function collectCallsRegex(content, symbols = [], maxCalls = 512) {
   const out2 = /* @__PURE__ */ new Map();
   const ownDefLines = new Set(symbols.map((s) => `${s.name} ${s.line}`));
   const lines = content.split("\n");
   const CALL_RE = /(?:\bnew\s+)?(?:([A-Za-z_$][\w$]*)\s*\.\s*)?([A-Za-z_$][\w$]*)\s*\(/g;
-  for (let i2 = 0; i2 < lines.length && out2.size < 512; i2++) {
+  for (let i2 = 0; i2 < lines.length && out2.size < maxCalls; i2++) {
     const line = lines[i2];
     const trimmed = line.trimStart();
     if (trimmed.startsWith("//") || trimmed.startsWith("#") || trimmed.startsWith("*")) continue;
@@ -6418,7 +6420,7 @@ function collectCallsRegex(content, symbols = []) {
     CALL_RE.lastIndex = 0;
     let m;
     const fallbackExcluded = /* @__PURE__ */ new Set();
-    while ((m = CALL_RE.exec(line)) !== null && out2.size < 512) {
+    while ((m = CALL_RE.exec(line)) !== null && out2.size < maxCalls) {
       const receiver = m[1];
       const name2 = m[2];
       if (name2.length < 2 || CALL_KEYWORDS.has(name2)) continue;
@@ -6435,8 +6437,8 @@ function collectCallsRegex(content, symbols = []) {
   }
   return [...out2.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.line - b.line);
 }
-function extractCode(rel, ext, content) {
-  const ast = extractAst(rel, ext, content);
+function extractCode(rel, ext, content, opts = {}) {
+  const ast = extractAst(rel, ext, content, { maxCalls: opts.maxCallsPerFile });
   const symbols = (ast ? ast.symbols : extractSymbols(rel, ext, content)).slice(0, 400);
   const known = new Set(symbols.map((s) => s.name));
   const reexports = extractReexports(rel, content, symbols).filter((s) => !known.has(s.name));
@@ -6452,7 +6454,7 @@ function extractCode(rel, ext, content) {
     // collector otherwise, so caller indexes exist without the wasm sidecar.
     // `symbols` (this file's own regex-extracted defs) lets the collector
     // exclude a definition's own name+line from its call candidates.
-    calls: ast ? ast.calls : collectCallsRegex(content, symbols),
+    calls: ast ? ast.calls : collectCallsRegex(content, symbols, opts.maxCallsPerFile),
     importedNames: ast?.importedNames
   };
 }
@@ -6524,7 +6526,8 @@ function scanRepo(root, opts = {}) {
   const { files: walked, capped, excluded } = walk(root, {
     maxFileBytes: opts.maxBytes,
     maxFiles: opts.maxFiles,
-    gitignore: opts.gitignore
+    gitignore: opts.gitignore,
+    ignoreDirs: opts.ignoreDirs
   });
   const outPrefix = opts.out ? opts.out.replace(/\/+$/, "") + "/" : null;
   const files = [];
@@ -6573,7 +6576,7 @@ function scanRepo(root, opts = {}) {
       } else if (kind === "doc") {
         record.title = basename(f.rel);
       } else if (kind === "code") {
-        const code = extractCode(f.rel, f.ext, content);
+        const code = extractCode(f.rel, f.ext, content, { maxCallsPerFile: opts.maxCallsPerFile });
         record.title = basename(f.rel);
         record.summary = code.summary;
         record.symbols = code.symbols;
@@ -9418,16 +9421,12 @@ function resolveEmbedModelDir(repo) {
 function hasEmbedModel(repo) {
   return resolveEmbedModelDir(repo) !== void 0;
 }
-function loadEmbedModel(dir) {
-  if (!dir) return void 0;
-  const path = join10(dir, "model.json");
-  if (!existsSync3(path)) return void 0;
-  const raw = JSON.parse(readFileSync5(path, "utf8"));
-  const { modelId, dim, vocab, weights } = raw;
-  if (typeof modelId !== "string" || !modelId) throw new Error(`embed model: missing modelId in ${path}`);
-  if (!Number.isInteger(dim) || dim <= 0) throw new Error(`embed model: bad dim ${dim} in ${path}`);
+function parseEmbedModel(raw, source) {
+  const { modelId, dim, vocab, weights, unk: rawUnk } = raw ?? {};
+  if (typeof modelId !== "string" || !modelId) throw new Error(`embed model: missing modelId in ${source}`);
+  if (!Number.isInteger(dim) || dim <= 0) throw new Error(`embed model: bad dim ${dim} in ${source}`);
   if (!Array.isArray(vocab) || !Array.isArray(weights) || vocab.length !== weights.length) {
-    throw new Error(`embed model: vocab/weights length mismatch in ${path}`);
+    throw new Error(`embed model: vocab/weights length mismatch in ${source}`);
   }
   const vocabSize = vocab.length;
   const flat = new Float64Array(vocabSize * dim);
@@ -9442,10 +9441,17 @@ function loadEmbedModel(dir) {
     }
     for (let d = 0; d < dim; d++) flat[i2 * dim + d] = Number(row[d]);
   }
-  const unk = typeof raw.unk === "string" ? raw.unk : "[UNK]";
+  const unk = typeof rawUnk === "string" ? rawUnk : "[UNK]";
   const unkId = vmap.has(unk) ? vmap.get(unk) : -1;
   return { modelId, dim, unk, unkId, vocabSize, vocab: vmap, weights: flat };
 }
+function loadEmbedModel(dir) {
+  if (!dir) return void 0;
+  const path = join10(dir, "model.json");
+  if (!existsSync3(path)) return void 0;
+  const raw = JSON.parse(readFileSync5(path, "utf8"));
+  return parseEmbedModel(raw, path);
+}
 function resolveEmbedPullUrl() {
   const env = process.env.CODEINDEX_EMBED_URL;
   if (env && env.trim()) return { url: env.trim() };
@@ -10172,10 +10178,13 @@ var init_viz = __esm({
 // src/mcp.ts
 var mcp_exports = {};
 __export(mcp_exports, {
+  memoizedEmbedModel: () => memoizedEmbedModel,
   memoizedEmbeddingIndex: () => memoizedEmbeddingIndex,
   runMcpServer: () => runMcpServer,
   scanFingerprint: () => scanFingerprint
 });
+import { statSync as statSync4 } from "fs";
+import { join as join12 } from "path";
 import { createInterface } from "readline";
 function str(v) {
   return typeof v === "string" && v ? v : void 0;
@@ -10196,6 +10205,19 @@ async function memoizedEmbeddingIndex(key, build) {
   embeddingIndexCache = { key: cacheKey, index };
   return index;
 }
+function memoizedEmbedModel(modelDir) {
+  let stat;
+  try {
+    stat = statSync4(join12(modelDir, "model.json"));
+  } catch {
+    return void 0;
+  }
+  const key = `${modelDir}:${stat.mtimeMs}:${stat.size}`;
+  if (embedModelCache && embedModelCache.key === key) return embedModelCache.model;
+  const model = loadEmbedModel(modelDir);
+  if (model) embedModelCache = { key, model };
+  return model;
+}
 async function callTool(name2, args2) {
   const repo = str(args2.repo);
   if (!repo) throw new Error("`repo` is required (absolute path to the repository root)");
@@ -10350,7 +10372,7 @@ async function callTool(name2, args2) {
         }
       }
       const modelDir = resolveEmbedModelDir(repo);
-      const model = modelDir ? loadEmbedModel(modelDir) : void 0;
+      const model = modelDir ? memoizedEmbedModel(modelDir) : void 0;
       if (model) {
         const index = await memoizedEmbeddingIndex(
           { mode: "static", identity: `${modelDir}#${model.modelId}`, scan: scan2 },
@@ -10370,7 +10392,7 @@ async function callTool(name2, args2) {
   }
   if (name2 === "embed_status") {
     const modelDir = resolveEmbedModelDir(repo);
-    const model = modelDir ? loadEmbedModel(modelDir) : void 0;
+    const model = modelDir ? memoizedEmbedModel(modelDir) : void 0;
     const endpoint = resolveEmbedEndpoint();
     const mode = endpoint ? "endpoint" : model ? "static" : "none";
     const status = {
@@ -10445,7 +10467,7 @@ async function runMcpServer() {
     }
   }
 }
-var repoProp, scopeProps, TOOLS, embeddingIndexCache;
+var repoProp, scopeProps, TOOLS, embeddingIndexCache, embedModelCache;
 var init_mcp = __esm({
   "src/mcp.ts"() {
     "use strict";
@@ -11148,7 +11170,7 @@ init_pipeline();
 init_graph_json();
 init_symbols_json();
 import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
-import { join as join12, resolve } from "path";
+import { join as join13, resolve } from "path";
 init_scan();
 init_callers();
 init_workspaces();
@@ -11216,8 +11238,11 @@ Flags:
   --exclude <glob>    Exclude matching paths (repeatable)
   --scope <dir>       Restrict to one directory (sugar for --include '<dir>/**')
   --no-gitignore      Do not honor .gitignore files (default: honored)
+  --ignore-dir <name> Directory names to skip (repeatable) \u2014 REPLACES the
+                      default ignored-directory set, never merges with it
   --max-files <n>     Cap walked files (default 20000)
   --max-bytes <n>     Skip files above this size (default 1 MiB)
+  --max-calls <n>     Per-file call-site cap for extraction (default 512)
   --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)
@@ -11232,7 +11257,7 @@ Flags:
                       each site corroborated|unique-name
 `;
 function parseFlags(args2) {
-  const flags2 = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false, fuzzy: true, semantic: false };
+  const flags2 = { repo: process.cwd(), include: [], exclude: [], gitignore: true, ignoreDirs: [], noAst: false, fuzzy: true, semantic: false };
   for (let i2 = 0; i2 < args2.length; i2++) {
     const a = args2[i2];
     const next = () => {
@@ -11255,8 +11280,10 @@ function parseFlags(args2) {
     else if (a === "--exclude") flags2.exclude.push(next());
     else if (a === "--scope") flags2.scope = next();
     else if (a === "--no-gitignore") flags2.gitignore = false;
+    else if (a === "--ignore-dir") flags2.ignoreDirs.push(next());
     else if (a === "--max-files") flags2.maxFiles = num();
     else if (a === "--max-bytes") flags2.maxBytes = num();
+    else if (a === "--max-calls") flags2.maxCalls = num();
     else if (a === "--ignore-case") flags2.ignoreCase = true;
     else if (a === "--max-hits") flags2.maxHits = num();
     else if (a === "--budget-tokens") flags2.budgetTokens = num();
@@ -11283,8 +11310,10 @@ function scanOptions(flags2) {
     exclude: flags2.exclude.length ? flags2.exclude : void 0,
     scope: flags2.scope,
     gitignore: flags2.gitignore,
+    ignoreDirs: flags2.ignoreDirs.length ? flags2.ignoreDirs : void 0,
     maxFiles: flags2.maxFiles,
-    maxBytes: flags2.maxBytes
+    maxBytes: flags2.maxBytes,
+    maxCallsPerFile: flags2.maxCalls
   };
 }
 async function runCli(argv) {
@@ -11309,7 +11338,7 @@ async function runCli(argv) {
     if (!flags2.out) throw new Error("index needs --out <dir>");
     const outDir = flags2.out;
     mkdirSync2(outDir, { recursive: true });
-    const cachePath = join12(outDir, "cache.json");
+    const cachePath = join13(outDir, "cache.json");
     let cache;
     try {
       const parsed = JSON.parse(readFileSync6(cachePath, "utf8"));
@@ -11319,8 +11348,8 @@ async function runCli(argv) {
     } catch {
     }
     const { scan: scan2, graph, symbols } = buildIndexArtifacts(flags2.repo, { ...scanOptions(flags2), cache, out: outDir });
-    writeFileSync3(join12(outDir, "graph.json"), renderGraphJson(graph));
-    writeFileSync3(join12(outDir, "symbols.json"), renderSymbolsJson(symbols));
+    writeFileSync3(join13(outDir, "graph.json"), renderGraphJson(graph));
+    writeFileSync3(join13(outDir, "symbols.json"), renderSymbolsJson(symbols));
     const files = {};
     for (const f of scan2.files) {
       const entry = { hash: f.hash, record: f, size: f.size };
@@ -11337,7 +11366,7 @@ async function runCli(argv) {
     const model = modelDir ? loadEmbedModel(modelDir) : void 0;
     if (model) {
       const index = buildEmbeddingIndex(scan2, model);
-      writeFileSync3(join12(outDir, "embeddings.bin"), serializeEmbeddings(index));
+      writeFileSync3(join13(outDir, "embeddings.bin"), serializeEmbeddings(index));
       embedNote = ` + embeddings.bin (${index.records.length} records, model ${model.modelId})`;
     }
     process.stderr.write(`codeindex: ${scan2.files.length} files \u2192 ${outDir}/graph.json + symbols.json${embedNote}${scan2.capped ? " (capped)" : ""}
@@ -11469,14 +11498,14 @@ async function runCli(argv) {
       mkdirSync2(flags2.out, { recursive: true });
       const scan2 = scanRepo(flags2.repo, scanOptions(flags2));
       const index = buildEmbeddingIndex(scan2, model);
-      writeFileSync3(join12(flags2.out, "embeddings.bin"), serializeEmbeddings(index));
+      writeFileSync3(join13(flags2.out, "embeddings.bin"), serializeEmbeddings(index));
       process.stderr.write(`codeindex: ${index.records.length} embedding records \u2192 ${flags2.out}/embeddings.bin (model ${model.modelId})
 `);
     } else if (sub === "pull") {
       const { url, sha256 } = resolveEmbedPullUrl();
-      const destDir = process.env.CODEINDEX_EMBED_DIR ?? join12(flags2.repo, ".codeindex", "models");
+      const destDir = process.env.CODEINDEX_EMBED_DIR ?? join13(flags2.repo, ".codeindex", "models");
       mkdirSync2(destDir, { recursive: true });
-      process.stderr.write(`codeindex: fetching model from ${url} \u2192 ${join12(destDir, "model.json")}
+      process.stderr.write(`codeindex: fetching model from ${url} \u2192 ${join13(destDir, "model.json")}
 `);
       let body2;
       try {
@@ -11488,14 +11517,17 @@ async function runCli(argv) {
         return;
       }
       try {
-        JSON.parse(body2);
-      } catch {
-        process.stderr.write("codeindex: pull failed \u2014 response is not a valid model.json (expected JSON)\n");
+        parseEmbedModel(JSON.parse(body2), url);
+      } catch (e) {
+        process.stderr.write(
+          `codeindex: pull failed \u2014 response is not a valid model.json (${e instanceof Error ? e.message : String(e)}) (nothing written)
+`
+        );
         process.exitCode = 1;
         return;
       }
-      writeFileSync3(join12(destDir, "model.json"), body2);
-      process.stderr.write(`codeindex: model written to ${join12(destDir, "model.json")}
+      writeFileSync3(join13(destDir, "model.json"), body2);
+      process.stderr.write(`codeindex: model written to ${join13(destDir, "model.json")}
 `);
     } else {
       throw new Error("embed needs a subcommand: status | build | pull | serve");

package/src/ast/extract.ts

@@ -399,8 +399,9 @@ function readReceiver(node: TSNode | null): string | undefined {
 // dedicated member-call node's `name`; "constructor" reads the constructed type.
 // A qualified call also carries the immediate `receiver` name (see readReceiver).
 // Names are filtered to plausible identifiers (≥ 2 chars), deduped by name+line,
-// sorted, and capped, so the set stays small and deterministic.
-function collectCalls(root: TSNode, spec: LangSpec): { name: string; line: number; receiver?: string }[] {
+// sorted, and capped (default MAX_CALLS; overridable via maxCalls), so the set
+// stays small and deterministic.
+function collectCalls(root: TSNode, spec: LangSpec, maxCalls: number = MAX_CALLS): { name: string; line: number; receiver?: string }[] {
   if (!spec.calls) return [];
   const out: { name: string; line: number; receiver?: string }[] = [];
   const seen = new Set<string>();
@@ -439,7 +440,7 @@ function collectCalls(root: TSNode, spec: LangSpec): { name: string; line: numbe
   };
   visit(root);
   out.sort((a, b) => byStr(a.name, b.name) || a.line - b.line);
-  return out.slice(0, MAX_CALLS);
+  return out.slice(0, maxCalls);
 }
 
 // Collect JS/TS named-import bindings: `import { a, b as c } from "x"` →
@@ -476,7 +477,8 @@ function collectImportedNames(root: TSNode, spec: LangSpec): string[] {
 // Extract declared symbols from one file via its committed grammar. Returns
 // undefined when no grammar is loaded for the extension (caller falls back to the
 // regex extractor). Walks top-level declarations plus one level of nested members.
-export function extractAst(rel: string, ext: string, content: string): AstResult | undefined {
+// `opts.maxCalls` overrides the per-file call-site cap (default MAX_CALLS).
+export function extractAst(rel: string, ext: string, content: string, opts: { maxCalls?: number } = {}): AstResult | undefined {
   const key = grammarKeyForExt(ext);
   if (!key || !grammarReady(key)) return undefined;
   const spec = SPECS[key];
@@ -697,7 +699,7 @@ export function extractAst(rel: string, ext: string, content: string): AstResult
 
     const refs = collectImports(root, spec);
     const idents = collectRefIdents(root, new Set(symbols.map((s) => s.name)));
-    const calls = collectCalls(root, spec);
+    const calls = collectCalls(root, spec, opts.maxCalls);
     const importedNames = collectImportedNames(root, spec);
     let pkg: string | undefined;
     if (spec.lang === "java") {

package/src/embed/model.ts

@@ -87,20 +87,17 @@ export function hasEmbedModel(repo?: string): boolean {
   return resolveEmbedModelDir(repo) !== undefined;
 }
 
-// Load and validate a static model from a directory containing model.json.
-// Throws on a malformed file (bad dim, ragged weights) so a corrupt asset fails
-// loudly at load rather than silently misranking. Returns undefined only when
-// the directory has no model.json (the not-present case).
-export function loadEmbedModel(dir?: string): StaticEmbedModel | undefined {
-  if (!dir) return undefined;
-  const path = join(dir, "model.json");
-  if (!existsSync(path)) return undefined;
-  const raw = JSON.parse(readFileSync(path, "utf8")) as ModelFile;
-  const { modelId, dim, vocab, weights } = raw;
-  if (typeof modelId !== "string" || !modelId) throw new Error(`embed model: missing modelId in ${path}`);
-  if (!Number.isInteger(dim) || dim <= 0) throw new Error(`embed model: bad dim ${dim} in ${path}`);
+// Validate a parsed model.json body and construct the loaded model. Throws on
+// a malformed shape (missing modelId, bad dim, vocab/weights mismatch, ragged
+// rows) with a message citing `source` (a file path, a URL, …) so a corrupt
+// asset fails loudly wherever it enters — at load, or at `embed pull` BEFORE
+// the shape-invalid file is ever written to disk.
+export function parseEmbedModel(raw: unknown, source: string): StaticEmbedModel {
+  const { modelId, dim, vocab, weights, unk: rawUnk } = (raw ?? {}) as ModelFile;
+  if (typeof modelId !== "string" || !modelId) throw new Error(`embed model: missing modelId in ${source}`);
+  if (!Number.isInteger(dim) || dim <= 0) throw new Error(`embed model: bad dim ${dim} in ${source}`);
   if (!Array.isArray(vocab) || !Array.isArray(weights) || vocab.length !== weights.length) {
-    throw new Error(`embed model: vocab/weights length mismatch in ${path}`);
+    throw new Error(`embed model: vocab/weights length mismatch in ${source}`);
   }
   const vocabSize = vocab.length;
   const flat = new Float64Array(vocabSize * dim);
@@ -115,11 +112,23 @@ export function loadEmbedModel(dir?: string): StaticEmbedModel | undefined {
     }
     for (let d = 0; d < dim; d++) flat[i * dim + d] = Number(row[d]);
   }
-  const unk = typeof raw.unk === "string" ? raw.unk : "[UNK]";
+  const unk = typeof rawUnk === "string" ? rawUnk : "[UNK]";
   const unkId = vmap.has(unk) ? vmap.get(unk)! : -1;
   return { modelId, dim, unk, unkId, vocabSize, vocab: vmap, weights: flat };
 }
 
+// Load and validate a static model from a directory containing model.json.
+// Throws on a malformed file (bad dim, ragged weights) so a corrupt asset fails
+// loudly at load rather than silently misranking. Returns undefined only when
+// the directory has no model.json (the not-present case).
+export function loadEmbedModel(dir?: string): StaticEmbedModel | undefined {
+  if (!dir) return undefined;
+  const path = join(dir, "model.json");
+  if (!existsSync(path)) return undefined;
+  const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+  return parseEmbedModel(raw, path);
+}
+
 // What `embed pull` fetches, and whether to verify it. CODEINDEX_EMBED_URL wins
 // outright (the user's explicit override / private mirror) and carries NO
 // sha256, so a custom asset keeps the current un-verified behavior. With no env,

package/src/engine-cli.ts

@@ -19,7 +19,7 @@ import { symbolComplexity, riskHotspots } from "./complexity.js";
 import { renderMermaid } from "./viz.js";
 import { searchIndex } from "./bm25.js";
 import { checkRules, parseRules } from "./rules.js";
-import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, resolveEmbedPullUrl, fetchEmbedModel } from "./embed/model.js";
+import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, parseEmbedModel, resolveEmbedPullUrl, fetchEmbedModel } from "./embed/model.js";
 import { buildEmbeddingIndex, serializeEmbeddings } from "./embed/index.js";
 import { searchSemantic } from "./embed/search.js";
 import {
@@ -80,8 +80,11 @@ Flags:
   --exclude <glob>    Exclude matching paths (repeatable)
   --scope <dir>       Restrict to one directory (sugar for --include '<dir>/**')
   --no-gitignore      Do not honor .gitignore files (default: honored)
+  --ignore-dir <name> Directory names to skip (repeatable) — REPLACES the
+                      default ignored-directory set, never merges with it
   --max-files <n>     Cap walked files (default 20000)
   --max-bytes <n>     Skip files above this size (default 1 MiB)
+  --max-calls <n>     Per-file call-site cap for extraction (default 512)
   --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)
@@ -103,8 +106,10 @@ interface CliFlags {
   exclude: string[];
   scope?: string;
   gitignore: boolean;
+  ignoreDirs: string[];
   maxFiles?: number;
   maxBytes?: number;
+  maxCalls?: number;
   noAst: boolean;
   since?: string;
   ignoreCase?: boolean;
@@ -121,7 +126,7 @@ interface CliFlags {
 }
 
 function parseFlags(args: string[]): CliFlags {
-  const flags: CliFlags = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false, fuzzy: true, semantic: false };
+  const flags: CliFlags = { repo: process.cwd(), include: [], exclude: [], gitignore: true, ignoreDirs: [], noAst: false, fuzzy: true, semantic: false };
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     const next = (): string => {
@@ -144,8 +149,10 @@ function parseFlags(args: string[]): CliFlags {
     else if (a === "--exclude") flags.exclude.push(next());
     else if (a === "--scope") flags.scope = next();
     else if (a === "--no-gitignore") flags.gitignore = false;
+    else if (a === "--ignore-dir") flags.ignoreDirs.push(next());
     else if (a === "--max-files") flags.maxFiles = num();
     else if (a === "--max-bytes") flags.maxBytes = num();
+    else if (a === "--max-calls") flags.maxCalls = num();
     else if (a === "--ignore-case") flags.ignoreCase = true;
     else if (a === "--max-hits") flags.maxHits = num();
     else if (a === "--budget-tokens") flags.budgetTokens = num();
@@ -174,8 +181,10 @@ function scanOptions(flags: CliFlags): BuildIndexOptions {
     exclude: flags.exclude.length ? flags.exclude : undefined,
     scope: flags.scope,
     gitignore: flags.gitignore,
+    ignoreDirs: flags.ignoreDirs.length ? flags.ignoreDirs : undefined,
     maxFiles: flags.maxFiles,
     maxBytes: flags.maxBytes,
+    maxCallsPerFile: flags.maxCalls,
   };
 }
 
@@ -404,9 +413,14 @@ export async function runCli(argv: string[]): Promise<void> {
         return;
       }
       try {
-        JSON.parse(body);
-      } catch {
-        process.stderr.write("codeindex: pull failed — response is not a valid model.json (expected JSON)\n");
+        // Shape-validate BEFORE writing: a JSON-valid but shape-invalid asset
+        // would otherwise land on disk and turn every later semantic search
+        // into a hard loadEmbedModel error instead of the documented degrade.
+        parseEmbedModel(JSON.parse(body), url);
+      } catch (e) {
+        process.stderr.write(
+          `codeindex: pull failed — response is not a valid model.json (${e instanceof Error ? e.message : String(e)}) (nothing written)\n`,
+        );
         process.exitCode = 1;
         return;
       }

package/src/engine.ts

@@ -114,7 +114,7 @@ export {
   loadEmbedModel,
   resolveEmbedPullUrl,
 } from "./embed/model.js";
-export type { StaticEmbedModel } from "./embed/model.js";
+export type { StaticEmbedModel, EmbedPullTarget } from "./embed/model.js";
 export { encode, quantize, tokenize, wordpiece, basicTokenize, roundHalfToEven, intDot } from "./embed/encode.js";
 export { buildEmbeddingIndex, serializeEmbeddings, deserializeEmbeddings, embeddingUnits } from "./embed/index.js";
 export type { EmbeddingIndex, EmbeddingRecord, EmbeddingUnit } from "./embed/index.js";

package/src/extract/code.ts

@@ -302,12 +302,13 @@ const DEF_INTRODUCERS = /(?:\bfunction|\bdef|\bfunc|\bfun|\bfn|\bclass|\bsub|\bm
 export function collectCallsRegex(
   content: string,
   symbols: Pick<CodeSymbol, "name" | "line">[] = [],
+  maxCalls: number = 512,
 ): { name: string; line: number; receiver?: string }[] {
   const out = new Map<string, { name: string; line: number; receiver?: string }>();
   const ownDefLines = new Set(symbols.map((s) => `${s.name} ${s.line}`));
   const lines = content.split("\n");
   const CALL_RE = /(?:\bnew\s+)?(?:([A-Za-z_$][\w$]*)\s*\.\s*)?([A-Za-z_$][\w$]*)\s*\(/g;
-  for (let i = 0; i < lines.length && out.size < 512; i++) {
+  for (let i = 0; i < lines.length && out.size < maxCalls; i++) {
     const line = lines[i]!;
     // Cheap comment guard: a line-leading comment marker means no calls here
     // (block-comment interiors and strings stay best-effort, like the symbol
@@ -332,7 +333,7 @@ export function collectCallsRegex(
     CALL_RE.lastIndex = 0;
     let m: RegExpExecArray | null;
     const fallbackExcluded = new Set<string>();
-    while ((m = CALL_RE.exec(line)) !== null && out.size < 512) {
+    while ((m = CALL_RE.exec(line)) !== null && out.size < maxCalls) {
       const receiver = m[1];
       const name = m[2]!;
       if (name.length < 2 || CALL_KEYWORDS.has(name)) continue;
@@ -350,13 +351,16 @@ export function collectCallsRegex(
   return [...out.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.line - b.line));
 }
 
-export function extractCode(rel: string, ext: string, content: string): CodeInfo {
+// `opts.maxCallsPerFile` overrides the per-file call-site cap (default 512) on
+// BOTH extraction tiers — AST and regex — so recall-oriented consumers can raise
+// it. Dedup/sort semantics are unchanged; absent, output is byte-identical.
+export function extractCode(rel: string, ext: string, content: string, opts: { maxCallsPerFile?: number } = {}): CodeInfo {
   // Symbols come from tree-sitter when a grammar is loaded for this extension
   // (AST-exact: real nesting, precise kinds, structural export), else the regex
   // extractors. Imports/pkg stay on the battle-tested regex path here — their
   // resolution is covered by resolve tests and the e2e ratchet; the new-language
   // AST importers land with their resolvers.
-  const ast = extractAst(rel, ext, content);
+  const ast = extractAst(rel, ext, content, { maxCalls: opts.maxCallsPerFile });
   const symbols = (ast ? ast.symbols : extractSymbols(rel, ext, content)).slice(0, 400);
   // Add barrel re-exports the local def didn't already cover.
   const known = new Set(symbols.map((s) => s.name));
@@ -378,7 +382,7 @@ export function extractCode(rel: string, ext: string, content: string): CodeInfo
     // collector otherwise, so caller indexes exist without the wasm sidecar.
     // `symbols` (this file's own regex-extracted defs) lets the collector
     // exclude a definition's own name+line from its call candidates.
-    calls: ast ? ast.calls : collectCallsRegex(content, symbols),
+    calls: ast ? ast.calls : collectCallsRegex(content, symbols, opts.maxCallsPerFile),
     importedNames: ast?.importedNames,
   };
 }

package/src/lang/js-ts.ts

@@ -7,7 +7,7 @@ import { scan, type Rule } from "./common.js";
 const RULES: Rule[] = [
   { re: /^\s*export\s+(?:async\s+)?function\s+(?<name>[\w$]+)/, kind: "function", exported: true },
   { re: /^\s*export\s+default\s+(?:async\s+)?function\s+(?<name>[\w$]+)/, kind: "function", exported: true },
-  { re: /^\s*export\s+default\s+(?:abstract\s+)?class\s+(?<name>[\w$]+)/, kind: "class", exported: true },
+  { re: /^\s*export\s+default\s+(?:abstract\s+)?class\s+(?!extends\b)(?<name>[\w$]+)/, kind: "class", exported: true },
   { re: /^\s*(?:async\s+)?function\s+(?<name>[\w$]+)/, kind: "function", exported: false },
   { re: /^\s*export\s+(?:abstract\s+)?class\s+(?<name>[\w$]+)/, kind: "class", exported: true },
   { re: /^\s*(?:abstract\s+)?class\s+(?<name>[\w$]+)/, kind: "class", exported: false },

package/src/mcp.ts

@@ -5,6 +5,8 @@
 // `repo` path and returns JSON text content.
 //
 // Register in an MCP client as:  node scripts/engine.mjs mcp
+import { statSync } from "node:fs";
+import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { ENGINE_VERSION } from "./types.js";
 import { ensureGrammars, allGrammarKeys } from "./ast/loader.js";
@@ -25,7 +27,7 @@ import { replaceSymbolBody, insertAfterSymbol, insertBeforeSymbol } from "./edit
 import { writeMemory, readMemory, deleteMemory, listMemories } from "./memory.js";
 import { searchIndex } from "./bm25.js";
 import { checkRules, parseRules } from "./rules.js";
-import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel } from "./embed/model.js";
+import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, type StaticEmbedModel } from "./embed/model.js";
 import { buildEmbeddingIndex, type EmbeddingIndex } from "./embed/index.js";
 import { searchSemantic } from "./embed/search.js";
 import { resolveEmbedEndpoint, buildEndpointIndex, encodeQueryViaEndpoint, probeEndpoint } from "./embed/endpoint.js";
@@ -366,6 +368,31 @@ export async function memoizedEmbeddingIndex(
   return index;
 }
 
+// A SINGLE entry — never an unbounded map — holding the most recent parse.
+let embedModelCache: { key: string; model: StaticEmbedModel } | undefined;
+
+// model.json is 10-30 MB with the real asset; reading + JSON.parsing it on
+// EVERY request dominates static-tier latency, so the parsed model is memoized
+// across requests. One statSync per request keys the cache on
+// (dir, mtimeMs, size) so an in-place re-pull invalidates on the next call.
+// Same discipline as memoizedEmbeddingIndex: a failed load is NEVER cached —
+// the throw propagates and the cache is left as it was, so the next request
+// retries from scratch. A missing model.json returns undefined (the
+// not-present case, exactly like loadEmbedModel).
+export function memoizedEmbedModel(modelDir: string): StaticEmbedModel | undefined {
+  let stat;
+  try {
+    stat = statSync(join(modelDir, "model.json"));
+  } catch {
+    return undefined;
+  }
+  const key = `${modelDir}:${stat.mtimeMs}:${stat.size}`;
+  if (embedModelCache && embedModelCache.key === key) return embedModelCache.model;
+  const model = loadEmbedModel(modelDir);
+  if (model) embedModelCache = { key, model };
+  return model;
+}
+
 async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
   const repo = str(args.repo);
   if (!repo) throw new Error("`repo` is required (absolute path to the repository root)");
@@ -530,7 +557,7 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<st
         }
       }
       const modelDir = resolveEmbedModelDir(repo);
-      const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+      const model = modelDir ? memoizedEmbedModel(modelDir) : undefined;
       if (model) {
         const index = await memoizedEmbeddingIndex(
           { mode: "static", identity: `${modelDir}#${model.modelId}`, scan },
@@ -552,7 +579,7 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<st
   }
   if (name === "embed_status") {
     const modelDir = resolveEmbedModelDir(repo);
-    const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+    const model = modelDir ? memoizedEmbedModel(modelDir) : undefined;
     const endpoint = resolveEmbedEndpoint();
     const mode: "none" | "static" | "endpoint" = endpoint ? "endpoint" : model ? "static" : "none";
     const status: Record<string, unknown> = {

package/src/scan.ts

@@ -36,8 +36,15 @@ export interface ScanOptions {
   scope?: string;
   // Honor .gitignore files (default true — see WalkOptions.gitignore).
   gitignore?: boolean;
+  // Directory names to skip — REPLACES the default set (see
+  // WalkOptions.ignoreDirs; compose with the IGNORE_DIRS export to extend it).
+  ignoreDirs?: string[];
   maxBytes?: number;
   maxFiles?: number;
+  // Per-file call-site cap for extraction (default 512, both AST and regex
+  // tiers). Raising it trades index size for call-graph recall; dedup/sort
+  // semantics are unchanged. Absent, output is byte-identical to before.
+  maxCallsPerFile?: number;
   out?: string; // absolute output dir to exclude from the scan (self-index guard)
   // Previous build's extraction cache (rel → {hash, record, size?, mtimeMs?}). A
   // file whose (size,mtime) key matches skips read+hash entirely (the stat
@@ -65,6 +72,7 @@ export function scanRepo(root: string, opts: ScanOptions = {}): RepoScan {
     maxFileBytes: opts.maxBytes,
     maxFiles: opts.maxFiles,
     gitignore: opts.gitignore,
+    ignoreDirs: opts.ignoreDirs,
   });
   // Never index our own output (e.g. a committed `docs/ultraindex/`), or builds
   // would describe the encyclopedia instead of the code.
@@ -144,7 +152,7 @@ export function scanRepo(root: string, opts: ScanOptions = {}): RepoScan {
         // Non-markdown prose (.rst/.txt): title from basename, no link graph.
         record.title = basename(f.rel);
       } else if (kind === "code") {
-        const code = extractCode(f.rel, f.ext, content);
+        const code = extractCode(f.rel, f.ext, content, { maxCallsPerFile: opts.maxCallsPerFile });
         record.title = basename(f.rel);
         record.summary = code.summary;
         record.symbols = code.symbols;

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.12.0";
+export const ENGINE_VERSION = "2.13.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
@@ -37,8 +37,11 @@ export const SCHEMA_VERSION = 4;
 // resolved export-alias symbol also cite the original declaration's own line
 // (and endLine, when the AST tier populated one) instead of the export
 // statement's line — a citation-precision fix (issue #9) for consumers
-// (ultradoc) that use file:line as evidence.
-export const EXTRACTOR_VERSION = 9;
+// (ultradoc) that use file:line as evidence; v10 stops the regex tier
+// emitting a spurious exported class symbol named "extends" for
+// `export default class extends Base {}` (issue #11) — the file-stem
+// default symbol is unchanged.
+export const EXTRACTOR_VERSION = 10;
 
 // How a file is classified. `code` gets symbol/import extraction; `doc` gets
 // link/heading extraction; the rest are catalogued but not deeply parsed.

package/src/walk.ts

@@ -4,12 +4,15 @@ import { parseGitignore, isIgnored, type IgnoreRule } from "./ignore.js";
 
 // Directories that never carry signal for a documentation/code question and
 // would bloat the index (dependencies, build output, VCS internals, caches).
+// .codeindex is the engine's OWN output (index artifacts, pulled models, MCP
+// memories) — indexing it would feed memories into search and churn the scan
+// fingerprint on every write_memory (issue #12).
 // Exported so grep.ts can align ripgrep's universe with the walker's.
 export const IGNORE_DIRS = new Set([
   ".git", "node_modules", ".pnpm", "bower_components", "vendor", "dist", "build", "out",
   "target", ".next", ".nuxt", ".svelte-kit", ".turbo", "coverage", "__pycache__", ".venv",
   "venv", ".tox", ".mypy_cache", ".pytest_cache", ".gradle", ".idea", ".vscode", ".cache",
-  "tmp", ".ultraindex", "Pods", "DerivedData", ".terraform", "elm-stuff", ".dart_tool",
+  "tmp", ".ultraindex", ".codeindex", "Pods", "DerivedData", ".terraform", "elm-stuff", ".dart_tool",
 ]);
 
 // Lockfiles: huge, machine-generated, and pure noise for a code/docs question —
@@ -36,6 +39,13 @@ export interface WalkOptions {
   // semantics — see ignore.ts). Default TRUE: an ignored file is noise for
   // every consumer; pass false to index generated/ignored trees deliberately.
   gitignore?: boolean;
+  // Directory names to skip, REPLACING the default set entirely (not merging
+  // with it). IGNORE_DIRS is a public export, so consumers compose
+  // `[...IGNORE_DIRS, "extra"]` — or filter it — themselves; replace is the
+  // simplest contract. Deliberate scope boundary: grep.ts (the ripgrep
+  // universe) and the MCP server keep the DEFAULT set — recall consumers
+  // (e.g. ultrasec) consume scan/extract, not grep.
+  ignoreDirs?: string[];
 }
 
 export interface WalkedFile {
@@ -65,6 +75,9 @@ export function walk(root: string, opts: WalkOptions = {}): WalkResult {
   const maxFileBytes = opts.maxFileBytes ?? 1024 * 1024;
   const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES;
   const useGitignore = opts.gitignore !== false;
+  // Effective ignored-directory set, built once: the caller's replacement when
+  // given (see WalkOptions.ignoreDirs — replace, never merge), else the default.
+  const ignoreDirs = opts.ignoreDirs ? new Set(opts.ignoreDirs) : IGNORE_DIRS;
   const out: WalkedFile[] = [];
   let capped = false;
   let excluded = 0;
@@ -125,7 +138,7 @@ export function walk(root: string, opts: WalkOptions = {}): WalkResult {
         continue;
       }
       if (st.isDirectory()) {
-        if (IGNORE_DIRS.has(name)) continue;
+        if (ignoreDirs.has(name)) continue;
         // An in-repo DIRECTORY symlink is skipped entirely: its target is (or
         // will be) walked under its canonical name, and letting both paths race
         // through the cycle guard would keep whichever readdir served first —