Merge pull request #68 from rvermeulen/guideline-recategorization

Guideline recategorization support

Author: rvermeulen

.github/workflows/code-scanning-pack-gen.yml

@@ -86,7 +86,7 @@ jobs:
           codeql query compile --search-path c --search-path cpp --threads 0 c
 
           cd ..
-          zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/deviations codeql-coding-standards/scripts/reports
+          zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/configuration codeql-coding-standards/scripts/reports codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/guideline_recategorization codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/schemas
 
       - name: Upload GHAS Query Pack
         uses: actions/upload-artifact@v2

.github/workflows/tooling-unit-tests.yml

@@ -0,0 +1,91 @@
+name: 🧰 Tooling unit tests
+
+on:
+  push:
+    branches:
+      - main
+      - "rc/**"
+      - next
+  pull_request:
+    branches:
+      - main
+      - "rc/**"
+      - next
+
+jobs:
+  prepare-supported-codeql-env-matrix:
+    name: Prepare supported CodeQL environment matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.export-supported-codeql-env-matrix.outputs.matrix }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Export supported CodeQL environment matrix
+        id: export-supported-codeql-env-matrix
+        run: |
+          echo "::set-output name=matrix::$(
+            jq --compact-output '.supported_environment | {include: .}' supported_codeql_configs.json
+          )"
+
+  analysis-report-tests:
+    name: Run analysis report tests
+    needs: prepare-supported-codeql-env-matrix
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.prepare-supported-codeql-env-matrix.outputs.matrix) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
+      - name: Install Python dependencies
+        run: pip install -r scripts/reports/requirements.txt
+
+      - name: Cache CodeQL
+        id: cache-codeql
+        uses: actions/cache@v2.1.3
+        with:
+          path: ${{ github.workspace }}/codeql_home
+          key: codeql-home-${{ matrix.os }}-${{ matrix.codeql_cli }}-${{ matrix.codeql_standard_library }}
+
+      - name: Install CodeQL
+        if: steps.cache-codeql.outputs.cache-hit != 'true'
+        uses: ./.github/actions/install-codeql
+        with:
+          codeql-cli-version: ${{ matrix.codeql_cli }}
+          codeql-stdlib-version: ${{ matrix.codeql_standard_library }}
+          codeql-home: ${{ github.workspace }}/codeql_home
+          add-to-path: false
+
+      - name: Run PyTest
+        env:
+          CODEQL_HOME: ${{ github.workspace }}/codeql_home
+        run: |
+          PATH=$PATH:$CODEQL_HOME/codeql
+          pytest scripts/reports/analysis_report_test.py
+
+  recategorization-tests:
+    name: Run Guideline Recategorization tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
+      - name: Install Python dependencies
+        run: pip install -r scripts/guideline_recategorization/requirements.txt
+
+      - name: Run PyTest
+        run: |
+          pytest scripts/guideline_recategorization/recategorize_test.py

.github/workflows/validate-coding-standards.yml

@@ -28,6 +28,15 @@ jobs:
         with:
           python-version: "3.9"
 
+      - name: Install CodeQL
+        run: |
+          VERSION="v$( jq -r '.supported_environment | .[0] | .codeql_cli' supported_codeql_configs.json)"
+          gh extensions install github/gh-codeql
+          gh codeql set-version "$VERSION"
+          gh codeql install-stub
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
       - name: Install generate_package_files.py dependencies
         run: pip install -r scripts/requirements.txt
 
@@ -49,14 +58,14 @@ jobs:
 
       - name: Validate Package Files (CPP)
         run: |
-          find rule_packages/cpp -name \*.json -exec basename {} .json \; | xargs --max-procs "$XARGS_MAX_PROCS" --max-args 1 python scripts/generate_rules/generate_package_files.py cpp
+          find rule_packages/cpp -name \*.json -exec basename {} .json \; | xargs python scripts/generate_rules/generate_package_files.py cpp
           git diff
           git diff --compact-summary
           git diff --quiet
 
       - name: Validate Package Files (C)
         run: |
-          find rule_packages/c -name \*.json -exec basename {} .json \; | xargs --max-procs "$XARGS_MAX_PROCS" --max-args 1 python scripts/generate_rules/generate_package_files.py c
+          find rule_packages/c -name \*.json -exec basename {} .json \; | xargs python scripts/generate_rules/generate_package_files.py c
           git diff
           git diff --compact-summary
           git diff --quiet
@@ -68,25 +77,26 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v2
 
