token-goat 2.6.36 → 2.8.1

package/dist/{token-goat-chunk-IYTVE6KN.mjs → token-goat-chunk-RMDQFTQD.mjs}

@@ -2,6 +2,7 @@ import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
   IMPORT_RE,
+  ImageDecodeError,
   MAX_OVER_FETCH,
   OVER_FETCH_FACTOR,
   SKIP_DIRS,
@@ -21,12 +22,15 @@ import {
   formatCsvTable,
   getFileEntry,
   indexFileSync,
+  isAvailable,
   isBlobStale,
   isImagePath,
   isIndexEmptyForProject,
+  isOcrEngineAvailable,
   isTextHeavy,
   lineOpenDelimiterAfter,
   loadBlob,
+  locatePdfPages,
   mergeNearbyHits,
   ocrImage,
   parseWhereSpecs,
@@ -50,8 +54,9 @@ import {
   walkProject,
   yamlLineClosesQuote,
   yamlOpenQuoteAfter
-} from "./token-goat-chunk-UFOVM7ZN.mjs";
+} from "./token-goat-chunk-2G6RAB4G.mjs";
 import {
+  Database,
   PER_FILE_COUNTERFACTUAL_CEILING,
   _detectOpenQuote,
   _lineClosesQuote,
@@ -101,7 +106,7 @@ import {
   unsupportedLanguageName,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-V465YKOR.mjs";
+} from "./token-goat-chunk-ELDJRLHZ.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-AO2QD2AG.mjs";
@@ -320,7 +325,15 @@ function resolveHeaderPos(headers, base, ordinal) {
     const pick2 = ordinal === null ? 0 : ordinal - 1;
     const headerPos = matches[pick2];
     if (headerPos === void 0) return null;
-    return { headerPos, redirectedFrom: null };
+    let occurrences = null;
+    if (ordinal === null && matches.length > 1) {
+      occurrences = [];
+      for (const i of matches) {
+        const h = headers[i];
+        if (h !== void 0) occurrences.push(h.index + 1);
+      }
+    }
+    return { headerPos, redirectedFrom: null, occurrences };
   }
   if (ordinal !== null || normalizedTarget.length === 0) return null;
   let prefixPos = -1;
@@ -337,7 +350,7 @@ function resolveHeaderPos(headers, base, ordinal) {
   if (distinct.size === 1 && prefixPos !== -1) {
     const chosen = headers[prefixPos];
     if (chosen === void 0) return null;
-    return { headerPos: prefixPos, redirectedFrom: base };
+    return { headerPos: prefixPos, redirectedFrom: base, occurrences: null };
   }
   const queryWords = normalizedTarget.split(/\s+/).filter((w) => w.length >= MIN_WIDEN_WORD_LEN);
   if (queryWords.length === 0) return null;
@@ -352,7 +365,7 @@ function resolveHeaderPos(headers, base, ordinal) {
   if (widenedMatches.length !== 1) return null;
   const widenedPos = widenedMatches[0];
   if (widenedPos === void 0) return null;
-  return { headerPos: widenedPos, redirectedFrom: base };
+  return { headerPos: widenedPos, redirectedFrom: base, occurrences: null };
 }
 function buildSectionResult(headers, kind, lines, headerPos, redirectedFrom) {
   const header = headers[headerPos];
@@ -378,7 +391,9 @@ function resolveSectionFromText(text, headingSpec, language) {
   const lines = text.split("\n");
   const resolved = resolveHeaderPos(headers, base, ordinal);
   if (resolved === null) return null;
-  return buildSectionResult(headers, kind, lines, resolved.headerPos, resolved.redirectedFrom);
+  const built = buildSectionResult(headers, kind, lines, resolved.headerPos, resolved.redirectedFrom);
+  if (built === null || resolved.occurrences === null) return built;
+  return { ...built, occurrences: resolved.occurrences };
 }
 function extractSection(text, headingSpec) {
   return resolveSectionFromText(text, headingSpec, "unknown");
@@ -3439,6 +3454,33 @@ function mergeParameters(pathLevelParams, ownParams) {
   });
   return [...inheritedParams, ...ownParams];
 }
+function resolveJsonPointer(root, ref) {
+  const parts = ref.slice(2).split("/").map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+  let cur = root;
+  for (const part of parts) {
+    if (typeof cur !== "object" || cur === null) return null;
+    cur = cur[part];
+    if (cur === void 0) return null;
+  }
+  return cur;
+}
+function dereferenceLocalRefs(node, root, seen) {
+  if (Array.isArray(node)) return node.map((item) => dereferenceLocalRefs(item, root, seen));
+  if (typeof node !== "object" || node === null) return node;
+  const rec = node;
+  const ref = rec["$ref"];
+  if (typeof ref === "string" && ref.startsWith("#/")) {
+    if (seen.has(ref)) return node;
+    const target = resolveJsonPointer(root, ref);
+    if (target === void 0 || target === null) return node;
+    return dereferenceLocalRefs(target, root, /* @__PURE__ */ new Set([...seen, ref]));
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(rec)) {
+    out[key] = dereferenceLocalRefs(value, root, seen);
+  }
+  return out;
+}
 function extractOperations(spec) {
   if (typeof spec !== "object" || spec === null) return [];
   const paths = spec["paths"];
@@ -3461,9 +3503,9 @@ function extractOperations(spec) {
         ...typeof op["summary"] === "string" ? { summary: op["summary"] } : {},
         ...typeof op["description"] === "string" ? { description: op["description"] } : {},
         ...tags !== void 0 && tags.length > 0 ? { tags } : {},
-        parameters: mergeParameters(pathLevelParams, ownParams),
-        ...op["requestBody"] !== void 0 ? { requestBody: op["requestBody"] } : {},
-        responses: typeof op["responses"] === "object" && op["responses"] !== null ? op["responses"] : {}
+        parameters: dereferenceLocalRefs(mergeParameters(pathLevelParams, ownParams), spec, /* @__PURE__ */ new Set()),
+        ...op["requestBody"] !== void 0 ? { requestBody: dereferenceLocalRefs(op["requestBody"], spec, /* @__PURE__ */ new Set()) } : {},
+        responses: typeof op["responses"] === "object" && op["responses"] !== null ? dereferenceLocalRefs(op["responses"], spec, /* @__PURE__ */ new Set()) : {}
       });
     }
   }
