[codex] Fix native addon build and runtime metadata

.coderabbit.yml

@@ -1,35 +1,23 @@
-# CodeRabbit configuration for faiss-node-native
-# Free for open source projects
+# CodeRabbit configuration file for faiss-node-native
 # https://coderabbit.ai
 
-language: "en"
+# The config is in YAML format
+# Note: This config file is optional - the defaults work well and designed for open source projects
 
-early_access: false
+language: "en"
 
 reviews:
   # Enable high-level summary of changes
   high_level_summary: true
-  high_level_summary_placeholder: "@coderabbitai summary"
 
-  # Enable poem generation (fun feature)
+  # Enable poem generation
   poem: true
 
-  # Review status checks
+  # Show status messages
   review_status: true
 
-  # Enable collapse and expand from specific lines
-  collapse_walkthrough: false
-
   # Configuration for sequence diagrams
   sequence_diagrams: true
-  path_filters:
-    - "!**/.env*"
-    - "!**/node_modules/"
-    - "!**/build/"
-    - "!**/dist/"
-    - "!**/.git/"
-    - "!**/*.lock"
-    - "!**/package-lock.json"
 
   # Auto-review settings
   auto_review:
@@ -42,133 +30,46 @@ reviews:
       - "main"
       - "develop"
 
-  # Enable path-based instructions for different file types
+  # Path filters to exclude files from review
+  path_filters:
+    - "!**/.env*"
+    - "!**/node_modules/"
+    - "!**/build/"
+    - "!**/dist/"
+    - "!**/.git/"
+    - "!**/*.lock"
+    - "!**/package-lock.json"
+
+  # Path-specific review instructions
   path_instructions:
     - path: "**/*.cpp"
-      instructions: |
+      instructions: >
         Review this C++ code with a focus on:
-        1. Memory management and resource leaks
-        2. Thread safety and mutex usage
-        3. N-API best practices for Node.js addons
-        4. Error handling and exception safety
-        5. Performance optimizations for vector operations
-        6. Proper cleanup in destructors
-        7. FAISS API usage correctness
-
-        Ensure:
-        - No raw pointers without proper RAII wrappers
-        - All FAISS resources are properly released
-        - Exception handling is compatible with N-API
-        - Code follows C++17 best practices
-        - Thread-safe operations are properly synchronized
-
-    - path: "**/*.h"
-      instructions: |
-        Review this C++ header file with a focus on:
-        1. Proper header guards
-        2. Forward declarations vs includes
-        3. Const correctness
-        4. API design clarity
-        5. Documentation completeness
-        6. Thread safety annotations
+        - Memory management and resource leaks
+        - Thread safety and mutex usage
+        - N-API best practices for Node.js addons
+        - Error handling and exception safety
+        - Proper cleanup in destructors
+        - FAISS API usage correctness
 
     - path: "src/js/**/*.js"
-      instructions: |
+      instructions: >
         Review this JavaScript code with a focus on:
-        1. Async/await error handling
-        2. Input validation and type checking
-        3. Native module boundary safety
-        4. Promise rejection handling
-        5. API ergonomics and developer experience
-        6. Proper resource cleanup
-
-        Ensure:
-        - All native calls have proper error handling
-        - Type checking before calling native methods
-        - Clear error messages for native module failures
-        - Promise chains are complete
-
-    - path: "test/**/*.js"
-      instructions: |
-        Review tests for:
-        1. Edge case coverage
-        2. Resource cleanup in tests
-        3. Async test handling
-        4. Memory leak detection
-        5. Integration test thoroughness
-        6. Performance test validity
+        - Async/await error handling
+        - Input validation and type checking
+        - Native module boundary safety
+        - Promise rejection handling
+        - API ergonomics and developer experience
+        - Proper resource cleanup
 
     - path: "binding.gyp"
-      instructions: |
+      instructions: >
         Review build configuration for:
