Add support for guideline recategorizations

This commit adds:
- A new section `guideline-recategorizations` to the configuration
  specification for `coding-standards.yml`.
- Two tests to list all the indexed guideline recategorizations and all
  the invalid guideline recategorizations.

This commit does not include the application of the effective category.

Author: rvermeulen

cpp/common/src/codingstandards/cpp/Config.qll

@@ -0,0 +1,32 @@
+/**
+ * A module for runtime configuration settings specified in a `conding-standards.yml` file.
+ */
+
+import cpp
+import semmle.code.cpp.XML
+import codingstandards.cpp.exclusions.RuleMetadata
+import codingstandards.cpp.deviations.Deviations
+
+/** A `coding-standards.xml` configuration file (usually generated from an YAML configuration file). */
+class CodingStandardsFile extends XMLFile {
+  CodingStandardsFile() {
+    this.getBaseName() = "coding-standards.xml" and
+    // Must be within the users source code.
+    exists(this.getRelativePath())
+  }
+}
+
+class CodingStandardsConfigSection extends XMLElement {
+  CodingStandardsConfigSection() { getParent() instanceof CodingStandardsConfig }
+}
+
+/** A "Coding Standards" configuration file */
+class CodingStandardsConfig extends XMLElement {
+  CodingStandardsConfig() {
+    any(CodingStandardsFile csf).getARootElement() = this and
+    this.getName() = "codingstandards"
+  }
+
+  /** Get a section in this configuration file. */
+  CodingStandardsConfigSection getASection() { result.getParent() = this }
+}

cpp/common/src/codingstandards/cpp/deviations/Deviations.qll

@@ -7,6 +7,7 @@
 import cpp
 import semmle.code.cpp.XML
 import codingstandards.cpp.exclusions.RuleMetadata
