[jeffdupont]

Step 5 of AIC-3500 for JS, part 2: CI fails on a breaking change to the public API unless the PR declares it (checks 2 and 3, TESTING.md §5.2). The Python version is python-ai-sdk#196. Stacked on #153.

What changes

• scripts/api-breaking.mjs (plain Node, no dependencies, like api-surface.mjs) compares each non-experimental report declaration by declaration.
  • A removed or changed declaration is breaking, and so is a report present at base but gone at head. An added declaration is not. Comment-only changes such as doc comments or @deprecated don't count.
  • TypeScript's tool can't tell a compatible change from a breaking one (A.16), so an added optional member is flagged and passes with the api-compatible label.
• pr mode passes when the title has ! (same regex as Python) or the PR has api-compatible.
• release mode runs on the release-please PR. For each package whose version changes, it compares against the package's last release tag (<component>-<version>, from release-please-config.json). A breaking change needs a major bump, or a minor one before 1.0.
• .github/workflows/api-compatibility.yml: same triggers as Python's (edited, labeled and unlabeled re-run it) and the same release-PR detection (release-please--branches--main). The title goes through env, not shell interpolation.
• 24 node:test tests (yarn test:api-breaking, run in CI) in a throwaway git repo.

Verified

• All repo checks pass, plus yarn test:api-breaking (24 passed).
• A real pr run against part 1 and against main says "No breaking changes to the public API."
• Changing input?: to input: in the openai-messages report fails and shows the old and new lines; with a feat!: title it passes.
• release mode, with the manifest edited temporarily: client 0.4.0 → 0.4.1 fails (and passes with api-compatible), and 0.4.0 → 0.5.0 passes.
• Five ai-server declarations have changed since @launchdarkly/ai-server-0.4.0. The open release PR chore: release main #131 bumps the client to 0.5.0, which passes. I didn't run the script against that branch.

Known limit: the provider packages have no report at their last release tag, so check 3 skips them, with a message, until their next release.

🤖 Generated with Claude Code

---

Note

Overview
Adds API compatibility enforcement so CI blocks undeclared breaking changes to committed API Extractor reports (packages/*/etc/*.api.md).

A new scripts/api-breaking.mjs compares stable (non-experimental) reports declaration-by-declaration: removals, signature/type changes, and deleted reports count as breaking; additions do not; comment-only edits are ignored. PR mode fails unless the title uses conventional ! (feat!:, etc.) or the PR has the api-compatible label. Release mode (release-please branch) compares each bumped package to its last release tag and requires a major bump (or pre-1.0 minor) when breaking diffs exist, with the same label escape hatch.

A dedicated .github/workflows/api-compatibility.yml runs those checks on PR events (including title/label edits). Main ci.yml runs yarn test:api-breaking (24 fixture git tests). AGENTS.md documents the policy for contributors.

^{Reviewed by Cursor Bugbot for commit 08fbcc1. Bugbot is set up for automated code reviews on this repo. Configure here.}