raggrep 0.17.1 → 0.18.0

package/dist/cli/main.js

@@ -1171,7 +1171,107 @@ var init_searchResult = __esm(() => {
     minScore: 0.15,
     filePatterns: [],
     pathFilter: [],
-    ensureFresh: true
+    ensureFresh: true,
+    rankingWeights: {},
+    quiet: false,
+    rankBy: "structured"
+  };
+});
+
+// src/domain/entities/rankingWeights.ts
+function mergeLiteralWeights(def, partial) {
+  if (!partial) {
+    return def;
+  }
+  return {
+    baseScore: partial.baseScore ?? def.baseScore,
+    multipliers: {
+      definition: {
+        ...def.multipliers.definition,
+        ...partial.multipliers?.definition
+      },
+      reference: {
+        ...def.multipliers.reference,
+        ...partial.multipliers?.reference
+      },
+      import: { ...def.multipliers.import, ...partial.multipliers?.import }
+    },
+    vocabulary: { ...def.vocabulary, ...partial.vocabulary }
+  };
+}
+function mergeRankingWeights(partial) {
+  if (!partial) {
+    return DEFAULT_RANKING_WEIGHTS;
+  }
+  return {
+    discriminative: {
+      ...DEFAULT_RANKING_WEIGHTS.discriminative,
+      ...partial.discriminative
+    },
+    typescript: {
+      ...DEFAULT_RANKING_WEIGHTS.typescript,
+      ...partial.typescript
+    },
+    language: {
+      ...DEFAULT_RANKING_WEIGHTS.language,
+      ...partial.language
+    },
+    markdown: {
+      ...DEFAULT_RANKING_WEIGHTS.markdown,
+      ...partial.markdown
+    },
+    json: {
+      ...DEFAULT_RANKING_WEIGHTS.json,
+      ...partial.json
+    },
+    literal: mergeLiteralWeights(DEFAULT_RANKING_WEIGHTS.literal, partial.literal)
+  };
+}
+var DEFAULT_DISCRIMINATIVE_WEIGHTS, DEFAULT_LITERAL_BOOST_WEIGHTS, DEFAULT_RANKING_WEIGHTS;
+var init_rankingWeights = __esm(() => {
+  DEFAULT_DISCRIMINATIVE_WEIGHTS = {
+    boostCap: 0.1,
+    penaltyMax: 0.16,
+    penaltyFloor: 0.72
+  };
+  DEFAULT_LITERAL_BOOST_WEIGHTS = {
+    baseScore: 0.5,
+    multipliers: {
+      definition: { high: 2.5, medium: 2, low: 1.5 },
+      reference: { high: 2, medium: 1.5, low: 1.3 },
+      import: { high: 1.5, medium: 1.3, low: 1.1 }
+    },
+    vocabulary: {
+      baseMultiplier: 1.3,
+      perWordBonus: 0.1,
+      maxVocabularyBonus: 0.5,
+      minWordsForMatch: 2
+    }
+  };
+  DEFAULT_RANKING_WEIGHTS = {
+    discriminative: DEFAULT_DISCRIMINATIVE_WEIGHTS,
+    typescript: {
+      semantic: 0.43,
+      bm25: 0.42,
+      vocab: 0.15,
+      vocabBypassThreshold: 0.4
+    },
+    language: {
+      semantic: 0.7,
+      bm25: 0.3
+    },
+    markdown: {
+      semantic: 0.62,
+      bm25: 0.33,
+      docIntentBoost: 0.03,
+      headingPhraseCoverageMin: 0.25,
+      headingPhraseCoverageSpan: 0.75
+    },
+    json: {
+      bm25: 0.4,
+      literalBaseWeight: 0.6
+    },
+    literal: DEFAULT_LITERAL_BOOST_WEIGHTS
   };
 });
 
