fix(openapi): HATEOAS: resolve cross-schema dependencies regardless of loading order

[arnaud]

The fix ensures that there is no correct or incorrect order of swaggers - whatever their order, schema loading and HATEOAS cross-referencing works reliably through coordinated batch processing with proper dependency resolution.

Description

Core Issue: HATEOAS support was unreliable due to order dependency - when Schema A referenced operations from Schema B, it would fail if Schema A was loaded before Schema B.

Solution: Implemented context-aware batch loading that resolves cross-schema dependencies regardless of loading order.

Fixes #8654

Type of change

• [x] Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

• [x] HATEOAS should load schemas successfully regardless of order using batch loading
• [x] HATEOAS should handle backward compatibility with single schema loading

Test Environment:

• OS:
• @graphql-mesh/...:
• NodeJS:

Checklist:

• [x] I have followed the CONTRIBUTING doc and the style guidelines of this project
• [x] I have performed a self-review of my own code
• [x] I have commented my code, particularly in hard-to-understand areas
• [ ] I have made corresponding changes to the documentation
• [x] My changes generate no new warnings
• [x] I have added tests that prove my fix is effective or that my feature works, and I have added a changeset using yarn changeset that bumps the version
• [x] New and existing unit tests and linter rules pass locally with my changes
• [ ] Any dependent changes have been merged and published in downstream modules

Further comments

1. Context-Aware Loading System

• Added HATEOASContext interface to manage cross-schema dependencies
• Replaced global futureLinks state with context-specific management
• Added optional hateoasContext parameter for coordinated loading

2. Batch Loading Function

export async function getJSONSchemaOptionsFromMultipleOpenAPIOptions(
  schemas: Array<{name: string, options: GetJSONSchemaOptionsFromOpenAPIOptionsParams}>
)

• Loads multiple schemas with shared context
• Resolves cross-references in multi-pass approach
• No timeout issues or order dependencies

3. Improved HATEOAS Resolution

• Enhanced path matching to handle query parameters properly
• Skip timeouts in batch mode for faster processing
• Better error handling and logging

[coderabbitai[bot]]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added support for loading multiple OpenAPI schemas in batch mode with robust cross-schema HATEOAS link resolution, ensuring correct behavior regardless of schema loading order.

• Bug Fixes

  • Resolved issues with HATEOAS cross-references between schemas, preventing dependency or timeout problems when schemas reference each other.

• Tests

  • Introduced new tests to verify successful batch loading and cross-schema HATEOAS resolution, as well as backward compatibility for single schema loading.

• Chores

  • Updated .gitignore to exclude eslint_report.json from version control.

Summary by CodeRabbit

• New Features
  • Added support for loading and resolving HATEOAS links across multiple OpenAPI schemas in batch mode, improving cross-schema reference handling.
• Bug Fixes
  • Enhanced resolution of HATEOAS links to prevent dependency or timeout issues when schemas reference each other.
• Tests
  • Introduced new tests to verify correct multi-schema loading and backward compatibility with single schema loading.

Walkthrough

The changes introduce a shared context mechanism for HATEOAS link resolution across multiple OpenAPI schemas, enabling robust cross-schema references regardless of load order. A new batch loading function and related tests are added, while maintaining backward compatibility with the previous single-schema approach.

Changes

File(s)	Change Summary
packages/loaders/openapi/src/getJSONSchemaOptionsFromOpenAPIOptions.ts	Added HATEOASContext interface, exported futureLinks, updated main function for context-aware link resolution, and introduced batch loading function for multiple schemas.
packages/loaders/openapi/tests/hateoas-ordering.test.ts	Added new tests for cross-schema HATEOAS link resolution and backward compatibility with single schema loading.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant BatchLoader as getJSONSchemaOptionsFromMultipleOpenAPIOptions
    participant SchemaLoader as getJSONSchemaOptionsFromOpenAPIOptions
    participant HATEOASContext

    Caller->>BatchLoader: Provide array of schemas
    BatchLoader->>HATEOASContext: Initialize context
    loop For each schema
        BatchLoader->>SchemaLoader: Load schema with HATEOASContext
        SchemaLoader->>HATEOASContext: Register loaded schema
    end
    loop Resolve future links (max retries)
        BatchLoader->>HATEOASContext: Attempt to resolve all pending links
        HATEOASContext-->>BatchLoader: Unresolved links (if any)
    end
    BatchLoader-->>Caller: Return loaded schemas with resolved links

Assessment against linked issues

Objective	Addressed	Explanation
Resolve cross-schema HATEOAS dependencies regardless of schema loading order (#8654)	✅
Ensure backward compatibility for single schema loading (#8654)	✅
Add tests verifying cross-schema and single schema HATEOAS resolution (#8654)	✅

Poem

In a warren of schemas, links used to stray,
But now with shared context, they all find their way.
No matter the order, each reference is clear—
Cross-schema confusion? No longer here!
Batch loading in harmony, the rabbits all cheer! 🐇✨

[!WARNING] There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/loaders/openapi/src/getJSONSchemaOptionsFromOpenAPIOptions.ts

Oops! Something went wrong! :(

ESLint: 9.27.0

ESLint couldn't find an eslint.config.(js|mjs|cjs) file.

From ESLint v9.0.0, the default configuration file is now eslint.config.js. If you are using a .eslintrc.* file, please follow the migration guide to update your configuration file to the new format:

https://eslint.org/docs/latest/use/configure/migration-guide

If you still have problems after following the migration guide, please stop by https://eslint.org/chat/help to chat with the team.

✨ Finishing Touches

• [ ] 📝 Generate Docstrings

---

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.