Provide messages for SARIF2004.OptimizeFileSize.

docs/Producing effective SARIF.md

@@ -385,12 +385,22 @@ This run does not provide 'versionControlProvenance'. As a result, it is not pos
 
 #### Description
 
+Emit arrays only if they provide additional information.
+
+In several parts of a SARIF log file, a subset of information about an object appears in one place, and the full information describing all such objects appears in an array elsewhere in the log file. For example, each 'result' object has a 'ruleId' property that identifies the rule that was violated. Elsewhere in the log file, the array 'run.tool.driver.rules' contains additional information about the rules. But if the elements of the 'rules' array contained no information about the rules beyond their ids, then there might be no reason to include the 'rules' array at all, and the log file could be made smaller simply by omitting it. In some scenarios (for example, when assessing compliance with policy), the 'rules' array might be used to record the full set of rules that were evaluated. In such a scenario, the 'rules' array should be retained even if it contains only id information.
+
+Similarly, most 'result' objects contain at least one 'artifactLocation' object. Elsewhere in the log file, the array 'run.artifacts' contains additional information about the artifacts that were analyzed. But if the elements of the 'artifacts' array contained not information about the artifacts beyond their locations, then there might be no reason to include the 'artifacts' array at all, and again the log file could be made smaller by omitting it. In some scenarios (for example, when assessing compliance with policy), the 'artifacts' array might be used to record the full set of artifacts that were analyzed. In such a scenario, the 'artifacts' array should be retained even if it contains only location information.
+
 #### Messages
 
 ##### `EliminateLocationOnlyArtifacts`: warning
 
+{0): The 'artifacts' array contains no information beyond the locations of the artifacts. Removing this array might reduce the log file size without losing information. In some scenarios (for example, when assessing compliance with policy), the 'artifacts' array might be used to record the full set of artifacts that were analyzed. In such a scenario, the 'artifacts' array should be retained even if it contains only location information.
+
 ##### `EliminateIdOnlyRules`: warning
 
+{0}: The 'rules' array contains no information beyond the ids of the rules. Removing this array might reduce the log file size without losing information. In some scenarios (for example, when assessing compliance with policy), the 'rules' array might be used to record the full set of rules that were evaluated. In such a scenario, the 'rules' array should be retained even if it contains only id information.
+
 ---
 
 ### Rule `SARIF2005.ProvideToolProperties`

src/Sarif.Multitool/Rules/RuleResources.resx

@@ -268,10 +268,14 @@ Many tools follow a conventional format for the 'reportingDescriptor.id' propert
     <value>{0}: This 'region' object does not specify 'startLine', 'charOffset', or 'byteOffset'. As a result, it is impossible to determine whether this 'region' object describes a line/column text region, a character offset/length text region, or a binary region.</value>
   </data>
   <data name="SARIF2004_OptimizeFileSize_FullDescription_Text" xml:space="preserve">
-    <value>Placeholder_SARIF2004_OptimizeFileSize_FullDescription_Text</value>
+    <value>Emit arrays only if they provide additional information.
+
+In several parts of a SARIF log file, a subset of information about an object appears in one place, and the full information describing all such objects appears in an array elsewhere in the log file. For example, each 'result' object has a 'ruleId' property that identifies the rule that was violated. Elsewhere in the log file, the array 'run.tool.driver.rules' contains additional information about the rules. But if the elements of the 'rules' array contained no information about the rules beyond their ids, then there might be no reason to include the 'rules' array at all, and the log file could be made smaller simply by omitting it. In some scenarios (for example, when assessing compliance with policy), the 'rules' array might be used to record the full set of rules that were evaluated. In such a scenario, the 'rules' array should be retained even if it contains only id information.
+
+Similarly, most 'result' objects contain at least one 'artifactLocation' object. Elsewhere in the log file, the array 'run.artifacts' contains additional information about the artifacts that were analyzed. But if the elements of the 'artifacts' array contained not information about the artifacts beyond their locations, then there might be no reason to include the 'artifacts' array at all, and again the log file could be made smaller by omitting it. In some scenarios (for example, when assessing compliance with policy), the 'artifacts' array might be used to record the full set of artifacts that were analyzed. In such a scenario, the 'artifacts' array should be retained even if it contains only location information.</value>
   </data>
   <data name="SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text" xml:space="preserve">
