@softerist/heuristic-mcp 2.1.47 → 3.0.0

package/scripts/download-model.js

@@ -1,6 +1,5 @@
-
 import path from 'path';
-import os from 'os';
+
 import { getGlobalCacheDir } from '../lib/config.js';
 
 async function downloadModel() {
@@ -13,23 +12,29 @@ async function downloadModel() {
     // Force cache directory to global location
     env.cacheDir = globalCacheDir;
 
-    console.log(`[Model Setup] Pre-caching model to: ${globalCacheDir}`);
+    console.info(`[Model Setup] Pre-caching model to: ${globalCacheDir}`);
     // Check if network is available by pinging HF (simple check)
     // Actually, pipeline() will fail fast if network is down
-    console.log(`[Model Setup] Downloading 'Xenova/all-MiniLM-L6-v2'...`);
+    console.info(`[Model Setup] Downloading 'jinaai/jina-embeddings-v2-base-code'...`);
 
     // This will download the model to the cache directory
-    await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+    await pipeline('feature-extraction', 'jinaai/jina-embeddings-v2-base-code');
 
-    console.log(`[Model Setup] ✅ Model cached successfully!`);
+    console.info(`[Model Setup] ✅ Model cached successfully!`);
   } catch (error) {
     if (error && error.code === 'ERR_MODULE_NOT_FOUND') {
-      console.warn('[Model Setup] ⚠️  Transformers not available yet; skipping model pre-download.');
-      console.warn('[Model Setup] This is okay! The server will attempt to download it when started.');
+      console.warn(
+        '[Model Setup] ⚠️  Transformers not available yet; skipping model pre-download.'
+      );
+      console.warn(
+        '[Model Setup] This is okay! The server will attempt to download it when started.'
+      );
       return;
     }
     console.warn(`[Model Setup] ⚠️  Constructive warning: Failed to pre-download model.`);
-    console.warn('[Model Setup] This is okay! The server will attempt to download it when started.');
+    console.warn(
+      '[Model Setup] This is okay! The server will attempt to download it when started.'
+    );
     console.warn(`[Model Setup] Error details: ${error.message}`);
     // Don't fail the install, just warn
   }

package/scripts/postinstall.js

@@ -1,12 +1,12 @@
 import { register } from '../features/register.js';
 
 // Run the registration process - MUST await to ensure file writes complete
-console.log('[PostInstall] Running Heuristic MCP registration...');
+console.info('[PostInstall] Running Heuristic MCP registration...');
 
 try {
-    await register();
-    console.log('[PostInstall] Registration complete.');
+  await register();
+  console.info('[PostInstall] Registration complete.');
 } catch (err) {
-    console.error('[PostInstall] Registration failed:', err.message);
-    // Don't fail the install if registration fails, just warn
+  console.error('[PostInstall] Registration failed:', err.message);
+  // Don't fail the install if registration fails, just warn
 }

package/search-configs.js

@@ -0,0 +1,36 @@
+
+import { loadConfig } from './lib/config.js';
+import { EmbeddingsCache } from './lib/cache.js';
+import { HybridSearch } from './features/hybrid-search.js';
+import { pipeline, env } from '@xenova/transformers';
+
+// Force same thread config as server
+if (env?.backends?.onnx) {
+  env.backends.onnx.numThreads = 2;
+  if (env.backends.onnx.wasm) {
+    env.backends.onnx.wasm.numThreads = 2;
+  }
+}
+
+async function searchConfigs() {
+  const config = await loadConfig(process.cwd());
+  const cache = new EmbeddingsCache(config);
+  await cache.load();
+
+  const embedder = async (text) => {
+      const pipe = await pipeline('feature-extraction', config.embeddingModel, {
+        session_options: { numThreads: 2 } 
+      });
+      return pipe(text, { pooling: 'mean', normalize: true });
+  };
+
+  const searcher = new HybridSearch(embedder, cache, config);
+  const { results } = await searcher.search('configuration files, config, settings');
+
+  console.info(JSON.stringify(results, null, 2));
+}
+
+searchConfigs().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/test/ann-config.test.js

@@ -0,0 +1,179 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AnnConfigTool, getToolDefinition, handleToolCall } from '../features/ann-config.js';
+
+describe('AnnConfigTool', () => {
+  let cache;
+  let config;
+
+  beforeEach(() => {
+    cache = {
+      getAnnStats: vi.fn(),
+      setEfSearch: vi.fn(),
+      invalidateAnnIndex: vi.fn(),
+      ensureAnnIndex: vi.fn(),
+    };
+    config = {};
+  });
+
+  it('returns stats by default', async () => {
+    const stats = {
+      enabled: true,
+      indexLoaded: false,
+      dirty: false,
+      vectorCount: 0,
+      minChunksForAnn: 10,
+    };
+    cache.getAnnStats.mockReturnValue(stats);
+    const tool = new AnnConfigTool(cache, config);
+
+    const result = await tool.execute({});
+
+    expect(result).toEqual(stats);
+    expect(cache.getAnnStats).toHaveBeenCalled();
+  });
+
+  it('validates set_ef_search arguments', async () => {
+    const tool = new AnnConfigTool(cache, config);
+
+    const result = await tool.execute({ action: 'set_ef_search' });
+
+    expect(result).toEqual({
+      success: false,
+      error: 'efSearch parameter is required for set_ef_search action',
+    });
+  });
+
+  it('sets efSearch when provided', async () => {
+    cache.setEfSearch.mockResolvedValue({ success: true });
+    const tool = new AnnConfigTool(cache, config);
+
+    const result = await tool.execute({
+      action: 'set_ef_search',
+      efSearch: 64,
+    });
+
+    expect(cache.setEfSearch).toHaveBeenCalledWith(64);
+    expect(result).toEqual({ success: true });
+  });
+
+  it('rebuilds ANN index and reports success', async () => {
+    cache.ensureAnnIndex.mockResolvedValue({ ok: true });
+    const tool = new AnnConfigTool(cache, config);
+
+    const result = await tool.execute({ action: 'rebuild' });
+
+    expect(cache.invalidateAnnIndex).toHaveBeenCalled();
+    expect(cache.ensureAnnIndex).toHaveBeenCalled();
+    expect(result).toEqual({
+      success: true,
+      message: 'ANN index rebuilt successfully',
+    });
+  });
+
+  it('reports rebuild failure when index is unavailable', async () => {
+    cache.ensureAnnIndex.mockResolvedValue(null);
+    const tool = new AnnConfigTool(cache, config);
+
+    const result = await tool.execute({ action: 'rebuild' });
+
+    expect(result).toEqual({
+      success: false,
+      message: 'ANN index rebuild failed or not available',
+    });
+  });
+
+  it('handles unknown actions', async () => {
+    const tool = new AnnConfigTool(cache, config);
+
+    const result = await tool.execute({ action: 'mystery' });
+
+    expect(result).toEqual({
+      success: false,
+      error: 'Unknown action: mystery. Valid actions: stats, set_ef_search, rebuild',
+    });
+  });
+
+  it('formats error results', () => {
+    const tool = new AnnConfigTool(cache, config);
+
+    const formatted = tool.formatResults({ success: false, error: 'boom' });
+
+    expect(formatted).toBe('Error: boom');
+  });
+
+  it('formats stats results with config', () => {
+    const tool = new AnnConfigTool(cache, config);
+    const formatted = tool.formatResults({
+      enabled: true,
+      indexLoaded: true,
+      dirty: false,
+      vectorCount: 2,
+      minChunksForAnn: 3,
+      config: {
+        metric: 'l2',
+        dim: 2,
+        count: 2,
+        m: 16,
+        efConstruction: 100,
+        efSearch: 64,
+      },
+    });
+
+    expect(formatted).toContain('ANN Index Statistics');
+    expect(formatted).toContain('Current Config');
+    expect(formatted).toContain('efSearch');
+  });
+
+  it('formats stats results without active config', () => {
+    const tool = new AnnConfigTool(cache, config);
+    const formatted = tool.formatResults({
+      enabled: true,
+      indexLoaded: false,
+      dirty: true,
+      vectorCount: 0,
+      minChunksForAnn: 1,
+      config: null,
+    });
+
+    expect(formatted).toContain('No active ANN index');
+  });
+
+  it('formats generic results as JSON', () => {
+    const tool = new AnnConfigTool(cache, config);
+    const formatted = tool.formatResults({ success: true, message: 'ok' });
+
+    expect(formatted).toBe(JSON.stringify({ success: true, message: 'ok' }, null, 2));
+  });
+
+  it('handles tool calls end-to-end', async () => {
+    cache.getAnnStats.mockReturnValue({
+      enabled: false,
+      indexLoaded: false,
+      dirty: false,
+      vectorCount: 0,
+      minChunksForAnn: 1,
+    });
+    const tool = new AnnConfigTool(cache, config);
+    const request = { params: { arguments: {} } };
+
+    const response = await handleToolCall(request, tool);
+
+    expect(response.content[0].text).toContain('ANN Index Statistics');
+  });
+
+  it('defaults missing tool arguments', async () => {
+    cache.getAnnStats.mockReturnValue({
+      enabled: true,
+      indexLoaded: false,
+      dirty: false,
+      vectorCount: 0,
+      minChunksForAnn: 1,
+    });
+    const tool = new AnnConfigTool(cache, config);
+    const request = { params: {} };
+
+    const response = await handleToolCall(request, tool);
+
+    expect(response.content[0].text).toContain('ANN Index Statistics');
+  });
+});

