Add reference property to context.report() for external documentation

Add the `reference` property to the `context.report()` method for external documentation links.

Fix #1052

* **Documentation**: Update `docs/custom-plugins/custom-rules.md` to include the `reference` property in the `context.report()` method documentation.
* **New Rule**: Add `packages/core/src/rules/arazzo/reference-property.ts` to implement a new rule for validating the `reference` property in the report object.
* **Rule Integration**: Modify `packages/core/src/rules/arazzo/index.ts` to import and add the new `reference-property` rule to the existing rules.
* **Unit Tests**: Add `packages/core/src/rules/arazzo/__tests__/reference-property.test.ts` to test the presence and format validation of the `reference` property and error reporting for missing or incorrect `reference` property.

Author: ImBIOS

docs/custom-plugins/custom-rules.md

@@ -91,6 +91,7 @@ The main method used is `context.report()`, which publishes a warning or error (
 - `location` - {Location} (optional) An object specifying the location of the problem. Can be constructed using location object methods.
 - `suggest` - {string[]} (optional) - "Did you mean" suggestion.
 - `from` - {Location} (optional) - Referenced by location.
+- `reference` - {string} (optional) - A URI reference to external documentation supporting the design decision of a particular rule.
 
 You may use the message alone:
 

packages/core/src/rules/arazzo/__tests__/reference-property.test.ts

@@ -0,0 +1,105 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Arazzo reference-property', () => {
+  const document = parseYamlToDocument(
+    outdent`
+      arazzo: '1.0.1'
+      info:
+        title: Cool API
+        version: 1.0.0
+        description: A cool API
+      sourceDescriptions:
+        - name: museum-api
+          type: openapi
+          url: openapi.yaml
+      workflows:
+        - workflowId: get-museum-hours
+          description: This workflow demonstrates how to get the museum opening hours and buy tickets.
+          parameters:
+            - in: header
+              name: Authorization
+              value: Basic Og==
+          steps:
+            - stepId: get-museum-hours
+              description: >-
+                Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description.
+              operationId: museum-api.getMuseumHours
+              successCriteria:
+                - condition: $statusCode == 200
+    `,
+    'arazzo.yaml'
+  );
+
+  it('should report an error when the `reference` property is invalid', async () => {
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        rules: { 'reference-property': 'error' },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/workflows/0/steps/0/successCriteria/0",
+              "reportOnKey": false,
+              "source": "arazzo.yaml",
+            },
+          ],
+          "message": "The \`reference\` property must be a valid URI.",
+          "ruleId": "reference-property",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report an error when the `reference` property is valid', async () => {
+    const validDocument = parseYamlToDocument(
+      outdent`
+        arazzo: '1.0.1'
+        info:
+          title: Cool API
+          version: 1.0.0
+          description: A cool API
+        sourceDescriptions:
+          - name: museum-api
+            type: openapi
+            url: openapi.yaml
+        workflows:
+          - workflowId: get-museum-hours
+            description: This workflow demonstrates how to get the museum opening hours and buy tickets.
+            parameters:
+              - in: header
+                name: Authorization
+                value: Basic Og==
+            steps:
+              - stepId: get-museum-hours
+                description: >-
+                  Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description.
+                operationId: museum-api.getMuseumHours
+                successCriteria:
+                  - condition: $statusCode == 200
+                    reference: https://www.redocly.com
+      `,
+      'arazzo.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document: validDocument,
+      config: await makeConfig({
+        rules: { 'reference-property': 'error' },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+});

packages/core/src/rules/arazzo/index.ts

@@ -13,6 +13,7 @@ import { StepOnFailureUnique } from './step-onFailure-unique';
 import { RequestBodyReplacementsUnique } from './requestBody-replacements-unique';
 import { NoCriteriaXpath } from '../spot/no-criteria-xpath';
 import { CriteriaUnique } from './criteria-unique';
+import { ReferenceProperty } from './reference-property';
 
 import type { Arazzo1Rule } from '../../visitors';
 import type { Arazzo1RuleSet } from '../../oas-types';
@@ -33,6 +34,7 @@ export const rules: Arazzo1RuleSet<'built-in'> = {
   'requestBody-replacements-unique': RequestBodyReplacementsUnique,
   'no-criteria-xpath': NoCriteriaXpath,
   'criteria-unique': CriteriaUnique,
+  'reference-property': ReferenceProperty,
 };
 
 export const preprocessors = {};

packages/core/src/rules/arazzo/reference-property.ts

@@ -0,0 +1,22 @@
+import type { Arazzo1Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+
+export const ReferenceProperty: Arazzo1Rule = () => {
+  return {
+    Report: {
+      enter(report, { report: ctxReport, location }: UserContext) {
+        const reference = report?.reference;
+        if (reference !== undefined) {
+          try {
+            new URL(reference);
+          } catch (_) {
+            ctxReport({
+              message: 'The `reference` property must be a valid URI.',
+              location: location.child(['reference']),
+            });
+          }
+        }
+      },
+    },
+  };
+};