feat(parser-adapter-asyncapi-yaml-3): add package for parser adapter asyncapi yaml 3

Author: lukaszzazulak

packages/apidom-ls/package.json

@@ -106,6 +106,7 @@
     "@swagger-api/apidom-parser-adapter-api-design-systems-yaml": "^1.0.0-rc.3",
     "@swagger-api/apidom-parser-adapter-asyncapi-json-2": "^1.0.0-rc.3",
     "@swagger-api/apidom-parser-adapter-asyncapi-yaml-2": "^1.0.0-rc.3",
+    "@swagger-api/apidom-parser-adapter-asyncapi-yaml-3": "^1.0.0-beta.0",
     "@swagger-api/apidom-parser-adapter-json": "^1.0.0-rc.3",
     "@swagger-api/apidom-parser-adapter-openapi-json-2": "^1.0.0-rc.3",
     "@swagger-api/apidom-parser-adapter-openapi-json-3-0": "^1.0.0-rc.3",

packages/apidom-ls/src/services/validation/validation-service.ts

@@ -450,6 +450,10 @@ export class DefaultValidationService implements ValidationService {
 
     let processedText;
     const nameSpace = await findNamespace(text, this.settings?.defaultContentLanguage);
+    // TODO: Turned off validation, because we will implement it in the future.
+    if (nameSpace.namespace === 'asyncapi' && nameSpace.version === '3.0.0') {
+      return [];
+    }
     let docNs: string = nameSpace.namespace;
     // no API document has been parsed
     if (result.annotations) {

packages/apidom-ls/src/utils/utils.ts

@@ -6,6 +6,7 @@ import * as openapi31xAdapterJson from '@swagger-api/apidom-parser-adapter-opena
 import * as openapi31xAdapterYaml from '@swagger-api/apidom-parser-adapter-openapi-yaml-3-1';
 import * as asyncapi2AdapterJson from '@swagger-api/apidom-parser-adapter-asyncapi-json-2';
 import * as asyncapi2AdapterYaml from '@swagger-api/apidom-parser-adapter-asyncapi-yaml-2';
+import * as asyncapi3AdapterYaml from '@swagger-api/apidom-parser-adapter-asyncapi-yaml-3';
 import * as adsAdapterJson from '@swagger-api/apidom-parser-adapter-api-design-systems-json';
 import * as adsAdapterYaml from '@swagger-api/apidom-parser-adapter-api-design-systems-yaml';
 import * as adapterJson from '@swagger-api/apidom-parser-adapter-json';
@@ -836,6 +837,19 @@ export async function findNamespace(
     };
   }
 
+  if (await asyncapi3AdapterYaml.detect(text)) {
+    const asyncapi3YamlMatch = text.match(asyncapi3AdapterYaml.detectionRegExp)!;
+    const groups = asyncapi3YamlMatch.groups!;
+    const version = groups.version_json ?? groups.version_yaml;
+
+    return {
+      namespace: 'asyncapi',
+      version,
+      format: 'YAML',
+      mediaType: asyncapi3AdapterYaml.mediaTypes.findBy(version, 'yaml'),
+    };
+  }
+
   if (await openapi2AdapterJson.detect(text)) {
     const openapi2JsonMatch = text.match(openapi2AdapterJson.detectionRegExp)!;
     const groups = openapi2JsonMatch.groups!;

packages/apidom-parser-adapter-asyncapi-yaml-3/.eslintignore

@@ -0,0 +1,8 @@
+/**/*.js
+/**/*.mjs
+/**/*.cjs
+/dist
+/types
+/config
+/.nyc_output
+/node_modules

packages/apidom-parser-adapter-asyncapi-yaml-3/.gitignore

@@ -0,0 +1,7 @@
+/src/**/*.mjs
+/src/**/*.cjs
+/test/**/*.mjs
+/dist
+/types
+/NOTICE
+/swagger-api-apidom-parser-adapter-asyncapi-yaml-3-*.tgz

packages/apidom-parser-adapter-asyncapi-yaml-3/.mocharc.json

@@ -0,0 +1,8 @@
+{
+  "extensions": ["ts"],
+  "loader": "ts-node/esm",
+  "recursive": true,
+  "spec": "test/**/*.ts",
+  "file": ["test/mocha-bootstrap.ts"],
+  "ignore": ["test/perf/**/*.ts"]
+}

packages/apidom-parser-adapter-asyncapi-yaml-3/.npmrc

@@ -0,0 +1,2 @@
+save-prefix="="
+save=false

packages/apidom-parser-adapter-asyncapi-yaml-3/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

packages/apidom-parser-adapter-asyncapi-yaml-3/README.md

@@ -0,0 +1,92 @@
+# @swagger-api/apidom-parser-adapter-asyncapi-yaml-3
+
+`@swagger-api/apidom-parser-adapter-asyncapi-yaml-3` is a parser adapter for following AsyncAPI specification versions defined in [YAML format](https://yaml.org/spec/1.2/spec.html):
+
+- [AsyncAPI 3.0.0 specification](https://github.com/asyncapi/spec/blob/v3.0.0/spec/asyncapi.md)
+
+Under the hood this adapter uses [@swagger-api/apidom-parser-adapter-yaml-1-2](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-yaml-1-2)
+to parse a source string into generic ApiDOM in [base ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom#base-namespace)
+
+[//]: # (// TODO: The below link does not have content yet.)
+which is then refracted with [AsyncApi 3.x.y Refractors](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-asyncapi-3#refractors).
+
+## Installation
+
+After [prerequisites](https://github.com/swagger-api/apidom/blob/main/README.md#prerequisites) for installing this package are satisfied, you can install it
+via [npm CLI](https://docs.npmjs.com/cli) by running the following command:
+
+```sh
+ $ npm install @swagger-api/@swagger-api/apidom-parser-adapter-asyncapi-yaml-3
+```
+
+## Parser adapter API
+
+This parser adapter is fully compatible with parser adapter interface required by [@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser#mounting-parser-adapters)
+and implements all required properties.
+
+### mediaTypes
+
+Defines list of media types that this parser adapter recognizes.
+
+```js
+[
+  'application/vnd.aai.asyncapi;version=3.0.0',
+  'application/vnd.aai.asyncapi+yaml;version=3.0.0',
+]
+```
+
+### detect
+
+[Detection](https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-asyncapi-yaml-3/src/adapter.ts#L13) is based on a regular expression matching required AsyncApi 3.x.y specification symbols in YAML format.
+
+### namespace
+
+[//]: # (// TODO: Below link does not have content yet.)
+This adapter exposes an instance of [AsyncApi 3.x.y ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-asyncapi-3#asyncapi-2xy-namespace).
+
+### parse
+
+`parse` function consumes various options as a second argument. Here is a list of these options:
+
+Option | Type | Default | Description
+--- | --- | --- | ---
+<a name="specObj"></a>`specObj` | `Object` | [Specification Object](https://github.com/swagger-api/apidom/blob/main/packages/apidom-ns-asyncapi-3/src/refractor/specification.ts) | This specification object drives the YAML AST transformation to AsyncAPI 3.x ApiDOM namespace.
+<a name="sourceMap"></a>`sourceMap` | `Boolean` | `false` | Indicate whether to generate source maps.
+<a name="refractorOpts"></a>`refractorOpts` | `Object` | `{}` | Refractor options are [passed to refractors](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-asyncapi-3#refractor-plugins) during refracting phase.
+
+All unrecognized arbitrary options will be ignored.
+
+## Usage
+
+This parser adapter can be used directly or indirectly via [@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser).
+
+### Direct usage
+
+During direct usage you don't need to provide `mediaType` as the `parse` function is already pre-bound
+with [supported media types](#mediatypes).
+
+```js
+import { parse, detect } from '@swagger-api/apidom-parser-adapter-asyncapi-yaml-3';
+
+// detecting
+await detect('asyncapi: 3.0.0'); // => true
+await detect('test'); // => false
+
+// parsing
+const parseResult = await parse('asyncapi: 3.0.0', { sourceMap: true });
+```
+
+### Indirect usage
+
+You can omit the `mediaType` option here, but please read [Word on detect vs mediaTypes](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser#word-on-detect-vs-mediatypes) before you do so.
+
+```js
+import ApiDOMParser from '@swagger-api/apidom-parser';
+import * as asyncApiYamlAdapter from '@swagger-api/apidom-parser-adapter-asyncapi-yaml-3';
+
+const parser = new ApiDOMParser();
+
+parser.use(asyncApiYamlAdapter);
+
+const parseResult = await parser.parse('asyncapi: 3.0.0', { mediaType: asyncApiYamlAdapter.mediaTypes.latest('yaml') });
+```

packages/apidom-parser-adapter-asyncapi-yaml-3/config/api-extractor/api-extractor.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../../../api-extractor.json",
+  "mainEntryPointFilePath": "../../types/adapter.d.ts"
+}