@alumbwe/anvil 1.0.20 → 1.0.22

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

@@ -0,0 +1,351 @@
+# 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

@@ -0,0 +1,169 @@
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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
+}