fix: resolve $ref in docs.json for OpenAPI routes coverage check

[curquiza]

Summary

• The CI check Require all OpenAPI routes in docs.json was failing because navigation data (including OpenAPI routes) was moved from docs.json into config/navigation.json, referenced via a $ref pointer
• The script check-openapi-routes-coverage.mjs now resolves $ref pointers recursively before walking the tree, so it works regardless of how the navigation is split across files
• Updated the success message to mention "referenced files" for accuracy

Fixes #3567

Test plan

• Script passes with all 138 routes present
• Script fails with exit code 1 when a route is removed from navigation.json

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Improved API documentation coverage validation to expand referenced definitions so coverage includes routes pulled in via references.
  • Added detection for circular references to prevent infinite processing and surface errors when cycles exist.
  • Updated success messaging to clearly state coverage now accounts for both OpenAPI routes and referenced files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 05a5795c-f9b5-4e0b-998a-c08c37d48134

📥 Commits

Reviewing files that changed from the base of the PR and between 02a7f21 and d80f94b.

📒 Files selected for processing (1)

• scripts/check-openapi-routes-coverage.mjs

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/check-openapi-routes-coverage.mjs

---

📝 Walkthrough

Walkthrough

The script now resolves JSON $ref pointers in docs.json before extracting API routes, adding cycle detection and expanding referenced files; route extraction then runs on the expanded docs and the success message was updated to reflect covered referenced files.

Changes

Reference Resolution for Docs Coverage

Layer / File(s)	Summary
Dependencies scripts/check-openapi-routes-coverage.mjs	dirname is added to the path module imports to compute base directories for resolving reference targets.
Core Resolution Logic scripts/check-openapi-routes-coverage.mjs	New resolveRefs(obj, baseDir) function recursively walks objects and arrays, loading and parsing files referenced by $ref pointers and continuing resolution within their contents; it detects and throws on circular $ref cycles.
Integration scripts/check-openapi-routes-coverage.mjs	Docs loading is updated to parse docs.json into rawDocsJson and then apply resolveRefs() (with dirname(DOCS_JSON_PATH)) to expand all references before route extraction begins.
Output Message scripts/check-openapi-routes-coverage.mjs	Success log is updated to explicitly indicate coverage applies to both OpenAPI routes and referenced files.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hopping through references with glee,
The resolver peeks where pointers be.
No cycles hiding in the stack so deep,
All routes and refs now wake from sleep.
🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: resolving $ref pointers in docs.json for the OpenAPI routes coverage check script.
Linked Issues check	✅ Passed	The PR fully addresses issue #3567 by implementing $ref resolution in the coverage check script to validate OpenAPI routes across referenced files.
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing the OpenAPI routes coverage check as required by issue #3567; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/openapi-routes-coverage-navigation-json

---

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
meilisearch-documentation	🟢 Ready	View Preview	May 5, 2026, 1:58 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@scripts/check-openapi-routes-coverage.mjs`:
- Around line 95-113: The resolveRefs function lacks cycle detection and will
infinite-recurse on circular $ref chains; add a visited/stack parameter (e.g.,
visitedPaths or refStack) to resolveRefs and push the resolved refPath (from
resolve(baseDir, obj["$ref"])) before recursing, check at the top whether
refPath is already in the stack and throw a clear error including the circular
chain if so, and ensure you pop the refPath after processing; update all
recursive calls (array, object entries, and the $ref branch) to pass along the
visited/stack so cycles like A->B->A are detected and fail fast.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 78888afa-a899-4759-8fee-f5f559e84228

📥 Commits

Reviewing files that changed from the base of the PR and between 31660b4 and 02a7f21.

📒 Files selected for processing (1)

• scripts/check-openapi-routes-coverage.mjs