raggrep 0.9.0 → 0.10.1

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

@@ -46,6 +46,8 @@ export interface FileIntrospection {
     depth: number;
     /** Path segments for keyword matching */
     pathSegments: string[];
+    /** Relative path to nearest README in directory hierarchy */
+    nearestReadme?: string;
 }
 /**
  * Project structure metadata.

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

@@ -31,6 +31,8 @@ export interface ExtractedLiteral {
     type: LiteralType;
     /** How this chunk relates to the literal */
     matchType: LiteralMatchType;
+    /** Vocabulary words extracted from the literal (e.g., getUserById → ["get", "user", "by", "id"]) */
+    vocabulary?: string[];
 }
 /**
  * A literal detected in a search query.
@@ -80,6 +82,8 @@ export interface LiteralIndexEntry {
     originalCasing: string;
     type: LiteralType;
     matchType: LiteralMatchType;
+    /** Vocabulary words for partial matching */
+    vocabulary?: string[];
 }
 /**
  * Serialized literal index data for persistence.

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

@@ -8,3 +8,4 @@ export type { FileSystem, FileStats } from "./filesystem";
 export type { EmbeddingProvider, EmbeddingConfig, EmbeddingModelName, } from "./embedding";
 export type { IndexStorage } from "./storage";
 export type { Logger, ProgressInfo, LoggerFactory } from "./logger";
+export type { IParser, IGrammarManager, ParsedChunk, ParseResult, ParserConfig, ParserLanguage, GrammarStatus, } from "./parser";

package/dist/domain/ports/parser.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Parser Port
+ *
+ * Defines the interface for code parsers that can extract semantic chunks from source files.
+ * This abstraction allows for different parsing implementations (TypeScript API, tree-sitter)
+ * while keeping the domain layer independent of specific parsing technologies.
+ */
+import type { ChunkType } from "../entities/chunk";
+/**
+ * A parsed chunk of code with location and metadata.
+ * This is the output of any parser implementation.
+ */
+export interface ParsedChunk {
+    /** The source code content */
+    content: string;
+    /** 1-based start line number */
+    startLine: number;
+    /** 1-based end line number */
+    endLine: number;
+    /** The type of code construct */
+    type: ChunkType;
+    /** Name of the construct (function name, class name, etc.) */
+    name?: string;
+    /** Whether this is exported */
+    isExported?: boolean;
+    /** Documentation comment if present (JSDoc, docstring, etc.) */
+    docComment?: string;
+    /** Line comments associated with this chunk */
+    comments?: string[];
+}
+/**
+ * Supported languages for parsing.
+ */
+export type ParserLanguage = "typescript" | "javascript" | "python" | "go" | "rust" | "java";
+/**
+ * Parser configuration options.
+ */
+export interface ParserConfig {
+    /** Include full file chunk in output */
+    includeFullFileChunk?: boolean;
+    /** Associate comments with code chunks */
+    associateComments?: boolean;
+    /** Language-specific options */
+    languageOptions?: Record<string, unknown>;
+}
+/**
+ * Result of parsing a file.
+ */
+export interface ParseResult {
+    /** Parsed chunks */
+    chunks: ParsedChunk[];
+    /** Language detected/used */
+    language: ParserLanguage;
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Error message if parsing failed */
+    error?: string;
+}
+/**
+ * Parser interface for extracting semantic chunks from source code.
+ *
+ * Implementations:
+ * - TypeScriptParser: Uses TypeScript Compiler API for TS/JS files
+ * - TreeSitterParser: Uses tree-sitter for Python, Go, Rust, etc.
+ */
+export interface IParser {
+    /**
+     * Languages this parser supports.
+     */
+    readonly supportedLanguages: ParserLanguage[];
+    /**
+     * Parse source code into semantic chunks.
+     *
+     * @param content - The source code content
+     * @param filepath - The file path (used for language detection and context)
+     * @param config - Optional parser configuration
+     * @returns Parse result with chunks or error
+     */
+    parse(content: string, filepath: string, config?: ParserConfig): Promise<ParseResult>;
+    /**
+     * Check if the parser can handle a specific file.
+     *
+     * @param filepath - The file path to check
+     * @returns True if the parser can handle this file
+     */
+    canParse(filepath: string): boolean;
+}
+/**
+ * Grammar status for dynamic installation.
+ */
+export interface GrammarStatus {
+    /** Language identifier */
+    language: ParserLanguage;
+    /** Whether the grammar is installed */
+    installed: boolean;
+    /** Grammar package name if installed */
+    packageName?: string;
+    /** Error message if installation failed */
+    error?: string;
+}
+/**
+ * Grammar manager interface for dynamic grammar installation.
+ */
+export interface IGrammarManager {
+    /**
+     * Check if a grammar is installed.
+     */
+    isInstalled(language: ParserLanguage): Promise<boolean>;
+    /**
+     * Install a grammar for a language.
+     */
+    install(language: ParserLanguage): Promise<GrammarStatus>;
+    /**
+     * Get status of all grammars.
+     */
+    getStatus(): Promise<GrammarStatus[]>;
+    /**
+     * Pre-install grammars for a batch of languages.
+     */
+    preInstallBatch(languages: ParserLanguage[]): Promise<GrammarStatus[]>;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Configuration Validator
+ *
+ * Validates RAGgrep configuration for correctness and provides
+ * helpful error messages for invalid configurations.
+ */
+import type { Config } from "../entities/config";
+/**
+ * Validation result for a single field or section.
+ */
+export interface ValidationIssue {
+    /** The path to the invalid field (e.g., "modules[0].id") */
+    path: string;
+    /** The type of issue: error (invalid), warning (suboptimal), info (suggestion) */
+    severity: "error" | "warning" | "info";
+    /** Human-readable description of the issue */
+    message: string;
+    /** Suggested fix (optional) */
+    suggestion?: string;
+}
+/**
+ * Overall validation result.
+ */
+export interface ValidationResult {
+    /** Whether the configuration is valid (no errors) */
+    valid: boolean;
+    /** List of all issues found */
+    issues: ValidationIssue[];
+    /** Helper method to get issues by severity */
+    getErrors(): ValidationIssue[];
+    getWarnings(): ValidationIssue[];
+    getInfos(): ValidationIssue[];
+}
+/**
+ * Validate a RAGgrep configuration.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with any issues found
+ */
+export declare function validateConfig(config: Config): ValidationResult;
+/**
+ * Format validation issues for display.
+ */
+export declare function formatValidationIssues(issues: ValidationIssue[]): string;

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

@@ -0,0 +1 @@
+export {};

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

@@ -10,7 +10,9 @@ 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";
+export { extractLiterals, extractLiteralsWithReferences, extractVocabulary, } from "./literalExtractor";
+export { calculateLiteralMultiplier, calculateMaxMultiplier, calculateLiteralContribution, calculateVocabularyMatch, applyLiteralBoost, mergeWithLiteralBoost, LITERAL_SCORING_CONSTANTS, type LiteralScoreContribution, type VocabularyMatchResult, type MergeInput, type MergeOutput, } from "./literalScorer";
 export { getSynonyms, expandQuery, DEFAULT_LEXICON, EXPANSION_WEIGHTS, DEFAULT_EXPANSION_OPTIONS, } from "./lexicon";
 export { extractJsonPaths, extractJsonKeywords } from "./jsonPathExtractor";
+export { introspectFile, findNearestReadme, introspectionToKeywords, detectScopeFromName, findProjectForFile, calculateIntrospectionBoost, type IntrospectFileOptions, } from "./introspection";
+export { validateConfig, formatValidationIssues, type ValidationIssue, type ValidationResult, } from "./configValidator";

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

@@ -5,14 +5,34 @@
  * No I/O operations - all functions operate on provided data.
  */
 import type { FileIntrospection, Project, ProjectStructure, Scope } from "../entities/introspection";
+/**
+ * Options for introspecting a file.
+ */
+export interface IntrospectFileOptions {
+    /** File content for framework detection */
+    fileContent?: string;
+    /**
+     * Function to check if a file exists.
+     * Used for README discovery without I/O in the domain layer.
+     */
+    fileExists?: (filepath: string) => boolean;
+}
 /**
  * Extract introspection metadata for a file.
  *
  * @param filepath - Relative file path
  * @param structure - Project structure (from detectProjectStructure)
- * @param fileContent - Optional file content for framework detection
+ * @param options - Optional configuration including file content and file existence checker
+ */
+export declare function introspectFile(filepath: string, structure: ProjectStructure, options?: IntrospectFileOptions | string): FileIntrospection;
+/**
+ * Find the nearest README file by traversing up the directory hierarchy.
+ *
+ * @param filepath - Relative file path (normalized with forward slashes)
+ * @param fileExists - Function to check if a file exists
+ * @returns Relative path to the nearest README, or undefined if none found
  */
-export declare function introspectFile(filepath: string, structure: ProjectStructure, fileContent?: string): FileIntrospection;
+export declare function findNearestReadme(filepath: string, fileExists: (filepath: string) => boolean): string | undefined;
 /**
  * Extract keywords from introspection for search boosting.
  */

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

@@ -8,6 +8,20 @@
  */
 import type { Chunk } from "../entities/chunk";
 import type { ExtractedLiteral } from "../entities/literal";
+/**
+ * Extract vocabulary words from a literal (identifier) name.
+ *
+ * Handles multiple naming conventions:
+ * - camelCase: getUserById → ["get", "user", "by", "id"]
+ * - PascalCase: AuthService → ["auth", "service"]
+ * - snake_case: get_user_by_id → ["get", "user", "by", "id"]
+ * - kebab-case: get-user-by-id → ["get", "user", "by", "id"]
+ * - SCREAMING_SNAKE_CASE: MAX_RETRY_COUNT → ["max", "retry", "count"]
+ *
+ * @param literal - The identifier name to extract vocabulary from
+ * @returns Array of unique vocabulary words (lowercase, length > 1)
+ */
+export declare function extractVocabulary(literal: string): string[];
 /**
  * Extract literals from a code chunk.
  *
@@ -15,6 +29,8 @@ import type { ExtractedLiteral } from "../entities/literal";
  * as a "definition" literal. The name comes from proper AST parsing,
  * so it's accurate and reliable.
  *
+ * Also extracts vocabulary words from the literal for partial matching.
+ *
  * @param chunk - The code chunk to extract literals from
  * @returns Array of extracted literals (typically just the definition)
  */

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

@@ -0,0 +1,6 @@
+/**
+ * Literal Extractor Tests
+ *
+ * Tests for vocabulary extraction and literal extraction from code chunks.
+ */
+export {};

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

@@ -15,6 +15,17 @@ export declare const LITERAL_SCORING_CONSTANTS: {
     BASE_SCORE: number;
     /** Multipliers by match type and confidence */
     MULTIPLIERS: Record<LiteralMatchType, Record<LiteralConfidence, number>>;
+    /** Vocabulary match scoring */
+    VOCABULARY: {
+        /** Base multiplier for vocabulary-only matches (no exact literal match) */
+        BASE_MULTIPLIER: number;
+        /** Bonus per additional vocabulary word matched (up to a limit) */
+        PER_WORD_BONUS: number;
+        /** Maximum vocabulary bonus */
+        MAX_VOCABULARY_BONUS: number;
+        /** Minimum vocabulary words required for a match to count */
+        MIN_WORDS_FOR_MATCH: number;
+    };
 };
 /**
  * Calculate the literal multiplier for a given match type and confidence.
@@ -33,6 +44,30 @@ export declare function calculateLiteralMultiplier(matchType: LiteralMatchType,
  * @returns The maximum multiplier, or 1.0 if no matches
  */
 export declare function calculateMaxMultiplier(matches: LiteralMatch[]): number;
+/**
+ * Result of vocabulary-based matching.
+ */
+export interface VocabularyMatchResult {
+    /** Number of vocabulary words that matched */
+    matchedWordCount: number;
+    /** The vocabulary words that matched */
+    matchedWords: string[];
+    /** Multiplier to apply based on vocabulary match */
+    multiplier: number;
+    /** Whether this is a meaningful match (above threshold) */
+    isSignificant: boolean;
+}
+/**
+ * Calculate vocabulary-based scoring for a chunk.
+ *
+ * This is used for partial matching when no exact literal match exists.
+ * E.g., query "user authentication" might match chunk with "getUserAuth" literal.
+ *
+ * @param queryVocabulary - Vocabulary words extracted from the query
+ * @param chunkVocabulary - Vocabulary words extracted from chunk literals
+ * @returns Vocabulary match result with multiplier
+ */
+export declare function calculateVocabularyMatch(queryVocabulary: string[], chunkVocabulary: string[]): VocabularyMatchResult;
 /**
  * Score contribution from literal matches.
  * Used for debugging and explainability.