raggrep 0.3.0 → 0.5.0

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

@@ -35,6 +35,12 @@ export interface Config {
 export declare const DEFAULT_IGNORE_PATHS: string[];
 /**
  * Default file extensions to index.
+ *
+ * Note: Each module filters for its own supported extensions.
+ * - language/typescript: .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts
+ * - data/json: .json
+ * - docs/markdown: .md
+ * - core: all remaining extensions
  */
 export declare const DEFAULT_EXTENSIONS: string[];
 /**

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

@@ -5,6 +5,7 @@
  * This allows the domain to remain independent of the actual embedding implementation
  * (e.g., Transformers.js, OpenAI API, local models).
  */
+import type { Logger } from "./logger";
 /**
  * Available embedding model names
  */
@@ -15,8 +16,10 @@ export type EmbeddingModelName = "all-MiniLM-L6-v2" | "all-MiniLM-L12-v2" | "bge
 export interface EmbeddingConfig {
     /** Model name to use */
     model: EmbeddingModelName;
-    /** Whether to show progress during model loading */
+    /** Whether to show progress during model loading (deprecated, use logger instead) */
     showProgress?: boolean;
+    /** Logger for reporting download progress */
+    logger?: Logger;
 }
 /**
  * Abstract embedding provider interface.

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

@@ -5,5 +5,6 @@
  * These are implemented by infrastructure adapters.
  */
 export type { FileSystem, FileStats } from "./filesystem";
-export type { EmbeddingProvider, EmbeddingConfig, EmbeddingModelName } from "./embedding";
+export type { EmbeddingProvider, EmbeddingConfig, EmbeddingModelName, } from "./embedding";
 export type { IndexStorage } from "./storage";
+export type { Logger, ProgressInfo, LoggerFactory } from "./logger";

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

@@ -0,0 +1,66 @@
+/**
+ * Logger Port
+ *
+ * Abstract interface for logging progress and messages.
+ * This allows the domain and application layers to remain independent
+ * of the actual logging implementation (console, file, etc.).
+ */
+/**
+ * Progress information for long-running operations
+ */
+export interface ProgressInfo {
+    /** Current item being processed */
+    current: number;
+    /** Total number of items */
+    total: number;
+    /** Optional descriptive message */
+    message?: string;
+}
+/**
+ * Abstract logger interface.
+ *
+ * Implementations might:
+ * - Log to console (ConsoleLogger)
+ * - Log to console with inline replacement for progress (InlineProgressLogger)
+ * - Be silent (SilentLogger)
+ * - Log to a file or external service
+ */
+export interface Logger {
+    /**
+     * Log an info message (general progress updates)
+     */
+    info(message: string): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string): void;
+    /**
+     * Log an error message
+     */
+    error(message: string): void;
+    /**
+     * Log a debug message (only shown in verbose mode)
+     */
+    debug(message: string): void;
+    /**
+     * Log a progress update that can replace the current line.
+     * Used for download progress, file processing counters, etc.
+     *
+     * In terminal environments, this may overwrite the current line.
+     * In non-terminal environments (SDK), this may just log normally.
+     *
+     * @param message - Progress message to display
+     */
+    progress(message: string): void;
+    /**
+     * Clear any inline progress output.
+     * Call this before switching from progress() to info/warn/error.
+     */
+    clearProgress(): void;
+}
+/**
+ * Factory function type for creating loggers
+ */
+export type LoggerFactory = (options?: {
+    verbose?: boolean;
+}) => Logger;

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

