diff --git a/docs/Producing effective SARIF.md b/docs/Producing effective SARIF.md index d87cf095a..7cc2662df 100644 --- a/docs/Producing effective SARIF.md +++ b/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` diff --git a/docs/Rule factoring.xlsx b/docs/Rule factoring.xlsx index 911cb5d13..29711c742 100644 Binary files a/docs/Rule factoring.xlsx and b/docs/Rule factoring.xlsx differ diff --git a/src/Sarif.Multitool/Rules/RuleResources.Designer.cs b/src/Sarif.Multitool/Rules/RuleResources.Designer.cs index 8ecf66420..9021ec315 100644 --- a/src/Sarif.Multitool/Rules/RuleResources.Designer.cs +++ b/src/Sarif.Multitool/Rules/RuleResources.Designer.cs @@ -443,7 +443,9 @@ internal static string SARIF2003_ProvideVersionControlProvenance_Note_Default_Te } /// - /// Looks up a localized string similar to Placeholder_SARIF2004_OptimizeFileSize_FullDescription_Text. + /// Looks up a localized string similar to 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 [rest of string was truncated]";. /// internal static string SARIF2004_OptimizeFileSize_FullDescription_Text { get { @@ -452,7 +454,7 @@ internal static string SARIF2004_OptimizeFileSize_FullDescription_Text { } /// - /// Looks up a localized string similar to Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text. + /// Looks up a localized string similar to {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.. /// internal static string SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_Text { get { @@ -461,7 +463,7 @@ internal static string SARIF2004_OptimizeFileSize_Warning_EliminateIdOnlyRules_T } /// - /// Looks up a localized string similar to {0}: Placeholder_SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text. + /// Looks up a localized string similar to {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.. /// internal static string SARIF2004_OptimizeFileSize_Warning_EliminateLocationOnlyArtifacts_Text { get { diff --git a/src/Sarif.Multitool/Rules/RuleResources.resx b/src/Sarif.Multitool/Rules/RuleResources.resx index 5b7e7fad1..c364484ad 100644 --- a/src/Sarif.Multitool/Rules/RuleResources.resx +++ b/src/Sarif.Multitool/Rules/RuleResources.resx @@ -268,10 +268,14 @@ Many tools follow a conventional format for the 'reportingDescriptor.id' propert {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. - 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. - {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. 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. @@ -286,7 +290,7 @@ Many tools follow a conventional format for the 'reportingDescriptor.id' propert {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. - Placeholder_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. Placeholder_SARIF2006_UrisShouldBeReachable_FullDescription_Text diff --git a/src/Sarif.Multitool/Rules/SARIF2004.OptimizeFileSize.cs b/src/Sarif.Multitool/Rules/SARIF2004.OptimizeFileSize.cs index 779eafa0d..9ad457d32 100644 --- a/src/Sarif.Multitool/Rules/SARIF2004.OptimizeFileSize.cs +++ b/src/Sarif.Multitool/Rules/SARIF2004.OptimizeFileSize.cs @@ -19,7 +19,28 @@ public class OptimizeFileSize : SarifValidationSkimmerBase public override string Id => RuleId.OptimizeFileSize; /// - /// 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. /// 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)); diff --git a/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2004.OptimizeFileSize_Invalid.sarif b/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2004.OptimizeFileSize_Invalid.sarif index 8876da0b1..572416b81 100644 --- a/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2004.OptimizeFileSize_Invalid.sarif +++ b/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"