@softerist/heuristic-mcp 3.0.17 → 3.2.0

package/lib/cache.js

@@ -1,20 +1,21 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { Worker } from 'worker_threads';
-import { StreamingJsonWriter } from './json-writer.js';
-import { BinaryVectorStore } from './vector-store-binary.js';
-import { SqliteVectorStore } from './vector-store-sqlite.js';
-import {
-  JSON_WORKER_THRESHOLD_BYTES,
-  ANN_DIMENSION_SAMPLE_SIZE,
-  HNSWLIB_ERROR_RESET_MS,
+import { Worker } from 'worker_threads';
+import { StreamingJsonWriter } from './json-writer.js';
+import { BinaryVectorStore } from './vector-store-binary.js';
+import { SqliteVectorStore } from './vector-store-sqlite.js';
+import { isNonProjectDirectory } from './config.js';
+import {
+  JSON_WORKER_THRESHOLD_BYTES,
+  ANN_DIMENSION_SAMPLE_SIZE,
+  HNSWLIB_ERROR_RESET_MS,
   DEFAULT_READER_WAIT_TIMEOUT_MS,
 } from './constants.js';
 
 const CACHE_META_VERSION = 1;
 const CACHE_META_FILE = 'meta.json';
 
-// ANN meta version stays at 1 for compatibility; maxElements is optional.
+
 const ANN_META_VERSION = 1;
 const ANN_INDEX_FILE = 'ann-index.bin';
 const ANN_META_FILE = 'ann-meta.json';
@@ -23,7 +24,7 @@ const CALL_GRAPH_FILE = 'call-graph.json';
 
 const IS_TEST_ENV = process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
 
-// Yield to event loop to keep IDE/extension host responsive during heavy CPU loops
+
 const yieldToLoop = () => new Promise((resolve) => setImmediate(resolve));
 
 let hnswlibPromise = null;
@@ -36,9 +37,9 @@ async function parseJsonInWorker(filePath) {
       workerData: { filePath },
     });
 
