feat(ls): add option to pass refractor plugins (#5003)

Author: glowcloud

packages/apidom-ls/README.md

@@ -37,7 +37,12 @@ The capabilities of the ApiDOM Language Service can be extended by providing cus
 ```ts
 import { DocumentLink } from 'vscode-languageserver-types';
 import { TextDocument } from 'vscode-languageserver-textdocument';
-import { Element } from '@swagger-api/apidom-core';
+import {
+  Element,
+  MemberElement,
+  isStringElement,
+} from "@swagger-api/apidom-core";
+import { InfoElement } from '@swagger-api/apidom-ns-asyncapi-2';
 import { getLanguageService, LinksProvider, config } from '@swagger-api/apidom-ls';
 import type {
   LanguageSettings,
@@ -161,13 +166,31 @@ customMetadata.rules = {
   },
 };
 
+// Defining custom refractor plugins
+
+const refractorPlugin = () => () => ({
+  visitor: {
+    MemberElement(element: MemberElement) {
+      if (
+        isStringElement(element.key) &&
+        element.key.equals("additionalInfo")
+      ) {
+        element.value = InfoElement.refract(element.value);
+      }
+    },
+  },
+});
+
 // Initializing ApiDOM Language Service with custom configuration
 
 const refLinksProvider = new RefLinksProvider();
 
 const customContext = {
   metadata: customMetadata,
   linksProviders: [refLinksProvider],
+  refractorPlugins: {
+    'asyncapi-2': [refractorPlugin()],
+  }
 };
 
 const languageService = getLanguageService(customContext);

packages/apidom-ls/src/apidom-language-service.ts

@@ -64,7 +64,15 @@ export default function getLanguageService(context: LanguageServiceContext): Lan
     metadata = context.metadata;
   }
   const documentCache = getDocumentCache<ParseResultElement>(10, 60, (document) =>
-    parse(document, metadata.metadataMaps, true, true, true, context.defaultContentLanguage),
+    parse(
+      document,
+      metadata.metadataMaps,
+      true,
+      true,
+      true,
+      context.defaultContentLanguage,
+      context.refractorPlugins,
+    ),
   );
 
   const languageSettings: LanguageSettings = {

packages/apidom-ls/src/apidom-language-types.ts

@@ -106,6 +106,7 @@ export interface LanguageServiceContext {
   symbolsContext?: SymbolsContext;
   colorsContext?: ColorsContext;
   linksContext?: LinksContext;
+  refractorPlugins?: RefractorPlugins;
 }
 
 /**
@@ -387,6 +388,11 @@ export interface LinksContext {
   modifierFunction?: LinksModifierFunction;
 }
 
+/**
+ * @public
+ */
+export type RefractorPlugins = Record<string, (() => unknown)[]>;
+
 /**
  * @public
  */

packages/apidom-ls/src/index.ts

@@ -61,6 +61,7 @@ export type {
   LinterFunction,
   LinterConditionTarget,
   DocumentationMeta,
+  RefractorPlugins,
 } from './apidom-language-types.ts';
 
 export {

packages/apidom-ls/src/parser-factory.ts

@@ -18,7 +18,7 @@ import { TextDocument } from 'vscode-languageserver-textdocument';
 import { ParseResultElement } from '@swagger-api/apidom-core';
 
 import { setMetadataMap, findNamespace } from './utils/utils.ts';
-import { ContentLanguage, MetadataMaps } from './apidom-language-types.ts';
+import { ContentLanguage, MetadataMaps, RefractorPlugins } from './apidom-language-types.ts';
 
 export interface ParserOptions {
   sourceMap?: boolean;
@@ -33,74 +33,119 @@ export async function parse(
   freeze = true,
   setMetadata = true,
   defaultContentLanguage?: ContentLanguage,
+  refractorPlugins?: RefractorPlugins,
 ): Promise<ParseResultElement> {
   // TODO improve detection mechanism
   const text: string = typeof textDocument === 'string' ? textDocument : textDocument.getText();
   let result;
   const contentLanguage = await findNamespace(text, defaultContentLanguage);
   if (contentLanguage.namespace === 'asyncapi' && contentLanguage.format === 'JSON') {
-    result = await asyncapi2AdapterJson.parse(text, { sourceMap: true });
+    const options: Record<string, unknown> = {
+      sourceMap: true,
+      refractorOpts: {
+        plugins: [...(refractorPlugins?.['asyncapi-2'] || [])],
+      },
+    };
+
+    result = await asyncapi2AdapterJson.parse(text, options);
   } else if (contentLanguage.namespace === 'asyncapi' && contentLanguage.format === 'YAML') {
     const options: Record<string, unknown> = {
       sourceMap: true,
+      refractorOpts: {
+        plugins: [
+          registerPlugins && refractorPluginReplaceEmptyElementAsyncAPI2(),
+          ...(refractorPlugins?.['asyncapi-2'] || []),
+        ].filter(Boolean),
+      },
     };
-    if (registerPlugins) {
-      options.refractorOpts = { plugins: [refractorPluginReplaceEmptyElementAsyncAPI2()] };
-    }
+
     result = await asyncapi2AdapterYaml.parse(text, options);
   } else if (
     contentLanguage.namespace === 'openapi' &&
     contentLanguage.version === '2.0' &&
     contentLanguage.format === 'JSON'
   ) {
-    result = await openapi2AdapterJson.parse(text, { sourceMap: true });
+    const options: Record<string, unknown> = {
+      sourceMap: true,
+      refractorOpts: {
+        plugins: [...(refractorPlugins?.['openapi-2'] || [])],
+      },
+    };
+
+    result = await openapi2AdapterJson.parse(text, options);
   } else if (
     contentLanguage.namespace === 'openapi' &&
     contentLanguage.version === '2.0' &&
     contentLanguage.format === 'YAML'
   ) {
     const options: Record<string, unknown> = {
       sourceMap: true,
+      refractorOpts: {
+        plugins: [
+          registerPlugins && refractorPluginReplaceEmptyElementOpenAPI2(),
+          ...(refractorPlugins?.['openapi-2'] || []),
+        ].filter(Boolean),
+      },
     };
-    if (registerPlugins) {
-      options.refractorOpts = { plugins: [refractorPluginReplaceEmptyElementOpenAPI2()] };
-    }
+
     result = await openapi2AdapterYaml.parse(text, options);
   } else if (
     contentLanguage.namespace === 'openapi' &&
     contentLanguage.version?.startsWith('3.0') &&
     contentLanguage.format === 'JSON'
   ) {
-    result = await openapi3_0AdapterJson.parse(text, { sourceMap: true });
+    const options: Record<string, unknown> = {
+      sourceMap: true,
+      refractorOpts: {
+        plugins: [...(refractorPlugins?.['openapi-3-0'] || [])],
+      },
+    };
+
+    result = await openapi3_0AdapterJson.parse(text, options);
   } else if (
     contentLanguage.namespace === 'openapi' &&
     contentLanguage.version?.startsWith('3.0') &&
     contentLanguage.format === 'YAML'
   ) {
     const options: Record<string, unknown> = {
       sourceMap: true,
+      refractorOpts: {
+        plugins: [
+          registerPlugins && refractorPluginReplaceEmptyElementOpenAPI3_0(),
+          ...(refractorPlugins?.['openapi-3-0'] || []),
+        ].filter(Boolean),
+      },
     };
-    if (registerPlugins) {
-      options.refractorOpts = { plugins: [refractorPluginReplaceEmptyElementOpenAPI3_0()] };
-    }
+
     result = await openapi3_0AdapterYaml.parse(text, options);
   } else if (
     contentLanguage.namespace === 'openapi' &&
     contentLanguage.version?.startsWith('3.1') &&
     contentLanguage.format === 'JSON'
   ) {
-    result = await openapi3_1AdapterJson.parse(text, { sourceMap: true });
+    const options: Record<string, unknown> = {
+      sourceMap: true,
+      refractorOpts: {
+        plugins: [...(refractorPlugins?.['openapi-3-1'] || [])],
+      },
+    };
+
+    result = await openapi3_1AdapterJson.parse(text, options);
   } else if (
     contentLanguage.namespace === 'openapi' &&
     contentLanguage.version?.startsWith('3.1') &&
     contentLanguage.format === 'YAML'
   ) {
     const options: Record<string, unknown> = {
       sourceMap: true,
+      refractorOpts: {
+        plugins: [
+          registerPlugins && refractorPluginReplaceEmptyElementOpenAPI3_1(),
+          ...(refractorPlugins?.['openapi-3-1'] || []),
+        ].filter(Boolean),
+      },
     };
-    if (registerPlugins) {
-      options.refractorOpts = { plugins: [refractorPluginReplaceEmptyElementOpenAPI3_1()] };
-    }
+
     result = await openapi3_1AdapterYaml.parse(text, options);
   } else if (contentLanguage.namespace === 'ads' && contentLanguage.format === 'JSON') {
     result = await adsAdapterJson.parse(text, { sourceMap: true });

packages/apidom-ls/test/fixtures/parse/refractor-plugins/asyncapi-2.json

@@ -0,0 +1,11 @@
+{
+  "asyncapi": "2.6.0",
+  "info": {
+    "title": "Test",
+    "version": "1.0.0"
+  },
+  "channels": {},
+  "additionalInfo": {
+    "title": "Additional Info Test"
+  }
+}

packages/apidom-ls/test/fixtures/parse/refractor-plugins/asyncapi-2.yaml

@@ -0,0 +1,7 @@
+asyncapi: '2.6.0'
+info:
+  title: Test
+  version: '1.0.0'
+channels:
+additionalInfo:
+  title: Additional Info Test

packages/apidom-ls/test/fixtures/parse/refractor-plugins/openapi-2.json

@@ -0,0 +1,11 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "Test",
+    "version": "1.0.0"
+  },
+  "paths": {},
+  "additionalInfo": {
+    "title": "Additional Info Test"
+  }
+}

packages/apidom-ls/test/fixtures/parse/refractor-plugins/openapi-2.yaml

@@ -0,0 +1,7 @@
+swagger: '2.0'
+info:
+  title: Test
+  version: 1.0.0
+paths:
+additionalInfo:
+  title: Additional Info Test

packages/apidom-ls/test/fixtures/parse/refractor-plugins/openapi-3-0.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.0.4",
+  "info": {
+    "title": "Test",
+    "version": "1.0.0"
+  },
+  "paths": {},
+  "additionalInfo": {
+    "title": "Additional Info Test"
+  }
+}