search

microsoft / sarif-vscode-extension

SARIF Microsoft Visual Studio Code extension
MIT License
107 stars 48 forks source link

Output Diagnostic.codeDescription.href when rules[id].helpUri is present in SARIF log #369

Open scalvert opened 3 years ago

scalvert commented 3 years ago

The SARIF spec allows for rule metadata to be output in the log. Within that metadata is a helpUri property, which provides an href to be used to help provide additional information about the rule. From the spec:

A reportingDescriptor object MAY contain a property named helpUri whose value is a localizable string (§3.5.1) containing the absolute URI [RFC3986] of the primary documentation for the reporting item.

NOTE 1: The documentation might include examples, contact information for the authors, and links to additional information.

NOTE 2: This property is localizable so that help information in different languages can be viewed at different URIs.

To provide a richer output when annotating diagnostics in vscode, it would be great to be able to provide the Diagnostic additional information, if present, that would allow for annotations within the code window.

By setting Diagnostic.codeDescription.href to log.rules[id].helpUri, we can add a clickable link that can be used to provide help links to users. This is similar to what the vscode-eslint plugin provides for rule violations:

Screen Shot 2021-02-10 at 9 57 20 AM

In the image above, the ruleId is clickable, and navigates to the rule's documentation markdown file.

I'm happy to implement this, if there's interest.

scalvert commented 3 years ago

ping, anyone around to discuss this?

michaelcfanning commented 3 years ago

Hello! Sorry for the delay in reply. This would be a great contribution to the viewer, would love to see it happen.

@jeffersonking

jeffersonking commented 3 years ago

Hi @scalvert! Also sorry for the delay in reply. Happy to take a PR or implement this for you. Either way.

Looking briefly, I did not see a codeDescription property on Diagnostic. Will take a closer look at how ESLint does this. What am I missing here? Thanks!

scalvert commented 3 years ago

@jeffersonking it's part of the language server protocol.

scalvert commented 3 years ago

I'm happy either way WRT who implements. It may be faster for you since you're aware of the codebase, but there's no better time than the present for diving in and learning :)

Essentially we'd need a reference to the full SARIF log when constructing the diagnostic messages, as we'd need access to the rules in order to reference the rule metadata.

scalvert commented 3 years ago

eslint has a makeDiagnostic function they use, which contains the codeDescription if a ruleId is present.

The Diagnostic type is imported from vscode-languageserver/node

jeffersonking commented 3 years ago

@scalvert Thanks for that info. We currently do not implement a Language Server. Looks like implementing (transitioning to) that will be the bulk of the work. I'll talk with @michaelcfanning try to come up with an estimate.

If you have any other feature asks that require a Language Server, please let us know.

Re: "we'd need access to the rules": That should be no problem as we already access the rules.

scalvert commented 3 years ago

Perfect. Sounds good. Ya I figured that you weren't leveraging a language server yet. Happy to help out where I can. Let me know!