sweet-search 2.6.14 → 2.6.15

package/core/infrastructure/code-graph-repository.js

@@ -312,6 +312,77 @@ export class CodeGraphRepository {
     }
   }
 
+  /**
+   * Find the named entities immediately ADJACENT to a shown line window in
+   * the same file: the nearest ones lying fully ABOVE the window
+   * (end_line < startLine) and the nearest ones starting BELOW it
+   * (start_line > endLine). Powers the agent-format same-file span map —
+   * the pointer that tells an agent which sibling symbols sit just outside
+   * the chunk window it was shown.
+   *
+   * Entities enclosing the window (e.g. the surrounding class) never match
+   * either predicate, so results are true siblings. Inner entities contained
+   * in an already-kept row (closures inside the adjacent function) are
+   * filtered so the map names outermost neighbors only.
+   *
+   * @param {string} filePath
+   * @param {number} startLine - first shown line (1-based)
+   * @param {number} endLine - last shown line (1-based)
+   * @param {{ perSide?: number }} [opts] - max entities per side (default 2)
+   * @returns {{ above: Array<{id,name,type,startLine,endLine,parentClass}>,
+   *             below: Array<{id,name,type,startLine,endLine,parentClass}> }}
+   */
+  findAdjacentEntities(filePath, startLine, endLine, opts = {}) {
+    const perSide = opts.perSide ?? 2;
+    const empty = { above: [], below: [] };
+    if (!filePath || !Number.isFinite(startLine) || !Number.isFinite(endLine)) return empty;
+    const db = this._open();
+    if (!db) return empty;
+    const mapRow = row => ({
+      id: row.id,
+      name: row.name,
+      type: row.type,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      parentClass: row.parent_class || null,
+    });
+    // Keep outermost neighbors: drop rows contained in an already-kept row.
+    const keepOutermost = rows => {
+      const kept = [];
+      for (const row of rows) {
+        if (kept.some(k => row.start_line >= k.start_line && row.end_line <= k.end_line)) continue;
+        kept.push(row);
+        if (kept.length >= perSide) break;
+      }
+      return kept.map(mapRow);
+    };
+    try {
+      const aboveRows = prepareCached(db, `
+        SELECT id, name, type, start_line, end_line, parent_class
+        FROM entities
+        WHERE file_path = ?
+          AND end_line < ?
+          AND name IS NOT NULL AND name != ''
+          AND ${this._entityVisibilitySql(db)}
+        ORDER BY end_line DESC, start_line ASC
+        LIMIT 8
+      `).all(filePath, startLine, ...this._entityVisibilityParams(db));
+      const belowRows = prepareCached(db, `
+        SELECT id, name, type, start_line, end_line, parent_class
+        FROM entities
+        WHERE file_path = ?
+          AND start_line > ?
+          AND name IS NOT NULL AND name != ''
+          AND ${this._entityVisibilitySql(db)}
+        ORDER BY start_line ASC, end_line DESC
+        LIMIT 8
+      `).all(filePath, endLine, ...this._entityVisibilityParams(db));
+      return { above: keepOutermost(aboveRows), below: keepOutermost(belowRows) };
+    } catch {
+      return empty;
+    }
+  }
+
   /**
    * Get a single entity by id, with file:line metadata.
    *

package/core/search/context-expander.js

@@ -1931,6 +1931,40 @@ export function selectAgentBudget(format, signals, opts = {}) {
  *   'no-syntax-expansion', 'no-header', 'no-diversity', 'no-adaptive-budget'
  * @returns {object} Agent mode response
  */
