feat: add reference property to context.report() for external docs links (#2734)

Author: mvanhorn

.changeset/report-reference-property.md

@@ -0,0 +1,7 @@
+---
+"@redocly/openapi-core": minor
+---
+
+Added a `reference` property to `context.report()` so that custom rules can link to external documentation.
+When set, the URL is rendered beneath the message in both stylish and `github-actions` output formats.
+Configurable rules also accept a top-level `reference` field.

packages/core/src/__tests__/__snapshots__/redocly-yaml.test.ts.snap

@@ -488,6 +488,9 @@ exports[`createConfigTypes > matches snapshot for the default config schema 1`]
       "message": {
         "type": "string",
       },
+      "reference": {
+        "type": "string",
+      },
       "severity": {
         "enum": [
           "error",

packages/core/src/__tests__/format.test.ts

@@ -210,6 +210,64 @@ describe('format', () => {
     `);
   });
 
+  it('should include reference URL in github-actions format', () => {
+    const problems: NormalizedProblem[] = [
+      {
+        ruleId: 'struct',
+        message: 'Operation must include a request body',
+        severity: 'error' as const,
+        location: [
+          {
+            source: { absoluteRef: 'openapi.yaml' } as Source,
+            start: { line: 1, col: 2 },
+            end: { line: 3, col: 4 },
+          } as LocationObject,
+        ],
+        suggest: [],
+        reference: 'https://wiki.example.com/api-guidelines#request-bodies',
+      },
+    ];
+
+    formatProblems(problems, {
+      format: 'github-actions',
+      version: '1.0.0',
+      totals: getTotals(problems),
+    });
+
+    expect(output).toEqual(
+      '::error title=struct,file=openapi.yaml,line=1,col=2,endLine=3,endColumn=4::Operation must include a request body%0A%0AReference: https://wiki.example.com/api-guidelines#request-bodies%0A%0A\n'
+    );
+  });
+
+  it('should render both suggestions and reference with single separator in github-actions format', () => {
+    const problems: NormalizedProblem[] = [
+      {
+        ruleId: 'operation-id',
+        message: 'Operation ID is required',
+        severity: 'error' as const,
+        location: [
+          {
+            source: { absoluteRef: 'openapi.yaml' } as Source,
+            start: { line: 1, col: 2 },
+            end: { line: 3, col: 4 },
+          } as LocationObject,
+        ],
+        suggest: ['addOperation'],
+        reference: 'https://wiki.example.com/api-guidelines#operation-id',
+      },
+    ];
+
+    formatProblems(problems, {
+      format: 'github-actions',
+      version: '1.0.0',
+      totals: getTotals(problems),
+    });
+
+    expect(output).toEqual(
+      '::error title=operation-id,file=openapi.yaml,line=1,col=2,endLine=3,endColumn=4::Operation ID is required%0A%0ADid you mean: addOperation ?%0A%0AReference: https://wiki.example.com/api-guidelines#operation-id%0A%0A\n'
+    );
+  });
+
   it('should limit suggestions based on REDOCLY_CLI_LINT_MAX_SUGGESTIONS constant', () => {
     const problems: NormalizedProblem[] = [
       {

packages/core/src/__tests__/lint.test.ts

@@ -390,6 +390,41 @@ describe('lint', () => {
     expect(replaceSourceWithRef(results_with_createConfig)).toEqual(replaceSourceWithRef(results));
   });
 
+  it('lintFromString should propagate reference from a configurable rule to the resulting problem', async () => {
+    const source = outdent`
+      openapi: 3.0.2
+      info:
+        title: Example
+        version: '1.0'
+      paths:
+        /user:
+          get:
+            responses:
+              '200':
+                description: OK
+    `;
+    const results = await lintFromString({
+      absoluteRef: '/test/spec.yaml',
+      source,
+      config: await createConfig(outdent`
+        rules:
+          rule/operation-summary-required:
+            subject:
+              type: Operation
+              property: summary
+            assertions:
+              defined: true
+            message: Operation summary is required
+            severity: error
+            reference: https://docs.example.com/style-guide#operation-summary
+      `),
+    });
+
+    const problem = results.find((r) => r.ruleId === 'rule/operation-summary-required');
+    expect(problem).toBeDefined();
+    expect(problem?.reference).toEqual('https://docs.example.com/style-guide#operation-summary');
+  });
+
   it('lint should work', async () => {
     const results = await lint({
       ref: path.join(__dirname, 'fixtures/lint/openapi.yaml'),

packages/core/src/format/format.ts

@@ -284,6 +284,7 @@ export function formatProblems(
       `[${idx + 1}] ${bgColor(fileWithLoc)} ${atPointer}\n\n` +
       `${problem.message}\n\n` +
       formatDidYouMean(problem) +
+      (problem.reference ? `Reference: ${colorize.blue(problem.reference)}\n\n` : '') +
       getCodeframe(loc, color) +
       '\n\n' +
       formatFrom(cwd, problem.from) +
@@ -440,7 +441,9 @@ function outputForGithubActions(problems: NormalizedProblem[], cwd: string): voi
           break;
       }
       const suggest = formatDidYouMean(problem);
-      const message = suggest !== '' ? problem.message + '\n\n' + suggest : problem.message;
+      const reference = problem.reference ? `Reference: ${problem.reference}\n\n` : '';
+      const message =
+        problem.message + (suggest !== '' || reference !== '' ? '\n\n' : '') + suggest + reference;
       const properties = {
         title: problem.ruleId,
         file: isAbsoluteUrl(location.source.absoluteRef)

packages/core/src/rules/common/assertions/index.ts

@@ -30,6 +30,7 @@ export type RawAssertion = AssertionDefinition & {
   where?: AssertionDefinition[];
   message?: string;
   suggest?: string[];
+  reference?: string;
   severity?: RuleSeverity;
 };
 

packages/core/src/rules/common/assertions/utils.ts

@@ -238,6 +238,7 @@ export function buildSubjectVisitor(assertId: string, assertion: Assertion): Vis
           location: getProblemsLocation(problemGroup) || ctx.location,
           forceSeverity: assertion.severity || 'error',
           suggest: assertion.suggest || [],
+          ...(assertion.reference && { reference: assertion.reference }),
           ruleId: assertId,
         });
       }

packages/core/src/types/redocly-yaml.ts

@@ -594,6 +594,7 @@ const ConfigurableRule: NodeType = {
     where: listOf('Where'),
     message: { type: 'string' },
     suggest: { type: 'array', items: { type: 'string' } },
+    reference: { type: 'string' },
     severity: { enum: ['error', 'warn', 'off'] },
   },
   required: ['subject', 'assertions'],

packages/core/src/walk.ts

@@ -79,6 +79,7 @@ export type Problem = {
   from?: LocationObject;
   forceSeverity?: RuleSeverity;
   ruleId?: string;
+  reference?: string;
 };
 
 export type NormalizedProblem = {
@@ -89,6 +90,7 @@ export type NormalizedProblem = {
   from?: LocationObject;
   suggest: string[];
   ignored?: boolean;
+  reference?: string;
 };
 
 export type WalkContext = {

tests/e2e/lint/configurable-rule-with-reference/openapi.yaml

@@ -0,0 +1,14 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Reference field test
+  description: Test that configurable rule reference is rendered.
+  license:
+    name: MIT
+paths: {}
+components:
+  examples:
+    snake_case_example:
+      value: { hello: 'world' }
+    anotherBadExample:
+      value: { foo: 'bar' }