@ff-labs/fff-bun 0.1.0-nightly.044314f

package/src/finder.ts

@@ -0,0 +1,380 @@
+/**
+ * FileFinder - High-level API for the fff file finder
+ *
+ * This class provides a type-safe, ergonomic API for file finding operations.
+ * All methods return Result types for explicit error handling.
+ */
+
+import {
+  ffiInit,
+  ffiDestroy,
+  ffiSearch,
+  ffiLiveGrep,
+  ffiScanFiles,
+  ffiIsScanning,
+  ffiGetScanProgress,
+  ffiWaitForScan,
+  ffiRestartIndex,
+  ffiTrackAccess,
+  ffiRefreshGitStatus,
+  ffiTrackQuery,
+  ffiGetHistoricalQuery,
+  ffiHealthCheck,
+  ensureLoaded,
+  isAvailable,
+} from "./ffi";
+
+import type {
+  Result,
+  InitOptions,
+  SearchOptions,
+  SearchResult,
+  ScanProgress,
+  HealthCheck,
+  GrepOptions,
+  GrepResult,
+} from "./types";
+
+import { err, toInternalInitOptions, toInternalSearchOptions, toInternalGrepOptions, createGrepCursor } from "./types";
+
+/**
+ * FileFinder - Fast file finder with fuzzy search
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "fff";
+ *
+ * // Initialize
+ * const result = FileFinder.init({ basePath: "/path/to/project" });
+ * if (!result.ok) {
+ *   console.error(result.error);
+ *   process.exit(1);
+ * }
+ *
+ * // Wait for initial scan
+ * FileFinder.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = FileFinder.search("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Cleanup
+ * FileFinder.destroy();
+ * ```
+ */
+export class FileFinder {
+  private static initialized = false;
+
+  /**
+   * Initialize the file finder with the given options.
+   *
+   * @param options - Initialization options
+   * @returns Result indicating success or failure
+   *
+   * @example
+   * ```typescript
+   * // Basic initialization
+   * FileFinder.init({ basePath: "/path/to/project" });
+   *
+   * // With custom database paths
+   * FileFinder.init({
+   *   basePath: "/path/to/project",
+   *   frecencyDbPath: "/custom/frecency.mdb",
+   *   historyDbPath: "/custom/history.mdb",
+   * });
+   *
+   * // Minimal mode (no databases - just omit db paths)
+   * FileFinder.init({ basePath: "/path/to/project" });
+   * ```
+   */
+  static init(options: InitOptions): Result<void> {
+    const internalOpts = toInternalInitOptions(options);
+    const result = ffiInit(JSON.stringify(internalOpts));
+
+    if (result.ok) {
+      this.initialized = true;
+    }
+
+    return result;
+  }
+
+  /**
+   * Destroy and clean up all resources.
+   *
+   * Call this when you're done using the file finder to free memory
+   * and stop background file watching.
+   */
+  static destroy(): Result<void> {
+    const result = ffiDestroy();
+    if (result.ok) {
+      this.initialized = false;
+    }
+    return result;
+  }
+
+  /**
+   * Search for files matching the query.
+   *
+   * The query supports fuzzy matching and special syntax:
+   * - `foo bar` - Match files containing "foo" and "bar"
+   * - `src/` - Match files in src directory
+   * - `file.ts:42` - Match file.ts with line 42
+   * - `file.ts:42:10` - Match file.ts with line 42, column 10
+   *
+   * @param query - Search query string
+   * @param options - Search options
+   * @returns Search results with matched files and scores
+   *
+   * @example
+   * ```typescript
+   * const result = FileFinder.search("main.ts", { pageSize: 10 });
+   * if (result.ok) {
+   *   console.log(`Found ${result.value.totalMatched} files`);
+   *   for (const item of result.value.items) {
+   *     console.log(item.relativePath);
+   *   }
+   * }
+   * ```
+   */
+  static search(query: string, options?: SearchOptions): Result<SearchResult> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+
+    const internalOpts = toInternalSearchOptions(options);
+    const result = ffiSearch(query, JSON.stringify(internalOpts));
+
+    if (!result.ok) {
+      return result;
+    }
+
+    // The FFI returns the search result already parsed
+    return result as Result<SearchResult>;
+  }
+
+  /**
+   * Search file contents (live grep).
+   *
+   * Searches through the contents of indexed files using the specified mode:
+   * - `"plain"` (default): SIMD-accelerated literal text matching
+   * - `"regex"`: Regular expression matching
+   * - `"fuzzy"`: Smith-Waterman fuzzy matching per line
+   *
+   * Supports pagination for large result sets. The result includes a `nextCursor`
+   * that can be passed back to fetch the next page.
+   *
+   * The query also supports constraint syntax:
+   * - `*.ts pattern` - Only search in TypeScript files
+   * - `src/ pattern` - Only search in the src directory
+   *
+   * @param query - Search query string
+   * @param options - Grep options (mode, pagination, limits)
+   * @returns Grep results with matched lines and file metadata
+   *
+   * @example
+   * ```typescript
+   * // First page
+   * const result = FileFinder.liveGrep("TODO", { mode: "plain", pageLimit: 20 });
+   * if (result.ok) {
+   *   for (const match of result.value.items) {
+   *     console.log(`${match.relativePath}:${match.lineNumber}: ${match.lineContent}`);
+   *   }
+   *   // Fetch next page
+   *   if (result.value.nextCursor) {
+   *     const page2 = FileFinder.liveGrep("TODO", {
+   *       cursor: result.value.nextCursor,
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  static liveGrep(query: string, options?: GrepOptions): Result<GrepResult> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+
+    const internalOpts = toInternalGrepOptions(options);
+    const result = ffiLiveGrep(query, JSON.stringify(internalOpts));
+
+    if (!result.ok) {
+      return result;
+    }
+
+    // Transform the raw FFI result: replace nextFileOffset with an opaque cursor
+    const raw = result.value as Record<string, unknown>;
+    const nextFileOffset = raw.nextFileOffset as number;
+
+    const grepResult: GrepResult = {
+      items: raw.items as GrepResult["items"],
+      totalMatched: raw.totalMatched as number,
+      totalFilesSearched: raw.totalFilesSearched as number,
+      totalFiles: raw.totalFiles as number,
+      filteredFileCount: raw.filteredFileCount as number,
+      nextCursor: nextFileOffset > 0 ? createGrepCursor(nextFileOffset) : null,
+      regexFallbackError: raw.regexFallbackError as string | undefined,
+    };
+
+    return { ok: true, value: grepResult };
+  }
+
+  /**
+   * Trigger a rescan of the indexed directory.
+   *
+   * This is useful after major file system changes that the
+   * background watcher might have missed.
+   */
+  static scanFiles(): Result<void> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiScanFiles();
+  }
+
+  /**
+   * Check if a scan is currently in progress.
+   */
+  static isScanning(): boolean {
+    if (!this.initialized) return false;
+    return ffiIsScanning();
+  }
+
+  /**
+   * Get the current scan progress.
+   */
+  static getScanProgress(): Result<ScanProgress> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiGetScanProgress() as Result<ScanProgress>;
+  }
+
+  /**
+   * Wait for the initial file scan to complete.
+   *
+   * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+   * @returns true if scan completed, false if timed out
+   *
+   * @example
+   * ```typescript
+   * FileFinder.init({ basePath: "/path/to/project" });
+   * const completed = FileFinder.waitForScan(10000);
+   * if (!completed.ok || !completed.value) {
+   *   console.warn("Scan did not complete in time");
+   * }
+   * ```
+   */
+  static waitForScan(timeoutMs: number = 5000): Result<boolean> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiWaitForScan(timeoutMs);
+  }
+
+  /**
+   * Change the indexed directory to a new path.
+   *
+   * This stops the current file watcher and starts indexing the new directory.
+   *
+   * @param newPath - New directory path to index
+   */
+  static reindex(newPath: string): Result<void> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiRestartIndex(newPath);
+  }
+
+  /**
+   * Track file access for frecency scoring.
+   *
+   * Call this when a user opens a file to improve future search rankings.
+   *
+   * @param filePath - Absolute path to the accessed file
+   */
+  static trackAccess(filePath: string): Result<boolean> {
+    if (!this.initialized) {
+      return { ok: true, value: false };
+    }
+    return ffiTrackAccess(filePath);
+  }
+
+  /**
+   * Refresh the git status cache.
+   *
+   * @returns Number of files with updated git status
+   */
+  static refreshGitStatus(): Result<number> {
+    if (!this.initialized) {
+      return err("FileFinder not initialized. Call FileFinder.init() first.");
+    }
+    return ffiRefreshGitStatus();
+  }
+
+  /**
+   * Track query completion for smart suggestions.
+   *
+   * Call this when a user selects a file from search results.
+   * This helps improve future search rankings for similar queries.
+   *
+   * @param query - The search query that was used
+   * @param selectedFilePath - The file path that was selected
+   */
+  static trackQuery(query: string, selectedFilePath: string): Result<boolean> {
+    if (!this.initialized) {
+      return { ok: true, value: false };
+    }
+    return ffiTrackQuery(query, selectedFilePath);
+  }
+
+  /**
+   * Get a historical query by offset.
+   *
+   * @param offset - Offset from most recent (0 = most recent)
+   * @returns The historical query string, or null if not found
+   */
+  static getHistoricalQuery(offset: number): Result<string | null> {
+    if (!this.initialized) {
+      return { ok: true, value: null };
+    }
+    return ffiGetHistoricalQuery(offset);
+  }
+
+  /**
+   * Get health check information.
+   *
+   * Useful for debugging and verifying the file finder is working correctly.
+   *
+   * @param testPath - Optional path to test git repository detection
+   */
+  static healthCheck(testPath?: string): Result<HealthCheck> {
+    return ffiHealthCheck(testPath || "") as Result<HealthCheck>;
+  }
+
+  /**
+   * Check if the native library is available.
+   */
+  static isAvailable(): boolean {
+    return isAvailable();
+  }
+
+  /**
+   * Ensure the native library is loaded.
+   *
+   * This will download the binary if needed and load it.
+   * Useful for preloading before first use.
+   */
+  static async ensureLoaded(): Promise<void> {
+    return ensureLoaded();
+  }
+
+  /**
+   * Check if the file finder is initialized.
+   */
+  static isInitialized(): boolean {
+    return this.initialized;
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,230 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { FileFinder } from "./index";
+import { findBinary, getDevBinaryPath } from "./download";
+import { getTriple, getLibExtension, getLibFilename } from "./platform";
+
+const testDir = process.cwd();
+
+describe("Platform Detection", () => {
+  test("getTriple returns valid triple", () => {
+    const triple = getTriple();
+    expect(triple).toMatch(
+      /^(x86_64|aarch64|arm)-(apple-darwin|unknown-linux-(gnu|musl)|pc-windows-msvc)$/,
+    );
+  });
+
+  test("getLibExtension returns correct extension", () => {
+    const ext = getLibExtension();
+    const platform = process.platform;
+
+    if (platform === "darwin") {
+      expect(ext).toBe("dylib");
+    } else if (platform === "win32") {
+      expect(ext).toBe("dll");
+    } else {
+      expect(ext).toBe("so");
+    }
+  });
+
+  test("getLibFilename returns correct filename", () => {
+    const filename = getLibFilename();
+    const ext = getLibExtension();
+
+    if (process.platform === "win32") {
+      expect(filename).toBe(`fff_c.${ext}`);
+    } else {
+      expect(filename).toBe(`libfff_c.${ext}`);
+    }
+  });
+});
+
+describe("Binary Detection", () => {
+  test("getDevBinaryPath finds local build", () => {
+    const devPath = getDevBinaryPath();
+    expect(devPath).not.toBeNull();
+    expect(devPath).toContain("target/release");
+  });
+
+  test("findBinary returns a path", () => {
+    const path = findBinary();
+    expect(path).not.toBeNull();
+  });
+});
+
+describe("FileFinder - Health Check", () => {
+  test("healthCheck works before initialization", () => {
+    // Make sure we start fresh
+    FileFinder.destroy();
+
+    const result = FileFinder.healthCheck();
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.version).toBeDefined();
+      expect(result.value.git.available).toBe(true);
+      expect(result.value.filePicker.initialized).toBe(false);
+    }
+  });
+});
+
+describe("FileFinder - Full Lifecycle", () => {
+  // Single beforeAll/afterAll for the entire test suite to avoid repeated init/destroy
+  beforeAll(() => {
+    FileFinder.destroy(); // Clean any previous state
+  });
+
+  afterAll(() => {
+    FileFinder.destroy();
+  });
+
+  test("init succeeds with valid path", () => {
+    const result = FileFinder.init({
+      basePath: testDir,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(FileFinder.isInitialized()).toBe(true);
+  });
+
+  test("isScanning returns a boolean", () => {
+    const scanning = FileFinder.isScanning();
+    expect(typeof scanning).toBe("boolean");
+  });
+
+  test("getScanProgress returns valid data", () => {
+    const result = FileFinder.getScanProgress();
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(typeof result.value.scannedFilesCount).toBe("number");
+      expect(typeof result.value.isScanning).toBe("boolean");
+    }
+  });
+
+  test("waitForScan completes", () => {
+    // Small timeout - scan should be fast or already done
+    const result = FileFinder.waitForScan(500);
+    expect(result.ok).toBe(true);
+  });
+
+  test("search with empty query returns all files", () => {
+    const result = FileFinder.search("");
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      // Empty query should return files (frecency-sorted)
+      expect(result.value.totalFiles).toBeGreaterThan(0);
+    }
+  });
+
+  test("search returns a valid result structure", () => {
+    const result = FileFinder.search("Cargo.toml");
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(typeof result.value.totalMatched).toBe("number");
+      expect(typeof result.value.totalFiles).toBe("number");
+      expect(Array.isArray(result.value.items)).toBe(true);
+      expect(Array.isArray(result.value.scores)).toBe(true);
+    }
+  });
+
+  test("search returns empty for non-matching query", () => {
+    const result = FileFinder.search("xyznonexistentfilenamexyz123456");
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.totalMatched).toBe(0);
+      expect(result.value.items.length).toBe(0);
+    }
+  });
+
+  test("search respects pageSize option", () => {
+    const result = FileFinder.search("ts", { pageSize: 3 });
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.items.length).toBeLessThanOrEqual(3);
+    }
+  });
+
+  test("healthCheck shows initialized state", () => {
+    const result = FileFinder.healthCheck();
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.filePicker.initialized).toBe(true);
+      expect(result.value.filePicker.basePath).toBeDefined();
+      expect(typeof result.value.filePicker.indexedFiles).toBe("number");
+    }
+  });
+
+  test("healthCheck detects git repository", () => {
+    const result = FileFinder.healthCheck(testDir);
+    expect(result.ok).toBe(true);
+
+    if (result.ok) {
+      expect(result.value.git.available).toBe(true);
+      expect(typeof result.value.git.repositoryFound).toBe("boolean");
+    }
+  });
+
+  test("destroy and re-init works", () => {
+    FileFinder.destroy();
+    expect(FileFinder.isInitialized()).toBe(false);
+
+    const result = FileFinder.init({
+      basePath: testDir,
+    });
+    expect(result.ok).toBe(true);
+    expect(FileFinder.isInitialized()).toBe(true);
+  });
+});
+
+describe("FileFinder - Error Handling", () => {
+  test("search fails when not initialized", () => {
+    FileFinder.destroy();
+
+    const result = FileFinder.search("test");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("not initialized");
+    }
+  });
+
+  test("getScanProgress fails when not initialized", () => {
+    const result = FileFinder.getScanProgress();
+    expect(result.ok).toBe(false);
+  });
+
+  test("init fails with invalid path", () => {
+    const result = FileFinder.init({
+      basePath: "/nonexistent/path/that/does/not/exist",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("Failed");
+    }
+  });
+});
+
+describe("Result Type Helpers", () => {
+  test("ok helper creates success result", async () => {
+    const { ok } = await import("./types");
+    const result = ok(42);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(42);
+    }
+  });
+
+  test("err helper creates error result", async () => {
+    const { err } = await import("./types");
+    const result = err<number>("something went wrong");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBe("something went wrong");
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * fff - Fast File Finder
+ *
+ * High-performance fuzzy file finder for Bun, powered by Rust.
+ * Perfect for LLM agent tools that need to search through codebases.
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "fff";
+ *
+ * // Initialize with a directory
+ * const result = FileFinder.init({ basePath: "/path/to/project" });
+ * if (!result.ok) {
+ *   console.error(result.error);
+ *   process.exit(1);
+ * }
+ *
+ * // Wait for initial scan
+ * FileFinder.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = FileFinder.search("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Track file access (for frecency)
+ * FileFinder.trackAccess("/path/to/project/src/main.ts");
+ *
+ * // Cleanup when done
+ * FileFinder.destroy();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Main API
+export { FileFinder } from "./finder";
+
+// Types
+export type {
+  Result,
+  InitOptions,
+  SearchOptions,
+  FileItem,
+  Score,
+  Location,
+  SearchResult,
+  ScanProgress,
+  HealthCheck,
+  DbHealth,
+  GrepMode,
+  GrepOptions,
+  GrepMatch,
+  GrepResult,
+  GrepCursor,
+} from "./types";
+
+// Result helpers
+export { ok, err } from "./types";
+
+// Binary management (for CLI tools)
+export {
+  downloadBinary,
+  ensureBinary,
+  binaryExists,
+  getBinaryPath,
+  findBinary,
+} from "./download";
+
+// Platform utilities
+export { getTriple, getLibExtension, getLibFilename, getNpmPackageName } from "./platform";