+import codingstandards.cpp.Config
 
 predicate applyDeviationsAtQueryLevel() {
   not exists(CodingStandardsReportDeviatedAlerts reportDeviatedResults |
@@ -15,26 +16,6 @@ predicate applyDeviationsAtQueryLevel() {
   )
 }
 
-/** A `coding-standards.xml` configuration file (usually generated from an YAML configuration file). */
-class CodingStandardsFile extends XMLFile {
-  CodingStandardsFile() {
-    this.getBaseName() = "coding-standards.xml" and
-    // Must be within the users source code.
-    exists(this.getRelativePath())
-  }
-}
-
-/** A "Coding Standards" configuration file */
-class CodingStandardsConfig extends XMLElement {
-  CodingStandardsConfig() {
-    any(CodingStandardsFile csf).getARootElement() = this and
-    this.getName() = "codingstandards"
-  }
-
-  /** Gets a deviation record for this configuration. */
-  DeviationRecord getADeviationRecord() { result = getAChild().(DeviationRecords).getAChild() }
-}
-
 /** An element which tells the analysis whether to report deviated results. */
 class CodingStandardsReportDeviatedAlerts extends XMLElement {
   CodingStandardsReportDeviatedAlerts() {
@@ -44,19 +25,13 @@ class CodingStandardsReportDeviatedAlerts extends XMLElement {
 }
 
 /** A container of deviation records. */
-class DeviationRecords extends XMLElement {
-  DeviationRecords() {
-    getParent() instanceof CodingStandardsConfig and
-    hasName("deviations")
-  }
+class DeviationRecords extends CodingStandardsConfigSection {
+  DeviationRecords() { hasName("deviations") }
 }
 
 /** A container for the deviation permits records. */
-class DeviationPermits extends XMLElement {
-  DeviationPermits() {
-    getParent() instanceof CodingStandardsConfig and
-    hasName("deviation-permits")
-  }
+class DeviationPermits extends CodingStandardsConfigSection {
+  DeviationPermits() { hasName("deviation-permits") }
 }
 
 /** A deviation permit record, that is specified by a permit identifier */

cpp/common/src/codingstandards/cpp/guideline_recategorizations/GuidelineRecategorizations.qll

@@ -0,0 +1,105 @@
+/**
+ * A module for identifying guideline recategorizations specified in a `conding-standards.yml` file.
+ */
+
+import cpp
+import semmle.code.cpp.XML
+import codingstandards.cpp.exclusions.RuleMetadata
+import codingstandards.cpp.Config
+
+/** A container of guideline recategorizations. */
+class GuidelineRecategorizations extends CodingStandardsConfigSection {
+  GuidelineRecategorizations() { hasName("guideline-recategorizations") }
+}
+
+newtype TEffectiveCategory =
+  TInvalid(string reason) {
+    exists(GuidelineRecategorization gr | reason = gr.getAnInvalidReason())
+  } or
+  TDisapplied() or
+  TAdvisory() or
+  TRequired() or
+  TMandatory()
+
+class EffectiveCategory extends TEffectiveCategory {
+  string toString() {
+    this instanceof TInvalid and result = "invalid"
+    or
+    this instanceof TDisapplied and result = "disapplied"
+    or
+    this instanceof TAdvisory and result = "advisory"
+    or
+    this instanceof TRequired and result = "required"
+    or
+    this instanceof TMandatory and result = "mandatory"
+  }
+
+  /** Holds if the effective category permits a deviation */
+  predicate permitsDeviation() { not this instanceof TMandatory and not this instanceof TInvalid }
+}
+
+class GuidelineRecategorization extends XMLElement {
+  GuidelineRecategorization() {
+    getParent() instanceof GuidelineRecategorizations and
+    hasName("guideline-recategorizations-entry")
+  }
+
+  string getRuleId() { result = getAChild("rule-id").getTextValue() }
+
+  string getCategory() { result = getAChild("category").getTextValue() }
+
+  /** Get a query for which a recategorization is specified. */
+  Query getQuery() { result.getRuleId() = getRuleId() }
+
+  private EffectiveCategory getValidEffectiveCategory() {
+    exists(string category, string recategorization |
+      category = getQuery().getCategory() and
+      recategorization = getCategory()
+    |
+      result = TMandatory() and
+      category = ["advisory", "required"] and
+      recategorization = "mandatory"
+      or
+      result = TRequired() and
+      category = "advisory" and
+      recategorization = "required"
+      or
+      result = TDisapplied() and
+      category = "advisory" and
+      recategorization = "disapplied"
+    )
+  }
+
+  private predicate isValidRecategorization(string category, string recategorization) {
+    category = ["advisory", "required"] and
+    recategorization = "mandatory"
+    or
+    category = "advisory" and
+    recategorization = "required"
+    or
+    category = "advisory" and
+    recategorization = "disapplied"
+  }
+
+  string getAnInvalidReason() {
+    not isValidRecategorization(this.getQuery().getCategory(), this.getCategory()) and
+    if exists(this.getQuery())
+    then
+      result =
+        "Invalid recategorization from '" + this.getQuery().getCategory() + "' to '" +
+          this.getCategory() + "'."
+    else result = "Unknown rule id '" + this.getRuleId() + "'."
+  }
+
+  predicate isValid() { not isInvalid() }
+
+  predicate isInvalid() { getEffectiveCategory() = TInvalid(_) }
+
+  EffectiveCategory getEffectiveCategory() {
+    (
+      if exists(getValidEffectiveCategory())
+      then result = getValidEffectiveCategory()
+      else result = TInvalid(getAnInvalidReason())
+    )
+  }
+}

cpp/common/src/codingstandards/cpp/guideline_recategorizations/InvalidGuidelineRecategorizations.ql

@@ -0,0 +1,13 @@
+/**
+ * @id cpp/coding-standards/invalid-guideline-recategorizations
+ * @name Invalid guideline recategorizations
+ * @description Guideline recategorizations marked as invalid will not be applied.
+ */
+
+import cpp
+import GuidelineRecategorizations
+
+from GuidelineRecategorization gr
+select gr,
+  gr.getFile().getRelativePath() + ": '" + gr.getAnInvalidReason() + "' for rule " + gr.getRuleId() +
+    "."

cpp/common/src/codingstandards/cpp/guideline_recategorizations/ListGuidelineRecategorizations.ql

@@ -0,0 +1,12 @@
+/**
+ * @id cpp/coding-standards/list-guideline-recategorizations
+ * @kind table
+ * @name List all guideline recategorizations observed in a database
+ * @description Lists all the guideline recategorizations that were indexed in the database.
+ */
+
+import cpp
+import GuidelineRecategorizations
+
+from GuidelineRecategorization gr
+select gr.getRuleId(), gr.getCategory()

cpp/common/test/guideline_recategorizations/InvalidGuidelineRecategorizations.expected

@@ -0,0 +1,5 @@
+| invalid/coding-standards.xml:5:7:8:43 | guideline-recategorizations-entry | guideline_recategorizations/invalid/coding-standards.xml: 'Invalid recategorization from 'required' to 'advisory'.' for rule A0-1-1. |
+| invalid/coding-standards.xml:9:7:12:43 | guideline-recategorizations-entry | guideline_recategorizations/invalid/coding-standards.xml: 'Invalid recategorization from 'required' to 'disapplied'.' for rule A0-1-2. |
+| invalid/coding-standards.xml:13:7:16:43 | guideline-recategorizations-entry | guideline_recategorizations/invalid/coding-standards.xml: 'Unknown rule id 'A1-4-3'.' for rule A1-4-3. |
+| invalid/coding-standards.xml:17:7:20:43 | guideline-recategorizations-entry | guideline_recategorizations/invalid/coding-standards.xml: 'Invalid recategorization from 'mandatory' to 'required'.' for rule RULE-13-6. |
+| invalid/coding-standards.xml:21:7:24:43 | guideline-recategorizations-entry | guideline_recategorizations/invalid/coding-standards.xml: 'Invalid recategorization from 'rule' to 'required'.' for rule CON50-CPP. |

cpp/common/test/guideline_recategorizations/InvalidGuidelineRecategorizations.qlref

@@ -0,0 +1 @@
+codingstandards/cpp/guideline_recategorizations/InvalidGuidelineRecategorizations.ql

cpp/common/test/guideline_recategorizations/ListGuidelineRecategorizations.expected

@@ -0,0 +1,9 @@
+| A0-1-1 | advisory |
+| A0-1-1 | mandatory |
+| A0-1-2 | disapplied |
+| A0-1-6 | disapplied |
+| A1-4-3 | mandatory |
+| A10-4-1 | required |
+| A11-0-1 | mandatory |
+| CON50-CPP | required |
+| RULE-13-6 | required |

cpp/common/test/guideline_recategorizations/ListGuidelineRecategorizations.qlref

@@ -0,0 +1 @@
+codingstandards/cpp/guideline_recategorizations/ListGuidelineRecategorizations.ql

cpp/common/test/guideline_recategorizations/dummy.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0"?>
+<!-- Dummy XML file in root of test to ensure the XML extractor is invoked on CLIs prior to v2.10.3. -->