@ff-labs/fff-node 0.1.0-nightly.5809316

package/dist/src/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * fff - Fast File Finder
+ *
+ * High-performance fuzzy file finder for Node.js, powered by Rust.
+ * Perfect for LLM agent tools that need to search through codebases.
+ *
+ * Each `FileFinder` instance is backed by an independent native file picker.
+ * Create as many as you need and destroy them when done.
+ *
+ * Uses ffi-rs to load the same native libfff_c binary used by @ff-labs/fff-bun.
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "@ff-labs/fff-node";
+ *
+ * // Create a file finder instance
+ * const result = FileFinder.create({ basePath: "/path/to/project" });
+ * if (!result.ok) {
+ *   console.error(result.error);
+ *   process.exit(1);
+ * }
+ * const finder = result.value;
+ *
+ * // Wait for initial scan
+ * finder.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = finder.fileSearch("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Cleanup when done
+ * finder.destroy();
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { binaryExists, findBinary, } from "./binary.js";
+export { closeLibrary } from "./ffi.js";
+export { FileFinder } from "./finder.js";
+export { getLibExtension, getLibFilename, getNpmPackageName, getTriple, } from "./platform.js";
+export type { DbHealth, FileItem, GrepCursor, GrepMatch, GrepMode, GrepOptions, GrepResult, HealthCheck, InitOptions, Location, MultiGrepOptions, Result, ScanProgress, Score, SearchOptions, SearchResult, } from "./types.js";
+export { err, ok } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,47 @@
+/**
+ * fff - Fast File Finder
+ *
+ * High-performance fuzzy file finder for Node.js, powered by Rust.
+ * Perfect for LLM agent tools that need to search through codebases.
+ *
+ * Each `FileFinder` instance is backed by an independent native file picker.
+ * Create as many as you need and destroy them when done.
+ *
+ * Uses ffi-rs to load the same native libfff_c binary used by @ff-labs/fff-bun.
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "@ff-labs/fff-node";
+ *
+ * // Create a file finder instance
+ * const result = FileFinder.create({ basePath: "/path/to/project" });
+ * if (!result.ok) {
+ *   console.error(result.error);
+ *   process.exit(1);
+ * }
+ * const finder = result.value;
+ *
+ * // Wait for initial scan
+ * finder.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = finder.fileSearch("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Cleanup when done
+ * finder.destroy();
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { binaryExists, findBinary, } from "./binary.js";
+export { closeLibrary } from "./ffi.js";
+export { FileFinder } from "./finder.js";
+export { getLibExtension, getLibFilename, getNpmPackageName, getTriple, } from "./platform.js";
+// Result helpers
+export { err, ok } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,SAAS,GACV,MAAM,eAAe,CAAC;AAoBvB,iBAAiB;AACjB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/platform.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Platform detection utilities for downloading the correct binary
+ */
+/**
+ * Get the platform triple (e.g., "x86_64-unknown-linux-gnu")
+ */
+export declare function getTriple(): string;
+/**
+ * Get the library file extension for the current platform
+ */
+export declare function getLibExtension(): "dylib" | "so" | "dll";
+/**
+ * Get the library filename prefix (empty on Windows)
+ */
+export declare function getLibPrefix(): string;
+/**
+ * Get the full library filename for the current platform
+ */
+export declare function getLibFilename(): string;
+/**
+ * Get the npm package name for the current platform's native binary.
+ *
+ * @returns Package name like "@ff-labs/fff-bin-darwin-arm64"
+ * @throws If the current platform is not supported
+ */
+export declare function getNpmPackageName(): string;
+//# sourceMappingURL=platform.d.ts.map

package/dist/src/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/platform.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAiBlC;AAqCD;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,GAAG,IAAI,GAAG,KAAK,CASxD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAkBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C"}

package/dist/src/platform.js

@@ -0,0 +1,117 @@
+/**
+ * Platform detection utilities for downloading the correct binary
+ */
+import { execSync } from "node:child_process";
+/**
+ * Get the platform triple (e.g., "x86_64-unknown-linux-gnu")
+ */
+export function getTriple() {
+    const platform = process.platform;
+    const arch = process.arch;
+    let osName;
+    if (platform === "darwin") {
+        osName = "apple-darwin";
+    }
+    else if (platform === "linux") {
+        osName = detectLinuxLibc();
+    }
+    else if (platform === "win32") {
+        osName = "pc-windows-msvc";
+    }
+    else {
+        throw new Error(`Unsupported platform: ${platform}`);
+    }
+    const archName = normalizeArch(arch);
+    return `${archName}-${osName}`;
+}
+/**
+ * Detect whether we're on musl or glibc Linux
+ */
+function detectLinuxLibc() {
+    try {
+        const lddOutput = execSync("ldd --version 2>&1", {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (lddOutput.toLowerCase().includes("musl")) {
+            return "unknown-linux-musl";
+        }
+    }
+    catch {
+        // ldd failed, assume glibc
+    }
+    return "unknown-linux-gnu";
+}
+/**
+ * Normalize architecture name to Rust target format
+ */
+function normalizeArch(arch) {
+    switch (arch) {
+        case "x64":
+        case "amd64":
+            return "x86_64";
+        case "arm64":
+            return "aarch64";
+        case "arm":
+            return "arm";
+        default:
+            throw new Error(`Unsupported architecture: ${arch}`);
+    }
+}
+/**
+ * Get the library file extension for the current platform
+ */
+export function getLibExtension() {
+    switch (process.platform) {
+        case "darwin":
+            return "dylib";
+        case "win32":
+            return "dll";
+        default:
+            return "so";
+    }
+}
+/**
+ * Get the library filename prefix (empty on Windows)
+ */
+export function getLibPrefix() {
+    return process.platform === "win32" ? "" : "lib";
+}
+/**
+ * Get the full library filename for the current platform
+ */
+export function getLibFilename() {
+    const prefix = getLibPrefix();
+    const ext = getLibExtension();
+    return `${prefix}fff_c.${ext}`;
+}
+/**
+ * Map from Rust target triple to npm platform package name.
+ * The @ff-labs/fff-bin-* packages contain the pre-built libfff_c
+ * shared library and are runtime-agnostic (used by both Bun and Node).
+ */
+const TRIPLE_TO_NPM_PACKAGE = {
+    "aarch64-apple-darwin": "@ff-labs/fff-bin-darwin-arm64",
+    "x86_64-apple-darwin": "@ff-labs/fff-bin-darwin-x64",
+    "x86_64-unknown-linux-gnu": "@ff-labs/fff-bin-linux-x64-gnu",
+    "aarch64-unknown-linux-gnu": "@ff-labs/fff-bin-linux-arm64-gnu",
+    "x86_64-unknown-linux-musl": "@ff-labs/fff-bin-linux-x64-musl",
+    "aarch64-unknown-linux-musl": "@ff-labs/fff-bin-linux-arm64-musl",
+    "x86_64-pc-windows-msvc": "@ff-labs/fff-bin-win32-x64",
+    "aarch64-pc-windows-msvc": "@ff-labs/fff-bin-win32-arm64",
+};
+/**
+ * Get the npm package name for the current platform's native binary.
+ *
+ * @returns Package name like "@ff-labs/fff-bin-darwin-arm64"
+ * @throws If the current platform is not supported
+ */
+export function getNpmPackageName() {
+    const triple = getTriple();
+    const packageName = TRIPLE_TO_NPM_PACKAGE[triple];
+    if (!packageName) {
+        throw new Error(`No npm package available for platform: ${triple}`);
+    }
+    return packageName;
+}
+//# sourceMappingURL=platform.js.map

package/dist/src/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/platform.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -0,0 +1,430 @@
+/**
+ * Result type for all operations - follows the Result pattern
+ */
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Helper to create a successful result
+ */
+export declare function ok<T>(value: T): Result<T>;
+/**
+ * Helper to create an error result
+ */
+export declare function err<T>(error: string): Result<T>;
+/**
+ * Initialization options for the file finder
+ */
+export interface InitOptions {
+    /** Base directory to index (required) */
+    basePath: string;
+    /** Path to frecency database (optional, omit to skip frecency initialization) */
+    frecencyDbPath?: string;
+    /** Path to query history database (optional, omit to skip query tracker initialization) */
+    historyDbPath?: string;
+    /** Use unsafe no-lock mode for databases (optional, defaults to false) */
+    useUnsafeNoLock?: boolean;
+    /**
+     * Pre-populate mmap caches for all files after the initial scan completes.
+     * When enabled, the first grep search will be as fast as subsequent ones
+     * at the cost of a longer scan time and higher initial memory usage.
+     * (default: false)
+     */
+    warmupMmapCache?: boolean;
+    /** enables optimizations for AI agent assistants. Provide as true if running via mcp/agent */
+    aiMode?: boolean;
+}
+/**
+ * Search options for fuzzy file search
+ */
+export interface SearchOptions {
+    /** Maximum threads for parallel search (0 = auto) */
+    maxThreads?: number;
+    /** Current file path (for deprioritization in results) */
+    currentFile?: string;
+    /** Combo boost score multiplier (default: 100) */
+    comboBoostMultiplier?: number;
+    /** Minimum combo count for boost (default: 3) */
+    minComboCount?: number;
+    /** Page index for pagination (default: 0) */
+    pageIndex?: number;
+    /** Page size for pagination (default: 100) */
+    pageSize?: number;
+}
+/**
+ * A file item in search results
+ */
+export interface FileItem {
+    /** Absolute path to the file */
+    path: string;
+    /** Path relative to the indexed directory */
+    relativePath: string;
+    /** File name only */
+    fileName: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp (Unix seconds) */
+    modified: number;
+    /** Frecency score based on access patterns */
+    accessFrecencyScore: number;
+    /** Frecency score based on modification time */
+    modificationFrecencyScore: number;
+    /** Combined frecency score */
+    totalFrecencyScore: number;
+    /** Git status: 'clean', 'modified', 'untracked', 'staged_new', etc. */
+    gitStatus: string;
+}
+/**
+ * Score breakdown for a search result
+ */
+export interface Score {
+    /** Total combined score */
+    total: number;
+    /** Base fuzzy match score */
+    baseScore: number;
+    /** Bonus for filename match */
+    filenameBonus: number;
+    /** Bonus for special filenames (index.ts, main.rs, etc.) */
+    specialFilenameBonus: number;
+    /** Boost from frecency */
+    frecencyBoost: number;
+    /** Penalty for distance in path */
+    distancePenalty: number;
+    /** Penalty if this is the current file */
+    currentFilePenalty: number;
+    /** Boost from query history combo matching */
+    comboMatchBoost: number;
+    /** Whether this was an exact match */
+    exactMatch: boolean;
+    /** Type of match: 'fuzzy', 'exact', 'prefix', etc. */
+    matchType: string;
+}
+/**
+ * Location in file (from query like "file.ts:42")
+ */
+export type Location = {
+    type: "line";
+    line: number;
+} | {
+    type: "position";
+    line: number;
+    col: number;
+} | {
+    type: "range";
+    start: {
+        line: number;
+        col: number;
+    };
+    end: {
+        line: number;
+        col: number;
+    };
+};
+/**
+ * Search result from fuzzy file search
+ */
+export interface SearchResult {
+    /** Matched file items */
+    items: FileItem[];
+    /** Corresponding scores for each item */
+    scores: Score[];
+    /** Total number of files that matched */
+    totalMatched: number;
+    /** Total number of indexed files */
+    totalFiles: number;
+    /** Location parsed from query (e.g., "file.ts:42:10") */
+    location?: Location;
+}
+/**
+ * Scan progress information
+ */
+export interface ScanProgress {
+    /** Number of files scanned so far */
+    scannedFilesCount: number;
+    /** Whether a scan is currently in progress */
+    isScanning: boolean;
+}
+/**
+ * Database health information
+ */
+export interface DbHealth {
+    /** Path to the database */
+    path: string;
+    /** Size of the database on disk in bytes */
+    diskSize: number;
+}
+/**
+ * Health check result
+ */
+export interface HealthCheck {
+    /** Library version */
+    version: string;
+    /** Git integration status */
+    git: {
+        /** Whether git2 library is available */
+        available: boolean;
+        /** Whether a git repository was found */
+        repositoryFound: boolean;
+        /** Git working directory path */
+        workdir?: string;
+        /** libgit2 version string */
+        libgit2Version: string;
+        /** Error message if git detection failed */
+        error?: string;
+    };
+    /** File picker status */
+    filePicker: {
+        /** Whether the file picker is initialized */
+        initialized: boolean;
+        /** Base path being indexed */
+        basePath?: string;
+        /** Whether a scan is in progress */
+        isScanning?: boolean;
+        /** Number of indexed files */
+        indexedFiles?: number;
+        /** Error message if there's an issue */
+        error?: string;
+    };
+    /** Frecency database status */
+    frecency: {
+        /** Whether frecency tracking is initialized */
+        initialized: boolean;
+        /** Database health information */
+        dbHealthcheck?: DbHealth;
+        /** Error message if there's an issue */
+        error?: string;
+    };
+    /** Query tracker status */
+    queryTracker: {
+        /** Whether query tracking is initialized */
+        initialized: boolean;
+        /** Database health information */
+        dbHealthcheck?: DbHealth;
+        /** Error message if there's an issue */
+        error?: string;
+    };
+}
+/**
+ * Internal: Options format sent to Rust FFI
+ * @internal
+ */
+export interface InitOptionsInternal {
+    base_path: string;
+    frecency_db_path?: string;
+    history_db_path?: string;
+    use_unsafe_no_lock: boolean;
+    warmup_mmap_cache: boolean;
+    ai_mode: boolean;
+}
+/**
+ * Internal: Search options format sent to Rust FFI
+ * @internal
+ */
+export interface SearchOptionsInternal {
+    max_threads?: number;
+    current_file?: string;
+    combo_boost_multiplier?: number;
+    min_combo_count?: number;
+    page_index?: number;
+    page_size?: number;
+}
+/**
+ * Convert public InitOptions to internal format
+ * @internal
+ */
+export declare function toInternalInitOptions(opts: InitOptions): InitOptionsInternal;
+/**
+ * Convert public SearchOptions to internal format
+ * @internal
+ */
+export declare function toInternalSearchOptions(opts?: SearchOptions): SearchOptionsInternal;
+/**
+ * Grep search mode
+ */
+export type GrepMode = "plain" | "regex" | "fuzzy";
+/**
+ * Opaque pagination cursor for grep results.
+ * Pass this to `GrepOptions.cursor` to fetch the next page.
+ * Do not construct or modify this — use the `nextCursor` from a previous `GrepResult`.
+ */
+export interface GrepCursor {
+    /** @internal */
+    readonly __brand: "GrepCursor";
+    /** @internal */
+    readonly _offset: number;
+}
+/**
+ * @internal Create a GrepCursor from a raw file offset.
+ */
+export declare function createGrepCursor(offset: number): GrepCursor;
+/**
+ * Options for live grep (content search)
+ *
+ * Files are searched sequentially in frecency order (most recently/frequently
+ * accessed first). The engine returns a `nextCursor` for fetching the next page.
+ */
+export interface GrepOptions {
+    /** Maximum file size to search in bytes. Files larger than this are skipped. (default: 10MB) */
+    maxFileSize?: number;
+    /** Maximum matching lines to collect from a single file (default: 200) */
+    maxMatchesPerFile?: number;
+    /** Smart case: case-insensitive when the query is all lowercase, case-sensitive otherwise (default: true) */
+    smartCase?: boolean;
+    /**
+     * Pagination cursor from a previous `GrepResult.nextCursor`.
+     * Omit (or pass `null`) for the first page.
+     */
+    cursor?: GrepCursor | null;
+    /** Search mode (default: "plain") */
+    mode?: GrepMode;
+    /**
+     * Maximum wall-clock time in milliseconds to spend searching before returning
+     * partial results. 0 = unlimited. (default: 0)
+     */
+    timeBudgetMs?: number;
+    /** Number of context lines to include before each match (default: 0) */
+    beforeContext?: number;
+    /** Number of context lines to include after each match (default: 0) */
+    afterContext?: number;
+}
+/**
+ * A single grep match with file and line information
+ */
+export interface GrepMatch {
+    /** Absolute path to the file */
+    path: string;
+    /** Path relative to the indexed directory */
+    relativePath: string;
+    /** File name only */
+    fileName: string;
+    /** Git status */
+    gitStatus: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp (Unix seconds) */
+    modified: number;
+    /** Whether the file is binary */
+    isBinary: boolean;
+    /** Combined frecency score */
+    totalFrecencyScore: number;
+    /** Access-based frecency score */
+    accessFrecencyScore: number;
+    /** Modification-based frecency score */
+    modificationFrecencyScore: number;
+    /** 1-based line number of the match */
+    lineNumber: number;
+    /** 0-based byte column of first match start */
+    col: number;
+    /** Absolute byte offset of the matched line from file start */
+    byteOffset: number;
+    /** The matched line text (may be truncated) */
+    lineContent: string;
+    /** Byte offset pairs [start, end] within lineContent for highlighting */
+    matchRanges: [number, number][];
+    /** Fuzzy match score (only in fuzzy mode) */
+    fuzzyScore?: number;
+    /** Lines before the match (context). Empty array when context is 0. */
+    contextBefore?: string[];
+    /** Lines after the match (context). Empty array when context is 0. */
+    contextAfter?: string[];
+}
+/**
+ * Result from a grep search
+ */
+export interface GrepResult {
+    /** Matched items with file and line information. At most `max_matches_per_file`. */
+    items: GrepMatch[];
+    /** Total number of matches collected (always equal to items.length). */
+    totalMatched: number;
+    /** Number of files actually opened and searched in this call */
+    totalFilesSearched: number;
+    /** Total number of indexed files (before any filtering) */
+    totalFiles: number;
+    /** Number of files eligible for search after filtering out binary files, oversized files, and constraint mismatches */
+    filteredFileCount: number;
+    /**
+     * Cursor for the next page, or `null` if all eligible files have been searched.
+     * Pass this as `GrepOptions.cursor` to continue from where this call left off.
+     */
+    nextCursor: GrepCursor | null;
+    /** When regex mode fails to compile the pattern, the engine falls back to literal matching and this field contains the compilation error */
+    regexFallbackError?: string;
+}
+/**
+ * Options for multi-pattern grep (Aho-Corasick multi-needle search)
+ *
+ * Searches for lines matching ANY of the provided patterns using
+ * SIMD-accelerated Aho-Corasick multi-pattern matching.
+ */
+export interface MultiGrepOptions {
+    /** Patterns to search for (OR logic — matches lines containing any pattern) */
+    patterns: string[];
+    /** File constraints like "*.rs" or "/src/" */
+    constraints?: string;
+    /** Maximum file size to search in bytes (default: 10MB) */
+    maxFileSize?: number;
+    /** Maximum matching lines to collect from a single file (default: 0 = unlimited) */
+    maxMatchesPerFile?: number;
+    /** Smart case: case-insensitive when all patterns are lowercase (default: true) */
+    smartCase?: boolean;
+    /**
+     * Pagination cursor from a previous `GrepResult.nextCursor`.
+     * Omit (or pass `null`) for the first page.
+     */
+    cursor?: GrepCursor | null;
+    /**
+     * Maximum wall-clock time in milliseconds to spend searching before returning
+     * partial results. 0 = unlimited. (default: 0)
+     */
+    timeBudgetMs?: number;
+    /** Number of context lines to include before each match (default: 0) */
+    beforeContext?: number;
+    /** Number of context lines to include after each match (default: 0) */
+    afterContext?: number;
+}
+/**
+ * Internal: Multi-grep options format sent to Rust FFI
+ * @internal
+ */
+export interface MultiGrepOptionsInternal {
+    patterns: string[];
+    constraints?: string;
+    max_file_size?: number;
+    max_matches_per_file?: number;
+    smart_case?: boolean;
+    file_offset?: number;
+    page_limit?: number;
+    time_budget_ms?: number;
+    before_context?: number;
+    after_context?: number;
+}
+/**
+ * Convert public MultiGrepOptions to internal format
+ * @internal
+ */
+export declare function toInternalMultiGrepOptions(opts: MultiGrepOptions, pageLimit?: number): MultiGrepOptionsInternal;
+/**
+ * Internal: Grep options format sent to Rust FFI
+ * @internal
+ */
+export interface GrepOptionsInternal {
+    max_file_size?: number;
+    max_matches_per_file?: number;
+    smart_case?: boolean;
+    file_offset?: number;
+    page_limit?: number;
+    mode?: string;
+    time_budget_ms?: number;
+    before_context?: number;
+    after_context?: number;
+}
+/**
+ * Convert public GrepOptions to internal format
+ * @internal
+ */
+export declare function toInternalGrepOptions(opts?: GrepOptions, pageLimit?: number): GrepOptionsInternal;
+//# sourceMappingURL=types.d.ts.map