feat: add git pre-commit hook integration (#91)

The `phylum-ci` script entry point already had most of the code for a `pre-commit` environment. This PR updated that code to account for some edge cases.

The `.pre-commit-hooks.yaml` file was added, with a single hook configuration defined for use in consuming repositories. This is a Python hook and works without any additional system-level dependencies. If the `phylum` CLI binary is installed locally, it will be used. Otherwise, the hook will install it.

There was an attempt to add a second hook which would make use of the `phylumio/phylum-ci` docker image. This proved too difficult to implement without overhauling the way the image is used in regards to entrypoints. The only real loss is for users who may not want to have the `phylum` CLI installed locally and prefer a self-contained Docker environment instead.

Up until now, the CI environments that have been implemented allow for output, in the form of review comments, to be posted as rendered markdown. The environments that don't use CI...`pre-commit` and `no-CI` so far...display their output in the terminal. Instead of writing separate output for these environments, a conversion utility library (`connect-markdown-renderer`) is used to render the existing markdown output in the terminal. Additionally, the labels for these environments were shortened to be more readable...in both the output as a link and the Phylum UI in the label dropdown menu.

A local git pre-commit hook configuration was added to this repository. This will help to dog-food the integration and understand the `pre-commit` environment more generally. Like all `pre-commit` configurations, this is opt-in for individual developers. More hooks may be added when #14 is tackled.

Other actions taken:

* Rename `poetry_update` workflow to `auto_updates`
* Update the `auto_updates` workflow
  * Enable auto updates of the pre-commit hooks to the latest tags
    * Use immutable hashes instead of tag names
  * Ensure commits by `phylum-bot` are signed
  * Rename the workflow and branch names
* Add git `pre-commit` documentation

Closes #35

.github/workflows/poetry_update.yml → .github/workflows/auto_updates.yml

@@ -1,5 +1,6 @@
 # This is a workflow for updating Python dependencies with Poetry.
 # Major version updates are handled separately, by Dependabot.
+# It will also update the pre-commit hooks to use latest tags.
 ---
 name: Update Deps
 
@@ -10,8 +11,8 @@ on:
     - cron: '35 14 * * 1'
 
 jobs:
-  poetry-update:
-    name: Update Python dependencies
+  workflow-auto-updates:
+    name: Update dependencies and hooks
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -24,8 +25,19 @@ jobs:
       - name: Checkout the repo
         uses: actions/checkout@v3
 
-      - name: Install poetry
-        run: pipx install poetry
+      # This GPG key is for the `phylum-bot` account and used in order to ensure commits are signed/verified
+      - name: Import GPG key for bot account
+        uses: crazy-max/ghaction-import-gpg@v5
+        with:
+          gpg_private_key: ${{ secrets.PHYLUM_BOT_GPG_PRIVATE_KEY }}
+          passphrase: ${{ secrets.PHYLUM_BOT_GPG_PASSPHRASE }}
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+
+      - name: Install poetry and pre-commit
+        run: |
+          pipx install poetry
+          pipx install pre-commit
 
       - name: Configure poetry
         run: poetry config virtualenvs.in-project true
@@ -45,17 +57,20 @@ jobs:
           poetry env use python${{ matrix.python-version }}
           poetry install --verbose --no-root
 
-      - name: Poetry update
+      - name: Update Python dependencies
         run: poetry update -vv
 
+      - name: Update pre-commit hooks
+        run: pre-commit autoupdate --freeze
+
       - name: Commit changes
         id: commit
         continue-on-error: true
+        # NOTE: The git user name and email used for commits is already configured,
+        #       by the crazy-max/ghaction-import-gpg action.
         run: |
-          git config user.name 'Phylum Bot'
-          git config user.email '[email protected]'
-          git commit -a -m "build: Bump poetry.lock dependencies"
-          git push --force origin HEAD:auto-poetry-update
+          git commit -a -m "build: Bump poetry.lock dependencies and pre-commit hooks"
+          git push --force origin HEAD:workflow-auto-updates
 
       - name: Create Pull Request
         if: ${{ steps.commit.outcome == 'success' }}
@@ -66,8 +81,8 @@ jobs:
             github.rest.pulls.create({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              head: "auto-poetry-update",
+              head: "workflow-auto-updates",
               base: context.ref,
-              title: "build: Bump poetry.lock dependencies",
-              body: "Bump dependencies in poetry.lock for all SemVer-compatible updates.",
+              title: "build: Bump poetry.lock dependencies and pre-commit hooks",
+              body: "Bump dependencies in `poetry.lock` and hooks in `.pre-commit-config.yaml`.",
             });

.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+# This is the config for using `pre-commit` on this repository.
+#
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+#
+# NOTE: Individual hook revisions are kept up to date automatically with
+#       the `auto_updates` workflow, which bumps hooks to the latest tag.
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3298ddab3c13dd77d6ce1fc0baf97691430d84b0  # frozen: v4.3.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: f6c139c5215ce04fd3e73a900f1372942d58eca0  # frozen: 22.6.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: a78007c1e9de96e71d5fb3e720c2b9fae8ed8abf  # frozen: v2.37.3
+    hooks:
+      - id: pyupgrade
+        args: [--py37-plus]
+
+  # NOTE: don't use this config for your own repositories. Instead, see
+  #       "Git pre-commit Integration" in `docs/sync/git_precommit.md`
+  - repo: local
+    hooks:
+      - id: phylum-ci
+        name: analyze lockfile with phylum-ci
+        language: system
+        files: ^poetry\.lock$
+        entry: poetry run phylum-ci

.pre-commit-hooks.yaml

@@ -0,0 +1,11 @@
+# This is the config for defining `pre-commit` hooks for use in other repositories.
+#
+# See https://pre-commit.com for more information
+---
+- id: phylum
+  name: analyze lockfile with phylum
+  description: Run `phylum` on a dependency lockfile
+  entry: phylum-ci
+  language: python
+  require_serial: true
+  stages: [commit]

CONTRIBUTING.md

@@ -87,7 +87,20 @@ Here's how to set up `phylum-ci` for local development.
     git clone [email protected]:phylum-dev/phylum-ci.git
     ```
 
-2. Ensure all supported Python versions are installed locally
+2. Optional: Install [pre-commit](https://pre-commit.com/) and the local hooks
+
+    ```sh
+    # If the `pre-commit` tool is not already installed, the recommended method is to use pipx
+    pipx install pre-commit
+
+    # Installing with homebrew is another good option
+    brew install pre-commit
+
+    # Use the `pre-commit` tool to install the git hooks used by the repository
+    pre-commit install
+    ```
+
+3. Ensure all supported Python versions are installed locally
    1. The strategy is to support all released minor versions of Python that are not end-of-life yet
    2. The current list
       1. at the time of this writing is 3.7, 3.8, 3.9, and 3.10
@@ -108,59 +121,64 @@ Here's how to set up `phylum-ci` for local development.
     pyenv global 3.10.x 3.9.x 3.8.x 3.7.x
     ```
 
-3. Ensure [poetry](https://python-poetry.org/docs/) is installed
-4. Install dependencies with `poetry`, which will automatically create a virtual environment:
+4. Ensure [poetry](https://python-poetry.org/docs/) is installed
+5. Install dependencies with `poetry`, which will automatically create a virtual environment:
 
     ```sh
     cd phylum-ci
     poetry install
     ```
 
-5. Create a branch for local development:
+6. Create a branch for local development:
 
     ```sh
     git checkout -b <name-of-your-branch>
     ```
 
     Now you can make your changes locally.
 
-6. If new dependencies are added, do so in a way that does not add upper version constraints and ensure
+7. If new dependencies are added, do so in a way that does not add upper version constraints and ensure
    the `poetry.lock` file is updated (and committed):
 
     ```sh
     # Unless there is a reason to do so, prefer to add dependencies without constraints
-    poetry add new-dependency-name
+    poetry add "new-dependency-name==*"
 
-    # When a version constraint is not specified, poetry chooses one. For example (in pyproject.toml):
+    # When a version constraint is not specified, poetry chooses one. For example, the command:
+    #
+    #   $ poetry add new-dependency-name
+    #
+    # results in a caret-style version constraint added to the dependency in pyproject.toml:
     #
     #   new-dependency-name = "^1.2.3"
     #
-    # Unless the constraint was intentional, change the entry to remove the constraint:
+    # Unless the constraint was intentional, change the pyproject.toml entry to remove the constraint:
     #
     #   new-dependency-name = "*"
 
     # Update the lockfile and the local environment to get the latest versions of dependencies
     poetry update
 
-    # Dependencies will be checked automatically in CI during a PR, but checking locally is possible:
+    # Dependencies will be checked automatically in CI during a PR. They will also be checked
+    # with the local pre-commit hook, if enabled. Manually checking locally is also possible:
     phylum analyze poetry.lock
     ```
 
-7. 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 the tests:
 
     ```sh
     poetry run tox
     ```
 
-8. Commit your changes and push your branch to GitHub:
+9. Commit your changes and push your branch to GitHub:
 
     ```sh
     git add .
     git commit -m "Description of the changes goes here"
     git push --set-upstream origin <name-of-your-branch>
     ```
 
-9. Submit a pull request (PR) through the GitHub website
+10. Submit a pull request (PR) through the GitHub website
 
 ## Pull Request Guidelines
 

README.md

@@ -7,6 +7,7 @@
 ![GitHub last commit](https://img.shields.io/github/last-commit/phylum-dev/phylum-ci)
 [![GitHub Workflow Status (branch)][workflow_shield]][workflow_test]
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)][CoC]
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)][pre-commit]
 
 Utilities for integrating Phylum into CI pipelines (and beyond)
 
