@ff-labs/fff-bun 0.1.0-nightly.fcdf4a9 → 0.2.4-dev.233679d

package/src/ffi.ts

@@ -9,15 +9,37 @@
  */
 
 import { CString, dlopen, FFIType, type Pointer, ptr, read } from "bun:ffi";
-import { ensureBinary, findBinary } from "./download";
-import type { Result } from "./types";
+import { findBinary } from "./download";
+import type { FileItem, Location, Result, Score, SearchResult } from "./types";
 import { err } from "./types";
 
-// Define the FFI symbols
+/** Grep mode constants matching the C API (u8). */
+const GREP_MODE_PLAIN = 0;
+const GREP_MODE_REGEX = 1;
+const GREP_MODE_FUZZY = 2;
+
+/** Map string mode to u8 */
+function grepModeToU8(mode?: string): number {
+  switch (mode) {
+    case "regex":
+      return GREP_MODE_REGEX;
+    case "fuzzy":
+      return GREP_MODE_FUZZY;
+    default:
+      return GREP_MODE_PLAIN;
+  }
+}
+
 const ffiDefinition = {
-  // Lifecycle
-  fff_create: {
-    args: [FFIType.cstring],
+  fff_create_instance: {
+    args: [
+      FFIType.cstring, // base_path
+      FFIType.cstring, // frecency_db_path
+      FFIType.cstring, // history_db_path
+      FFIType.bool, // use_unsafe_no_lock
+      FFIType.bool, // warmup_mmap_cache
+      FFIType.bool, // ai_mode
+    ],
     returns: FFIType.ptr,
   },
   fff_destroy: {
@@ -27,19 +49,54 @@ const ffiDefinition = {
 
   // Search
   fff_search: {
-    args: [FFIType.ptr, FFIType.cstring, FFIType.cstring],
+    args: [
+      FFIType.ptr, // handle
+      FFIType.cstring, // query
+      FFIType.cstring, // current_file
+      FFIType.u32, // max_threads
+      FFIType.u32, // page_index
+      FFIType.u32, // page_size
+      FFIType.i32, // combo_boost_multiplier
+      FFIType.u32, // min_combo_count
+    ],
     returns: FFIType.ptr,
   },
 
   // Live grep (content search)
   fff_live_grep: {
-    args: [FFIType.ptr, FFIType.cstring, FFIType.cstring],
+    args: [
+      FFIType.ptr, // handle
+      FFIType.cstring, // query
+      FFIType.u8, // mode
+      FFIType.u64, // max_file_size
+      FFIType.u32, // max_matches_per_file
+      FFIType.bool, // smart_case
+      FFIType.u32, // file_offset
+      FFIType.u32, // page_limit
+      FFIType.u64, // time_budget_ms
+      FFIType.u32, // before_context
+      FFIType.u32, // after_context
+      FFIType.bool, // classify_definitions
+    ],
     returns: FFIType.ptr,
   },
 
   // Multi-pattern grep (Aho-Corasick)
   fff_multi_grep: {
-    args: [FFIType.ptr, FFIType.cstring],
+    args: [
+      FFIType.ptr, // handle
+      FFIType.cstring, // patterns_joined (\n-separated)
+      FFIType.cstring, // constraints
+      FFIType.u64, // max_file_size
+      FFIType.u32, // max_matches_per_file
+      FFIType.bool, // smart_case
+      FFIType.u32, // file_offset
+      FFIType.u32, // page_limit
+      FFIType.u64, // time_budget_ms
+      FFIType.u32, // before_context
+      FFIType.u32, // after_context
+      FFIType.bool, // classify_definitions
+    ],
     returns: FFIType.ptr,
   },
 
@@ -87,6 +144,20 @@ const ffiDefinition = {
     returns: FFIType.ptr,
   },
 
+  // Search result accessors
+  fff_free_search_result: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  fff_search_result_get_item: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+  fff_search_result_get_score: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+
   // Memory management
   fff_free_result: {
     args: [FFIType.ptr],
@@ -112,7 +183,7 @@ function loadLibrary(): FFFLibrary {
   const binaryPath = findBinary();
   if (!binaryPath) {
     throw new Error(
-      "fff native library not found. Run `bunx fff download` or build from source with `cargo build --release -p fff-c`",
+      "fff native library not found. Build from source with `cargo build --release -p fff-c` or install the platform package.",
     );
   }
 
@@ -210,13 +281,24 @@ export type NativeHandle = Pointer;
 
 /**
  * Create a new file finder instance.
- *
- * Returns the opaque native handle on success. The handle must be passed to
- * all subsequent FFI calls and freed with `ffiDestroy`.
  */
-export function ffiCreate(optsJson: string): Result<NativeHandle> {
+export function ffiCreate(
+  basePath: string,
+  frecencyDbPath: string,
+  historyDbPath: string,
+  useUnsafeNoLock: boolean,
+  warmupMmapCache: boolean,
+  aiMode: boolean,
+): Result<NativeHandle> {
   const library = loadLibrary();
-  const resultPtr = library.symbols.fff_create(ptr(encodeString(optsJson)));
+  const resultPtr = library.symbols.fff_create_instance(
+    ptr(encodeString(basePath)),
+    ptr(encodeString(frecencyDbPath)),
+    ptr(encodeString(historyDbPath)),
+    useUnsafeNoLock,
+    warmupMmapCache,
+    aiMode,
+  );
 
   if (resultPtr === null) {
     return err("FFI returned null pointer");
@@ -231,7 +313,7 @@ export function ffiCreate(optsJson: string): Result<NativeHandle> {
     library.symbols.fff_free_result(resultPtr);
 
     if (!handle || handle === (0 as unknown as Pointer)) {
-      return err("fff_create returned null handle");
+      return err("fff_create_instance returned null handle");
     }
 
     return { ok: true, value: handle };
@@ -250,19 +332,254 @@ export function ffiDestroy(handle: NativeHandle): void {
   library.symbols.fff_destroy(handle);
 }
 
+// ---------------------------------------------------------------------------
+// Struct byte offsets (must match #[repr(C)] layout on 64-bit)
+// ---------------------------------------------------------------------------
+
+// FffSearchResult { items: *mut, scores: *mut, count: u32, total_matched: u32, total_files: u32, location: FffLocation }
+const SR_ITEMS    = 0;   // *mut FffFileItem (8)
+const SR_SCORES   = 8;   // *mut FffScore    (8)
+const SR_COUNT    = 16;  // u32              (4)
+const SR_MATCHED  = 20;  // u32              (4)
+const SR_TOTAL    = 24;  // u32              (4)
+// FffLocation is inlined at offset 28
+const SR_LOC_TAG  = 28;  // u8               (1 + 3 padding)
+const SR_LOC_LINE = 32;  // i32              (4)
+const SR_LOC_COL  = 36;  // i32              (4)
+const SR_LOC_END_LINE = 40; // i32           (4)
+const SR_LOC_END_COL  = 44; // i32           (4)
+
+// FffFileItem (80 bytes)
+const FI_PATH     = 0;   // *mut c_char (8)
+const FI_RELPATH  = 8;   // *mut c_char (8)
+const FI_FNAME    = 16;  // *mut c_char (8)
+const FI_GIT      = 24;  // *mut c_char (8)
+const FI_SIZE     = 32;  // u64         (8)
+const FI_MODIFIED = 40;  // u64         (8)
+const FI_ACCESS   = 48;  // i64         (8)
+const FI_MODFR    = 56;  // i64         (8)
+const FI_TOTAL_FR = 64;  // i64         (8)
+const FI_BINARY   = 72;  // bool        (1 + 7 pad)
+const FI_SIZE_OF  = 80;
+
+// FffScore (48 bytes)
+const SC_TOTAL    = 0;   // i32         (4)
+const SC_BASE     = 4;   // i32         (4)
+const SC_FNAME    = 8;   // i32         (4)
+const SC_SPECIAL  = 12;  // i32         (4)
+const SC_FREC     = 16;  // i32         (4)
+const SC_DIST     = 20;  // i32         (4)
+const SC_CURFILE  = 24;  // i32         (4)
+const SC_COMBO    = 28;  // i32         (4)
+const SC_EXACT    = 32;  // bool        (1 + 7 pad)
+const SC_MTYPE    = 40;  // *mut c_char (8)
+const SC_SIZE_OF  = 48;
+
+/** Cast a number (raw address from pointer math) to Pointer for read.*. */
+function asPtr(n: number): Pointer {
+  return n as unknown as Pointer;
+}
+
+/**
+ * Read an FffFileItem struct at the given raw address.
+ */
+function readFileItemStruct(p: number): FileItem {
+  const pp = asPtr(p);
+  return {
+    path:                      readCString(read.ptr(pp, FI_PATH)) ?? "",
+    relativePath:              readCString(read.ptr(pp, FI_RELPATH)) ?? "",
+    fileName:                  readCString(read.ptr(pp, FI_FNAME)) ?? "",
+    gitStatus:                 readCString(read.ptr(pp, FI_GIT)) ?? "",
+    size:                      Number(read.u64(pp, FI_SIZE)),
+    modified:                  Number(read.u64(pp, FI_MODIFIED)),
+    accessFrecencyScore:       Number(read.i64(pp, FI_ACCESS)),
+    modificationFrecencyScore: Number(read.i64(pp, FI_MODFR)),
+    totalFrecencyScore:        Number(read.i64(pp, FI_TOTAL_FR)),
+  };
+}
+
+/**
+ * Read an FffScore struct at the given raw address.
+ */
+function readScoreStruct(p: number): Score {
+  const pp = asPtr(p);
+  return {
+    total:               read.i32(pp, SC_TOTAL),
+    baseScore:           read.i32(pp, SC_BASE),
+    filenameBonus:       read.i32(pp, SC_FNAME),
+    specialFilenameBonus:read.i32(pp, SC_SPECIAL),
+    frecencyBoost:       read.i32(pp, SC_FREC),
+    distancePenalty:     read.i32(pp, SC_DIST),
+    currentFilePenalty:  read.i32(pp, SC_CURFILE),
+    comboMatchBoost:     read.i32(pp, SC_COMBO),
+    exactMatch:          read.u8(pp, SC_EXACT) !== 0,
+    matchType:           readCString(read.ptr(pp, SC_MTYPE)) ?? "",
+  };
+}
+
+/**
+ * Parse an FffSearchResult from a raw pointer, then free native memory.
+ */
+function parseSearchResult(resultPtr: Pointer | null): Result<SearchResult> {
+  if (resultPtr === null) {
+    return err("FFI returned null pointer");
+  }
+
+  const success = read.u8(resultPtr, 0) !== 0;
+  const errorPtr = read.ptr(resultPtr, 16);
+  const handlePtr = read.ptr(resultPtr, 24);
+
+  const library = loadLibrary();
+
+  if (!success) {
+    const errorMsg = readCString(errorPtr) || "Unknown error";
+    library.symbols.fff_free_result(resultPtr);
+    return err(errorMsg);
+  }
+
+  // Free the FffResult envelope (does NOT free handle)
+  library.symbols.fff_free_result(resultPtr);
+
+  if (handlePtr === 0) {
+    return err("fff_search returned null search result");
+  }
+
+  // Read FffSearchResult struct from handlePtr
+  // Cast number to Pointer for Bun's read.* type requirements
+  const hp = handlePtr as unknown as Pointer;
+  const count        = read.u32(hp, SR_COUNT);
+  const totalMatched = read.u32(hp, SR_MATCHED);
+  const totalFiles   = read.u32(hp, SR_TOTAL);
+  const itemsBase    = read.ptr(hp, SR_ITEMS);
+  const scoresBase   = read.ptr(hp, SR_SCORES);
+
+  // Read location
+  const locTag = read.u8(hp, SR_LOC_TAG);
+  let location: Location | undefined;
+  if (locTag === 1) {
+    location = { type: "line", line: read.i32(hp, SR_LOC_LINE) };
+  } else if (locTag === 2) {
+    location = { type: "position", line: read.i32(hp, SR_LOC_LINE), col: read.i32(hp, SR_LOC_COL) };
+  } else if (locTag === 3) {
+    location = {
+      type: "range",
+      start: { line: read.i32(hp, SR_LOC_LINE), col: read.i32(hp, SR_LOC_COL) },
+      end: { line: read.i32(hp, SR_LOC_END_LINE), col: read.i32(hp, SR_LOC_END_COL) },
+    };
+  }
+
+  // Read items and scores arrays using pointer arithmetic
+  const items: FileItem[] = [];
+  const scores: Score[] = [];
+
+  for (let i = 0; i < count; i++) {
+    items.push(readFileItemStruct(itemsBase + i * FI_SIZE_OF));
+    scores.push(readScoreStruct(scoresBase + i * SC_SIZE_OF));
+  }
+
+  // Free native search result
+  library.symbols.fff_free_search_result(hp);
+
+  const result: SearchResult = { items, scores, totalMatched, totalFiles };
+  if (location) {
+    result.location = location;
+  }
+  return { ok: true, value: result };
+}
+
 /**
  * Perform fuzzy search.
  */
 export function ffiSearch(
   handle: NativeHandle,
   query: string,
-  optsJson: string,
-): Result<unknown> {
+  currentFile: string,
+  maxThreads: number,
+  pageIndex: number,
+  pageSize: number,
+  comboBoostMultiplier: number,
+  minComboCount: number,
+): Result<SearchResult> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_search(
     handle,
     ptr(encodeString(query)),
-    ptr(encodeString(optsJson)),
+    ptr(encodeString(currentFile)),
+    maxThreads,
+    pageIndex,
+    pageSize,
+    comboBoostMultiplier,
+    minComboCount,
+  );
+  return parseSearchResult(resultPtr);
+}
+
+/**
+ * Live grep - search file contents.
+ */
+export function ffiLiveGrep(
+  handle: NativeHandle,
+  query: string,
+  mode: string,
+  maxFileSize: number,
+  maxMatchesPerFile: number,
+  smartCase: boolean,
+  fileOffset: number,
+  pageLimit: number,
+  timeBudgetMs: number,
+  beforeContext: number,
+  afterContext: number,
+  classifyDefinitions: boolean,
+): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_live_grep(
+    handle,
+    ptr(encodeString(query)),
+    grepModeToU8(mode),
+    BigInt(maxFileSize),
+    maxMatchesPerFile,
+    smartCase,
+    fileOffset,
+    pageLimit,
+    BigInt(timeBudgetMs),
+    beforeContext,
+    afterContext,
+    classifyDefinitions,
+  );
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Multi-pattern grep - Aho-Corasick multi-needle search.
+ */
+export function ffiMultiGrep(
+  handle: NativeHandle,
+  patternsJoined: string,
+  constraints: string,
+  maxFileSize: number,
+  maxMatchesPerFile: number,
+  smartCase: boolean,
+  fileOffset: number,
+  pageLimit: number,
+  timeBudgetMs: number,
+  beforeContext: number,
+  afterContext: number,
+  classifyDefinitions: boolean,
+): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_multi_grep(
+    handle,
+    ptr(encodeString(patternsJoined)),
+    ptr(encodeString(constraints)),
+    BigInt(maxFileSize),
+    maxMatchesPerFile,
+    smartCase,
+    fileOffset,
+    pageLimit,
+    BigInt(timeBudgetMs),
+    beforeContext,
+    afterContext,
+    classifyDefinitions,
   );
   return parseResult<unknown>(resultPtr);
 }
@@ -301,8 +618,6 @@ export function ffiWaitForScan(handle: NativeHandle, timeoutMs: number): Result<
   const resultPtr = library.symbols.fff_wait_for_scan(handle, BigInt(timeoutMs));
   const result = parseResult<boolean | string>(resultPtr);
   if (!result.ok) return result;
-  // JSON.parse("true") returns boolean true, but we also handle
-  // the string case defensively.
   return { ok: true, value: result.value === true || result.value === "true" };
 }
 
@@ -323,7 +638,6 @@ export function ffiRefreshGitStatus(handle: NativeHandle): Result<number> {
   const resultPtr = library.symbols.fff_refresh_git_status(handle);
   const result = parseResult<number | string>(resultPtr);
   if (!result.ok) return result;
-  // JSON.parse("3") returns 3 (number), parseInt handles both
   return {
     ok: true,
     value: typeof result.value === "number" ? result.value : parseInt(result.value, 10),
@@ -382,45 +696,12 @@ export function ffiHealthCheck(
 }
 
 /**
- * Detect workspace roots in the indexed directory.
- */
-export function ffiDetectWorkspaces(handle: NativeHandle): Result<unknown> {
-  const library = loadLibrary();
-  const resultPtr = library.symbols.fff_detect_workspaces(handle);
-  return parseResult<unknown>(resultPtr);
-}
-
-/**
- * Live grep - search file contents.
- */
-export function ffiLiveGrep(
-  handle: NativeHandle,
-  query: string,
-  optsJson: string,
-): Result<unknown> {
-  const library = loadLibrary();
-  const resultPtr = library.symbols.fff_live_grep(
-    handle,
-    ptr(encodeString(query)),
-    ptr(encodeString(optsJson)),
-  );
-  return parseResult<unknown>(resultPtr);
-}
-
-/**
- * Multi-pattern grep - Aho-Corasick multi-needle search.
- */
-export function ffiMultiGrep(handle: NativeHandle, optsJson: string): Result<unknown> {
-  const library = loadLibrary();
-  const resultPtr = library.symbols.fff_multi_grep(handle, ptr(encodeString(optsJson)));
-  return parseResult<unknown>(resultPtr);
-}
-
-/**
- * Ensure the library is loaded (for preloading).
+ * Ensure the library is loaded.
+ *
+ * Loads the native library from the platform-specific npm package
+ * or a local dev build. Throws if the binary is not found.
  */
-export async function ensureLoaded(): Promise<void> {
-  await ensureBinary();
+export function ensureLoaded(): void {
   loadLibrary();
 }
 

package/src/finder.ts

@@ -40,33 +40,7 @@ import type {
   SearchResult,
 } from "./types";
 
-import {
-  createGrepCursor,
-  err,
-  toInternalGrepOptions,
-  toInternalInitOptions,
-  toInternalMultiGrepOptions,
-  toInternalSearchOptions,
-} from "./types";
-
-/** Transform raw FFI grep result into typed GrepResult with opaque cursor. */
-function transformGrepResult(result: Result<unknown>): Result<GrepResult> {
-  if (!result.ok) {
-    return result;
-  }
-  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 };
-}
+import { createGrepCursor, err } from "./types";
 
 /**
  * FileFinder - Fast file finder with fuzzy search
@@ -127,8 +101,14 @@ export class FileFinder {
    * ```
    */
   static create(options: InitOptions): Result<FileFinder> {
-    const internalOpts = toInternalInitOptions(options);
-    const result = ffiCreate(JSON.stringify(internalOpts));
+    const result = ffiCreate(
+      options.basePath,
+      options.frecencyDbPath ?? "",
+      options.historyDbPath ?? "",
+      options.useUnsafeNoLock ?? false,
+      options.warmupMmapCache ?? false,
+      options.aiMode ?? false,
+    );
 
     if (!result.ok) {
       return result;
@@ -192,18 +172,20 @@ export class FileFinder {
    * }
    * ```
    */
-  search(query: string, options?: SearchOptions): Result<SearchResult> {
+  fileSearch(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>;
+    return ffiSearch(
+      guard.value,
+      query,
+      options?.currentFile ?? "",
+      options?.maxThreads ?? 0,
+      options?.pageIndex ?? 0,
+      options?.pageSize ?? 0,
+      options?.comboBoostMultiplier ?? 0,
+      options?.minComboCount ?? 0,
+    );
   }
 
   /**
@@ -228,26 +210,38 @@ export class FileFinder {
    * @example
    * ```typescript
    * // First page
-   * const result = finder.liveGrep("TODO", { mode: "plain" });
+   * const result = finder.grep("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", {
+   *     const page2 = finder.grep("TODO", {
    *       cursor: result.value.nextCursor,
    *     });
    *   }
    * }
    * ```
    */
-  liveGrep(query: string, options?: GrepOptions): Result<GrepResult> {
+  grep(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));
+    const result = ffiLiveGrep(
+      guard.value,
+      query,
+      options?.mode ?? "plain",
+      options?.maxFileSize ?? 0,
+      options?.maxMatchesPerFile ?? 0,
+      options?.smartCase ?? true,
+      options?.cursor?._offset ?? 0,
+      0, // page_limit (0 = default 50)
+      options?.timeBudgetMs ?? 0,
+      options?.beforeContext ?? 0,
+      options?.afterContext ?? 0,
+      false,
+    );
 
     return transformGrepResult(result);
   }
@@ -285,8 +279,20 @@ export class FileFinder {
       return err("patterns array must have at least 1 element");
     }
 
-    const internalOpts = toInternalMultiGrepOptions(options);
-    const result = ffiMultiGrep(guard.value, JSON.stringify(internalOpts));
+    const result = ffiMultiGrep(
+      guard.value,
+      options.patterns.join("\n"),
+      options.constraints ?? "",
+      options.maxFileSize ?? 0,
+      options.maxMatchesPerFile ?? 0,
+      options.smartCase ?? true,
+      options.cursor?._offset ?? 0,
+      0, // page_limit (0 = default 50)
+      options.timeBudgetMs ?? 0,
+      options.beforeContext ?? 0,
+      options.afterContext ?? 0,
+      false,
+    );
 
     return transformGrepResult(result);
   }
@@ -412,14 +418,9 @@ export class FileFinder {
     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();
+  /** Ensure the native library is loaded. */
+  static ensureLoaded(): void {
+    ensureLoaded();
   }
 
   /**
@@ -433,3 +434,21 @@ export class FileFinder {
     return ffiHealthCheck(null, testPath || "") as Result<HealthCheck>;
   }
 }
+
+function transformGrepResult(result: Result<unknown>): Result<GrepResult> {
+  if (!result.ok) {
+    return result;
+  }
+  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 };
+}