@maxgfr/codeindex 2.11.1 → 2.13.0

package/src/embed/model.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -20,12 +21,24 @@ import { join } from "node:path";
 // graph.json / symbols.json consumers.
 export const EMBED_VERSION = 1;
 
-// The default model-name a `pull` writes and a `status` reports. The real asset
-// URL is intentionally NOT hard-coded yet (see resolveEmbedPullUrl): the asset
-// is unpublished, so `pull` fails cleanly asking for CODEINDEX_EMBED_URL rather
-// than fetching a phantom.
+// The default sub-directory a `pull` writes into and a `status` reports.
 export const DEFAULT_EMBED_DIRNAME = "models";
 
+// The official static-embedding asset, published as the dedicated GitHub release
+// `embed-model-v1` (tag deliberately outside the `v<semver>` semantic-release
+// namespace, so publishing it triggers no CI). `pull` uses this when
+// CODEINDEX_EMBED_URL is unset. Reproduce the asset byte-for-byte with the pinned
+// toolchain in scripts/embed-asset/.
+export const DEFAULT_EMBED_URL =
+  "https://github.com/maxgfr/codeindex/releases/download/embed-model-v1/model.json";
+
+// sha256 of the published model.json. `pull` verifies the downloaded bytes
+// against this ONLY when it fetched the built-in default (a custom
+// CODEINDEX_EMBED_URL is the user's own mirror and keeps the un-verified
+// behavior). Regenerate alongside DEFAULT_EMBED_URL when re-cutting the asset:
+// `shasum -a 256 model.json`.
+export const EMBED_ASSET_SHA256 = "163ad053eab4e9a80d421ed4164f32292c83290f02fbbe6fe4b9b1cd6ea18d34";
+
 // A loaded static-embedding model. `vocab` maps a wordpiece token to its row
 // index; `weights` is the flat row-major (vocabSize × dim) matrix as IEEE-754
 // doubles (float rows widen to double exactly, so mean-pool stays deterministic).
@@ -74,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);
@@ -102,16 +112,54 @@ 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 };
 }
 
