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

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'
  }
  ]
  }