@kb-labs/shared 1.1.0

package/packages/shared-testing/src/mock-cache.ts

@@ -0,0 +1,179 @@
+/**
+ * @module @kb-labs/shared-testing/mock-cache
+ *
+ * In-memory cache mock that actually stores data (unlike noop mocks).
+ * All methods are vi.fn() spies for assertion.
+ *
+ * @example
+ * ```typescript
+ * const cache = mockCache();
+ * await cache.set('key', { data: 42 }, 5000);
+ * expect(await cache.get('key')).toEqual({ data: 42 });
+ * expect(cache.set).toHaveBeenCalledWith('key', { data: 42 }, 5000);
+ * ```
+ */
+
+import { vi } from 'vitest';
+import type { ICache } from '@kb-labs/core-platform';
+
+interface CacheEntry {
+  value: unknown;
+  expiresAt: number | null; // null = no TTL
+}
+
+interface SortedSetMember {
+  score: number;
+  member: string;
+}
+
+/**
+ * Mock cache instance with working in-memory storage.
+ * All methods are vi.fn() spies.
+ */
+export interface MockCacheInstance extends ICache {
+  /** Direct access to the internal store (for assertions) */
+  readonly store: Map<string, CacheEntry>;
+  /** Direct access to sorted sets (for assertions) */
+  readonly sortedSets: Map<string, SortedSetMember[]>;
+  /** Reset all data and spy call history */
+  reset: () => void;
+}
+
+/**
+ * Create a mock cache with working in-memory storage.
+ *
+ * Unlike noop mocks, this cache actually stores and retrieves data,
+ * respects TTL, and supports sorted set operations.
+ *
+ * @param initial - Optional initial data to populate the cache
+ *
+ * @example
+ * ```typescript
+ * // Empty cache
+ * const cache = mockCache();
+ *
+ * // Pre-populated cache
+ * const cache = mockCache({ 'user:1': { name: 'Alice' } });
+ *
+ * // TTL works
+ * await cache.set('temp', 'value', 100); // expires in 100ms
+ * await new Promise(r => setTimeout(r, 150));
+ * expect(await cache.get('temp')).toBeNull(); // expired
+ * ```
+ */
+export function mockCache(initial?: Record<string, unknown>): MockCacheInstance {
+  const store = new Map<string, CacheEntry>();
+  const sortedSets = new Map<string, SortedSetMember[]>();
+
+  // Populate initial data
+  if (initial) {
+    for (const [key, value] of Object.entries(initial)) {
+      store.set(key, { value, expiresAt: null });
+    }
+  }
+
+  function isExpired(entry: CacheEntry): boolean {
+    return entry.expiresAt !== null && Date.now() > entry.expiresAt;
+  }
+
+  // Keep raw vi.fn() references for mockClear() in reset.
+  // The ICache-typed versions are cast below for the public interface.
+  const spies: ReturnType<typeof vi.fn>[] = [];
+
+  function spy<T extends (...args: any[]) => any>(fn: T): T {
+    const s = vi.fn(fn) as unknown as T;
+    spies.push(s as unknown as ReturnType<typeof vi.fn>);
+    return s;
+  }
+
+  const getFn = spy(async (key: string): Promise<unknown> => {
+    const entry = store.get(key);
+    if (!entry || isExpired(entry)) {
+      if (entry) {store.delete(key);} // cleanup expired
+      return null;
+    }
+    return entry.value;
+  });
+
+  const setFn = spy(async (key: string, value: unknown, ttl?: number): Promise<void> => {
+    store.set(key, {
+      value,
+      expiresAt: ttl ? Date.now() + ttl : null,
+    });
+  });
+
+  const deleteFn = spy(async (key: string): Promise<void> => {
+    store.delete(key);
+  });
+
+  const clearFn = spy(async (pattern?: string): Promise<void> => {
+    if (!pattern) {
+      store.clear();
+      return;
+    }
+    // Simple glob matching: only support trailing *
+    const prefix = pattern.replace(/\*$/, '');
+    for (const key of store.keys()) {
+      if (key.startsWith(prefix)) {
+        store.delete(key);
+      }
+    }
+  });
+
+  const zaddFn = spy(async (key: string, score: number, member: string): Promise<void> => {
+    if (!sortedSets.has(key)) {sortedSets.set(key, []);}
+    const set = sortedSets.get(key)!;
+    // Remove existing member
+    const idx = set.findIndex(m => m.member === member);
+    if (idx >= 0) {set.splice(idx, 1);}
+    // Add with new score
+    set.push({ score, member });
+    // Keep sorted by score
+    set.sort((a, b) => a.score - b.score);
+  });
+
+  const zrangebyscoreFn = spy(async (key: string, min: number, max: number): Promise<string[]> => {
+    const set = sortedSets.get(key);
+    if (!set) {return [];}
+    return set
+      .filter(m => m.score >= min && m.score <= max)
+      .map(m => m.member);
+  });
+
+  const zremFn = spy(async (key: string, member: string): Promise<void> => {
+    const set = sortedSets.get(key);
+    if (!set) {return;}
+    const idx = set.findIndex(m => m.member === member);
+    if (idx >= 0) {set.splice(idx, 1);}
+  });
+
+  const setIfNotExistsFn = spy(async (key: string, value: unknown, ttl?: number): Promise<boolean> => {
+    const existing = store.get(key);
+    if (existing && !isExpired(existing)) {return false;}
+    store.set(key, {
+      value,
+      expiresAt: ttl ? Date.now() + ttl : null,
+    });
+    return true;
+  });
+
+  const instance: MockCacheInstance = {
+    get: getFn as unknown as ICache['get'],
+    set: setFn as unknown as ICache['set'],
+    delete: deleteFn,
+    clear: clearFn,
+    zadd: zaddFn,
+    zrangebyscore: zrangebyscoreFn,
+    zrem: zremFn,
+    setIfNotExists: setIfNotExistsFn as unknown as ICache['setIfNotExists'],
+    get store() { return store; },
+    get sortedSets() { return sortedSets; },
+    reset: () => {
+      store.clear();
+      sortedSets.clear();
+      for (const s of spies) {s.mockClear();}
+    },
+  };
+
+  return instance;
+}