-// Resolve the URL `embed pull` fetches from. The official asset is not published
-// yet, so there is no built-in default: the user must point CODEINDEX_EMBED_URL
-// at a model.json (or a directory serving one). Returns undefined when unset —
-// the caller turns that into a clean, actionable failure, never a crash.
-export function resolveEmbedPullUrl(): string | undefined {
-  const url = process.env.CODEINDEX_EMBED_URL;
-  return url && url.trim() ? url.trim() : 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 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,
+// we fall back to the built-in official asset AND its pinned sha256, so `pull`
+// can prove integrity of the default download.
+export interface EmbedPullTarget {
+  url: string;
+  sha256?: string; // present only for the built-in default → verify
+}
+
+export function resolveEmbedPullUrl(): EmbedPullTarget {
+  const env = process.env.CODEINDEX_EMBED_URL;
+  if (env && env.trim()) return { url: env.trim() };
+  return { url: DEFAULT_EMBED_URL, sha256: EMBED_ASSET_SHA256 };
+}
+
+// Fetch a model.json body over HTTP, following redirects (GitHub release assets
+// 302 to a CDN — native fetch follows by default). When `expectedSha256` is
+// given, the downloaded bytes are hashed and MUST match or this throws with a
+// clear message and returns nothing — so a corrupt/tampered default asset never
+// gets written. A non-2xx response also throws. Verification and I/O are split
+// from the CLI so both the success and the sha-mismatch paths are unit-testable.
+export async function fetchEmbedModel(url: string, expectedSha256?: string): Promise<string> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status} from ${url}`);
+  const body = await res.text();
+  if (expectedSha256) {
+    const got = createHash("sha256").update(body).digest("hex");
+    if (got !== expectedSha256) {
+      throw new Error(`sha256 mismatch: expected ${expectedSha256}, got ${got}`);
+    }
+  }
+  return body;
 }

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 } 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 {
@@ -55,8 +55,9 @@ Commands:
                 embed status   Effective mode (none/static/endpoint), model +
                                EMBED_VERSION, and endpoint reachability (JSON)
                 embed build    Write embeddings.bin into --out <dir> (static tier)
-                embed pull     Fetch the model asset into CODEINDEX_EMBED_DIR (or
-                               <repo>/.codeindex/models/) — needs CODEINDEX_EMBED_URL
+                embed pull     Fetch the official model asset into CODEINDEX_EMBED_DIR
+                               (or <repo>/.codeindex/models/); sha256-verified. Override
+                               the source with CODEINDEX_EMBED_URL
                 embed serve    Print (or --run) the docker command that starts the
                                containerized embedding server (rich tier)
   rules       Architecture rules (forbidden edges, cycles, orphans) validated
@@ -79,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)
@@ -102,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;
@@ -120,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 => {
@@ -143,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();
@@ -173,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,
   };
 }
 
@@ -387,30 +397,30 @@ export async function runCli(argv: string[]): Promise<void> {
       writeFileSync(join(flags.out, "embeddings.bin"), serializeEmbeddings(index));
       process.stderr.write(`codeindex: ${index.records.length} embedding records → ${flags.out}/embeddings.bin (model ${model.modelId})\n`);
     } else if (sub === "pull") {
-      const url = resolveEmbedPullUrl();
-      if (!url) {
-        // Clean, actionable failure — the official asset is not published yet.
-        process.stderr.write(
-          "codeindex: no model URL configured. The official static-embedding asset is not published yet.\n" +
-            "Set CODEINDEX_EMBED_URL to a model.json URL (optionally CODEINDEX_EMBED_DIR as the destination), then re-run `codeindex embed pull`.\n",
-        );
-        process.exitCode = 1;
-        return;
-      }
+      // Default: the official published asset + its pinned sha256. A user-set
+      // CODEINDEX_EMBED_URL overrides both (mirror/custom model, no verification).
+      const { url, sha256 } = resolveEmbedPullUrl();
       const destDir = process.env.CODEINDEX_EMBED_DIR ?? join(flags.repo, ".codeindex", "models");
       mkdirSync(destDir, { recursive: true });
       process.stderr.write(`codeindex: fetching model from ${url} → ${join(destDir, "model.json")}\n`);
-      const res = await fetch(url);
-      if (!res.ok) {
-        process.stderr.write(`codeindex: pull failed — HTTP ${res.status} from ${url}\n`);
+      let body: string;
+      try {
+        // Follows redirects (GitHub → CDN) and verifies sha256 for the default asset.
+        body = await fetchEmbedModel(url, sha256);
+      } catch (e) {
+        process.stderr.write(`codeindex: pull failed — ${e instanceof Error ? e.message : String(e)} (nothing written)\n`);
         process.exitCode = 1;
         return;
       }
-      const body = await res.text();
       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

@@ -55,7 +55,7 @@ export { buildModules, isTestFile, tierForPath } from "./modules.js";
 export type { ModuleInfo } from "./modules.js";
 export { buildGraph, uniqueSymbolDefs } from "./graph.js";
 export { resolveCallEdges } from "./calls.js";
-export { buildCallerIndex, enclosingSymbol, computeImportPairs } from "./callers.js";
+export { buildCallerIndex, buildRawCallerIndex, enclosingSymbol, computeImportPairs } from "./callers.js";
 export { symbolsOverview, findSymbol, findReferences } from "./query.js";
 export { resolveUniqueSymbol, replaceSymbolBody, insertAfterSymbol, insertBeforeSymbol } from "./edit.js";
 export type { EditResult } from "./edit.js";
@@ -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";
@@ -143,6 +143,10 @@ export type { ArchRule, ForbiddenEdgeRule, BuiltinRule, RuleSeverity, RuleViolat
 // Caller-index recall mode (issue #7) — options for buildCallerIndex above.
 export type { CallerIndexOptions } from "./callers.js";
 
+// Raw-recall caller index (issue #8) — ungated, def-resolution-free companion
+// to buildCallerIndex above; see its JSDoc in callers.ts for the contract.
+export type { RawCallerIndex, RawCallerSite } from "./callers.js";
+
 // Behavioral analytics (git-history mining) + the token-budgeted repo map.
 export { changeCoupling, rankHotspots } from "./coupling.js";
 export type { ChangeCoupling, CouplingOptions, Hotspot } from "./coupling.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/common.ts

@@ -75,11 +75,14 @@ const REEXPORT_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".m
 //
 // An ALIAS with no `from` clause (`export { b as c }`) renames an in-file
 // declaration — `localSymbols` (already extracted by the AST or regex tier)
-// lets us resolve `b` and mirror ITS kind onto `c` (e.g. "function"), so the
-// alias reads as the real symbol it is rather than the generic "reexport".
+// lets us resolve `b` and mirror ITS kind, declaration line, and endLine (AST
+// tier only) onto `c` (e.g. "function" at b's own line), so the alias reads
+// as the real symbol it is — citeable at its actual declaration — rather than
+// the generic "reexport" pinned to the export statement's line.
 // A true cross-module re-export (`export { b as c } from "./mod"`) has no
 // local `b` to resolve — and an alias the local pass genuinely can't see
-// (destructured/ambient/etc.) falls back the same way — both keep "reexport".
+// (destructured/ambient/etc.) falls back the same way — both keep "reexport"
+// and cite the export statement's own line, the only line they have.
 //
 // Shared by extractCode (extract/code.ts) AND the standalone extractSymbols
 // (lang/registry.ts) — ultradoc and other direct extractSymbols consumers hit
@@ -92,8 +95,11 @@ export function extractReexports(rel: string, content: string, localSymbols: Cod
   const out: CodeSymbol[] = [];
   const seen = new Set<string>();
   const lineAt = (idx: number): number => content.slice(0, idx).split(/\r?\n/).length;
-  const localKindOf = new Map<string, string>();
-  for (const s of localSymbols) if (!localKindOf.has(s.name)) localKindOf.set(s.name, s.kind);
+  // Keyed on the whole CodeSymbol (not just kind) so the alias branch below
+  // can also cite the resolved declaration's own line/endLine, not just mirror
+  // its kind.
+  const localDeclOf = new Map<string, CodeSymbol>();
+  for (const s of localSymbols) if (!localDeclOf.has(s.name)) localDeclOf.set(s.name, s);
 
   const named = /export\s*\{([\s\S]*?)\}\s*(?:from\s*['"]([^'"]+)['"])?\s*;?/g;
   let m: RegExpExecArray | null;
@@ -106,9 +112,14 @@ export function extractReexports(rel: string, content: string, localSymbols: Cod
       const name = as ? as[2]! : p;
       if (!/^[A-Za-z_$][\w$]*$/.test(name) || name === "default" || seen.has(name)) continue;
       seen.add(name);
-      const mirroredKind = !from ? localKindOf.get(orig) : undefined;
+      // A resolved decl means this is a same-file alias: cite ITS line (and
+      // endLine, when the AST tier populated one) rather than the export
+      // statement's — an unresolved alias or a `from`-clause re-export has no
+      // local declaration to point at, so it keeps lineAt(m.index) below.
+      const decl = !from ? localDeclOf.get(orig) : undefined;
       out.push({
-        name, kind: mirroredKind ?? "reexport", file: rel, line: lineAt(m.index),
+        name, kind: decl?.kind ?? "reexport", file: rel, line: decl ? decl.line : lineAt(m.index),
+        ...(decl?.endLine !== undefined ? { endLine: decl.endLine } : {}),
         signature: from ? `export { ${name} } from "${from}"` : `export { ${name} }`,
         exported: true, lang,
       });

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,12 +5,14 @@
 // `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";
 import { buildIndexArtifacts } from "./pipeline.js";
 import { renderGraphJson } from "./render/graph-json.js";
