ci(spec): add SDK types generation and breaking-change gate

[yakimoto]

Completes the L6 CONTRACT card levers 2+3 (api-spec side).

• package.json + package-lock.json: pinned tooling (openapi-typescript@7.13.0, js-yaml, redocly@2.40.0) with the full transitive tree locked; CI installs via npm ci --ignore-scripts (lockfile added during review to pin transitives).
• generated/api-types.d.ts: deterministic types emitted from openapi.yaml (verified byte-identical on re-run).
• sdk-types CI job: regenerates types on every PR, git diff --exit-code fails on drift + non-empty artifact check.
• breaking-change CI job: extracts base-branch spec, runs oasdiff breaking --fail-on ERR (verified: exit 0 on no breaking, exit 1 on breaking) vs PR spec via ghcr.io/tufin/oasdiff; fails unless PR body carries explicit Breaking: yes marker.
• CHANGELOG updated.

Not changing openapi.yaml, so the breaking gate is green (verified exit 0 against origin/main).

---

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

---

Note

^{Cursor Bugbot is generating a summary for commit 237334c. Configure here.}

Note

Add SDK types generation and breaking-change gate to CI

• Adds a sdk-types CI job that regenerates TypeScript types from openapi.yaml using pinned openapi-typescript and fails if the result differs from the committed generated/api-types.d.ts.
• Adds a breaking-change CI job that diffs openapi.yaml against the PR base branch using pinned oasdiff v1.28.0 and fails unless the PR body contains the marker Breaking: yes.
• Adds package.json with lint and gen:types npm scripts and pins devDependencies; commits package-lock.json for reproducible installs (.gitignore updated accordingly).

^{Macroscope summarized e41c5fd.}

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 51 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3987537f-1443-4663-bb19-b1bfa73ed8ca

📥 Commits

Reviewing files that changed from the base of the PR and between 31d6a24 and e41c5fd.

⛔ Files ignored due to path filters (2)