+/**
+ * Same-file span map (2026-07, within-file blind-spot fix). When the top-1
+ * pack entry is a WINDOWED view of a file (kind chunk/sandwich/syntax — not
+ * a fully-shown symbol) and the sufficiency verdict is not a clear YES, one
+ * compact line names the sibling symbols immediately above/below the shown
+ * window so the agent can sweep the fix surface instead of leaving the file
+ * (the fhir/sushi-1175 miss shape: right file, bug 30 lines above the
+ * window). Names+kinds+lines only — never bodies; ~25-45 tokens.
+ *
+ * @param {{ file:string, startLine:number, endLine:number }} top - top-1 agent result
+ * @param {{ above:Array, below:Array }} adjacent - findAdjacentEntities() result
+ * @returns {{ rendered:string, tokens:number, neighbors:Array }|null}
+ */
+export function buildSameFileMap(top, adjacent) {
+  const above = adjacent?.above || [];
+  const below = adjacent?.below || [];
+  if (above.length === 0 && below.length === 0) return null;
+  const shortType = t => (t === 'function' ? 'fn' : (t || 'sym'));
+  const fmt = (e, pos) => `${e.name} (${shortType(e.type)} ${e.startLine}-${e.endLine} ${pos})`;
+  const neighbors = [
+    ...above.map(e => ({ ...e, position: 'above' })),
+    ...below.map(e => ({ ...e, position: 'below' })),
+  ];
+  const parts = [
+    ...above.map(e => fmt(e, 'above')),
+    ...below.map(e => fmt(e, 'below')),
+  ];
+  // Placeholder-style drill-in hint (the v2.6.13 `ss-grep "<regex>" --in
+  // <file>` convention, which agents demonstrably follow) — embedding the
+  // live query costs ~25-30 tokens per pack for no extra signal.
+  const rendered = `# same file: ${parts.join(' · ')} — sweep: ss-semantic ${top.file} "<query>"`;
+  return { rendered, tokens: estimateTokens(rendered), neighbors };
+}
+
 export function packageForAgent(rankedResults, searchStats, opts) {
   const {
     query,
@@ -2347,6 +2381,53 @@ export function packageForAgent(rankedResults, searchStats, opts) {
     unresolvedExternalCount = sufficiency.unresolvedExternalCount || 0;
   }
 
+  // Phase 7: same-file span map (top-1 only). Emitted ONLY when the verdict
+  // is not a clear YES (composes with the query-conditioned verdict: the map
+  // supplies the "where to look next" exactly when the engine says "keep
+  // looking") AND top-1 is a windowed view (kind != 'full' — fully-shown
+  // symbols stay byte-identical) AND the line fits the remaining tier
+  // budget (dropped on overflow, never a truncated pack). Its tokens are
+  // counted inside tokensUsed. Disabled by 'no-same-file-map' ablation.
+  if (!ablations.has('no-same-file-map')
+      && agentResults.length > 0
+      && sufficiencyVerdict !== 'yes'
+      && codeGraphRepo
+      && typeof codeGraphRepo.findAdjacentEntities === 'function') {
+    const top = agentResults[0];
+    const windowed = top.code
+      && top.presentation !== 'summary'
+      && top.expansionKind
+      && top.expansionKind !== 'full'
+      && top.file
+      && Number.isFinite(top.startLine)
+      && Number.isFinite(top.endLine);
+    if (windowed) {
+      let adjacent = null;
+      try {
+        adjacent = codeGraphRepo.findAdjacentEntities(top.file, top.startLine, top.endLine, { perSide: 2 });
+      } catch { adjacent = null; }
+      // Don't name neighbors whose code is ALREADY visible in the pack —
+      // locality clustering pulls same-file companions to ranks 2-3; a map
+      // entry for a shown span is pure noise.
+      if (adjacent) {
+        const shownSameFile = agentResults.filter(r =>
+          r !== top && r.code && r.file === top.file
+          && Number.isFinite(r.startLine) && Number.isFinite(r.endLine));
+        const overlapsShown = e => shownSameFile.some(r =>
+          e.startLine <= r.endLine && e.endLine >= r.startLine);
+        adjacent = {
+          above: adjacent.above.filter(e => !overlapsShown(e)),
+          below: adjacent.below.filter(e => !overlapsShown(e)),
+        };
+      }
+      const map = adjacent ? buildSameFileMap(top, adjacent) : null;
+      if (map && map.tokens <= Math.max(0, tokenBudget - tokensUsed)) {
+        top.sameFile = map;
+        tokensUsed += map.tokens;
+      }
+    }
+  }
+
   return {
     query,
     regex,

package/core/search/search-read.js

@@ -239,6 +239,48 @@ function _attachIndexMetadata(filePathRel, projectRoot) {
   return { indexed: true, chunks, language };
 }
 
+// ---------------------------------------------------------------------------
+// Remainder definition sniffing — fallback symbol names for the "what
+// remains" trailer when the index has no named chunks in the unread span
+// (e.g. C++ files where the chunker recorded `name: null`). Scans ONLY the
+// remainder lines of the buffer already in memory: zero I/O, capped.
+// ---------------------------------------------------------------------------
+
+const SNIFF_MAX_LINES = 4000;
+const UNREAD_SYMBOLS_MAX = 5;        // hard cap on named symbols in the trailer
+const UNREAD_SYMBOLS_MIN_LINES = 20; // smaller remainders get the short form
+const C_FAMILY_EXTS = new Set(['.c', '.h', '.cc', '.cpp', '.cxx', '.hpp', '.hh', '.hxx', '.java', '.cs', '.m', '.mm']);
+
+// Keyword-introduced definitions (Python/Ruby/JS/TS/Go/Rust/Kotlin/PHP/...).
+const KEYWORD_DEF_RE = /^\s*(?:export\s+|default\s+|pub(?:\([^)]*\))?\s+|static\s+|async\s+|abstract\s+|final\s+|public\s+|private\s+|protected\s+|inline\s+|constexpr\s+|unsafe\s+|override\s+|open\s+|sealed\s+)*(?:def|fn|func|function\*?|class|struct|enum|trait|interface|impl|object|module|proc)\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*(?:(?:::|\.)[A-Za-z_][\w]*)*)/;
+// C-family definitions at low indent: `[return-type] Qualified::name(args...`
+// with no trailing `;` (declarations) — captures the identifier before the
+// first `(`. The return-type prefix is lazy so qualification stays intact.
+const C_DEF_RE = /^(?:[A-Za-z_][\w:<>,*&~\s]*?[\s*&]+)?((?:[A-Za-z_~][\w]*::)*(?:~?[A-Za-z_][\w]*|operator\s*[^\s(]{1,3}))\s*\(/;
+const C_CONTROL_RE = /^\s*(?:if|for|while|switch|return|else|do|catch|case|sizeof|new|delete|throw|goto|using|typedef)\b/;
+
+function _sniffRemainderDefinitions(text, isCFamily) {
+  const names = [];
+  const seen = new Set();
+  const lines = text.split('\n', SNIFF_MAX_LINES);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!/\S/.test(line)) continue;
+    let name = null;
+    const kw = line.match(KEYWORD_DEF_RE);
+    if (kw) name = kw[1];
+    else if (isCFamily && /^[A-Za-z_]/.test(line) && !line.trimEnd().endsWith(';') && !C_CONTROL_RE.test(line)) {
+      const m = line.match(C_DEF_RE);
+      if (m) name = m[1].replace(/\s+/g, '');
+    }
+    if (name && !seen.has(name)) {
+      seen.add(name);
+      names.push({ symbol: name, type: null, startLine: i + 1 }); // startLine relative; caller offsets
+    }
+  }
+  return names;
+}
+
 // ---------------------------------------------------------------------------
 // Public API — single read
 // ---------------------------------------------------------------------------
@@ -293,6 +335,47 @@ async function _readFileUnpinned(req) {
     language = meta.language;
   }
 
+  // "What remains" trailer data (2026-07, within-file blind-spot fix): when
+  // a range read stops before EOF, record what the UNREAD remainder below
+  // the window contains — computed from the full chunk table BEFORE the
+  // overlap-narrowing just below. A bare "(lines a-b of N)" marker is
+  // provably ignored by agents (the botan-2738 shape: three reads, never
+  // past line 205 of 272, fix surface below); naming the symbols is what
+  // makes the remainder actionable. Whole-file reads and read-to-EOF stay
+  // byte-identical (unreadBelow stays null).
+  let unreadBelow = null;
+  if (wantsRange && sliced.totalLines > 0 && sliced.endLine < sliced.totalLines) {
+    // Token diet: a tiny remainder needs no symbol list — the range plus the
+    // continue command IS the affordance; names only earn their tokens when
+    // the unread span is big enough to hide a sibling branch.
+    const remainderLines = sliced.totalLines - sliced.endLine;
+    const seen = new Set();
+    let symbols = [];
+    if (remainderLines >= UNREAD_SYMBOLS_MIN_LINES) {
+      for (const c of chunks) {
+        if (c.startLine == null || c.startLine <= sliced.endLine) continue;
+        if (!c.symbol || seen.has(c.symbol)) continue;
+        seen.add(c.symbol);
+        symbols.push({ symbol: c.symbol, type: c.type ?? null, startLine: c.startLine });
+      }
+      // Index had no named chunks in the remainder (common for C/C++ where the
+      // chunker stores name:null) — sniff definition lines from the in-memory
+      // buffer instead. Zero I/O; capped at SNIFF_MAX_LINES.
+      if (symbols.length === 0 && disk.text != null) {
+        const remainder = _sliceLines(disk.text, disk.lineOffsets, sliced.endLine + 1, sliced.totalLines);
+        const isCFamily = C_FAMILY_EXTS.has(path.extname(absPath).toLowerCase());
+        symbols = _sniffRemainderDefinitions(remainder.text, isCFamily)
+          .map(s => ({ ...s, startLine: sliced.endLine + s.startLine }));
+      }
+    }
+    unreadBelow = {
+      startLine: sliced.endLine + 1,
+      endLine: sliced.totalLines,
+      symbols: symbols.slice(0, UNREAD_SYMBOLS_MAX),
+      moreCount: Math.max(0, symbols.length - UNREAD_SYMBOLS_MAX),
+    };
+  }
+
   // If a line range was requested, narrow attached chunks to the overlap.
   if (wantsRange && chunks.length) {
     chunks = chunks.filter(c =>
@@ -315,6 +398,7 @@ async function _readFileUnpinned(req) {
     range: wantsRange ? { startLine: sliced.startLine, endLine: sliced.endLine } : null,
     text: sliced.text,
     chunks,
+    unreadBelow,
     timings: { totalMs: +(performance.now() - t0).toFixed(2) },
   };
 }
@@ -362,6 +446,28 @@ export async function readFiles(files, opts = {}) {
 // Formatting
 // ---------------------------------------------------------------------------
 
+/**
+ * Render the "what remains" trailer for a range read that stopped before
+ * EOF. Names the symbols in the unread remainder plus the exact continue
+ * command — the actionable form (a bare truncation marker is ignored;
+ * see the 2026-07 within-file design note). Returns '' when the read
+ * covered the whole file / reached EOF.
+ *
+ * @param {Object} result - readFile() result
+ * @param {{ command?: 'read'|'ss-read' }} [opts] - continue-command surface
+ * @returns {string} one line without trailing newline, or ''
+ */
+export function renderUnreadBelow(result, { command = 'read' } = {}) {
+  const u = result?.unreadBelow;
+  if (!u) return '';
+  const names = (u.symbols || []).map(s => s.symbol).join(', ');
+  const more = u.moreCount > 0 ? ` +${u.moreCount} more` : '';
+  const cont = command === 'ss-read'
+    ? `ss-read ${result.file} ${u.startLine} ${u.endLine}`
+    : `read ${result.file} ${u.startLine}-${u.endLine}`;
+  return `# unread below (${u.startLine}-${u.endLine})${names ? ': ' + names + more : ''} — continue: ${cont}`;
+}
+
 function _formatAgent(result) {
   if (!result.ok) {
     return `### ${result.file}\n[error] ${result.error}\n`;
@@ -377,7 +483,8 @@ function _formatAgent(result) {
       .filter(Boolean);
     if (names.length) symbolHint = `\nsymbols: ${names.join(', ')}`;
   }
-  return `### ${result.file}${range}${symbolHint}\n${fence}\n${result.text}\n\`\`\`\n`;
+  const remainder = renderUnreadBelow(result);
+  return `### ${result.file}${range}${symbolHint}\n${fence}\n${result.text}\n\`\`\`${remainder ? '\n' + remainder : ''}\n`;
 }
 
 export function formatReadResults(results, format = 'agent') {

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -242,6 +242,11 @@ async function cmdFind(rawArgs) {
     if (r.neighbors && r.neighbors.rendered) {
       process.stdout.write(`### related (1-hop graph, ~${r.neighbors.tokens} tok)\n${r.neighbors.rendered}\n`);
     }
+    // Same-file span map (top-1, windowed chunk, verdict != YES): sibling
+    // symbols just outside the shown window + a copy-paste drill-in command.
+    if (r.sameFile && r.sameFile.rendered) {
+      process.stdout.write(`${r.sameFile.rendered}\n`);
+    }
   }
   if (!response.results || response.results.length === 0) process.stdout.write('(no matches)\n');
   process.exit(0);
@@ -297,7 +302,7 @@ async function cmdRead(args) {
       }
     }
   }
-  const { readFile } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
+  const { readFile, renderUnreadBelow } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
   const r = await readFile({ path: file, projectRoot: PROJECT_ROOT, startLine: start ?? undefined, endLine: end ?? undefined });
   if (!r.ok) {
     process.stderr.write(`[ss-read] error: ${r.error}\n`);
@@ -305,7 +310,11 @@ async function cmdRead(args) {
   }
   const range = r.range ? ` (lines ${r.range.startLine}-${r.range.endLine} of ${r.totalLines})` : ` (${r.totalLines} lines)`;
   const fence = r.language ? '```' + r.language : '```';
-  process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`\n`);
+  // "What remains" trailer: on a range read that stops before EOF, one final
+  // line names the symbols in the unread remainder + the exact continue
+  // command (last line for recency — the actionable form of truncation).
+  const remainder = renderUnreadBelow(r, { command: 'ss-read' });
+  process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`${remainder ? '\n' + remainder : ''}\n`);
   process.exit(0);
 }
 
@@ -441,6 +450,11 @@ async function cmdAgentSearch(rawArgs) {
     if (r.neighbors && r.neighbors.rendered) {
       process.stdout.write(`### related (1-hop graph, ~${r.neighbors.tokens} tok)\n${r.neighbors.rendered}\n`);
     }
+    // Same-file span map (top-1, windowed chunk, verdict != YES): sibling
+    // symbols just outside the shown window + a copy-paste drill-in command.
+    if (r.sameFile && r.sameFile.rendered) {
+      process.stdout.write(`${r.sameFile.rendered}\n`);
+    }
   }
 
   if (!response.results || response.results.length === 0) {
@@ -479,6 +493,8 @@ async function cmdAgentSearch(rawArgs) {
     sufficiencyReasons: Array.isArray(response.sufficiencyReasons) ? response.sufficiencyReasons : null,
     unresolvedExternalCount: typeof response.unresolvedExternalCount === 'number'
       ? response.unresolvedExternalCount : null,
+    sameFileMapTokens: response.results?.[0]?.sameFile?.tokens ?? null,
+    sameFileNeighborCount: response.results?.[0]?.sameFile?.neighbors?.length ?? null,
   };
   process.stdout.write(`\n<<SS_ROUTE_META>>${JSON.stringify(meta)}\n`);
   process.exit(0);

package/mcp/read-tool.js

@@ -23,6 +23,16 @@ const ReadFileResultSchema = z.object({
     endLine: z.number().int().nullable().optional(),
     signature: z.string().nullable().optional(),
   })).optional(),
+  unreadBelow: z.object({
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+    symbols: z.array(z.object({
+      symbol: z.string(),
+      type: z.string().nullable().optional(),
+      startLine: z.number().int().nullable().optional(),
+    })),
+    moreCount: z.number().int(),
+  }).nullable().optional(),
   error: z.string().optional(),
   timings: z.object({ totalMs: z.number() }).optional(),
 });

