feat(assertions): support reference on configurable rules and fix github-actions formatting

Addresses @DmitryAnansky's feedback on #2734:

- Add `reference: string` to the `ConfigurableRule` schema so `redocly.yaml`
  rules can set a top-level `reference` field alongside `message` and
  `suggest`.
- Thread `reference` through `buildSubjectVisitor` so assertion failures
  populate `problem.reference` for the existing stylish and
  github-actions formatters (which already handle `problem.reference`).
- Add `reference?: string` to `RawAssertion` so the TypeScript surface
  matches the runtime schema.

Also fixes the github-actions formatter's double-newline when both
`suggest` and `reference` are present (flagged by Cursor Bugbot):
`formatDidYouMean()` already returns a string ending with `\n\n`, so the
old separator logic produced four consecutive newlines. Match the
codeframe pattern: add a single `\n\n` separator before the first
section and rely on each formatter's trailing newlines.

Tests:
- Extend lint tests with a configurable rule that sets `reference`;
  assert the resulting problem carries the URL through to the output.
- Add a github-actions format test covering both `suggest` + `reference`
  together, asserting a single blank line between each section.
- Update changeset to cover configurable rules (with the line-break
  phrasing JLekawa suggested).

Author: mvanhorn

.changeset/report-reference-property.md

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

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

@@ -239,6 +239,35 @@ describe('format', () => {
     );
   });
 
+  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

@@ -443,9 +443,7 @@ function outputForGithubActions(problems: NormalizedProblem[], cwd: string): voi
       const suggest = formatDidYouMean(problem);
       const reference = problem.reference ? `Reference: ${problem.reference}\n\n` : '';
       const message =
-        problem.message +
-        (suggest !== '' ? '\n\n' + suggest : '') +
-        (reference !== '' ? '\n\n' + reference : '');
+        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 || [],
+          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'],