API Diff
@effect/api-diff compares the consumer-visible TypeScript declarations emitted
by two repository revisions. Its JSON output is canonical; the Markdown report
is intended for migration review and does not make semantic-version
compatibility claims.
Run a complete comparison from the repository root:
pnpm api-diff \
--base-ref v3 \
--head-ref origin/main \
--output tmp/api-diff/run
Both refs are required and are resolved to commit SHAs before work starts. The tool builds detached disposable worktrees with each branch's native build, discovers every public package entrypoint independently, extracts both snapshots with one pinned TypeScript compiler API, and caches successful snapshots by commit and compiler.
The command writes:
base.snapshot.jsonhead.snapshot.jsondiff.jsonreport.md
Generate the agent-facing v3-to-v4 migration reference from a fresh diff and
the YAML files in migration/annotations:
pnpm api-diff --write-doc migration/v3-to-v4.md
The document command defaults to refs v3 and main, records their resolved
SHAs, preserves the existing import map sections, and replaces the API
reference in place. It does not write diff.json unless --output is also
provided.
List missing annotations, grouped by v3 module, and exit non-zero when any are missing:
pnpm api-diff --check
Unmatched APIs are reported as removals from the base and additions in the head. Likely replacements are reported separately for review, including cross-module moves and the paired type/value facets of class-style APIs.