@@ -0,0 +1,66 @@
+/**
+ * Text Chunking Service
+ *
+ * Provides generic text chunking strategies for indexing.
+ * These are language-agnostic and work with any text content.
+ */
+import type { ChunkType } from "../entities";
+/**
+ * Represents a chunk of text with location information.
+ */
+export interface TextChunk {
+    /** The text content */
+    content: string;
+    /** 1-based start line number */
+    startLine: number;
+    /** 1-based end line number */
+    endLine: number;
+    /** The type of chunk */
+    type: ChunkType;
+    /** Optional name for the chunk */
+    name?: string;
+}
+/**
+ * Options for line-based chunking.
+ */
+export interface ChunkingOptions {
+    /** Lines per chunk (default: 30) */
+    chunkSize?: number;
+    /** Overlap between chunks (default: 5) */
+    overlap?: number;
+    /** Minimum lines to create multiple chunks (default: chunkSize) */
+    minLinesForMultipleChunks?: number;
+}
+/** Default lines per chunk */
+export declare const DEFAULT_CHUNK_SIZE = 30;
+/** Default overlap between chunks */
+export declare const DEFAULT_OVERLAP = 5;
+/**
+ * Split text into overlapping chunks based on line boundaries.
+ *
+ * This is a generic chunking strategy that works with any text content.
+ * It creates overlapping chunks to ensure context is preserved across
+ * chunk boundaries.
+ *
+ * @param content - The text content to chunk
+ * @param options - Chunking options
+ * @returns Array of text chunks
+ */
+export declare function createLineBasedChunks(content: string, options?: ChunkingOptions): TextChunk[];
+/**
+ * Create a single chunk from entire content.
+ * Useful for small files or when chunking isn't needed.
+ *
+ * @param content - The text content
+ * @returns A single file chunk
+ */
+export declare function createSingleChunk(content: string): TextChunk;
+/**
+ * Generate a unique chunk ID from filepath and line numbers.
+ *
+ * @param filepath - The source file path
+ * @param startLine - Start line number
+ * @param endLine - End line number
+ * @returns Unique chunk identifier
+ */
+export declare function generateChunkId(filepath: string, startLine: number, endLine: number): string;

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

@@ -7,3 +7,5 @@
 export { BM25Index, tokenize, normalizeScore, type BM25Document, type BM25Result, type BM25SerializedData, } from "./bm25";
 export { extractKeywords, extractPathKeywords, parsePathContext, formatPathContextForEmbedding, COMMON_KEYWORDS, type PathContext, } from "./keywords";
 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";

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

@@ -0,0 +1,55 @@
+/**
+ * Query Intent Detection Service
+ *
+ * Detects whether a search query is looking for implementation code
+ * or documentation, and calculates appropriate boosts.
+ */
+/** Implementation-related query terms that boost source code files */
+export declare const IMPLEMENTATION_TERMS: string[];
+/** Documentation-related query terms that boost documentation files */
+export declare const DOCUMENTATION_TERMS: string[];
+/** Source code file extensions */
+export declare const SOURCE_CODE_EXTENSIONS: string[];
+/** Documentation file extensions */
+export declare const DOC_EXTENSIONS: string[];
+/** Data/config file extensions */
+export declare const DATA_EXTENSIONS: string[];
+/** Query intent types */
+export type QueryIntent = "implementation" | "documentation" | "neutral";
+/**
+ * Detect query intent based on terms.
+ * Returns: 'implementation' | 'documentation' | 'neutral'
+ *
+ * @param queryTerms - Array of query terms (lowercase)
+ * @returns The detected intent
+ */
+export declare function detectQueryIntent(queryTerms: string[]): QueryIntent;
+/**
+ * Extract query terms from a search query.
+ *
+ * @param query - The search query string
+ * @returns Array of lowercase terms (length > 2)
+ */
+export declare function extractQueryTerms(query: string): string[];
+/**
+ * Determine if a file is a source code file based on extension.
+ */
+export declare function isSourceCodeFile(filepath: string): boolean;
+/**
+ * Determine if a file is a documentation file based on extension.
+ */
+export declare function isDocFile(filepath: string): boolean;
+/**
+ * Determine if a file is a data/config file based on extension.
+ */
+export declare function isDataFile(filepath: string): boolean;
+/**
+ * Calculate boost based on file type and query context.
+ * Bidirectional: boosts code for implementation queries, docs for documentation queries.
+ * Only applies when query intent is clear.
+ *
+ * @param filepath - The file path
+ * @param queryTerms - Array of query terms (lowercase)
+ * @returns Boost value (0 to ~0.1)
+ */
+export declare function calculateFileTypeBoost(filepath: string, queryTerms: string[]): number;