@@ -3745,7 +3787,6 @@ ${c.body}`).join("\n\n");
 
 // src/sqlite_query.ts
 import * as fs2 from "node:fs";
-import Database from "better-sqlite3";
 var SQLITE_QUERY_ROW_CAP = 5e3;
 var SQLITE_MAGIC = Buffer.from([83, 81, 76, 105, 116, 101, 32, 102, 111, 114, 109, 97, 116, 32, 51, 0]);
 function readMagicBytes(filePath) {
@@ -4930,7 +4971,7 @@ function loadTs() {
   }
   return _ts;
 }
-function isAvailable() {
+function isAvailable2() {
   return loadTs() !== null;
 }
 function loadError() {
@@ -5094,6 +5135,8 @@ function findIdentifierNearPosition(ts, sourceFile, line0, position, name) {
 
 // src/read_commands.ts
 var DIDYOUMEAN_LIMIT = 5;
+var SYMBOL_PREVIEW_LINES = 5;
+var AMBIGUOUS_HEADING_LIMIT = 10;
 var TYPO_TWO_EDIT_MIN_LEN = 8;
 var TYPO_MAX_QUERY_LEN = 64;
 var MIN_REVERSE_MATCH_LEN = 3;
@@ -5382,13 +5425,14 @@ function filterSimilarHeadings(available, query) {
   return sortByLengthCloseness(matched, query);
 }
 function didYouMean(candidates) {
-  if (candidates.length === 0) return "";
+  const unique = [...new Set(candidates)];
+  if (unique.length === 0) return "";
   const lines = ["Did you mean:"];
-  for (const c of candidates.slice(0, DIDYOUMEAN_LIMIT)) {
+  for (const c of unique.slice(0, DIDYOUMEAN_LIMIT)) {
     lines.push(`  - ${c}`);
   }
-  if (candidates.length > DIDYOUMEAN_LIMIT) {
-    lines.push(`  (${candidates.length - DIDYOUMEAN_LIMIT} more not shown)`);
+  if (unique.length > DIDYOUMEAN_LIMIT) {
+    lines.push(`  (${unique.length - DIDYOUMEAN_LIMIT} more not shown)`);
   }
   return lines.join("\n");
 }
@@ -5644,9 +5688,13 @@ ${emptyIndexMessage(emptyIndexRoot)}`;
     const goneTag = fileIsGone(sym.filePath) ? `  ${DELETED_TAG}` : "";
     const header = `# ${sym.name} (${sym.kind}) \u2014 ${toDisplayPath(symbolDisplayRoot, sym.filePath)}:${sym.lineStart}-${sym.lineEnd}${statsStr}${goneTag}`;
     const body = resolveBody(sym);