package/packages/shared-testing/src/mock-llm.ts

@@ -0,0 +1,319 @@
+/**
+ * @module @kb-labs/shared-testing/mock-llm
+ *
+ * LLM mock builder with fluent API and call tracking.
+ *
+ * @example
+ * ```typescript
+ * const llm = mockLLM()
+ *   .onComplete('Generate commit').respondWith('feat: add login')
+ *   .onComplete(/explain/i).respondWith('This function does X')
+ *   .onAnyComplete().respondWith('default answer');
+ *
+ * const res = await llm.complete('Generate commit message');
+ * expect(res.content).toBe('feat: add login');
+ * expect(llm.complete).toHaveBeenCalledOnce();
+ * ```
+ */
+
+import { vi } from 'vitest';
+import type {
+  ILLM,
+  LLMOptions,
+  LLMResponse,
+  LLMMessage,
+  LLMToolCallOptions,
+  LLMToolCallResponse,
+  LLMToolCall,
+} from '@kb-labs/core-platform';
+
+// ────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────
+
+/** Recorded call to complete() */
+export interface LLMCall {
+  prompt: string;
+  options?: LLMOptions;
+  response: LLMResponse;
+}
+
+/** Recorded call to chatWithTools() */
+export interface LLMToolCallRecord {
+  messages: LLMMessage[];
+  options: LLMToolCallOptions;
+  response: LLMToolCallResponse;
+}
+
+type PromptMatcher = string | RegExp | ((prompt: string) => boolean);
+
+interface CompletionRule {
+  matcher: PromptMatcher;
+  response: string | LLMResponse | ((prompt: string) => string | LLMResponse);
+}
+
+/**
+ * Mock LLM instance with call tracking and fluent API.
+ * All methods are vi.fn() spies.
+ */
+export interface MockLLMInstance extends ILLM {
+  /** All recorded complete() calls */
+  calls: LLMCall[];
+  /** Last complete() call (or undefined) */
+  lastCall: LLMCall | undefined;
+  /** All recorded chatWithTools() calls */
+  toolCalls: LLMToolCallRecord[];
+  /** Reset all recorded calls and spies */
+  resetCalls: () => void;
+}
+
+/** Public type returned by mockLLM() — builder fluent API + ILLM spy instance */
+export interface MockLLM extends MockLLMInstance {
+  onComplete(matcher: PromptMatcher): { respondWith: (response: string | LLMResponse | ((prompt: string) => string | LLMResponse)) => MockLLM };
+  onAnyComplete(): { respondWith: (response: string | LLMResponse | ((prompt: string) => string | LLMResponse)) => MockLLM };
+  streaming(chunks: string[]): MockLLM;
+  failing(error: Error): MockLLM;
+  withToolCalls(calls: LLMToolCall[], content?: string): MockLLM;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Builder
+// ────────────────────────────────────────────────────────────────────
+
+class MockLLMBuilder {
+  private rules: CompletionRule[] = [];
+  private defaultResponse: string | LLMResponse | ((prompt: string) => string | LLMResponse) = 'mock response';
+  private streamChunks: string[] = ['mock'];
+  private errorToThrow: Error | null = null;
+  private toolCallsToReturn: LLMToolCall[] = [];
+  private toolCallResponseContent = '';
+
+  /**
+   * Match a specific prompt (exact string or regex).
+   * Returns a handler to set the response.
+   */
+  onComplete(matcher: PromptMatcher): { respondWith: (response: string | LLMResponse | ((prompt: string) => string | LLMResponse)) => MockLLMBuilder } {
+    return {
+      respondWith: (response) => {
+        this.rules.push({ matcher, response });
+        return this;
+      },
+    };
+  }
+
+  /**
+   * Set the default response for any prompt that doesn't match a rule.
+   */
+  onAnyComplete(): { respondWith: (response: string | LLMResponse | ((prompt: string) => string | LLMResponse)) => MockLLMBuilder } {
+    return {
+      respondWith: (response) => {
+        this.defaultResponse = response;
+        return this;
+      },
+    };
+  }
+
+  /**
+   * Configure streaming to yield specific chunks.
+   */
+  streaming(chunks: string[]): MockLLMBuilder {
+    this.streamChunks = chunks;
+    return this;
+  }
+
+  /**
+   * Make the LLM throw an error on every call.
+   */
+  failing(error: Error): MockLLMBuilder {
+    this.errorToThrow = error;
+    return this;
+  }
+
+  /**
+   * Configure chatWithTools() to return specific tool calls.
+   */
+  withToolCalls(calls: LLMToolCall[], content = ''): MockLLMBuilder {
+    this.toolCallsToReturn = calls;
+    this.toolCallResponseContent = content;
+    return this;
+  }
+
+  /**
+   * Build the mock ILLM instance. Called automatically by mockLLM().
+   */
+  build(): MockLLMInstance {
+    const calls: LLMCall[] = [];
+    const toolCallRecords: LLMToolCallRecord[] = [];
+    const rules = this.rules;
+    const defaultResponse = this.defaultResponse;
+    const streamChunks = this.streamChunks;
+    const errorToThrow = this.errorToThrow;
+    const toolCallsToReturn = this.toolCallsToReturn;
+    const toolCallResponseContent = this.toolCallResponseContent;
+
+    function resolveResponse(prompt: string): LLMResponse {
+      // Check rules in order
+      for (const rule of rules) {
+        if (matchesPrompt(rule.matcher, prompt)) {
+          return toResponse(rule.response, prompt);
+        }
+      }
+      // Fallback
+      return toResponse(defaultResponse, prompt);
+    }
+
+    const completeFn = vi.fn(async (prompt: string, options?: LLMOptions): Promise<LLMResponse> => {
+      if (errorToThrow) {throw errorToThrow;}
+      const response = resolveResponse(prompt);
+      calls.push({ prompt, options, response });
+      return response;
+    });
+
+    const streamFn = vi.fn(async function* (_prompt: string, _options?: LLMOptions): AsyncIterable<string> {
+      if (errorToThrow) {throw errorToThrow;}
+      for (const chunk of streamChunks) {
+        yield chunk;
+      }
+    });
+
+    const chatWithToolsFn = vi.fn(async (messages: LLMMessage[], options: LLMToolCallOptions): Promise<LLMToolCallResponse> => {
+      if (errorToThrow) {throw errorToThrow;}
+
+      const lastUserMsg = messages.filter(m => m.role === 'user').pop();
+      const prompt = lastUserMsg?.content ?? '';
+      const baseResponse = resolveResponse(prompt);
+
+      const response: LLMToolCallResponse = {
+        ...baseResponse,
+        content: toolCallsToReturn.length > 0 ? toolCallResponseContent : baseResponse.content,
+        toolCalls: toolCallsToReturn.length > 0 ? toolCallsToReturn : undefined,
+      };
+
+      toolCallRecords.push({ messages, options, response });
+      return response;
+    });
+
+    const instance: MockLLMInstance = {
+      complete: completeFn,
+      stream: streamFn,
+      chatWithTools: chatWithToolsFn,
+      calls,
+      toolCalls: toolCallRecords,
+      get lastCall() {
+        return calls[calls.length - 1];
+      },
+      resetCalls: () => {
+        calls.length = 0;
+        toolCallRecords.length = 0;
+        completeFn.mockClear();
+        streamFn.mockClear();
+        chatWithToolsFn.mockClear();
+      },
+    };
+
+    return instance;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────
+
+function matchesPrompt(matcher: PromptMatcher, prompt: string): boolean {
+  if (typeof matcher === 'string') {return prompt.includes(matcher);}
+  if (matcher instanceof RegExp) {return matcher.test(prompt);}
+  return matcher(prompt);
+}
+
+function toResponse(
+  value: string | LLMResponse | ((prompt: string) => string | LLMResponse),
+  prompt: string,
+): LLMResponse {
+  const resolved = typeof value === 'function' ? value(prompt) : value;
+  if (typeof resolved === 'string') {
+    return {
+      content: resolved,
+      usage: { promptTokens: 0, completionTokens: 0 },
+      model: 'mock',
+    };
+  }
+  return resolved;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a mock LLM with fluent builder API.
+ *
+ * @example
+ * ```typescript
+ * // Simple: always returns same response
+ * const llm = mockLLM();
+ *
+ * // With specific responses
+ * const llm = mockLLM()
+ *   .onComplete('generate commit').respondWith('feat: add feature')
+ *   .onComplete(/explain/i).respondWith('This code does...')
+ *   .onAnyComplete().respondWith('default');
+ *
+ * // Streaming
+ * const llm = mockLLM().streaming(['chunk1', 'chunk2', 'chunk3']);
+ *
+ * // Error simulation
+ * const llm = mockLLM().failing(new Error('rate limit exceeded'));
+ *
+ * // Tool calling
+ * const llm = mockLLM().withToolCalls([
+ *   { id: 'call-1', name: 'search', input: { query: 'test' } },
+ * ]);
+ * ```
+ */
+export function mockLLM(): MockLLM {
+  const builder = new MockLLMBuilder();
+
+  // Create a Proxy that acts as both builder and built instance.
+  // Builder methods are forwarded to the builder.
+  // ILLM methods (complete, stream, etc.) trigger auto-build on first access.
+  let built: MockLLMInstance | null = null;
+
+  function ensureBuilt(): MockLLMInstance {
+    if (!built) {built = builder.build();}
+    return built;
+  }
+
+  const proxy = new Proxy(builder, {
+    get(target, prop, _receiver) {
+      // Builder methods — return from builder
+      if (prop in target && typeof (target as any)[prop] === 'function') {
+        const method = (target as any)[prop].bind(target);
+        // After calling a builder method, invalidate the built instance
+        return (...args: unknown[]) => {
+          built = null;
+          const result = method(...args);
+          // If the result is the builder itself (chaining), return the proxy
+          if (result === target || (result && typeof result === 'object' && 'respondWith' in result)) {
+            if (result === target) {return proxy;}
+            // Wrap respondWith to return proxy
+            return {
+              respondWith: (...rArgs: unknown[]) => {
+                built = null;
+                (result as any).respondWith(...rArgs);
+                return proxy;
+              },
+            };
+          }
+          return result;
+        };
+      }
+
+      // ILLM instance properties — auto-build
+      const instance = ensureBuilt();
+      // Return functions directly (not bound) to preserve vi.fn() spy identity
+      return (instance as any)[prop];
+    },
+  });
+
+  return proxy as unknown as MockLLM;
+}

package/packages/shared-testing/src/mock-logger.ts

@@ -0,0 +1,97 @@
+/**
+ * @module @kb-labs/shared-testing/mock-logger
+ *
+ * Logger mock with message recording and vi.fn() spies.
+ *
+ * @example
+ * ```typescript
+ * const logger = mockLogger();
+ * logger.info('hello', { extra: 'data' });
+ * logger.error('oops', new Error('fail'));
+ *
+ * expect(logger.messages).toEqual([
+ *   { level: 'info', msg: 'hello', meta: { extra: 'data' } },
+ *   { level: 'error', msg: 'oops', error: expect.any(Error), meta: undefined },
+ * ]);
+ * expect(logger.info).toHaveBeenCalledWith('hello', { extra: 'data' });
+ * ```
+ */
+
+import { vi } from 'vitest';
+import type { ILogger } from '@kb-labs/core-platform';
+
+/** Recorded log entry */
+export interface LogEntry {
+  level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  msg: string;
+  error?: Error;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Mock logger instance with message recording.
+ */
+export interface MockLoggerInstance extends ILogger {
+  /** All recorded log messages */
+  readonly messages: LogEntry[];
+  /** Reset messages and spy call history */
+  reset: () => void;
+}
+
+/**
+ * Create a mock logger with message recording.
+ *
+ * All log methods are vi.fn() spies. Messages are collected
+ * into a `.messages` array for easy assertion.
+ *
+ * Child loggers share the same messages array.
+ *
+ * @example
+ * ```typescript
+ * const logger = mockLogger();
+ * const child = logger.child({ module: 'auth' });
+ *
+ * child.info('user logged in');
+ * expect(logger.messages).toHaveLength(1);
+ * expect(logger.messages[0].msg).toBe('user logged in');
+ * ```
+ */
+export function mockLogger(sharedMessages?: LogEntry[]): MockLoggerInstance {
+  const messages: LogEntry[] = sharedMessages ?? [];
+
+  // trace, debug, info, warn: (message, meta?)
+  function createSimpleLogMethod(level: LogEntry['level']) {
+    return vi.fn((msg: string, meta?: Record<string, unknown>) => {
+      messages.push({ level, msg, meta });
+    });
+  }
+
+  // error, fatal: (message, error?, meta?)
+  function createErrorLogMethod(level: 'error' | 'fatal') {
+    return vi.fn((msg: string, error?: Error, meta?: Record<string, unknown>) => {
+      messages.push({ level, msg, error, meta });
+    });
+  }
+
+  const instance: MockLoggerInstance = {
+    trace: createSimpleLogMethod('trace'),
+    debug: createSimpleLogMethod('debug'),
+    info: createSimpleLogMethod('info'),
+    warn: createSimpleLogMethod('warn'),
+    error: createErrorLogMethod('error'),
+    fatal: createErrorLogMethod('fatal'),
+    child: (_bindings?: Record<string, unknown>) => mockLogger(messages),
+    get messages() { return messages; },
+    reset: () => {
+      messages.length = 0;
+      (instance.trace as ReturnType<typeof vi.fn>).mockClear();
+      (instance.debug as ReturnType<typeof vi.fn>).mockClear();
+      (instance.info as ReturnType<typeof vi.fn>).mockClear();
+      (instance.warn as ReturnType<typeof vi.fn>).mockClear();
+      (instance.error as ReturnType<typeof vi.fn>).mockClear();
+      (instance.fatal as ReturnType<typeof vi.fn>).mockClear();
+    },
+  };
+
+  return instance;
+}

package/packages/shared-testing/src/mock-storage.ts

@@ -0,0 +1,108 @@
+/**
+ * @module @kb-labs/shared-testing/mock-storage
+ *
+ * Virtual filesystem mock for IStorage interface.
+ * All methods are vi.fn() spies.
+ *
+ * @example
+ * ```typescript
+ * const storage = mockStorage({
+ *   'config.json': '{"key": "value"}',
+ *   'data/file.txt': 'hello world',
+ * });
+ *
+ * const content = await storage.read('config.json');
+ * expect(content?.toString()).toBe('{"key": "value"}');
+ * expect(storage.read).toHaveBeenCalledWith('config.json');
+ * ```
+ */
+
+import { vi } from 'vitest';
+import type { IStorage } from '@kb-labs/core-platform';
+
+/**
+ * Mock storage instance with in-memory virtual filesystem.
+ */
+export interface MockStorageInstance extends IStorage {
+  /** Direct access to the virtual filesystem (for assertions) */
+  readonly files: Map<string, Buffer>;
+  /** Reset all files and spy call history */
+  reset: () => void;
+}
+
+/**
+ * Create a mock storage with in-memory virtual filesystem.
+ *
+ * @param initial - Optional initial files. Keys are paths, values are content (string or Buffer).
+ *
+ * @example
+ * ```typescript
+ * const storage = mockStorage({
+ *   'data.json': JSON.stringify({ items: [] }),
+ *   'binary.dat': Buffer.from([0x00, 0x01]),
+ * });
+ *
+ * // Write and read
+ * await storage.write('new.txt', Buffer.from('hello'));
+ * expect(await storage.exists('new.txt')).toBe(true);
+ *
+ * // List files
+ * const files = await storage.list('');
+ * expect(files).toContain('new.txt');
+ * ```
+ */
+export function mockStorage(initial?: Record<string, string | Buffer>): MockStorageInstance {
+  const files = new Map<string, Buffer>();
+
+  // Populate initial files
+  if (initial) {
+    for (const [path, content] of Object.entries(initial)) {
+      files.set(path, typeof content === 'string' ? Buffer.from(content) : content);
+    }
+  }
+
+  const readFn = vi.fn(async (path: string): Promise<Buffer | null> => {
+    return files.get(path) ?? null;
+  });
+
+  const writeFn = vi.fn(async (path: string, data: Buffer): Promise<void> => {
+    files.set(path, data);
+  });
+
+  const deleteFn = vi.fn(async (path: string): Promise<void> => {
+    files.delete(path);
+  });
+
+  const listFn = vi.fn(async (prefix: string): Promise<string[]> => {
+    const result: string[] = [];
+    for (const path of files.keys()) {
+      if (path.startsWith(prefix)) {
+        result.push(path);
+      }
+    }
+    return result.sort();
+  });
+
+  const existsFn = vi.fn(async (path: string): Promise<boolean> => {
+    return files.has(path);
+  });
+
+  const instance: MockStorageInstance = {
+    read: readFn,
+    write: writeFn,
+    delete: deleteFn,
+    list: listFn,
+    exists: existsFn,
+    get files() { return files; },
+    reset: () => {
+      files.clear();
+      readFn.mockClear();
+      writeFn.mockClear();
+      deleteFn.mockClear();
+      listFn.mockClear();
+      existsFn.mockClear();
+    },
+  };
+
+  return instance;
+}