-import { scanRepo } from "./scan.js";
+import { scanRepo, type RepoScan } from "./scan.js";
 import { buildCallerIndex } from "./callers.js";
 import { detectWorkspaces } from "./workspaces.js";
 import { gitChurn } from "./git.js";
@@ -25,10 +27,11 @@ 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 { buildEmbeddingIndex } from "./embed/index.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";
+import { sha1 } from "./hash.js";
 
 interface RpcRequest {
   jsonrpc: "2.0";
@@ -270,7 +273,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 by default — 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`. Set `semantic: true` to RRF-fuse the deterministic static-embedding tier when a model asset is present (degrades to lexical otherwise — see embed_status).',
+      '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 by default — 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`. Set `semantic: true` to RRF-fuse an embedding tier (HTTP endpoint, else a local static model) with lexical — the response then wraps the ranked list as `{ results, tier, degradedReason? }`, `tier` being "endpoint"/"static" when fusion happened or "lexical" (with `degradedReason`) when it did not (see embed_status). Without `semantic`, the response is the bare ranked array, unchanged.',
     inputSchema: {
       type: "object",
       properties: {
@@ -286,7 +289,7 @@ const TOOLS = [
         semantic: {
           type: "boolean",
           description:
-            "RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. Degrades silently to lexical-only when neither is available/reachable — see embed_status.",
+            'RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. The response reports the effective tier as a top-level `tier` field ("endpoint"/"static" on success, "lexical" plus `degradedReason` when neither is available/reachable) instead of degrading silently — see embed_status.',
         },
       },
       required: ["repo", "query"],
@@ -320,6 +323,75 @@ function str(v: unknown): string | undefined {
 function strArray(v: unknown): string[] | undefined {
   return Array.isArray(v) && v.every((x) => typeof x === "string") && v.length ? (v as string[]) : undefined;
 }
+function errMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// --- embedding index memoization --------------------------------------------
+// The MCP server process is long-lived, but every `search` call used to redo
+// the FULL corpus embedding build — N `buildEndpointIndex` HTTP round-trips,
+// or a full `buildEmbeddingIndex` re-encode pass — even when nothing in the
+// repo changed between requests. Memoize the last build behind a fingerprint
+// of the scan contents plus the tier's identity, so an unchanged repo reuses
+// the cached index and any file add/edit/remove (or a switch of endpoint/model)
+// still rebuilds. RepoScan carries no fingerprint of its own (checked
+// scan.ts/types.ts) — every FileRecord already carries a content hash, so
+// hashing the (rel, hash) pairs is the staleness oracle scan.ts itself uses.
+export function scanFingerprint(scan: RepoScan): string {
+  return sha1(scan.files.map((f) => `${f.rel}:${f.hash}`).join("\n"));
+}
+
+export interface EmbeddingIndexCacheKey {
+  mode: "endpoint" | "static";
+  // Distinguishes cache entries across configs sharing the same scan: the
+  // endpoint URL, or the model dir + modelId for the static tier.
+  identity: string;
+  scan: RepoScan;
+}
+
+// A SINGLE entry — never an unbounded map — holding the most recent build.
+let embeddingIndexCache: { key: string; index: EmbeddingIndex } | undefined;
+
+// Reuse the cached index when (mode, identity, scanFingerprint) matches the
+// last build; otherwise call `build` and cache its result. A failed build is
+// NEVER cached (matches today's per-call error behavior: the next request
+// retries from scratch, and a still-valid previous entry — under a different
+// key — is left untouched).
+export async function memoizedEmbeddingIndex(
+  key: EmbeddingIndexCacheKey,
+  build: () => Promise<EmbeddingIndex> | EmbeddingIndex,
+): Promise<EmbeddingIndex> {
+  const cacheKey = `${key.mode}:${key.identity}:${scanFingerprint(key.scan)}`;
+  if (embeddingIndexCache && embeddingIndexCache.key === cacheKey) return embeddingIndexCache.index;
+  const index = await build();
+  embeddingIndexCache = { key: cacheKey, index };
+  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);
@@ -459,31 +531,55 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<st
     const limit = typeof args.limit === "number" ? args.limit : undefined;
     const fuzzy = typeof args.fuzzy === "boolean" ? args.fuzzy : undefined;
     if (args.semantic === true) {
+      // semantic:true changes the response SHAPE (wraps the ranked list with a
+      // `tier`/`degradedReason?`) so a caller can tell "fusion happened" apart
+      // from "degraded to lexical" — see the `search` tool description. This
+      // branch is the ONLY place that shape appears; plain lexical search below
+      // stays the bare array, byte-compat for existing consumers.
       const endpoint = resolveEmbedEndpoint();
       if (endpoint) {
         // Rich tier — endpoint takes PRECEDENCE over a local static model. An
-        // unreachable/malformed endpoint degrades to lexical (no throw).
+        // unreachable/malformed endpoint degrades to lexical, now with a reason.
+        // The corpus index is memoized per (endpoint, scan state) — the query
+        // itself is always re-encoded fresh (it differs per call).
         try {
-          const index = await buildEndpointIndex(scan);
+          const index = await memoizedEmbeddingIndex({ mode: "endpoint", identity: endpoint, scan }, () => buildEndpointIndex(scan));
           const queryVec = await encodeQueryViaEndpoint(query);
-          return JSON.stringify(searchSemantic(scan, query, index, { queryVec, limit, fuzzy }), null, 2);
-        } catch {
-          return JSON.stringify(searchIndex(scan, query, { limit, fuzzy }), null, 2);
+          const results = searchSemantic(scan, query, index, { queryVec, limit, fuzzy });
+          return JSON.stringify({ results, tier: "endpoint" }, null, 2);
+        } catch (e) {
+          const results = searchIndex(scan, query, { limit, fuzzy });
+          return JSON.stringify(
+            { results, tier: "lexical", degradedReason: `embedding endpoint failed: ${errMessage(e)}` },
+            null,
+            2,
+          );
         }
       }
       const modelDir = resolveEmbedModelDir(repo);
-      const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+      const model = modelDir ? memoizedEmbedModel(modelDir) : undefined;
       if (model) {
-        const index = buildEmbeddingIndex(scan, model);
-        return JSON.stringify(searchSemantic(scan, query, index, { model, limit, fuzzy }), null, 2);
+        const index = await memoizedEmbeddingIndex(
+          { mode: "static", identity: `${modelDir}#${model.modelId}`, scan },
+          () => buildEmbeddingIndex(scan, model),
+        );
+        const results = searchSemantic(scan, query, index, { model, limit, fuzzy });
+        return JSON.stringify({ results, tier: "static" }, null, 2);
       }
-      // Degrade to lexical (opt-in tier not activated) — no throw.
+      // Opt-in tier not activated (no endpoint, no model asset) — degrade to
+      // lexical with a reason instead of failing silently.
+      const results = searchIndex(scan, query, { limit, fuzzy });
+      return JSON.stringify(
+        { results, tier: "lexical", degradedReason: "no embedding endpoint or static model configured — see embed_status" },
+        null,
+        2,
+      );
     }
     return JSON.stringify(searchIndex(scan, query, { limit, fuzzy }), null, 2);
   }
   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;