opencode-swarm 7.195.0 → 7.197.0

package/.opencode/skills/writing-tests/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: writing-tests
-audience: swarm-plugin
 description: >
   Guidelines for writing, organizing, and maintaining tests in the opencode-swarm repository.
   Covers framework rules (bun:test), mock isolation, CI pipeline structure, file placement,
   and anti-patterns that break cross-platform CI. Load this skill before writing or modifying
   any test file.
+metadata:
+  audience: swarm-plugin
 ---
 
 # Writing Tests for opencode-swarm
@@ -156,138 +157,7 @@ When test files pass individually but fail when run together, follow this protoc
    - Symptom: `expect(mockFn).not.toHaveBeenCalled()` fails because the real function was called
 6. **Fix path**: Migrate the affected test file to the `_internals` DI seam pattern documented above (opencode-swarm repository contributors also have a dedicated mock-to-internals-migration skill that walks the recipe in depth). This eliminates both the `vi.mock()` call and the closure capture surface area. **Exception — reference-captured functions**: if the source code passes a function as a direct argument or captures it in a closure at module scope (e.g., `transactFile(path, readKnowledge, ...)`), the reference bypasses `_internals` entirely — mutating `_internals.readKnowledge` changes only the object property, not the module-scope binding the source already holds. Migrating to `_internals` does not help. In that case, test via observable outcomes (e.g., run concurrent callers and assert on final persisted state).
 
