Extend sync-api-types to support versioned OpenAPI specs and detect breaking changes

[Lakes41]

Difficulty: Advanced
Type: DevOps

Background
scripts/sync-api-types.js is described as a "zero-dependency compiler converting openapi.json to typescript types," compiling test/fixtures/openapi.json into lib/api/types.ts, with a companion npm run check-types to validate they still match.

Problem
If guildpass-core ever introduces a /v2 API (a natural evolution given its documented versioning contract) or makes a breaking change to /v1 types, sync-api-types.js and check-types have no described mechanism to detect breaking changes (removed fields, changed types) versus purely additive ones, risking silent type drift or an unhelpfully blunt full-regeneration diff.

Expected outcome
sync-api-types.js supports pointing at multiple OpenAPI fixture files (e.g., a v1 and future v2), generating correctly namespaced types for each, and check-types reports specifically which fields were removed/changed type (breaking) versus added (non-breaking) when the fixture and generated types diverge.

Suggested implementation

• Extend the script's CLI/config to accept an OpenAPI version identifier and output namespaced types (e.g., V1Member, V2Member) rather than assuming a single flat type set.
• Implement a structural diff between the previously-generated types and freshly-parsed schema, categorizing changes as additive vs. breaking.
• Update check-types to print a clear breaking-vs-additive report and exit non-zero only on breaking changes (or on any drift, per current behavior — document the chosen policy).
• Add a test fixture pair (a base openapi.json and a modified one) exercising both additive and breaking scenarios.

Acceptance criteria

• Script generates correctly namespaced types for more than one OpenAPI fixture version
• check-types distinguishes and reports breaking vs. additive schema changes
• Test fixtures demonstrate both scenarios passing/failing as expected
• README.md's Scripts section updated to describe the new capability

Likely affected files/directories

• scripts/sync-api-types.js
• test/fixtures/openapi.json
• lib/api/types.ts
• README.md

[mayborn005]

Hello @maintainer, I understand the expected outcome and would love to work on this. I'll provide a solution that satisfies the acceptance criteria.

[Six2world]

I'll take this one.

Plan:

1. Extend sync-api-types.js to accept multiple OpenAPI fixture inputs with a version identifier, generating namespaced types (V1Member, V2Member, etc.) instead of a flat set.
2. Add a structural diff step comparing freshly-parsed schema against previously-generated types, classifying changes as additive (new optional fields/types) vs. breaking (removed fields, type changes, now-required fields).
3. Update check-types to print a breaking-vs-additive report; exit non-zero on breaking changes (documenting this policy choice vs. failing on any drift).
4. Add a base + modified fixture pair under test/fixtures/ to exercise both scenarios.
5. Update README's Scripts section to describe multi-version support and the new diff behavior.

Assigning to myself.

[grantfox-oss]

🦊 GrantFox — @Six2world has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #336)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.