/**
 * FTS Engine Factory - Auto-Detection and Selection
 *
 * This module provides automatic selection of the best FTS engine based on:
 * - User preference (auto, js, native)
 * - Codebase size (file count)
 * - Native module availability
 *
 * The factory implements the dual-engine architecture from the Hybrid Search RFC,
 * ensuring zero-configuration for most users while providing power user control.
 *
 * Selection Logic:
 * - 'js' preference: Always use NaturalBM25Engine
 * - 'native' preference: Use SQLiteFTS5Engine if available, fallback to JS
 * - 'auto' preference:
 *   - If fileCount > 5000 AND native available: Use native
 *   - Otherwise: Use JS
 */
import { FTSEngine, FTSEngineType } from './ftsEngine.js';
export type { FTSEnginePreference } from '../storage/config.js';
import type { FTSEnginePreference } from '../storage/config.js';
/**
 * File count threshold for auto-detection.
 *
 * When using 'auto' preference:
 * - Projects with > FILE_COUNT_THRESHOLD files will prefer native engine
 * - Projects with <= FILE_COUNT_THRESHOLD files will use JS engine
 *
 * Rationale: The JS engine performs well for small-medium codebases (<5000 files)
 * but memory usage and search latency become problematic for larger projects.
 * The native SQLite FTS5 engine uses disk-backed storage and handles large
 * codebases more efficiently.
 */
export declare const FILE_COUNT_THRESHOLD = 5000;
/**
 * Result of engine selection including the engine instance, type, and reason.
 */
export interface EngineSelectionResult {
    /** The created FTS engine instance */
    engine: FTSEngine;
    /** The type of engine that was selected */
    type: FTSEngineType;
    /** Human-readable reason for the selection */
    reason: string;
}
/**
 * Create the appropriate FTS engine based on preference and environment.
 *
 * This is the main entry point for creating FTS engines. It handles:
 * - User preference override (js/native)
 * - Auto-detection based on file count and native availability
 * - Graceful fallback from native to JS when native is unavailable
 *
 * @param dbPath - Path to the database directory (used for native engine)
 * @param preference - User's engine preference: 'auto', 'js', or 'native'
 * @param fileCount - Number of files in the codebase (for auto-detection)
 * @returns Promise resolving to engine instance, type, and selection reason
 *
 * @example
 * ```typescript
 * // Auto-detect based on project size
 * const { engine, type, reason } = await createFTSEngine(
 *   indexPath,
 *   'auto',
 *   1500
 * );
 * console.log(`Using ${type} engine: ${reason}`);
 *
 * // Force JS engine
 * const { engine } = await createFTSEngine(indexPath, 'js', 10000);
 *
 * // Force native engine (with fallback)
 * const { engine, reason } = await createFTSEngine(indexPath, 'native', 100);
 * if (reason.includes('fell back')) {
 *   console.log('Native unavailable, using JS fallback');
 * }
 * ```
 */
export declare function createFTSEngine(dbPath: string, preference: FTSEnginePreference, fileCount: number): Promise<EngineSelectionResult>;
/**
 * Check if the native FTS engine is available in the current environment.
 *
 * This is a convenience re-export of isNativeAvailable from sqliteFTS5.
 * Use this to check availability before making decisions that depend on
 * the native engine being present.
 *
 * @returns Promise resolving to true if native engine is available
 *
 * @example
 * ```typescript
 * const canUseNative = await checkNativeAvailable();
 * if (canUseNative) {
 *   console.log('Native SQLite FTS5 engine is available');
 * } else {
 *   console.log('Falling back to JavaScript engine');
 * }
 * ```
 */
export declare function checkNativeAvailable(): Promise<boolean>;
/**
 * Get a human-readable description of why a particular engine was selected.
 *
 * This is useful for displaying to users in status output or logs.
 *
 * @param type - The engine type that was selected
 * @param reason - The raw reason string from selection
 * @returns Formatted description for user display
 */
export declare function formatEngineSelectionReason(type: FTSEngineType, reason: string): string;
/**
 * Determine if the given file count would trigger native engine selection in auto mode.
 *
 * Useful for predicting which engine will be selected before actually creating it.
 *
 * @param fileCount - Number of files in the codebase
 * @returns true if file count exceeds the threshold for native engine selection
 */
export declare function wouldSelectNative(fileCount: number): boolean;
/**
 * Load an existing FTS engine based on the type stored in metadata.
 *
 * This function creates an FTS engine instance but does NOT load its index data.
 * The caller should call `engine.load(path)` to load the persisted index.
 *
 * @param indexPath - Path to the index directory
 * @param engineType - The engine type ('js' or 'native')
 * @returns FTS engine instance ready for loading, or null if type is unknown
 *
 * @example
 * ```typescript
 * const engine = await loadFTSEngine(indexPath, 'js');
 * if (engine) {
 *   await engine.load(ftsIndexPath);
 *   const results = await engine.search('query', 10);
 * }
 * ```
 */
export declare function loadFTSEngine(indexPath: string, engineType: FTSEngineType | string): Promise<FTSEngine | null>;
//# sourceMappingURL=ftsEngineFactory.d.ts.map