mock-to-internals-migration · diff
git:20261012.097422c to git:20261030.00ff7e9
52 added, 3 removed. Audit A to A.
---
name: mock-to-internals-migration
- description: Codex adapter for migrating opencode-swarm tests away from Bun mock.module leakage toward _internals dependency-injection seams. Use when touching tests with mock.module, adding test seams, fixing Bun mock isolation failures, or updating source modules for injectable internals.
+ description: Codex canon for migrating opencode-swarm tests away from Bun mock.module leakage toward _internals dependency-injection seams. Use when touching tests with mock.module, adding test seams, fixing Bun mock isolation failures, or updating source modules for injectable internals.
metadata:
audience: swarm-plugin
---
# Mock To Internals Migration
- Read `.opencode/skills/generated/mock-to-internals-migration/SKILL.md` for the canonical migration protocol.
+ This is the canonical Codex migration protocol (self-contained since the #2966
+ retired-generated-skill reconciliation; it previously delegated to a retired
+ generated fork). The host-agnostic rules live in AGENTS.md invariant 7 and
+ `.opencode/skills/writing-tests/SKILL.md`; this canon carries the migration's own
+ procedure and checks.
+ ## Required Procedure
+
+ - Mirror the existing opt-in pattern when gating tools behind feature flags: a
+ separate tool-map constant, a conditional merge in `src/agents/index.ts`, and
+ gating tests verifying BOTH the disabled and enabled states.
+ - Run barrel-import-dependent tests after modifying barrel exports.
+ - Audit code structure integrity before editing a file that was recently
+ refactored or extracted (the symbol may have moved).
+ - Grep for all `vi.fn()`, `vi.spyOn()`, `vi.mock()` in converted files before
+ declaring the conversion complete.
+ - Spread the real module's exports (`...realModule`) as the base of every
+ `mock.module` return object that must remain (Node built-ins especially).
+ - Prefer a small `_internals` seam exposing only the dependency under test over
+ a new `mock.module` target — `mock.module` leaks across test files in Bun's
+ shared test-runner process (AGENTS.md invariant 7; the allowlist is closed by
+ `bun run check:invariants` Check 4).
+ - Design command-transformation pipelines as idempotent passes, not stacking
+ layers.
+ - Run tests on the unmodified codebase before starting, to establish a failure
+ baseline.
+ - Run the lint check (e.g. `bun run lint`) as part of pre-submit verification,
+ not just the build.
+
+ ## Forbidden Shortcuts
+
+ - Invent new tool-gating mechanisms for opt-in feature flags.
+ - Label post-change test failures as "pre-existing" without having run the
+ tests before the change.
+
+ ## Reviewer Checks
+
+ - Grep for import-from-barrel patterns in test files and run the affected tests
+ after barrel changes.
+ - Grep for `mock.module` patterns that lack the `...realModule` spread.
+ - Confirm `bun:test` isolation patterns match the skill guidelines.
+ - For wrapper transforms, verify idempotency by applying the transform twice and
+ confirming the output equals the single-call output.
+ - Run `git diff <base>..<head> --name-only` and confirm file presence before
+ marking `introduced_by_pr` verdicts.
+
+ ## Test Engineer Checks
+
+ - Add or update tests covering the trigger condition and the forbidden shortcut.
+
Also load:
1. `.agents/skills/writing-tests/SKILL.md`
- 2. `.agents/skills/engineering-conventions/SKILL.md` if the seam touches runtime-sensitive code
+ 2. `.agents/skills/engineering-conventions/SKILL.md` if the seam touches
+ runtime-sensitive code
Codex-specific execution notes:
- Use `apply_patch` for source and test edits.
- Use focused per-file `bun --smol test <file> --timeout 30000` validation first.
- Restore any `_internals` overrides in `afterEach`.
- Prefer small seams that expose only the dependency under test.