• generated/api-types.d.ts is excluded by !**/generated/**
• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (4)

• .github/workflows/foundation-gate.yml
• .gitignore
• CHANGELOG.md
• package.json

---

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_6a21b49e-3f0d-4223-9784-9150a96454ca)

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	js-yaml@​4.1.0
	@​redocly/​cli@​2.40.0
	openapi-typescript@​7.13.0

View full report

[cursor]

Risk: medium. Left a non-blocking comment because Cursor Bugbot and Cursor Security Agent both finished as skipped, so the required automated-review signals are incomplete. Human review is needed; no additional reviewers were assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[qodo-code-review]

PR Summary by Qodo

Add CI gates for generated SDK types drift and OpenAPI breaking changes

⚙️ Configuration changes ✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Generate and commit deterministic TypeScript API types from openapi.yaml.
• Add CI gate to fail PRs when generated types drift from the spec.
• Add CI breaking-change detection requiring explicit "Breaking: yes" acknowledgement.

Diagram

graph TD
  PR["Pull Request"] --> Spec["openapi.yaml"] --> TypesJob(["CI: sdk-types"]) --> TypesFile["generated/api-types.d.ts"]
  TypesJob --> DiffGate["git diff --exit-code"]
  PR --> BaseSpec["base branch openapi.yaml"] --> BreakJob(["CI: breaking-change"]) --> OAS{{"oasdiff (docker)"}}
  Spec --> BreakJob --> Ack{"Breaking: yes?"}
  subgraph Legend
    direction LR
    _f["File"] ~~~ _j(["CI job"]) ~~~ _e{{"External tool"}} ~~~ _d{"Decision"}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Pin oasdiff image version

• ➕ Eliminates CI behavior changes from upstream 'latest' tag updates
• ➕ Improves debuggability/reproducibility when a diff result changes
• ➖ Requires periodic version bumps to pick up new diff rules/bug fixes

2. Use PR label for break acknowledgement

• ➕ Less brittle than matching an exact body string
• ➕ Easier to audit/search for breaking changes in the PR list
• ➖ Requires label permissions/automation; slightly more repo admin overhead
• ➖ May be slower for contributors unfamiliar with labeling

3. Generate types as a build artifact only (don’t commit)

• ➕ Avoids large generated-file diffs in reviews
• ➕ Prevents merge conflicts on generated output
• ➖ Consumers lose a stable, versioned types file in-repo
• ➖ Harder to ensure downstream SDKs stay in lockstep without extra publishing steps

Recommendation: The PR’s approach is strong for contract enforcement: committing deterministic types enables downstream consumers to depend on a versioned artifact, and the CI drift gate keeps it honest. Consider pinning the oasdiff container tag (instead of :latest) to avoid unexpected CI changes; the PR-body marker is acceptable, but a PR label acknowledgement is a viable upgrade if brittleness becomes an issue.

Files changed (4) +3659 / -0

Enhancement (1) +3573 / -0

api-types.d.tsAdd generated TypeScript definitions from OpenAPI spec +3573/-0

Add generated TypeScript definitions from OpenAPI spec

• Adds the openapi-typescript-generated declaration file exporting typed paths, operations, and schemas derived from openapi.yaml. Intended to be deterministic and treated as a committed artifact validated by CI.

generated/api-types.d.ts

Documentation (1) +8 / -0

CHANGELOG.mdDocument new CI contract gates and generated types artifact +8/-0

Document new CI contract gates and generated types artifact

• Adds changelog entries describing the committed SDK types file and the sdk-types drift gate. Documents the breaking-change gate behavior and the required PR-body marker for acknowledged breaks.

CHANGELOG.md

Other (2) +78 / -0

foundation-gate.ymlAdd sdk-types drift gate and breaking-change acknowledgement gate +62/-0

Add sdk-types drift gate and breaking-change acknowledgement gate

• Introduces a new sdk-types job that regenerates TypeScript types from openapi.yaml and fails if the committed generated file differs or is missing/empty. Adds a breaking-change job that compares PR vs base-branch specs using oasdiff and blocks unacknowledged breaking changes unless the PR body contains "Breaking: yes".

.github/workflows/foundation-gate.yml

package.jsonIntroduce pinned OpenAPI tooling and generation scripts +16/-0

Introduce pinned OpenAPI tooling and generation scripts

• Adds a package.json defining pinned devDependencies (openapi-typescript, @redocly/cli, js-yaml) and scripts for linting the spec and generating types. Aligns local/CI tooling versions without committing a lockfile.

package.json

[macroscopeapp]

Approvability

Verdict: Approved e41c5fd

Adds CI quality gates for SDK type drift detection and breaking API change detection. Changes are limited to workflow configuration, .gitignore, and changelog - no production runtime impact. Author owns all modified files.

^{You can customize Macroscope's approvability policy. Learn more.}

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📜 Skill insights (0)

1. PR body read may 403 ✓ Resolved 🐞 Bug ☼ Reliability

Description

The new breaking-change job calls gh pr view to read the PR body, but the workflow’s token
permissions are restricted to contents: read, so this step can fail with an authorization error
when breaking changes are detected (preventing acknowledged breaks from passing).

Code

.github/workflows/foundation-gate.yml[R113-115]

+            if gh pr view "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}" \
+                --json body --jq '.body' | grep -q "Breaking: yes"; then
+              echo "::warning::Breaking spec changes acknowledged via 'Breaking: yes' marker."

Relevance

●●● Strong

Clear reliability fix: gh pr view needs PR read permissions; teams usually accept minimal workflow
permission adjustments.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The workflow restricts token permissions to contents: read, while the newly added
breaking-change job uses gh pr view with GH_TOKEN to read PR metadata (the body), which
requires pull-request read permissions.

.github/workflows/foundation-gate.yml[19-21]
.github/workflows/foundation-gate.yml[106-115]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `breaking-change` job uses `gh pr view ... --json body` to read the pull request body, but the workflow permissions only include `contents: read`. With explicit permissions configured, GitHub does not grant other scopes implicitly, so the PR-body fetch can fail with 403 in breaking-change scenarios.

## Issue Context
This only triggers when `oasdiff` detects a breaking change (the path where the PR-body marker check matters), so the gate may become unusable for acknowledged breaking changes.

## Fix Focus Areas
- .github/workflows/foundation-gate.yml[19-21]
- .github/workflows/foundation-gate.yml[86-122]

## Suggested fix
Add `pull-requests: read` (preferably job-scoped for least privilege), e.g.:

```yml
breaking-change:
 permissions:
   contents: read
   pull-requests: read
```

(or add `pull-requests: read` to the workflow-level `permissions:` block if you want it shared across jobs).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Mutable oasdiff image tag ✓ Resolved 🐞 Bug ⛨ Security

Description

The breaking-change gate runs ghcr.io/tufin/oasdiff:latest, which is mutable; tool behavior can
change over time without repo changes, making CI non-reproducible and increasing supply-chain risk.

Code

.github/workflows/foundation-gate.yml[R109-110]

+          if docker run --rm -v /tmp/base:/base:ro -v "$PWD":/spec:ro ghcr.io/tufin/oasdiff:latest \
+               breaking --fail-on ERR /base/openapi.yaml /spec/openapi.yaml > /tmp/oasdiff.txt 2>&1; then

Relevance

●●● Strong

Accepted precedent: pin moving CI refs/inputs to immutable versions for determinism and supply-chain
safety.

PR-#7

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The docker invocation explicitly references ghcr.io/tufin/oasdiff:latest, which is a mutable tag
rather than a pinned version/digest.

.github/workflows/foundation-gate.yml[108-110]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The workflow uses `ghcr.io/tufin/oasdiff:latest`, a mutable tag. This can silently change CI behavior (unexpected pass/fail) and expands supply-chain risk.

## Issue Context
This is a contract gate; stability and reproducibility matter. Pinning the container to an immutable reference prevents unexpected drift.

## Fix Focus Areas
- .github/workflows/foundation-gate.yml[108-110]

## Suggested fix
Pin to a specific version and ideally a digest:

```bash
docker run ... ghcr.io/tufin/oasdiff@sha256:<digest> ...
```

Optionally add a short comment indicating how to update the digest when upgrading oasdiff.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. api-types.d.ts exceeds 500 lines 📘 Rule violation ⚙ Maintainability

Description

generated/api-types.d.ts is a newly added/generated file with ~3,573 lines, far exceeding the 500
line limit for touched source files. This increases maintenance burden and violates the repository
source-file length guideline.

Code

generated/api-types.d.ts[R3568-3571]

+            403: components["responses"]["Forbidden"];
+            429: components["responses"]["RateLimitError"];
+            503: components["responses"]["MoqJoinUnconfigured"];
+        };

Relevance

●● Moderate

Generated type file is intentionally committed, but no precedent on enforcing/waiving 500-line rule
for generated artifacts.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2497975 requires every touched source file to be ≤500 non-empty, non-comment lines.
The added generated/api-types.d.ts file is at least 3,573 lines long (see line numbers near the
end of the file), making it non-compliant with this limit.

Rule 2497975: Limit source file length to 500 lines of code
generated/api-types.d.ts[3568-3573]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR adds/commits `generated/api-types.d.ts`, which is thousands of lines long and exceeds the 500-line maximum for files touched by the change.

## Issue Context
The compliance rule applies to each touched source file; generated artifacts are not exempt per the checklist text.

## Fix Focus Areas
- generated/api-types.d.ts[1-20]
- generated/api-types.d.ts[3568-3573]

## Suggested remediation options
- Stop committing `generated/api-types.d.ts` and instead generate it in CI and publish it as a build artifact/package output.
- Or introduce a post-generation step that splits the output into multiple `.d.ts` modules (each <=500 LOC) with an `index.d.ts` re-exporting them.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

✅ Compliance rules (platform): 1 rule

✅ REVIEW.md

Review mode: ⚖️ Balanced: The PR adds behavior-affecting CI gates and pinned tooling around public API contract generation and breaking-change detection; despite the large generated artifact being mechanical, workflow correctness and contract enforcement warrant a careful single-pass review.

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

Qodo Fixer

✅ Merged (0) · ☑ Fixed (0)

Process

• No fixes were applied (no_fixes_applied)

[devin-ai-integration]

Devin Review found 4 new potential issues.

[devin-ai-integration]

🟡 Newly committed dependency lockfile is never used by the build, so tool versions still float

The build installs its tooling ad hoc instead of from the newly committed exact-version list (npm install --no-save --no-audit --no-fund openapi-typescript@7.13.0 at .github/workflows/foundation-gate.yml:78, and the same pattern at .github/workflows/foundation-gate.yml:51 and .github/workflows/foundation-gate.yml:59), so the reproducibility the change advertises is not actually in effect.

Impact: Indirect dependency versions can change between runs, so the generated-types comparison can fail for reasons unrelated to the specification, and package install hooks still execute.

Incomplete migration to lockfile-based installs

This PR adds package.json (with lint and gen:types scripts) and package-lock.json, and rewrites .gitignore:2-5 to state that "CI installs with npm ci --ignore-scripts". No job in .github/workflows/foundation-gate.yml runs npm ci, and neither npm script is invoked — spec-lint still uses npx --yes @redocly/cli@2.40.0 and npm install --no-save js-yaml@4.1.0, and sdk-types uses npm install --no-save openapi-typescript@7.13.0 plus npx openapi-typescript. Commits fc9bbb0/f4528e6 in this PR introduced npm ci --no-audit --no-fund --ignore-scripts and npm run lint / npm run gen:types; commit e41c5fd reverted those steps while keeping the lockfile and the .gitignore text.

Suggested change

	- name: Install tooling
	run: npm install --no-save --no-audit --no-fund openapi-typescript@7.13.0
	- name: Regenerate types and fail if the committed artifact drifted
	run: |
	npx openapi-typescript openapi.yaml -o generated/api-types.d.ts
	git diff --exit-code -- generated/api-types.d.ts
	- name: Install pinned tooling from lockfile
	# package.json pins the direct tools by exact version and package-lock.json pins the
	# full transitive tree, so npm ci is byte-reproducible across CI and local runs.
	run: npm ci --no-audit --no-fund --ignore-scripts
	- name: Regenerate types and fail if the committed artifact drifted
	run: |
	npm run gen:types
	git diff --exit-code -- generated/api-types.d.ts

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🔍 Final commit reverted three earlier review hardenings

Commit e41c5fd (head) reverted changes made by fc9bbb0, f4528e6, and 16e49cc in this same PR: the npm ci --ignore-scripts installs, the npm-script invocations, the deletion-proof drift check, and the oasdiff exit-code table handling. The commit message only mentions the oasdiff binary pinning, the pull-requests: read grant, and the GITHUB_BASE_REF substitution — the other reverts look like a bad rebase/force-push rather than a deliberate decision. Worth confirming with the author before merge (the individual regressions are reported separately as bugs).

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟨 oasdiff download runs unpinned tarball extraction into PATH with only a self-hosted checksum

The breaking-change job downloads an oasdiff release tarball and its checksums.txt from the same GitHub release and verifies one against the other (.github/workflows/foundation-gate.yml:109-117). Because both the artifact and the checksum come from the same mutable source, the verification only detects transport corruption, not a tampered/re-published release. The extracted contents are unpacked wholesale into /usr/local/bin, which is on PATH for all later steps of the job.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟨 Spec tooling is installed without the lockfile and with install scripts enabled

The CI jobs install tooling with npx --yes @redocly/cli@2.40.0 and npm install --no-save ... (.github/workflows/foundation-gate.yml:51, .github/workflows/foundation-gate.yml:59, .github/workflows/foundation-gate.yml:78) even though this PR commits a package-lock.json and .gitignore:2-5 states CI installs with npm ci --ignore-scripts. Transitive dependencies therefore resolve freshly on every run and package lifecycle install hooks execute in the CI environment.

---

Was this helpful? React with 👍 or 👎 to provide feedback.