sweet-search 2.5.1 → 2.5.3

package/core/graph/hcgs-generator.js

@@ -399,12 +399,13 @@ async function generateSummariesForEntities(entityIds, options = {}) {
   } = options;
 
   const Database = (await import('better-sqlite3')).default;
-  const { applyReadPragmas } = await import('../infrastructure/db-utils.js');
+  const { applyReadPragmas, assertInClauseSize } = await import('../infrastructure/db-utils.js');
   const db = new Database(dbPath, { readonly: true });
   applyReadPragmas(db);
 
   try {
     // Fetch entities by IDs
+    assertInClauseSize(entityIds.length, 'hcgs-generator.fetchEntitiesByIds');
     const placeholders = entityIds.map(() => '?').join(',');
     const entities = db.prepare(`
       SELECT id, file_path, type, name, signature, doc_comment, parent_id, hierarchy_level

package/core/graph/index.js

@@ -11,6 +11,8 @@ export { default as communityDetector } from './community-detector.js';
 export * from './leiden-algorithm.js';
 export * from './repo-map.js';
 export { default as repoMap } from './repo-map.js';
+export * from './structural-context.js';
+export { default as StructuralContextBuilder } from './structural-context.js';
 export * from './hcgs-generator.js';
 export * from './summary-manager.js';
 export { default as summaryManager } from './summary-manager.js';

package/core/graph/repo-map.js

@@ -17,6 +17,16 @@ import Database from 'better-sqlite3';
 import path from 'path';
 import { DB_PATHS } from '../infrastructure/config/index.js';
 import { applyReadPragmas } from '../infrastructure/db-utils.js';
+import {
+  createCodeGraphVisibility,
+  entityVisibilityParams,
+  entityVisibilitySql,
+  readAdjacentManifest,
+  readAdjacentManifestEpoch,
+  relationshipVisibilityParams,
+  relationshipVisibilitySql,
+  resolveManifestCodeGraphPath,
+} from '../infrastructure/code-graph-visibility.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -119,24 +129,32 @@ export function pageRank(outEdges, allNodes, opts = {}) {
 /**
  * Load graph data from the code-graph.db SQLite database.
  * @param {string} [dbPath] - Path to code-graph.db
+ * @param {{ manifestEpoch?: number }} [opts]
  * @returns {{ entities: Array, relationships: Array }}
  */
-export function loadGraph(dbPath) {
-  const resolvedPath = dbPath || DB_PATHS.codeGraph;
+export function loadGraph(dbPath, opts = {}) {
+  const basePath = dbPath || DB_PATHS.codeGraph;
+  const manifest = opts.manifest || readAdjacentManifest(basePath);
+  const resolvedPath = resolveManifestCodeGraphPath(basePath, manifest);
   const db = new Database(resolvedPath, { readonly: true, timeout: 5000 });
   applyReadPragmas(db);
 
   try {
+    const manifestEpoch = Number.isInteger(opts.manifestEpoch)
+      ? opts.manifestEpoch
+      : (Number.isInteger(manifest?.epoch) ? manifest.epoch : readAdjacentManifestEpoch(resolvedPath));
+    const visibility = createCodeGraphVisibility(db, manifestEpoch);
     const entities = db.prepare(`
       SELECT id, file_path, type, name, signature, start_line, end_line
       FROM entities
-      WHERE stale_since IS NULL
-    `).all();
+      WHERE ${entityVisibilitySql(visibility)}
+    `).all(...entityVisibilityParams(visibility));
 
     const relationships = db.prepare(`
       SELECT source_id, target_id, target_name, type, weight
       FROM relationships
-    `).all();
+      WHERE ${relationshipVisibilitySql(visibility, '')}
+    `).all(...relationshipVisibilityParams(visibility));
 
     return { entities, relationships };
   } finally {
@@ -335,6 +353,7 @@ function buildMapText(entries) {
  * @param {string} [opts.dbPath] - Override code-graph.db path
  * @param {string[]} [opts.focusFiles] - Boost scores for entities in these files
  * @param {string[]} [opts.focusEntities] - Boost scores for these entity names
+ * @param {number} [opts.manifestEpoch] - Optional pinned manifest epoch for incremental readers
  * @returns {{ text: string, entityCount: number, fileCount: number, totalEntities: number, pageRankTimeMs: number }}
  */
 export function generateRepoMap(opts = {}) {
@@ -342,7 +361,10 @@ export function generateRepoMap(opts = {}) {
   const start = Date.now();
 
   // 1. Load graph from SQLite
-  const graph = loadGraph(opts.dbPath);
+  const graph = loadGraph(opts.dbPath, {
+    manifest: opts.manifest,
+    manifestEpoch: opts.manifestEpoch,
+  });
 
   if (graph.entities.length === 0) {
     return {

package/core/graph/structural-answer-cues.js

@@ -0,0 +1,168 @@
+import { stripNonCode } from './structural-callsite-hints.js';
+
+const STOP = new Set([
+  'const', 'let', 'var', 'return', 'function', 'export', 'import', 'from', 'null', 'true', 'false',
+  'this', 'self', 'if', 'else', 'for', 'while', 'switch', 'case', 'break', 'continue', 'typeof',
+  'string', 'number', 'boolean', 'undefined', 'object', 'class', 'struct', 'enum', 'trait', 'impl',
+  'pub', 'fn', 'func', 'mut', 'use', 'type', 'async', 'await', 'new', 'def', 'len', 'none', 'the', 'that', 'this', 'with',
+  'when', 'where', 'which', 'from', 'into', 'will', 'can', 'may', 'not', 'and', 'or',
+]);
+
+function terms(text) {
+  const out = new Map();
+  for (const m of String(text || '').matchAll(/[A-Za-z_$][A-Za-z0-9_$]{2,}/g)) {
+    const raw = m[0];
+    const key = raw.toLowerCase();
+    if (STOP.has(key)) continue;
+    const prev = out.get(key) || { raw, count: 0, score: 0 };
+    prev.count++;
+    prev.score += /[A-Z_]/.test(raw.slice(1)) || /^[A-Z]/.test(raw) ? 2 : 1;
+    out.set(key, prev);
+  }
+  return out;
+}
+
+function rankedTerms(target, hint) {
+  const found = terms(`${target.signature || ''}\n${target.summary || ''}\n${stripNonCode(target.code || '')}`);
+  const hintText = String(hint || '').toLowerCase();
+  for (const [key, value] of found) {
+    if (hintText.includes(key)) value.score += 4;
+    value.score += Math.min(4, value.count);
+  }
+  return [...found.values()]
+    .sort((a, b) => (b.score - a.score) || a.raw.localeCompare(b.raw))
+    .slice(0, 24)
+    .map(x => x.raw);
+}
+
+function shortItem(x) {
+  const loc = x.filePath ? `${x.filePath}:${x.startLine || '?'}` : 'external';
+  const edge = x.relationship ? `${x.relationship} ` : '';
+  return `${edge}${x.name} (${loc})`;
+}
+
+function shortPath(p) {
+  return p.path.map(x => `${x.name}${x.filePath ? `@${x.filePath}:${x.startLine || '?'}` : '@external'}`).join(' -> ');
+}
+
+function isLowSignalPath(filePath = '') {
+  return /(^|\/)(__tests__|tests?|spec|fixtures|examples?|docs?)(\/|$)|[-_.](test|spec)\.[cm]?[jt]sx?$|_test\.go$/.test(filePath);
+}
+
+function preferProduction(items, isLowSignal) {
+  const primary = items.filter(item => !isLowSignal(item));
+  return primary.length ? primary : items;
+}
+
+function addSymbol(out, name) {
+  if (name && !out.includes(name)) out.push(name);
+}
+
+function keySymbols(target, hint, callers, callees, impactPaths) {
+  const q = String(hint || '').toLowerCase();
+  const out = [];
+  addSymbol(out, target.name);
+  const wantsCallers = /\b(caller|callers|upstream|references)\b/.test(q);
+  const wantsCallees = /\b(callee|callees|downstream|helper|helpers|conversion|next)\b/.test(q);
+  const wantsImpact = /\b(impact|changing|change|affect|break|handoff|surface)\b/.test(q);
+  if (wantsCallers || (!wantsCallees && !wantsImpact)) callers.slice(0, 3).forEach(item => addSymbol(out, item.name));
+  if (wantsCallees || (!wantsCallers && !wantsImpact)) callees.slice(0, 4).forEach(item => addSymbol(out, item.name));
+  if (wantsImpact) {
+    for (const path of impactPaths.slice(0, 4)) {
+      for (const item of path.path || []) {
+        if (item.type !== 'external') addSymbol(out, item.name);
+      }
+    }
+  }
+  return out.slice(0, 10);
+}
+
+const BRANCH_ORDER = [
+  'tuple', 'dict', 'list', 'str', 'string', 'bytes', 'bytearray', 'buffer', 'stream', 'json',
+  'response', 'status', 'headers', 'params', 'body', 'querystring', 'atomicbool', 'parallel',
+];
+const BRANCH_WORDS = new Set(BRANCH_ORDER);
+
+function branchTerms(targetTerms) {
+  const byLower = new Map();
+  for (const term of targetTerms) {
+    const lower = term.toLowerCase();
+    if (BRANCH_WORDS.has(lower)) {
+      byLower.set(lower, term);
+      continue;
+    }
+    for (const branch of BRANCH_ORDER) {
+      if (lower === `${branch}s` || lower.startsWith(`${branch}schema`)) {
+        byLower.set(branch, branch);
+      }
+    }
+  }
+  return BRANCH_ORDER.map(term => byLower.get(term)).filter(Boolean).slice(0, 12);
+}
+
+function branchSnippets(target, branches) {
+  if (!branches.length || !target.code) return [];
+  const wanted = branches.map(x => x.toLowerCase());
+  const lines = String(target.code).split('\n');
+  const out = [];
+  const covered = new Set();
+  let tripleQuote = null;
+  for (let i = 0; i < lines.length && out.length < 12; i++) {
+    const line = lines[i].trim();
+    const quote = line.includes('"""') ? '"""' : line.includes("'''") ? "'''" : null;
+    if (tripleQuote) {
+      if (quote === tripleQuote) tripleQuote = null;
+      continue;
+    }
+    if (quote) {
+      if ((line.match(new RegExp(quote, 'g')) || []).length % 2 === 1) tripleQuote = quote;
+      continue;
+    }
+    if (!line || /^(#|\/\/|\/\*|\*|`|:)/.test(line)) continue;
+    if (!/[()[\]{}=:]|\b(if|elif|else|case|switch|const|let|var|return)\b/.test(line)) continue;
+    const lower = line.toLowerCase();
+    const hits = wanted.filter(term => lower.includes(term) || lower.includes(`${term}schema`));
+    if (!hits.length || hits.every(term => covered.has(term))) continue;
+    const lineNo = (target.startLine || 1) + i;
+    out.push(`L${lineNo}: ${line.replace(/\s+/g, ' ')}`);
+    hits.forEach(term => covered.add(term));
+    if (covered.size >= wanted.length) break;
+  }
+  return out;
+}
+
+function relatedDefinitions(target, targetTerms, resolveTerm) {
+  if (!resolveTerm) return [];
+  const out = [];
+  const seen = new Set([target.id]);
+  for (const term of targetTerms.slice(0, 12)) {
+    const found = resolveTerm(term);
+    if (!found || seen.has(found.id) || found.filePath !== target.filePath) continue;
+    if (found.name === target.name && found.startLine === target.startLine) continue;
+    seen.add(found.id);
+    const snippet = found.summary && found.summary !== 'Same-file definition found from source text'
+      ? ` - ${found.summary}`
+      : '';
+    out.push(`${found.name} [${found.type}] ${found.filePath}:${found.startLine || '?'}${snippet}`);
+    if (out.length >= 6) break;
+  }
+  return out;
+}
+
+export function buildAnswerCues({ target, hint, callers, callees, impactPaths, resolveTerm }) {
+  const targetTerms = rankedTerms(target, hint);
+  const branches = branchTerms(targetTerms);
+  const cueCallers = preferProduction(callers, item => isLowSignalPath(item.filePath));
+  const cueCallees = preferProduction(callees, item => isLowSignalPath(item.filePath));
+  const cuePaths = preferProduction(impactPaths, path => (path.path || []).some(item => isLowSignalPath(item.filePath)));
+  return {
+    targetTerms,
+    keySymbols: keySymbols(target, hint, cueCallers, cueCallees, cuePaths),
+    branchTerms: branches,
+    branchSnippets: branchSnippets(target, branches),
+    relatedDefinitions: relatedDefinitions(target, targetTerms, resolveTerm),
+    topCallers: cueCallers.slice(0, 5).map(shortItem),
+    topCallees: cueCallees.slice(0, 5).map(shortItem),
+    criticalPaths: cuePaths.slice(0, 5).map(shortPath),
+  };
+}

