smart-context-mcp 1.3.1 → 1.4.0

package/src/utils/context-scoring.js

@@ -0,0 +1,400 @@
+import path from 'node:path';
+import { extractSymbolCandidates } from './query-extraction.js';
+
+const ROLE_PRIORITY = ['primary', 'test', 'dependency', 'dependent'];
+const ROLE_RANK = Object.fromEntries(ROLE_PRIORITY.map((role, idx) => [role, idx]));
+const EVIDENCE_PRIORITY = {
+  entryFile: 0,
+  diffHit: 1,
+  searchHit: 2,
+  symbolMatch: 3,
+  symbolDetail: 4,
+  testOf: 5,
+  dependencyOf: 6,
+  dependentOf: 7,
+};
+const ROLE_BASE_SCORE = { primary: 130, test: 85, dependency: 60, dependent: 50 };
+const EVIDENCE_BASE_SCORE = {
+  entryFile: 120,
+  diffHit: 100,
+  searchHit: 70,
+  symbolMatch: 90,
+  symbolDetail: 95,
+  testOf: 40,
+  dependencyOf: 25,
+  dependentOf: 22,
+};
+
+const PRIMARY_PATH_HINT_MAP = [
+  { test: /\b(api|endpoint|endpoints|route|routes)\b/, hints: ['api', 'routes'] },
+  { test: /\b(auth|token|jwt|login|session)\b/, hints: ['auth'] },
+  { test: /\b(config|env|secret|yaml|json)\b/, hints: ['config'] },
+  { test: /\b(test|tests|spec|coverage)\b/, hints: ['test', 'tests'] },
+  { test: /\b(model|models|schema|schemas|entity|entities)\b/, hints: ['model', 'models'] },
+  { test: /\b(container|docker|image|deploy|deployment)\b/, hints: ['dockerfile', 'docker'] },
+];
+
+const TEST_FILE_RE = /(^|\/)(tests?|__tests__)\//;
+const QUERY_TOKEN_RE = /[a-zA-Z0-9_]+/g;
+
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'is', 'are',
+  'was', 'were', 'be', 'been', 'and', 'or', 'but', 'not', 'this', 'that', 'it',
+  'how', 'what', 'where', 'when', 'why', 'which', 'who', 'do', 'does', 'did',
+  'has', 'have', 'had', 'from', 'by', 'about', 'into', 'my', 'our', 'your',
+  'can', 'could', 'will', 'would', 'should', 'may', 'might', 'i', 'we', 'you',
+  'all', 'each', 'every', 'me', 'us', 'them', 'its',
+]);
+
+const LOW_SIGNAL_QUERY_WORDS = new Set([
+  'find', 'show', 'list', 'get', 'search', 'locate', 'lookup', 'look', 'check',
+  'inspect', 'review', 'analyze', 'analyse', 'understand', 'explore', 'read',
+  'open', 'walk', 'help', 'need', 'want', 'please', 'context', 'preview',
+  'recall', 'stuff', 'thing', 'things', 'happen', 'happens', 'handle', 'handles',
+  'handling', 'wired', 'declare', 'declared', 'defined', 'owns', 'owner', 'existing',
+  'exercise', 'exercises', 'before', 'main', 'shared', 'related', 'across', 'split',
+  'live', 'lives', 'surface', 'public', 'entry', 'point', 'path', 'logic', 'covers',
+  'api', 'apis', 'flow', 'flows', 'file', 'files', 'onboarding', 'app', 'application', 'load', 'loads', 'loaded',
+]);
+
+const uniqueList = (items = []) => [...new Set(items.filter(Boolean))];
+
+const evidenceKey = (evidence) => JSON.stringify([
+  evidence.type,
+  evidence.via ?? null,
+  evidence.ref ?? null,
+  evidence.rank ?? null,
+  evidence.query ?? null,
+  Array.isArray(evidence.symbols) ? evidence.symbols.join('|') : null,
+]);
+
+export const dedupeEvidence = (items = []) => {
+  const map = new Map();
+  for (const item of items) {
+    if (!item?.type) continue;
+    const normalized = { ...item };
+    if (Array.isArray(normalized.symbols)) {
+      normalized.symbols = uniqueList(normalized.symbols).slice(0, 3);
+      if (normalized.symbols.length === 0) delete normalized.symbols;
+    }
+    const key = evidenceKey(normalized);
+    if (!map.has(key)) map.set(key, normalized);
+  }
+  return [...map.values()].sort((a, b) => {
+    const priorityDiff = (EVIDENCE_PRIORITY[a.type] ?? 99) - (EVIDENCE_PRIORITY[b.type] ?? 99);
+    if (priorityDiff !== 0) return priorityDiff;
+    return (a.rank ?? 999) - (b.rank ?? 999);
+  });
+};
+
+export const formatReasonIncluded = (evidence = []) => {
+  const primary = evidence[0];
+  if (!primary) return 'selected';
+
+  switch (primary.type) {
+    case 'entryFile':
+      return 'entry';
+    case 'diffHit':
+      return primary.ref ? `diff: ${primary.ref}` : 'diff';
+    case 'searchHit':
+      return primary.query ? `search: ${primary.query}` : 'search';
+    case 'symbolMatch':
+      return `symbol: ${(primary.symbols ?? []).slice(0, 2).join(', ')}`;
+    case 'symbolDetail':
+      return `detail: ${(primary.symbols ?? []).slice(0, 2).join(', ')}`;
+    case 'testOf':
+      return primary.via ? `test: ${primary.via}` : 'test';
+    case 'dependencyOf':
+      return primary.via ? `imported-by: ${primary.via}` : 'imported-by';
+    case 'dependentOf':
+      return primary.via ? `imports: ${primary.via}` : 'imports';
+    default:
+      return 'selected';
+  }
+};
+
+const HIGH_SIGNAL_PREVIEW_KINDS = new Set([
+  'actor', 'class', 'enum', 'function', 'interface', 'method',
+  'protocol', 'struct', 'trait', 'type',
+]);
+
+const getPreviewKindPriority = (kind) => {
+  switch (kind) {
+    case 'class':
+    case 'function':
+    case 'method':
+      return 4;
+    case 'interface':
+    case 'type':
+    case 'protocol':
+    case 'trait':
+    case 'struct':
+    case 'enum':
+    case 'actor':
+      return 3;
+    default:
+      return 0;
+  }
+};
+
+const compactSymbolPreview = (entry) => ({
+  name: entry.name,
+  kind: entry.kind,
+  ...(entry.signature ? { signature: entry.signature } : entry.snippet ? { snippet: entry.snippet } : {}),
+});
+
+export const buildSymbolPreviews = (entries = [], matchedSymbols = [], { includeFallback = false, maxItems = 3 } = {}) => {
+  if (maxItems <= 0) return [];
+
+  const matchedSet = new Set(matchedSymbols.map((symbol) => symbol.toLowerCase()));
+  const candidates = entries
+    .filter((entry) => includeFallback || matchedSet.has(entry.name.toLowerCase()))
+    .sort((a, b) => {
+      const aMatched = matchedSet.has(a.name.toLowerCase()) ? 1 : 0;
+      const bMatched = matchedSet.has(b.name.toLowerCase()) ? 1 : 0;
+      if (aMatched !== bMatched) return bMatched - aMatched;
+      const aKind = getPreviewKindPriority(a.kind);
+      const bKind = getPreviewKindPriority(b.kind);
+      if (aKind !== bKind) return bKind - aKind;
+      const aRich = Number(Boolean(a.signature)) + Number(Boolean(a.snippet));
+      const bRich = Number(Boolean(b.signature)) + Number(Boolean(b.snippet));
+      if (aRich !== bRich) return bRich - aRich;
+      return a.line - b.line;
+    });
+
+  const prioritized = [];
+  const secondary = [];
+
+  for (const candidate of candidates) {
+    const isMatched = matchedSet.has(candidate.name.toLowerCase());
+    if (isMatched || HIGH_SIGNAL_PREVIEW_KINDS.has(candidate.kind)) prioritized.push(candidate);
+    else secondary.push(candidate);
+  }
+
+  return [...prioritized, ...secondary].slice(0, maxItems).map(compactSymbolPreview);
+};
+
+export const attachSymbolEvidence = (files, index, symbolCandidates) => {
+  if (!index || symbolCandidates.length === 0) return;
+
+  const candidateMap = new Map(symbolCandidates.map((symbol) => [symbol.toLowerCase(), symbol]));
+
+  for (const [rel, info] of files) {
+    const fileSymbols = index.files?.[rel]?.symbols ?? [];
+    const matchedSymbols = [];
+
+    for (const symbol of fileSymbols) {
+      const matched = candidateMap.get(symbol.name.toLowerCase());
+      if (matched && !matchedSymbols.includes(matched)) matchedSymbols.push(matched);
+    }
+
+    if (matchedSymbols.length === 0) continue;
+
+    const evidence = dedupeEvidence([
+      ...(info.evidence ?? []),
+      { type: 'symbolMatch', symbols: matchedSymbols.slice(0, 3) },
+    ]);
+
+    files.set(rel, {
+      ...info,
+      evidence,
+      matchedSymbols: uniqueList([...(info.matchedSymbols ?? []), ...matchedSymbols]).slice(0, 3),
+    });
+  }
+};
+
+export const computeStaticUtility = (candidate, intent) => {
+  let score = ROLE_BASE_SCORE[candidate.role] ?? 40;
+  if (candidate.role === 'test' && intent === 'tests') score += 20;
+
+  for (const evidence of candidate.evidence ?? []) {
+    score += EVIDENCE_BASE_SCORE[evidence.type] ?? 0;
+    if (evidence.type === 'searchHit') score += Math.max(0, 24 - ((evidence.rank ?? 1) - 1) * 6);
+    if (evidence.type === 'symbolMatch') score += (evidence.symbols?.length ?? 0) * 12;
+  }
+
+  score += (candidate.matchedSymbols?.length ?? 0) * 10;
+  return score;
+};
+
+export const inferRelatedRole = (candidate) => {
+  const evidenceTypes = new Set((candidate.evidence ?? []).map((item) => item.type));
+  if (evidenceTypes.has('testOf')) return 'test';
+  if (evidenceTypes.has('dependencyOf')) return 'dependency';
+  if (evidenceTypes.has('dependentOf')) return 'dependent';
+  return 'dependent';
+};
+
+export const computePrimarySignal = (candidate, intent) => {
+  const relLower = (candidate.rel ?? '').toLowerCase();
+  let score = 0;
+
+  for (const evidence of candidate.evidence ?? []) {
+    if (evidence.type === 'entryFile') score += 120;
+    if (evidence.type === 'diffHit') score += 110;
+    if (evidence.type === 'searchHit') score += Math.max(0, 28 - ((evidence.rank ?? 1) - 1) * 6);
+    if (evidence.type === 'symbolMatch') score += (evidence.symbols?.length ?? 0) * 10;
+    if (evidence.type === 'symbolDetail') score += (evidence.symbols?.length ?? 0) * 12;
+  }
+
+  score += (candidate.matchedSymbols?.length ?? 0) * 12;
+
+  if (TEST_FILE_RE.test(relLower)) {
+    score += intent === 'tests' ? 10 : -60;
+  } else if (relLower.startsWith('src/')) {
+    score += 10;
+  }
+
+  return score;
+};
+
+const tokenizePath = (rel) =>
+  uniqueList((rel.toLowerCase().match(/[a-z0-9]+/g) || []).filter((token) => token.length > 1));
+
+const extractPrimaryPathHints = (task) => {
+  const lowerTask = task.toLowerCase();
+  const hints = new Set(
+    (lowerTask.match(QUERY_TOKEN_RE) || [])
+      .map((token) => token.toLowerCase())
+      .filter((token) => token.length > 2 && !STOP_WORDS.has(token) && !LOW_SIGNAL_QUERY_WORDS.has(token))
+  );
+
+  for (const entry of PRIMARY_PATH_HINT_MAP) {
+    if (entry.test.test(lowerTask)) {
+      for (const hint of entry.hints) hints.add(hint);
+    }
+  }
+
+  return [...hints];
+};
+
+export const scorePrimarySeed = (seed, task, intent) => {
+  const rel = seed.rel ?? '';
+  const relLower = rel.toLowerCase();
+  const basename = path.basename(relLower, path.extname(relLower));
+  const pathTokens = new Set(tokenizePath(relLower));
+  const pathHints = extractPrimaryPathHints(task);
+  let score = 0;
+
+  for (const evidence of seed.evidence ?? []) {
+    if (evidence.type !== 'searchHit') continue;
+    score += Math.max(0, 40 - ((evidence.rank ?? 1) - 1) * 8);
+    if (!evidence.query) continue;
+
+    const query = evidence.query.toLowerCase();
+    if (basename === query) score += 28;
+    else if (relLower.includes(query)) score += 18;
+    else if (pathTokens.has(query)) score += 14;
+  }
+
+  let hintHits = 0;
+  for (const hint of pathHints) {
+    if (basename === hint) {
+      score += 28;
+      hintHits++;
+      continue;
+    }
+    if (pathTokens.has(hint) || relLower.includes(hint)) {
+      score += 18;
+      hintHits++;
+    }
+  }
+
+  const targetsApiSurface = pathHints.includes('api') || pathHints.includes('routes');
+  if (targetsApiSurface) {
+    if (/(^|\/)(api|routes)(\/|$)/.test(relLower)) score += 28;
+    if (/(^|\/)(models?|schemas?)(\/|$)/.test(relLower)) score -= 12;
+  }
+
+  if (TEST_FILE_RE.test(relLower)) {
+    score += intent === 'tests' ? 24 : -40;
+  } else if (intent === 'tests') {
+    score -= 10;
+  }
+
+  if (intent === 'implementation' && relLower.startsWith('src/')) score += 10;
+  if ((intent === 'debug' || intent === 'review') && relLower.startsWith('src/')) score += 8;
+  if (hintHits > 0 && relLower.startsWith('src/')) score += 6;
+
+  return score;
+};
+
+export const rerankPrimarySeeds = (primarySeeds, task, intent) =>
+  [...primarySeeds].sort((a, b) =>
+    scorePrimarySeed(b, task, intent) - scorePrimarySeed(a, task, intent)
+    || a.rel.localeCompare(b.rel)
+  );
+
+export const computePrimaryPromotionScore = (candidate, task, intent) => {
+  let score = scorePrimarySeed(candidate, task, intent);
+  score += computePrimarySignal(candidate, intent);
+  if (candidate.role === 'primary') score += 6;
+  return score;
+};
+
+export const normalizePrimaryCandidate = (files, task, intent) => {
+  const candidates = [...files.entries()].map(([rel, info]) => ({ rel, ...info }));
+  if (candidates.length === 0) return;
+
+  const currentPrimary = candidates.find((candidate) => candidate.role === 'primary');
+  const best = [...candidates].sort((a, b) =>
+    computePrimaryPromotionScore(b, task, intent) - computePrimaryPromotionScore(a, task, intent)
+    || a.rel.localeCompare(b.rel)
+  )[0];
+
+  if (!best) return;
+
+  const currentScore = currentPrimary
+    ? computePrimaryPromotionScore(currentPrimary, task, intent)
+    : Number.NEGATIVE_INFINITY;
+  const bestScore = computePrimaryPromotionScore(best, task, intent);
+  const chosenPrimary = currentPrimary && currentScore > bestScore + 10 ? currentPrimary : best;
+
+  for (const candidate of candidates) {
+    if (candidate.rel === chosenPrimary.rel) {
+      files.set(candidate.rel, { ...files.get(candidate.rel), role: 'primary' });
+      continue;
+    }
+
+    if (candidate.role !== 'primary') continue;
+    files.set(candidate.rel, { ...files.get(candidate.rel), role: inferRelatedRole(candidate) });
+  }
+};
+
+const collectViaRefs = (candidate) => uniqueList((candidate.evidence ?? []).map((item) => item.via));
+
+export const computeMarginalPenalty = (candidate, selected) => {
+  if (selected.length === 0) return 0;
+
+  const dir = path.dirname(candidate.rel);
+  const candidateVia = new Set(collectViaRefs(candidate));
+  const candidateSymbols = new Set((candidate.matchedSymbols ?? []).map((symbol) => symbol.toLowerCase()));
+
+  let penalty = 0;
+  let sameDirCount = 0;
+  let sameRoleCount = 0;
+  let sameViaCount = 0;
+  let overlappingSymbolCount = 0;
+
+  for (const item of selected) {
+    if (path.dirname(item.rel) === dir) sameDirCount++;
+    if (item.role === candidate.role) sameRoleCount++;
+
+    for (const via of collectViaRefs(item)) {
+      if (candidateVia.has(via)) sameViaCount++;
+    }
+
+    for (const symbol of item.matchedSymbols ?? []) {
+      if (candidateSymbols.has(symbol.toLowerCase())) overlappingSymbolCount++;
+    }
+  }
+
+  penalty += sameDirCount * (candidate.role === 'primary' ? 3 : 8);
+  penalty += sameRoleCount * (candidate.role === 'primary' ? 2 : 5);
+  penalty += sameViaCount * 12;
+  penalty += overlappingSymbolCount * 18;
+
+  return penalty;
+};
+
+export { ROLE_RANK, ROLE_BASE_SCORE, EVIDENCE_BASE_SCORE };

