API extractor reports
API extractor 报告
Public API changes are invisible — nothing makes "this commit changed the public API" an explicit, reviewable fact. A reviewer reading a diff can miss that an exported type gained a field or a method signature shifted.
English
Problem
Public API changes are invisible — nothing makes "this commit changed the public API" an explicit, reviewable fact. A reviewer reading a diff can miss that an exported type gained a field or a method signature shifted.
Proposal
api-extractor (or tsc --emitDeclarationOnly + a normalized public-API dump) producing a checked-in etc/<pkg>.api.md per package; CI fails if regeneration differs. Every public-API change becomes a diff line a reviewer (or review agent) must see.
Alternatives considered
tsc --emitDeclarationOnly plus a normalized public-API dump — the lighter mechanism if api-extractor proves too heavy; either satisfies the checked-in, diffable report shape the proposal needs.
Acceptance criteria
- Every package has a checked-in
etc/<pkg>.api.md; CI fails when regeneration differs from the committed report. - A public-API change (a new export, a widened field, a shifted signature) is visible as a report diff line in review.
Risks
The dependency is heavy and finicky — the reason this was deferred — and the report format churns with compiler upgrades, adding a maintenance burden that buys little while the packages stay unpublished.
Why deferred
Deferred when doc-sync landed: low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency. Revisit if the packages are ever published externally — at that point a stable, diffable public API earns its keep.
中文
问题
公开 API 的变更是不可见的：没有任何机制将「此次提交改变了公开接口」变为一个显式、可评审的事实。评审者阅读 diff 时可能遗漏某个导出类型新增了字段，或某个方法签名发生了变化。
提案
使用 api-extractor（或 tsc --emitDeclarationOnly 加一份规范化的公开 API 清单）为每个包生成一份签入仓库的 etc/<pkg>.api.md；CI 在重新生成结果与已签入报告不一致时失败。这样，每一次公开 API 变更都会成为评审者（或评审 agent（智能体））必须看到的一行 diff。
曾考虑的替代方案
tsc --emitDeclarationOnly 加规范化的公开 API 清单：如果 api-extractor 过于笨重，这是更轻量的机制；两者都能满足提案所需的「签入仓库、可 diff」的报告形态。
验收标准
- 每个包都有一份签入仓库的
etc/<pkg>.api.md；CI 在重新生成结果与已提交报告不一致时失败。 - 公开 API 变更（新增导出、字段放宽、签名变化）在评审中以报告 diff 行的形式可见。
风险
该依赖笨重且难以调教（这正是它被推迟的原因），且报告格式会随编译器升级而变动，增加一个维护面；在各包尚未发布的阶段，收益有限。
推迟原因
在 doc-sync 落地时被推迟：对于一个内部 monorepo，评审者已经能看到源码 diff，价值不高；且依赖笨重、难以调教。如果各包将来对外发布，再重新评估——届时一份稳定、可 diff 的公开接口报告才值得其维护成本。