package/test/ann-fallback.test.js

@@ -18,12 +18,12 @@ describe('ANN Fallback (Missing hnswlib-node)', () => {
       annEnabled: true,
       annMinChunks: 5, // Low threshold for testing
       annIndexCache: false,
-      embeddingModel: 'test-model'
+      embeddingModel: 'test-model',
     };
 
     // Mock embedder
     embedder = vi.fn().mockResolvedValue({
-      data: new Float32Array([0.1, 0.2, 0.3])
+      data: new Float32Array([0.1, 0.2, 0.3]),
     });
 
     cache = new EmbeddingsCache(config);
@@ -36,7 +36,7 @@ describe('ANN Fallback (Missing hnswlib-node)', () => {
         content: `content ${i}`,
         startLine: 1,
         endLine: 5,
-        vector: [0.1, 0.2, 0.3] // simple dummy vector
+        vector: [0.1, 0.2, 0.3], // simple dummy vector
       });
     }
     cache.setVectorStore(vectors);
@@ -45,7 +45,7 @@ describe('ANN Fallback (Missing hnswlib-node)', () => {
   });
 
   it('should fall back to linear search when ANN index is unavailable', async () => {
-    const query = "test query";
+    const query = 'test query';
     const maxResults = 5;
 
     const result = await hybridSearch.search(query, maxResults);
@@ -55,7 +55,7 @@ describe('ANN Fallback (Missing hnswlib-node)', () => {
     expect(embedder).toHaveBeenCalledWith(query, expect.any(Object));
     // Verify it didn't throw and ANN attempt doesn't prevent results
     const annAttempt = await cache.queryAnn([0.1, 0.2, 0.3], 5);
-    expect(annAttempt).toBeNull();
+    expect(annAttempt).toEqual([]);
   });
 
   it('should handle ANN loading failure gracefully', async () => {
@@ -63,6 +63,6 @@ describe('ANN Fallback (Missing hnswlib-node)', () => {
     expect(index).toBeNull();
 
     const annResults = await cache.queryAnn([0.1, 0.2, 0.3], 5);
-    expect(annResults).toBeNull();
+    expect(annResults).toEqual([]);
   });
 });

package/test/binary-store.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { BinaryVectorStore } from '../lib/vector-store-binary.js';
+
+async function withTempDir(testFn) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'heuristic-binary-'));
+  try {
+    await testFn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe('BinaryVectorStore smoke', () => {
+  it('writes and loads a larger store', async () => {
+    await withTempDir(async (dir) => {
+      const count = 512;
+      const chunks = new Array(count).fill(null).map((_, i) => ({
+        file: path.join(dir, `file-${i % 8}.js`),
+        startLine: i + 1,
+        endLine: i + 2,
+        content: `line-${i}`,
+        vector: new Float32Array([i / 100, i / 200, i / 300]),
+      }));
+
+      const store = await BinaryVectorStore.write(dir, chunks, { contentCacheEntries: 4 });
+      expect(store.length).toBe(count);
+
+      const loaded = await BinaryVectorStore.load(dir, { contentCacheEntries: 4 });
+      expect(loaded.length).toBe(count);
+      expect(loaded.dim).toBe(3);
+      expect(await loaded.getContent(0)).toContain('line-0');
+
+      await store.close();
+      await loaded.close();
+    });
+  });
+
+  it('supports disk-backed vector reads', async () => {
+    await withTempDir(async (dir) => {
+      const chunks = [
+        {
+          file: path.join(dir, 'file-a.js'),
+          startLine: 1,
+          endLine: 2,
+          content: 'const x = 1;',
+          vector: new Float32Array([0.1, 0.2, 0.3]),
+        },
+      ];
+
+      const store = await BinaryVectorStore.write(dir, chunks, { contentCacheEntries: 2 });
+      await store.close();
+
+      const loaded = await BinaryVectorStore.load(dir, {
+        contentCacheEntries: 2,
+        vectorCacheEntries: 1,
+        vectorLoadMode: 'disk',
+      });
+
+      const vector = loaded.getVector(0);
+      expect(vector).toBeInstanceOf(Float32Array);
+      expect(vector.length).toBe(3);
+
+      await loaded.close();
+    });
+  });
+});

package/test/cache-branches.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+const makeConfig = (cacheDir) => ({
+  cacheDirectory: cacheDir,
+  searchDirectory: cacheDir,
+  enableCache: true,
+  callGraphEnabled: false,
+  embeddingModel: 'test-model',
+  fileExtensions: ['js'],
+  excludePatterns: [],
+  annEnabled: true,
+  annMinChunks: 1,
+  annMetric: 'cosine',
+  annM: 48,
+  annEfConstruction: 200,
+  annEfSearch: 10,
+  annIndexCache: true,
+  verbose: true,
+});
+
+async function withTempDir(testFn) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'heuristic-cache-branches-'));
+  try {
+    await testFn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe('EmbeddingsCache branch coverage', () => {
+  let consoleSpy;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    vi.clearAllMocks();
+    vi.resetModules();
+  });
+
+  it('logs when HierarchicalNSW export is missing', async () => {
+    await withTempDir(async (dir) => {
+      vi.doMock('hnswlib-node', () => ({ default: {} }));
+      const { EmbeddingsCache } = await import('../lib/cache.js');
+      const cache = new EmbeddingsCache(makeConfig(dir));
+      cache.vectorStore = [{ vector: [1, 2, 3] }];
+
+      const result = await cache.ensureAnnIndex();
+
+      expect(result).toBeNull();
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('hnswlib-node unavailable'));
+    });
+  });
+
+  it('returns null for empty ANN labels and preserves Float32Array input', async () => {
+    await withTempDir(async (dir) => {
+      const { EmbeddingsCache } = await import('../lib/cache.js');
+      const cache = new EmbeddingsCache(makeConfig(dir));
+      cache.vectorStore = [{ vector: [1, 2, 3] }];
+      const searchKnn = vi.fn().mockReturnValue({});
+      cache.annIndex = { searchKnn };
+      cache.annDirty = false;
+
+      const query = Float32Array.from([0.1, 0.2]);
+      const result = await cache.queryAnn(query, 2);
+
+      expect(result).toEqual([]);
+      expect(searchKnn).toHaveBeenCalledWith(query, 2);
+    });
+  });
+
+  it('logs embedding model and size mismatches when loading ANN metadata', async () => {
+    await withTempDir(async (dir) => {
+      const { EmbeddingsCache } = await import('../lib/cache.js');
+      const cache = new EmbeddingsCache(makeConfig(dir));
+      cache.vectorStore = [{ vector: [1, 2, 3] }];
+
+      const annMetaFile = path.join(dir, 'ann-meta.json');
+
+      await fs.writeFile(
+        annMetaFile,
+        JSON.stringify({
+          version: 1,
+          embeddingModel: 'other-model',
+          dim: 3,
+          count: 1,
+          metric: 'cosine',
+          m: 48,
+          efConstruction: 200,
+        })
+      );
+      await cache.loadAnnIndexFromDisk(class {}, 3);
+
+      await fs.writeFile(
+        annMetaFile,
+        JSON.stringify({
+          version: 1,
+          embeddingModel: 'test-model',
+          dim: 2,
+          count: 5,
+          metric: 'cosine',
+          m: 48,
+          efConstruction: 200,
+        })
+      );
+      await cache.loadAnnIndexFromDisk(class {}, 3);
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Embedding model changed for ANN index')
+      );
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('ANN index size mismatch'));
+    });
+  });
+});