-      - name: Fetch CodeQL
+      - name: Install CodeQL
         run: |
-          TAG="v$( jq -r '.supported_environment | .[0] | .codeql_cli' supported_codeql_configs.json)"
-          gh release download $TAG --repo https://github.com/github/codeql-cli-binaries --pattern codeql-linux64.zip
-          unzip -q codeql-linux64.zip
+          VERSION="v$( jq -r '.supported_environment | .[0] | .codeql_cli' supported_codeql_configs.json)"
+          gh extensions install github/gh-codeql
+          gh codeql set-version "$VERSION"
+          gh codeql install-stub
         env:
           GITHUB_TOKEN: ${{ github.token }}
 
       - name: Validate CodeQL Format (CPP)
         run: |
-          find cpp -name \*.ql -or -name \*.qll -print0 | xargs -0 --max-procs "$XARGS_MAX_PROCS" codeql/codeql query format --in-place
+          find cpp -name \*.ql -or -name \*.qll -print0 | xargs -0 --max-procs "$XARGS_MAX_PROCS" codeql query format --in-place
 
           git diff
           git diff --compact-summary
           git diff --quiet
 
       - name: Validate CodeQL Format (C)
         run: |
-          find c -name \*.ql -or -name \*.qll -print0 | xargs -0 --max-procs "$XARGS_MAX_PROCS" codeql/codeql query format --in-place
+          find c -name \*.ql -or -name \*.qll -print0 | xargs -0 --max-procs "$XARGS_MAX_PROCS" codeql query format --in-place
 
           git diff
           git diff --compact-summary

change_notes/2022-11-07-add-guideline-recategorization-scripts.md

@@ -0,0 +1,2 @@
+- Add the Python scripts under `scripts/guideline_recategorization` and the JSON schemas under `schemas`.
+- Add the Python scripts under `scripts/shared` relied upon by the analysis report generation.

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/Exclusions.qll

@@ -25,20 +25,25 @@ predicate isExcluded(Element e) {
 }
 
 bindingset[e, query]
-predicate isExcluded(Element e, Query query) {
-  e instanceof ExcludedElement
+predicate isExcluded(Element e, Query query) { isExcluded(e, query, _) }
+
+bindingset[e, query]
+predicate isExcluded(Element e, Query query, string reason) {
+  e instanceof ExcludedElement and reason = "Element is an excluded element."
   or
-  e.getFile() instanceof ExcludedFile
+  e.getFile() instanceof ExcludedFile and reason = "Element is part of an excluded file."
   or
-  not exists(e.getFile())
+  not exists(e.getFile()) and reason = "Element is not part of the source repository."
   or
-  // There exists a `DeviationRecord` that applies to this element and query
+  // There exists a `DeviationRecord` that applies to this element and query, and the query's effective category permits deviation.
+  query.getEffectiveCategory().permitsDeviation() and
   exists(DeviationRecord dr | applyDeviationsAtQueryLevel() |
     // The element is in a file which has a deviation for this query
     exists(string path |
       dr.isDeviated(query, path) and
       e.getFile().getRelativePath().prefix(path.length()) = path
-    )
+    ) and
+    reason = "Query has an associated deviation record for the element's file."
     or
     // The element is on the same line as a suppression comment
     exists(Comment c |
@@ -50,6 +55,13 @@ predicate isExcluded(Element e, Query query) {
         e.getLocation().hasLocationInfo(filepath, _, _, endLine, _) and
         c.getLocation().hasLocationInfo(filepath, endLine, _, _, _)
       )
-    )
+    ) and
+    reason =
+      "Query has an associated deviation record with a code identifier that is applied to the element."
   )
+  or
+  // The effective category of the query is 'Disapplied'.
+  // This can occur when a Guideline Recategorization Plan is applied.
+  query.getEffectiveCategory().isDisapplied() and
+  reason = "The query is disapplied."
 }

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 */
@@ -357,6 +332,13 @@ class DeviationRecord extends XMLElement {
     hasPermitId() and
     not hasADeviationPermit() and
     result = "There is no deviation permit with id `" + getPermitId() + "`."
+    or
+    exists(Query q | q.getQueryId() = getQueryId() |
+      not q.getEffectiveCategory().permitsDeviation() and
+      result =
+        "The deviation is applied to a query with the rule category '" +
+          q.getEffectiveCategory().toString() + "' that does not permit a deviation."
+    )
   }
 
   /** Holds if the deviation record is valid */