@@ -15,6 +16,7 @@ Utilities for integrating Phylum into CI pipelines (and beyond)
 [workflow_shield]: https://img.shields.io/github/workflow/status/phylum-dev/phylum-ci/Test/main?label=Test&logo=GitHub
 [workflow_test]: https://github.com/phylum-dev/phylum-ci/actions/workflows/test.yml
 [CoC]: https://github.com/phylum-dev/phylum-ci/blob/main/CODE_OF_CONDUCT.md
+[pre-commit]: https://github.com/pre-commit/pre-commit
 [contributing]: https://github.com/phylum-dev/phylum-ci/blob/main/CONTRIBUTING.md
 [changelog]: https://github.com/phylum-dev/phylum-ci/blob/main/CHANGELOG.md
 [security]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/security.md
@@ -116,14 +118,18 @@ The current CI platforms/environments supported are:
 * GitHub Actions
   * See the [GitHub Actions Integration documentation][github_docs] for more info
 
+* Git `pre-commit` Hooks
+  * See the [Git `pre-commit` Integration documentation][precommit_docs] for more info
+
 * None (local use)
   * This is the "fall-through" case used when no other environment is detected
   * Can be useful to analyze lockfiles locally, prior to or after submitting a pull/merge request (PR/MR) to a CI system
     * Establishing a successful submission prior to submitting a PR/MR to a CI system
     * Troubleshooting after submitting a PR/MR to a CI system and getting unexpected results
 
-[gitlab_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/gitlab_ci.md
-[github_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/github_actions.md
+[gitlab_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/sync/gitlab_ci.md
+[github_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/sync/github_actions.md
+[precommit_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/sync/git_precommit.md
 
 ## License