chore: add QA checks to Test workflow

This change adds a new `QA` job to the existing `Test` workflow. It is
done in a way that the `Test rollup` job can continue to be an enforced
status check, but with the addition of this job. A new optional `tox`
test environment named `qa` was added and is called by the `QA` job.
The environment can also be called by users locally. It relies on simply
running `pre-commit` on the existing hooks defined in the repository:

* trim trailing whitespace
* fix end of files
* check yaml
* check for added large files
* `black`
* `pyupgrade`
* analyze lockfile with `phylum-ci`

The `pre-commit` package was added as a dependency in the `qa` group and
can therefore be kept under configuration control and used by `poetry`.
Documentation was updated to make all the new usage patterns explicit.

Additional QA checks and `pre-commit` hooks will be added separatetely.

.github/workflows/test.yml

@@ -10,17 +10,50 @@ on:
     branches:
       - main
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
+  QA:
+    name: Quality Assurance
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # It's only one Python version specified in a "matrix", but on purpose to stay DRY
+        python-version: ["3.11"]
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v3.5.0
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - name: Configure poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Set up Python
+        uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'poetry'
+
+      - name: Install the project with poetry
+        run: |
+          poetry env use python${{ matrix.python-version }}
+          poetry lock --check
+          poetry install --verbose --no-root --sync --with qa
+
+      - name: Run tox via poetry
+        run: poetry run tox run -e qa
+
   test-matrix:
     name: Test on Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
         python-version: ["3.8", "3.9", "3.10", "3.11"]
-    defaults:
-      run:
-        shell: bash
     steps:
       - name: Checkout the repo
         uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v3.5.0
@@ -55,9 +88,6 @@ jobs:
       matrix:
         # It's only one Python version specified in a "matrix", but on purpose to stay DRY
         python-version: ["3.11"]
-    defaults:
-      run:
-        shell: bash
     env:
       DOCKER_BUILDKIT: 1
     steps:
@@ -123,18 +153,16 @@ jobs:
   # the repo settings without needing to update those settings everytime the test jobs are updated.
   test-rollup:
     name: Test rollup
-    if: always()
-    needs: [test-matrix, docker]
     runs-on: ubuntu-latest
+    if: always()
+    needs: [QA, test-matrix, docker]
     steps:
       - name: Check for test jobs failure
-        if: (needs.test-matrix.result != 'success') || (needs.docker.result != 'success')
-        shell: bash
+        if: (needs.QA.result != 'success') || (needs.test-matrix.result != 'success') || (needs.docker.result != 'success')
         run: |
-          echo "One or more test matrix jobs was/were not successful"
+          echo "At least one test job was not successful"
           exit 1
 
       - name: Confirm test jobs success
-        if: (needs.test-matrix.result == 'success') && (needs.docker.result == 'success')
-        shell: bash
-        run: echo "All test matrix jobs were successful"
+        if: (needs.QA.result == 'success') && (needs.test-matrix.result == 'success') && (needs.docker.result == 'success')
+        run: echo "All test jobs were successful"

CONTRIBUTING.md

@@ -140,9 +140,10 @@ Here's how to set up `phylum-ci` for local development.
     # Install the main dependencies only:
     poetry install --sync
 
-    # Alternatively, specific dependency groups can be installed at the same time.
-    # It makes sense to add the "test" group now if new code is going to be added and tested:
-    poetry install --sync --with test
+    # Alternatively, specific dependency groups can be installed at the
+    # same time. It makes sense to add the "test" and "qa" groups now
+    # if new code is going to be added and tested:
+    poetry install --sync --with test,qa
     ```
 
 6. Create a branch for local development:
@@ -180,12 +181,13 @@ Here's how to set up `phylum-ci` for local development.
     phylum analyze poetry.lock
     ```
 
-8. When you're done making changes, check that your changes pass the tests:
+8. When you're done making changes, check that your changes pass QA and the tests:
 
     ```sh
-    # Ensure the "test" dependency group is installed, if not done previously
-    poetry install --sync --with test
-    poetry run tox
+    # Ensure the "test" and "qa" dependency groups are installed, if not done previously
+    poetry install --sync --with test,qa
+    poetry run tox run -e qa
+    poetry run tox run-parallel
     ```
 
 9. Commit your changes and push your branch to GitHub:
@@ -232,16 +234,16 @@ interact with `pytest` by passing additional positional arguments:
 ```sh
 # passing additional options to pytest requires using the double dash
 # escape twice, once for escaping `poetry` and again for escaping `tox`
-poetry run -- tox -e py310 -- --help
+poetry run -- tox run -e py310 -- --help
 
-# run a specific test module across all test environments
-poetry run -- tox -- tests/unit/test_package_metadata.py
+# run a specific test module across all test environments in parallel
+poetry run -- tox run-parallel -- tests/unit/test_package_metadata.py
 
 # run a specific test module across a specific test environment
-poetry run -- tox -e py39 -- tests/unit/test_package_metadata.py
+poetry run -- tox run -e py39 -- tests/unit/test_package_metadata.py
 
 # run a specific test function within a test module, in a specific test environment
-poetry run -- tox -e py310 -- tests/unit/test_package_metadata.py::test_python_version
+poetry run -- tox run -e py310 -- tests/unit/test_package_metadata.py::test_python_version
 ```
 
 To run a script entry point with the local checkout of the code (in develop mode), use `poetry`:

pyproject.toml

@@ -76,6 +76,7 @@ optional = true
 
 [tool.poetry.group.qa.dependencies]
 types-requests = "*"
+pre-commit = "*"
 
 [tool.black]
 line-length = 120

src/phylum/ci/constants.py

@@ -12,7 +12,7 @@
 
 SUCCESS_DETAILS = "The Phylum risk analysis is complete and did not identify any issues."
 
-# Expandable HTML providing information on why there was a failure
+# Background text providing information on why there was a failure
 FAILURE_DETAILS = """
         This repository analyzes risk of new dependencies with Phylum. An administrator
         of this repository has set score requirements for Phylum's five risk domains.

tox.ini

@@ -1,4 +1,6 @@
 [tox]
+# Sub-commands were introduced in v4. These are used in workflows and docs.
+min_version = 4
 envlist = py38, py39, py310, py311
 isolated_build = true
 
@@ -10,10 +12,22 @@ python =
     3.11: py311
 
 [testenv]
+description = Test environment for minor Python version
 passenv = *
+# Skip the local package install so that `poetry` can handle installing
+# all of the dependencies and do so only from the `poetry.lock` lockfile.
+skip_install = true
 allowlist_externals = poetry
 commands =
     poetry lock --check
     poetry install --verbose --sync --with test
     poetry run python -m pip list
     poetry run pytest {posargs}
+
+[testenv:qa]
+description = Quality Assurance (QA) checks
+commands =
+    poetry lock --check
+    poetry install --verbose --sync --with qa
+    poetry run python -m pip list
+    poetry run pre-commit run --all-files --verbose