-    <value>{0}: Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text</value>
+    <value>{0): The 'artifacts' array contains no information beyond the locations of the artifacts. Removing this array might reduce the log file size without losing information. In some scenarios (for example, when assessing compliance with policy), the 'artifacts' array might be used to record the full set of artifacts that were analyzed. In such a scenario, the 'artifacts' array should be retained even if it contains only location information.</value>
   </data>
   <data name="SARIF2002_ProvideMessageArguments_FullDescription_Text" xml:space="preserve">
     <value>In result messages, use the 'message.id' and 'message.arguments' properties rather than 'message.text'. This has several advantages. If 'text' is lengthy, using 'id' and 'arguments' makes the SARIF file smaller. If the rule metadata is stored externally to the SARIF log file, the message text can be improved (for example, by adding more text, clarifying the phrasing, or fixing typos), and the result messages will pick up the improvements the next time it is displayed. Finally, SARIF supports localizing messages into different languages, which is possible if the SARIF file contains 'message.id' and 'message.arguments', but not if it contains 'message.text' directly.</value>
@@ -286,7 +290,7 @@ Many tools follow a conventional format for the 'reportingDescriptor.id' propert
     <value>{0}: This run does not provide 'versionControlProvenance'. As a result, it is not possible to determine which version of code was analyzed, nor to map relative paths to their locations within the repository.</value>
   </data>
   <data name="SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text" xml:space="preserve">
-    <value>Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text</value>
+    <value>{0}: The 'rules' array contains no information beyond the ids of the rules. Removing this array might reduce the log file size without losing information. In some scenarios (for example, when assessing compliance with policy), the 'rules' array might be used to record the full set of rules that were evaluated. In such a scenario, the 'rules' array should be retained even if it contains only id information.</value>
   </data>
   <data name="SARIF2006_UrisShouldBeReachable_FullDescription_Text" xml:space="preserve">
     <value>Placeholder_SARIF2006_UrisShouldBeReachable_FullDescription_Text</value>

src/Sarif.Multitool/Rules/SARIF2004.OptimizeFileSize.cs

@@ -19,7 +19,28 @@ public class OptimizeFileSize : SarifValidationSkimmerBase
         public override string Id => RuleId.OptimizeFileSize;
 
         /// <summary>
-        /// Placeholder_SARIF2004_OptimizeFileSize_FullDescription_Text
+        /// Emit arrays only if they provide additional information.
+        ///
+        /// In several parts of a SARIF log file, a subset of information about an object appears
+        /// in one place, and the full information describing all such objects appears in an array
+        /// elsewhere in the log file. For example, each 'result' object has a 'ruleId' property
+        /// that identifies the rule that was violated. Elsewhere in the log file, the array
+        /// 'run.tool.driver.rules' contains additional information about the rules. But if the
+        /// elements of the 'rules' array contained no information about the rules beyond their ids,
+        /// then there might be no reason to include the 'rules' array at all, and the log file
+        /// could be made smaller simply by omitting it. In some scenarios (for example, when
+        /// assessing compliance with policy), the 'rules' array might be used to record the full
+        /// set of rules that were evaluated. In such a scenario, the 'rules' array should be retained
+        /// even if it contains only id information.
+        ///
+        /// Similarly, most 'result' objects contain at least one 'artifactLocation' object. Elsewhere
+        /// in the log file, the array 'run.artifacts' contains additional information about the artifacts
+        /// that were analyzed. But if the elements of the 'artifacts' array contained not information
+        /// about the artifacts beyond their locations, then there might be no reason to include the
+        /// 'artifacts' array at all, and again the log file could be made smaller by omitting it. In
+        /// some scenarios (for example, when assessing compliance with policy), the 'artifacts' array
+        /// might be used to record the full set of artifacts that were analyzed. In such a scenario,
+        /// the 'artifacts' array should be retained even if it contains only location information.
         /// </summary>
         public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = RuleResources.SARIF2004_OptimizeFileSize_FullDescription_Text };
 
