fix(cli): resolve external JSON references in AsyncAPI specs

[devin-ai-integration]

Description

Fixes external JSON references ($ref) in AsyncAPI specifications not being resolved. Previously, AsyncAPI specs with references like $ref: "./schemas/file.yml#/Schema" would fail to resolve, resulting in empty messages and missing types.

Link to Devin run: https://app.devin.ai/sessions/9fadf9f4b75a485db4df87fba1fa910d
Requested by: [email protected]

Changes Made

• Added custom resolveLocalFileRefs function in loadAsyncAPI.ts to resolve local file references
• Only resolves local file references (e.g., ./schemas/file.yml#/Schema) while preserving URL references (http://, https://) for the AsyncAPI converter to handle
• Handles JSON pointer navigation (e.g., #/SpeakV1Encoding) to extract specific schemas from referenced files
• Includes circular reference detection to prevent infinite loops
• Updated test snapshots to reflect the fix (external references now properly resolved)

Updates since last revision

Initially attempted to use @redocly/openapi-core's bundle function (same as OpenAPI), but this resolved URL references too aggressively, breaking the AsyncAPI converter which expects URL refs to retain their $ref property. Switched to a custom local-file-only resolver that preserves URL references.

Testing

• Existing test fixture asyncapi-json-refs (from PR chore(cli): add test for AsyncAPI with JSON references to external files #11770) now passes with resolved references
• url-reference test continues to pass (URL refs preserved correctly)
• Snapshots updated showing:
  • plantUpdates channel now has messages (previously empty [])
  • SpeakV1Encoding type is now included in types
  • ChannelsPlantUpdatesSubscribeEncoding enum properly extracted
• Lint checks pass (pnpm run check)

Review Checklist

• Verify resolveLocalFileRefs handles edge cases correctly (missing files, invalid JSON pointers)
• Confirm circular reference detection works as expected
• Check that URL references (http/https) are preserved and not resolved
• Verify JSON pointer navigation handles nested paths correctly

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring