Provide a format for links embedded in our plain text messages

[michaelcfanning]

We have discussed preferring/permitting markdown for representing SARIF messages. In part, we have considered this in order to support embedding links in output. As an alternate, we could simply permit embedded links in plain text messages (which could themselves follow the markdown format). This has the downside of introducing a 'mini-language' into the format. That mini-language can follow an existing standard, however (markdown). By restricting markdown use to this narrow scenario, we can also describe a way for SARIF message consumers that can't support an actual inlined link to display the content in a reasonable way. Issue #33 refers to the broad problem of formatting in messages. This issue also relates to #57, as an embedded link typically references a region in the file that is linked to.

Markdown support for links is relatively rich. For simplicity we should likely pick the smallest useful subset. One proposal would be to support the standard link text + link + link title syntax:

link text here

An example SARIF message:

A call to 'Start' may result in arbitrary code execution. The untrusted data that flows into this call site originated [here](http://somefile.cpp#startLine=10 SomeFile.cpp)

A link consumer would convert this into a clickable link. A pure plain-text viewer would parse this, trim the hover link text and render as so:

A call to 'Start' may result in arbitrary code execution. The untrusted data that flows into this call site originated here (http://somefile.cpp#startLine=10)

Additional complexities: if we define a protocol for referencing files that are stored in the object, consumers will need to potentially go locate the actual URI for the file (SARIF allows for files to be referenced by arbitrary key, to accommodate situations where there may be file name collisions)

[DerSaidin]

If the URI in the link is referencing a SARIF file object, is it useful to show it to users?
I think users seeing a URI would expect something they can put into their web browser.

Would it be more user friendly to parse the URI and transform it into a human readable description equivalent?

A call to 'Start' may result in arbitrary code execution. The untrusted data that flows into this call site originated here (line 10 of somefile.cpp)

[michaelcfanning]

I like this. For an internal SARIF file reference, this could be a preferable recommendation, I agree. For standard URLs (there's no reason someone couldn't choose to link to an external web site in the message, for example), viewers could stick with the standard URL.

[michaelcfanning]

Here are some other URL formats that exist along these lines:

GITHUB:
https://github.com/Microsoft/sarif-sdk/blob/d18d48cbebf4271f7b43d41ca1acdf16f0c9ee90/src/Sarif.Driver/Pair.cs#L18-L21

VSTS:
https://microsoft.visualstudio.com/SomeRepository/_git/os?path=%2FsomeDirectory&version=aac5c5a8e03a6a505d2a7e4dc0aa111e8230f63b71&_a=contents&line=14&lineEnd=15

BitBucket:
https://bitbucket.org/atlassian/python-bitbucket/src/master/tests/test_auth.py
?fileviewer=file-view-default
#test_auth.py-29

Notes:

• Specific file revisions typically handled by altering path. VSTS provides a specific revision/version argument in its query string
• URLs provide limited support for code selection, mostly allowing one or more lines to be selected
• Some representation of fragment use for line locations, otherwise query string parameters

[ghost]

Fixed in c443e9a.