Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

✨ Clicking on a rule's code in the tooltip open the rule's documentationUrl in the browser #237

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

✨ Clicking on a rule's code in the tooltip open the rule's documentationUrl in the browser #237

wants to merge 4 commits into from

Conversation

ouvreboite
Copy link

@ouvreboite ouvreboite commented Jul 26, 2024 •
edited
Loading

Fixes #235

Allow to "click to know more" on a problem's rule code, using the rule/ruleset documentationUrl.

This allow the user to access a richer documentation and to not be restricted to just the error message/error code.

Checklist

  • Tests added / updated
  • Docs added / updated (I'm not sure there are docs that need to be updated)

Does this PR introduce a breaking change?

  • Yes
  • No

image
image

The error-code becomes clickable (in the Problems view but also in the tooltip).

The link is constructed following the rules defined here:

  • if the rule has it's own documentationUrl, we use it
  • otherwise we use the ruleset's documentationUrl (if it exists), with #the-rule-code appended
  • the implementation also work for extended rulesets has we access each rule's "owner" (i.e. owning ruleset)

Additional context

🚨This feature requires Diagnostic.codeDescription, with is available in https://www.npmjs.com/package/vscode-languageserver-types > 3.16, which required upgrading some other vscode-languageserver and client dependencies.

I'm using a basic ruleset to test it locally, but I've not pushed it:

formats: ["oas3"]
documentationUrl: https://example.com
extends: spectral:oas
rules:
  with-direct-documentation: #should have the doc https://example.com/direct
    documentationUrl: https://example.com/direct
    severity: error
    given: $.tags[*]
    then:
      field: description
      function: falsy
  without-direct-documentation: #should have the doc https://example.com#without-direct-documentation
    severity: error
    given: $.tags[*]
    then:
      field: description
      function: truthy

@ouvreboite ouvreboite changed the title ✨ Provide the rule's documentation url has codeDescription ✨ Clicking on a rule's code in the tooltip open the rule's documentationUrl in the browser Jul 29, 2024
@mnaumanali94
Copy link
Contributor

@ouvreboite Would you mind fixing the conflicts? I'd love to get this merged 🙏🏼

jb.muscat added 2 commits November 25, 2024 11:24
@ouvreboite
Copy link
Author

@mnaumanali94 this should be good now :)

@mnaumanali94
Copy link
Contributor

@ouvreboite Thanks for the quick turnaround and your contribution. I'll work on getting this out.

@mnaumanali94
Copy link
Contributor

@ouvreboite e2e tests are failing. Do you want to take a look? Otherwise i'll give it a go later 🙏🏼

@ouvreboite
Copy link
Author

ouvreboite commented Nov 25, 2024 •
edited
Loading

I'll have a quick look.

⏳

  • Also failing locally, when running node make.js allDev, with a similar console output.
  • I'm able to make the E2E tests runs by upgrading the vscode dependencies
  • Need to update the snapshots
  • Somehow the documentationUrl does not show in the snapshot of the E2E test for the .yaml file
    • Seems to be an artefact of how the vscode.Uri is serialized in the snapshots

@ouvreboite
Copy link
Author

ouvreboite commented Nov 25, 2024 •
edited
Loading

@mnaumanali94

@mnaumanali94
Copy link
Contributor

I've pushed updated snapshots for the E2E tests
On my machine, I also had to upgrade the VSCode dependencies (targeting the latest VSCode version). I don't understand why this would be needed, so I've not pushed yet. Do you want me to push it?

Yes push away. I can take a look

I've noted that the generated documentation url for the base rule set look like this (as expected): https://meta.stoplight.io/docs/spectral/docs/reference/openapi-rules.md#oas3-api-servers
But, if you follow the link, there is a redirection to https://meta.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules (I suppose there is some kind of URL versioning happening). So, this get you to the ruleset's doc, but the #oas3-api-servers is lost during the redirection 😞.

We can fix the links in the ruleset separate from this feature.

@ouvreboite
⬆️ Update to latest VSCode dependencies
a12d039 
Requires VSCode 1.95+ and Node 20+ (due to @vscode/vsce)
@ouvreboite
Copy link
Author

@mnaumanali94 I've pushed a new commit with the VSCode upgrade

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

documentationUrl causes
2 participants
@ouvreboite @mnaumanali94