feat: add Spectral rule to validate operation messages (#911)

* feat: add Spectral rule to validate operation messages

* fix test example

* be more precise when matching the json pointer

* improve test by testing multiple messages in operation

Author: smoya

src/ruleset/index.ts

@@ -1,5 +1,6 @@
 import { coreRuleset, recommendedRuleset } from './ruleset';
 import { v2CoreRuleset, v2SchemasRuleset, v2RecommendedRuleset } from './v2';
+import { v3CoreRuleset } from './v3';
 
 import type { Parser } from '../parser';
 import type { RulesetDefinition } from '@stoplight/spectral-core';
@@ -18,6 +19,7 @@ export function createRuleset(parser: Parser, options?: RulesetOptions): Ruleset
     useCore && v2CoreRuleset,
     useCore && v2SchemasRuleset(parser),
     useRecommended && v2RecommendedRuleset,
+    useCore && v3CoreRuleset,
     ...(options as any || {})?.extends || [],
   ].filter(Boolean);
 

src/ruleset/v3/functions/operationMessagesUnambiguity.ts

@@ -0,0 +1,44 @@
+import { createRulesetFunction } from '@stoplight/spectral-core';
+import type { IFunctionResult } from '@stoplight/spectral-core';
+import { SchemaDefinition } from '@stoplight/spectral-core/dist/ruleset/function';
+
+const referenceSchema: SchemaDefinition = {
+  type: 'object',
+  properties: {
+    $ref: {
+      type: 'string',
+      format: 'uri-reference'
+    },
+  },
+};
+
+export const operationMessagesUnambiguity = createRulesetFunction<{ channel?: {'$ref': string}; messages?: [{'$ref': string}] }, null>(
+  {
+    input: {
+      type: 'object',
+      properties: {
+        channel: referenceSchema,
+        messages: {
+          type: 'array',
+          items: referenceSchema,
+        },
+      },
+    },
+    options: null,
+  },
+  (targetVal, _, ctx) => {
+    const results: IFunctionResult[] = [];
+    const channelPointer = targetVal.channel?.$ref as string; // required
+
+    targetVal.messages?.forEach((message, index) => {      
+      if (!message.$ref.startsWith(`${channelPointer}/messages`)) {
+        results.push({
+          message: 'Operation message does not belong to the specified channel.',
+          path: [...ctx.path, 'messages', index],
+        });
+      }
+    });
+  
+    return results;
+  },
+);

src/ruleset/v3/index.ts

@@ -0,0 +1 @@
+export * from './ruleset';

src/ruleset/v3/ruleset.ts

@@ -0,0 +1,28 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+
+import { AsyncAPIFormats } from '../formats';
+import { operationMessagesUnambiguity } from './functions/operationMessagesUnambiguity';
+
+export const v3CoreRuleset = {
+  description: 'Core AsyncAPI 3.x.x ruleset.',
+  formats: AsyncAPIFormats.filterByMajorVersions(['3']).formats(),
+  rules: {
+    /**
+     * Operation Object rules
+     */
+    'asyncapi3-operation-messages-from-referred-channel': {
+      description: 'Operation "messages" must be a subset of the messages defined in the channel referenced in this operation.',
+      message: '{{error}}',
+      severity: 'error',
+      recommended: true,
+      resolved: false, // We use the JSON pointer to match the channel.
+      given: [
+        '$.operations.*',
+        '$.components.operations.*',
+      ],
+      then: {
+        function: operationMessagesUnambiguity,
+      },
+    },
+  },
+};

test/custom-operations/parse-schema-v3.spec.ts

@@ -26,7 +26,7 @@ describe('custom operations for v3 - parse schemas', function() {
           },
           messages: [
             {
-              $ref: '#/components/messages/message'
+              $ref: '#/channels/channel/messages/message'
             }
           ]
         }