package/dist/index.d.ts

@@ -7,25 +7,42 @@
  * ```ts
  * import raggrep from 'raggrep';
  *
- * // Index a directory
+ * // Index a directory (automatically cleans up deleted files)
  * await raggrep.index('/path/to/project');
  *
  * // Search the index
  * const results = await raggrep.search('/path/to/project', 'user authentication');
  *
- * // Clean up stale entries
- * await raggrep.cleanup('/path/to/project');
+ * // Reset (clear) the index completely
+ * await raggrep.reset('/path/to/project');
+ * ```
+ *
+ * @example With custom logger
+ * ```ts
+ * import raggrep, { createLogger, createInlineLogger } from 'raggrep';
+ *
+ * // Create a logger (defaults to console)
+ * const logger = createLogger({ verbose: true });
+ *
+ * // Or use inline logger for CLI-style progress
+ * const inlineLogger = createInlineLogger({ verbose: false });
+ *
+ * await raggrep.index('/path/to/project', { logger: inlineLogger });
  * ```
  */
-import type { IndexResult, IndexOptions, CleanupResult } from "./app/indexer";
+import type { IndexResult, IndexOptions, CleanupResult, CleanupOptions, ResetResult } from "./app/indexer";
 import { formatSearchResults } from "./app/search";
 import type { SearchOptions, SearchResult } from "./types";
-export type { IndexResult, IndexOptions, CleanupResult } from "./app/indexer";
+import { ConsoleLogger, InlineProgressLogger, SilentLogger, createLogger, createInlineLogger, createSilentLogger } from "./infrastructure/logger";
+export type { IndexResult, IndexOptions, CleanupResult, CleanupOptions, ResetResult, } from "./app/indexer";
 export type { SearchOptions, SearchResult, Chunk, FileIndex } from "./types";
+export type { Logger, LoggerFactory } from "./domain/ports";
+export { ConsoleLogger, InlineProgressLogger, SilentLogger, createLogger, createInlineLogger, createSilentLogger, };
 /**
  * Index a directory for semantic search.
  *
  * Creates a `.raggrep/` folder with the index data.
+ * Automatically cleans up stale entries for deleted files.
  *
  * @param directory - Path to the directory to index
  * @param options - Index options
@@ -69,6 +86,9 @@ export declare function search(directory: string, query: string, options?: Searc
 /**
  * Clean up stale index entries for files that no longer exist.
  *
+ * Note: Cleanup is now automatic during indexing. This function is provided
+ * for explicit cleanup without re-indexing.
+ *
  * @param directory - Path to the indexed directory
  * @param options - Cleanup options
  * @returns Array of cleanup results per module
@@ -79,9 +99,25 @@ export declare function search(directory: string, query: string, options?: Searc
  * console.log(`Removed ${results[0].removed} stale entries`);
  * ```
  */
-export declare function cleanup(directory: string, options?: {
-    verbose?: boolean;
-}): Promise<CleanupResult[]>;
+export declare function cleanup(directory: string, options?: CleanupOptions): Promise<CleanupResult[]>;
+/**
+ * Reset (completely clear) the index for a directory.
+ *
+ * @param directory - Path to the indexed directory
+ * @returns Result with success status and removed index path
+ * @throws Error if no index exists for the directory
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const result = await raggrep.reset('./my-project');
+ *   console.log(`Cleared index at: ${result.indexDir}`);
+ * } catch (error) {
+ *   console.error('No index found');
+ * }
+ * ```
+ */
+export declare function reset(directory: string): Promise<ResetResult>;
 /**
  * Format search results for display.
  *
@@ -93,6 +129,7 @@ declare const raggrep: {
     index: typeof index;
     search: typeof search;
     cleanup: typeof cleanup;
+    reset: typeof reset;
     formatSearchResults: typeof formatSearchResults;
 };
 export default raggrep;