@@ -60,7 +81,12 @@ private void AnalyzeLocationOnlyArtifacts(Run run, string runPointer)
 
             if (HasResultLocationsWithUriAndIndex(firstResultLocationPointer) && HasLocationOnlyArtifacts(firstArtifactPointer))
             {
-                // {0}: Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text
+                // {0): The 'artifacts' array contains no information beyond the locations of the
+                // artifacts. Removing this array might  reduce the log file size without losing
+                // information. In some scenarios (for example, when assessing compliance with policy),
+                // the 'artifacts' array might be used to record the full set of artifacts that were
+                // analyzed. In such a scenario, the 'artifacts' array should be retained even if it
+                // contains only location information.
                 LogResult(
                     firstArtifactPointer,
                     nameof(RuleResources.SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text));
@@ -105,7 +131,12 @@ private void AnalyzeIdOnlyRules(Run run, string runPointer)
 
             if (HasIdOnlyRules(firstRulePointer))
             {
-                // {0}: SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text
+                // {0}: The 'rules' array contains no information beyond the ids of the rules.
+                // Removing this array might reduce the log file size without losing information.
+                // In some scenarios (for example, when assessing compliance with policy), the
+                // 'rules' array might be used to record the full set of rules that were evaluated.
+                // In such a scenario, the 'rules' array should be retained even if it contains
+                // only id information.
                 LogResult(
                     firstRulePointer,
                     nameof(RuleResources.SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text));

src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2004.OptimizeFileSize_Invalid.sarif

@@ -11,17 +11,17 @@
               "id": "SARIF2004",
               "name": "OptimizeFileSize",
               "shortDescription": {
-                "text": "Placeholder_SARIF2004_OptimizeFileSize_FullDescription_Text."
+                "text": "Emit arrays only if they provide additional information."
               },
               "fullDescription": {
-                "text": "Placeholder_SARIF2004_OptimizeFileSize_FullDescription_Text"
+                "text": "Emit arrays only if they provide additional information.\r\n\r\nIn several parts of a SARIF log file, a subset of information about an object appears in one place, and the full information describing all such objects appears in an array elsewhere in the log file. For example, each 'result' object has a 'ruleId' property that identifies the rule that was violated. Elsewhere in the log file, the array 'run.tool.driver.rules' contains additional information about the rules. But if the elements of the 'rules' array contained no information about the rules beyond their ids, then there might be no reason to include the 'rules' array at all, and the log file could be made smaller simply by omitting it. In some scenarios (for example, when assessing compliance with policy), the 'rules' array might be used to record the full set of rules that were evaluated. In such a scenario, the 'rules' array should be retained even if it contains only id information.\r\n\r\nSimilarly, most 'result' objects contain at least one 'artifactLocation' object. Elsewhere in the log file, the array 'run.artifacts' contains additional information about the artifacts that were analyzed. But if the elements of the 'artifacts' array contained not information about the artifacts beyond their locations, then there might be no reason to include the 'artifacts' array at all, and again the log file could be made smaller by omitting it. In some scenarios (for example, when assessing compliance with policy), the 'artifacts' array might be used to record the full set of artifacts that were analyzed. In such a scenario, the 'artifacts' array should be retained even if it contains only location information."
               },
               "messageStrings": {
                 "Warning_EliminateLocationOnlyArtifacts": {
-                  "text": "{0}: Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text"
+                  "text": "{0): The 'artifacts' array contains no information beyond the locations of the artifacts. Removing this array might reduce the log file size without losing information. In some scenarios (for example, when assessing compliance with policy), the 'artifacts' array might be used to record the full set of artifacts that were analyzed. In such a scenario, the 'artifacts' array should be retained even if it contains only location information."
                 },
                 "Warning_EliminateIdOnlyRules": {
-                  "text": "Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text"
+                  "text": "{0}: The 'rules' array contains no information beyond the ids of the rules. Removing this array might reduce the log file size without losing information. In some scenarios (for example, when assessing compliance with policy), the 'rules' array might be used to record the full set of rules that were evaluated. In such a scenario, the 'rules' array should be retained even if it contains only id information."
                 }
               },
               "helpUri": "http://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html"