package/mcp/tool-handlers.js

@@ -127,7 +127,14 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
           const header = `${r.rank}. ${r.file}:${r.startLine}-${r.endLine} (score: ${r.score.toFixed(3)}, ${r.presentation})`;
           const symbolInfo = r.symbol ? `\n   ${r.symbolType || 'symbol'}: ${r.symbol}` : '';
           const code = r.code ? `\n\`\`\`\n${r.code}\n\`\`\`` : '';
-          return header + symbolInfo + code;
+          // Same-file span map (top-1, windowed chunk, verdict != YES) —
+          // MCP phrasing references the MCP drill-in tool name.
+          const sameFile = (r.sameFile && r.sameFile.neighbors?.length)
+            ? `\n   Same file: ${r.sameFile.neighbors
+                .map(n => `${n.name} (${n.type === 'function' ? 'fn' : (n.type || 'sym')} ${n.startLine}-${n.endLine} ${n.position})`)
+                .join(' · ')} — sweep: read-semantic ${r.file}`
+            : '';
+          return header + symbolInfo + code + sameFile;
         });
 
       const summaries = agentResults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweet-search",
-  "version": "2.6.14",
+  "version": "2.6.15",
   "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
   "type": "module",
   "main": "core/search/sweet-search.js",
@@ -167,13 +167,13 @@
     "vitest": "^4.0.16"
   },
   "optionalDependencies": {
-    "@sweet-search/native-darwin-arm64": "2.6.14",
-    "@sweet-search/native-darwin-x64": "2.6.14",
-    "@sweet-search/native-linux-arm64-gnu": "2.6.14",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.6.14",
-    "@sweet-search/native-linux-x64-gnu": "2.6.14",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.6.14",
-    "@sweet-search/bg-priority": "2.6.14"
+    "@sweet-search/native-darwin-arm64": "2.6.15",
+    "@sweet-search/native-darwin-x64": "2.6.15",
+    "@sweet-search/native-linux-arm64-gnu": "2.6.15",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.6.15",
+    "@sweet-search/native-linux-x64-gnu": "2.6.15",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.6.15",
+    "@sweet-search/bg-priority": "2.6.15"
   },
   "engines": {
     "node": ">=18.0.0"