@sparkleideas/plugins 3.0.0-alpha.10

package/__tests__/utils/ruvector-test-utils.ts

@@ -0,0 +1,860 @@
+/**
+ * RuVector Test Utilities
+ *
+ * Shared utilities for RuVector integration tests including:
+ * - Random vector generation
+ * - Mock data factories
+ * - Test database helpers
+ * - Performance measurement utilities
+ *
+ * @module @sparkleideas/plugins/__tests__/utils/ruvector-test-utils
+ */
+
+import { vi, type Mock } from 'vitest';
+import type {
+  RuVectorConfig,
+  RuVectorClientOptions,
+  VectorSearchOptions,
+  VectorSearchResult,
+  VectorInsertOptions,
+  VectorUpdateOptions,
+  VectorIndexOptions,
+  BatchVectorOptions,
+  GraphData,
+  GNNLayer,
+  AttentionConfig,
+  AttentionInput,
+  HyperbolicEmbedding,
+  HyperbolicInput,
+  DistanceMetric,
+  VectorIndexType,
+  IndexStats,
+  QueryResult,
+  BatchResult,
+  ConnectionResult,
+  HealthStatus,
+  RuVectorStats,
+  AnalysisResult,
+  MigrationResult,
+} from '../../src/integrations/ruvector/types.js';
+
+// ============================================================================
+// Environment Detection
+// ============================================================================
+
+/**
+ * Check if real database tests should be run
+ */
+export function useRealDatabase(): boolean {
+  return process.env.RUVECTOR_TEST_DB === 'true';
+}
+
+/**
+ * Get test database configuration from environment
+ */
+export function getTestDatabaseConfig(): RuVectorConfig {
+  return {
+    host: process.env.RUVECTOR_TEST_HOST ?? 'localhost',
+    port: parseInt(process.env.RUVECTOR_TEST_PORT ?? '5432', 10),
+    database: process.env.RUVECTOR_TEST_DATABASE ?? 'ruvector_test',
+    user: process.env.RUVECTOR_TEST_USER ?? 'postgres',
+    password: process.env.RUVECTOR_TEST_PASSWORD ?? 'postgres',
+    poolSize: 5,
+    connectionTimeoutMs: 5000,
+    queryTimeoutMs: 30000,
+  };
+}
+
+// ============================================================================
+// Vector Generation Utilities
+// ============================================================================
+
+/**
+ * Generate a random vector with specified dimensions
+ */
+export function randomVector(dimensions: number = 384): number[] {
+  return Array.from({ length: dimensions }, () => Math.random() * 2 - 1);
+}
+
+/**
+ * Generate a normalized random vector (unit length)
+ */
+export function normalizedVector(dimensions: number = 384): number[] {
+  const vec = randomVector(dimensions);
+  const magnitude = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+  return vec.map(v => v / magnitude);
+}
+
+/**
+ * Generate a vector within Poincare ball (norm < 1)
+ */
+export function poincareVector(dimensions: number = 32): number[] {
+  const vec = randomVector(dimensions);
+  const magnitude = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+  const scale = Math.random() * 0.95 / Math.max(magnitude, 0.001);
+  return vec.map(v => v * scale);
+}
+
+/**
+ * Generate multiple random vectors
+ */
+export function randomVectors(count: number, dimensions: number = 384): number[][] {
+  return Array.from({ length: count }, () => randomVector(dimensions));
+}
+
+/**
+ * Generate vectors with known similarities for testing search accuracy
+ */
+export function generateSimilarVectors(
+  base: number[],
+  count: number,
+  noise: number = 0.1
+): number[][] {
+  return Array.from({ length: count }, () =>
+    base.map(v => v + (Math.random() - 0.5) * noise * 2)
+  );
+}
+
+/**
+ * Generate orthogonal vectors for testing
+ */
+export function orthogonalVectors(dimensions: number, count: number): number[][] {
+  // Simple Gram-Schmidt orthogonalization
+  const vectors: number[][] = [];
+
+  for (let i = 0; i < count; i++) {
+    let v = randomVector(dimensions);
+
+    // Subtract projections onto previous vectors
+    for (const u of vectors) {
+      const dot = v.reduce((sum, val, idx) => sum + val * u[idx], 0);
+      v = v.map((val, idx) => val - dot * u[idx]);
+    }
+
+    // Normalize
+    const mag = Math.sqrt(v.reduce((sum, val) => sum + val * val, 0));
+    if (mag > 0.001) {
+      vectors.push(v.map(val => val / mag));
+    }
+  }
+
+  return vectors;
+}
+
+/**
+ * Calculate cosine similarity between two vectors
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  const dot = a.reduce((sum, v, i) => sum + v * b[i], 0);
+  const magA = Math.sqrt(a.reduce((sum, v) => sum + v * v, 0));
+  const magB = Math.sqrt(b.reduce((sum, v) => sum + v * v, 0));
+  return dot / (magA * magB);
+}
+
+/**
+ * Calculate Euclidean distance between two vectors
+ */
+export function euclideanDistance(a: number[], b: number[]): number {
+  return Math.sqrt(a.reduce((sum, v, i) => sum + (v - b[i]) ** 2, 0));
+}
+
+/**
+ * Calculate Poincare distance in hyperbolic space
+ */
+export function poincareDistance(a: number[], b: number[]): number {
+  const normA = Math.sqrt(a.reduce((sum, v) => sum + v * v, 0));
+  const normB = Math.sqrt(b.reduce((sum, v) => sum + v * v, 0));
+  const diffNorm = Math.sqrt(a.reduce((sum, v, i) => sum + (v - b[i]) ** 2, 0));
+
+  const numerator = 2 * diffNorm ** 2;
+  const denominator = (1 - normA ** 2) * (1 - normB ** 2);
+
+  return Math.acosh(1 + numerator / Math.max(denominator, 1e-10));
+}
+
+// ============================================================================
+// Mock Data Factories
+// ============================================================================
+
+/**
+ * Create a test configuration with optional overrides
+ */
+export function createTestConfig(overrides: Partial<RuVectorConfig> = {}): RuVectorConfig {
+  return {
+    host: 'localhost',
+    port: 5432,
+    database: 'test_db',
+    user: 'test_user',
+    password: 'test_password',
+    poolSize: 10,
+    connectionTimeoutMs: 5000,
+    queryTimeoutMs: 30000,
+    schema: 'public',
+    ...overrides,
+  };
+}
+
+/**
+ * Create test client options
+ */
+export function createTestClientOptions(
+  overrides: Partial<RuVectorClientOptions> = {}
+): RuVectorClientOptions {
+  return {
+    ...createTestConfig(),
+    autoReconnect: true,
+    maxReconnectAttempts: 3,
+    ...overrides,
+  };
+}
+
+/**
+ * Create mock search results
+ */
+export function createMockSearchResults(
+  count: number,
+  options: { includeVector?: boolean; includeMetadata?: boolean; dimensions?: number } = {}
+): VectorSearchResult[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `result-${i}`,
+    score: 1 - i * (1 / count),
+    distance: i * (1 / count),
+    rank: i + 1,
+    retrievedAt: new Date(),
+    ...(options.includeVector && { vector: randomVector(options.dimensions ?? 384) }),
+    ...(options.includeMetadata && { metadata: { index: i, label: `item-${i}` } }),
+  }));
+}
+
+/**
+ * Create mock connection result
+ */
+export function createMockConnectionResult(): ConnectionResult {
+  return {
+    connectionId: `conn-${Date.now()}`,
+    ready: true,
+    serverVersion: 'PostgreSQL 15.0',
+    ruVectorVersion: '1.0.0',
+    parameters: {
+      server_encoding: 'UTF8',
+      client_encoding: 'UTF8',
+      server_version: '15.0',
+    },
+  };
+}
+
+/**
+ * Create mock index stats
+ */
+export function createMockIndexStats(
+  indexName: string,
+  indexType: VectorIndexType = 'hnsw'
+): IndexStats {
+  return {
+    indexName,
+    indexType,
+    numVectors: 10000 + Math.floor(Math.random() * 90000),
+    sizeBytes: 1024 * 1024 * (50 + Math.floor(Math.random() * 200)),
+    buildTimeMs: 5000 + Math.floor(Math.random() * 10000),
+    lastRebuild: new Date(),
+    params: {
+      m: 16,
+      efConstruction: 200,
+      ef_search: 100,
+    },
+  };
+}
+
+/**
+ * Create mock health status
+ */
+export function createMockHealthStatus(healthy: boolean = true): HealthStatus {
+  return {
+    status: healthy ? 'healthy' : 'unhealthy',
+    components: {
+      database: {
+        name: 'PostgreSQL',
+        healthy,
+        latencyMs: healthy ? 5 : undefined,
+        error: healthy ? undefined : 'Connection failed',
+      },
+      ruvector: {
+        name: 'RuVector Extension',
+        healthy,
+        latencyMs: healthy ? 1 : undefined,
+      },
+      pool: {
+        name: 'Connection Pool',
+        healthy: true,
+        latencyMs: 0,
+      },
+    },
+    lastCheck: new Date(),
+    issues: healthy ? [] : ['Database connection failed'],
+  };
+}
+
+/**
+ * Create mock stats
+ */
+export function createMockStats(): RuVectorStats {
+  return {
+    version: '1.0.0',
+    totalVectors: 100000,
+    totalSizeBytes: 1024 * 1024 * 500,
+    numIndices: 3,
+    numTables: 5,
+    queryStats: {
+      totalQueries: 50000,
+      avgQueryTimeMs: 15,
+      p95QueryTimeMs: 50,
+      p99QueryTimeMs: 100,
+      cacheHitRate: 0.85,
+    },
+    memoryStats: {
+      usedBytes: 1024 * 1024 * 256,
+      peakBytes: 1024 * 1024 * 512,
+      indexBytes: 1024 * 1024 * 150,
+      cacheBytes: 1024 * 1024 * 50,
+    },
+  };
+}
+
+/**
+ * Create mock analysis result
+ */
+export function createMockAnalysisResult(tableName: string = 'vectors'): AnalysisResult {
+  return {
+    tableName,
+    numRows: 10000,
+    columnStats: [
+      {
+        columnName: 'id',
+        dataType: 'uuid',
+        nullPercent: 0,
+        distinctCount: 10000,
+        avgSizeBytes: 16,
+      },
+      {
+        columnName: 'embedding',
+        dataType: 'vector(384)',
+        nullPercent: 0,
+        distinctCount: 10000,
+        avgSizeBytes: 1536,
+      },
+      {
+        columnName: 'metadata',
+        dataType: 'jsonb',
+        nullPercent: 5,
+        distinctCount: 9500,
+        avgSizeBytes: 256,
+      },
+    ],
+    recommendations: [
+      'Consider adding an HNSW index for faster similarity search',
+      'Metadata column could benefit from a GIN index',
+    ],
+  };
+}
+
+/**
+ * Create mock migration result
+ */
+export function createMockMigrationResult(
+  name: string,
+  direction: 'up' | 'down' = 'up',
+  success: boolean = true
+): MigrationResult {
+  return {
+    name,
+    success,
+    direction,
+    durationMs: 500 + Math.floor(Math.random() * 2000),
+    affectedTables: ['vectors', 'vector_indices'],
+    error: success ? undefined : 'Migration failed: table already exists',
+  };
+}
+
+// ============================================================================
+// Graph Data Factories
+// ============================================================================
+
+/**
+ * Create a random graph for GNN testing
+ */
+export function createRandomGraph(
+  numNodes: number,
+  numEdges: number,
+  featureDim: number
+): GraphData {
+  const nodeFeatures = randomVectors(numNodes, featureDim);
+  const edges: [number[], number[]] = [[], []];
+
+  for (let i = 0; i < numEdges; i++) {
+    const source = Math.floor(Math.random() * numNodes);
+    const target = Math.floor(Math.random() * numNodes);
+    edges[0].push(source);
+    edges[1].push(target);
+  }
+
+  return {
+    nodeFeatures,
+    edgeIndex: edges,
+  };
+}
+
+/**
+ * Create a complete graph (all nodes connected)
+ */
+export function createCompleteGraph(numNodes: number, featureDim: number): GraphData {
+  const nodeFeatures = randomVectors(numNodes, featureDim);
+  const edges: [number[], number[]] = [[], []];
+
+  for (let i = 0; i < numNodes; i++) {
+    for (let j = 0; j < numNodes; j++) {
+      if (i !== j) {
+        edges[0].push(i);
+        edges[1].push(j);
+      }
+    }
+  }
+
+  return {
+    nodeFeatures,
+    edgeIndex: edges,
+  };
+}
+
+/**
+ * Create a chain graph (linear sequence)
+ */
+export function createChainGraph(numNodes: number, featureDim: number): GraphData {
+  const nodeFeatures = randomVectors(numNodes, featureDim);
+  const edges: [number[], number[]] = [[], []];
+
+  for (let i = 0; i < numNodes - 1; i++) {
+    edges[0].push(i);
+    edges[1].push(i + 1);
+    // Bidirectional
+    edges[0].push(i + 1);
+    edges[1].push(i);
+  }
+
+  return {
+    nodeFeatures,
+    edgeIndex: edges,
+  };
+}
+
+// ============================================================================
+// Mock Database Interfaces
+// ============================================================================
+
+/**
+ * Mock PostgreSQL client interface
+ */
+export interface MockPgClient {
+  connect: Mock;
+  query: Mock;
+  release: Mock;
+  end: Mock;
+  on: Mock;
+  off: Mock;
+}
+
+/**
+ * Mock PostgreSQL pool interface
+ */
+export interface MockPgPool {
+  connect: Mock;
+  query: Mock;
+  end: Mock;
+  on: Mock;
+  totalCount: number;
+  idleCount: number;
+  waitingCount: number;
+}
+
+/**
+ * Create a mock PostgreSQL client
+ */
+export function createMockPgClient(): MockPgClient {
+  return {
+    connect: vi.fn().mockResolvedValue(undefined),
+    query: vi.fn().mockResolvedValue({ rows: [], rowCount: 0 }),
+    release: vi.fn(),
+    end: vi.fn().mockResolvedValue(undefined),
+    on: vi.fn(),
+    off: vi.fn(),
+  };
+}
+
+/**
+ * Create a mock PostgreSQL pool
+ */
+export function createMockPgPool(): MockPgPool {
+  const mockClient = createMockPgClient();
+  return {
+    connect: vi.fn().mockResolvedValue(mockClient),
+    query: vi.fn().mockResolvedValue({ rows: [], rowCount: 0 }),
+    end: vi.fn().mockResolvedValue(undefined),
+    on: vi.fn(),
+    totalCount: 10,
+    idleCount: 5,
+    waitingCount: 0,
+  };
+}
+
+// ============================================================================
+// Performance Testing Utilities
+// ============================================================================
+
+/**
+ * Measure execution time of an async function
+ */
+export async function measureAsync<T>(
+  fn: () => Promise<T>
+): Promise<{ result: T; durationMs: number }> {
+  const start = performance.now();
+  const result = await fn();
+  const durationMs = performance.now() - start;
+  return { result, durationMs };
+}
+
+/**
+ * Run a function multiple times and return statistics
+ */
+export async function benchmark<T>(
+  fn: () => Promise<T>,
+  iterations: number = 100
+): Promise<{
+  iterations: number;
+  totalMs: number;
+  avgMs: number;
+  minMs: number;
+  maxMs: number;
+  p95Ms: number;
+  p99Ms: number;
+}> {
+  const times: number[] = [];
+
+  for (let i = 0; i < iterations; i++) {
+    const { durationMs } = await measureAsync(fn);
+    times.push(durationMs);
+  }
+
+  times.sort((a, b) => a - b);
+
+  return {
+    iterations,
+    totalMs: times.reduce((sum, t) => sum + t, 0),
+    avgMs: times.reduce((sum, t) => sum + t, 0) / iterations,
+    minMs: times[0],
+    maxMs: times[times.length - 1],
+    p95Ms: times[Math.floor(iterations * 0.95)],
+    p99Ms: times[Math.floor(iterations * 0.99)],
+  };
+}
+
+/**
+ * Generate test data for throughput testing
+ */
+export function generateBulkInsertData(
+  count: number,
+  dimensions: number = 384
+): VectorInsertOptions['vectors'] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `bulk-${Date.now()}-${i}`,
+    vector: randomVector(dimensions),
+    metadata: {
+      index: i,
+      timestamp: Date.now(),
+      batch: Math.floor(i / 100),
+    },
+  }));
+}
+
+// ============================================================================
+// Test Data Builders
+// ============================================================================
+
+/**
+ * Builder for VectorSearchOptions
+ */
+export class SearchOptionsBuilder {
+  private options: VectorSearchOptions;
+
+  constructor(dimensions: number = 384) {
+    this.options = {
+      query: randomVector(dimensions),
+      k: 10,
+      metric: 'cosine',
+    };
+  }
+
+  withQuery(query: number[]): this {
+    this.options = { ...this.options, query };
+    return this;
+  }
+
+  withK(k: number): this {
+    this.options = { ...this.options, k };
+    return this;
+  }
+
+  withMetric(metric: DistanceMetric): this {
+    this.options = { ...this.options, metric };
+    return this;
+  }
+
+  withFilter(filter: Record<string, unknown>): this {
+    this.options = { ...this.options, filter };
+    return this;
+  }
+
+  withThreshold(threshold: number): this {
+    this.options = { ...this.options, threshold };
+    return this;
+  }
+
+  withTable(tableName: string): this {
+    this.options = { ...this.options, tableName };
+    return this;
+  }
+
+  includeVector(include: boolean = true): this {
+    this.options = { ...this.options, includeVector: include };
+    return this;
+  }
+
+  includeMetadata(include: boolean = true): this {
+    this.options = { ...this.options, includeMetadata: include };
+    return this;
+  }
+
+  build(): VectorSearchOptions {
+    return { ...this.options };
+  }
+}
+
+/**
+ * Builder for VectorInsertOptions
+ */
+export class InsertOptionsBuilder {
+  private options: VectorInsertOptions;
+
+  constructor(tableName: string = 'vectors') {
+    this.options = {
+      tableName,
+      vectors: [],
+    };
+  }
+
+  addVector(
+    vector: number[],
+    id?: string,
+    metadata?: Record<string, unknown>
+  ): this {
+    this.options = {
+      ...this.options,
+      vectors: [...this.options.vectors, { id, vector, metadata }],
+    };
+    return this;
+  }
+
+  addRandomVectors(count: number, dimensions: number = 384): this {
+    const vectors = Array.from({ length: count }, (_, i) => ({
+      id: `gen-${Date.now()}-${i}`,
+      vector: randomVector(dimensions),
+      metadata: { generated: true, index: i },
+    }));
+    this.options = {
+      ...this.options,
+      vectors: [...this.options.vectors, ...vectors],
+    };
+    return this;
+  }
+
+  withUpsert(upsert: boolean = true): this {
+    this.options = { ...this.options, upsert };
+    return this;
+  }
+
+  withBatchSize(batchSize: number): this {
+    this.options = { ...this.options, batchSize };
+    return this;
+  }
+
+  withReturning(returning: boolean = true): this {
+    this.options = { ...this.options, returning };
+    return this;
+  }
+
+  build(): VectorInsertOptions {
+    return { ...this.options };
+  }
+}
+
+/**
+ * Builder for VectorIndexOptions
+ */
+export class IndexOptionsBuilder {
+  private options: VectorIndexOptions;
+
+  constructor(tableName: string, columnName: string = 'embedding') {
+    this.options = {
+      tableName,
+      columnName,
+      indexType: 'hnsw',
+    };
+  }
+
+  withType(indexType: VectorIndexType): this {
+    this.options = { ...this.options, indexType };
+    return this;
+  }
+
+  withName(indexName: string): this {
+    this.options = { ...this.options, indexName };
+    return this;
+  }
+
+  withMetric(metric: DistanceMetric): this {
+    this.options = { ...this.options, metric };
+    return this;
+  }
+
+  withHNSWParams(m: number, efConstruction: number): this {
+    this.options = { ...this.options, m, efConstruction };
+    return this;
+  }
+
+  withIVFParams(lists: number): this {
+    this.options = { ...this.options, lists };
+    return this;
+  }
+
+  concurrent(concurrent: boolean = true): this {
+    this.options = { ...this.options, concurrent };
+    return this;
+  }
+
+  replace(replace: boolean = true): this {
+    this.options = { ...this.options, replace };
+    return this;
+  }
+
+  build(): VectorIndexOptions {
+    return { ...this.options };
+  }
+}
+
+// ============================================================================
+// Assertion Helpers
+// ============================================================================
+
+/**
+ * Assert that results are sorted by score descending
+ */
+export function assertSortedByScore(results: VectorSearchResult[]): void {
+  for (let i = 1; i < results.length; i++) {
+    if (results[i].score > results[i - 1].score) {
+      throw new Error(
+        `Results not sorted by score: ${results[i - 1].score} > ${results[i].score}`
+      );
+    }
+  }
+}
+
+/**
+ * Assert that results are sorted by distance ascending
+ */
+export function assertSortedByDistance(results: VectorSearchResult[]): void {
+  for (let i = 1; i < results.length; i++) {
+    if (
+      results[i].distance !== undefined &&
+      results[i - 1].distance !== undefined &&
+      results[i].distance! < results[i - 1].distance!
+    ) {
+      throw new Error(
+        `Results not sorted by distance: ${results[i - 1].distance} < ${results[i].distance}`
+      );
+    }
+  }
+}
+
+/**
+ * Assert that all vectors are normalized (unit length)
+ */
+export function assertNormalized(vectors: number[][], tolerance: number = 0.001): void {
+  for (const vec of vectors) {
+    const magnitude = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+    if (Math.abs(magnitude - 1) > tolerance) {
+      throw new Error(`Vector not normalized: magnitude = ${magnitude}`);
+    }
+  }
+}
+
+/**
+ * Assert that all vectors are inside Poincare ball
+ */
+export function assertInPoincareBall(
+  vectors: number[][],
+  maxNorm: number = 0.99
+): void {
+  for (const vec of vectors) {
+    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+    if (norm >= maxNorm) {
+      throw new Error(`Vector outside Poincare ball: norm = ${norm}`);
+    }
+  }
+}
+
+// ============================================================================
+// Cleanup Utilities
+// ============================================================================
+
+/**
+ * Generate unique table name for tests
+ */
+export function uniqueTableName(prefix: string = 'test'): string {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Generate unique index name for tests
+ */
+export function uniqueIndexName(tableName: string, columnName: string = 'embedding'): string {
+  return `idx_${tableName}_${columnName}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type {
+  RuVectorConfig,
+  RuVectorClientOptions,
+  VectorSearchOptions,
+  VectorSearchResult,
+  VectorInsertOptions,
+  VectorUpdateOptions,
+  VectorIndexOptions,
+  BatchVectorOptions,
+  GraphData,
+  GNNLayer,
+  AttentionConfig,
+  AttentionInput,
+  HyperbolicEmbedding,
+  HyperbolicInput,
+  DistanceMetric,
+  VectorIndexType,
+  IndexStats,
+  QueryResult,
+  BatchResult,
+  ConnectionResult,
+  HealthStatus,
+  RuVectorStats,
+  AnalysisResult,
+  MigrationResult,
+};