-        1. Cross-platform compatibility
-        2. Correct library paths for FAISS
-        3. Proper compiler flags
-        4. N-API version consistency
-        5. Platform-specific linking
-
-    - path: "examples/**/*.js"
-      instructions: |
-        Review examples for:
-        1. Clarity and educational value
-        2. Best practice demonstration
-        3. Error handling patterns
-        4. Comments and explanations
-        5. Real-world applicability
-
-    - path: "*.md"
-      instructions: |
-        Review documentation for:
-        1. Accuracy of code examples
-        2. Clarity for new users
-        3. API documentation completeness
-        4. Migration guide correctness
-        5. Technical accuracy
-
-    - path: "package.json"
-      instructions: |
-        Review package.json for:
-        1. Dependency security
-        2. Semantic versioning compliance
-        3. Correct main/types entries
-        4. Scripts correctness
-        5. Metadata completeness
-
-  # Tools integration
-  tools:
-    eslint:
-      enabled: true
-      config_file: ".eslintrc.js"
-    shellcheck:
-      enabled: true
-    npm:
-      install:
-        - "faiss-node-native"
-
-# Enable knowledge base (future feature)
-knowledge_base:
-  opt_out: false
-  learnings:
-    - scope: "project_context"
-      description: "Native Node.js addon with C++ bindings to FAISS"
-      tags:
-        - "node-js"
-        - "native-addon"
-        - "cpp"
-        - "faiss"
-        - "vector-search"
-    - scope: "naming_patterns"
-      description: "Async methods use camelCase, sync methods are avoided"
-      tags:
-        - "async"
-        - "promises"
+        - Cross-platform compatibility
+        - Correct library paths for FAISS
+        - Proper compiler flags
+        - N-API version consistency
 
 # Chat configuration
 chat:
   auto_reply: true
-
-# Additional comments or notes
-comment:
-  - "Remember: This is a native addon - memory management is critical"
-  - "Thread safety is essential for production use"
-  - "Always check for proper cleanup of FAISS resources"

API.md

@@ -24,8 +24,9 @@ Creates a new FAISS index with the specified configuration.
 
 **Parameters:**
 
-- `config.type` (string, required): Index type
+- `config.type` (string, optional): Index type (default: `'FLAT_L2'`)
   - `'FLAT_L2'` - Exact search, brute force
+  - `'FLAT_IP'` - Exact inner-product search
   - `'IVF_FLAT'` - Fast approximate search with clustering
   - `'HNSW'` - State-of-the-art approximate search
 - `config.dims` (number, required): Vector dimensions (must be positive integer)
@@ -35,6 +36,8 @@ Creates a new FAISS index with the specified configuration.
 - `config.efConstruction` (number, optional): HNSW construction parameter (default: 200)
 - `config.efSearch` (number, optional): HNSW search parameter (default: 50)
 
+Use `nlist` and `nprobe` only with `IVF_FLAT`, and use `M`, `efConstruction`, and `efSearch` only with `HNSW`.
+
 **Example:**
 
 ```javascript
@@ -229,21 +232,21 @@ await ivfIndex.add(dataVectors);  // Now you can add vectors
 - `Error` if index is not IVF_FLAT
 - `Error` if index is disposed
 
-### setNprobe(nprobe: number): Promise<void>
+### setNprobe(nprobe: number): void
 
-Set the number of clusters to search for IVF_FLAT indexes.
+Set the number of clusters to search for IVF_FLAT indexes. Calling this on other index types has no effect.
 
 **Parameters:**
 - `nprobe` (number): Number of clusters to search (higher = more accurate, slower)
 
 **Example:**
 
 ```javascript
-await ivfIndex.setNprobe(20);  // Search more clusters
+ivfIndex.setNprobe(20);  // Search more clusters
 ```
 
 **Throws:**
-- `Error` if index is not IVF_FLAT
+- `TypeError` if `nprobe` is not a positive integer
 - `Error` if index is disposed
 
 ### getStats(): IndexStats
@@ -339,7 +342,7 @@ const index = await FaissIndex.fromBuffer(buffer);
 
 ### mergeFrom(otherIndex: FaissIndex): Promise<void>
 
-Merge vectors from another index into this index.
+Transfer vectors from another index into this index.
 
 **Parameters:**
 - `otherIndex` (FaissIndex): Index to merge from
@@ -354,7 +357,7 @@ await index1.add(vectors1);
 await index2.add(vectors2);
 
 await index1.mergeFrom(index2);  // index1 now contains vectors from both
-// Note: index2 is now empty (FAISS behavior)
+// Note: index2 is now empty after the transfer (FAISS behavior)
 ```
 
 **Throws:**

README.md

