@alumbwe/anvil 1.0.20 → 1.0.22

package/vendor/@anvil/common/src/testing/mocks/analytics.ts

@@ -0,0 +1,261 @@
+/**
+ * Typed analytics mock factory for testing.
+ *
+ * Provides type-safe mocks for analytics functions used throughout the codebase.
+ * Helps avoid the need for `as any` casts when mocking analytics in tests.
+ *
+ * @example
+ * ```typescript
+ * import { createMockAnalytics, setupAnalyticsMocks } from '@anvil/common/testing/mocks/analytics'
+ *
+ * // Option 1: Create mock object
+ * const analytics = createMockAnalytics()
+ * someFunction({ trackEvent: analytics.trackEvent })
+ *
+ * // Option 2: Setup spies on actual module
+ * const spies = setupAnalyticsMocks()
+ * await runTest()
+ * expect(spies.trackEvent).toHaveBeenCalledWith('event_name', { prop: 'value' })
+ * spies.restore()
+ * ```
+ */
+
+import { mock, spyOn } from 'bun:test'
+
+import type { Mock } from 'bun:test'
+
+/**
+ * Properties that can be tracked with an event.
+ */
+export type EventProperties = Record<string, unknown>
+
+/**
+ * Signature for the trackEvent function.
+ */
+export type TrackEventFn = (
+  eventName: string,
+  properties?: EventProperties,
+) => void
+
+/**
+ * Signature for the flushAnalytics function.
+ */
+export type FlushAnalyticsFn = () => Promise<void>
+
+/**
+ * Signature for the identifyUser function.
+ */
+export type IdentifyUserFn = (
+  userId: string,
+  traits?: Record<string, unknown>,
+) => void
+
+/**
+ * Interface for the complete mock analytics object.
+ */
+export interface MockAnalytics {
+  /** Track a named event with optional properties */
+  trackEvent: Mock<TrackEventFn>
+  /** Flush pending analytics events */
+  flushAnalytics: Mock<FlushAnalyticsFn>
+  /** Identify a user with optional traits */
+  identifyUser: Mock<IdentifyUserFn>
+}
+
+/**
+ * Tracked event entry for inspection.
+ */
+export interface TrackedEvent {
+  name: string
+  properties?: EventProperties
+  timestamp: Date
+}
+
+/**
+ * Options for creating mock analytics.
+ */
+export interface CreateMockAnalyticsOptions {
+  /**
+   * Whether to capture tracked events for later inspection.
+   * @default false
+   */
+  captureEvents?: boolean
+}
+
+/**
+ * Creates a type-safe mock analytics object for testing.
+ *
+ * @param options - Configuration options
+ * @returns A mock analytics object with all methods as tracked mocks
+ *
+ * @example
+ * ```typescript
+ * const analytics = createMockAnalytics()
+ *
+ * // Pass to function under test
+ * await processPayment({ analytics })
+ *
+ * // Verify events were tracked
+ * expect(analytics.trackEvent).toHaveBeenCalledWith('payment_processed', {
+ *   amount: 100,
+ *   currency: 'USD',
+ * })
+ * ```
+ */
+export function createMockAnalytics(
+  options: CreateMockAnalyticsOptions = {},
+): MockAnalytics {
+  return {
+    trackEvent: mock(() => {}),
+    flushAnalytics: mock(async () => {}),
+    identifyUser: mock(() => {}),
+  }
+}
+
+/**
+ * Result of creating mock analytics with event capture.
+ */
+export interface MockAnalyticsWithCapture {
+  /** The mock analytics object */
+  analytics: MockAnalytics
+  /** Array of all tracked events */
+  events: TrackedEvent[]
+  /** Clear all captured events */
+  clearEvents: () => void
+  /** Get events by name */
+  getEventsByName: (name: string) => TrackedEvent[]
+  /** Check if an event was tracked */
+  hasEvent: (name: string) => boolean
+  /** Get the last event tracked */
+  getLastEvent: () => TrackedEvent | undefined
+}
+
+/**
+ * Creates mock analytics that captures all tracked events for inspection.
+ *
+ * @returns An object containing the analytics mock and utilities for inspection
+ *
+ * @example
+ * ```typescript
+ * const { analytics, events, getEventsByName } = createMockAnalyticsWithCapture()
+ *
+ * await runUserFlow({ analytics })
+ *
+ * // Check events were tracked in order
+ * expect(events.map(e => e.name)).toEqual([
+ *   'flow_started',
+ *   'step_completed',
+ *   'flow_finished',
+ * ])
+ *
+ * // Check specific event properties
+ * const completionEvents = getEventsByName('step_completed')
+ * expect(completionEvents[0].properties).toMatchObject({ stepId: 'step1' })
+ * ```
+ */
+export function createMockAnalyticsWithCapture(): MockAnalyticsWithCapture {
+  const events: TrackedEvent[] = []
+
+  const analytics: MockAnalytics = {
+    trackEvent: mock((name: string, properties?: EventProperties) => {
+      events.push({
+        name,
+        properties,
+        timestamp: new Date(),
+      })
+    }),
+    flushAnalytics: mock(async () => {}),
+    identifyUser: mock(() => {}),
+  }
+
+  return {
+    analytics,
+    events,
+    clearEvents: () => {
+      events.length = 0
+    },
+    getEventsByName: (name: string) => events.filter((e) => e.name === name),
+    hasEvent: (name: string) => events.some((e) => e.name === name),
+    getLastEvent: () => events[events.length - 1],
+  }
+}
+
+/**
+ * Result of setting up analytics spies on the actual module.
+ */
+export interface AnalyticsSpies {
+  /** Spy on trackEvent */
+  trackEvent: ReturnType<typeof spyOn>
+  /** Spy on flushAnalytics */
+  flushAnalytics: ReturnType<typeof spyOn>
+  /** Restore all spies */
+  restore: () => void
+  /** Clear all spy call history */
+  clear: () => void
+}
+
+/**
+ * Sets up spies on the analytics module.
+ * Use this when you need to spy on the actual module rather than inject a mock.
+ *
+ * @param analyticsModule - The analytics module to spy on
+ * @returns Object containing the spies and cleanup utilities
+ *
+ * @example
+ * ```typescript
+ * import * as analytics from '@anvil/common/analytics'
+ *
+ * describe('my test', () => {
+ *   let analyticsSpy: AnalyticsSpies
+ *
+ *   beforeEach(() => {
+ *     analyticsSpy = setupAnalyticsMocks(analytics)
+ *   })
+ *
+ *   afterEach(() => {
+ *     analyticsSpy.restore()
+ *   })
+ *
+ *   it('tracks the event', async () => {
+ *     await doSomething()
+ *     expect(analyticsSpy.trackEvent).toHaveBeenCalledWith('something_done')
+ *   })
+ * })
+ * ```
+ */
+export function setupAnalyticsMocks(analyticsModule: {
+  trackEvent: TrackEventFn
+  flushAnalytics: FlushAnalyticsFn
+}): AnalyticsSpies {
+  const trackEventSpy = spyOn(analyticsModule, 'trackEvent').mockImplementation(
+    () => {},
+  )
+  const flushAnalyticsSpy = spyOn(
+    analyticsModule,
+    'flushAnalytics',
+  ).mockImplementation(async () => {})
+
+  return {
+    trackEvent: trackEventSpy,
+    flushAnalytics: flushAnalyticsSpy,
+    restore: () => {
+      trackEventSpy.mockRestore()
+      flushAnalyticsSpy.mockRestore()
+    },
+    clear: () => {
+      trackEventSpy.mockClear()
+      flushAnalyticsSpy.mockClear()
+    },
+  }
+}
+
+/**
+ * Restores all mock methods on an analytics object.
+ *
+ * @param analytics - The mock analytics to restore
+ */
+export function restoreMockAnalytics(analytics: MockAnalytics): void {
+  analytics.trackEvent.mockRestore()
+  analytics.flushAnalytics.mockRestore()
+  analytics.identifyUser.mockRestore()
+}

