feat(ci): add openapi spec sync check

[notrab]

Lite PR

Tip: Review docs on the ENSNode PR process

Summary

• Add openapi-sync-check CI job to test_ci.yml that verifies the committed ensapi-openapi.json matches what pnpm generate:openapi produces.

---

Why

• The committed OpenAPI spec can silently drift from the actual API code. This CI check catches that on every PR.
• The old shell script (in https://github.com/namehash/ensnode/pull/1550/changes#diff-4877d60558688cfe43cd6439318422cec1e180fd252565f5a5dc8a2b322bd0ae) was built around spinning up an ENSApi server to fetch the spec at runtime. Since we now have generateOpenApi31Document() which generates the spec directly, the script is unnecessary.

---

Testing

• Not tested locally, the CI job itself is the test. It runs pnpm generate:openapi and checks git diff.

---

Notes for Reviewer (Optional)

• The old script handled server lifecycle (startup, polling, cleanup traps, mock config). The new approach is two workflow steps with no extra files.
• No changeset needed as this is a CI-only change.

---

Pre-Review Checklist (Blocking)

• This PR does not introduce significant changes and is low-risk to review quickly.
• Relevant changesets are included (or are not required)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 68fc5e9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
admin.ensnode.io	Ready	Preview, Comment	Mar 6, 2026 8:01am
ensnode.io	Ready	Preview, Comment	Mar 6, 2026 8:01am
ensrainbow.io	Ready	Preview, Comment	Mar 6, 2026 8:01am

[coderabbitai]

Warning

Rate limit exceeded

@notrab has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 16 minutes and 32 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 62203585-fa35-485b-9abd-0ac903c4e3e5

📥 Commits

Reviewing files that changed from the base of the PR and between 7d48611 and 68fc5e9.

📒 Files selected for processing (2)

• .github/workflows/test_ci.yml
• README.md

📝 Walkthrough

Walkthrough

Adds a CI job that generates and verifies the repository OpenAPI spec against the committed docs/docs.ensnode.io/ensapi-openapi.json, and updates that OpenAPI spec (v1.5.1 → v1.6.0) to expose new public config properties and reshape ensIndexerPublicConfig.

Changes

Cohort / File(s)	Summary
CI Workflow OpenAPI Verification ​.github/workflows/test_ci.yml	New CI job "OpenAPI Spec Sync Check": checks out repo, sets up Node, runs pnpm generate:openapi, compares generated spec to docs/docs.ensnode.io/ensapi-openapi.json (fails with diff if out-of-sync), and runs Mintlify validation.
OpenAPI Spec (schema changes) docs/docs.ensnode.io/ensapi-openapi.json	Version bumped 1.5.1 → 1.6.0. Adds databaseSchemaName, ensRainbowPublicConfig (with nested labelSet and recordsCount), indexedChainIds, and isSubgraphCompatible to ensIndexerPublicConfig; refactors versionInfo (removes rainbow fields, keeps ensNormalize); updates required properties and ordering. No API paths/responses changed.

Sequence Diagram(s)

sequenceDiagram
    participant Repo as Repository
    participant CI as CI Runner
    participant Node as Node / pnpm
    participant Committed as Committed OpenAPI (`docs/.../ensapi-openapi.json`)
    participant Mintlify as Mintlify Validator

    CI->>Repo: checkout
    CI->>Node: setup Node & pnpm
    CI->>Node: run `pnpm generate:openapi` (-> generated.json)
    Node->>CI: generated.json
    CI->>Committed: compare generated.json ↔ committed spec
    alt diff or missing
        CI->>CI: fail job (print diff & instructions)
    else in sync
        CI->>CI: print success
        CI->>Mintlify: validate generated.json
        Mintlify->>CI: validation result
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I twitched my nose and nudged the tree,
Specs aligned — now everyone can see.
CI hums, the JSON sings in sync,
I ate a carrot, gave a wink.
Hooray for tidy docs and devs! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding an OpenAPI spec sync check to the CI workflow. It is concise and directly reflects the primary objective of the pull request.
Description check	✅ Passed	The pull request description follows the required template with all key sections completed: Summary, Why, Testing, Notes for Reviewer, and Pre-Review Checklist. All required information is present and well-articulated.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch openapi-spec-sync-check

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

This PR adds an openapi-sync-check CI job to test_ci.yml that ensures the committed docs/docs.ensnode.io/ensapi-openapi.json stays in sync with what pnpm generate:openapi produces from the current code. The job runs on every push and PR, replacing the need for the previous runtime-based shell script approach.

• New CI job (openapi-sync-check) checks out the repo, installs dependencies via the shared setup_node_environment action, runs pnpm generate:openapi, and then uses git diff --quiet to detect any drift between the generated spec and the committed one.
• The script under the hood (scripts/generate-ensapi-openapi.ts) calls generateOpenApi31Document() — a deterministic, server-free generator — and then formats the output with Biome, making the check reproducible across environments.
• The error path provides clear, actionable output including the colored diff and instructions to re-run pnpm generate:openapi and commit the result.
• Minor: git diff --quiet only detects changes to tracked files. If ensapi-openapi.json were ever removed from git tracking, a freshly generated (untracked) file would not be caught by the check. This is a low-risk edge case given the file is firmly committed, but an additional git ls-files --error-unmatch guard could make the check fully airtight.

Confidence Score: 5/5

• This PR is safe to merge — it is a purely additive CI-only change with no impact on application code.
• The change introduces a single new CI job with straightforward, well-understood shell logic. The git diff --quiet pattern is an established idiom for sync checks. The generate:openapi script is deterministic (no timestamps, no random values) and uses a pinned Biome version for formatting consistency. No application code, dependencies, or existing workflows are modified.
• No files require special attention.

Important Files Changed

Filename	Overview
.github/workflows/test_ci.yml	Adds a new openapi-sync-check CI job that generates the OpenAPI spec via pnpm generate:openapi and verifies it matches the committed ensapi-openapi.json using git diff. Logic is correct for tracked files; minor edge case exists if the file were ever untracked.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([GitHub Actions Trigger]) --> B[actions/checkout v4]
    B --> C[setup_node_environment\npnpm install]
    C --> D[pnpm generate:openapi]
    D --> E[generateOpenApi31Document]
    E --> H[Write ensapi-openapi.json]
    H --> I[Format with Biome]
    I --> J{git diff --quiet\nensapi-openapi.json}
    J -- Diff detected --> K[Print error and diff\nexit 1]
    J -- No diff --> L[OpenAPI spec is in sync\nexit 0]
    K --> M([CI FAIL])
    L --> N([CI PASS])

Loading

_{Last reviewed commit: ee1da07}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/test_ci.yml:
- Around line 74-75: The workflow step currently runs an unpinned Mintlify CLI
via the command "pnpm dlx mintlify openapi-check
docs/docs.ensnode.io/ensapi-openapi.json", which can pull different CLI versions
and cause flaky CI; update that step to pin an explicit Mintlify version by
changing the invocation to "pnpm dlx mintlify@<version> openapi-check
docs/docs.ensnode.io/ensapi-openapi.json" (replace <version> with the tested
release you want to lock to), then run the pipeline and commit the updated
workflow.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ef440714-4222-46e2-b490-867c971405b3

📥 Commits

Reviewing files that changed from the base of the PR and between ee1da07 and 3cdc4e9.

📒 Files selected for processing (2)

• .github/workflows/test_ci.yml
• docs/docs.ensnode.io/ensapi-openapi.json

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/test_ci.yml:
- Around line 74-75: The workflow step named "Validate OpenAPI spec with
Mintlify" uses an invalid package version syntax `mint@@^4.1.0`; change the
command invoked by that step to use a single `@` for versioning (i.e.,
`mint@^4.1.0`) so `pnpm dlx` can resolve the package correctly and the OpenAPI
validation runs.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: bd2259dd-33f6-4746-9962-198c01772d61

📥 Commits

Reviewing files that changed from the base of the PR and between 3cdc4e9 and 7d48611.

📒 Files selected for processing (1)

• .github/workflows/test_ci.yml