smart-context-mcp 1.16.5 → 1.18.0

package/README.md

@@ -56,7 +56,7 @@ Restart your AI client. Done.
 # Check installed version
 npm list -g smart-context-mcp
 
-# Should show: smart-context-mcp@1.16.5 (or later)
+# Should show: smart-context-mcp@1.18.0 (or later)
 
 # Update to latest version
 npm update -g smart-context-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-context-mcp",
   "mcpName": "io.github.Arrayo/smart-context-mcp",
-  "version": "1.16.5",
+  "version": "1.18.0",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Arrayo/smart-context-mcp",
     "source": "github"
   },
-  "version": "1.16.5",
+  "version": "1.18.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-context-mcp",
-      "version": "1.16.5",
+      "version": "1.18.0",
       "transport": {
         "type": "stdio"
       },

package/src/client-contract.js

@@ -52,8 +52,11 @@ export const buildRecommendedPathLines = (
     lines.push(`${nextToolsLabel}: ${recommendedPath.nextTools.slice(0, 3).join(' -> ')}`);
   }
 
-  if (includePath && recommendedPath.steps?.[0]?.instruction) {
-    lines.push(`${pathLabel}: ${truncate(recommendedPath.steps[0].instruction, maxLength)}`);
+  if (includePath) {
+    const pathInstruction = recommendedPath.steps?.[0]?.instruction ?? recommendedPath.next ?? null;
+    if (pathInstruction) {
+      lines.push(`${pathLabel}: ${truncate(pathInstruction, maxLength)}`);
+    }
   }
 
   return lines;

package/src/explain/explainer.js

@@ -0,0 +1,234 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { loadIndex, queryIndex, queryRelated } from '../index.js';
+import { projectRoot } from '../utils/paths.js';
+import { getExplainCache, setExplainCache } from '../storage/sqlite.js';
+import { countTokens } from '../tokenCounter.js';
+
+const SIDE_EFFECT_PATTERNS = [
+  { kind: 'io', re: /\b(fs|fsPromises)\.(read|write|append|unlink|mkdir|rm|stat|exists|copy|rename)/ },
+  { kind: 'io', re: /\b(readFileSync|writeFileSync|appendFileSync|unlinkSync|mkdirSync|rmSync|statSync)\b/ },
+  { kind: 'network', re: /\b(fetch|axios|http\.request|https\.request|XMLHttpRequest|WebSocket)\b/ },
+  { kind: 'process', re: /\b(process\.(env|exit|kill|chdir)|child_process|execSync|spawnSync|execFile|spawn)\b/ },
+  { kind: 'logging', re: /\bconsole\.(log|info|warn|error|debug)\b/ },
+  { kind: 'mutation', re: /\b(this\.\w+\s*=|let\s+\w+\s*=|\w+\.push\(|\w+\.splice\(|delete\s+\w+\[)/ },
+  { kind: 'throws', re: /\bthrow\s+(new\s+)?\w+/ },
+  { kind: 'async', re: /\b(await|Promise\.(all|race|any|allSettled)|setTimeout|setInterval|setImmediate)\b/ },
+  { kind: 'db', re: /\b(prepare|execute|query|transaction|raw|knex|pgp)\(/ },
+];
+
+const COMMENT_LINE_RE = /^\s*(?:\/\/|#|\*|\/\*\*|\/\*|"""|''')/;
+const STRIPPED_COMMENT_RE = /^\s*(?:\/\/+|#+|\*+\/?|\/\*\*?|"""|''')\s?/;
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+
+const stripCommentMarkers = (line) =>
+  line.replace(STRIPPED_COMMENT_RE, '').replace(/\*\/\s*$/, '').trim();
+
+export const extractDocstring = (lines, signatureLineIndex) => {
+  if (signatureLineIndex <= 0) return '';
+  const docLines = [];
+  for (let i = signatureLineIndex - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (line == null) break;
+    if (line.trim() === '') {
+      if (docLines.length === 0) continue;
+      break;
+    }
+    if (!COMMENT_LINE_RE.test(line)) break;
+    docLines.unshift(stripCommentMarkers(line));
+  }
+  return docLines.join(' ').replace(/\s+/g, ' ').trim().slice(0, 280);
+};
+
+export const extractFirstBodyLine = (lines, signatureLineIndex) => {
+  for (let i = signatureLineIndex + 1; i < lines.length && i < signatureLineIndex + 12; i += 1) {
+    const line = lines[i];
+    if (line == null) continue;
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed === '{' || COMMENT_LINE_RE.test(trimmed)) continue;
+    return trimmed.slice(0, 160);
+  }
+  return '';
+};
+
+export const detectSideEffects = (block) => {
+  const found = new Set();
+  for (const { kind, re } of SIDE_EFFECT_PATTERNS) {
+    if (re.test(block)) found.add(kind);
+  }
+  return [...found];
+};
+
+const extractBlock = (lines, startLine, maxLines = 80) => {
+  const startIdx = Math.max(0, (startLine ?? 1) - 1);
+  const endIdx = Math.min(lines.length, startIdx + maxLines);
+  return {
+    block: lines.slice(startIdx, endIdx).join('\n'),
+    startIdx,
+    endIdx,
+  };
+};
+
+const countCallers = (index, relPath, symbol) => {
+  if (!index) return 0;
+  const hits = queryIndex(index, symbol);
+  const related = queryRelated(index, relPath);
+  const callerFiles = new Set(related.importedBy);
+  const externalHits = hits.filter((h) => h.path !== relPath).length;
+  return callerFiles.size + externalHits;
+};
+
+const lookupSymbolMeta = (index, relPath, symbol) => {
+  if (!index) return null;
+  const hits = queryIndex(index, symbol);
+  const local = hits.find((h) => h.path === relPath);
+  return local ?? hits[0] ?? null;
+};
+
+export const buildStructuralExplanation = ({
+  fullPath,
+  content,
+  symbol,
+  root = projectRoot,
+  index = null,
+}) => {
+  const lines = content.split('\n');
+  const relPath = path.relative(root, fullPath).replace(/\\/g, '/');
+  const resolvedIndex = index ?? loadIndex(root);
+  const meta = lookupSymbolMeta(resolvedIndex, relPath, symbol);
+
+  if (!meta) {
+    return null;
+  }
+
+  const { block, startIdx } = extractBlock(lines, meta.line, 80);
+  const signature = meta.signature ?? lines[startIdx]?.trim() ?? '';
+  const docstring = extractDocstring(lines, startIdx);
+  const firstBodyLine = extractFirstBodyLine(lines, startIdx);
+  const sideEffects = detectSideEffects(block);
+  const callers = countCallers(resolvedIndex, relPath, symbol);
+  const contentHash = sha256(block);
+
+  return {
+    symbol,
+    file: relPath,
+    line: meta.line,
+    kind: meta.kind ?? null,
+    parent: meta.parent ?? null,
+    signature: signature.slice(0, 200),
+    docstring,
+    firstBodyLine,
+    sideEffects,
+    callers,
+    contentHash,
+  };
+};
+
+const formatExplanationText = (explanation) => {
+  const lines = [
+    `${explanation.symbol} (${explanation.kind ?? 'symbol'}) — ${explanation.file}:${explanation.line}`,
+    `signature: ${explanation.signature || '<unknown>'}`,
+  ];
+  if (explanation.parent) lines.push(`parent: ${explanation.parent}`);
+  if (explanation.docstring) lines.push(`docs: ${explanation.docstring}`);
+  if (explanation.firstBodyLine) lines.push(`first body: ${explanation.firstBodyLine}`);
+  if (explanation.sideEffects.length > 0) lines.push(`side effects: ${explanation.sideEffects.join(', ')}`);
+  lines.push(`callers: ${explanation.callers}`);
+  return lines.join('\n');
+};
+
+export const explainSymbol = async ({
+  fullPath,
+  content,
+  symbol,
+  root = projectRoot,
+  index = null,
+  useCache = true,
+}) => {
+  const relPath = path.relative(root, fullPath).replace(/\\/g, '/');
+  const partial = buildStructuralExplanation({ fullPath, content, symbol, root, index });
+
+  if (!partial) {
+    return {
+      symbol,
+      file: relPath,
+      found: false,
+      text: `Symbol not found in index or content: ${symbol}`,
+      cached: false,
+      provider: 'structural',
+    };
+  }
+
+  if (useCache) {
+    try {
+      const cached = await getExplainCache({
+        relPath,
+        symbol,
+        contentHash: partial.contentHash,
+      });
+      if (cached?.explanation) {
+        const text = formatExplanationText(cached.explanation);
+        return {
+          ...cached.explanation,
+          found: true,
+          text,
+          cached: true,
+          provider: cached.provider,
+        };
+      }
+    } catch {
+      // cache unavailable — fall through and recompute
+    }
+  }
+
+  const text = formatExplanationText(partial);
+  const tokens = countTokens(text);
+
+  if (useCache) {
+    try {
+      await setExplainCache({
+        relPath,
+        symbol,
+        contentHash: partial.contentHash,
+        explanation: partial,
+        provider: 'structural',
+        tokens,
+      });
+    } catch {
+      // best-effort cache write
+    }
+  }
+
+  return {
+    ...partial,
+    found: true,
+    text,
+    cached: false,
+    provider: 'structural',
+  };
+};
+
+export const explainSymbols = async ({ fullPath, content, symbols, root = projectRoot, index = null, useCache = true }) => {
+  const list = Array.isArray(symbols) ? symbols : [symbols];
+  const results = [];
+  for (const sym of list) {
+    if (!sym) continue;
+    results.push(await explainSymbol({ fullPath, content, symbol: sym, root, index, useCache }));
+  }
+  return results;
+};
+
+export const formatExplanationsAsText = (results) =>
+  results.map((r) => r.text).join('\n\n');
+
+const fileExists = (p) => {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+};
+
+export const __internal = { fileExists, formatExplanationText };

package/src/graph-paths.js

@@ -0,0 +1,174 @@
+import path from 'node:path';
+import { queryIndex, queryRelated } from './index.js';
+
+const DEFAULT_MAX_HOPS = 5;
+const NEAREST_LIMIT = 3;
+
+const buildAdjacency = (index, { directed = false } = {}) => {
+  const adj = new Map();
+  const ensure = (key) => {
+    if (!adj.has(key)) adj.set(key, new Set());
+    return adj.get(key);
+  };
+  for (const edge of index?.graph?.edges ?? []) {
+    if (!edge?.from || !edge?.to) continue;
+    if (edge.kind && edge.kind !== 'import' && edge.kind !== 'testOf') continue;
+    ensure(edge.from).add(edge.to);
+    if (!directed) ensure(edge.to).add(edge.from);
+  }
+  return adj;
+};
+
+export const resolveEntityToFiles = (index, entity) => {
+  if (!entity || typeof entity !== 'string') return [];
+  const normalized = entity.replace(/\\/g, '/').trim();
+
+  if (normalized.includes('/') || /\.[a-zA-Z0-9]+$/.test(normalized)) {
+    if (index?.files?.[normalized]) return [normalized];
+    const filesMap = index?.files ?? {};
+    const matches = Object.keys(filesMap).filter((rel) => rel.endsWith(`/${normalized}`) || rel === normalized);
+    return matches;
+  }
+
+  const hits = queryIndex(index, normalized);
+  return [...new Set(hits.map((h) => h.path))];
+};
+
+const reconstructPath = (parents, target) => {
+  const path = [target];
+  let cursor = target;
+  while (parents.has(cursor)) {
+    const prev = parents.get(cursor);
+    if (prev === null) break;
+    path.unshift(prev);
+    cursor = prev;
+  }
+  return path;
+};
+
+export const findPath = (index, fromFile, toFile, { maxHops = DEFAULT_MAX_HOPS, directed = false } = {}) => {
+  if (!index?.graph?.edges) return null;
+  if (!fromFile || !toFile) return null;
+  if (fromFile === toFile) return { hops: 0, path: [fromFile] };
+
+  const adj = buildAdjacency(index, { directed });
+  if (!adj.has(fromFile) && !adj.has(toFile)) return null;
+
+  const visited = new Map();
+  visited.set(fromFile, 0);
+  const parents = new Map([[fromFile, null]]);
+  const queue = [fromFile];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const depth = visited.get(current);
+    if (depth >= maxHops) continue;
+
+    const neighbors = adj.get(current) ?? new Set();
+    for (const next of neighbors) {
+      if (visited.has(next)) continue;
+      visited.set(next, depth + 1);
+      parents.set(next, current);
+      if (next === toFile) {
+        return { hops: depth + 1, path: reconstructPath(parents, toFile) };
+      }
+      queue.push(next);
+    }
+  }
+
+  return null;
+};
+
+const collectNearestNeighbors = (index, file, limit = NEAREST_LIMIT) => {
+  const result = new Map();
+  if (!file || !index) return [];
+
+  const related = queryRelated(index, file);
+  for (const rel of [...related.imports, ...related.importedBy, ...related.tests, ...related.neighbors]) {
+    if (rel === file) continue;
+    if (!result.has(rel)) result.set(rel, result.size);
+    if (result.size >= limit) break;
+  }
+  return [...result.keys()];
+};
+
+export const findNearest = (index, fromFile, toFile, limit = NEAREST_LIMIT) => ({
+  fromNeighbors: collectNearestNeighbors(index, fromFile, limit),
+  toNeighbors: collectNearestNeighbors(index, toFile, limit),
+});
+
+const symbolForPathStep = (index, relPath, symbolName) => {
+  const filesMap = index?.files ?? {};
+  const entry = filesMap[relPath];
+  if (!entry?.symbols) return null;
+  if (symbolName) {
+    return entry.symbols.find((s) => s.name?.toLowerCase() === symbolName.toLowerCase()) ?? null;
+  }
+  return entry.symbols.find((s) => s.kind === 'function' || s.kind === 'class' || s.kind === 'const')
+    ?? entry.symbols[0]
+    ?? null;
+};
+
+export const describePath = (index, pathFiles, { hintSymbols = {} } = {}) => {
+  if (!Array.isArray(pathFiles) || pathFiles.length === 0) return [];
+  return pathFiles.map((rel) => {
+    const sym = symbolForPathStep(index, rel, hintSymbols[rel]);
+    return {
+      file: rel,
+      symbol: sym?.name ?? null,
+      signature: sym?.signature ?? null,
+      line: sym?.line ?? null,
+      kind: sym?.kind ?? null,
+    };
+  });
+};
+
+export const buildPathsResult = (index, from, to, options = {}) => {
+  const fromFiles = resolveEntityToFiles(index, from);
+  const toFiles = resolveEntityToFiles(index, to);
+
+  if (fromFiles.length === 0 || toFiles.length === 0) {
+    return {
+      from,
+      to,
+      resolved: { from: fromFiles, to: toFiles },
+      found: false,
+      reason: fromFiles.length === 0 ? 'from-not-found' : 'to-not-found',
+      path: [],
+      hops: null,
+      fallback: null,
+    };
+  }
+
+  for (const f of fromFiles) {
+    for (const t of toFiles) {
+      const result = findPath(index, f, t, options);
+      if (result) {
+        return {
+          from,
+          to,
+          resolved: { from: [f], to: [t] },
+          found: true,
+          hops: result.hops,
+          path: describePath(index, result.path),
+          fallback: null,
+        };
+      }
+    }
+  }
+
+  const seedFrom = fromFiles[0];
+  const seedTo = toFiles[0];
+  const fallback = findNearest(index, seedFrom, seedTo, options.nearestLimit ?? NEAREST_LIMIT);
+
+  return {
+    from,
+    to,
+    resolved: { from: [seedFrom], to: [seedTo] },
+    found: false,
+    reason: 'no-path',
+    path: [],
+    hops: null,
+    fallback,
+  };
+};

package/src/index-manager.js

@@ -128,3 +128,24 @@ export const getIndexStatus = (root = projectRoot) => {
     age: meta?.builtAt ? Date.now() - meta.builtAt : null
   };
 };
+
+let backgroundBuildPromise = null;
+
+export const triggerBackgroundIndexBuild = ({ root = projectRoot, timeoutMs = INDEX_BUILD_TIMEOUT_MS } = {}) => {
+  if (backgroundBuildPromise) {
+    return backgroundBuildPromise;
+  }
+
+  const status = getIndexStatus(root);
+  if (status.available && status.fresh) {
+    return Promise.resolve({ status: 'fresh', cached: true });
+  }
+
+  backgroundBuildPromise = ensureIndexReady({ root, timeoutMs })
+    .catch((error) => ({ status: 'error', error: error?.message ?? String(error) }))
+    .finally(() => {
+      backgroundBuildPromise = null;
+    });
+
+  return backgroundBuildPromise;
+};

package/src/index.js

@@ -5,7 +5,7 @@ import ts from 'typescript';
 import { isBinaryBuffer } from './utils/fs.js';
 import { IGNORED_DIRS } from './config/ignored-paths.js';
 
-const INDEX_VERSION = 4;
+const INDEX_VERSION = 6;
 
 const MAX_SIGNATURE_LEN = 200;
 const MAX_SNIPPET_LEN = 280;
@@ -60,8 +60,15 @@ const indexableExtensions = new Set([
   '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
   '.py', '.go', '.rs', '.java',
   '.cs', '.kt', '.php', '.swift',
+  '.md', '.markdown',
 ]);
 
+const isIndexableMarkdownFile = (fullPath) => {
+  const ext = path.extname(fullPath).toLowerCase();
+  if (ext !== '.md' && ext !== '.markdown') return false;
+  return isAdrPath(fullPath);
+};
+
 const ignoredDirs = new Set(IGNORED_DIRS);
 
 const scriptKindByExtension = {
@@ -564,6 +571,105 @@ const extractSwiftImports = (content) => {
   return { imports, exports: [] };
 };
 
+// ---------------------------------------------------------------------------
+// ADR / Spec / Architecture markdown parser
+// ---------------------------------------------------------------------------
+
+const ADR_PATH_RE = /(?:^|\/)(?:adrs?|decisions|architecture|design-docs)\//i;
+const ADR_FILENAME_RE = /^(?:adr[-_]?\d{0,4}.*|\d{3,4}[-_].*|SPEC|ARCHITECTURE|DESIGN|RFC[-_]?\d*.*)\.(?:md|markdown)$/i;
+const ADR_STATUS_RE = /^\s*[*_>-]{0,3}\s*status\s*[*_]{0,2}\s*[:=]?\s*[*_]{0,2}\s*([A-Za-z][A-Za-z -]+)/i;
+const MARKDOWN_HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
+const ADR_VALID_STATUS = new Set([
+  'proposed', 'draft', 'rejected', 'accepted', 'deprecated',
+  'superseded', 'amended', 'approved', 'in review', 'in-review',
+]);
+
+export const isAdrPath = (relPath) => {
+  if (!relPath) return false;
+  const norm = relPath.replace(/\\/g, '/');
+  if (ADR_PATH_RE.test(norm)) return true;
+  const base = path.basename(norm);
+  return ADR_FILENAME_RE.test(base);
+};
+
+const slugify = (text) => text.trim()
+  .toLowerCase()
+  .replace(/[^\w\s-]/g, '')
+  .replace(/\s+/g, '-')
+  .replace(/-+/g, '-')
+  .replace(/^-|-$/g, '')
+  .slice(0, 60);
+
+const extractAdrStatus = (lines, headingLine) => {
+  const start = Math.max(0, headingLine - 1);
+  const end = Math.min(lines.length, start + 20);
+  for (let i = start; i < end; i += 1) {
+    const m = ADR_STATUS_RE.exec(lines[i]);
+    if (!m) continue;
+    const value = m[1].trim().toLowerCase().replace(/\s+/g, '-');
+    if (ADR_VALID_STATUS.has(value) || ADR_VALID_STATUS.has(value.replace('-', ' '))) {
+      return value;
+    }
+  }
+  return null;
+};
+
+export const extractAdrSymbols = (content, fullPath) => {
+  const symbols = [];
+  const lines = content.split('\n');
+  let titleSet = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const headingMatch = MARKDOWN_HEADING_RE.exec(lines[i]);
+    if (!headingMatch) continue;
+
+    const level = headingMatch[1].length;
+    const titleText = headingMatch[2].trim();
+    if (!titleText) continue;
+
+    if (!titleSet && level === 1) {
+      const name = slugify(titleText) || `adr-${path.basename(fullPath).toLowerCase()}`;
+      const status = extractAdrStatus(lines, i + 1);
+      const signature = `# ${titleText}${status ? ` (status: ${status})` : ''}`;
+      symbols.push({
+        name,
+        kind: 'adr',
+        line: i + 1,
+        signature: trimSignature(signature),
+        snippet: trimSnippet(titleText),
+        ...(status ? { status } : {}),
+        title: titleText,
+      });
+      titleSet = true;
+      continue;
+    }
+
+    if (level === 2 || level === 3) {
+      const sectionSlug = slugify(titleText);
+      if (!sectionSlug) continue;
+      symbols.push({
+        name: sectionSlug,
+        kind: 'adr-section',
+        line: i + 1,
+        signature: trimSignature(`${headingMatch[1]} ${titleText}`),
+      });
+    }
+  }
+
+  if (!titleSet) {
+    const base = path.basename(fullPath).replace(/\.[^.]+$/, '');
+    symbols.unshift({
+      name: slugify(base) || 'adr',
+      kind: 'adr',
+      line: 1,
+      signature: trimSignature(`# ${base}`),
+      title: base,
+    });
+  }
+
+  return symbols;
+};
+
 // ---------------------------------------------------------------------------
 // Unified file info extraction
 // ---------------------------------------------------------------------------
@@ -591,6 +697,7 @@ const extractFileInfo = (fullPath, content) => {
   else if (ext === '.kt') info = { symbols: extractKotlinSymbols(content), ...extractKotlinImports(content) };
   else if (ext === '.php') info = { symbols: extractPhpSymbols(content), ...extractPhpImports(content) };
   else if (ext === '.swift') info = { symbols: extractSwiftSymbols(content), ...extractSwiftImports(content) };
+  else if ((ext === '.md' || ext === '.markdown') && isAdrPath(fullPath)) info = { symbols: extractAdrSymbols(content, fullPath), imports: [], exports: [] };
   else info = { symbols: [], imports: [], exports: [] };
 
   return {
@@ -672,7 +779,10 @@ const walkForIndex = (dir, files = []) => {
 
     if (entry.isDirectory()) {
       walkForIndex(fullPath, files);
-    } else if (indexableExtensions.has(path.extname(entry.name).toLowerCase())) {
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!indexableExtensions.has(ext)) continue;
+      if ((ext === '.md' || ext === '.markdown') && !isIndexableMarkdownFile(fullPath)) continue;
       files.push(fullPath);
     }
   }
@@ -722,8 +832,6 @@ export const buildIndex = (root, progress = null) => {
         if (!invertedIndex[key]) invertedIndex[key] = [];
         const entry = { path: relPath, line: sym.line, kind: sym.kind };
         if (sym.parent) entry.parent = sym.parent;
-        if (sym.signature) entry.signature = sym.signature;
-        if (sym.snippet) entry.snippet = sym.snippet;
         invertedIndex[key].push(entry);
       }
     } catch { /* unreadable */ }
@@ -783,10 +891,24 @@ export const buildIndex = (root, progress = null) => {
 // Query helpers
 // ---------------------------------------------------------------------------
 
+const findSymbolForHit = (index, key, hit) => {
+  const symbols = index.files?.[hit.path]?.symbols;
+  if (!Array.isArray(symbols)) return null;
+  return symbols.find((sym) => sym.name?.toLowerCase() === key && sym.line === hit.line) ?? null;
+};
+
 export const queryIndex = (index, symbolName) => {
   if (!index?.invertedIndex) return [];
   const key = symbolName.toLowerCase();
-  return index.invertedIndex[key] ?? [];
+  const hits = index.invertedIndex[key] ?? [];
+  return hits.map((hit) => {
+    const sym = findSymbolForHit(index, key, hit);
+    if (!sym) return hit;
+    const enriched = { ...hit };
+    if (sym.signature && !enriched.signature) enriched.signature = sym.signature;
+    if (sym.snippet && !enriched.snippet) enriched.snippet = sym.snippet;
+    return enriched;
+  });
 };
 
 export const queryRelated = (index, relPath) => {
@@ -873,8 +995,6 @@ export const reindexFile = (index, root, relPath) => {
       if (!index.invertedIndex[key]) index.invertedIndex[key] = [];
       const invEntry = { path: relPath, line: sym.line, kind: sym.kind };
       if (sym.parent) invEntry.parent = sym.parent;
-      if (sym.signature) invEntry.signature = sym.signature;
-      if (sym.snippet) invEntry.snippet = sym.snippet;
       index.invertedIndex[key].push(invEntry);
     }