-    // finish() provides safe cleanup: removeAllListeners ensures no memory leak from
-    // orphaned handlers, terminate() cleans up the worker process. The 'settled' flag
-    // prevents double-resolution if multiple events fire before cleanup completes.
+    
+    
+    
     const finish = (handler, value) => {
       if (settled) return;
       settled = true;
@@ -87,7 +88,7 @@ async function readJsonFile(
   try {
     stats = await fs.stat(filePath);
   } catch {
-    // File doesn't exist - this is expected and not an error condition
+    
     return null;
   }
 
@@ -109,7 +110,7 @@ async function readJsonFile(
 }
 
 async function loadHnswlib() {
-  // Reset error state after configured timeout to allow retry
+  
   if (hnswlibLoadError) {
     if (hnswlibLoadError._timestamp && Date.now() - hnswlibLoadError._timestamp > HNSWLIB_ERROR_RESET_MS) {
       hnswlibLoadError = null;
@@ -127,7 +128,7 @@ async function loadHnswlib() {
         return HierarchicalNSW;
       })
       .catch((err) => {
-        // Store timestamp to allow later retry
+        
         err._timestamp = Date.now();
         hnswlibLoadError = err;
         console.warn(`[ANN] hnswlib-node unavailable, using linear search (${err.message})`);
@@ -159,7 +160,7 @@ function readHnswIndex(index, filePath, maxElements) {
     index.readIndexSync(filePath, maxElements);
     return true;
   } catch {
-    /* ignore */
+    
   }
   try {
     index.readIndexSync(filePath);
@@ -181,7 +182,7 @@ function ensureFloat32(vector) {
   if (!vector) return null;
   if (vector instanceof Float32Array) return vector;
 
-  // Convert values (do NOT reinterpret bytes)
+  
   let result;
   if (ArrayBuffer.isView(vector)) {
     result = Float32Array.from(vector);
@@ -189,7 +190,7 @@ function ensureFloat32(vector) {
     result = new Float32Array(vector);
   }
 
-  // In test environment, validate that all values are finite to catch corruption early
+  
   if (IS_TEST_ENV && result.length > 0) {
     for (let i = 0; i < result.length; i++) {
       if (!Number.isFinite(result[i])) {
@@ -264,49 +265,45 @@ export class EmbeddingsCache {
       embeddingDimension: config.embeddingDimension ?? null,
     };
 
-    // Save coalescing / debounce (serialized via saveQueue)
+    
     this.saveQueue = Promise.resolve();
     this._saveTimer = null;
     this._saveRequested = false;
     this._savePromise = null;
 
-    // ANN state
+    
     this.annIndex = null;
     this.annMeta = null;
-    this.annDirty = false; // needs rebuild
-    this.annPersistDirty = false; // in-memory differs from disk
+    this.annDirty = false; 
+    this.annPersistDirty = false; 
     this.annLoading = null;
     this.annVectorCache = null;
 
-    // Call graph
+    
     this.fileCallData = new Map();
     this.callGraph = null;
     this._callGraphBuild = null;
 
-    // Binary vector store (optional)
+    
     this.binaryStore = null;
 
-    // SQLite vector store (optional)
+    
     this.sqliteStore = null;
 
-    // Error tracking
+    
     this.initErrors = [];
 
-    // Concurrency hooks (read tracking)
+    
     this.activeReads = 0;
     this._readWaiters = [];
-    this._saveInProgress = false; // Prevents new reads during save
+    this._saveInProgress = false; 
 
-    // Lazy reload support after dropping in-memory vectors
+    
     this._clearedAfterIndex = false;
     this._loadPromise = null;
   }
 
-  /**
-   * Add an initialization error with consistent structure.
-   * @param {string} stage - The stage where the error occurred (e.g., 'loadHnswlib', 'ensureAnnIndex')
-   * @param {Error|string} error - The error object or message
-   */
+  
   addInitError(stage, error) {
     this.initErrors.push({
       stage,
@@ -327,7 +324,7 @@ export class EmbeddingsCache {
       try {
         this.binaryStore.close?.();
       } catch {
-        // ignore close errors
+        
       }
       this.binaryStore = null;
     }
@@ -335,7 +332,7 @@ export class EmbeddingsCache {
       try {
         this.sqliteStore.close?.();
       } catch {
-        // ignore close errors
+        
       }
       this.sqliteStore = null;
     }
@@ -350,7 +347,7 @@ export class EmbeddingsCache {
       try {
         this.sqliteStore.close();
       } catch {
-        // SQLite may already be closed or in error state
+        
       }
       this.sqliteStore = null;
     }
@@ -394,7 +391,7 @@ export class EmbeddingsCache {
       try {
         await this.binaryStore.close();
       } catch {
-        // ignore close errors
+        
       }
       this.binaryStore = null;
     }
@@ -403,7 +400,7 @@ export class EmbeddingsCache {
       try {
         this.sqliteStore.close();
       } catch {
-        // ignore close errors
+        
       }
       this.sqliteStore = null;
     }
@@ -411,10 +408,10 @@ export class EmbeddingsCache {
     this._clearedAfterIndex = true;
   }
 
-  // -------------------- Concurrency Hooks --------------------
+  
 
   startRead() {
-    // Prevent new reads while save is in progress to avoid race conditions
+    
     if (this._saveInProgress) {
       throw new Error('Cache save in progress, try again shortly');
     }
@@ -462,7 +459,7 @@ export class EmbeddingsCache {
           if (!resolved) {
             resolved = true;
             timedOut = true;
-            // Remove waiter from array to prevent late invocation after timeout
+            
             const idx = this._readWaiters.indexOf(waiterResolve);
             if (idx >= 0) this._readWaiters.splice(idx, 1);
             resolve();
@@ -471,7 +468,7 @@ export class EmbeddingsCache {
       }),
     ]);
     if (timedOut) {
-      // Always warn (not just verbose) since proceeding with active readers is risky
+      
       console.warn(
         `[Cache] Timed out waiting for ${this.activeReads} active reader(s); proceeding with save anyway. ` +
           'This may cause data inconsistency if readers access the store during write.'
@@ -480,19 +477,16 @@ export class EmbeddingsCache {
     return !timedOut;
   }
 
-  // -------------------- Reset --------------------
+  
 
-  /**
-   * Resets the cache state (clears vectors, hashes, and call graph).
-   * Used for forced reindexing.
-   */
+  
   async reset() {
     this.vectorStore = [];
     if (this.binaryStore) {
       try {
         await this.binaryStore.close();
       } catch {
-        // ignore close errors
+        
       }
       this.binaryStore = null;
     }
@@ -500,7 +494,7 @@ export class EmbeddingsCache {
       try {
         this.sqliteStore.close();
       } catch {
-        // ignore close errors
+        
       }
       this.sqliteStore = null;
     }
@@ -510,7 +504,7 @@ export class EmbeddingsCache {
     this.initErrors = [];
   }
 
-  // -------------------- Load --------------------
+  
 
   async load({ forceVectorLoadMode } = {}) {
     if (!this.config.enableCache) return;
@@ -543,7 +537,7 @@ export class EmbeddingsCache {
         }
       };
 
-      // In tests, read cache files eagerly to exercise worker paths.
+      
       let cacheData = null;
       let hashData = null;
       let prefetched = false;
@@ -558,7 +552,7 @@ export class EmbeddingsCache {
         ]);
       }
 
-      // Read meta first to avoid parsing huge cache files when invalid
+      
       const metaData = await fs.readFile(metaFile, 'utf-8').catch(() => null);
       if (!metaData) {
         console.warn('[Cache] Missing cache metadata, ignoring cache');
@@ -668,7 +662,7 @@ export class EmbeddingsCache {
         }
       }
 
-      // SQLite store loading
+      
       if (useSqlite) {
         try {
           this.sqliteStore = await SqliteVectorStore.load(this.config.cacheDirectory);
@@ -678,7 +672,7 @@ export class EmbeddingsCache {
               includeVector: effectiveVectorLoadMode !== 'disk',
             });
           } else {
-            // SQLite file missing, need reindex
+            
             console.warn('[Cache] vectorStoreFormat=sqlite but vectors.sqlite is missing. Reindex to regenerate the cache.');
           }
         } catch (err) {
@@ -710,7 +704,7 @@ export class EmbeddingsCache {
         this.vectorStore = [];
         this.fileHashes.clear();
 
-        // Single-pass filter + normalization
+        
         for (const chunk of cacheData) {
           if (applyExtensionFilter) {
             if (!shouldKeepFile(chunk.file)) continue;
@@ -724,7 +718,7 @@ export class EmbeddingsCache {
         }
 
         if (hasHashData) {
-          // Only keep hashes for allowed extensions
+          
           for (const [file, entry] of rawHashes) {
             if (!applyExtensionFilter || shouldKeepFile(file)) {
               const normalized = normalizeFileHashEntry(entry);
@@ -745,7 +739,7 @@ export class EmbeddingsCache {
           console.info(`[Cache] Loaded ${this.vectorStore.length} cached embeddings`);
         }
 
-        // ANN index is lazily loaded/built on first query
+        
         this.annDirty = false;
         this.annPersistDirty = false;
         this.annIndex = null;
@@ -757,7 +751,7 @@ export class EmbeddingsCache {
         console.warn('[Cache] Hashes exist without embeddings; ignoring file-hashes.json');
       }
 
-      // Load call-graph data if it exists
+      
       const callGraphFile = path.join(this.config.cacheDirectory, CALL_GRAPH_FILE);
       try {
         const callGraphData = await fs.readFile(callGraphFile, 'utf8');
@@ -767,7 +761,7 @@ export class EmbeddingsCache {
           console.info(`[Cache] Loaded call-graph data for ${this.fileCallData.size} files`);
         }
       } catch {
-        // no cache yet, OK
+        
       }
     } catch (error) {
       console.warn('[Cache] Failed to load cache:', error.message);
@@ -775,7 +769,7 @@ export class EmbeddingsCache {
     }
   }
 
-  // -------------------- Save (debounced + serialized) --------------------
+  
 
   save() {
     if (!this.config.enableCache) return Promise.resolve();
@@ -809,18 +803,30 @@ export class EmbeddingsCache {
     return this._savePromise;
   }
 
-  async performSave() {
-    // Block new reads from starting during save operation
-    this._saveInProgress = true;
-
-    // Wait for active readers before modifying state to prevent data corruption
-    if (this.activeReads > 0) {
+  async performSave() {
+    
+    this._saveInProgress = true;
+    if (
+      this.config.allowSystemWorkspaceCache !== true &&
+      this.config.searchDirectory &&
+      isNonProjectDirectory(this.config.searchDirectory)
+    ) {
+      const source = this.config.workspaceResolution?.source || 'unknown';
+      console.warn(
+        `[Cache] Skipping cache save for non-project workspace (${source}): ${this.config.searchDirectory}`
+      );
+      this._saveInProgress = false;
+      return;
+    }
+
+    
+    if (this.activeReads > 0) {
       const timeoutMs = this.config.saveReaderWaitTimeoutMs ?? DEFAULT_READER_WAIT_TIMEOUT_MS;
       const allReadersFinished = await this.waitForReadersWithTimeout(timeoutMs);
       if (!allReadersFinished && !this.config.forceSaveWithActiveReaders) {
         console.warn('[Cache] Aborting save - active readers still present after timeout');
-        this._saveInProgress = false; // Reset flag on early return
-        return; // Abort instead of risking data corruption
+        this._saveInProgress = false; 
+        return; 
       }
     }
 
@@ -833,8 +839,8 @@ export class EmbeddingsCache {
       const hashFile = path.join(this.config.cacheDirectory, 'file-hashes.json');
       const metaFile = path.join(this.config.cacheDirectory, CACHE_META_FILE);
 
-      // Snapshot to avoid race conditions during async write.
-      // Keep this shallow for binary/sqlite to prevent multi-GB vector materialization.
+      
+      
       const snapshotStore = Array.isArray(this.vectorStore) ? [...this.vectorStore] : [];
       const supportsBackendVectorResolve =
         this.config.vectorStoreFormat === 'binary' || this.config.vectorStoreFormat === 'sqlite';
@@ -896,12 +902,12 @@ export class EmbeddingsCache {
           this.cacheMeta.chunksStored = this.binaryStore.length;
         }
       } else if (this.config.vectorStoreFormat === 'sqlite') {
-        // SQLite store save
+        
         if (this.sqliteStore) {
           try {
             this.sqliteStore.close();
           } catch {
-            // ignore close errors
+            
           }
           this.sqliteStore = null;
         }
@@ -930,7 +936,7 @@ export class EmbeddingsCache {
           highWaterMark: this.config.cacheWriteHighWaterMark ?? 256 * 1024,
           floatDigits: this.config.cacheVectorFloatDigits ?? 6,
           flushChars: this.config.cacheVectorFlushChars ?? 256 * 1024,
-          indent: '', // set to "  " if you prefer pretty formatting
+          indent: '', 
           assumeFinite: this.config.cacheVectorAssumeFinite,
           checkFinite: this.config.cacheVectorCheckFinite,
           noMutation: this.config.cacheVectorNoMutation ?? false,
@@ -940,7 +946,7 @@ export class EmbeddingsCache {
 
         await vectorWriter.writeStart();
 
-        // Optional responsiveness yield (only for huge saves)
+        
         const yieldEvery = total >= 50_000 ? 5000 : 0;
 
         try {
@@ -969,7 +975,7 @@ export class EmbeddingsCache {
         fs.writeFile(metaFile, JSON.stringify(this.cacheMeta, null, 2)),
       ]);
 
-      // Save call-graph data (or remove stale cache)
+      
       const callGraphFile = path.join(this.config.cacheDirectory, CALL_GRAPH_FILE);
       if (this.fileCallData.size > 0) {
         await fs.writeFile(
@@ -980,8 +986,8 @@ export class EmbeddingsCache {
         await fs.rm(callGraphFile, { force: true });
       }
 
-      // Persist ANN index if it exists and changed in memory
-      // Use mutex to prevent concurrent writes (index could be modified during save)
+      
+      
       if (
         this.config.annIndexCache !== false &&
         this.annPersistDirty &&
@@ -1007,7 +1013,7 @@ export class EmbeddingsCache {
       }
     } catch (error) {
       console.warn('[Cache] Failed to save cache:', error.message);
-      // Attempt to recover binary store if it was closed during failed save
+      
       if (
         this.config.vectorStoreFormat === 'binary' &&
         this.binaryStore &&
@@ -1021,10 +1027,10 @@ export class EmbeddingsCache {
           console.info('[Cache] Binary store recovered.');
         } catch (recoverErr) {
           console.warn(`[Cache] Failed to recover binary store: ${recoverErr.message}`);
-          this.binaryStore = null; // Ensure it's null if unusable
+          this.binaryStore = null; 
         }
       }
-      // Attempt to recover SQLite store if closed during failed save
+      
       if (
         this.config.vectorStoreFormat === 'sqlite' &&
         !this.sqliteStore
@@ -1042,11 +1048,11 @@ export class EmbeddingsCache {
       }
     } finally {
       this.isSaving = false;
-      this._saveInProgress = false; // Allow reads to resume
+      this._saveInProgress = false; 
     }
   }
 
-  // -------------------- Vector Store API --------------------
+  
 
   getVectorStore() {
     return Array.isArray(this.vectorStore) ? this.vectorStore : [];
@@ -1067,14 +1073,14 @@ export class EmbeddingsCache {
       try {
         await previousBinaryStore.close();
       } catch {
-        // ignore close errors
+        
       }
     }
     if (previousSqliteStore) {
       try {
         previousSqliteStore.close();
       } catch {
-        // ignore close errors
+        
       }
     }
   }
@@ -1185,7 +1191,7 @@ export class EmbeddingsCache {
       if (entry) return await this.getChunkContent(entry, chunk);
       if (!store && this.binaryStore) {
         const content = await this.binaryStore.getContent(chunk);
-        return content ?? '';  // Ensure consistent empty string return
+        return content ?? '';  
       }
       if (!store && this.sqliteStore) {
         return this.sqliteStore.getContent(chunk) ?? '';
@@ -1197,12 +1203,12 @@ export class EmbeddingsCache {
     }
     if (this.binaryStore && Number.isInteger(chunk?._binaryIndex)) {
       const content = await this.binaryStore.getContent(chunk._binaryIndex);
-      return content ?? '';  // Ensure consistent empty string return
+      return content ?? '';  
     }
     const resolved = Number.isInteger(index) ? index : chunk?._index;
     if (this.binaryStore && !Array.isArray(this.vectorStore) && Number.isInteger(resolved)) {
       const content = await this.binaryStore.getContent(resolved);
-      return content ?? '';  // Ensure consistent empty string return
+      return content ?? '';  
     }
     if (this.sqliteStore) {
       const sqliteIndex = Number.isInteger(chunk?._sqliteIndex)
@@ -1221,15 +1227,10 @@ export class EmbeddingsCache {
     this.fileHashes.delete(file);
   }
 
-  /**
-   * Remove all chunks for a given file from the vector store.
-   * Note: This is async to support future backend-specific cleanup.
-   * For binary/SQLite stores, actual removal happens on next full save.
-   * @param {string} file - Absolute path of file to remove
-   */
+  
   async removeFileFromStore(file) {
     if (!Array.isArray(this.vectorStore)) return;
-    // In-place compaction to avoid allocating a new large array
+    
     let w = 0;
     for (let r = 0; r < this.vectorStore.length; r++) {
       const chunk = this.vectorStore[r];
@@ -1240,10 +1241,10 @@ export class EmbeddingsCache {
     }
     this.vectorStore.length = w;
 
-    // Removing shifts labels => rebuild ANN
+    
     this.invalidateAnnIndex();
     this.removeFileCallData(file);
-    // Also remove file hash to prevent orphaned entries
+    
     this.fileHashes.delete(file);
   }
 
@@ -1261,7 +1262,7 @@ export class EmbeddingsCache {
       this.annVectorCache.push(chunk.vector);
     }
 
-    // Best-effort incremental ANN append (fast path)
+    
     if (
       this.annIndex &&
       !this.annDirty &&
@@ -1276,7 +1277,7 @@ export class EmbeddingsCache {
         this.annPersistDirty = true;
         return;
       } catch {
-        // fall through
+        
       }
     }
 
@@ -1338,20 +1339,9 @@ export class EmbeddingsCache {
     };
   }
 
-  // -------------------- ANN --------------------
-
-  /**
-   * Ensure ANN (Approximate Nearest Neighbor) index is built and ready.
-   * Loads from disk cache if available and valid, otherwise builds a new index.
-   * 
-   * @returns {Promise<HierarchicalNSW|null>} The HNSW index, or null if:
-   *   - ANN is disabled in config
-   *   - vectorStore is not an array
-   *   - vectorStore size is below annMinChunks threshold
-   *   - hnswlib-node is not available
-   *   - Vector dimension mismatch detected
-   * @note This method is safe to call multiple times; concurrent calls share the same promise.
-   */
+  
+
+  
   async ensureAnnIndex() {
     if (!this.config.annEnabled) return null;
     if (!Array.isArray(this.vectorStore)) return null;
@@ -1375,8 +1365,8 @@ export class EmbeddingsCache {
           this.sqliteStore?.dim;
         if (!dim) return null;
 
-        // Validate dimension consistency before building index
-        // Use stratified sampling for better coverage across entire store
+        
+        
         let dimensionMismatch = false;
         const sampleSize = Math.min(ANN_DIMENSION_SAMPLE_SIZE, this.vectorStore.length);
         const step = Math.max(1, Math.floor(this.vectorStore.length / sampleSize));
@@ -1394,7 +1384,7 @@ export class EmbeddingsCache {
 
         if (dimensionMismatch) {
           this.addInitError('ensureAnnIndex', `Vector dimension inconsistency detected. Expected ${dim}. Full reindex required.`);
-          return null; // Skip ANN build - fallback to linear search
+          return null; 
         }
 
         if (!this.annDirty && this.config.annIndexCache !== false) {
@@ -1549,16 +1539,7 @@ export class EmbeddingsCache {
     }
   }
 
-  /**
-   * Query the ANN index for k nearest neighbors.
-   * Falls back gracefully to empty results if ANN is unavailable.
-   * 
-   * @param {Float32Array|number[]} queryVector - Normalized query embedding
-   * @param {number} k - Number of neighbors to return
-   * @returns {Promise<number[]>} Array of chunk indices sorted by similarity (may be empty)
-   * @throws Never throws - returns empty array on all error conditions
-   * @note Automatically invalidates corrupted index and falls back to linear search on next query
-   */
+  
   async queryAnn(queryVector, k) {
     if (!Array.isArray(this.vectorStore) || this.vectorStore.length === 0) return [];
     const index = await this.ensureAnnIndex();
@@ -1566,14 +1547,14 @@ export class EmbeddingsCache {
 
     const qVec = queryVector instanceof Float32Array ? queryVector : new Float32Array(queryVector);
     
-    // Wrap searchKnn in try-catch to handle corrupted index or dimension mismatches
+    
     let results;
     try {
       results = index.searchKnn(qVec, k);
     } catch (err) {
       console.warn(`[ANN] searchKnn failed: ${err.message}. Falling back to linear search.`);
       this.addInitError('queryAnn', err);
-      // Invalidate to trigger rebuild on next query
+      
       this.invalidateAnnIndex();
       return [];
     }
@@ -1599,7 +1580,7 @@ export class EmbeddingsCache {
         try {
           await this.binaryStore.close();
         } catch {
-          // ignore close errors
+          
         }
       }
       this.binaryStore = null;
@@ -1607,7 +1588,7 @@ export class EmbeddingsCache {
         try {
           this.sqliteStore.close();
         } catch {
-          // ignore close errors
+          
         }
       }
       this.sqliteStore = null;
@@ -1623,12 +1604,7 @@ export class EmbeddingsCache {
     }
   }
 
-  /**
-   * Adjust efSearch at runtime for speed/accuracy tradeoff.
-   * Higher values = more accurate but slower.
-   * @param {number} efSearch - New efSearch value (typically 16-512)
-   * @returns {object} Result with success status and current config
-   */
+  
   setEfSearch(efSearch) {
     if (typeof efSearch !== 'number' || efSearch < 1 || efSearch > 1000) {
       return {
@@ -1655,10 +1631,7 @@ export class EmbeddingsCache {
     return { success: true, applied: false, efSearch };
   }
 
-  /**
-   * Get current ANN index statistics for diagnostics.
-   * @returns {object} ANN stats including index state, config, and vector count
-   */
+  
   getAnnStats() {
     return {
       enabled: this.config.annEnabled ?? false,
@@ -1679,7 +1652,7 @@ export class EmbeddingsCache {
     };
   }
 
-  // -------------------- Call Graph --------------------
+  
 
   async clearCallGraphData({ removeFile = false } = {}) {
     this.fileCallData.clear();
@@ -1728,20 +1701,13 @@ export class EmbeddingsCache {
     return this.fileCallData.size;
   }
 
-  /**
-   * Sets call data for a specific file.
-   * @param {string} file
-   * @param {object} data
-   */
+  
   setFileCallData(file, data) {
     this.fileCallData.set(file, data);
     this.callGraph = null;
   }
 
-  /**
-   * Sets the entire file call data map.
-   * @param {Map<string, object>|object} entries
-   */
+  
   setFileCallDataEntries(entries) {
     if (entries instanceof Map) {
       this.fileCallData = entries;
@@ -1808,12 +1774,9 @@ export class EmbeddingsCache {
     };
   }
 
-  // -------------------- Abstraction Layer --------------------
+  
 
-  /**
-   * Returns the total number of chunks in the store.
-   * @returns {number}
-   */
+  
   getStoreSize() {
     if (Array.isArray(this.vectorStore)) return this.vectorStore.length;
     if (this.binaryStore) return this.binaryStore.length;
@@ -1821,20 +1784,12 @@ export class EmbeddingsCache {
     return 0;
   }
 
-  /**
-   * Retrieves a vector by its store index.
-   * @param {number} index
-   * @returns {Float32Array|null}
-   */
+  
   getVector(index) {
     return this.getChunkVector(index);
   }
 
-  /**
-   * Retrieves a chunk object by its store index.
-   * @param {number} index
-   * @returns {object|null}
-   */
+  
   getChunk(index) {
     if (Array.isArray(this.vectorStore) && index >= 0 && index < this.vectorStore.length) {
       return this.vectorStore[index];