-## Two-Tier Mock Convention
-
-The codebase uses a two-tier strategy for mock isolation, plus a zero-mock testing pattern:
-
-### Tier 0: _test_exports Pure Function Testing (Zero Mocks)
-
-When a module contains internal utility functions (formatters, normalizers, transformers) that don't need external dependencies, export them via a `_test_exports` object for direct unit testing. This avoids `mock.module` entirely and produces tests that are deterministic, fast, and immune to Bun's cross-file mock leakage:
-
-```typescript
-// In source file (src/tools/formatter.ts)
-function formatEntry(entry: SomeType): string {
-  // internal implementation — may use optional chaining, defaults, etc.
-  return entry.score?.toFixed(2) ?? 'N/A';
-}
-
-// Public API (tool handler, command handler, etc.)
-export function handleQuery(ctx: Context) {
-  const entries = readData(ctx);
-  return entries.map(formatEntry);
-}
-
-// Export seam for testing — only used by test files
-export const _test_exports = { formatEntry };
-```
-
-```typescript
-// In test file (tests/unit/tools/formatter.test.ts)
-import { _test_exports } from '../../../src/tools/formatter';
-
-const { formatEntry } = _test_exports;
-
-describe('formatEntry', () => {
-  test('handles missing score', () => {
-    expect(formatEntry({ score: undefined })).toBe('N/A');
-  });
-  test('formats numeric score', () => {
-    expect(formatEntry({ score: 0.85 })).toBe('0.85');
-  });
-});
-```
-
-**When to use Tier 0 vs Tier 1:**
-- **Tier 0 (`_test_exports`)**: The function is a pure utility (formatter, normalizer, transformer) that doesn't call external modules. No mocking needed — test it directly.
-- **Tier 1 (`_internals`)**: You need to mock a function within the same module to test the caller in isolation. The function has side effects or calls external APIs.
-- **Tier 2 (`mock.module`)**: You need to mock a dependency from another module (Node built-ins, other application modules).
-
-**Benefits of Tier 0:**
-- Zero mock pollution — no `mock.module` calls, no `mock.restore()` needed
-- Works in batch test runs without per-file isolation
-- Type-safe (the exported object carries the real TypeScript types)
-- No filesystem dependencies (no tmpDir, no chdir, no existsSync)
-- Deterministic on all platforms and CI environments
-
-### Tier 1: _internals DI Seams (Within-Module)
-
-For mocking functions within the same module, source files export an `_internals` object that wraps key functions. Tests can replace individual functions without using `mock.module`:
-
-```typescript
-// In source file (src/services/my-service.ts)
-export const _internals = {
-  helperFn: () => { /* real implementation */ }
-};
-
-export function mainFn() {
-  return _internals.helperFn();
-}
-```
-
-```typescript
-// In test file
-import { _internals, mainFn } from '../../../src/services/my-service';
-
-test('mainFn uses mocked helper', () => {
-  const original = _internals.helperFn;
-  _internals.helperFn = mock(() => 'mocked');
-  // ... test ...
-  _internals.helperFn = original; // restore
-});
-```
-
-**Benefits:**
-- No process-global mock pollution
-- Type-safe
-- Fast (no module re-parsing)
-- Works in batch test runs without isolation
-
-**Critical limitation — reference-captured functions:** `_internals` interception requires the source code to read `_internals.fn` at the call site. When a function is instead passed as a direct argument or captured in a closure at module definition time, replacing `_internals.fn` has no effect — the mock is silently ignored and the real function runs.
-
-```typescript
-// Source: readKnowledge is captured at definition time, NOT via _internals
-export async function transactKnowledge(filePath: string, mutate: Fn) {
-  return transactFile(filePath, readKnowledge, ...);  // direct ref, captured at definition time
-}
-export const _internals = { readKnowledge };  // mutating this does NOT affect the closure above
-
-// Test — mock is silently ignored; real readKnowledge still runs
-const orig = _internals.readKnowledge;
-_internals.readKnowledge = mock(() => []);  // only mutates the object property
-await transactKnowledge(path, mutate);      // still calls the real readKnowledge
-_internals.readKnowledge = orig;
-```
-
-When `_internals` interception cannot work, verify **observable outcomes** instead: run concurrent callers and assert on final persisted state. See `tests/unit/hooks/knowledge-application.test.ts` ("two concurrent bumpCountersBatch calls") for the pattern.
-
-### Tier 2: mock.module (Cross-Module)
-
-When mocking dependencies from other modules (especially Node built-ins), use `mock.module` with proper cleanup:
-
-```typescript
-import * as realFs from 'node:fs/promises';
-
-mock.module('node:fs/promises', () => ({
-  ...realFs,  // MUST spread real exports
-  readFile: mock(() => Promise.resolve('mocked')),
-}));
-
-afterEach(() => mock.restore());
-```
-
-**Critical rules for cross-module mocks:**
-1. **Always spread real exports** for Node built-ins — other code depends on exports you don't mock
-2. **Always add `afterEach(mock.restore())`** — provides best-effort cleanup
-3. **Run in per-file isolation** — CI runs each file in its own process (`for f in *.test.ts; do bun --smol test "$f"; done`)
-
-### Choosing Between Tiers
-
-| Scenario | Pattern | Example |
-|----------|---------|--------|
-| Mocking a function in the same module you're testing | `_internals` seam | `src/state.ts` `_internals.loadSnapshot` |
-| Mocking a Node built-in (fs, child_process, etc.) | `mock.module` + spread real | `mock.module('node:fs/promises', () => ({ ...realFs, readFile: mockFn }))` |
-| Mocking another application module | `mock.module` + cleanup | `mock.module('../../../src/utils/logger', ...)` + `afterEach(mock.restore())` |
-| File-scoped mock (applies to all tests in file) | `mock.module` at top level + `mockReset()` in `beforeEach` | Preflight tests with `mockLoadPlan.mockReset()` |
+Detailed reference material moved to `.opencode/skills/writing-tests/references/mock-tiers.md` (issue #2907 progressive-disclosure budget).
 
 ## Mock Coverage Documentation
 
@@ -320,216 +190,9 @@ mock.module('../../../src/turbo/lean/runtime-conformance', () => ({
 
 This requirement applies to all three mock tiers (`_test_exports`, `_internals`, `mock.module`) whenever the mock narrows the exercised branch set.
 
-## mock.module() Export Completeness
-
-When using `mock.module()` (or `vi.mock()`) with Bun's test runner, the mock factory **MUST provide stubs for ALL named exports** of the target module — not just the ones your test calls. Bun validates the export set at dynamic-import time and throws `SyntaxError: Export named 'X' not found` if any export is missing.
-
-### Why this matters
-
-Transitive imports may reference exports your test never calls directly. For example, if your test mocks `config/schema.js` and only uses `stripKnownSwarmPrefix`, but a transitive dependency imports `PluginConfigSchema` from the same module, the mock MUST include `PluginConfigSchema` as a stub — even though your test never calls it.
-
-When the source module gains new exports (e.g., a PR adds 50 new Zod schemas to `config/schema.ts`), ALL existing `mock.module()` calls targeting that module must be updated — even if the new exports are irrelevant to your test.
-
-### How to verify completeness
-
-Before finalizing a test that uses `mock.module()`:
-
-1. List all runtime exports of the target module (type-only exports are erased at compile time and need no stub):
-   ```bash
-   grep -E "^export (const|function|async function|class) " src/path/to/module.ts
-   ```
-   **Note:** Do NOT include `type` or `interface` exports — Bun erases these at compile time and they need no runtime stub.
-2. Ensure every export name has an entry in your `mock.module()` factory.
-3. Stubs can be minimal:
-   - Functions: `() => null` or `async () => {}`
-   - Zod schemas: use a comprehensive stub that supports common methods:
-     ```typescript
-     const zodStub = {
-       parse: (v: unknown) => v,
-       safeParse: (v: unknown) => ({ success: true as const, data: v }),
-       parseAsync: async (v: unknown) => v,
-     };
-     ```
-   - Constants: appropriate zero values (`''`, `0`, `null`, `[]`, `{}`)
-
-### Verification pattern
-
-```typescript
-// ✅ CORRECT — all exports provided, test uses only the first one
-mock.module('../../../src/config/schema.js', () => ({
-  // The one export your test actually uses
-  stripKnownSwarmPrefix: mockStripFn,
-  // Stubs for transitive import resolution (never called in test)
-  PluginConfigSchema: zodStub,
-  ScoringConfigSchema: zodStub,
-  isKnownCanonicalRole: () => false,
-  // ... all other runtime exports as stubs
-}));
-
-// ❌ WRONG — missing exports cause SyntaxError at module-load time
-mock.module('../../../src/config/schema.js', () => ({
-  stripKnownSwarmPrefix: mockStripFn,
-  // Missing: PluginConfigSchema, ScoringConfigSchema, etc.
-  // → "SyntaxError: Export named 'PluginConfigSchema' not found"
-}));
-```
+Detailed reference material moved to `.opencode/skills/writing-tests/references/mock-tiers.md` (issue #2907 progressive-disclosure budget).
 
-### What IS and IS NOT test theater
-
-Adding stubs for ESM resolution is NOT test theater — it's a Bun runtime requirement. The distinction:
-
-| Pattern | Test theater? | Why |
-|---------|--------------|-----|
-| Adding `PluginConfigSchema: zodStub` so the module loads | **No** | Required for ESM resolution; stub is never called |
-| Stubbing `validateDirectory` to return `true` then asserting "validation works" | **Yes** | The stub bypasses the logic you should be testing |
-| Using `zodStub` in assertions: `expect(zodStub.parse(input)).toBe(input)` | **Yes** | Testing the stub, not the real code |
-| Adding stubs for ALL 50 Zod schemas in config/schema.ts | **No** | All are required for transitive import resolution |
-
-The stubs exist solely to satisfy the module loader. Test assertions must verify behavior through the real-mocked functions (the ones your test actually calls), not through the stubs.
-
-### Files Intentionally Using File-Scoped Mocks
-
-Some test files use top-level `mock.module` that must persist across all tests in the file. These files use `mockReset()`/`mockClear()` in `beforeEach` instead of `mock.restore()` in `afterEach`:
-
-- `src/__tests__/preflight-phase.test.ts` — mocks `plan/manager` and `preflight-service`
-
-## Cross-Platform Test Patterns
-
-Tests run on all three CI platforms (ubuntu, macos, windows). Path and filesystem behavior
-differs between them. Follow these patterns to prevent platform-specific failures:
-
-### Mock keys with filesystem paths
-
-**Never hardcode Unix-format paths as mock keys.** On Windows, `path.resolve('/dir', 'file')`
-produces drive-letter-prefixed paths like `D:\dir\file`, not `/dir/file`. A mock that checks
-for `/dir/file` will silently never match, causing the test to behave differently on Windows.
-
-**Use `path.resolve()` to construct mock keys the same way the source code does:**
-
-```typescript
-// ❌ WRONG — fails on Windows (mock expects '/safe/dir/linked.ts',
-//    but path.resolve('/safe/dir', 'linked.ts') = 'D:\safe\dir\linked.ts')
-mockRealpathSync.mockImplementation((inputPath: string) => {
-  if (inputPath === '/safe/dir') return '/safe/dir';
-  if (inputPath === '/safe/dir/linked.ts') return '/outside/linked.ts';
-  return inputPath;
-});
-
-// ✅ CORRECT — path.resolve produces matching keys on all platforms
-const mockDir = path.resolve('/safe/dir');
-const linkedResolved = path.resolve(mockDir, 'linked.ts');
-const outsideResolved = path.resolve('/outside/linked.ts');
-
-// mockRealpathSync is a mock() function (bun:test) — see mocking patterns above
-mockRealpathSync.mockImplementation((inputPath: string) => {
-  if (inputPath === mockDir) return mockDir;
-  if (inputPath === linkedResolved) return outsideResolved;
-  return inputPath;
-});
-```
-
-### Symlink behavior differences
-
-- On Windows, `fs.symlinkSync` for directories creates **junctions** by default, which
-  resolve differently than POSIX symlinks. Junction creation may require administrator
-  elevation on older Node.js versions.
-- `fs.realpathSync` on a broken symlink throws `ENOENT` on POSIX but may throw
-  `EINVAL` on Windows, depending on symlink type.
-- Use `test.skipIf(process.platform === 'win32')` for tests that directly manipulate
-  filesystem symlinks, unless the test's purpose is explicitly to verify cross-platform
-  symlink behavior.
-
-### Temporary directory patterns
-
-- Use `os.tmpdir()` + `path.join()` for temp paths. **Never** hardcode `/tmp` or `C:\`.
-- Wrap `mkdtempSync` in `realpathSync` if the result is `chdir`'d on macOS (temp
-  dirs are often symlinked to `/private/var/...`).
-- Clean up temp dirs in `afterEach` or `afterAll` with a bounded helper that
-  verifies the resolved cleanup target is a child of `os.tmpdir()` before
-  calling recursive `rm`. Reuse `tests/helpers/safe-test-dir.ts` when possible.
-  Do not call recursive `rm` on a computed path unless the helper has rejected
-  empty strings, `os.tmpdir()` itself, and paths outside the temp root.
-
-### Platform-specific environment variable redirection
-
-When tests redirect `process.env.HOME` to isolate path-resolver-dependent code
-(functions like `resolveHiveKnowledgePath`, `resolveSwarmKnowledgePath`, or any
-function that reads `os.homedir()` / platform env vars), they MUST redirect ALL
-platform-specific env vars, not just `HOME`. A partial redirect silently falls
-back to the real user profile on some platforms, causing tests to read/write
-actual user data instead of the isolated temp directory.
-
-Per-platform requirements:
-
-- **Linux**: redirect `HOME`, `XDG_CONFIG_HOME`, and `XDG_DATA_HOME`.
-- **macOS**: redirect `HOME` (macOS resolves `~/Library/Application Support` from
-  the home directory).
-- **Windows**: redirect `HOME`, `LOCALAPPDATA`, AND `APPDATA`. Windows path
-  resolvers read `LOCALAPPDATA` and `APPDATA`, neither of which is derived from
-  `HOME`. Redirecting only `HOME` silently fails on Windows, causing tests to
-  touch the real `%LOCALAPPDATA%` and `%APPDATA%` trees.
-
-> **⚠️ Bun caches `os.homedir()` on first call.** If a module calls `os.homedir()`
-> before the test sets `process.env.HOME`, the cached value persists for the
-> lifetime of the process and later env changes are silently ignored. Set
-> `process.env.HOME` (and other redirected vars) **before** importing any module
-> that calls `os.homedir()`. The source code documents this at
-> `src/hooks/knowledge-store.ts`: "Bun caches os.homedir(), so changing $HOME
-> after first call is ignored."
-
-Use per-variable save/restore rather than saving and replacing the entire
-`process.env` object — the latter discards process-level env state and can
-interfere with other test infrastructure:
-
-```typescript
-import { beforeEach, afterEach } from 'bun:test';
-import os from 'node:os';
-import path from 'node:path';
-
-const saved = {
-  HOME: process.env.HOME,
-  LOCALAPPDATA: process.env.LOCALAPPDATA,
-  APPDATA: process.env.APPDATA,
-  XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
-  XDG_DATA_HOME: process.env.XDG_DATA_HOME,
-};
-
-beforeEach(() => {
-  const isolatedDir = path.join(os.tmpdir(), 'test-home');
-  process.env.HOME = isolatedDir;
-  process.env.LOCALAPPDATA = isolatedDir;
-  process.env.APPDATA = isolatedDir;
-  process.env.XDG_CONFIG_HOME = isolatedDir;
-  process.env.XDG_DATA_HOME = isolatedDir;
-});
-
-afterEach(() => {
-  for (const [key, value] of Object.entries(saved)) {
-    if (value === undefined) delete process.env[key];
-    else process.env[key] = value;
-  }
-});
-```
-
-For cross-file isolation (tests that must survive across multiple files in the
-same process, e.g. batch steps), use `beforeAll` / `afterAll` with the same
-per-var save/restore pattern. Never mutate `process.env` without restoring it in
-a matching teardown hook.
-
-**Preferred approach:** Use `createIsolatedTestEnv()` from
-`tests/helpers/isolated-test-env.ts`. It handles `XDG_CONFIG_HOME`, `APPDATA`,
-`LOCALAPPDATA`, and `HOME` with correct per-variable save/restore and returns a
-cleanup function that removes the temp directory. Use this helper unless your
-test has specific requirements it doesn't cover.
-
-### Line ending normalization
-
-Git on Windows converts LF to CRLF by default. Tests that compare file contents
-byte-by-byte against expected strings must normalize line endings:
-
-```typescript
-const actual = readFileSync(path, 'utf-8').replace(/\r\n/g, '\n');
-```
+Detailed reference material moved to `.opencode/skills/writing-tests/references/cross-platform-patterns.md` (issue #2907 progressive-disclosure budget).
 
 ## CI Pipeline Structure
 
@@ -734,104 +397,11 @@ When a SKILL.md (or other agent-facing document) contains an **executable exampl
 - Examples that are intentionally schematic ("the response looks roughly like this") rather than literal.
 - Documentation that is auto-generated from source — drift is impossible by construction in that case.
 
-## Cross-Platform Requirements
+Detailed reference material moved to `.opencode/skills/writing-tests/references/cross-platform-patterns.md` (issue #2907 progressive-disclosure budget).
 
-> **See also**: [Cross-Platform Test Patterns](#cross-platform-test-patterns) above for detailed
+> **See also**: [Cross-Platform Test Patterns](references/cross-platform-patterns.md) for detailed
 > guidance on mock keys, symlink behavior, temp directories, and line endings.
 
-All tests must pass on Linux, macOS, and Windows unless explicitly gated with:
-```typescript
-const isWindows = process.platform === 'win32';
-if (isWindows) test.skip('reason', () => {});
-```
-
-### Path handling
-- Use `path.join()` or `path.resolve()`, never string concatenation with `/`.
-- Temp directories: use `os.tmpdir()`, not hardcoded `/tmp`.
-- File comparisons: normalize paths before comparing (`path.resolve(a) === path.resolve(b)`).
-
-### Process spawning
-- Use `.cmd` extension on Windows for npm/bun binaries: `process.platform === 'win32' ? 'bun.cmd' : 'bun'`.
-- Use array-form `spawn`/`spawnSync`, never shell string commands.
-
-### macOS rename-visibility race (write-then-read atomic files)
-
-On macOS/APFS, `fs.renameSync` can complete before the data is visible to
-subsequent reads. Tests that write-then-read atomic files may fail on
-`macos-latest` but pass on `ubuntu-latest` and `windows-latest`.
-
-**Symptom:** Test fails only on macOS with `result === null` or
-`result === undefined` immediately after a write that should have made the
-file visible.
-
-**Root cause:** macOS filesystem updates the directory entry asynchronously
-after `fs.renameSync`. Immediately-following reads may see ENOENT or stale
-data.
-
-**Fix — three layers (use all three for production code):**
-
-**Layer 1: Use `bunWrite` for atomic writes.** The `bunWrite` function in
-`src/utils/bun-compat.ts` already handles temp file creation, fsync,
-atomic rename, and parent directory fsync correctly across platforms.
-Do NOT reimplement this pattern.
-
-**Layer 2: Add ENOENT retry in the read path.** Wrap `validateSwarmPath` and
-the file read in a try/catch with a bounded retry loop for ENOENT:
-
-```typescript
-// CORRECT — retry on ENOENT only (not other errors), bounded
-const maxAttempts = 5;
-const retryDelayMs = 10;
-for (let attempt = 0; attempt < maxAttempts; attempt++) {
-  try {
-    const resolvedPath = _internals.validateSwarmPath(directory, filename);
-    const file = bunFile(resolvedPath);
-    const content = await file.text();
-    return content;
-  } catch (err) {
-    const isNotFound = (err as NodeJS.ErrnoException)?.code === 'ENOENT';
-    if (!isNotFound || attempt === maxAttempts - 1) {
-      return null;
-    }
-    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
-  }
-}
-return null;
-```
-
-CRITICAL: `validateSwarmPath` must be INSIDE the try block so that throws
-(for path traversal attempts) are caught and return null. Security tests
-expect `readSwarmFileAsync` to return null for traversal attempts.
-
-**Layer 3: Don't add arbitrary delays.** `setTimeout` should be bounded
-(5-10ms, max 5 attempts). Do not add `await new Promise(r => setTimeout(r, 100))`
-"just in case" — that's a code smell. The retry loop handles it.
-
-See [`.opencode/skills/engineering-conventions/SKILL.md`](../engineering-conventions/SKILL.md)
-for the evidence file flow that triggers this retry pattern in QA gates.
-
-### Node FileHandle API
-
-Node's `FileHandle` uses `.sync()`, NOT `.fsync()`:
-
-```typescript
-// CORRECT
-const fd = await fsPromises.open(dir, 'r');
-try {
-  await fd.sync();
-} finally {
-  await fd.close();
-}
-
-// WRONG — TypeScript error: Property 'fsync' does not exist on type 'FileHandle'
-const fd = await fsPromises.open(dir, 'r');
-try {
-  await fd.fsync();
-} finally {
-  await fd.close();
-}
-```
-
 ## Running Tests
 
 For the full test execution commands (bash and PowerShell per-file isolation loops, CI integration), read `file:.swarm/bundled-skills/running-tests/SKILL.md`. The key principle: always run one test file per process (`bun --smol test <file> --timeout 30000`) to prevent `mock.module` cross-contamination.