@alumbwe/anvil 1.0.42 → 1.0.49

package/vendor/@anvil/common/src/testing/TESTING_PATTERNS.md

@@ -1,351 +0,0 @@
-# Testing Patterns Guide
-
-This guide documents best practices for writing tests in the Anvil codebase, based on lessons learned from buffbench runs and production issues.
-
-## Table of Contents
-
-1. [Mock Cleanup](#mock-cleanup)
-2. [Type-Safe Mocks](#type-safe-mocks)
-3. [Assertion Best Practices](#assertion-best-practices)
-4. [Test Isolation](#test-isolation)
-5. [Common Patterns](#common-patterns)
-
----
-
-## Mock Cleanup
-
-### ❌ DON'T: Use `afterAll` for mock restoration
-
-```typescript
-// BAD: Mocks leak between tests
-afterAll(() => {
-  mockSpy.mockRestore()
-})
-```
-
-### ✅ DO: Use `afterEach` for mock restoration
-
-```typescript
-// GOOD: Each test starts with clean state
-afterEach(() => {
-  mockSpy.mockRestore()
-})
-```
-
-**Why**: `afterAll` runs only once after all tests complete. If one test modifies mock behavior, subsequent tests inherit that state, causing flaky tests and hard-to-debug failures.
-
----
-
-## Type-Safe Mocks
-
-### ❌ DON'T: Use `as any` casts for mocks
-
-```typescript
-// BAD: Type safety lost, bugs hide
-spyOn(db, 'insert').mockReturnValue({
-  values: mock(() => Promise.resolve({ id: 'test-id' })),
-} as any)
-```
-
-### ✅ DO: Use typed mock factories
-
-```typescript
-// GOOD: Type-safe, reusable, documented
-import { setupDbSpies } from '@anvil/common/testing/mocks'
-
-const dbSpies = setupDbSpies(db, { defaultInsertId: 'test-id' })
-// dbSpies.insert is properly typed
-```
-
-### Available Mock Factories
-
-```typescript
-import {
-  // Logger mocks
-  createMockLogger,
-  createMockLoggerWithCapture,
-
-  // Analytics mocks
-  createMockAnalytics,
-  setupAnalyticsMocks,
-
-  // Database mocks
-  setupDbSpies,
-  createMockDbOperations,
-
-  // Crypto mocks
-  setupCryptoMocks,
-  createMockUuid,
-
-  // Stream mocks
-  createToolCallChunk,
-  createMockStream,
-} from '@anvil/common/testing/mocks'
-```
-
----
-
-## Assertion Best Practices
-
-### ❌ DON'T: Assert on raw strings with formatting
-
-```typescript
-// BAD: Brittle to whitespace/format changes
-expect(JSON.stringify(result)).toContain('"role":"assistant"')
-```
-
-### ✅ DO: Parse JSON and assert on structured fields
-
-```typescript
-// GOOD: Robust to formatting changes
-const parsed = JSON.parse(result)
-expect(parsed.role).toBe('assistant')
-expect(parsed.content).toHaveLength(1)
-```
-
-### ❌ DON'T: Use substring checks for role validation
-
-```typescript
-// BAD: False positives possible
-expect(serializedHistory).toContain('assistant')
-```
-
-### ✅ DO: Check exact field values
-
-```typescript
-// GOOD: Precise and reliable
-expect(messages.some((m) => m.role === 'assistant')).toBe(true)
-```
-
----
-
-## Test Isolation
-
-### ❌ DON'T: Share mutable state between tests
-
-```typescript
-// BAD: Tests affect each other
-let sharedState = { count: 0 }
-
-it('test 1', () => {
-  sharedState.count++
-  expect(sharedState.count).toBe(1)
-})
-
-it('test 2', () => {
-  // Fails if test 1 runs first!
-  expect(sharedState.count).toBe(0)
-})
-```
-
-### ✅ DO: Reset state in `beforeEach`
-
-```typescript
-// GOOD: Each test has fresh state
-let state: { count: number }
-
-beforeEach(() => {
-  state = { count: 0 }
-})
-
-it('test 1', () => {
-  state.count++
-  expect(state.count).toBe(1)
-})
-
-it('test 2', () => {
-  expect(state.count).toBe(0) // Works!
-})
-```
-
----
-
-## Common Patterns
-
-### Testing with Mock Logger
-
-```typescript
-import { createMockLoggerWithCapture } from '@anvil/common/testing/mocks'
-
-describe('myFunction', () => {
-  it('logs errors appropriately', async () => {
-    const { logger, getByLevel } = createMockLoggerWithCapture()
-
-    await myFunction({ logger })
-
-    const errors = getByLevel('error')
-    expect(errors).toHaveLength(0) // No errors logged
-  })
-})
-```
-
-### Testing with Mock Analytics
-
-```typescript
-import { setupAnalyticsMocks } from '@anvil/common/testing/mocks'
-import * as analytics from '@anvil/common/analytics'
-
-describe('tracking', () => {
-  let analyticsSpy: AnalyticsSpies
-
-  beforeEach(() => {
-    analyticsSpy = setupAnalyticsMocks(analytics)
-  })
-
-  afterEach(() => {
-    analyticsSpy.restore()
-  })
-
-  it('tracks the event', async () => {
-    await doSomething()
-    expect(analyticsSpy.trackEvent).toHaveBeenCalledWith('something_done', {
-      prop: 'value',
-    })
-  })
-})
-```
-
-### Testing with Deterministic UUIDs
-
-```typescript
-import { setupCryptoMocks } from '@anvil/common/testing/mocks'
-
-describe('ID generation', () => {
-  let cryptoSpies: CryptoMockSpies
-
-  beforeEach(() => {
-    cryptoSpies = setupCryptoMocks({ prefix: 'test', sequential: true })
-  })
-
-  afterEach(() => {
-    cryptoSpies.restore()
-  })
-
-  it('creates items with sequential IDs', async () => {
-    const item1 = await createItem()
-    const item2 = await createItem()
-
-    expect(item1.id).toBe('test-0000-0000-0000-000000000000')
-    expect(item2.id).toBe('test-0000-0000-0000-000000000001')
-  })
-})
-```
-
-### Testing LLM Streams
-
-```typescript
-import {
-  createMockStream,
-  createTextChunk,
-  createToolCallChunk,
-  collectStreamChunks,
-} from '@anvil/common/testing/mocks'
-
-describe('stream processing', () => {
-  it('handles tool calls', async () => {
-    const stream = createMockStream([
-      createTextChunk('Analyzing...'),
-      createToolCallChunk('read_files', { paths: ['test.ts'] }),
-      createTextChunk('Done!'),
-      createToolCallChunk('end_turn', {}),
-    ])
-
-    const { chunks } = await collectStreamChunks(stream)
-
-    const toolCalls = chunks.filter((c) => c.type === 'tool-call')
-    expect(toolCalls).toHaveLength(2)
-    expect(toolCalls[0].toolName).toBe('read_files')
-  })
-})
-```
-
-### Testing Database Operations
-
-```typescript
-import { setupDbSpies } from '@anvil/common/testing/mocks'
-import db from '@anvil/internal/db'
-
-describe('data layer', () => {
-  let dbSpies: DbSpies
-
-  beforeEach(() => {
-    dbSpies = setupDbSpies(db, { defaultInsertId: 'new-record-id' })
-  })
-
-  afterEach(() => {
-    dbSpies.restore()
-  })
-
-  it('inserts a new record', async () => {
-    const result = await createRecord({ name: 'Test' })
-
-    expect(dbSpies.insert).toHaveBeenCalled()
-    expect(result.id).toBe('new-record-id')
-  })
-})
-```
-
----
-
-## Additional Lessons from Buffbench
-
-### Cross-Browser Styles
-
-When adding custom scrollbar styles, always include Firefox support:
-
-```css
-/* WebKit (Chrome, Safari, Edge) */
-::-webkit-scrollbar {
-  width: 6px;
-}
-
-/* Firefox */
-scrollbar-width: thin;
-scrollbar-color: hsl(var(--border) / 0.6) transparent;
-```
-
-### Duplicate Code Detection
-
-Before adding utility functions, search for existing implementations:
-
-```bash
-# Search for similar functions
-rg "filterOutSystemRole\|filterSystem" --type ts
-```
-
-### Shared Mock File Context
-
-Don't duplicate mock file context creators. Use the shared one:
-
-```typescript
-import { mockFileContext } from '@anvil/common/testing/fixtures/agent-runtime'
-
-// Don't create a new one in each test file
-```
-
-### Error Path Coverage
-
-Always add tests for error scenarios:
-
-```typescript
-it('handles API errors gracefully', async () => {
-  mockApi.mockRejectedValueOnce(new Error('Network error'))
-
-  const result = await fetchData()
-
-  expect(result.error).toBe('Network error')
-})
-```
-
----
-
-## Migration Checklist
-
-When updating tests to use these patterns:
-
-1. [ ] Replace `as any` casts with typed mock factories
-2. [ ] Move mock restoration from `afterAll` to `afterEach`
-3. [ ] Replace string assertions with structured assertions
-4. [ ] Use shared fixtures instead of duplicating mock data
-5. [ ] Add error path coverage if missing
-6. [ ] Ensure deterministic IDs with `setupCryptoMocks`

package/vendor/@anvil/common/src/testing/anvil-offer-invariants.ts

@@ -1,169 +0,0 @@
-/**
- * One rule, checked the same way on every surface: **if a picker can OFFER a
- * anvil model row, every gate that row then passes through must accept it.**
- *
- * Anvil model ids fan out across several hand-kept lists — the per-tier
- * picker catalogs, the session-admission sets, the free-mode agent allowlist,
- * and each surface's own request validator. They are separate on purpose (a
- * model can be retired from a picker while live sessions keep running on it),
- * so nothing stops one from moving without the others. When they drift in the
- * offer→gate direction the user sees a row they cannot use: Anvil Desktop
- * shipped the earned GLM 5.2 row while its `/api/thread/:id/agent` route still
- * validated against `ANVIL_MODELS` (which excludes GLM by design), so every
- * user who earned the reward got 400 "invalid model" when they picked it.
- *
- * Drift the OTHER way is fine and deliberate — an id that is acceptable but not
- * offered is exactly how a staged retirement works — so this only ever checks
- * offered ⊆ accepted.
- *
- * Each surface owns its offer set (they live in the desktop/cli/web packages,
- * which `common` cannot import), so each calls `anvilOfferViolations` from
- * its own test with its own rows. Keeping the CHECKS here is what makes a new
- * gate apply to every surface at once.
- */
-
-import {
-  FREE_MODE_AGENT_MODELS,
-  ANVIL_ROOT_AGENT_IDS,
-} from '../constants/free-agents'
-import {
-  getAnvilModel,
-  getAnvilWebModel,
-  isAnvilSessionModelAllowedForAccessTier,
-  isAnvilSessionModelId,
-  resolveAnvilSessionModelForAccessTier,
-} from '../constants/anvil-models'
-
-import type { AnvilAccessTier } from '../constants/anvil-models'
-
-/** Which catalog the surface reads a row's name/tagline/badges out of. A
- *  surface that renders through the wrong one shows a fallback model's label on
- *  the row (both getters degrade to DeepSeek Flash rather than throwing). */
-export type AnvilCatalogSource = 'supported' | 'web'
-
-export interface AnvilOfferSurface {
-  /** Names the surface in failure messages, e.g. 'anvil-desktop picker (full)'. */
-  surface: string
-  /** The tier whose rows `offered` describes — gates are tier-sensitive. */
-  accessTier: AnvilAccessTier
-  /** Every model id this surface can put in front of a user on that tier,
-   *  INCLUDING earned/unlocked rows like the GLM referral reward. */
-  offered: readonly string[]
-  /** The surface's own request validator, if it has one (the desktop route's
-   *  `isModelForHarness`, the web picker's selectable filter, …). */
-  accepts?: (model: string) => boolean
-  /** The free-mode root agent(s) this surface's turns run under. One id, or
-   *  several when the surface has per-execution-mode roots. */
-  rootAgentIdFor?: (model: string) => string | readonly string[]
-  /** Catalog the surface renders from. Omit to skip the label check. */
-  catalog?: AnvilCatalogSource
-}
-
-function rootAgentIds(
-  surface: AnvilOfferSurface,
-  model: string,
-): readonly string[] {
-  if (!surface.rootAgentIdFor) return []
-  const ids = surface.rootAgentIdFor(model)
-  return typeof ids === 'string' ? [ids] : ids
-}
-
-/**
- * Every way `model` is offerable-but-unusable on this surface, as sentences a
- * failing test can print verbatim. Empty array means the row is good.
- */
-function violationsForModel(
-  surface: AnvilOfferSurface,
-  model: string,
-): string[] {
-  const where = `${surface.surface}: ${model}`
-  const out: string[] = []
-
-  // 1. the session layer has to know the id at all, on any tier
-  if (!isAnvilSessionModelId(model)) {
-    // everything below is derived from the same catalogs, so one unknown id
-    // would otherwise produce five near-identical lines
-    return [`${where} is offered but is not a anvil session model id`]
-  }
-
-  // 2. …and admit it for THIS tier, or admission answers model_not_allowed
-  if (!isAnvilSessionModelAllowedForAccessTier(model, surface.accessTier)) {
-    out.push(
-      `${where} is offered to the ${surface.accessTier} tier, which session admission does not allow it on`,
-    )
-  }
-
-  // 3. a resolver that silently swaps the pick is as bad as a refusal: the user
-  //    picks GLM, the turn runs on DeepSeek, and nothing says why
-  const resolved = resolveAnvilSessionModelForAccessTier(
-    model,
-    surface.accessTier,
-  )
-  if (resolved !== model) {
-    out.push(
-      `${where} is offered but resolveAnvilSessionModelForAccessTier coerces it to ${resolved}`,
-    )
-  }
-
-  // 4. the surface's own validator — the check the GLM 400 needed
-  if (surface.accepts && !surface.accepts(model)) {
-    out.push(`${where} is offered but the surface's own validator rejects it`)
-  }
-
-  // 5. free mode charges/403s per (agent, model) pair, so the root this
-  //    surface runs turns under must allow the model, and must itself be a
-  //    registered root or its subagents 403 with free_mode_invalid_agent_hierarchy
-  const roots = rootAgentIds(surface, model)
-  if (surface.rootAgentIdFor && roots.length === 0) {
-    // a resolver that answers "no root" for an offered model is a wiring error, and
-    // silently running no root checks is exactly how this whole class of bug hides
-    out.push(`${where} is offered but resolves to no free-mode root agent`)
-  }
-  for (const rootId of roots) {
-    const allowed = FREE_MODE_AGENT_MODELS[rootId]
-    if (!allowed) {
-      out.push(
-        `${where} runs under free-mode root ${rootId}, which is not in FREE_MODE_AGENT_MODELS`,
-      )
-      continue
-    }
-    if (!allowed.has(model)) {
-      out.push(
-        `${where} runs under free-mode root ${rootId}, whose allowlist does not include it (free_mode_invalid_agent_model)`,
-      )
-    }
-    if (!ANVIL_ROOT_AGENT_IDS.some((id) => id === rootId)) {
-      out.push(
-        `${where} runs under free-mode root ${rootId}, which is missing from ANVIL_ROOT_AGENT_IDS (its subagents would 403)`,
-      )
-    }
-  }
-
-  // 6. the row has to render as itself rather than as the fallback's label
-  if (surface.catalog) {
-    const row =
-      surface.catalog === 'web'
-        ? getAnvilWebModel(model)
-        : getAnvilModel(model)
-    if (row.id !== model) {
-      out.push(
-        `${where} is offered but the ${surface.catalog} catalog has no row for it, so it renders as ${row.id}`,
-      )
-    }
-  }
-
-  return out
-}
-
-/** Every offer→gate violation on a surface. Assert `toEqual([])`: the strings
- *  are the failure message. */
-export function anvilOfferViolations(
-  surface: AnvilOfferSurface,
-): string[] {
-  // an empty offer set passes every check below while meaning the test wired
-  // itself to the wrong list, which is the one failure mode a green run hides
-  if (surface.offered.length === 0) {
-    return [`${surface.surface}: offers no models at all — check the test wiring`]
-  }
-  return surface.offered.flatMap((model) => violationsForModel(surface, model))
-}

package/vendor/@anvil/common/src/testing/errors.ts

@@ -1,33 +0,0 @@
-/**
- * Shared error helper utilities for tests.
- * These provide typed ways to create errors with additional properties
- * like `code` (for Node.js filesystem errors) and `constraint` (for Postgres errors).
- */
-
-export interface NodeError extends Error {
-  code?: string
-}
-
-export interface PostgresError extends Error {
-  code: string
-  constraint?: string
-}
-
-export const createNodeError = (message: string, code: string): NodeError => {
-  const error: NodeError = new Error(message)
-  error.code = code
-  return error
-}
-
-export const createPostgresError = (
-  message: string,
-  code: string,
-  constraint?: string,
-): PostgresError => {
-  const error = new Error(message) as PostgresError
-  error.code = code
-  if (constraint !== undefined) {
-    error.constraint = constraint
-  }
-  return error
-}