@cmmd-center/forge 0.13.5 → 0.13.7

package/dist/node_modules/@ff-labs/fff-node/dist/src/ffi.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Node.js FFI bindings for the fff-c native library using ffi-rs
+ *
+ * This module uses ffi-rs to call into the Rust C library.
+ * All functions follow the Result pattern for error handling.
+ *
+ * The API is instance-based: `ffiCreate` returns an opaque handle that must
+ * be passed to all subsequent calls and freed with `ffiDestroy`.
+ *
+ * ## Memory management
+ *
+ * Every `fff_*` function returning `*mut FffResult` allocates with Rust's Box.
+ * We MUST call `fff_free_result` to properly deallocate (not libc::free).
+ *
+ * ## FffResult struct reading
+ *
+ * The FffResult struct layout (#[repr(C)]):
+ *   offset  0: success (bool, 1 byte + 7 padding)
+ *   offset  8: data pointer (8 bytes) - *mut c_char (JSON string or null)
+ *   offset 16: error pointer (8 bytes) - *mut c_char (error message or null)
+ *   offset 24: handle pointer (8 bytes) - *mut c_void (instance handle or null)
+ *
+ * ## Two-step approach for reading + freeing
+ *
+ * ffi-rs auto-dereferences struct retType pointers, losing the original pointer.
+ * We solve this by:
+ * 1. Calling the C function with `retType: DataType.External` to get the raw pointer
+ * 2. Using `restorePointer` to read the struct fields from the raw pointer
+ * 3. Calling `fff_free_result` with the original raw pointer
+ *
+ * ## Null pointer detection
+ *
+ * `isNullPointer` from ffi-rs correctly detects null C pointers wrapped as
+ * V8 External objects. We use this instead of truthy checks.
+ */
+import { type JsExternal } from "ffi-rs";
+import type { DirSearchResult, GrepResult, MixedSearchResult, Result, SearchResult } from "./fff-api.js";
+/**
+ * Opaque native handle type. Callers must not inspect or modify this value.
+ */
+export type NativeHandle = JsExternal;
+export declare function ffiCreate(basePath: string, frecencyDbPath: string, historyDbPath: string, _useUnsafeNoLock: boolean, enableMmapCache: boolean, enableContentIndexing: boolean, watch: boolean, aiMode: boolean, logFilePath: string, logLevel: string, cacheBudgetMaxFiles: number, cacheBudgetMaxBytes: number, cacheBudgetMaxFileSize: number, enableFsRootScanning: boolean, enableHomeDirScanning: boolean): Result<NativeHandle>;
+/**
+ * Destroy and clean up an instance.
+ */
+export declare function ffiDestroy(handle: NativeHandle): void;
+/**
+ * Perform fuzzy search.
+ */
+export declare function ffiSearch(handle: NativeHandle, query: string, currentFile: string, maxThreads: number, pageIndex: number, pageSize: number, comboBoostMultiplier: number, minComboCount: number): Result<SearchResult>;
+/**
+ * Glob-only search. Bypasses the regular query parser, applies the pattern
+ * as a single `Constraint::Glob`, ranks by frecency, paginates.
+ */
+export declare function ffiGlob(handle: NativeHandle, pattern: string, currentFile: string, maxThreads: number, pageIndex: number, pageSize: number): Result<SearchResult>;
+/**
+ * Perform fuzzy directory search.
+ */
+export declare function ffiSearchDirectories(handle: NativeHandle, query: string, currentFile: string | null, maxThreads: number, pageIndex: number, pageSize: number): Result<DirSearchResult>;
+/**
+ * Perform mixed (files + directories) fuzzy search.
+ */
+export declare function ffiSearchMixed(handle: NativeHandle, query: string, currentFile: string, maxThreads: number, pageIndex: number, pageSize: number, comboBoostMultiplier: number, minComboCount: number): Result<MixedSearchResult>;
+/**
+ * Live grep - search file contents.
+ */
+export declare 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<GrepResult>;
+/**
+ * Multi-pattern grep - Aho-Corasick multi-needle search.
+ */
+export declare 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<GrepResult>;
+/**
+ * Trigger file scan.
+ */
+export declare function ffiScanFiles(handle: NativeHandle): Result<void>;
+/**
+ * Check if scanning.
+ */
+export declare function ffiIsScanning(handle: NativeHandle): boolean;
+/**
+ * Get the base path of the file picker.
+ */
+export declare function ffiGetBasePath(handle: NativeHandle): Result<string | null>;
+/**
+ * Get scan progress.
+ */
+export declare function ffiGetScanProgress(handle: NativeHandle): Result<{
+    scannedFilesCount: number;
+    isScanning: boolean;
+    isWatcherReady: boolean;
+    isWarmupComplete: boolean;
+}>;
+/**
+ * Wait for a tree scan to complete.
+ */
+export declare function ffiWaitForScan(handle: NativeHandle, timeoutMs: number): Result<boolean>;
+/**
+ * Restart index in new path.
+ */
+export declare function ffiRestartIndex(handle: NativeHandle, newPath: string): Result<void>;
+/**
+ * Refresh git status.
+ */
+export declare function ffiRefreshGitStatus(handle: NativeHandle): Result<number>;
+/**
+ * Track query completion.
+ */
+export declare function ffiTrackQuery(handle: NativeHandle, query: string, filePath: string): Result<boolean>;
+/**
+ * Get historical query.
+ */
+export declare function ffiGetHistoricalQuery(handle: NativeHandle, offset: number): Result<string | null>;
+/**
+ * Health check.
+ *
+ * `handle` can be null for a limited check (version + git only).
+ * When null, we pass DataType.U64 with value 0 as a null pointer workaround
+ * since ffi-rs does not accept `null` for External parameters.
+ */
+export declare function ffiHealthCheck(handle: NativeHandle | null, testPath: string): Result<unknown>;
+/**
+ * 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 declare function ensureLoaded(): void;
+/**
+ * Check if the library is available.
+ */
+export declare function isAvailable(): boolean;
+/**
+ * Close the library and release ffi-rs resources.
+ * Call this when completely done with the library.
+ */
+export declare function closeLibrary(): void;
+//# sourceMappingURL=ffi.d.ts.map