token-goat 2.8.3 → 2.8.6

package/dist/{token-goat-chunk-TX4JFJTD.mjs → token-goat-chunk-XAWIELXH.mjs}

@@ -23,9 +23,11 @@ import {
   extractPdfMeta,
   extractPdfOutline,
   extractPdfText,
+  fenceUntrusted,
   fenceUntrustedContent,
   formatCsvProfile,
   formatCsvTable,
+  getEmbeddingCoverage,
   getFileEntry,
   indexFileSync,
   isAvailable,
@@ -39,6 +41,7 @@ import {
   locatePdfPages,
   mergeNearbyHits,
   ocrImage,
+  ocrIntegrityFailed,
   parseWhereSpecs,
   pathEqClause,
   probeImageMeta,
@@ -48,13 +51,14 @@ import {
   queryRefs,
   queryRefsByContext,
   querySymbols,
-  scanForInjectionPatterns,
+  scanAndRecord,
   searchEvidenceSemantically,
   searchSemantic,
   searchSymbolsFts,
   shrinkImage,
   storeBlob,
   stripLeadingAttributes,
+  stripTomlComment,
   tomlBracketDelta,
   trimToBudget,
   unzipBounded,
@@ -62,7 +66,7 @@ import {
   walkProject,
   yamlLineClosesQuote,
   yamlOpenQuoteAfter
-} from "./token-goat-chunk-PWVXXPCC.mjs";
+} from "./token-goat-chunk-DK4VLLYB.mjs";
 import {
   Database,
   PER_FILE_COUNTERFACTUAL_CEILING,
@@ -82,6 +86,7 @@ import {
   excludeTestsHiddenNote,
   extractErrorMessage,
   fileIsAbsent,
+  filtersFilteredToEmptyNotice,
   findHtmlHeadingMatches,
   findProject,
   fingerprintContent,
@@ -107,6 +112,7 @@ import {
   resolveIndexPath,
   resolveProjectRoot,
   runGit,
+  savedTokensFromBytes,
   shortFingerprint,
   stripAnsi,
   stripBom,
@@ -114,7 +120,7 @@ import {
   unsupportedLanguageName,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-6ODZ6PZK.mjs";
+} from "./token-goat-chunk-2JZ66BBE.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-AO2QD2AG.mjs";
@@ -198,18 +204,19 @@ function findTableHeaders(lines, isToml) {
       const restStart = closeIdx + openDelim.length;
       const m2 = TABLE_HEADER_RE.exec(line.slice(restStart));
       if (m2 !== null && m2[1] !== void 0) headers.push({ heading: m2[1].trim(), level: 1, index: i });
-      openDelim = lineOpenDelimiterAfter(line, restStart);
+      openDelim = lineOpenDelimiterAfter(stripTomlComment(line.slice(restStart)), 0);
       continue;
     }
     if (isToml && arrayDepth > 0) {
-      arrayDepth = Math.max(0, arrayDepth + tomlBracketDelta(line));
+      arrayDepth = Math.max(0, arrayDepth + tomlBracketDelta(stripTomlComment(line)));
       continue;
     }
     const m = TABLE_HEADER_RE.exec(line);
     if (m !== null && m[1] !== void 0) headers.push({ heading: m[1].trim(), level: 1, index: i });
     if (isToml) {
-      openDelim = lineOpenDelimiterAfter(line, 0);
-      if (openDelim === null) arrayDepth = Math.max(0, tomlBracketDelta(line));
+      const code = stripTomlComment(line);
+      openDelim = lineOpenDelimiterAfter(code, 0);
+      if (openDelim === null) arrayDepth = Math.max(0, tomlBracketDelta(code));
     }
   }
   return headers;
@@ -255,10 +262,11 @@ function findKeyValueHeaders(lines, language) {
       if (closed) openQuote = null;
       continue;
     }
-    const m = (isEnv ? ENV_KEYVALUE_HEADER_RE : KEYVALUE_HEADER_RE).exec(line);
+    const scanned = isEnv ? line.replace(/^[ \t]+/, "") : line;
+    const m = (isEnv ? ENV_KEYVALUE_HEADER_RE : KEYVALUE_HEADER_RE).exec(scanned);
     if (m === null || m[1] === void 0) continue;
     headers.push({ heading: m[1], level: 1, index: i });
-    openQuote = isEnv ? _detectOpenQuote(line.slice(m[0].length)) : yamlOpenQuoteAfter(line, m[0].length);
+    openQuote = isEnv ? _detectOpenQuote(scanned.slice(m[0].length)) : yamlOpenQuoteAfter(line, m[0].length);
   }
   return headers;
 }
@@ -5347,15 +5355,12 @@ function guardText(text, command) {
   const cfg = loadConfig();
   return cfg.overflow_guard.enabled ? trimToBudget(text, cfg.overflow_guard.max_tokens, command) : text;
 }
-function fenceGithubTextIfMatched(text) {
-  let matches = [];
-  try {
-    if (loadConfig().injection.enabled) matches = scanForInjectionPatterns(text);
-  } catch {
-    matches = [];
-  }
+function fenceGithubText(text) {
+  return fenceUntrusted(text, UNTRUSTED_GITHUB_TAG);
+}
+function fenceGithubFieldIfMatched(text) {
+  const matches = scanAndRecord(text);
   if (matches.length === 0) return text;
-  recordStat("injection_detected", 0, 0, void 0, matches.join(","));
   return fenceUntrustedContent(text, matches, UNTRUSTED_GITHUB_TAG);
 }
 function guardJsonRows(items) {
@@ -5376,7 +5381,7 @@ function sumFileSizes(filePaths) {
 function recordReadStat(kind, fullSourceBytes, emittedText, detail) {
   const emittedBytes = Buffer.byteLength(emittedText, "utf8");
   const bytesSaved = Math.max(1, fullSourceBytes - emittedBytes);
-  recordStat(kind, bytesSaved, Math.round(bytesSaved / 4), void 0, detail);
+  recordStat(kind, bytesSaved, savedTokensFromBytes(bytesSaved), void 0, detail);
 }
 function findSpecSeparator(spec) {
   return spec.lastIndexOf("::");
@@ -5659,10 +5664,21 @@ function runSymbol(opts) {
     if (opts.name !== void 0 && emptyIndexRoot !== null) {
       const rootDir = emptyIndexRoot;
       const rawSymbols = querySymbols({ limit: FIND_SCAN_LIMIT, rootDir });
-      const candidates = rankSimilarNames(rawSymbols.map((s) => s.name), opts.name);
-      text2 += candidates.length > 0 ? `
+      const exactMatches = rawSymbols.filter((s) => s.name === opts.name);
+      if (exactMatches.length > 0) {
+        const shown = exactMatches.slice(0, DIDYOUMEAN_LIMIT);
+        const where = shown.map((s) => `${s.kind} at ${toDisplayPath(rootDir, s.filePath)}:${s.lineStart}`).join("; ");
+        const more = exactMatches.length > shown.length ? ` (+${exactMatches.length - shown.length} more)` : "";
+        const flags = [opts.kind !== void 0 ? "--kind" : null, opts.file !== void 0 ? "--file" : null].filter((f) => f !== null);
+        const widen = flags.length > 0 ? `drop ${flags.join("/")} to see it` : "widen the search scope to see it";
+        text2 += `
+'${opts.name}' IS indexed (${where}${more}) -- ${widen}`;
+      } else {
+        const candidates = rankSimilarNames(rawSymbols.map((s) => s.name), opts.name);
+        text2 += candidates.length > 0 ? `
 ${didYouMean(candidates)}` : indexEmpty ? "" : `
 Try: token-goat semantic "${opts.name}"`;
+      }
       const structuredFiles = [...new Set(rawSymbols.map((s) => s.filePath))].sort();
       const hit = findStructuredKeyPath(opts.name, structuredFiles);
       if (hit !== null) {
@@ -5936,9 +5952,11 @@ function resolveSymbolSpec(spec, forceRefresh, projectRoot) {
   let candidates = querySymbols({ name: lookupName, filePath: resolved, limit: 10 });
   if (candidates.length === 0) {
     const foldedFile = foldPath(file);
+    const baseName = file.slice(Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")) + 1);
     candidates = querySymbols({
       name: lookupName,
       limit: 50,
+      ...baseName !== "" ? { fileBaseName: baseName } : {},
       ...projectRoot !== void 0 ? { rootDir: projectRoot } : {}
     }).filter((s) => {
       const foldedFilePath = foldPath(s.filePath);
@@ -6072,6 +6090,12 @@ ${sub.text}`);
 function resolveAgainstProjectRoot(file, projectRoot) {
   return projectRoot !== void 0 && !path5.isAbsolute(file) ? path5.resolve(projectRoot, file) : file;
 }
+function literalHeadingExists(filePath, heading) {
+  const ordinalMatch = /^([^#\r\n]+)#(\d+)$/.exec(heading);
+  const base = (ordinalMatch?.[1] ?? heading).trim().toLowerCase();
+  if (base.length === 0) return false;
+  return listSections(filePath, readFileText).some((h) => h.trim().toLowerCase() === base);
+}
 function runSection(opts) {
   const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
   if (crossFilePairs !== null) return runSectionCrossFile(crossFilePairs, opts);
@@ -6082,7 +6106,7 @@ function runSection(opts) {
   const specFilePath = opts.spec.slice(0, colonIdx);
   const filePath = resolveAgainstProjectRoot(specFilePath, opts.projectRoot);
   const heading = opts.spec.slice(colonIdx + 2);
-  if (heading.includes(",")) {
+  if (heading.includes(",") && !literalHeadingExists(filePath, heading)) {
     const multiHeadings = heading.split(",").map((h) => h.trim()).filter((h) => h.length > 0);
     if (multiHeadings.length > 1) return runSectionMulti(specFilePath, filePath, multiHeadings, opts);
   }
@@ -6516,14 +6540,10 @@ function formatStatsSuffix(refCounts, sym) {
   return refCounts !== void 0 ? `  [${countNoun(refCounts.get(sym.name) ?? 0, "ref")}, ${hasRealDocstring(sym.docstring) ? "documented" : "undocumented"}]` : "";
 }
 function filteredToEmptyNotice(preFilterCount, minLines, grep) {
-  const plural = preFilterCount === 1 ? "symbol" : "symbols";
   const parts = [];
   if (minLines !== void 0) parts.push(`--min-lines ${minLines}`);
   if (grep !== void 0) parts.push(`--grep ${grep}`);
-  const cause = parts.length === 0 ? "the active filter" : parts.join(" + ");
-  const knob = parts.length > 1 ? "filters" : "filter";
-  const verb = preFilterCount === 1 ? "was" : "were";
-  return `  (all ${preFilterCount} indexed ${plural} ${verb} filtered out by ${cause}; the file is indexed -- widen or drop the ${knob} to see them)`;
+  return filtersFilteredToEmptyNotice(preFilterCount, parts, "indexed symbol", "indexed symbols", "the file is indexed");
 }
 function prepareSymbolListing(file, opts) {
   const resolved = resolveIndexPath(file, opts.projectRoot ?? process.cwd());
@@ -6632,6 +6652,12 @@ function runSkeleton(opts) {
   recordReadStat("stub_view", fullSourceBytes, text, opts.file);
   return { text, code: 0 };
 }
+var DOC_SUMMARY_MAX_CHARS = 140;
+function clipDocSummary(firstLine) {
+  if (firstLine.length <= DOC_SUMMARY_MAX_CHARS) return firstLine;
+  const cut = firstLine.lastIndexOf(" ", DOC_SUMMARY_MAX_CHARS);
+  return `${firstLine.slice(0, cut > 40 ? cut : DOC_SUMMARY_MAX_CHARS).trimEnd()}\u2026`;
+}
 function runOutline(opts) {
   const multiFiles = parseMultiFileSpec(opts.file);
   if (multiFiles !== null) return runPerFileListing(multiFiles, (file) => runOutline({ ...opts, file, includeFilePath: true }), opts.json === true);
@@ -6669,7 +6695,7 @@ function runOutline(opts) {
     const rangeStr = `${sym.lineStart.toString().padStart(4)}-${sym.lineEnd.toString().padEnd(6)}`;
     const kindStr = sym.kind.padEnd(14);
     const bodyLen = sym.lineEnd - sym.lineStart + 1;
-    const docFirst = hasRealDocstring(sym.docstring) ? `  # ${sym.docstring.split("\n")[0] ?? ""}` : "";
+    const docFirst = hasRealDocstring(sym.docstring) ? `  # ${clipDocSummary(sym.docstring.split("\n")[0] ?? "")}` : "";
     const statsStr = formatStatsSuffix(refCounts, sym);
     lines.push(`  ${rangeStr}  ${kindStr}  ${sym.name}  (${bodyLen}\u2113)${docFirst}${statsStr}`);
   }
@@ -6709,11 +6735,11 @@ function runCsvQuery(opts) {
       const rowsJson = result.rows.map((r) => Object.fromEntries(result.header.map((h, i) => [h, r[i]])));
       const headTruncated = result.rows.length < result.totalRows;
       const capped = guardJsonRows(rowsJson);
-      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount: result.totalRows });
+      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount: result.totalRows, ...result.totalRows === 0 && result.preFilterRows > 0 ? { filteredFromRows: result.preFilterRows } : {} });
       emit(jsonText);
       recordReadStat("csv_query", fullSourceBytes, jsonText, opts.file);
     } else {
-      const tableText = formatCsvTable(result);
+      const tableText = formatCsvTable(result, (opts.where ?? []).map((w) => `--where ${w}`));
       emit(tableText);
       recordReadStat("csv_query", fullSourceBytes, tableText, opts.file);
     }
@@ -6856,6 +6882,7 @@ function resolveYamlMergeKeys(node) {
 }
 function parseYamlDocument(text) {
   const docs = loadAll(text).map(resolveYamlMergeKeys);
+  if (docs.length === 0) return null;
   return docs.length === 1 ? docs[0] : docs;
 }
 function runYamlOutline(opts) {
@@ -7189,11 +7216,11 @@ function runPrSlice(opts) {
         }
         const fullSourceBytes = Buffer.byteLength(diffText, "utf8");
         if (opts.json === true) {
-          const jsonText = JSON.stringify({ path: parsed.path, diff: fenceGithubTextIfMatched(fileDiff) });
+          const jsonText = JSON.stringify({ path: parsed.path, diff: fenceGithubFieldIfMatched(fileDiff) });
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} diff:${parsed.path}`);
         } else {
-          emitGuarded(fenceGithubTextIfMatched(fileDiff), "pr-slice");
+          emitGuarded(fenceGithubText(fileDiff), "pr-slice");
           recordReadStat("pr_slice", fullSourceBytes, fileDiff, `${repo}#${opts.pr} diff:${parsed.path}`);
         }
         return 0;
@@ -7202,14 +7229,14 @@ function runPrSlice(opts) {
         const comments = fetchPrComments(opts.pr, repo);
         const fullSourceBytes = Buffer.byteLength(JSON.stringify(comments), "utf8");
         if (opts.json === true) {
-          const fencedComments = comments.map((c) => ({ ...c, body: fenceGithubTextIfMatched(c.body) }));
+          const fencedComments = comments.map((c) => ({ ...c, body: fenceGithubFieldIfMatched(c.body) }));
           const capped = guardJsonRows(fencedComments);
           const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} comments`);
         } else {
           const text = formatCommentsSlice(comments);
-          emitGuarded(fenceGithubTextIfMatched(text), "pr-slice");
+          emitGuarded(fenceGithubText(text), "pr-slice");
           recordReadStat("pr_slice", fullSourceBytes, text, `${repo}#${opts.pr} comments`);
         }
         return 0;
@@ -7220,15 +7247,15 @@ function runPrSlice(opts) {
         if (opts.json === true) {
           const fencedDesc = {
             ...desc,
-            title: fenceGithubTextIfMatched(desc.title),
-            body: desc.body !== null ? fenceGithubTextIfMatched(desc.body) : null
+            title: fenceGithubFieldIfMatched(desc.title),
+            body: desc.body !== null ? fenceGithubFieldIfMatched(desc.body) : null
           };
           const jsonText = JSON.stringify(fencedDesc);
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} description`);
         } else {
           const text = formatDescriptionSlice(desc);
-          emitGuarded(fenceGithubTextIfMatched(text), "pr-slice");
+          emitGuarded(fenceGithubText(text), "pr-slice");
           recordReadStat("pr_slice", fullSourceBytes, text, `${repo}#${opts.pr} description`);
         }
         return 0;
@@ -7439,6 +7466,9 @@ async function runImageText(file) {
   const data = fs5.readFileSync(file);
   const ocr = await ocrImage(data);
   if (ocr === null) {
+    if (ocrIntegrityFailed()) {
+      throw new Error(`${file} was not OCRed: the cached language model failed its checksum and was discarded, so the next run re-downloads it`);
+    }
     if (isOcrEngineAvailable()) {
       throw new Error(`${file} could not be processed by OCR (unreadable image, timeout, or offline model fetch)`);
     }
@@ -7489,15 +7519,14 @@ ${emptyIndexMessage(rootDir2)}`, code: 1 };
   const match = resolution.entry;
   const rootDir = resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() });
   const excludeTests = opts.excludeTests === true;
-  const unboundedQuery = excludeTests || opts.grep !== void 0;
-  const allCallers = resolveCallers(match.name, void 0, match.filePath, rootDir, unboundedQuery);
+  const allCallers = resolveCallers(match.name, void 0, match.filePath, rootDir, true);
   const testFiltered = excludeTests ? allCallers.filter((c) => !isTestFile(c.file)) : allCallers;
   const hiddenByExcludeTests = excludeTests ? allCallers.length - testFiltered.length : 0;
   const preGrepCount = testFiltered.length;
   const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
   const callers = matchesGrep !== void 0 ? testFiltered.filter((c) => matchesGrep(c.caller)) : testFiltered;
   const hiddenByGrep = matchesGrep !== void 0 ? preGrepCount - callers.length : 0;
-  const totalCallers = unboundedQuery ? callers.length : queryRefCounts([match.name], globalDbPath(), rootDir).get(match.name) ?? callers.length;
+  const totalCallers = callers.length;
   const section = findContainingSection(match.filePath, match.lineStart, match.lineEnd, readFileText);
   const limit = opts.limit ?? 20;
   const shown = callers.slice(0, limit);
@@ -7643,7 +7672,7 @@ function runFind(opts) {
   }
   if (opts.json === true) {
     const fuzzyPayload = fuzzyNames.length > 0 ? { fuzzy: true, matchedNames: fuzzyNames } : {};
-    emit(JSON.stringify({ files, truncated, ...fuzzyPayload }, null, 2));
+    emit(JSON.stringify({ files, truncated, totalCount: allFiles.length, ...fuzzyPayload }, null, 2));
     return 0;
   }
   if (fuzzyNames.length > 0) {
@@ -8913,6 +8942,18 @@ async function runSemantic(query, opts) {
       `Matching on meaning is off (${extractErrorMessage(e)}); these results come from keyword search alone.`
     );
   }
+  if (rawHits.length === 0 && isAvailable()) {
+    try {
+      const enabled = loadConfig().indexing.embeddings_enabled;
+      const { indexedFiles, embeddedFiles } = enabled ? getEmbeddingCoverage(globalDbPath(), rootDir) : { indexedFiles: 0, embeddedFiles: 0 };
+      if (indexedFiles > 0 && embeddedFiles < indexedFiles) {
+        console.warn(
+          `Matching on meaning found nothing, and only ${embeddedFiles} of ${indexedFiles} indexed file(s) in this project have embeddings \u2014 these results come from keyword search alone. Run 'token-goat doctor' for why.`
+        );
+      }
+    } catch {
+    }
+  }
   const mergedHits = mergeNearbyHits(rawHits);
   const overFetchFts = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
   const ftsRows = searchSymbolsFts(query, overFetchFts, void 0, rootDir);
@@ -8959,7 +9000,9 @@ async function runSemantic(query, opts) {
   const anyFilter = matchesGrep !== void 0 || opts.excludeTests === true;
   const filteredHits = anyFilter ? fusedHits.filter(keepHit) : fusedHits;
   const suppressedTotal = opts.excludeTests === true ? fusedHits.filter((h) => (matchesGrep === void 0 || matchesGrep(toDisplayPath(rootDir, h.filePath))) && isTestFile(h.filePath)).length : 0;
+  const eligibleCount = filteredHits.length;
   const hits = filteredHits.slice(0, n);
+  const candidatesClipped = rawHits.length >= overFetchForMerge || ftsRows.length >= overFetchFts;
   const hadDense = mergedHits.length > 0;
   const hadFts = ftsRows.length > 0;
   const source = hadDense && hadFts ? "hybrid" : hadDense ? "embeddings" : "fts";
@@ -8975,7 +9018,8 @@ async function runSemantic(query, opts) {
         preview: previewLines(h.previewText, 3)
       }));
       const capped = guardJsonRows(items);
-      const text3 = JSON.stringify({ source, ...capped }, null, 2);
+      const limitTruncated = hits.length < eligibleCount;
+      const text3 = JSON.stringify({ source, ...capped, truncated: capped.truncated || limitTruncated, totalCount: eligibleCount, ...candidatesClipped ? { totalCountIsFloor: true } : {} }, null, 2);
       recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text3, query);
       return { text: text3, code: 0 };
     }
@@ -8989,6 +9033,9 @@ ${previewLines(h.previewText, 3)}`;
 ${previewLines(h.previewText, 3)}`;
     });
     const text2 = guardText(blocks.join("\n\n"), "semantic");
+    if (hits.length < eligibleCount) {
+      emitErr(`Showing ${hits.length} of ${candidatesClipped ? "at least " : ""}${countNoun(eligibleCount, "match", "matches")} (raise --limit to see the rest).`);
+    }
     recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text2, query);
     return { text: text2, code: 0 };
   }
@@ -9146,10 +9193,14 @@ function bfsCallChains(start, callersOf, maxDepth) {
     const tip = chain[chain.length - 1];
     if (tip === void 0) continue;
     const callers = callersOf(tip);
-    if (callers.length === 0 || chain.length > maxDepth) {
+    if (callers.length === 0) {
       complete.push(chain);
       continue;
     }
+    if (chain.length > maxDepth) {
+      complete.push([...chain, "(depth-limit)"]);
+      continue;
+    }
     let expanded = false;
     for (const caller of callers) {
       if (chain.includes(caller)) {
@@ -9235,8 +9286,11 @@ function runCallers(opts) {
     emitErr2(`Symbol '${name}' not found in '${file}'`);
     return 1;
   }
-  const unbounded = opts.excludeTests === true || opts.grep !== void 0;
-  const resolved = resolveCallers(name, opts.limit, fileHint, rootDir, unbounded);
+  const unbounded = opts.excludeTests === true || opts.grep !== void 0 || fileHint !== void 0;
+  const requestedLimit = opts.limit ?? DEFAULT_REF_QUERY_LIMIT;
+  const probed = resolveCallers(name, unbounded ? opts.limit : requestedLimit + 1, fileHint, rootDir, unbounded);
+  const sqlTruncated = !unbounded && probed.length > requestedLimit;
+  const resolved = sqlTruncated ? probed.slice(0, requestedLimit) : probed;
   const suppressed = opts.excludeTests === true ? resolved.filter((e) => isTestFile(e.file)).length : 0;
   let filtered = opts.excludeTests === true ? resolved.filter((e) => !isTestFile(e.file)) : resolved;
   const preGrepCount = filtered.length;
@@ -9277,7 +9331,7 @@ function runCallers(opts) {
       return { ...e, file: displayPath, filePath: displayPath };
     });
     const capped = guardJsonRows(rows);
-    const limitTruncated = entries.length < filtered.length;
+    const limitTruncated = entries.length < filtered.length || sqlTruncated;
     const hiddenByGrep = preGrepCount - filtered.length;
     emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || limitTruncated, totalCount: filtered.length, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...opts.excludeTests === true && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
     return 0;
@@ -9316,7 +9370,7 @@ function runCallChain(opts) {
   const getSyms = buildFileSymCache();
   let suppressedCount = 0;
   const callersOf = (n) => {
-    const refs = queryRefs({ name: n, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
+    const refs = queryRefs({ name: n, limit: UNBOUNDED_REF_LIMIT, rootDir });
     if (refs.length === 0) return [];
     const scoped = fileHint !== void 0 && n === name ? filterRefsForSymbol(refs, n, fileHint, getSyms) : refs;
     const names = /* @__PURE__ */ new Set();
@@ -9379,12 +9433,16 @@ function runImpact(opts) {
   const hops = /* @__PURE__ */ new Map([[rootName, 0]]);
   const queue = [[rootName, 0]];
   let suppressedCount = 0;
+  let depthCapped = 0;
   while (queue.length > 0) {
     const item = queue.shift();
     if (item === void 0) break;
     const [name, depth] = item;
-    if (depth >= DEPTH_CAP) continue;
-    const refs = queryRefs({ name, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
+    if (depth >= DEPTH_CAP) {
+      depthCapped += 1;
+      continue;
+    }
+    const refs = queryRefs({ name, limit: UNBOUNDED_REF_LIMIT, rootDir });
     const scoped = fileHint !== void 0 && name === rootName ? filterRefsForSymbol(refs, name, fileHint, getSyms) : refs;
     for (const ref of scoped) {
       if (opts.excludeTests === true && isTestFile(ref.filePath)) {
@@ -9412,6 +9470,12 @@ function runImpact(opts) {
   const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
   const grepped = matchesGrep !== void 0 ? allSorted.filter(([symbol]) => matchesGrep(symbol)) : allSorted;
   const sorted = grepped.slice(0, top);
+  if (depthCapped > 0) {
+    emitErr2(`Impact truncated at the ${DEPTH_CAP}-hop depth limit: ${depthCapped} symbol${depthCapped === 1 ? "" : "s"} at that depth ${depthCapped === 1 ? "was" : "were"} not expanded, so callers reachable only beyond ${DEPTH_CAP} hops are missing.`);
+  }
+  if (grepped.length > sorted.length) {
+    emitErr2(`Showing top ${sorted.length} of ${grepped.length} impacted symbols (raise --top to see the rest).`);
+  }
   if (matchesGrep !== void 0 && sorted.length === 0 && allSorted.length > 0) {
     if (opts.json === true) {
       emitErr2(grepFilteredToEmptyNotice(allSorted.length, opts.grep, "impacted symbol", "impacted symbols"));
@@ -9541,14 +9605,17 @@ function runDead(opts) {
     }
     return 1;
   }
-  const syms = kinds.flatMap((k) => querySymbols({ kind: k, limit: 5e3, rootDir }));
+  const syms = kinds.flatMap((k) => querySymbols({ kind: k, limit: UNBOUNDED_REF_LIMIT, rootDir }));
   const getSyms = buildFileSymCache();
   const results = [];
   let suppressed = 0;
   for (const sym of syms) {
     if (opts.includePrivate !== true && sym.name.startsWith("_")) continue;
     const refs = queryRefs({ name: sym.name, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
-    const scoped = filterRefsForSymbol(refs, sym.name, sym.filePath, getSyms);
+    let scoped = filterRefsForSymbol(refs, sym.name, sym.filePath, getSyms);
+    if (scoped.length === 0 && refs.length >= DEFAULT_REF_QUERY_LIMIT) {
+      scoped = filterRefsForSymbol(queryRefs({ name: sym.name, limit: UNBOUNDED_REF_LIMIT, rootDir }), sym.name, sym.filePath, getSyms);
+    }
     if (!isDeadSymbol(sym.name, scoped.length)) continue;
     if (sym.kind === "method") {
       const ownScope = enclosingNamedScope(getSyms(sym.filePath), sym.lineStart);
@@ -9769,7 +9836,7 @@ var TYPE_KINDS = [
 var CORE_SYMBOL_KINDS = [
   .../* @__PURE__ */ new Set([...GENERIC_SYMBOL_KINDS, ...TYPE_KINDS, ...OTHER_ADAPTER_SYMBOL_KINDS])
 ];
-var TYPES_EXCLUDE_TESTS_SCAN_LIMIT = 5e3;
+var TYPES_SCAN_LIMIT = 5e3;
 function runTypes(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
     emitErr2(`--limit must be a positive number, got: ${opts.limit}`);
@@ -9782,34 +9849,25 @@ function runTypes(opts) {
   const rootDir = resolveProjectRoot({ project: process.cwd() });
   const results = [];
   let suppressed = 0;
-  const queryLimit = excludeTests ? TYPES_EXCLUDE_TESTS_SCAN_LIMIT : limit;
   for (const k of TYPE_KINDS) {
-    const syms = querySymbols({ kind: k, ...fpOpt, limit: queryLimit, rootDir });
-    if (!excludeTests) {
-      results.push(...syms);
-      continue;
-    }
-    const kept = [];
+    const syms = querySymbols({ kind: k, ...fpOpt, limit: TYPES_SCAN_LIMIT, rootDir });
     for (const sym of syms) {
-      if (isTestFile(sym.filePath)) {
+      if (excludeTests && isTestFile(sym.filePath)) {
         suppressed += 1;
         continue;
       }
-      kept.push(sym);
+      results.push(sym);
     }
-    results.push(...kept.slice(0, limit));
   }
-  const classes = querySymbols({ kind: "class", ...fpOpt, limit: queryLimit, rootDir });
-  const typeClasses = [];
+  const classes = querySymbols({ kind: "class", ...fpOpt, limit: TYPES_SCAN_LIMIT, rootDir });
   for (const cls of classes) {
     if (!looksLikeTypeClass(cls.body)) continue;
     if (excludeTests && isTestFile(cls.filePath)) {
       suppressed += 1;
       continue;
     }
-    typeClasses.push(cls);
+    results.push(cls);
   }
-  results.push(...excludeTests ? typeClasses.slice(0, limit) : typeClasses);
   results.sort(
     // Pin the locale: an unlocaled localeCompare() sorts differently across
     // Node's small-icu vs full-icu builds and different system default
@@ -9836,7 +9894,16 @@ function runTypes(opts) {
   }
   const preFilterCount = results.length;
   const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
-  const filtered = matchesGrep !== void 0 ? results.filter((r) => matchesGrep(r.name)) : results;
+  const matched = matchesGrep !== void 0 ? results.filter((r) => matchesGrep(r.name)) : results;
+  const eligibleCount = matched.length;
+  const perKindShown = /* @__PURE__ */ new Map();
+  const filtered = matched.filter((r) => {
+    const seen = perKindShown.get(r.kind) ?? 0;
+    if (seen >= limit) return false;
+    perKindShown.set(r.kind, seen + 1);
+    return true;
+  });
+  const cappedOut = eligibleCount - filtered.length;
   if (filtered.length === 0) {
     if (opts.json === true) {
       emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preFilterCount }, null, 2));
@@ -9847,8 +9914,8 @@ function runTypes(opts) {
   }
   if (opts.json === true) {
     const capped = guardJsonRows(filtered.map((r) => ({ ...r, filePath: toDisplayPath(rootDir, r.filePath) })));
-    const hiddenByGrep = preFilterCount - filtered.length;
-    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...excludeTests && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
+    const hiddenByGrep = preFilterCount - eligibleCount;
+    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || cappedOut > 0, totalCount: eligibleCount, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...excludeTests && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
     return 0;
   }
   if (excludeTests && suppressed > 0) {
@@ -9857,6 +9924,9 @@ function runTypes(opts) {
   for (const r of filtered) {
     emit2(`${r.name}	${r.kind}	${toDisplayPath(rootDir, r.filePath)}:${r.lineStart}`);
   }
+  if (cappedOut > 0) {
+    emitErr2(`Showing ${filtered.length} of ${eligibleCount} type declarations (--limit is per kind; raise it to see the rest).`);
+  }
   return 0;
 }
 function runScope(opts) {
@@ -9872,7 +9942,7 @@ function runScope(opts) {
     return 1;
   }
   const line = Number.parseInt(lineStr, 10);
-  if (!Number.isFinite(line) || line < 1) {
+  if (!Number.isSafeInteger(line) || line < 1) {
     emitErr2(`Invalid line number: ${lineStr}`);
     return 1;
   }
@@ -9882,25 +9952,32 @@ function runScope(opts) {
     return 1;
   }
   const filePath = resolveIndexPath(file);
-  const syms = querySymbols({ filePath, limit: ALL_SYMBOLS_IN_FILE_LIMIT });
-  const enclosing = syms.filter((s) => s.lineStart <= line && line <= s.lineEnd).sort((a, b) => b.lineStart - a.lineStart);
-  if (syms.length === 0) {
-    if (!fs6.existsSync(filePath)) {
-      emitErr2(`Could not read: ${file}`);
+  const enclosing = querySymbols({ filePath, enclosingLine: line, limit: ALL_SYMBOLS_IN_FILE_LIMIT }).sort((a, b) => b.lineStart - a.lineStart || a.lineEnd - b.lineEnd || a.name.localeCompare(b.name, "en"));
+  if (enclosing.length === 0) {
+    if (querySymbols({ filePath, limit: 1 }).length === 0) {
+      if (!fs6.existsSync(filePath)) {
+        emitErr2(`Could not read: ${file}`);
+        return 1;
+      }
+      emitErr2(
+        `No indexed symbols in '${file}' \u2014 the file exists but nothing is indexed for it, so every line looks empty`
+      );
       return 1;
     }
-    emitErr2(`No indexed symbols in '${file}' \u2014 the file exists but nothing is indexed for it, so every line looks empty`);
-    return 1;
-  }
-  if (enclosing.length === 0) {
     emitErr2(`No symbols enclosing line ${line} in '${file}'`);
     return 1;
   }
+  const scopeDisplayRoot = getDisplayRoot();
   if (opts.json === true) {
-    emit2(JSON.stringify(enclosing, null, 2));
+    emit2(
+      JSON.stringify(
+        enclosing.map((s) => ({ ...s, filePath: toDisplayPath(scopeDisplayRoot, s.filePath) })),
+        null,
+        2
+      )
+    );
     return 0;
   }
-  const scopeDisplayRoot = getDisplayRoot();
   for (const s of enclosing) {
     emit2(`${s.name}	${s.kind}	${toDisplayPath(scopeDisplayRoot, s.filePath)}:${s.lineStart}-${s.lineEnd}`);
   }
@@ -9967,17 +10044,18 @@ function canonicalCycleKey(cyclePath) {
   }
   return [...nodes.slice(minIdx), ...nodes.slice(0, minIdx)].join(" ");
 }
-function findCycles(graph) {
+function findCyclesCapped(graph) {
   const cycles = [];
   const seen = /* @__PURE__ */ new Set();
   const sccs = tarjanSCCs(graph);
+  const probeLimit = MAX_CYCLES + 1;
   for (const component of sccs) {
     let dfs2 = function(start, node, pathSoFar) {
-      if (cycles.length >= MAX_CYCLES) return;
+      if (cycles.length >= probeLimit) return;
       stack.add(node);
       for (const nb of graph.get(node) ?? []) {
         if (!sccSet.has(nb)) continue;
-        if (cycles.length >= MAX_CYCLES) break;
+        if (cycles.length >= probeLimit) break;
         if (nb === start) {
           const cyclePath = [...pathSoFar, node, start];
           const key = canonicalCycleKey(cyclePath);
@@ -9992,6 +10070,7 @@ function findCycles(graph) {
       stack.delete(node);
     };
     var dfs = dfs2;
+    if (cycles.length >= probeLimit) break;
     if (component.length === 1) {
       const [only] = component;
       if (only !== void 0 && (graph.get(only) ?? []).includes(only)) cycles.push([only, only]);
@@ -10000,11 +10079,12 @@ function findCycles(graph) {
     const sccSet = new Set(component);
     const stack = /* @__PURE__ */ new Set();
     for (const start of component) {
-      if (cycles.length >= MAX_CYCLES) break;
+      if (cycles.length >= probeLimit) break;
       dfs2(start, start, []);
     }
   }
-  return cycles;
+  if (cycles.length > MAX_CYCLES) return { cycles: cycles.slice(0, MAX_CYCLES), truncated: true };
+  return { cycles, truncated: false };
 }
 function runSimilar(opts) {
   if (opts.top !== void 0 && opts.top <= 0) {
@@ -10022,8 +10102,12 @@ function runSimilar(opts) {
   const words = [anchor.name, ...(anchor.docstring ?? "").split(/\s+/).filter((w) => w.length > 4)];
   const query = words.slice(0, 8).join(" ");
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const hits = searchSymbolsFts(query, top + 1, void 0, rootDir);
-  const results = hits.filter((h) => !(h.filePath === anchor.filePath && h.name === anchor.name)).slice(0, top);
+  const hits = searchSymbolsFts(query, UNBOUNDED_REF_LIMIT, void 0, rootDir);
+  const matches = hits.filter((h) => !(h.filePath === anchor.filePath && h.name === anchor.name));
+  const results = matches.slice(0, top);
+  if (matches.length > results.length) {
+    emitErr2(`Showing top ${results.length} of ${matches.length} similar symbols (raise --top to see the rest).`);
+  }
   if (opts.json === true) {
     emit2(JSON.stringify(results.map((h) => ({ name: h.name, kind: h.kind, file: h.filePath, line: h.lineStart })), null, 2));
     return 0;
@@ -10039,7 +10123,9 @@ function runContextFor(opts) {
   const top = opts.top ?? 12;
   const budget = opts.budget;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const hits = searchSymbolsFts(opts.task, top, void 0, rootDir);
+  const fetched = searchSymbolsFts(opts.task, top + 1, void 0, rootDir);
+  const moreBeyondTop = fetched.length > top;
+  const hits = fetched.slice(0, top);
   if (hits.length === 0) {
     emitErr2(`No matches found for '${opts.task}'`);
     return 1;
@@ -10052,6 +10138,15 @@ function runContextFor(opts) {
     tokensSoFar += bodyTokens;
     entries.push({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` });
   }
+  const skippedByBudget = hits.length - entries.length;
+  const notices = [];
+  if (skippedByBudget > 0) {
+    notices.push(
+      entries.length === 0 ? `All ${countNoun(skippedByBudget, "matching symbol")} were larger than --budget ${String(opts.budget)} tokens, so none are shown. Raise --budget.` : `Showing ${entries.length} of ${countNoun(hits.length, "matching symbol")}; ${skippedByBudget} did not fit --budget ${String(opts.budget)} tokens.`
+    );
+  }
+  if (moreBeyondTop) notices.push(`More matches exist beyond --top ${top} (raise it to see them).`);
+  for (const n of notices) emitErr2(n);
   if (opts.json === true) {
     emit2(JSON.stringify(entries, null, 2));
     return 0;
@@ -10108,8 +10203,8 @@ function runCoverageGaps(opts) {
   }
   const top = opts.top ?? 50;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const allFns = querySymbols({ kind: "function", limit: 2e3, rootDir });
-  const allMethods = querySymbols({ kind: "method", limit: 2e3, rootDir });
+  const allFns = querySymbols({ kind: "function", limit: UNBOUNDED_REF_LIMIT, rootDir });
+  const allMethods = querySymbols({ kind: "method", limit: UNBOUNDED_REF_LIMIT, rootDir });
   const candidates = [...allFns, ...allMethods];
   const gaps = [];
   for (const sym of candidates) {
@@ -10120,6 +10215,9 @@ function runCoverageGaps(opts) {
     if (!hasTestRef) gaps.push({ name: sym.name, kind: sym.kind, file: sym.filePath, line: sym.lineStart });
   }
   const sliced = gaps.slice(0, top);
+  if (gaps.length > sliced.length) {
+    emitErr2(`Showing top ${sliced.length} of ${gaps.length} coverage gaps (raise --top to see the rest).`);
+  }
   if (opts.json === true) {
     emit2(JSON.stringify(sliced, null, 2));
     return 0;
@@ -10186,18 +10284,22 @@ function runArch(opts) {
     }
     graph.set(file, internal);
   }
-  const hubs = [...importedBy.entries()].sort((a, b) => b[1].size - a[1].size).slice(0, top).map(([f, importers]) => ({ file: f, importedBy: importers.size }));
-  const entryPoints = files.filter((f) => !importedBy.has(f) && (graph.get(f) ?? []).length > 0).slice(0, top).map((f) => ({ file: f }));
-  const cycles = findCycles(graph);
+  const allHubs = [...importedBy.entries()].sort((a, b) => b[1].size - a[1].size).map(([f, importers]) => ({ file: f, importedBy: importers.size }));
+  const hubsTotal = allHubs.length;
+  const hubs = allHubs.slice(0, top);
+  const allEntryPoints = files.filter((f) => !importedBy.has(f) && (graph.get(f) ?? []).length > 0).map((f) => ({ file: f }));
+  const entryPointsTotal = allEntryPoints.length;
+  const entryPoints = allEntryPoints.slice(0, top);
+  const { cycles, truncated: cyclesTruncated } = findCyclesCapped(graph);
   if (opts.json === true) {
-    emit2(JSON.stringify({ hubs, entryPoints, cycles }, null, 2));
+    emit2(JSON.stringify({ hubs, hubsTotal, hubsTruncated: hubs.length < hubsTotal, entryPoints, entryPointsTotal, entryPointsTruncated: entryPoints.length < entryPointsTotal, cycles, ...cyclesTruncated ? { cyclesTruncated: true } : {} }, null, 2));
     return 0;
   }
-  emit2(`hubs (top ${top} most-imported):`);
+  emit2(hubs.length < hubsTotal ? `hubs (top ${hubs.length} of ${hubsTotal} most-imported):` : `hubs (${hubsTotal} most-imported):`);
   for (const h of hubs) emit2(`  ${h.importedBy} importers	${toDisplayPath(getDisplayRoot(opts.cwd), h.file)}`);
-  emit2(`entry points (imported by nobody, top ${top}):`);
+  emit2(entryPoints.length < entryPointsTotal ? `entry points (imported by nobody, top ${entryPoints.length} of ${entryPointsTotal}):` : `entry points (imported by nobody, ${entryPointsTotal} found):`);
   for (const e of entryPoints) emit2(`  ${toDisplayPath(getDisplayRoot(opts.cwd), e.file)}`);
-  emit2(`cycles (${cycles.length} found):`);
+  emit2(cyclesTruncated ? `cycles (first ${cycles.length}, truncated at the ${MAX_CYCLES}-cycle enumeration limit: more cycles exist):` : `cycles (${cycles.length} found):`);
   for (const c of cycles) emit2(`  ${c.map((f) => toDisplayPath(getDisplayRoot(opts.cwd), f)).join(" -> ")}`);
   return 0;
 }
@@ -10245,21 +10347,30 @@ function runAsk(opts) {
   }
   const top = opts.top ?? 8;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const hits = searchSymbolsFts(opts.question, top, void 0, rootDir);
+  const fetched = searchSymbolsFts(opts.question, top + 1, void 0, rootDir);
+  const moreBeyondTop = fetched.length > top;
+  const hits = fetched.slice(0, top);
+  if (moreBeyondTop) {
+    emitErr2(`Answer is grounded in the top ${countNoun(top, "match", "matches")}; more matched (raise --top to widen the evidence).`);
+  }
   const BACKEND_ENV = "TOKEN_GOAT_ASK_BACKEND";
   const backendLabel = process.env[BACKEND_ENV] ?? "";
   const entries = hits.map((h) => ({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` }));
-  const degrade = () => {
+  const degrade = (reason, extraNote) => {
     if (opts.json === true) {
-      emit2(JSON.stringify({ degraded: true, note: `Set ${BACKEND_ENV}=claude|codex for LLM synthesis`, context: entries }, null, 2));
+      emit2(JSON.stringify({ degraded: true, note: reason, ...extraNote !== void 0 ? { hint: extraNote } : {}, context: entries }, null, 2));
       return 0;
     }
-    emit2(`[degraded mode - set ${BACKEND_ENV}=claude|codex for LLM synthesis]`);
+    emit2(`[degraded mode - ${reason}]`);
+    if (extraNote !== void 0) emit2(extraNote);
     for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}@${e.line}"`);
     return 0;
   };
-  if (!backendLabel) return degrade();
-  if (hits.length === 0) return degrade();
+  if (!backendLabel) return degrade(`set ${BACKEND_ENV}=claude|codex for LLM synthesis`);
+  if (hits.length === 0) {
+    if (isIndexEmptyForProject(globalDbPath(), rootDir)) return degrade(`${BACKEND_ENV}=${backendLabel} is set, but nothing is indexed for this project yet, so there is no context to answer from`, emptyIndexMessage(rootDir));
+    return degrade(`${BACKEND_ENV}=${backendLabel} is set, but no indexed symbol matched this question, so there is no context to answer from -- try different wording or token-goat semantic`);
+  }
   const isWin = process.platform === "win32";
   let backendPath = null;
   try {
@@ -10268,7 +10379,7 @@ function runAsk(opts) {
     if (found) backendPath = found;
   } catch {
   }
-  if (!backendPath) return degrade();
+  if (!backendPath) return degrade(`${BACKEND_ENV}=${backendLabel} is set, but '${backendLabel}' was not found on PATH`);
   const context = hits.map((h, i) => `[${i + 1}] ${h.filePath}
 ${h.body ?? ""}`).join("\n\n");
   const prompt = `Answer the QUESTION using only the CODE SNIPPETS below.
@@ -10319,7 +10430,7 @@ ANSWER:`;
       }
     }
   }
-  return degrade();
+  return degrade(`${BACKEND_ENV}=${backendLabel} ran but returned no answer`);
 }
 
 // src/content_store.ts