Reformat SARIF1005, update spreadsheet. (#1940)

docs/Producing effective SARIF.md

@@ -6,21 +6,24 @@ This document is for creators of static analysis tools who want to produce SARIF
 
 Teams can use SARIF log files in many ways. They can view the results in an IDE extension such as the [SARIF extension for VS Code](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer) or the [SARIF Viewer VSIX for Visual Studio](https://marketplace.visualstudio.com/items?itemName=WDGIS.MicrosoftSarifViewer), or in a [web-based viewer](https://microsoft.github.io/sarif-web-component/). They can import it into a static analysis results database, or use it to drive automatic bug fiing. Most important, developers use the information in a SARIF log file to understand and fix the problems it reports.
 
-Because of this variety of usage scenarios, a SARIF log file that is useful one scenario might not be useful in another. Ideally, static analysis tools will provide options to let their users specify the output that meets their needs.
+Because of this variety of usage scenarios, a SARIF log file that is useful in one scenario might not be useful in another. Ideally, static analysis tools will provide options to let their users specify the output that meets their needs.
 
 The [SARIF specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) defines dozens of objects with hundreds of properties. It can be hard to decide which ones are important (aside from the few that the spec says are mandatory). What information is most helpful to developers? What information should you include if you want to file useful bugs from the SARIF log?
 
 On top of all that, the spec is written in format language that's hard to read. If you want to learn SARIF, take a look at the [SARIF Tutorials](https://github.com/microsoft/sarif-tutorials).
 
 The purpose of this document is to cut through the confusion and provide clear guidance on what information your tool should include in a SARIF file, and how to make that information as helpful and usable as possible.
 
-## TODO: Conceptual values
+## Principles for producing effective SARIF
+
+This document contains dozens of individual rules and guidelines for producing effective SARIF, but they all derive from a handful of bedrock principles:
+
+### Readability/Understandability/Actionability
+
+### Compactness
+
+### Serviceability
 
-- Readable
-- Compact
-- Version tools/serviceable
-- Essential data for some scenarios
-- etc
 
 Here's how SARIF can accomplish those goals...
 

src/Sarif.Multitool/Rules/SARIF1005.UriMustBeAbsolute.cs

@@ -4,25 +4,28 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+
 using Microsoft.Json.Pointer;
 
 namespace Microsoft.CodeAnalysis.Sarif.Multitool.Rules
 {
  public class UriMustBeAbsolute : SarifValidationSkimmerBase
  {
- public override MultiformatMessageString FullDescription => new MultiformatMessageString
- {
-  Text = RuleResources.SARIF1005_UriMustBeAbsolute_FullDescription_Text
- };
+ /// <summary>
+ /// SARIF1005
+ /// </summary>
+ public override string Id => RuleId.UriMustBeAbsolute;
 
- public override FailureLevel DefaultLevel => FailureLevel.Error;
+ /// <summary>
+ /// Placeholder
+ /// </summary>
+ public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = RuleResources.SARIF1005_UriMustBeAbsolute_FullDescription_Text };
 
- public override string Id => RuleId.UriMustBeAbsolute;
+ protected override IEnumerable<string> MessageResourceNames => new string[] {
+ nameof(RuleResources.SARIF1005_UriMustBeAbsolute_Error_Default_Text)
+ };
 
- protected override IEnumerable<string> MessageResourceNames => new string[]
- {
- nameof(RuleResources.SARIF1005_UriMustBeAbsolute_Error_Default_Text)
- };
+ public override FailureLevel DefaultLevel => FailureLevel.Error;
 
  protected override void Analyze(SarifLog log, string logPointer)
  {
@@ -77,6 +80,7 @@ private void AnalyzeUri(string uriString, string pointer)
  Uri uri = new Uri(uriString, UriKind.RelativeOrAbsolute);
  if (!uri.IsAbsoluteUri)
  {
+ // Placeholder
  LogResult(pointer, nameof(RuleResources.SARIF1005_UriMustBeAbsolute_Error_Default_Text), uriString);
  }
  }