feat(rulesets): add unused components server rule (stoplightio#2097)

Author: jonaslagoni

docs/reference/asyncapi-rules.md

@@ -369,3 +369,15 @@ that acts as a library (a container storing reusable objects, leveraged by other
 specifications that reference those objects).
 
 **Recommended:** Yes
+
+### asyncapi-unused-components-server
+
+Potential unused reusable `server` entry has been detected.
+
+<!-- theme: warning -->
+
+_Warning:_ This rule may identify false positives when linting a specification
+that acts as a library (a container storing reusable objects, leveraged by other
+specifications that reference those objects).
+
+**Recommended:** Yes

packages/rulesets/src/asyncapi/__tests__/asyncapi-unused-components-server.test.ts

@@ -0,0 +1,40 @@
+import { DiagnosticSeverity } from '@stoplight/types';
+import produce from 'immer';
+import testRule from './__helpers__/tester';
+
+const document = {
+  asyncapi: '2.0.0',
+  servers: {
+    test: {
+      $ref: '#/components/servers/externallyDefinedServer',
+    },
+  },
+  channels: {},
+  components: {
+    servers: {
+      externallyDefinedServer: {},
+    },
+  },
+};
+
+testRule('asyncapi-unused-components-server', [
+  {
+    name: 'valid case',
+    document,
+    errors: [],
+  },
+
+  {
+    name: 'components.servers contains unreferenced objects',
+    document: produce(document, (draft: any) => {
+      delete draft.servers['test'];
+    }),
+    errors: [
+      {
+        message: 'Potentially unused components server has been detected.',
+        path: ['components', 'servers', 'externallyDefinedServer'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+]);

packages/rulesets/src/asyncapi/index.ts

@@ -381,5 +381,18 @@ export default {
         },
       },
     },
+    'asyncapi-unused-components-server': {
+      description: 'Potentially unused components server has been detected.',
+      recommended: true,
+      type: 'style',
+      resolved: false,
+      given: '$.components.servers',
+      then: {
+        function: unreferencedReusableObject,
+        functionOptions: {
+          reusableObjectsLocation: '#/components/servers',
+        },
+      },
+    },
   },
 };