@ff-labs/fff-bun 0.1.0-nightly.00750c2

package/src/finder.ts

@@ -0,0 +1,413 @@
+/**
+ * FileFinder - High-level API for the fff file finder
+ *
+ * This class provides a type-safe, ergonomic API for file finding operations.
+ * Each instance owns an independent native file picker that can be created
+ * and destroyed independently. Multiple instances can coexist.
+ *
+ * All methods return Result types for explicit error handling.
+ */
+
+import {
+  ffiCreate,
+  ffiDestroy,
+  ffiSearch,
+  ffiLiveGrep,
+  ffiScanFiles,
+  ffiIsScanning,
+  ffiGetScanProgress,
+  ffiWaitForScan,
+  ffiRestartIndex,
+  ffiTrackAccess,
+  ffiRefreshGitStatus,
+  ffiTrackQuery,
+  ffiGetHistoricalQuery,
+  ffiHealthCheck,
+  ensureLoaded,
+  isAvailable,
+  type NativeHandle,
+} 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
+ *
+ * Each instance is backed by an independent native file picker. Create as many
+ * as you need and destroy them when done.
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "fff";
+ *
+ * // Create an instance
+ * const finder = FileFinder.create({ basePath: "/path/to/project" });
+ * if (!finder.ok) {
+ *   console.error(finder.error);
+ *   process.exit(1);
+ * }
+ *
+ * // Wait for initial scan
+ * finder.value.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = finder.value.search("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Cleanup
+ * finder.value.destroy();
+ * ```
+ */
+export class FileFinder {
+  private handle: NativeHandle | null;
+
+  private constructor(handle: NativeHandle) {
+    this.handle = handle;
+  }
+
+  /**
+   * Create a new file finder instance.
+   *
+   * @param options - Initialization options
+   * @returns Result containing the new FileFinder instance or an error
+   *
+   * @example
+   * ```typescript
+   * // Basic initialization
+   * const finder = FileFinder.create({ basePath: "/path/to/project" });
+   *
+   * // With custom database paths
+   * const finder = FileFinder.create({
+   *   basePath: "/path/to/project",
+   *   frecencyDbPath: "/custom/frecency.mdb",
+   *   historyDbPath: "/custom/history.mdb",
+   * });
+   * ```
+   */
+  static create(options: InitOptions): Result<FileFinder> {
+    const internalOpts = toInternalInitOptions(options);
+    const result = ffiCreate(JSON.stringify(internalOpts));
+
+    if (!result.ok) {
+      return result;
+    }
+
+    return { ok: true, value: new FileFinder(result.value) };
+  }
+
+  /**
+   * Destroy and clean up all resources.
+   *
+   * Call this when you're done using the file finder to free memory
+   * and stop background file watching. After calling this, the instance
+   * must not be used again.
+   */
+  destroy(): void {
+    if (this.handle !== null) {
+      ffiDestroy(this.handle);
+      this.handle = null;
+    }
+  }
+
+  /**
+   * Check if this instance has been destroyed.
+   */
+  get isDestroyed(): boolean {
+    return this.handle === null;
+  }
+
+  /**
+   * Guard that returns an error if the instance has been destroyed.
+   */
+  private ensureAlive(): Result<NativeHandle> {
+    if (this.handle === null) {
+      return err("FileFinder instance has been destroyed.");
+    }
+    return { ok: true, value: this.handle };
+  }
+
+  /**
+   * 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 = finder.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);
+   *   }
+   * }
+   * ```
+   */
+  search(query: string, options?: SearchOptions): Result<SearchResult> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+
+    const internalOpts = toInternalSearchOptions(options);
+    const result = ffiSearch(guard.value, query, JSON.stringify(internalOpts));
+
+    if (!result.ok) {
+      return result;
+    }
+
+    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 = finder.liveGrep("TODO", { mode: "plain" });
+   * 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 = finder.liveGrep("TODO", {
+   *       cursor: result.value.nextCursor,
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  liveGrep(query: string, options?: GrepOptions): Result<GrepResult> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+
+    const internalOpts = toInternalGrepOptions(options);
+    const result = ffiLiveGrep(
+      guard.value,
+      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.
+   */
+  scanFiles(): Result<void> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiScanFiles(guard.value);
+  }
+
+  /**
+   * Check if a scan is currently in progress.
+   */
+  isScanning(): boolean {
+    if (this.handle === null) return false;
+    return ffiIsScanning(this.handle);
+  }
+
+  /**
+   * Get the current scan progress.
+   */
+  getScanProgress(): Result<ScanProgress> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiGetScanProgress(guard.value) 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
+   * const finder = FileFinder.create({ basePath: "/path/to/project" });
+   * if (finder.ok) {
+   *   const completed = finder.value.waitForScan(10000);
+   *   if (!completed.ok || !completed.value) {
+   *     console.warn("Scan did not complete in time");
+   *   }
+   * }
+   * ```
+   */
+  waitForScan(timeoutMs: number = 5000): Result<boolean> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiWaitForScan(guard.value, 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
+   */
+  reindex(newPath: string): Result<void> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiRestartIndex(guard.value, 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
+   */
+  trackAccess(filePath: string): Result<boolean> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiTrackAccess(guard.value, filePath);
+  }
+
+  /**
+   * Refresh the git status cache.
+   *
+   * @returns Number of files with updated git status
+   */
+  refreshGitStatus(): Result<number> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiRefreshGitStatus(guard.value);
+  }
+
+  /**
+   * 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
+   */
+  trackQuery(query: string, selectedFilePath: string): Result<boolean> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiTrackQuery(guard.value, 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
+   */
+  getHistoricalQuery(offset: number): Result<string | null> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiGetHistoricalQuery(guard.value, 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
+   */
+  healthCheck(testPath?: string): Result<HealthCheck> {
+    return ffiHealthCheck(
+      this.handle,
+      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();
+  }
+
+  /**
+   * Get a health check without requiring an instance.
+   *
+   * Returns limited info (version + git only, no picker/frecency/query data).
+   *
+   * @param testPath - Optional path to test git repository detection
+   */
+  static healthCheckStatic(testPath?: string): Result<HealthCheck> {
+    return ffiHealthCheck(null, testPath || "") as Result<HealthCheck>;
+  }
+}

package/src/git-lifecycle.test.ts

@@ -0,0 +1,291 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { FileFinder } from "./index";
+import type { FileItem } from "./types";
+import {
+  mkdtempSync,
+  writeFileSync,
+  rmSync,
+  unlinkSync,
+  mkdirSync,
+  realpathSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+/**
+ * Integration test: full git lifecycle with a real repository.
+ *
+ * Creates a temporary git repo, initialises a FileFinder instance pointing at
+ * it, then walks through:
+ *   1. Initial scan – committed files should have status "clean"
+ *   2. Add a new untracked file – should appear as "untracked"
+ *   3. Stage the new file – should appear as "staged_new"
+ *   4. Commit – should become "clean"
+ *   5. Modify a tracked file – should become "modified"
+ *   6. Stage the modification – should become "staged_modified"
+ *   7. Commit again – back to "clean"
+ *   8. Delete a file – should disappear from the index
+ */
+
+const WATCHER_SETTLE_MS = 500; // accompany for the debouncer and replicate real life uasage
+
+function git(cwd: string, ...args: string[]) {
+  const escaped = args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(" ");
+  execSync(`git ${escaped}`, {
+    cwd,
+    stdio: "pipe",
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "test",
+      GIT_AUTHOR_EMAIL: "test@test.com",
+      GIT_COMMITTER_NAME: "test",
+      GIT_COMMITTER_EMAIL: "test@test.com",
+    },
+  });
+}
+
+function sleep(ms: number) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function findFile(finder: FileFinder, name: string): FileItem | undefined {
+  const result = finder.search(name, { pageSize: 200 });
+  if (!result.ok) throw new Error(`search failed: ${result.error}`);
+  return result.value.items.find((item) => item.fileName === name);
+}
+
+describe.skipIf(process.platform === "win32")(
+  "Git lifecycle integration",
+  () => {
+    let tmpDir: string;
+    let finder: FileFinder;
+
+    beforeAll(() => {
+      // Create temp directory and initialise a git repo with two committed files.
+      // Use realpathSync to resolve symlinks (macOS /var -> /private/var) so
+      // that git2's resolved workdir paths match the file picker's base_path.
+      tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "fff-git-test-")));
+
+      git(tmpDir, "init", "-b", "main");
+      // Need at least one commit for status to work properly
+      writeFileSync(join(tmpDir, "hello.txt"), "hello world\n");
+      writeFileSync(join(tmpDir, "readme.md"), "# Test Project\n");
+      mkdirSync(join(tmpDir, "src"));
+      writeFileSync(
+        join(tmpDir, "src", "main.rs"),
+        'fn main() { println?."hi"); }\n',
+      );
+      git(tmpDir, "add", "-A");
+      git(tmpDir, "commit", "-m", "initial commit");
+
+      // Create the FileFinder instance
+      const result = FileFinder.create({ basePath: tmpDir });
+      expect(result.ok).toBe(true);
+      if (!result.ok) throw new Error(result.error);
+      finder = result.value;
+
+      // Wait for the initial scan to finish
+      const scanResult = finder.waitForScan(10_000);
+      expect(scanResult.ok).toBe(true);
+    });
+
+    afterAll(() => {
+      finder?.destroy();
+      if (tmpDir) {
+        rmSync(tmpDir, { recursive: true, force: true });
+      }
+    });
+
+    test("initial scan indexes all committed files", () => {
+      const result = finder.search("", { pageSize: 200 });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      const names = result.value.items.map((i) => i.relativePath).sort();
+      expect(names).toContain("hello.txt");
+      expect(names).toContain("readme.md");
+      expect(names).toContain("src/main.rs");
+      expect(result.value.totalFiles).toBe(3);
+    });
+
+    test("committed files have clean git status", async () => {
+      // Wait for background watcher to process initial git status
+      await sleep(WATCHER_SETTLE_MS);
+
+      const hello = findFile(finder, "hello.txt");
+      expect(hello).toBeDefined();
+      expect(hello?.gitStatus).toBe("clean");
+
+      const main = findFile(finder, "main.rs");
+      expect(main).toBeDefined();
+      expect(main?.gitStatus).toBe("clean");
+    });
+
+    test("new untracked file appears with 'untracked' status", async () => {
+      writeFileSync(join(tmpDir, "new_file.ts"), "export const x = 1;\n");
+
+      // Wait for the background watcher to pick up the change and update git status
+      await sleep(WATCHER_SETTLE_MS);
+
+      const newFile = findFile(finder, "new_file.ts");
+      expect(newFile).toBeDefined();
+      expect(newFile?.gitStatus).toBe("untracked");
+
+      // Total should now be 4
+      const all = finder.search("", { pageSize: 200 });
+      expect(all.ok).toBe(true);
+      if (all.ok) {
+        expect(all.value.totalFiles).toBe(4);
+      }
+    });
+
+    test("staging a new file changes status to 'staged_new'", async () => {
+      git(tmpDir, "add", "new_file.ts");
+
+      // Wait for background watcher to detect .git/index change
+      await sleep(WATCHER_SETTLE_MS);
+
+      const newFile = findFile(finder, "new_file.ts");
+      expect(newFile).toBeDefined();
+      expect(newFile?.gitStatus).toBe("staged_new");
+    });
+
+    test("committing makes the file 'clean'", async () => {
+      git(tmpDir, "commit", "-m", "add new_file");
+
+      // Wait for background watcher to detect .git changes
+      await sleep(WATCHER_SETTLE_MS);
+
+      const newFile = findFile(finder, "new_file.ts");
+      expect(newFile).toBeDefined();
+      expect(newFile?.gitStatus).toBe("clean");
+    });
+
+    test("modifying a tracked file changes status to 'modified'", async () => {
+      writeFileSync(
+        join(tmpDir, "hello.txt"),
+        "hello world\nupdated content\n",
+      );
+
+      // Wait for background watcher to detect file modification and update git status
+      await sleep(WATCHER_SETTLE_MS);
+
+      const hello = findFile(finder, "hello.txt");
+      expect(hello).toBeDefined();
+      expect(hello?.gitStatus).toBe("modified");
+    });
+
+    test("staging a modification changes status to 'staged_modified'", async () => {
+      git(tmpDir, "add", "hello.txt");
+
+      // Wait for background watcher to detect .git/index change
+      await sleep(WATCHER_SETTLE_MS);
+
+      const hello = findFile(finder, "hello.txt");
+      expect(hello).toBeDefined();
+      expect(hello?.gitStatus).toBe("staged_modified");
+    });
+
+    test("committing the modification returns to 'clean'", async () => {
+      git(tmpDir, "commit", "-m", "update hello");
+
+      // Wait for background watcher to detect .git changes
+      await sleep(WATCHER_SETTLE_MS);
+
+      const hello = findFile(finder, "hello.txt");
+      expect(hello).toBeDefined();
+      expect(hello?.gitStatus).toBe("clean");
+    });
+
+    test("deleting a file removes it from the index", async () => {
+      unlinkSync(join(tmpDir, "new_file.ts"));
+
+      await sleep(WATCHER_SETTLE_MS);
+
+      const result = finder.search("new_file.ts", { pageSize: 200 });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      const found = result.value.items.find(
+        (i) => i.fileName === "new_file.ts",
+      );
+      expect(found).toBeUndefined();
+
+      // Total should be back to 3
+      const all = finder.search("", { pageSize: 200 });
+      expect(all.ok).toBe(true);
+      if (all.ok) {
+        expect(all.value.totalFiles).toBe(3);
+      }
+    });
+
+    test("adding a file in a subdirectory works", async () => {
+      writeFileSync(join(tmpDir, "src", "utils.rs"), "pub fn helper() {}\n");
+
+      // Wait for background watcher to detect new file and update git status
+      await sleep(WATCHER_SETTLE_MS);
+
+      const utils = findFile(finder, "utils.rs");
+      expect(utils).toBeDefined();
+      expect(utils?.relativePath).toBe("src/utils.rs");
+      expect(utils?.gitStatus).toBe("untracked");
+    });
+
+    test("live grep finds content in a newly added file", async () => {
+      writeFileSync(
+        join(tmpDir, "src", "searchtarget.rs"),
+        'const UNIQUE_NEEDLE: &str = "xylophone_waterfall_97";\n',
+      );
+
+      await sleep(WATCHER_SETTLE_MS);
+
+      const result = finder.liveGrep("xylophone_waterfall_97", {
+        mode: "plain",
+      });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      expect(result.value.totalMatched).toBeGreaterThan(0);
+      const match = result.value.items.find(
+        (m) => m.relativePath === "src/searchtarget.rs",
+      );
+      expect(match).toBeDefined();
+      expect(match!.lineContent).toContain("xylophone_waterfall_97");
+    });
+
+    test("live grep no longer finds content after file is deleted", async () => {
+      unlinkSync(join(tmpDir, "src", "searchtarget.rs"));
+
+      await sleep(WATCHER_SETTLE_MS);
+
+      const result = finder.liveGrep("xylophone_waterfall_97", {
+        mode: "plain",
+      });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      expect(result.value.totalMatched).toBe(0);
+      expect(result.value.items.length).toBe(0);
+    });
+
+    test("full add-commit cycle for subdirectory file", async () => {
+      git(tmpDir, "add", "src/utils.rs");
+
+      await sleep(WATCHER_SETTLE_MS);
+
+      let utils = findFile(finder, "utils.rs");
+      expect(utils).toBeDefined();
+      expect(utils?.gitStatus).toBe("staged_new");
+
+      git(tmpDir, "commit", "-m", "add utils");
+
+      // Wait for background watcher to detect .git changes
+      await sleep(WATCHER_SETTLE_MS);
+
+      utils = findFile(finder, "utils.rs");
+      expect(utils).toBeDefined();
+      expect(utils?.gitStatus).toBe("clean");
+    });
+  },
+);