AsyncAPI spec silently fails to load when spec produces info/warning diagnostics (e.g. AsyncAPI 3.0.0)

[asc-netlight]

Support for AsyncAPIs (3.0.0) are not working with either npx mint validate or npx mint dev, when an AsyncAPI returns a trivial warning. It always fails with the error

AsyncAPI file X defined in tab in your docs.json does not exist

even when the file exists and is valid.

Root cause: validateAsyncApi.js L19:26 in @mintlify/common treats any diagnostic as a hard failure:

if (diagnostics.length > 0) {  // blocks on severity 2 (info) too
  return {
       valid: false,
       errorMessage: errorMessages,
       document: undefined,
   };
}

AsyncAPI 3.0.0 triggers the asyncapi-latest-version info rule (severity 2), causing the document to be silently dropped. The file never reaches asyncApiFiles[], so the lookup in generateAsyncApiFromDocsConfig fails.

More precisely, the error message from the Parser from @asyncapi/parser reads:

"The latest version of AsyncAPi is not used. It is recommended update to the \"3.1.0\" version."

This conflicts what is expressed in the official documentation, that the document must follow Async API 3.0..

Proposed fix

Filter to errors only:

  const errors = diagnostics.filter((d) => d.severity === 0);
  if (errors.length > 0) { ... }

Workaround

A postinstall script that patches the file after each npm install:

  // scripts/patch-asyncapi-validator.js
  const fs = require('fs');
  const file = 'node_modules/@mintlify/common/dist/asyncapi/valid
  ateAsyncApi.js';
  let content = fs.readFileSync(file, 'utf8');

  if (!content.includes('severity === 0')) {
    content = content
      .replace(
        'if (diagnostics.length > 0) {',
        'const errors = diagnostics.filter((d) => d.severity ===
  0); if (errors.length > 0) {'
      )
      .replace('diagnostics.map((diagnostic) =>',
  'errors.map((diagnostic) =>');
    fs.writeFileSync(file, content);
    console.log('AsyncAPI patch applied');
  }

And then in package.json add "postinstall": "node scripts/patch-asyncapi-validator.js"