package/vendor/@anvil/common/src/testing/mocks/child-process.ts

@@ -0,0 +1,93 @@
+/** Typed child process mock for testing code that spawns processes. */
+
+import { EventEmitter } from 'events'
+
+import { mock } from 'bun:test'
+
+import type { Mock } from 'bun:test'
+import type { ChildProcess } from 'child_process'
+
+/** Mock child process with typed stdout/stderr EventEmitters. */
+export interface MockChildProcess extends EventEmitter {
+  stdout: EventEmitter
+  stderr: EventEmitter
+  pid: number
+  killed: boolean
+  kill: Mock<(signal?: string) => boolean>
+}
+
+/** Creates a typed mock child process with EventEmitter-based stdout/stderr. */
+export function createMockChildProcess(): MockChildProcess {
+  const mockProcess = new EventEmitter() as MockChildProcess
+  mockProcess.stdout = new EventEmitter()
+  mockProcess.stderr = new EventEmitter()
+  mockProcess.pid = Math.floor(Math.random() * 10000)
+  mockProcess.killed = false
+  mockProcess.kill = mock((signal?: string) => {
+    mockProcess.killed = true
+    mockProcess.emit('close', signal === 'SIGKILL' ? 137 : 0)
+    return true
+  })
+  return mockProcess
+}
+
+/** Result type for code search tool output. */
+export interface CodeSearchResult {
+  stdout?: string
+  stderr?: string
+  message?: string
+  errorMessage?: string
+}
+
+/** Typed accessor for code search result value. */
+export function asCodeSearchResult(result: unknown): CodeSearchResult {
+  if (
+    result &&
+    typeof result === 'object' &&
+    'type' in result &&
+    result.type === 'json' &&
+    'value' in result
+  ) {
+    return result.value as CodeSearchResult
+  }
+  return {}
+}
+
+/** Creates a mock spawn function that returns the provided mock process. */
+export function createMockSpawn(
+  mockProcess: MockChildProcess,
+): Mock<(command: string, args: string[], options?: object) => ChildProcess> {
+  return mock(() => mockProcess as unknown as ChildProcess)
+}
+
+/** Helper to create ripgrep JSON match output. */
+export function createRgJsonMatch(
+  filePath: string,
+  lineNumber: number,
+  lineText: string,
+): string {
+  return JSON.stringify({
+    type: 'match',
+    data: {
+      path: { text: filePath },
+      lines: { text: lineText },
+      line_number: lineNumber,
+    },
+  })
+}
+
+/** Helper to create ripgrep JSON context output (for -A, -B, -C flags). */
+export function createRgJsonContext(
+  filePath: string,
+  lineNumber: number,
+  lineText: string,
+): string {
+  return JSON.stringify({
+    type: 'context',
+    data: {
+      path: { text: filePath },
+      lines: { text: lineText },
+      line_number: lineNumber,
+    },
+  })
+}

package/vendor/@anvil/common/src/testing/mocks/crypto.ts

@@ -0,0 +1,218 @@
+/**
+ * Typed crypto mock factory for testing.
+ *
+ * Provides type-safe mocks for crypto functions, particularly randomUUID.
+ * Makes tests deterministic by returning predictable UUIDs.
+ *
+ * @example
+ * ```typescript
+ * import { setupCryptoMocks, createMockUuid } from '@anvil/common/testing/mocks/crypto'
+ *
+ * // Setup deterministic UUIDs
+ * const spies = setupCryptoMocks()
+ * await runTest()
+ * spies.restore()
+ *
+ * // Or create specific UUIDs
+ * const uuid = createMockUuid('test-prefix')
+ * // Returns: 'test-prefix-0000-0000-0000-000000000000'
+ * ```
+ */
+
+import { spyOn } from 'bun:test'
+
+/**
+ * A valid UUID v4 format string.
+ */
+export type UUID = `${string}-${string}-${string}-${string}-${string}`
+
+/**
+ * Options for setting up crypto mocks.
+ */
+export interface SetupCryptoMocksOptions {
+  /**
+   * A prefix to use for generated UUIDs.
+   * The format will be: `{prefix}-0000-0000-0000-000000000000`
+   * @default 'mock-uuid'
+   */
+  prefix?: string
+
+  /**
+   * Whether to generate sequential UUIDs.
+   * If true, each call returns a different UUID: mock-uuid-1, mock-uuid-2, etc.
+   * @default false
+   */
+  sequential?: boolean
+
+  /**
+   * A specific list of UUIDs to return in order.
+   * If provided, UUIDs are returned from this list in sequence.
+   * When exhausted, falls back to default behavior.
+   */
+  uuids?: UUID[]
+}
+
+/**
+ * Result of setting up crypto mocks.
+ */
+export interface CryptoMockSpies {
+  /** The spy on randomUUID */
+  randomUUID: ReturnType<typeof spyOn>
+  /** Restore the original implementation */
+  restore: () => void
+  /** Clear call history */
+  clear: () => void
+  /** Get the current call count */
+  getCallCount: () => number
+}
+
+/**
+ * Creates a deterministic mock UUID with a given prefix.
+ *
+ * @param prefix - The prefix for the UUID
+ * @param index - Optional index for sequential UUIDs
+ * @returns A valid UUID-format string
+ *
+ * @example
+ * ```typescript
+ * createMockUuid('test')
+ * // Returns: 'test-uuid-0000-0000-000000000000'
+ *
+ * createMockUuid('test', 5)
+ * // Returns: 'test-uuid-0000-0005-000000000000'
+ * ```
+ */
+export function createMockUuid(prefix: string, index?: number): UUID {
+  const indexStr =
+    index !== undefined ? String(index).padStart(12, '0') : '000000000000'
+  return `${prefix}-0000-0000-0000-${indexStr}` as UUID
+}
+
+/**
+ * Sets up a spy on crypto.randomUUID with deterministic behavior.
+ *
+ * @param options - Configuration options
+ * @returns Object containing the spy and cleanup utilities
+ *
+ * @example
+ * ```typescript
+ * describe('my test', () => {
+ *   let cryptoSpies: CryptoMockSpies
+ *
+ *   beforeEach(() => {
+ *     cryptoSpies = setupCryptoMocks({ prefix: 'test' })
+ *   })
+ *
+ *   afterEach(() => {
+ *     cryptoSpies.restore()
+ *   })
+ *
+ *   it('creates deterministic IDs', async () => {
+ *     const result = await createSomething()
+ *     expect(result.id).toBe('test-0000-0000-0000-000000000000')
+ *   })
+ * })
+ * ```
+ */
+export function setupCryptoMocks(
+  options: SetupCryptoMocksOptions = {},
+): CryptoMockSpies {
+  const { prefix = 'mock-uuid', sequential = false, uuids = [] } = options
+
+  let callCount = 0
+
+  const randomUUIDSpy = spyOn(crypto, 'randomUUID').mockImplementation(() => {
+    const currentIndex = callCount
+    callCount++
+
+    // First try to return from the provided list
+    if (currentIndex < uuids.length) {
+      return uuids[currentIndex]
+    }
+
+    // Then fall back to generated UUIDs
+    if (sequential) {
+      return createMockUuid(prefix, currentIndex)
+    }
+
+    return createMockUuid(prefix)
+  })
+
+  return {
+    randomUUID: randomUUIDSpy,
+    restore: () => {
+      randomUUIDSpy.mockRestore()
+    },
+    clear: () => {
+      callCount = 0
+      randomUUIDSpy.mockClear()
+    },
+    getCallCount: () => callCount,
+  }
+}
+
+/**
+ * Sets up crypto mocks that return specific UUIDs in sequence.
+ * Useful when you need specific IDs for assertions.
+ *
+ * @param uuids - The UUIDs to return in order
+ * @returns Object containing the spy and cleanup utilities
+ *
+ * @example
+ * ```typescript
+ * const spies = setupSequentialCryptoMocks([
+ *   'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+ *   'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
+ * ])
+ *
+ * crypto.randomUUID() // 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
+ * crypto.randomUUID() // 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'
+ * crypto.randomUUID() // 'mock-uuid-0000-0000-0000-000000000002' (fallback)
+ * ```
+ */
+export function setupSequentialCryptoMocks(uuids: UUID[]): CryptoMockSpies {
+  return setupCryptoMocks({ uuids, sequential: true })
+}
+
+/**
+ * A set of commonly used test UUIDs for consistency across tests.
+ */
+export const TEST_UUIDS = {
+  /** Default user ID for tests */
+  USER: 'test-user-0000-0000-000000000001' as UUID,
+  /** Default session ID for tests */
+  SESSION: 'test-sess-0000-0000-000000000001' as UUID,
+  /** Default run ID for tests */
+  RUN: 'test-run0-0000-0000-000000000001' as UUID,
+  /** Default step ID for tests */
+  STEP: 'test-step-0000-0000-000000000001' as UUID,
+  /** Default message ID for tests */
+  MESSAGE: 'test-msg0-0000-0000-000000000001' as UUID,
+  /** Default agent ID for tests */
+  AGENT: 'test-agnt-0000-0000-000000000001' as UUID,
+} as const
+
+/**
+ * Creates a UUID generator that returns sequential UUIDs with a prefix.
+ * Useful for generating multiple related IDs.
+ *
+ * @param prefix - The prefix for generated UUIDs
+ * @returns A function that generates sequential UUIDs
+ *
+ * @example
+ * ```typescript
+ * const generateId = createUuidGenerator('item')
+ *
+ * generateId() // 'item-uuid-0000-0000-000000000000'
+ * generateId() // 'item-uuid-0000-0001-000000000000'
+ * generateId() // 'item-uuid-0000-0002-000000000000'
+ * ```
+ */
+export function createUuidGenerator(prefix: string): () => UUID {
+  let index = 0
+  return () => {
+    const uuid = createMockUuid(prefix, index)
+    index++
+    return uuid
+  }
+}