@@ -1319,6 +1419,7 @@ var init_lexicon = __esm(() => {
 // src/domain/entities/index.ts
 var init_entities = __esm(() => {
   init_searchResult();
+  init_rankingWeights();
   init_config();
   init_literal();
   init_lexicon();
@@ -1439,6 +1540,9 @@ class BM25Index {
       return 0;
     return Math.log(1 + (this.totalDocs - docFreq + 0.5) / (docFreq + 0.5));
   }
+  getInverseDocumentFrequency(term) {
+    return this.idf(term.toLowerCase());
+  }
   score(tokens, queryTerms) {
     const docLength = tokens.length;
     let score = 0;
@@ -3265,6 +3369,188 @@ var init_core = __esm(() => {
   init_symbols();
 });
 
+// src/domain/services/discriminativeTerms.ts
+function medianSorted(sorted) {
+  const n = sorted.length;
+  if (n === 0)
+    return 0;
+  const mid = Math.floor(n / 2);
+  return n % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function salientTermHitsChunk(term, haystack, tokenSet) {
+  if (tokenSet.has(term) || haystack.includes(term)) {
+    return true;
+  }
+  if (term.length < PREFIX_MATCH_MIN_LEN) {
+    return false;
+  }
+  for (const w of tokenSet) {
+    if (w.length < PREFIX_MATCH_MIN_LEN)
+      continue;
+    if (term.startsWith(w) || w.startsWith(term)) {
+      return true;
+    }
+  }
+  return false;
+}
+function scoreDiscriminativeTerms(bm25Index, query, chunkText, chunkName, weights = DEFAULT_DISCRIMINATIVE_WEIGHTS) {
+  const empty2 = () => ({
+    boost: 0,
+    penaltyFactor: 1,
+    salientTerms: [],
+    matchedSalient: [],
+    missingSalient: [],
+    salientCoverage: 1
+  });
+  const uniqueTerms = [...new Set(tokenize(query))];
+  if (uniqueTerms.length === 0) {
+    return empty2();
+  }
+  const indexed = [];
+  for (const term of uniqueTerms) {
+    const idf = bm25Index.getInverseDocumentFrequency(term);
+    if (idf > 0) {
+      indexed.push({ term, idf });
+    }
+  }
+  if (indexed.length === 0) {
+    return empty2();
+  }
+  const idfSorted = [...indexed.map((x) => x.idf)].sort((a, b) => a - b);
+  const medianIdf = medianSorted(idfSorted);
+  const salientEntries = indexed.filter((x) => x.idf >= medianIdf);
+  const salientTerms = [...new Set(salientEntries.map((x) => x.term))];
+  const idfByTerm = new Map;
+  for (const { term, idf } of salientEntries) {
+    idfByTerm.set(term, Math.max(idfByTerm.get(term) ?? 0, idf));
+  }
+  let totalW = 0;
+  for (const idf of idfByTerm.values()) {
+    totalW += idf;
+  }
+  const haystack = [chunkName ?? "", chunkText].join(`
+`).toLowerCase();
+  const tokenSet = new Set(tokenize(chunkName ? `${chunkName}
+${chunkText}` : chunkText));
+  const matchedSalient = [];
+  for (const term of salientTerms) {
+    const idf = idfByTerm.get(term) ?? 0;
+    if (idf <= 0)
+      continue;
+    if (salientTermHitsChunk(term, haystack, tokenSet)) {
+      matchedSalient.push(term);
+    }
+  }
+  const matchedSet = new Set(matchedSalient);
+  const missingSalient = salientTerms.filter((t) => !matchedSet.has(t));
+  let matchedW = 0;
+  for (const term of matchedSalient) {
+    matchedW += idfByTerm.get(term) ?? 0;
+  }
+  const salientCoverage = totalW > 0 ? matchedW / totalW : 1;
+  const { boostCap, penaltyMax, penaltyFloor } = weights;
+  const boost = boostCap * salientCoverage;
+  let penaltyFactor = 1 - penaltyMax * (1 - salientCoverage);
+  if (penaltyFactor < penaltyFloor) {
+    penaltyFactor = penaltyFloor;
+  }
+  return {
+    boost,
+    penaltyFactor,
+    salientTerms,
+    matchedSalient,
+    missingSalient,
+    salientCoverage
+  };
+}
+var PREFIX_MATCH_MIN_LEN = 4;
+var init_discriminativeTerms = __esm(() => {
+  init_rankingWeights();
+});
+
+// src/domain/services/matchScales.ts
+function semanticPctFromCosine(cosine) {
+  return clamp01((cosine + 1) / 2);
+}
+function clamp01(x) {
+  if (Number.isNaN(x) || !Number.isFinite(x))
+    return 0;
+  return Math.max(0, Math.min(1, x));
+}
+function num(ctx, key) {
+  const v = ctx[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+function additiveStructuredBoost(ctx) {
+  return num(ctx, "pathBoost") + num(ctx, "fileTypeBoost") + num(ctx, "chunkTypeBoost") + num(ctx, "exportBoost");
+}
+function attachMatchScales(result, rw) {
+  const ctx = result.context ?? {};
+  const mid = result.moduleId;
+  let semanticMatch = 0;
+  let structuredMatch = 0;
+  if (mid === "language/typescript") {
+    const cos = num(ctx, "semanticScore");
+    const bm25 = num(ctx, "bm25Score");
+    const vocab = num(ctx, "vocabScore");
+    const phraseCov = num(ctx, "phraseCoverage");
+    const tw = rw.typescript;
+    semanticMatch = semanticPctFromCosine(cos);
+    const denom = tw.bm25 + tw.vocab + 0.000000001;
+    const lexCore = (tw.bm25 * bm25 + tw.vocab * vocab) / denom;
+    structuredMatch = clamp01(lexCore + Math.min(0.35, additiveStructuredBoost(ctx)) + Math.min(0.15, phraseCov * 0.25));
+  } else if (mid.startsWith("language/")) {
+    const cos = num(ctx, "semanticScore");
+    const bm25 = num(ctx, "bm25Score");
+    semanticMatch = semanticPctFromCosine(cos);
+    structuredMatch = clamp01(bm25 + Math.min(0.3, additiveStructuredBoost(ctx)) + Math.min(0.12, num(ctx, "phraseCoverage") * 0.2));
+  } else if (mid === "docs/markdown") {
+    const cos = num(ctx, "semanticScore");
+    const bm25 = num(ctx, "bm25Score");
+    const docBoost = num(ctx, "docBoost");
+    const headingBoost = num(ctx, "headingBoost");
+    const phraseCov = num(ctx, "phraseCoverage");
+    const mw = rw.markdown;
+    semanticMatch = semanticPctFromCosine(cos);
+    structuredMatch = clamp01(mw.bm25 * bm25 + docBoost + headingBoost + Math.min(0.2, phraseCov * 0.15));
+  } else if (mid === "core") {
+    semanticMatch = 0;
+    const nBm = num(ctx, "bm25Score");
+    const sym = num(ctx, "symbolScore");
+    structuredMatch = clamp01(0.6 * nBm + 0.4 * sym);
+  } else if (mid === "data/json") {
+    semanticMatch = 0;
+    const bm25 = num(ctx, "bm25Score");
+    const litM = num(ctx, "literalMultiplier");
+    structuredMatch = clamp01(bm25 > 0.02 ? bm25 : Math.min(1, 0.35 + Math.min(0.65, (litM - 1) * 0.35)));
+  } else {
+    semanticMatch = 0;
+    structuredMatch = clamp01(result.score);
+  }
+  return { ...result, semanticMatch, structuredMatch };
+}
+function compareSearchResultsByRankBy(a, b, rankBy) {
+  if (rankBy === "combined") {
+    return b.score - a.score;
+  }
+  const sa = a.semanticMatch ?? 0;
+  const sb = b.semanticMatch ?? 0;
+  const ta = a.structuredMatch ?? 0;
+  const tb = b.structuredMatch ?? 0;
+  if (rankBy === "semantic") {
+    if (Math.abs(sb - sa) > 0.000000001)
+      return sb - sa;
+    if (Math.abs(tb - ta) > 0.000000001)
+      return tb - ta;
+    return b.score - a.score;
+  }
+  if (Math.abs(tb - ta) > 0.000000001)
+    return tb - ta;
+  if (Math.abs(sb - sa) > 0.000000001)
+    return sb - sa;
+  return b.score - a.score;
+}
+
 // src/domain/services/keywords.ts
 function extractKeywords(content, name, maxKeywords = 50) {
   const keywords = new Set;
@@ -3923,16 +4209,16 @@ var init_literalExtractor = __esm(() => {
 });
 
 // src/domain/services/literalScorer.ts
-function calculateLiteralMultiplier(matchType, confidence) {
-  return LITERAL_SCORING_CONSTANTS.MULTIPLIERS[matchType][confidence];
+function calculateLiteralMultiplier(matchType, confidence, weights = DEFAULT_LW) {
+  return weights.multipliers[matchType][confidence];
 }
-function calculateMaxMultiplier(matches) {
+function calculateMaxMultiplier(matches, weights = DEFAULT_LW) {
   if (!matches || matches.length === 0) {
     return 1;
   }
-  return Math.max(...matches.map((m) => calculateLiteralMultiplier(m.indexedLiteral.matchType, m.queryLiteral.confidence)));
+  return Math.max(...matches.map((m) => calculateLiteralMultiplier(m.indexedLiteral.matchType, m.queryLiteral.confidence, weights)));
 }
-function calculateLiteralContribution(matches, hasSemanticOrBm25) {
+function calculateLiteralContribution(matches, hasSemanticOrBm25, weights = DEFAULT_LW) {
   if (!matches || matches.length === 0) {
     return {
       multiplier: 1,
@@ -3943,7 +4229,7 @@ function calculateLiteralContribution(matches, hasSemanticOrBm25) {
   let bestMatch = null;
   let bestMultiplier = 0;
   for (const match of matches) {
-    const mult = calculateLiteralMultiplier(match.indexedLiteral.matchType, match.queryLiteral.confidence);
+    const mult = calculateLiteralMultiplier(match.indexedLiteral.matchType, match.queryLiteral.confidence, weights);
     if (mult > bestMultiplier) {
       bestMultiplier = mult;
       bestMatch = match;
@@ -3957,32 +4243,20 @@ function calculateLiteralContribution(matches, hasSemanticOrBm25) {
     matchCount: matches.length
   };
 }
-function applyLiteralBoost(baseScore, matches, hasSemanticOrBm25) {
+function applyLiteralBoost(baseScore, matches, hasSemanticOrBm25, weights = DEFAULT_LW) {
   if (!matches || matches.length === 0) {
     return baseScore;
   }
-  const multiplier = calculateMaxMultiplier(matches);
+  const multiplier = calculateMaxMultiplier(matches, weights);
   if (!hasSemanticOrBm25) {
-    return LITERAL_SCORING_CONSTANTS.BASE_SCORE * multiplier;
+    return weights.baseScore * multiplier;
   }
   return baseScore * multiplier;
 }
-var LITERAL_SCORING_CONSTANTS;
+var DEFAULT_LW;
 var init_literalScorer = __esm(() => {
-  LITERAL_SCORING_CONSTANTS = {
-    BASE_SCORE: 0.5,
-    MULTIPLIERS: {
-      definition: { high: 2.5, medium: 2, low: 1.5 },
-      reference: { high: 2, medium: 1.5, low: 1.3 },
-      import: { high: 1.5, medium: 1.3, low: 1.1 }
-    },
-    VOCABULARY: {
-      BASE_MULTIPLIER: 1.3,
-      PER_WORD_BONUS: 0.1,
-      MAX_VOCABULARY_BONUS: 0.5,
-      MIN_WORDS_FOR_MATCH: 2
-    }
-  };
+  init_rankingWeights();
+  DEFAULT_LW = DEFAULT_RANKING_WEIGHTS.literal;
 });
 
 // src/domain/services/lexicon.ts
@@ -4937,6 +5211,7 @@ var init_chunkContext = __esm(() => {
 
 // src/domain/services/index.ts
 var init_services = __esm(() => {
+  init_discriminativeTerms();
   init_keywords();
   init_queryIntent();
   init_queryLiteralParser();
@@ -5760,6 +6035,9 @@ class TypeScriptModule {
       minScore = DEFAULT_MIN_SCORE2,
       filePatterns
     } = options;
+    const rw = mergeRankingWeights(options.rankingWeights);
+    const tw = rw.typescript;
+    const lt = rw.literal;
     const { literals: queryLiterals, remainingQuery } = parseQueryLiterals(query);
     const indexDir = getRaggrepDir(ctx.rootDir, ctx.config);
     const symbolicIndex = new SymbolicIndex(indexDir, this.id);
@@ -5866,17 +6144,19 @@ class TypeScriptModule {
       const chunkTypeBoost = calculateChunkTypeBoost(chunk);
       const exportBoost = calculateExportBoost(chunk);
       const additiveBoost = pathBoost + fileTypeBoost + chunkTypeBoost + exportBoost + phraseMatch.boost;
-      const baseScore = SEMANTIC_WEIGHT * semanticScore + BM25_WEIGHT * bm25Score + VOCAB_WEIGHT * vocabScore;
+      const baseScore = tw.semantic * semanticScore + tw.bm25 * bm25Score + tw.vocab * vocabScore;
       const literalMatches = literalMatchMap.get(chunk.id) || [];
-      const literalContribution = calculateLiteralContribution(literalMatches, true);
-      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true);
+      const literalContribution = calculateLiteralContribution(literalMatches, true, lt);
+      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true, lt);
       const finalScore = boostedScore + additiveBoost;
+      const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+      const adjustedScore = (finalScore + disc.boost) * disc.penaltyFactor;
       processedChunkIds.add(chunk.id);
-      if (finalScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0 || vocabScore > VOCAB_THRESHOLD || phraseMatch.isSignificant) {
+      if (adjustedScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0 || vocabScore > tw.vocabBypassThreshold || phraseMatch.isSignificant) {
         results.push({
           filepath,
           chunk,
-          score: finalScore,
+          score: adjustedScore,
           moduleId: this.id,
           context: {
             semanticScore,
@@ -5888,6 +6168,10 @@ class TypeScriptModule {
             fileTypeBoost,
             chunkTypeBoost,
             exportBoost,
+            discriminativeCoverage: disc.salientCoverage,
+            discriminativePenaltyFactor: disc.penaltyFactor,
+            discriminativeBoost: disc.boost,
+            matchedSalientTerms: disc.matchedSalient,
             literalMultiplier: literalContribution.multiplier,
             literalMatchType: literalContribution.bestMatchType,
             literalConfidence: literalContribution.bestConfidence,
@@ -5940,15 +6224,17 @@ class TypeScriptModule {
         const chunkTypeBoost = calculateChunkTypeBoost(chunk);
         const exportBoost = calculateExportBoost(chunk);
         const additiveBoost = pathBoost + fileTypeBoost + chunkTypeBoost + exportBoost + phraseMatch.boost;
-        const literalContribution = calculateLiteralContribution(chunkLiteralMatches, false);
-        const baseScore = semanticScore > 0 ? SEMANTIC_WEIGHT * semanticScore + BM25_WEIGHT * bm25Score + VOCAB_WEIGHT * vocabScore : LITERAL_SCORING_CONSTANTS.BASE_SCORE;
-        const boostedScore = applyLiteralBoost(baseScore, chunkLiteralMatches, semanticScore > 0);
+        const literalContribution = calculateLiteralContribution(chunkLiteralMatches, false, lt);
+        const baseScore = semanticScore > 0 ? tw.semantic * semanticScore + tw.bm25 * bm25Score + tw.vocab * vocabScore : lt.baseScore;
+        const boostedScore = applyLiteralBoost(baseScore, chunkLiteralMatches, semanticScore > 0, lt);
         const finalScore = boostedScore + additiveBoost;
+        const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+        const adjustedScore = (finalScore + disc.boost) * disc.penaltyFactor;
         processedChunkIds.add(chunkId);
         results.push({
           filepath,
           chunk,
-          score: finalScore,
+          score: adjustedScore,
           moduleId: this.id,
           context: {
             semanticScore,
@@ -5960,6 +6246,10 @@ class TypeScriptModule {
             fileTypeBoost,
             chunkTypeBoost,
             exportBoost,
+            discriminativeCoverage: disc.salientCoverage,
+            discriminativePenaltyFactor: disc.penaltyFactor,
+            discriminativeBoost: disc.boost,
+            matchedSalientTerms: disc.matchedSalient,
             literalMultiplier: literalContribution.multiplier,
             literalMatchType: literalContribution.bestMatchType,
             literalConfidence: literalContribution.bestConfidence,
@@ -5996,13 +6286,14 @@ class TypeScriptModule {
     return references;
   }
 }
-var DEFAULT_MIN_SCORE2 = 0.15, DEFAULT_TOP_K2 = 10, SEMANTIC_WEIGHT = 0.6, BM25_WEIGHT = 0.25, VOCAB_WEIGHT = 0.15, VOCAB_THRESHOLD = 0.4, TYPESCRIPT_EXTENSIONS, supportsFile;
+var DEFAULT_MIN_SCORE2 = 0.15, DEFAULT_TOP_K2 = 10, TYPESCRIPT_EXTENSIONS, supportsFile;
 var init_typescript = __esm(() => {
   init_embeddings();
   init_services();
   init_config2();
   init_parseCode();
   init_storage();
+  init_entities();
   TYPESCRIPT_EXTENSIONS = [
     ".ts",
     ".tsx",
@@ -7115,6 +7406,9 @@ class PythonModule {
       minScore = DEFAULT_MIN_SCORE3,
       filePatterns
     } = options;
+    const rw = mergeRankingWeights(options.rankingWeights);
+    const lw = rw.language;
+    const lt = rw.literal;
     const { literals: queryLiterals, remainingQuery } = parseQueryLiterals(query);
     const indexDir = getRaggrepDir(ctx.rootDir, ctx.config);
     const symbolicIndex = new SymbolicIndex(indexDir, this.id);
@@ -7207,17 +7501,19 @@ class PythonModule {
       const chunkTypeBoost = calculateChunkTypeBoost2(chunk);
       const exportBoost = calculateExportBoost2(chunk);
       const additiveBoost = pathBoost + fileTypeBoost + chunkTypeBoost + exportBoost;
-      const baseScore = SEMANTIC_WEIGHT2 * semanticScore + BM25_WEIGHT2 * bm25Score;
+      const baseScore = lw.semantic * semanticScore + lw.bm25 * bm25Score;
       const literalMatches = literalMatchMap.get(chunk.id) || [];
-      const literalContribution = calculateLiteralContribution(literalMatches, true);
-      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true);
+      const literalContribution = calculateLiteralContribution(literalMatches, true, lt);
+      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true, lt);
       const finalScore = boostedScore + additiveBoost;
+      const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+      const adjustedScore = (finalScore + disc.boost) * disc.penaltyFactor;
       processedChunkIds.add(chunk.id);
-      if (finalScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0) {
+      if (adjustedScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0) {
         results.push({
           filepath,
           chunk,
-          score: finalScore,
+          score: adjustedScore,
           moduleId: this.id,
           context: {
             semanticScore,
@@ -7226,6 +7522,10 @@ class PythonModule {
             fileTypeBoost,
             chunkTypeBoost,
             exportBoost,
+            discriminativeCoverage: disc.salientCoverage,
+            discriminativePenaltyFactor: disc.penaltyFactor,
+            discriminativeBoost: disc.boost,
+            matchedSalientTerms: disc.matchedSalient,
             literalMultiplier: literalContribution.multiplier,
             literalMatchType: literalContribution.bestMatchType,
             literalConfidence: literalContribution.bestConfidence,
@@ -7260,15 +7560,17 @@ class PythonModule {
       const chunkTypeBoost = calculateChunkTypeBoost2(chunk);
       const exportBoost = calculateExportBoost2(chunk);
       const additiveBoost = pathBoost + fileTypeBoost + chunkTypeBoost + exportBoost;
-      const literalContribution = calculateLiteralContribution(matches, false);
-      const baseScore = semanticScore > 0 ? SEMANTIC_WEIGHT2 * semanticScore + BM25_WEIGHT2 * bm25Score : LITERAL_SCORING_CONSTANTS.BASE_SCORE;
-      const boostedScore = applyLiteralBoost(baseScore, matches, semanticScore > 0);
+      const literalContribution = calculateLiteralContribution(matches, false, lt);
+      const baseScore = semanticScore > 0 ? lw.semantic * semanticScore + lw.bm25 * bm25Score : lt.baseScore;
+      const boostedScore = applyLiteralBoost(baseScore, matches, semanticScore > 0, lt);
       const finalScore = boostedScore + additiveBoost;
+      const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+      const adjustedScore = (finalScore + disc.boost) * disc.penaltyFactor;
       processedChunkIds.add(chunkId);
       results.push({
         filepath,
         chunk,
-        score: finalScore,
+        score: adjustedScore,
         moduleId: this.id,
         context: {
           semanticScore,
@@ -7277,6 +7579,10 @@ class PythonModule {
           fileTypeBoost,
           chunkTypeBoost,
           exportBoost,
+          discriminativeCoverage: disc.salientCoverage,
+          discriminativePenaltyFactor: disc.penaltyFactor,
+          discriminativeBoost: disc.boost,
+          matchedSalientTerms: disc.matchedSalient,
           literalMultiplier: literalContribution.multiplier,
           literalMatchType: literalContribution.bestMatchType,
           literalConfidence: literalContribution.bestConfidence,
@@ -7289,13 +7595,14 @@ class PythonModule {
     return results.slice(0, topK);
   }
 }
-var DEFAULT_MIN_SCORE3 = 0.15, DEFAULT_TOP_K3 = 10, SEMANTIC_WEIGHT2 = 0.7, BM25_WEIGHT2 = 0.3, PYTHON_EXTENSIONS, supportsFile2;
+var DEFAULT_MIN_SCORE3 = 0.15, DEFAULT_TOP_K3 = 10, PYTHON_EXTENSIONS, supportsFile2;
 var init_python = __esm(() => {
   init_embeddings();
   init_services();
   init_config2();
   init_storage();
   init_parsing();
+  init_entities();
   PYTHON_EXTENSIONS = [".py", ".pyw"];
   supportsFile2 = isPythonFile;
 });
@@ -7647,6 +7954,9 @@ class GoModule {
       minScore = DEFAULT_MIN_SCORE4,
       filePatterns
     } = options;
+    const rw = mergeRankingWeights(options.rankingWeights);
+    const lw = rw.language;
+    const lt = rw.literal;
     const { literals: queryLiterals, remainingQuery } = parseQueryLiterals(query);
     const indexDir = getRaggrepDir(ctx.rootDir, ctx.config);
     const symbolicIndex = new SymbolicIndex(indexDir, this.id);
@@ -7739,17 +8049,19 @@ class GoModule {
       const chunkTypeBoost = calculateChunkTypeBoost3(chunk);
       const exportBoost = calculateExportBoost3(chunk);
       const additiveBoost = pathBoost + fileTypeBoost + chunkTypeBoost + exportBoost;
-      const baseScore = SEMANTIC_WEIGHT3 * semanticScore + BM25_WEIGHT3 * bm25Score;
+      const baseScore = lw.semantic * semanticScore + lw.bm25 * bm25Score;
       const literalMatches = literalMatchMap.get(chunk.id) || [];
-      const literalContribution = calculateLiteralContribution(literalMatches, true);
-      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true);
+      const literalContribution = calculateLiteralContribution(literalMatches, true, lt);
+      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true, lt);
       const finalScore = boostedScore + additiveBoost;
+      const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+      const adjustedScore = (finalScore + disc.boost) * disc.penaltyFactor;
       processedChunkIds.add(chunk.id);
-      if (finalScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0) {
+      if (adjustedScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0) {
         results.push({
           filepath,
           chunk,
-          score: finalScore,
+          score: adjustedScore,
           moduleId: this.id,
           context: {
             semanticScore,
@@ -7758,6 +8070,10 @@ class GoModule {
             fileTypeBoost,
             chunkTypeBoost,
             exportBoost,
+            discriminativeCoverage: disc.salientCoverage,
+            discriminativePenaltyFactor: disc.penaltyFactor,
+            discriminativeBoost: disc.boost,
+            matchedSalientTerms: disc.matchedSalient,
             literalMultiplier: literalContribution.multiplier,
             literalMatchType: literalContribution.bestMatchType,
             literalConfidence: literalContribution.bestConfidence,
@@ -7770,13 +8086,14 @@ class GoModule {
     return results.slice(0, topK);
   }
 }
-var DEFAULT_MIN_SCORE4 = 0.15, DEFAULT_TOP_K4 = 10, SEMANTIC_WEIGHT3 = 0.7, BM25_WEIGHT3 = 0.3, GO_EXTENSIONS, supportsFile3;
+var DEFAULT_MIN_SCORE4 = 0.15, DEFAULT_TOP_K4 = 10, GO_EXTENSIONS, supportsFile3;
 var init_go = __esm(() => {
   init_embeddings();
   init_services();
   init_config2();
   init_storage();
   init_parsing();
+  init_entities();
   GO_EXTENSIONS = [".go"];
   supportsFile3 = isGoFile;
 });
@@ -8207,6 +8524,9 @@ class RustModule {
       minScore = DEFAULT_MIN_SCORE5,
       filePatterns
     } = options;
+    const rw = mergeRankingWeights(options.rankingWeights);
+    const lw = rw.language;
+    const lt = rw.literal;
     const { literals: queryLiterals, remainingQuery } = parseQueryLiterals(query);
     const indexDir = getRaggrepDir(ctx.rootDir, ctx.config);
     const symbolicIndex = new SymbolicIndex(indexDir, this.id);
@@ -8299,17 +8619,19 @@ class RustModule {
       const chunkTypeBoost = calculateChunkTypeBoost4(chunk);
       const exportBoost = calculateExportBoost4(chunk);
       const additiveBoost = pathBoost + fileTypeBoost + chunkTypeBoost + exportBoost;
-      const baseScore = SEMANTIC_WEIGHT4 * semanticScore + BM25_WEIGHT4 * bm25Score;
+      const baseScore = lw.semantic * semanticScore + lw.bm25 * bm25Score;
       const literalMatches = literalMatchMap.get(chunk.id) || [];
-      const literalContribution = calculateLiteralContribution(literalMatches, true);
-      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true);
+      const literalContribution = calculateLiteralContribution(literalMatches, true, lt);
+      const boostedScore = applyLiteralBoost(baseScore, literalMatches, true, lt);
       const finalScore = boostedScore + additiveBoost;
+      const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+      const adjustedScore = (finalScore + disc.boost) * disc.penaltyFactor;
       processedChunkIds.add(chunk.id);
-      if (finalScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0) {
+      if (adjustedScore >= minScore || bm25Score > 0.3 || literalMatches.length > 0) {
         results.push({
           filepath,
           chunk,
-          score: finalScore,
+          score: adjustedScore,
           moduleId: this.id,
           context: {
             semanticScore,
@@ -8318,6 +8640,10 @@ class RustModule {
             fileTypeBoost,
             chunkTypeBoost,
             exportBoost,
+            discriminativeCoverage: disc.salientCoverage,
+            discriminativePenaltyFactor: disc.penaltyFactor,
+            discriminativeBoost: disc.boost,
+            matchedSalientTerms: disc.matchedSalient,
             literalMultiplier: literalContribution.multiplier,
             literalMatchType: literalContribution.bestMatchType,
             literalConfidence: literalContribution.bestConfidence,
@@ -8330,13 +8656,14 @@ class RustModule {
     return results.slice(0, topK);
   }
 }
-var DEFAULT_MIN_SCORE5 = 0.15, DEFAULT_TOP_K5 = 10, SEMANTIC_WEIGHT4 = 0.7, BM25_WEIGHT4 = 0.3, RUST_EXTENSIONS, supportsFile4;
+var DEFAULT_MIN_SCORE5 = 0.15, DEFAULT_TOP_K5 = 10, RUST_EXTENSIONS, supportsFile4;
 var init_rust = __esm(() => {
   init_embeddings();
   init_services();
   init_config2();
   init_storage();
   init_parsing();
+  init_entities();
   RUST_EXTENSIONS = [".rs"];
   supportsFile4 = isRustFile;
 });
@@ -8466,6 +8793,8 @@ class JsonModule {
       minScore = DEFAULT_MIN_SCORE6,
       filePatterns
     } = options;
+    const rw = mergeRankingWeights(options.rankingWeights);
+    const jw = rw.json;
     const { literals: queryLiterals, remainingQuery } = parseQueryLiterals(query);
     const indexDir = getRaggrepDir(ctx.rootDir, ctx.config);
     const symbolicIndex = new SymbolicIndex(indexDir, this.id);
@@ -8519,9 +8848,9 @@ class JsonModule {
       const bm25Score = bm25Scores.get(chunk.id) || 0;
       const literalMatches = literalMatchMap.get(chunk.id) || [];
       const literalContribution = calculateLiteralContribution(literalMatches, bm25Score > 0);
-      const baseScore = BM25_WEIGHT5 * bm25Score;
-      const boostedScore = applyLiteralBoost(baseScore, literalMatches, bm25Score > 0);
-      const literalBase = literalMatches.length > 0 && bm25Score === 0 ? LITERAL_SCORING_CONSTANTS.BASE_SCORE * LITERAL_WEIGHT : 0;
+      const baseScore = jw.bm25 * bm25Score;
+      const boostedScore = applyLiteralBoost(baseScore, literalMatches, bm25Score > 0, rw.literal);
+      const literalBase = literalMatches.length > 0 && bm25Score === 0 ? rw.literal.baseScore * jw.literalBaseWeight : 0;
       const finalScore = boostedScore + literalBase;
       processedChunkIds.add(chunk.id);
       if (finalScore >= minScore || literalMatches.length > 0) {
@@ -8554,7 +8883,7 @@ class JsonModule {
       if (!chunk)
         continue;
       const literalContribution = calculateLiteralContribution(matches, false);
-      const score = LITERAL_SCORING_CONSTANTS.BASE_SCORE * literalContribution.multiplier;
+      const score = rw.literal.baseScore * literalContribution.multiplier;
       processedChunkIds.add(chunkId);
       results.push({
         filepath,
@@ -8575,11 +8904,12 @@ class JsonModule {
     return results.slice(0, topK);
   }
 }
-var DEFAULT_MIN_SCORE6 = 0.1, DEFAULT_TOP_K6 = 10, BM25_WEIGHT5 = 0.4, LITERAL_WEIGHT = 0.6, JSON_EXTENSIONS, supportsFile5;
+var DEFAULT_MIN_SCORE6 = 0.1, DEFAULT_TOP_K6 = 10, JSON_EXTENSIONS, supportsFile5;
 var init_json = __esm(() => {
   init_services();
   init_config2();
   init_storage();
+  init_entities();
   JSON_EXTENSIONS = [".json"];
   supportsFile5 = isJsonFile;
 });
@@ -8814,6 +9144,8 @@ class MarkdownModule {
       minScore = DEFAULT_MIN_SCORE7,
       filePatterns
     } = options;
+    const rw = mergeRankingWeights(options.rankingWeights);
+    const mw = rw.markdown;
     const indexDir = getRaggrepDir(ctx.rootDir, ctx.config);
     const symbolicIndex = new SymbolicIndex(indexDir, this.id);
     let allFiles;
@@ -8879,15 +9211,18 @@ class MarkdownModule {
         "what",
         "explain"
       ].includes(t))) {
-        docBoost = 0.05;
-      }
-      const headingBoost = calculateHeadingLevelBoost(chunk);
-      const hybridScore = SEMANTIC_WEIGHT5 * semanticScore + BM25_WEIGHT6 * bm25Score + docBoost + headingBoost + phraseMatch.boost;
-      if (hybridScore >= minScore || bm25Score > 0.3 || phraseMatch.isSignificant) {
+        docBoost = mw.docIntentBoost;
+      }
+      const rawHeadingBoost = calculateHeadingLevelBoost(chunk);
+      const headingBoost = rawHeadingBoost * (mw.headingPhraseCoverageMin + mw.headingPhraseCoverageSpan * (phraseMatch.totalTokenCount > 0 ? phraseMatch.coverage : 1));
+      const hybridScore = mw.semantic * semanticScore + mw.bm25 * bm25Score + docBoost + headingBoost + phraseMatch.boost;
+      const disc = scoreDiscriminativeTerms(bm25Index, query, chunk.content, chunk.name, rw.discriminative);
+      const finalScore = (hybridScore + disc.boost) * disc.penaltyFactor;
+      if (finalScore >= minScore || bm25Score > 0.3 || phraseMatch.isSignificant) {
         results.push({
           filepath,
           chunk,
-          score: hybridScore,
+          score: finalScore,
           moduleId: this.id,
           context: {
             semanticScore,
@@ -8896,7 +9231,11 @@ class MarkdownModule {
             phraseCoverage: phraseMatch.coverage,
             docBoost,
             headingBoost,
-            headingLevel: chunk.metadata?.headingLevel
+            headingLevel: chunk.metadata?.headingLevel,
+            discriminativeCoverage: disc.salientCoverage,
+            discriminativePenaltyFactor: disc.penaltyFactor,
+            discriminativeBoost: disc.boost,
+            matchedSalientTerms: disc.matchedSalient
           }
         });
       }
@@ -8905,11 +9244,12 @@ class MarkdownModule {
     return results.slice(0, topK);
   }
 }
-var DEFAULT_MIN_SCORE7 = 0.15, DEFAULT_TOP_K7 = 10, SEMANTIC_WEIGHT5 = 0.7, BM25_WEIGHT6 = 0.3, MARKDOWN_EXTENSIONS, supportsFile6;
+var DEFAULT_MIN_SCORE7 = 0.15, DEFAULT_TOP_K7 = 10, MARKDOWN_EXTENSIONS, supportsFile6;
 var init_markdown = __esm(() => {
   init_embeddings();
   init_services();
   init_config2();
+  init_entities();
   init_storage();
   MARKDOWN_EXTENSIONS = [".md", ".txt"];
   supportsFile6 = isMarkdownFile;
@@ -11954,7 +12294,9 @@ async function hybridSearch(rootDir, query, options = {}) {
   if (ensureFresh) {
     await ensureIndexFresh(rootDir, { quiet: true });
   }
-  console.log(`Searching for: "${query}"`);
+  if (!options.quiet) {
+    console.log(`Searching for: "${query}"`);
+  }
   const config = await loadConfig(rootDir);
   await registerBuiltInModules();
   const globalManifest = await loadGlobalManifest2(rootDir, config);
@@ -12017,10 +12359,18 @@ async function hybridSearch(rootDir, query, options = {}) {
       }
     }
   }
-  filteredResults.sort((a, b) => b.score - a.score);
+  const rw = mergeRankingWeights(options.rankingWeights);
+  let ranked = filteredResults.map((r) => attachMatchScales(r, rw));
+  for (const r of ranked) {
+    if (r.context?.exactMatchFusion) {
+      r.structuredMatch = clamp01((r.structuredMatch ?? 0) * 1.5);
+    }
+  }
+  const rankBy = options.rankBy ?? DEFAULT_SEARCH_OPTIONS.rankBy;
+  ranked.sort((a, b) => compareSearchResultsByRankBy(a, b, rankBy));
   const topK = options.topK ?? 10;
   return {
-    results: filteredResults.slice(0, topK),
+    results: ranked.slice(0, topK),
     exactMatches,
     fusionApplied
   };
@@ -12111,7 +12461,9 @@ function formatSearchResults2(results) {
     const nameInfo = chunk.name ? ` (${chunk.name})` : "";
     output += `${i + 1}. ${location}${nameInfo}
 `;
-    output += `   Score: ${(result.score * 100).toFixed(1)}% | Type: ${chunk.type}`;
+    const sm = result.semanticMatch != null ? ` | Semantic: ${(result.semanticMatch * 100).toFixed(1)}%` : "";
+    const st = result.structuredMatch != null ? ` | Structured: ${(result.structuredMatch * 100).toFixed(1)}%` : "";
+    output += `   Score: ${(result.score * 100).toFixed(1)}%${st}${sm} | Type: ${chunk.type}`;
     output += ` | via ${formatModuleName(result.moduleId)}`;
     if (chunk.isExported) {
       output += " | exported";
@@ -12209,6 +12561,7 @@ var init_search = __esm(() => {
   init_registry();
   init_indexer();
   init_services();
+  init_entities();
   init_usecases();
   init_filesystem();
 });
@@ -12743,7 +13096,7 @@ import { stat as stat3 } from "fs/promises";
 // package.json
 var package_default = {
   name: "raggrep",
-  version: "0.17.1",
+  version: "0.18.0",
   description: "Local filesystem-based RAG system for codebases - semantic search using local embeddings",
   type: "module",
   main: "./dist/index.js",
@@ -12771,9 +13124,12 @@ var package_default = {
     prepublishOnly: "bun run build",
     raggrep: "bun run src/app/cli/main.ts",
     test: "bun test",
-    typecheck: "tsc --noEmit -p tsconfig.json && tsc --noEmit -p scripts/tsconfig.json",
-    "bench:embeddings": "bun run scripts/benchmark-embedding-runtimes.ts",
-    "bench:retrieval": "bun run scripts/benchmark-retrieval-quality.ts",
+    typecheck: "tsc --noEmit -p tsconfig.json && tsc --noEmit -p research/tsconfig.json",
+    "bench:embeddings": "bun run research/bench/benchmark-embedding-runtimes.ts",
+    "bench:retrieval": "bun run research/bench/benchmark-retrieval-quality.ts",
+    "eval:golden": "bun run research/eval/run-golden-queries.ts",
+    "bench:golden-convex": "bun run research/bench/benchmark-raggrep-golden-queries.ts",
+    "bench:golden-hillclimb": "bun run research/bench/benchmark-raggrep-hillclimb.ts",
     dev: "bun run src/app/cli/main.ts"
   },
   keywords: [
@@ -12922,6 +13278,14 @@ function parseFlags(args2) {
         console.error("--dir / -C requires a path to the project directory to index or search.");
         process.exit(1);
       }
+    } else if (arg === "--rank-by") {
+      const v = args2[++i];
+      if (v === "structured" || v === "semantic" || v === "combined") {
+        flags.rankBy = v;
+      } else {
+        console.error(`--rank-by must be structured, semantic, or combined (got: ${v})`);
+        process.exit(1);
+      }
     } else if (arg === "--tool") {
       flags.forceTool = true;
     } else if (arg === "--skill") {
@@ -13053,6 +13417,7 @@ Options:
   -s, --min-score <n>  Minimum similarity score 0-1 (default: 0.15)
   -t, --type <ext>     Filter by file extension (e.g., ts, tsx, js)
   -f, --filter <path>  Filter by path or glob pattern (can be used multiple times)
+  --rank-by <mode>    Order results: structured (default), semantic, or combined (fused score only)
   -T, --timing         Show timing breakdown for performance profiling
   -h, --help           Show this help message
 
@@ -13151,6 +13516,7 @@ Examples:
           minScore: flags.minScore,
           filePatterns,
           pathFilter: flags.pathFilter,
+          rankBy: flags.rankBy,
           ensureFresh: false
         });
         console.log(formatHybridSearchResults2(hybridResults));
@@ -13386,4 +13752,4 @@ Run 'raggrep <command> --help' for more information.
 }
 main();
 
-//# debugId=1CBA39A0838887E764756E2164756E21
+//# debugId=9CA948E12F18492C64756E2164756E21