Open sourcing CodeQL Coding Standards

Author: rvermeulen

Diff for: .github/pull_request_template.md

@@ -20,7 +20,7 @@ _please enter the description of your change here_
 
 ## Release change checklist
 
-A change note ([development_handbook.md#change-notes](https://github.com/github/codeql-coding-standards/blob/main/development_handbook.md#change-notes)) is required for any pull request which modifies:
+A change note ([development_handbook.md#change-notes](https://github.com/github/codeql-coding-standards/blob/main/docs/development_handbook.md#change-notes)) is required for any pull request which modifies:
 
  - The structure or layout of the release artifacts.
  - The evaluation performance (memory, execution time) of an existing query.
@@ -44,7 +44,7 @@ For PRs that add new queries or modify existing queries, the following checklist
  - [ ] Have all the relevant rule package description files been checked in?
  - [ ] Have you verified that the metadata properties of each new query is set appropriately?
  - [ ] Do all the unit tests contain both "COMPLIANT" and "NON_COMPLIANT" cases?
- - [ ] Are the alert messages properly formatted and consistent with the [style guide](https://github.com/github/codeql-coding-standards/blob/main/development_handbook.md#query-style-guide)?
+ - [ ] Are the alert messages properly formatted and consistent with the [style guide](https://github.com/github/codeql-coding-standards/blob/main/docs/development_handbook.md#query-style-guide)?
  - [ ] Have you run the queries on OpenPilot and verified that the performance and results are acceptable?<br />_As a rule of thumb, predicates specific to the query should take no more than 1 minute, and for simple queries be under 10 seconds. If this is not the case, this should be highlighted and agreed in the code review process._
  - [ ] Does the query have an appropriate level of in-query comments/documentation?
  - [ ] Have you considered/identified possible edge cases?
@@ -56,7 +56,7 @@ For PRs that add new queries or modify existing queries, the following checklist
  - [ ] Have all the relevant rule package description files been checked in?
  - [ ] Have you verified that the metadata properties of each new query is set appropriately?
  - [ ] Do all the unit tests contain both "COMPLIANT" and "NON_COMPLIANT" cases?
- - [ ] Are the alert messages properly formatted and consistent with the [style guide](https://github.com/github/codeql-coding-standards/blob/main/development_handbook.md#query-style-guide)?
+ - [ ] Are the alert messages properly formatted and consistent with the [style guide](https://github.com/github/codeql-coding-standards/blob/main/docs/development_handbook.md#query-style-guide)?
  - [ ] Have you run the queries on OpenPilot and verified that the performance and results are acceptable?<br />_As a rule of thumb, predicates specific to the query should take no more than 1 minute, and for simple queries be under 10 seconds. If this is not the case, this should be highlighted and agreed in the code review process._
  - [ ] Does the query have an appropriate level of in-query comments/documentation?
  - [ ] Have you considered/identified possible edge cases?

Diff for: .github/workflows/code-scanning-pack-gen.yml

@@ -5,13 +5,13 @@ on:
     branches:
       - main
       - "rc/**"
-      - "c-coding-standards"
+      - next
 
   push:
     branches:
       - main
       - "rc/**"
-      - "c-coding-standards"
+      - next
 
 env:
   XARGS_MAX_PROCS: 4
@@ -59,25 +59,23 @@ jobs:
           codeql-home: ${{ github.workspace }}/codeql_home
           add-to-path: false
 
-      - name: Install latest CodeQL for docs generation
-        id: install-latest-codeql
-        uses: ./.github/actions/install-codeql
+      - name: Install Python
+        uses: actions/setup-python@v4
         with:
-          add-to-path: false
+          python-version: "3.9"
 
       - name: Anonymising and pre-compiling queries
         env:
           CODEQL_HOME: ${{ github.workspace }}/codeql_home
-          CODEQL_LATEST_HOME: ${{ steps.install-latest-codeql.outputs.codeql-home}}
         run: |
           PATH=$PATH:$CODEQL_HOME/codeql
           pip install -r scripts/requirements.txt
-          find rule_packages/cpp -name '*.json' -exec basename {} .json \; | xargs --max-procs "$XARGS_MAX_PROCS" --max-args 1 python3 scripts/generate_rules/generate_package_files.py -a cpp
-          find rule_packages/c -name '*.json' -exec basename {} .json \; | xargs --max-procs "$XARGS_MAX_PROCS" --max-args 1 python3 scripts/generate_rules/generate_package_files.py --skip-shared-test-generation -a c
+          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 -a cpp
+          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 --skip-shared-test-generation -a c
 
-          echo "Generating help markdown file for cert"
-          $CODEQL_LATEST_HOME/codeql/codeql generate query-help -vvv --format=markdown -o cpp/cert/src/ cpp/cert/src/rules
-          $CODEQL_LATEST_HOME/codeql/codeql generate query-help -vvv --format=markdown -o c/cert/src/ c/cert/src/rules
+          echo "Remove help files that cannot be freely distributed"
+          find cpp/autosar/src/rules -name "*.md" -delete
+          find c/misra/src/rules -name "*.md" -delete
 
           codeql query compile --search-path cpp --threads 0 cpp
           codeql query compile --search-path c --search-path cpp --threads 0 c
@@ -103,12 +101,11 @@ jobs:
               copy_to_root_name=$(realpath --relative-to "./$2/$1/src/" "$copy_from_root_name")
               query_dir=$(dirname "lgtm-cpp-query-pack/$copy_to_root_name")
               mkdir -p "$query_dir"
-              # Copy each selected ql file, plus the related files (qhelp, qhelp implementation)
+              # Copy each selected ql file
               cp "$copy_from_root_name.ql" "lgtm-cpp-query-pack/$copy_to_root_name.ql"
-              cp "$copy_from_root_name.qhelp" "lgtm-cpp-query-pack/$copy_to_root_name.qhelp"
             done
           }
-          
+
           echo "Copying autosar-default queries (CPP)"
           copy_queries_for_pack "autosar" "cpp"
           echo "Copying cert-default queries (CPP)"
@@ -186,30 +183,25 @@ jobs:
           codeql-home: ${{ github.workspace }}/codeql_home
           add-to-path: false
 
-      - name: Install latest CodeQL for docs generation
-        id: install-latest-codeql
-        uses: ./.github/actions/install-codeql
+      - name: Checkout external help files
+        uses: actions/checkout@v2
         with:
-          add-to-path: false
+          ssh-key: ${{ secrets.CODEQL_CODING_STANDARDS_HELP_KEY }}
+          repository: "github/codeql-coding-standards-help"
+          ref: ${{ github.head_ref }}
+          path: external-help-files
+
+      - name: Include external help files
+        run: |
+          pushd external-help-files
+          find . -name '*.md' -exec rsync -av --relative {} "$GITHUB_WORKSPACE" \;
+          popd
 
       - name: Pre-compiling queries
         env:
           CODEQL_HOME: ${{ github.workspace }}/codeql_home
-          CODEQL_LATEST_HOME: ${{ steps.install-latest-codeql.outputs.codeql-home}}
         run: |
           PATH=$PATH:$CODEQL_HOME/codeql
-          for s in "autosar" "cert"
-          do
-            echo "Generating help markdown file for $s"
-            $CODEQL_LATEST_HOME/codeql/codeql generate query-help -vvv --format=markdown -o cpp/$s/src/ cpp/$s/src/rules
-          done
-
-          for s in "misra" "cert"
-          do
-            echo "Generating help markdown file for $s"
-            $CODEQL_LATEST_HOME/codeql/codeql generate query-help -vvv --format=markdown -o c/$s/src/ c/$s/src/rules
-          done
-
 
           codeql query compile --search-path cpp --threads 0 cpp
           codeql query compile --search-path c --search-path cpp --threads 0 c
@@ -234,8 +226,8 @@ jobs:
             do
               copy_to_root="lgtm-cpp-query-pack/$(realpath --relative-to "./$2/$1/src/" "$rule_dir")"
               mkdir -p "$copy_to_root"
-              # Copy each selected ql file, plus the related files (qhelp, qhelp implementation)
-              find "$rule_dir" -name '*.ql' -o -name '*.qhelp' -o -name '*.c' -name '*.cpp' -o -name '*.png' -exec cp -n {} "$copy_to_root" \;
+              # Copy each selected ql file, plus the related files
+              find "$rule_dir" -name '*.ql' -o -name '*.c' -name '*.cpp' -o -name '*.png' -exec cp -n {} "$copy_to_root" \;
             done
           }
           echo "Copying autosar-default queries (CPP)"

Diff for: .github/workflows/codeql_unit_tests.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - main
       - "rc/**"
+      - next
   pull_request:
     branches:
       - "**"
@@ -42,10 +43,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v2
 
-      - name: Setup Python 3
-        uses: actions/setup-python@v2
+      - name: Install Python
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.x"
+          python-version: "3.9"
 
       - name: Cache CodeQL
         id: cache-codeql

Diff for: .github/workflows/create-draft-release.yml

@@ -41,6 +41,11 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
       - name: Install generate_release_notes.py dependencies
         run: pip install -r scripts/requirements.txt
 

Diff for: .github/workflows/generate-html-docs.yml

@@ -5,10 +5,12 @@ on:
     branches:
       - main
       - 'rc/**'
+      - next
   pull_request:
     branches:
       - main
       - 'rc/**'
+      - next
 
 jobs:
   generate-html-doc:
@@ -18,6 +20,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v2
 
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
       - name: Install generate_iso26262_docs.py dependencies
         run: pip install -r scripts/requirements.txt
 

Diff for: .github/workflows/standard_library_upgrade_tests.yml

@@ -6,6 +6,7 @@ on:
     branches:
       - main
       - "rc/**"
+      - next
     paths:
       - "supported_codeql_configs.json"
   workflow_dispatch:
@@ -155,10 +156,10 @@ jobs:
     needs: [run-test-suites]
     runs-on: ubuntu-latest
     steps:
-      - name: Setup Python 3
-        uses: actions/setup-python@v2
+      - name: Install Python
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.x"
+          python-version: "3.9"
 
       - name: Collect test results
         uses: actions/download-artifact@v2

Diff for: .github/workflows/validate-coding-standards.yml

@@ -4,12 +4,13 @@ on:
   push:
     branches:
       - main
-      - 'rc/**'
+      - "rc/**"
+      - next
   pull_request:
     branches:
       - main
-      - 'rc/**'
-      - 'c-coding-standards'
+      - "rc/**"
+      - next
 
 env:
   XARGS_MAX_PROCS: 4
@@ -22,6 +23,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v2
 
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
       - name: Install generate_package_files.py dependencies
         run: pip install -r scripts/requirements.txt
 
@@ -43,19 +49,18 @@ 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 python3 scripts/generate_rules/generate_package_files.py cpp
+          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
           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 python3 scripts/generate_rules/generate_package_files.py c
+          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
           git diff
           git diff --compact-summary
           git diff --quiet
 
-
   validate-codeql-format:
     name: "Validate CodeQL Format"
     runs-on: ubuntu-latest
@@ -90,41 +95,37 @@ jobs:
   validate-query-help-files:
     name: Validate Query Help Files
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        language: ['cpp', 'c']
     steps:
       - name: Checkout
         uses: actions/checkout@v2
 
-      - name: Fetch CodeQL
+      - name: Validate CPP Query Help Files
         run: |
-          gh release download --repo https://github.com/github/codeql-cli-binaries --pattern codeql-linux64.zip
-          unzip -q codeql-linux64.zip
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
+          exit_code=0
+          for help_file in `find cpp -name '*.md'`
+          do
+            if grep -F -q 'REPLACE THIS' "$help_file" > /dev/null
+            then
+              echo "Help file $help_file contains placeholders that are not replaced or removed!"
+              exit_code=1
+            fi
+          done
+
+          exit $exit_code
 
-      - name: Validate Query Help Files
+      - name: Validate C Query Help Files
         run: |
-          qhelp_output=$(( codeql/codeql generate query-help --format=markdown --output=${{ matrix.language }}/qhelp-markdown-dump ${{ matrix.language }} ) 2>&1 )
-          qhelp_count=$(find ${{ matrix.language }} -name \*.ql -or -name \*.qhelp | wc -l)
-
-          if [[ $qhelp_output ]]; then
-            errors=$( echo "$qhelp_output" | grep -v '/test/' || [[ $? == 1 ]] )
-            if [[ $errors ]]; then
-              echo "There are errors with the qhelp files: "
-              echo "$errors"
-              exit 1
-            else
-              echo "Disregarding tests..."
-              echo "Query help files look good."
+          exit_code=0
+          for help_file in `find c -name '*.md'`
+          do
+            if grep -F -q 'REPLACE THIS' "$help_file" > /dev/null
+            then
+              echo "Help file $help_file contains placeholders that are not replaced or removed!"
+              exit_code=1
             fi
-          elif [[ ! $qhelp_output && qhelp_count -gt 0 ]]; then
-            echo "Query help files look good."
-          else
-            echo "There are no query help files to analyze."
-          fi
+          done
+
+          exit $exit_code
 
   validate-cpp-test-files:
     name: Validate C++ Test Files
@@ -143,7 +144,7 @@ jobs:
           if ! test -f .clang-format; then
             echo "Cannot find .clang-format in '$PWD'. Exiting..."
           fi
-          
+
           find cpp/*/test -name \*.cpp -print0 | xargs -0 --max-procs "$XARGS_MAX_PROCS" clang-format --style=file -i --verbose
           git diff
           git diff --compact-summary
@@ -166,7 +167,7 @@ jobs:
           if ! test -f .clang-format; then
             echo "Cannot find .clang-format in '$PWD'. Exiting..."
           fi
-          
+
           find c/*/test -name \*.c -print0 | xargs -0 --max-procs "$XARGS_MAX_PROCS" clang-format --style=file -i --verbose
           git diff
           git diff --compact-summary