feat: add API validation script with Zod schemas and CI workflow inte…

[kpj2006]

…gration

Addressed Issues:

Fixes #(issue number)

Screenshots/Recordings:

Additional Notes:

Checklist

• My code follows the project's code style and conventions
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have joined the Discord server and I will share a link to this PR with the project maintainers there
• I have read the Contributing Guidelines

⚠️ AI Notice - Important!

We encourage contributors to use AI tools responsibly when creating Pull Requests. While AI can be a valuable aid, it is essential to ensure that your contributions meet the task requirements, build successfully, include relevant tests, and pass all linters. Submissions that do not meet these standards may be closed without warning to maintain the quality and integrity of the project. Please take the time to understand the changes you are proposing and their impact.

Summary by CodeRabbit

• New Features
  • Added automated API and schema validation that runs on pushes and pull requests to help detect breaking GitHub API changes early.
  • Added local commands to run the same API/schema checks from the project root.
  • Expanded validation coverage to include organization, repository, and issue responses.
• Bug Fixes
  • Improved response validation so malformed or incompatible API data is flagged sooner.

[coderabbitai]

Warning

Review limit reached

@kpj2006, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 33 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5a1125c0-302b-4782-b3ea-ebb34bdec21f

📥 Commits

Reviewing files that changed from the base of the PR and between 8bf147f and 3a10e23.

📒 Files selected for processing (3)

• .github/workflows/api-validation.yml
• .github/workflows/build-matrix.yml
• scripts/validate-api.js

Walkthrough

This PR adds GitHub API validation tooling: reusable GraphQL queries, a Zod-based validation script for mock and live REST/GraphQL checks, and supporting Makefile, npm, and GitHub Actions wiring to run validation.

Changes

API Validation Tooling

Layer / File(s)	Summary
GraphQL query definitions src/services/queries.js	Adds GET_ORG_DETAILS, GET_ORG_REPOS, and GET_REPO_ISSUES exported GraphQL query templates with pagination variables.
Validation script setup and schemas scripts/validate-api.js	Adds script bootstrap, token/color setup, exported Zod schemas for REST and GraphQL responses, and mock fixture data.
Validation workflow and helpers scripts/validate-api.js	Implements REST and GraphQL fetch helpers, error reporting, the multi-step validation routine, result reporting, and fatal error handling.
Build and CI wiring Makefile, package.json, .github/workflows/api-validation.yml	Adds Makefile targets, a validate-api npm script and devDependencies, and a workflow that runs validation on push and pull request events.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested labels: Make Lang

Poem

A rabbit hops through YAML and code,
Checking schemas along the API road. 🐇
Mock data, live calls, all parsed with care,
Zod stands guard like a watchful hare.
Green checks bloom—hop, hop, hooray!

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: an API validation script with Zod schemas and CI workflow integration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​octokit/​graphql-schema@​15.26.1
	dotenv@​17.4.2
	zod@​4.4.3
	graphql@​17.0.2

View full report

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/api-validation.yml:
- Around line 21-27: The workflow uses mutable action tags for actions/checkout
and actions/setup-node; update both uses entries to immutable commit SHAs
instead of `@v4`. Keep the existing behavior in the api-validation workflow, but
pin the checkout and Node setup steps to specific SHA references so the workflow
is hardened against tag mutation.
- Around line 1-35: The API validation workflow is using default GITHUB_TOKEN
permissions and leaving checkout credentials persisted, which are unnecessary
for schema validation. Add an explicit least-privilege permissions block for the
workflow/job in api-validation.yml and configure the Checkout repository step to
avoid persisting credentials. Keep the change scoped to the validate job and
preserve the existing validate-api execution with GITHUB_TOKEN only if still
needed.

In `@scripts/validate-api.js`:
- Around line 225-239: fetchGraphQL currently only rejects on HTTP failures, so
GitHub GraphQL responses with a top-level errors array still flow into Zod and
hide the real API error. Update fetchGraphQL to inspect the parsed JSON response
and throw a descriptive error when errors is present before returning data, then
make the callers that validate GraphQLOrgDetailsSchema and the other GraphQL
schemas consume only the data payload after this check.
- Around line 315-439: The live REST validation logic in validate-api.js is
duplicated across the repository, contributors, issues, and rate-limit blocks,
making the flow hard to maintain and easy to drift. Extract the repeated
fetchREST + array check + safeParse + handleZodError + 403 handling into a
shared helper such as validateLiveRESTCollection, then call it from the existing
live REST sections using the specific URL, schema, and label for each resource.
Keep the existing logging behavior and use the same fetchREST, handleZodError,
and schema symbols so the refactor stays localized.
- Around line 210-223: The 403 handling in fetchREST and its downstream catch
blocks is relying on a message substring that never matches, so the
unauthenticated skip path is dead code. Update fetchREST to throw a 403-specific
signal that can be checked reliably, and change the affected catch blocks that
inspect err.message.includes('403') to use a structured status check like
err.status === 403 instead. Make sure the logic around fetchREST and the live
REST skip handling stays consistent so rate-limit/forbidden responses gracefully
skip instead of setting failed = true.
- Around line 25-152: The schemas in validate-api.js are still using deprecated
chained string format methods, especially `.url()`, which will break on a future
Zod major version. Update the affected fields in `OrganizationSchema`,
`RepositorySchema`, `ContributorSchema`, `IssueSchema`,
`GraphQLOrgDetailsSchema`, and `GraphQLRepoIssuesSchema` to use the top-level
`z.url()` form instead of `z.string().url()`. Keep the existing
optional/nullable structure intact while migrating each URL field to the new
API.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 38446e7a-f81c-4fa6-80bd-d992c4eb524b

📥 Commits

Reviewing files that changed from the base of the PR and between d904719 and 8543701.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (5)

• .github/workflows/api-validation.yml
• Makefile
• package.json
• scripts/validate-api.js
• src/services/queries.js

[github-actions]

⚠️ This PR has merge conflicts.

Please resolve the merge conflicts before review.

Your PR will only be reviewed by a maintainer after all conflicts have been resolved.

📺 Watch this video to understand why conflicts occur and how to resolve them:
https://www.youtube.com/watch?v=Sqsz1-o7nXk