package/core/graph/structural-callsite-hints.js

@@ -0,0 +1,40 @@
+const SKIP = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'function', 'func', 'return', 'defer', 'go', 'select',
+  'len', 'cap', 'make', 'new', 'append', 'copy', 'delete', 'panic', 'recover',
+  'setTimeout', 'clearTimeout', 'require', 'import', 'new', 'await', 'async',
+]);
+
+const MEMBER_SKIP = new Set([
+  'bind', 'call', 'apply', 'map', 'filter', 'reduce', 'forEach', 'then', 'catch',
+  'toString', 'String', 'Error', 'Println', 'Printf', 'Errorf', 'Fatalf',
+]);
+
+function addHint(out, known, name, member = false) {
+  if (!name || known.has(name) || out.includes(name)) return;
+  if (SKIP.has(name) || (member && MEMBER_SKIP.has(name))) return;
+  out.push(name);
+}
+
+export function stripNonCode(text) {
+  return String(text || '')
+    .replace(/("""|''')[\s\S]*?\1/g, '')
+    .replace(/(["'`])(?:\\.|(?!\1)[\s\S])*?\1/g, '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*(#|\/\/).*$/gm, '');
+}
+
+export function callsiteHints(code, known = new Set()) {
+  const out = [];
+  const text = stripNonCode(code);
+  const free = /(?<![.\w$])([A-Za-z_$][\w$]*)\s*(?:\.(?:bind|call|apply))?\s*\(/g;
+  for (const m of text.matchAll(free)) {
+    addHint(out, known, m[1], false);
+    if (out.length >= 12) return out;
+  }
+  const member = /(?:\.|::)\s*([A-Za-z_$][\w$]*)\s*\(/g;
+  for (const m of text.matchAll(member)) {
+    addHint(out, known, m[1], true);
+    if (out.length >= 12) return out;
+  }
+  return out;
+}

package/core/graph/structural-context-format.js

@@ -0,0 +1,40 @@
+export function formatStructuralContext(result) {
+  if (!result.target) return `No indexed symbol found for "${result.symbol}".`;
+  const t = result.target;
+  const lines = [];
+  lines.push(`# trace ${t.name} [${t.type}] ${t.filePath}:${t.startLine}-${t.endLine}`);
+  lines.push(`fan-in=${t.fanIn} fan-out=${t.fanOut} budget=${result.tokensUsed}/${result.tokenBudget} (${result.budgetTier}:${result.budgetReason}) latency=${result.stats.latencyMs}ms`);
+  if (result.disambiguation.length) {
+    lines.push(`ambiguous: using first match; alternatives: ${result.disambiguation.slice(0, 5).map(a => `${a.name} ${a.file}:${a.startLine}`).join(', ')}`);
+  }
+  if (result.answerCues?.targetTerms?.length) {
+    if (result.answerCues.keySymbols?.length) lines.push(`answer checklist: key symbols=${result.answerCues.keySymbols.join(', ')}`);
+    if (result.answerCues.branchTerms?.length) lines.push(`answer checklist: branch terms to preserve=${result.answerCues.branchTerms.join(', ')}`);
+    if (result.answerCues.branchSnippets?.length) lines.push(`answer checklist: branch code=${result.answerCues.branchSnippets.join(' | ')}`);
+    if (result.answerCues.relatedDefinitions?.length) lines.push(`answer checklist: related definitions=${result.answerCues.relatedDefinitions.join(' | ')}`);
+    lines.push(`answer cues: target terms=${result.answerCues.targetTerms.join(', ')}`);
+    if (result.answerCues.topCallers.length) lines.push(`answer cues: top callers=${result.answerCues.topCallers.join(' | ')}`);
+    if (result.answerCues.topCallees.length) lines.push(`answer cues: top callees=${result.answerCues.topCallees.join(' | ')}`);
+    if (result.answerCues.criticalPaths.length) lines.push(`answer cues: critical paths=${result.answerCues.criticalPaths.join(' | ')}`);
+  }
+  if (t.headerContext) lines.push('\n## target imports\n```', t.headerContext, '```');
+  if (t.code) lines.push('\n## target\n```', t.code, '```');
+  if (t.callsiteHints?.length) lines.push(`target callsite hints: ${t.callsiteHints.join(', ')}`);
+  for (const [title, section] of [['callers', result.sections.callers], ['callees', result.sections.callees]]) {
+    lines.push(`\n## ${title} (${section.total})`);
+    for (const item of section.items) {
+      lines.push(`\n### ${item.name} [${item.type}] importance=${item.importance}`);
+      lines.push(item.summary);
+      if (item.code) lines.push('```', item.code, '```');
+    }
+    if (!section.items.length) lines.push('(none)');
+  }
+  lines.push(`\n## impact paths (${result.sections.impact.total}, depth <= ${result.maxDepth})`);
+  if (!result.sections.impact.paths.length) lines.push('(none)');
+  result.sections.impact.paths.forEach((p, i) => {
+    lines.push(`${i + 1}. ${p.direction} importance=${p.importance} ${p.path}`);
+  });
+  return lines.join('\n');
+}
+
+export default formatStructuralContext;