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

[mvanhorn]

What/Why/How?

Custom rules currently can't link users to external documentation explaining the design decision behind a rule. This PR adds a reference?: string property to context.report() that gets rendered beneath the message in both stylish (codeframe) and github-actions output formats.

Example usage from a plugin rule:

report({
  message: 'Operation must include a request body',
  reference: 'https://wiki.example.com/api-guidelines#request-bodies',
});

Stylish output:

Operation must include a request body

Reference: https://wiki.example.com/api-guidelines#request-bodies

GitHub Actions output:

::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

The property is carried through by the existing ...opts spread in the normalization path, so no wiring was needed beyond the type additions in walk.ts and the renderer branches in format.ts.

Reference

Fixes #1052

Testing

• packages/core/src/__tests__/format.test.ts adds a github-actions format case asserting the Reference: suffix renders correctly.
• All existing format tests still pass.

Screenshots (optional)

N/A - output is purely textual and covered by the new test.

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Low Risk
Small additive change limited to problem types and output formatting; primary risk is minor output/annotation string changes affecting consumers relying on exact formatting.

Overview
Custom rules can now attach an optional reference URL when calling context.report(), which is carried through problem normalization.

Formatting is updated to render Reference: <url> beneath the message in codeframe/stylish output and appended to github-actions annotations, with a new test covering the GitHub Actions format and a changeset bumping @redocly/openapi-core minor.

^{Reviewed by Cursor Bugbot for commit b4437dc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: b4437dc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	Minor
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tatomyr]

Could you add a E2E or a unit test that demonstrates how the output will look like? And please do not modify our PR template.

[tatomyr]

@mvanhorn the checks are failing, I'm converting your PR to draft.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b4437dc. Configure here.}

[cursor]

Extra double-newline when suggest and reference both present

Low Severity

In the github-actions formatter, when both suggestions and a reference are present, formatDidYouMean returns a string already ending with \n\n, and then '\n\n' + reference is appended, producing four consecutive newlines between the two sections. The codeframe formatter avoids this by directly concatenating without the extra \n\n prefix. The test only covers the case with an empty suggest array, so this inconsistency goes undetected.

Additional Locations (1)

• packages/core/src/format/format.ts#L285-L287

 

^{Reviewed by Cursor Bugbot for commit b4437dc. Configure here.}

[mvanhorn]

@tatomyr thanks for the pushback - addressed in b4437dc:

• Added a changeset under @redocly/openapi-core so the release pipeline picks this up.
• Added a github-actions format test in packages/core/src/__tests__/format.test.ts asserting the Reference: suffix renders correctly.
• Rewrote the PR description using the project's template (What/Why/How, Reference, Testing, Check yourself, Security) instead of my own sections.

Marked the PR ready again - hoping the required checks go green this time.