-    const preview = body.split(/\r?\n/).slice(0, 5).join("\n");
+    const bodyLines = body.split(/\r?\n/);
+    const preview = bodyLines.slice(0, SYMBOL_PREVIEW_LINES).join("\n");
+    const dropped = bodyLines.length - SYMBOL_PREVIEW_LINES;
+    const elided = dropped > 0 ? `
+  ...(${countNoun(dropped, "more line")}; full body: token-goat read "${toDisplayPath(symbolDisplayRoot, sym.filePath)}::${sym.name}")` : "";
     return preview.trim() !== "" ? `${header}
-${preview}` : header;
+${preview}${elided}` : header;
   });
   const warning = opts.file !== void 0 ? staleWarning(resolveIndexPath(opts.file, opts.projectRoot ?? process.cwd())) : "";
   const text = guardText(warning + blocks.join("\n\n"), "symbol");
@@ -6018,6 +6066,18 @@ function runSection(opts) {
     if (!fs5.existsSync(filePath)) {
       return { text: `File not found: '${filePath}'`, code: 1 };
     }
+    const ordSpec = /^(.*?)#(\d+)$/.exec(heading);
+    const ordBase = ordSpec?.[1]?.trim();
+    if (ordBase !== void 0 && ordBase.length > 0) {
+      const baseResult = readSection(filePath, ordBase, readFileText);
+      if (baseResult !== null) {
+        const total = baseResult.occurrences?.length ?? 1;
+        return {
+          text: `Heading '${ordBase}' has ${countNoun(total, "occurrence")} in '${specFilePath}'; valid ordinals are #1 to #${total}`,
+          code: 1
+        };
+      }
+    }
     const messages = [`Section '${heading}' not found in '${filePath}'`];
     const allHeadings = listSections(filePath, readFileText);
     const available = filterSimilarHeadings(allHeadings, heading);
@@ -6026,6 +6086,18 @@ function runSection(opts) {
     else messages.push(`Try: token-goat outline ${specFilePath}`);
     return { text: messages.join("\n"), code: 1 };
   }