package/src/utils/fs.js

@@ -2,17 +2,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { projectRoot } from './paths.js';
 
-const assertInsideProject = (fullPath) => {
-  const relative = path.relative(projectRoot, fullPath);
+const assertInsideProject = (fullPath, root = projectRoot) => {
+  const relative = path.relative(root, fullPath);
 
   if (relative.startsWith('..') || path.isAbsolute(relative)) {
     throw new Error(`Path escapes project root: ${fullPath}`);
   }
 };
 
-export const resolveSafePath = (inputPath = '.') => {
-  const fullPath = path.resolve(projectRoot, inputPath);
-  assertInsideProject(fullPath);
+export const resolveSafePath = (inputPath = '.', root = projectRoot) => {
+  const fullPath = path.resolve(root, inputPath);
+  assertInsideProject(fullPath, root);
   return fullPath;
 };
 
@@ -35,8 +35,8 @@ export const isDockerfile = (filePath) => {
   return baseName === 'dockerfile' || baseName.startsWith('dockerfile.');
 };
 
-export const readTextFile = (inputPath) => {
-  const fullPath = resolveSafePath(inputPath);
+export const readTextFile = (inputPath, root = projectRoot) => {
+  const fullPath = resolveSafePath(inputPath, root);
   const raw = fs.readFileSync(fullPath);
 
   if (isBinaryBuffer(raw)) {
@@ -45,3 +45,9 @@ export const readTextFile = (inputPath) => {
 
   return { fullPath, content: raw.toString('utf8') };
 };
+
+export const writeTextFile = (inputPath, content, root = projectRoot) => {
+  const fullPath = resolveSafePath(inputPath, root);
+  fs.writeFileSync(fullPath, content, 'utf8');
+  return fullPath;
+};

package/src/utils/query-extraction.js

@@ -0,0 +1,180 @@
+const INTENT_KEYWORDS = {
+  debug: ['debug', 'fix', 'error', 'bug', 'crash', 'fail', 'broken', 'issue', 'trace'],
+  tests: ['test', 'spec', 'coverage', 'assert', 'mock', 'jest', 'vitest'],
+  config: ['config', 'env', 'setup', 'deploy', 'docker', 'ci', 'terraform', 'yaml', 'secret', 'secrets', 'settings', 'database'],
+  docs: ['doc', 'readme', 'explain', 'document', 'guide'],
+  implementation: ['implement', 'add', 'create', 'build', 'feature', 'refactor', 'update', 'modify'],
+};
+
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'is', 'are',
+  'was', 'were', 'be', 'been', 'and', 'or', 'but', 'not', 'this', 'that', 'it',
+  'how', 'what', 'where', 'when', 'why', 'which', 'who', 'do', 'does', 'did',
+  'has', 'have', 'had', 'from', 'by', 'about', 'into', 'my', 'our', 'your',
+  'can', 'could', 'will', 'would', 'should', 'may', 'might', 'i', 'we', 'you',
+  'all', 'each', 'every', 'me', 'us', 'them', 'its',
+]);
+
+const LOW_SIGNAL_QUERY_WORDS = new Set([
+  'find', 'show', 'list', 'get', 'search', 'locate', 'lookup', 'look', 'check',
+  'inspect', 'review', 'analyze', 'analyse', 'understand', 'explore', 'read',
+  'open', 'walk', 'help', 'need', 'want', 'please', 'context', 'preview',
+  'recall', 'stuff', 'thing', 'things', 'happen', 'happens', 'handle', 'handles',
+  'handling', 'wired', 'declare', 'declared', 'defined', 'owns', 'owner', 'existing',
+  'exercise', 'exercises', 'before', 'main', 'shared', 'related', 'across', 'split',
+  'live', 'lives', 'surface', 'public', 'entry', 'point', 'path', 'logic', 'covers',
+  'api', 'apis', 'flow', 'flows', 'file', 'files', 'onboarding', 'app', 'application', 'load', 'loads', 'loaded',
+]);
+
+const IDENTIFIER_RE = /\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b|\b[A-Z][a-zA-Z0-9]{2,}\b|\b[a-z]{2,}_[a-z_]+\b/g;
+const QUERY_TOKEN_RE = /[a-zA-Z0-9_]+/g;
+
+const uniqueList = (items = []) => [...new Set(items.filter(Boolean))];
+
+export const inferIntent = (task) => {
+  const lower = task.toLowerCase();
+  let best = 'explore';
+  let bestScore = 0;
+
+  for (const [intent, keywords] of Object.entries(INTENT_KEYWORDS)) {
+    const score = keywords.filter((kw) => lower.includes(kw)).length;
+    if (score > bestScore) { bestScore = score; best = intent; }
+  }
+
+  return best;
+};
+
+const extractCompoundQueries = (task) => {
+  const lowerTask = task.toLowerCase();
+  const queries = [];
+
+  if (/\b(create[-\s]+user|user[-\s]+creation)\b/.test(lowerTask)) {
+    queries.push('createUser');
+  }
+
+  if (/\bjwt[-\s]+secret\b/.test(lowerTask)) {
+    queries.push('jwtSecret');
+  }
+
+  return queries;
+};
+
+const filterRedundantPromptQueries = (queries, compoundQueries) => {
+  const lowerCompoundQueries = new Set(compoundQueries.map((query) => query.toLowerCase()));
+  return queries.filter((query) => {
+    const lowerQuery = query.toLowerCase();
+    if (lowerCompoundQueries.has('jwtsecret') && lowerQuery === 'jwt') return false;
+    return true;
+  });
+};
+
+export const extractSymbolCandidates = (task) => {
+  const compoundQueries = extractCompoundQueries(task);
+  return uniqueList([
+    ...compoundQueries,
+    ...filterRedundantPromptQueries(task.match(IDENTIFIER_RE) || [], compoundQueries),
+  ]);
+};
+
+const isLikelyCodeSymbol = (token) =>
+  token.includes('_')
+  || /\d/.test(token)
+  || /[a-z][A-Z]/.test(token)
+  || /[A-Z]{2,}/.test(token);
+
+const scoreKeywordQuery = (token, lowerTask) => {
+  let score = Math.min(token.length, 8);
+  const position = lowerTask.indexOf(token);
+  if (position >= 0) score += Math.max(0, 16 - position);
+  if (token.length >= 12) score += 1;
+  return score;
+};
+
+const extractKeywordQueries = (task, { allowIntentKeywords = false } = {}) => {
+  const intentKws = new Set(Object.values(INTENT_KEYWORDS).flat());
+  const lowerTask = task.toLowerCase();
+  const compoundQueries = extractCompoundQueries(task);
+
+  return filterRedundantPromptQueries(
+    [...new Set((task.match(QUERY_TOKEN_RE) || [])
+      .map((token) => token.toLowerCase())
+      .filter((token) => {
+        if (token.length <= 2) return false;
+        if (/^\d+$/.test(token)) return false;
+        if (STOP_WORDS.has(token)) return false;
+        if (LOW_SIGNAL_QUERY_WORDS.has(token)) return false;
+        if (!allowIntentKeywords && intentKws.has(token)) return false;
+        return true;
+      })
+      .sort((a, b) => scoreKeywordQuery(b, lowerTask) - scoreKeywordQuery(a, lowerTask)
+        || lowerTask.indexOf(a) - lowerTask.indexOf(b)
+        || b.length - a.length
+        || a.localeCompare(b)))],
+    compoundQueries,
+  );
+};
+
+const extractExpandedQueries = (task) => {
+  const lowerTask = task.toLowerCase();
+  const queries = [...extractCompoundQueries(task)];
+
+  if (/\b(container|docker|image|deploy|deployment)\b/.test(lowerTask)) {
+    queries.push('FROM');
+  }
+
+  return queries;
+};
+
+const extractFallbackSearchQuery = (task) => {
+  const symbolFallback = extractSymbolCandidates(task).find(isLikelyCodeSymbol);
+  if (symbolFallback) return symbolFallback;
+
+  const keywordFallback = extractKeywordQueries(task, { allowIntentKeywords: true })[0];
+  if (keywordFallback) return keywordFallback;
+
+  return task.trim();
+};
+
+export const extractSearchQueries = (task) => {
+  const symbolQueries = extractSymbolCandidates(task)
+    .filter(isLikelyCodeSymbol)
+    .filter((candidate) => !LOW_SIGNAL_QUERY_WORDS.has(candidate.toLowerCase()) && !STOP_WORDS.has(candidate.toLowerCase()));
+  const keywordQueries = extractKeywordQueries(task);
+  const queries = [];
+  const seen = new Set();
+
+  for (const candidate of [...symbolQueries, ...keywordQueries]) {
+    const key = candidate.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    queries.push(candidate);
+  }
+
+  return queries.slice(0, 3);
+};
+
+const LITERAL_PATTERN_MARKERS = [
+  { pattern: /\/\*\*/, literal: '/**' },
+  { pattern: /\/\*/, literal: '/*' },
+  { pattern: /\/\/\s*TODO/, literal: 'TODO' },
+  { pattern: /\/\/\s*FIXME/, literal: 'FIXME' },
+  { pattern: /\/\/\s*XXX/, literal: 'XXX' },
+  { pattern: /\/\/\s*HACK/, literal: 'HACK' },
+  { pattern: /console\.log/, literal: 'console.log' },
+  { pattern: /console\.error/, literal: 'console.error' },
+  { pattern: /debugger/, literal: 'debugger' },
+];
+
+export const extractLiteralPatterns = (task) => {
+  const patterns = [];
+  
+  for (const marker of LITERAL_PATTERN_MARKERS) {
+    if (marker.pattern.test(task)) {
+      patterns.push(marker.literal);
+    }
+  }
+  
+  return patterns;
+};
+
+export { extractExpandedQueries, extractFallbackSearchQuery, extractKeywordQueries };