Re: recommendedArtifactDisplayBase

[James Kupsch <kupsch@cs.wisc.edu>]

Michael,

Our mails crossed in transit.  Upon further thought, as stated in my 
updated proposal, using an originalBaseUriId whose name is declared as 
the value to use is the right solution.  baseUriIds are good, but since 
there can be more than one, from a generic viewer can't know which would 
be the best to use, but the tool, result management system or translator 
may be able to state this.  Also not using the special value in 
artifactLocations allows the value to be changed without having to 
rewrite all the artifactLocations.

Here is my revised proposal (with a small revision to display just the 
absolute path if the scheme and authority match) and below that is an 
example:

An even simpler change requiring no schema change would be to simply 
document that a originalUriBaseId named DISPLAYBASE (or some other name) 
is used for this purpose.  If the value is set consumers SHOULD 
interpret it as a hint to display URIs relative to to the DISPLAYBASE 
uriBaseId.  Checking if the path is contained in DISPLAYBASE should be 
done after resolving and normalizing the DISPLAYBASE uri and the uri to 
display using the algorithm in 3.14.14.  If the URI to display's scheme, 
authority and the initial path segments match the DISPLAYBASE, only 
display the remaining path segments (or '.' if there are no remaining 
segments).  If the scheme and authority match, display the entire 
absolute path.   Otherwise, display the URI as an absolute URI (or some 
other appropriate method such as <uriBaseId, uri> pair).

Producers should not use DISPLAYBASE as a uriBaseId in artifactLocations 
as this allows a result management system, or translator to set or 
change the value after the fact without having to change all uses of 
DISPLAYBASE.

We could reserve all baseUriIds that start with SARIF_ for future use 
and use SARIF_DISPLAYBASE for the name.  That future proof other 
baseUriId uses to not conflict with producer uses.




Example:

Given the following oringalUriBaseIds (quotes elided in property names):
---------
originalUriBaseIds:  {
   WEBHOST:  {
     uri:        "http://www.example.com";
   },
   ROOT:  {
     uri:        "file:///"
   },
   HOME:  {
     uriBaseId:  "ROOT",
     uri:        "/home/user/"
   },
   PACKAGE:  {
     uriBaseId:  "HOME",
     uri:        "mySoftware/"
   },
   SRC:  {
     uriBaseId:  "PACKAGE",
     uri:        "src/"
   },
   DISPLAYBASE:  {
     uriBaseId:  "PACKAGE"
   }
}


---------
All these equivalent locations below would display as

   src/f.c

as the scheme, authority at path segments prefix match
---------
{
   uriBaseId:    "SRC",
   uri:          "f.c"
}
{
   uriBaseId:    "PACKAGE",
   uri:          "src/f.c"
}
{
   uri:          "file:///home/user/mySoftware/src/f.c"
}


---------
All these equivalent locations below would display as

   /usr/include/stdio.h

as the scheme and authority match, but not the path
---------
{
   uriBaseId:    "ROOT",
   uri:          "/usr/include/stdio.h"
}
{
   uriBaseId:    "SRC",
   uri:          "/usr/include/stdio.h"
}
{
   uri:          "file:///usr/include/stdio.h"
}

---------
All these equivalent locations below would display as

   http://www.example.com/hello

as the scheme and authority do not match
---------
{
   uriBaseId:    "WEBHOST",
   uri:          "hello"
}
{
   uri:          "http://www.example.com/hello";
}



---------
If DISPLAYBASE was changed to

   {
     uriBaseId:  "HOME"
   }

and no other changes were made, the only change to the
above display URIs would be src/f.c would be displayed as

   mySoftware/src/f.c

All other display values would be unchanged.


On 4/24/19 6:59 PM, Michael Fanning wrote:
> Can you explain further why one or more well-named uriBaseIds can’t help 
> here?
> 
> Imagine a viewer that simply constructs its view according to the way 
> that a producer has organized these constructs. If the producer is 
> thoughtful about how it organizes this data and the name that it uses, a 
> generic viewer could do a good job. This is a nice motivation for 
> producers to help out.
> 
> The obvious possible complication is when there is a necessary 
> decomposition of a URI into some uriBaseId + extra stuff, mandated by 
> things like nesting repositories. On a cursory think, though, I can’t 
> think of where this complexity interferes with the viewer function, it’s 
> **helpful** to know how the repository nesting is structured.
> 
> The great flexibility of uriBaseIds over your suggestion is that you can 
> provide more than one of them, rather than a single hint as you’ve 
> suggested.
> 
> If you have time to send a more detailed example of what you have in 
> mind, please do.
> 
> Play this mental game: if a SARIF producer created a uriBaseId named 
> $(RecommendedBase) and set it to the actual recommended base in the 
> originalUriBaseIds data, wouldn’t that effectively provide what you’re 
> after? At the potential cost of constraining other use of the URI 
> construction mechanism?
> 
> Sent from Mail <https://go.microsoft.com/fwlink/?LinkId=550986> for 
> Windows 10
> 
> ------------------------------------------------------------------------
> *From:* sarif@lists.oasis-open.org <sarif@lists.oasis-open.org> on 
> behalf of James Kupsch <kupsch@cs.wisc.edu>
> *Sent:* Wednesday, April 24, 2019 2:24:10 PM
> *To:* sarif@lists.oasis-open.org
> *Subject:* [sarif] recommendedArtifactDisplayBase
> Sorry for the late small proposal, but I've been thinking about a
> generic SARIF viewer and how to display paths to a human.  In a viewer
> it is nice to normalize the display for paths to be relative to a single
> location, or to be absolute for location not contained within the single
> location.
> 
> Without the viewer and the producer agreeing out of band on a uri, or a
> baseUriId name to use, the viewer does not know how to base the results
> for result display.
> 
> I propose adding a property name something like
> recommendedArtifactDisplayBase to the run object with a value of type
> artifactLocation.  Producers MAY set this to an appropriate value if
> possible.  If set, consumers that display relative paths, SHOULD display
> paths to relative to the recommendedArtifactDisplayBase if the path is
> contained in the recommendedArtifactDisplayBase.  If it is not contained
> in recommendedArtifactDisplayBase, viewer may display it as an absolute
> path (or by some other appropriate mechanism).
> 
> Jim