raggrep 0.6.0 → 0.7.0

package/dist/domain/entities/index.d.ts

@@ -14,3 +14,5 @@ export type { Config, ModuleConfig } from "./config";
 export { DEFAULT_IGNORE_PATHS, DEFAULT_EXTENSIONS, createDefaultConfig, } from "./config";
 export type { FileIntrospection, ProjectStructure, Project, ProjectType, Scope, IntrospectionConfig, } from "./introspection";
 export type { FileConvention, ConventionCategory, FrameworkConventions, ConventionMatch, } from "./conventions";
+export type { LiteralType, LiteralMatchType, LiteralConfidence, LiteralDetectionMethod, ExtractedLiteral, DetectedLiteral, QueryLiteralParseResult, LiteralMatch, LiteralIndexEntry, LiteralIndexData, } from "./literal";
+export { LITERAL_SCORING } from "./literal";

package/dist/domain/entities/literal.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Literal Entity
+ *
+ * Types for literal boosting - exact-match term detection and scoring.
+ * Supports both query literal detection and code literal extraction.
+ */
+/**
+ * Types of literals that can be extracted from code.
+ */
+export type LiteralType = "className" | "functionName" | "variableName" | "interfaceName" | "typeName" | "enumName" | "packageName" | "identifier";
+/**
+ * How the chunk relates to the literal.
+ * Used for scoring - definitions rank higher than references.
+ */
+export type LiteralMatchType = "definition" | "reference" | "import";
+/**
+ * Confidence level for detected literals.
+ */
+export type LiteralConfidence = "high" | "medium" | "low";
+/**
+ * How a literal was detected in a query.
+ */
+export type LiteralDetectionMethod = "explicit-backtick" | "explicit-quote" | "implicit-casing";
+/**
+ * A literal extracted from indexed code.
+ */
+export interface ExtractedLiteral {
+    /** The exact term as it appears in code */
+    value: string;
+    /** Type classification */
+    type: LiteralType;
+    /** How this chunk relates to the literal */
+    matchType: LiteralMatchType;
+}
+/**
+ * A literal detected in a search query.
+ */
+export interface DetectedLiteral {
+    /** The literal value (without backticks/quotes) */
+    value: string;
+    /** Original as it appeared in query (with backticks/quotes if explicit) */
+    rawValue: string;
+    /** Detection confidence */
+    confidence: LiteralConfidence;
+    /** How the literal was detected */
+    detectionMethod: LiteralDetectionMethod;
+    /** Inferred type based on pattern */
+    inferredType?: LiteralType;
+}
+/**
+ * Result of parsing a query for literals.
+ */
+export interface QueryLiteralParseResult {
+    /** Detected literals */
+    literals: DetectedLiteral[];
+    /** Query with literals removed (for semantic search) */
+    remainingQuery: string;
+}
+/**
+ * A match between a query literal and an indexed literal.
+ */
+export interface LiteralMatch {
+    /** The query literal that was matched */
+    queryLiteral: DetectedLiteral;
+    /** The indexed literal it matched */
+    indexedLiteral: ExtractedLiteral;
+    /** ID of the chunk containing this literal */
+    chunkId: string;
+    /** Filepath of the file containing the chunk */
+    filepath: string;
+    /** Whether the match is exact (case-sensitive) */
+    exactMatch: boolean;
+}
+/**
+ * Serialized format for literal index storage.
+ */
+export interface LiteralIndexEntry {
+    chunkId: string;
+    filepath: string;
+    originalCasing: string;
+    type: LiteralType;
+    matchType: LiteralMatchType;
+}
+/**
+ * Serialized literal index data for persistence.
+ */
+export interface LiteralIndexData {
+    /** Schema version */
+    version: string;
+    /** Map from literal value (lowercase) → entries */
+    entries: Record<string, LiteralIndexEntry[]>;
+}
+/**
+ * Scoring constants for literal boosting.
+ */
+export declare const LITERAL_SCORING: {
+    /** Base score for chunks found only via literal index */
+    BASE_SCORE: number;
+    /** Multipliers by match type and confidence */
+    MULTIPLIERS: Record<LiteralMatchType, Record<LiteralConfidence, number>>;
+};