+  if (result.occurrences !== void 0) {
+    const lines = [
+      `Ambiguous heading '${heading}' in '${specFilePath}': ${countNoun(result.occurrences.length, "heading")} match. Retry with one of the qualified commands below to pick one:`
+    ];
+    for (const [i, line] of result.occurrences.slice(0, AMBIGUOUS_HEADING_LIMIT).entries()) {
+      lines.push(`  - line ${line}  ->  token-goat section "${specFilePath}::${heading}#${i + 1}"`);
+    }
+    if (result.occurrences.length > AMBIGUOUS_HEADING_LIMIT) {
+      lines.push(`  (${result.occurrences.length - AMBIGUOUS_HEADING_LIMIT} more not shown)`);
+    }
+    return { text: lines.join("\n"), code: 1 };
+  }
   const kind = result.redirectedFrom !== void 0 ? "section_replacement" : "section_read";
   const fullSourceBytes = sumFileSizes([filePath]);
   if (opts.json === true) {
@@ -6145,40 +6217,15 @@ function refsSpecFiles(spec) {
   const { file } = parseMultiRefsSpec(spec);
   return file === void 0 ? [] : [file];
 }
-function runRefs(opts) {
-  if (opts.limit !== void 0 && opts.limit <= 0) {
-    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
-    return 1;
-  }
-  if (opts.top !== void 0 && opts.top <= 0) {
-    emitErr(`--top must be a positive number, got: ${opts.top}`);
-    return 1;
-  }
-  const confinedRoot = confinedProjectRoot();
-  if (confinedRoot !== null) {
-    const projectDenial = opts.projectRoot === void 0 ? null : confinementRefusal("--project", opts.projectRoot, confinedRoot);
-    if (projectDenial !== null) {
-      emitErr(projectDenial);
-      return 1;
-    }
-    for (const file2 of refsSpecFiles(opts.spec)) {
-      const denial = confinementRefusal("This file", resolveIndexPath(file2, opts.projectRoot ?? process.cwd()), confinedRoot);
-      if (denial !== null) {
-        emitErr(denial);
-        return 1;
-      }
-    }
-  }
-  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
-  if (crossFilePairs !== null) return runRefsCrossFile(crossFilePairs, opts);
-  const { file, symbols } = parseMultiRefsSpec(opts.spec);
-  if (symbols.length <= 1) return runRefsSingle(opts);
+function renderRefsTargets(targets, opts, {
+  annotateHiddenByGrep
+}) {
   const jsonOut = {};
   let anyFound = false;
   const lines = [];
   const refFilePaths = [];
-  for (const sym of symbols) {
-    const queryOpts = { name: sym };
+  for (const { file, symbol, key } of targets) {
+    const queryOpts = { name: symbol };
     if (opts.excludeTests === true || opts.grep !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
     else if (opts.limit !== void 0) queryOpts.limit = opts.limit;
     else if (opts.top !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
@@ -6186,7 +6233,7 @@ function runRefs(opts) {
     if (rootDir !== void 0) queryOpts.rootDir = rootDir;
     const scanned = queryRefs(queryOpts);
     const preScanCount = scanned.length;
-    let results = applyTypedRefsTier(sym, file, scanned);
+    let results = applyTypedRefsTier(symbol, file, scanned);
     let suppressed = 0;
     if (opts.excludeTests === true) {
       const f = applyExcludeTestsFilter(results);
@@ -6205,25 +6252,25 @@ function runRefs(opts) {
     refFilePaths.push(...results.map((r) => r.filePath));
     if (opts.json === true) {
       const hiddenByGrep = matchesGrep !== void 0 ? preGrepCount - (filteredTotal ?? results.length) : 0;
-      const withHidden = (payload) => ({ ...payload, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} });
+      const withHidden = (payload) => ({ ...payload, ...annotateHiddenByGrep && hiddenByGrep > 0 ? { hiddenByGrep } : {} });
       if (opts.top !== void 0) {
-        jsonOut[sym] = withHidden(topFilesJsonPayload(results, opts.top));
+        jsonOut[key] = withHidden(topFilesJsonPayload(results, opts.top));
       } else {
         const capped = guardJsonRows(results);
         const trueTotal = opts.excludeTests === true || matchesGrep !== void 0 ? filteredTotal ?? results.length : countRefs(queryOpts);
-        jsonOut[sym] = withHidden({ items: refsJsonItems(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal });
+        jsonOut[key] = withHidden({ items: refsJsonItems(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal });
       }
       continue;
     }
     if (results.length === 0) {
       if (matchesGrep !== void 0 && preGrepCount > 0) {
-        lines.push(`${sym}: ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references").trim()}`);
+        lines.push(`${key}: ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references").trim()}`);
         continue;
       }
-      lines.push(opts.excludeTests === true && suppressed > 0 ? `${sym}: (no non-test references found; ${excludeTestsHiddenNote(suppressed)})` : `${sym}: (no references found)`);
+      lines.push(opts.excludeTests === true && suppressed > 0 ? `${key}: (no non-test references found; ${excludeTestsHiddenNote(suppressed)})` : `${key}: (no references found)`);
       continue;
     }
-    lines.push(`${sym}:`);
+    lines.push(`${key}:`);
     if (opts.top !== void 0) {
       lines.push(...renderTopFilesSummary(results, opts.top, suppressed));
     } else if (opts.callers === true) {
@@ -6256,90 +6303,50 @@ function runRefs(opts) {
   if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text, opts.spec);
   return anyFound ? 0 : 1;
 }
-function runRefsCrossFile(pairs, opts) {
-  const distinctFiles = new Set(pairs.map((p) => p.file));
-  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
-  const jsonOut = {};
-  let anyFound = false;
-  const lines = [];
-  const refFilePaths = [];
-  for (const { file, symbol } of pairs) {
-    const key = keyFor({ file, symbol });
-    const queryOpts = { name: symbol };
-    if (opts.excludeTests === true || opts.grep !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
-    else if (opts.limit !== void 0) queryOpts.limit = opts.limit;
-    else if (opts.top !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
-    const rootDir = refsRootDir(opts);
-    if (rootDir !== void 0) queryOpts.rootDir = rootDir;
-    const scanned = queryRefs(queryOpts);
-    const preScanCount = scanned.length;
-    let results = applyTypedRefsTier(symbol, file, scanned);
-    let suppressed = 0;
-    if (opts.excludeTests === true) {
-      const f = applyExcludeTestsFilter(results);
-      suppressed = f.suppressed;
-      results = f.refs;
-    }
-    const preGrepCount = results.length;
-    const matchesGrep = refGrepFilter(opts.grep);
-    if (matchesGrep !== void 0) results = results.filter(matchesGrep);
-    let filteredTotal;
-    if (opts.excludeTests === true || matchesGrep !== void 0) filteredTotal = results.length;
-    if ((opts.excludeTests === true || matchesGrep !== void 0) && opts.top === void 0) {
-      results = results.slice(0, opts.limit ?? 100);
-    }
-    if (results.length > 0) anyFound = true;
-    refFilePaths.push(...results.map((r) => r.filePath));
-    if (opts.json === true) {
-      if (opts.top !== void 0) {
-        jsonOut[key] = topFilesJsonPayload(results, opts.top);
-      } else {
-        const capped = guardJsonRows(results);
-        const trueTotal = opts.excludeTests === true || matchesGrep !== void 0 ? filteredTotal ?? results.length : countRefs(queryOpts);
-        jsonOut[key] = { items: refsJsonItems(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
-      }
-      continue;
+function runRefs(opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    return 1;
+  }
+  if (opts.top !== void 0 && opts.top <= 0) {
+    emitErr(`--top must be a positive number, got: ${opts.top}`);
+    return 1;
+  }
+  const confinedRoot = confinedProjectRoot();
+  if (confinedRoot !== null) {
+    const projectDenial = opts.projectRoot === void 0 ? null : confinementRefusal("--project", opts.projectRoot, confinedRoot);
+    if (projectDenial !== null) {
+      emitErr(projectDenial);
+      return 1;
     }
-    if (results.length === 0) {
-      if (matchesGrep !== void 0 && preGrepCount > 0) {
-        lines.push(`${key}: ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references").trim()}`);
-        continue;
+    for (const file2 of refsSpecFiles(opts.spec)) {
+      const denial = confinementRefusal("This file", resolveIndexPath(file2, opts.projectRoot ?? process.cwd()), confinedRoot);
+      if (denial !== null) {
+        emitErr(denial);
+        return 1;
       }
-      lines.push(opts.excludeTests === true && suppressed > 0 ? `${key}: (no non-test references found; ${excludeTestsHiddenNote(suppressed)})` : `${key}: (no references found)`);
-      continue;
-    }
-    lines.push(`${key}:`);
-    if (opts.top !== void 0) {
-      lines.push(...renderTopFilesSummary(results, opts.top, suppressed));
-    } else if (opts.callers === true) {
-      if (opts.excludeTests === true && suppressed > 0) lines.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
-      lines.push(...renderCallerGroups(results, opts.context ?? 0));
-    } else {
-      if (opts.excludeTests === true && suppressed > 0) lines.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
-      for (const ref of results) lines.push(...renderRefLines(ref, opts.context ?? 0));
     }
-    if (opts.top === void 0) {
-      const notice = truncationNotice(
-        results.length,
-        opts.limit ?? 100,
-        () => refsTotal(opts.excludeTests === true || matchesGrep !== void 0, filteredTotal, results.length, () => countRefs(queryOpts), preScanCount),
-        "references",
-        "--limit"
-      );
-      if (notice !== null) lines.push(`  token-goat: ${notice}`);
-    }
-  }
-  const fullSourceBytes = sumFileSizes(refFilePaths);
-  if (opts.json === true) {
-    const text2 = JSON.stringify(jsonOut, null, 2);
-    emit(text2);
-    if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text2, opts.spec);
-    return anyFound ? 0 : 1;
   }
-  const text = lines.join("\n");
-  emitGuarded(text, "symbol");
-  if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text, opts.spec);
-  return anyFound ? 0 : 1;
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) return runRefsCrossFile(crossFilePairs, opts);
+  const { file, symbols } = parseMultiRefsSpec(opts.spec);
+  if (symbols.length <= 1) return runRefsSingle(opts);
+  return renderRefsTargets(
+    symbols.map((symbol) => ({ file, symbol, key: symbol })),
+    opts,
+    { annotateHiddenByGrep: true }
+  );
+}
+function runRefsCrossFile(pairs, opts) {
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  return renderRefsTargets(
+    pairs.map((p) => ({ file: p.file, symbol: p.symbol, key: keyFor(p) })),
+    opts,
+    // Not annotated today; renderRefsTargets's own option doc explains why that is a preserved
+    // divergence rather than a decision.
+    { annotateHiddenByGrep: false }
+  );
 }
 function runRefsSingle(opts) {
   const { file, symbol } = parseReadSpec(opts.spec);
@@ -6801,8 +6808,29 @@ function runQueryCommand(opts, parse, formatLabel, guardTag, kind) {
 function runJsonQuery(opts) {
   return runQueryCommand(opts, JSON.parse, "JSON", "json-query", "json_query");
 }
+function isPlainObject2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+function resolveYamlMergeKeys(node) {
+  if (Array.isArray(node)) return node.map(resolveYamlMergeKeys);
+  if (!isPlainObject2(node)) return node;
+  const merged = {};
+  const mergeVal = node["<<"];
+  if (mergeVal !== void 0) {
+    const sources = Array.isArray(mergeVal) ? mergeVal : [mergeVal];
+    for (const src of [...sources].reverse()) {
+      const resolved = resolveYamlMergeKeys(src);
+      if (isPlainObject2(resolved)) Object.assign(merged, resolved);
+    }
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "<<") continue;
+    merged[key] = resolveYamlMergeKeys(value);
+  }
+  return merged;
+}
 function parseYamlDocument(text) {
-  const docs = loadAll(text);
+  const docs = loadAll(text).map(resolveYamlMergeKeys);
   return docs.length === 1 ? docs[0] : docs;
 }
 function runYamlOutline(opts) {
@@ -7305,6 +7333,13 @@ async function runPdfMeta(file) {
   const data = fs5.readFileSync(file);
   return extractPdfMeta(new Uint8Array(data));
 }
+async function runPdfLocate(file, pattern, opts) {
+  if (!fileExists(file)) {
+    throw new Error(`Could not read: ${file}`);
+  }
+  const data = fs5.readFileSync(file);
+  return locatePdfPages(new Uint8Array(data), pattern, opts);
+}
 async function runImageMeta(file) {
   if (!fileExists(file)) {
     throw new Error(`Could not read: ${file}`);
@@ -7314,7 +7349,15 @@ async function runImageMeta(file) {
   }
   const data = fs5.readFileSync(file);
   const bytes = data.length;
-  const probe = await probeImageMeta(data);
+  let probe;
+  try {
+    probe = await probeImageMeta(data);
+  } catch (e) {
+    if (e instanceof ImageDecodeError) {
+      throw new Error(`${file} is not a readable image: ${e.message}`, { cause: e });
+    }
+    throw e;
+  }
   if (probe === null) {
     return { width: 0, height: 0, format: null, bytes, sharpAvailable: false, wouldShrink: false, shrunkBytes: null };
   }
@@ -7339,6 +7382,9 @@ async function runImageText(file) {
   const data = fs5.readFileSync(file);
   const ocr = await ocrImage(data);
   if (ocr === null) {
+    if (isOcrEngineAvailable()) {
+      throw new Error(`${file} could not be processed by OCR (unreadable image, timeout, or offline model fetch)`);
+    }
     return { ocrAvailable: false, confidence: 0, chars: 0, textHeavy: false, text: null };
   }
   const minConfidence = loadConfig().image_shrink.ocr_min_confidence;
@@ -7569,7 +7615,15 @@ function runListSections(opts) {
   }
   const preFilterCount = sections.length;
   const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
-  const filtered = matchesGrep !== void 0 ? sections.filter((s) => matchesGrep(s)) : sections;
+  const totals = /* @__PURE__ */ new Map();
+  for (const heading of sections) totals.set(heading, (totals.get(heading) ?? 0) + 1);
+  const seen = /* @__PURE__ */ new Map();
+  const labelled = sections.map((heading) => {
+    const nth = (seen.get(heading) ?? 0) + 1;
+    seen.set(heading, nth);
+    return (totals.get(heading) ?? 1) > 1 ? `${heading}#${nth}` : heading;
+  });
+  const filtered = matchesGrep !== void 0 ? labelled.filter((_, i) => matchesGrep(sections[i] ?? "")) : labelled;
   if (filtered.length === 0) {
     if (opts.json === true) {
       emit(JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2));
@@ -7583,8 +7637,8 @@ function runListSections(opts) {
     emit(JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, null, 2));
     return 0;
   }
-  for (const s of filtered) {
-    emit(s);
+  for (const heading of filtered) {
+    emit(heading);
   }
   return 0;
 }
@@ -8781,15 +8835,27 @@ async function runSemantic(query, opts) {
     }
   }
   const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
+  if (!isAvailable()) {
+    console.warn(
+      "Matching on meaning is off (onnxruntime-node is not installed); these results come from keyword search alone. Install it with: npm install -g onnxruntime-node (drop -g if token-goat is a project dependency)"
+    );
+  }
   const overFetchForMerge = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
-  const rawHits = await searchSemantic(
-    getDb(globalDbPath()),
-    query,
-    overFetchForMerge,
-    void 0,
-    void 0,
-    rootDir
-  );
+  let rawHits = [];
+  try {
+    rawHits = await searchSemantic(
+      getDb(globalDbPath()),
+      query,
+      overFetchForMerge,
+      void 0,
+      void 0,
+      rootDir
+    );
+  } catch (e) {
+    console.warn(
+      `Matching on meaning is off (${extractErrorMessage(e)}); these results come from keyword search alone.`
+    );
+  }
   const mergedHits = mergeNearbyHits(rawHits);
   const overFetchFts = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
   const ftsRows = searchSymbolsFts(query, overFetchFts, void 0, rootDir);
@@ -9761,6 +9827,14 @@ function runScope(opts) {
   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}`);
+      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;
@@ -10096,9 +10170,9 @@ function runBlame(opts) {
   }
   if (opts.json === true) {
     const lines = raw.split("\n").filter((l) => l.length > 0).map((l) => {
-      const m = /^([0-9a-f]+)\s+\((.+?)\s+(\d{4}-\d{2}-\d{2}[^)]*)\s+(\d+)\)(.*)/.exec(l);
+      const m = /^(\^?)([0-9a-f]+)\s+\((.+?)\s+(\d{4}-\d{2}-\d{2}[^)]*)\s+(\d+)\)(.*)/.exec(l);
       if (!m) return { raw: l };
-      return { commit: m[1], author: (m[2] ?? "").trim(), date: (m[3] ?? "").trim(), line: Number.parseInt(m[4] ?? "0", 10), content: m[5] };
+      return { commit: m[2], boundary: m[1] === "^", author: (m[3] ?? "").trim(), date: (m[4] ?? "").trim(), line: Number.parseInt(m[5] ?? "0", 10), content: m[6] };
     });
     emit2(JSON.stringify({ symbol: sym.name, file: filePath, lines }, null, 2));
     return 0;
@@ -10340,8 +10414,9 @@ export {
   symbolNamesInFile,
   computeFileFingerprint,
   upsertNote,
-  isAvailable,
+  isAvailable2 as isAvailable,
   loadError,
+  AMBIGUOUS_HEADING_LIMIT,
   ConfinementIdentityError,
   ABSENT_PIN,
   pinKey,
@@ -10381,6 +10456,7 @@ export {
   runPdfExtractText,
   runPdfOutline,
   runPdfMeta,
+  runPdfLocate,
   runImageMeta,
   runImageText,
   runScreenshot,