The best way to control Claude Code, Codex and more from any computer or phone

main
md 59 lines 1.96 KB
Rendered Raw
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.