package/dist/domain/services/index.d.ts

@@ -9,3 +9,6 @@ export { extractKeywords, extractPathKeywords, parsePathContext, formatPathConte
 export { cosineSimilarity, euclideanDistance } from "./similarity";
 export { detectQueryIntent, extractQueryTerms, calculateFileTypeBoost, isSourceCodeFile, isDocFile, isDataFile, IMPLEMENTATION_TERMS, DOCUMENTATION_TERMS, SOURCE_CODE_EXTENSIONS, DOC_EXTENSIONS, DATA_EXTENSIONS, type QueryIntent, } from "./queryIntent";
 export { createLineBasedChunks, createSingleChunk, generateChunkId, DEFAULT_CHUNK_SIZE, DEFAULT_OVERLAP, type TextChunk, type ChunkingOptions, } from "./chunking";
+export { parseQueryLiterals } from "./queryLiteralParser";
+export { extractLiterals, extractLiteralsWithReferences, } from "./literalExtractor";
+export { calculateLiteralMultiplier, calculateMaxMultiplier, calculateLiteralContribution, applyLiteralBoost, mergeWithLiteralBoost, LITERAL_SCORING_CONSTANTS, type LiteralScoreContribution, type MergeInput, type MergeOutput, } from "./literalScorer";

package/dist/domain/services/literalExtractor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Literal Extractor
+ *
+ * Extracts literals from code chunks for indexing.
+ * For TypeScript/JavaScript, uses the chunk name from AST parsing.
+ *
+ * This is a pure domain service with no external dependencies.
+ */
+import type { Chunk } from "../entities/chunk";
+import type { ExtractedLiteral } from "../entities/literal";
+/**
+ * Extract literals from a code chunk.
+ *
+ * For TypeScript/JavaScript chunks, this extracts the chunk's name
+ * as a "definition" literal. The name comes from proper AST parsing,
+ * so it's accurate and reliable.
+ *
+ * @param chunk - The code chunk to extract literals from
+ * @returns Array of extracted literals (typically just the definition)
+ */
+export declare function extractLiterals(chunk: Chunk): ExtractedLiteral[];
+/**
+ * Extract literals from a code chunk with additional reference extraction.
+ *
+ * This version also extracts references from the chunk content using
+ * pattern matching. Use this for modules that want deeper literal indexing.
+ *
+ * @param chunk - The code chunk to extract literals from
+ * @param options - Extraction options
+ * @returns Array of extracted literals
+ */
+export declare function extractLiteralsWithReferences(chunk: Chunk, options?: {
+    includeImports?: boolean;
+    includeTypeRefs?: boolean;
+}): ExtractedLiteral[];

package/dist/domain/services/literalScorer.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Literal Scorer
+ *
+ * Calculates multiplicative score boosts for literal matches.
+ * Implements the three-source merge strategy for literal boosting.
+ *
+ * This is a pure domain service with no external dependencies.
+ */
+import type { LiteralMatch, LiteralMatchType, LiteralConfidence } from "../entities/literal";
+/**
+ * Scoring constants for literal boosting.
+ */
+export declare const LITERAL_SCORING_CONSTANTS: {
+    /** Base score for chunks found only via literal index */
+    BASE_SCORE: number;
+    /** Multipliers by match type and confidence */
+    MULTIPLIERS: Record<LiteralMatchType, Record<LiteralConfidence, number>>;
+};
+/**
+ * Calculate the literal multiplier for a given match type and confidence.
+ *
+ * @param matchType - How the chunk relates to the literal (definition/reference/import)
+ * @param confidence - Detection confidence of the query literal
+ * @returns Multiplier to apply to the base score
+ */
+export declare function calculateLiteralMultiplier(matchType: LiteralMatchType, confidence: LiteralConfidence): number;
+/**
+ * Calculate the maximum multiplier for a set of literal matches.
+ *
+ * When a chunk has multiple literal matches, use the highest multiplier.
+ *
+ * @param matches - Array of literal matches for a chunk
+ * @returns The maximum multiplier, or 1.0 if no matches
+ */
+export declare function calculateMaxMultiplier(matches: LiteralMatch[]): number;
+/**
+ * Score contribution from literal matches.
+ * Used for debugging and explainability.
+ */
+export interface LiteralScoreContribution {
+    /** The multiplier applied */
+    multiplier: number;
+    /** Whether this is a literal-only match (not found by semantic/BM25) */
+    literalOnly: boolean;
+    /** Match type of the best match */
+    bestMatchType?: LiteralMatchType;
+    /** Confidence of the best match */
+    bestConfidence?: LiteralConfidence;
+    /** Number of literal matches */
+    matchCount: number;
+}
+/**
+ * Calculate the literal score contribution for a chunk.
+ *
+ * @param matches - Literal matches for the chunk (may be empty)
+ * @param hasSemanticOrBm25 - Whether the chunk was found by semantic or BM25 search
+ * @returns Score contribution details
+ */
+export declare function calculateLiteralContribution(matches: LiteralMatch[], hasSemanticOrBm25: boolean): LiteralScoreContribution;
+/**
+ * Apply literal boosting to a base score.
+ *
+ * Scoring rules:
+ * - If chunk has both semantic/BM25 and literal match: multiply base by multiplier
+ * - If chunk has only literal match: use BASE_SCORE
+ * - If chunk has no literal match: use base score as-is
+ *
+ * @param baseScore - Score from semantic/BM25 search (0 if not found)
+ * @param matches - Literal matches for the chunk
+ * @param hasSemanticOrBm25 - Whether the chunk was found by semantic or BM25
+ * @returns Final score after literal boosting
+ */
+export declare function applyLiteralBoost(baseScore: number, matches: LiteralMatch[], hasSemanticOrBm25: boolean): number;
+/**
+ * Merge results from three search sources with literal boosting.
+ *
+ * @param semanticBm25Results - Results from semantic and BM25 search
+ * @param literalMatches - Map from chunk ID to literal matches
+ * @returns Results with literal boosting applied
+ */
+export interface MergeInput {
+    /** Chunk ID */
+    chunkId: string;
+    /** Score from semantic/BM25 search */
+    baseScore: number;
+}
+export interface MergeOutput extends MergeInput {
+    /** Final score after literal boosting */
+    finalScore: number;
+    /** Literal contribution details */
+    literalContribution: LiteralScoreContribution;
+}
+export declare function mergeWithLiteralBoost(semanticBm25Results: MergeInput[], literalMatchMap: Map<string, LiteralMatch[]>): MergeOutput[];

package/dist/domain/services/queryLiteralParser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Query Literal Parser
+ *
+ * Parses search queries to extract literals for exact-match boosting.
+ * Supports explicit detection (backticks, quotes) and implicit detection (casing patterns).
+ *
+ * This is a pure domain service with no external dependencies.
+ */
+import type { QueryLiteralParseResult } from "../entities/literal";
+/**
+ * Parse a search query to extract literals.
+ *
+ * Detects:
+ * - Explicit literals: `backticks` or "quotes"
+ * - Implicit literals: PascalCase, camelCase, SCREAMING_SNAKE, snake_case, kebab-case
+ *
+ * @param query - The search query to parse
+ * @returns Detected literals and remaining query for semantic search
+ */
+export declare function parseQueryLiterals(query: string): QueryLiteralParseResult;

package/dist/domain/services/queryLiteralParser.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * QueryLiteralParser Tests
+ *
+ * Comprehensive tests for query literal detection.
+ * Tests explicit (backticks, quotes) and implicit (casing patterns) detection.
+ */
+export {};