| 1 | # API Diff |
| 2 | |
| 3 | `@effect/api-diff` compares the consumer-visible TypeScript declarations emitted |
| 4 | by two repository revisions. Its JSON output is canonical; the Markdown report |
| 5 | is intended for migration review and does not make semantic-version |
| 6 | compatibility claims. |
| 7 | |
| 8 | Run a complete comparison from the repository root: |
| 9 | |
| 10 | ```sh |
| 11 | pnpm api-diff \ |
| 12 | --base-ref v3 \ |
| 13 | --head-ref origin/main \ |
| 14 | --output tmp/api-diff/run |
| 15 | ``` |
| 16 | |
| 17 | Both refs are required and are resolved to commit SHAs before work starts. The |
| 18 | tool builds detached disposable worktrees with each branch's native build, |
| 19 | discovers every public package entrypoint independently, extracts both snapshots |
| 20 | with one pinned TypeScript compiler API, and caches successful snapshots by |
| 21 | commit and compiler. |
| 22 | |
| 23 | After updating the extractor, regenerate both snapshots with the same extractor |
| 24 | before comparing them. Old snapshots may have lost information that the current |
| 25 | extractor preserves; comparing snapshots from different extractor generations is |
| 26 | not supported. |
| 27 | |
| 28 | The command writes: |
| 29 | |
| 30 | - `base.snapshot.json` |
| 31 | - `head.snapshot.json` |
| 32 | - `diff.json` |
| 33 | - `report.md` |
| 34 | |
| 35 | Generate the agent-facing v3-to-v4 migration reference from a fresh diff and |
| 36 | the YAML files in `migration/annotations`: |
| 37 | |
| 38 | ```sh |
| 39 | pnpm api-diff --write-doc migration/v3-to-v4.md |
| 40 | ``` |
| 41 | |
| 42 | The document command defaults to refs `v3` and `main`, records their resolved |
| 43 | SHAs, preserves the existing import map sections, and replaces the API |
| 44 | reference in place. It does not write `diff.json` unless `--output` is also |
| 45 | provided. |
| 46 | |
| 47 | An API annotation can set `include: true` to retain migration guidance even |
| 48 | when the declaration comparison does not classify that API as changed. |
| 49 | |
| 50 | List missing annotations, grouped by v3 module, and exit non-zero when any are |
| 51 | missing: |
| 52 | |
| 53 | ```sh |
| 54 | pnpm api-diff --check |
| 55 | ``` |
| 56 | |
| 57 | Unmatched APIs are reported as removals from the base and additions in the |
| 58 | head. Likely replacements are reported separately for review, including |
| 59 | cross-module moves and the paired type/value facets of class-style APIs. |