@@ -111,14 +111,16 @@ const index = new FaissIndex(config);
 ```
 
 **Parameters:**
-- `config.type` (string, required): Index type - `'FLAT_L2'`, `'IVF_FLAT'`, or `'HNSW'`
+- `config.type` (string, optional): Index type - `'FLAT_L2'`, `'FLAT_IP'`, `'IVF_FLAT'`, or `'HNSW'` (default: `'FLAT_L2'`)
 - `config.dims` (number, required): Vector dimensions (must be positive integer)
 - `config.nlist` (number, optional): Number of clusters for IVF_FLAT (default: 100)
 - `config.nprobe` (number, optional): Clusters to search for IVF_FLAT (default: 10)
 - `config.M` (number, optional): Connections per node for HNSW (default: 16)
 - `config.efConstruction` (number, optional): HNSW construction parameter (default: 200)
 - `config.efSearch` (number, optional): HNSW search parameter (default: 50)
 
+Use `nlist` and `nprobe` only with `IVF_FLAT`, and use `M`, `efConstruction`, and `efSearch` only with `HNSW`.
+
 **Examples:**
 
 ```javascript
@@ -256,12 +258,12 @@ await ivfIndex.train(trainingVectors);
 await ivfIndex.add(dataVectors);  // Now you can add vectors
 ```
 
-#### `setNprobe(nprobe: number): Promise<void>`
+#### `setNprobe(nprobe: number): void`
 
-Set the number of clusters to search for IVF_FLAT indexes.
+Set the number of clusters to search for IVF_FLAT indexes. Calling this on other index types has no effect.
 
 ```javascript
-await ivfIndex.setNprobe(20);  // Search more clusters (more accurate, slower)
+ivfIndex.setNprobe(20);  // Search more clusters (more accurate, slower)
 ```
 
 #### `getStats(): IndexStats`
@@ -313,7 +315,7 @@ const index = await FaissIndex.fromBuffer(buffer);
 
 #### `mergeFrom(otherIndex: FaissIndex): Promise<void>`
 
-Merge vectors from another index into this index.
+Transfer vectors from another index into this index.
 
 ```javascript
 const index1 = new FaissIndex({ type: 'FLAT_L2', dims: 128 });
@@ -323,7 +325,7 @@ await index1.add(vectors1);
 await index2.add(vectors2);
 
 await index1.mergeFrom(index2);  // index1 now contains vectors from both
-// Note: index2 is now empty (FAISS behavior)
+// Note: index2 is now empty after the transfer (FAISS behavior)
 ```
 
 #### `dispose(): void`
@@ -928,4 +930,3 @@ MIT License - see [LICENSE](./LICENSE) file for details.
 ---
 
 Made with ❤️ for the Node.js community
-

binding.gyp

@@ -12,7 +12,13 @@
         "<!@(node -p \"require('node-addon-api').include\")",
         "src/cpp",
         "/opt/homebrew/include",
+        "/opt/homebrew/opt/faiss/include",
+        "/opt/homebrew/opt/openblas/include",
+        "/opt/homebrew/opt/libomp/include",
         "/usr/local/include",
+        "/usr/local/opt/faiss/include",
+        "/usr/local/opt/openblas/include",
+        "/usr/local/opt/libomp/include",
         "/usr/include"
       ],
       "defines": [
@@ -36,19 +42,24 @@
           "libraries": [
             "-L/opt/homebrew/lib",
             "-L/usr/local/lib",
-            "-L/opt/homebrew/opt/libomp/lib",
-            "-L/usr/local/opt/libomp/lib",
-            "-L/opt/homebrew/Cellar/openblas/0.3.30/lib",
+            "-L/opt/homebrew/opt/faiss/lib",
+            "-L/usr/local/opt/faiss/lib",
+            "-L/opt/homebrew/opt/openblas/lib",
+            "-L/usr/local/opt/openblas/lib",
             "-lfaiss",
             "-lopenblas",
-            "-lomp"
           ],
           "ldflags": [
             "-L/opt/homebrew/lib",
             "-L/usr/local/lib",
-            "-L/opt/homebrew/opt/libomp/lib",
-            "-L/usr/local/opt/libomp/lib",
-            "-L/opt/homebrew/Cellar/openblas/0.3.30/lib",
+            "-L/opt/homebrew/opt/faiss/lib",
+            "-L/usr/local/opt/faiss/lib",
+            "-L/opt/homebrew/opt/openblas/lib",
+            "-L/usr/local/opt/openblas/lib",
+            "-Wl,-rpath,/opt/homebrew/opt/faiss/lib",
+            "-Wl,-rpath,/usr/local/opt/faiss/lib",
+            "-Wl,-rpath,/opt/homebrew/opt/openblas/lib",
+            "-Wl,-rpath,/usr/local/opt/openblas/lib",
             "-headerpad_max_install_names"
           ]
         }],