Schema-diff driven release notes

[brianorwhatever]

Why

The majority of SDK releases exist because the upstream supergraph schema changed, but the release commit is a one-line package.json bump and the GitHub Release body is just a compare link — the schema is gitignored and fetched at build time, so neither git nor GitHub's release-note generator can see what actually changed. (This also meant the recent Category.iconUrl/bannerUrl removal shipped invisibly inside 2.3.12/2.3.13.)

What

• Track the schema: src/resources/schema.graphql is now committed. fetch:schema updates it; build reads the committed copy (copy:schema), so published artifacts are reproducible from the tagged commit — previously release.yml re-fetched at publish time and what shipped wasn't traceable to any commit.
• src/scripts/schemaDiff.ts (new, uses @graphql-inspector/core): diffs two SDL files and prints a markdown summary grouped into Breaking / Dangerous / Additions, with noise collapsed (added/removed types roll up their member bullets, directive-usage duplicates dropped, description edits summarized, 100-bullet cap per section). Emits changed/level outputs for CI.
• bump.yml: fetch latest schema → diff against committed copy → commit the schema update → bump minor if breaking, patch otherwise → tag → GitHub Release whose notes lead with the schema diff (auto-generated PR notes still appended). Skips the release entirely if the schema is unchanged and there are no new commits.

Note: the committed generated SDK code (src/sdk/generated, Subscribe.ts, Query.ts) is intentionally untouched here — it regenerates from the committed schema at build time and will sync up on the next release.

Example output

A release after the recent Category deprecations would render:

Schema additions

• Field 'Category.iconUrl' is deprecated
• Field 'Category.bannerUrl' is deprecated

1 description/documentation change(s).

And if fields are hard-removed, the notes lead with ⚠️ Breaking schema changes and the version bump escalates to minor automatically.

Testing

• Dry-ran the workflow steps locally against real historical schemas (2.3.13's shipped SDL, the briefly-live removal schema, and the last-committed Nov 2025 schema): breaking/nonbreaking/none detection, bump-level selection, and the no-op gate all behave as expected.
• pnpm run build and pnpm test (25/25) pass; new script is eslint/prettier clean.