bitwarden_workflow_linter 0.12.2__tar.gz → 0.12.4__tar.gz

{bitwarden_workflow_linter-0.12.2 → bitwarden_workflow_linter-0.12.4}/.github/workflows/bwwl_operations.yml

@@ -54,10 +54,10 @@ jobs:
           git config --local user.email "106330231+bitwarden-devops-bot@users.noreply.github.com"
           git config --local user.name "bitwarden-devops-bot"
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install bwwl binary
         run: python -m pip install --upgrade bitwarden_workflow_linter

bitwarden_workflow_linter-0.12.4/.python-version

@@ -0,0 +1 @@
+3.12

bitwarden_workflow_linter-0.12.4/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: bitwarden_workflow_linter
+Version: 0.12.4
+Summary: Custom GitHub Action Workflow Linter
+Project-URL: Homepage, https://github.com/bitwarden/workflow-linter
+Project-URL: Issues, https://github.com/bitwarden/workflow-linter/issues
+License-File: LICENSE.txt
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: annotated-types==0.7.0
+Requires-Dist: dataclasses-json==0.6.6
+Requires-Dist: marshmallow==3.21.2
+Requires-Dist: mypy-extensions==1.0.0
+Requires-Dist: packaging==24.0
+Requires-Dist: pydantic-core==2.18.3
+Requires-Dist: pydantic==2.7.2
+Requires-Dist: pyyaml==6.0.1
+Requires-Dist: ruamel-yaml-clib==0.2.8
+Requires-Dist: ruamel-yaml==0.18.6
+Requires-Dist: typing-extensions==4.12.0
+Requires-Dist: typing-inspect==0.9.0
+Requires-Dist: urllib3==2.2.1
+Description-Content-Type: text/markdown
+
+# Bitwarden Workflow Linter
+
+Bitwarden's Workflow Linter is an extensible linter to apply opinionated organization-specific GitHub Action standards. It was designed to be used alongside [yamllint](https://github.com/adrienverge/yamllint) to enforce specific YAML standards.
+
+To see an example of Workflow Linter in practice in GitHub Action, see the [composite Action](https://github.com/bitwarden/gh-actions/tree/main/lint-workflow).
+
+## Prerequisites
+
+- Python 3.12
+- pipenv
+- Windows systems: Chocolatey package manager
+- Mac OS systems: Homebrew package manager
+- pipx
+
+## Setup
+
+1. **Create the virtual environment:**
+   ```bash
+   python3.12 -m venv /Users/$USER/bitwarden_workflow_linter_venv
+   ```
+
+2. **Activate the virtual environment:**
+   ```bash
+   source /Users/$USER/bitwarden_workflow_linter_venv/bin/activate
+   ```
+
+## Installation
+
+### From PyPI
+This is the recommended method for most users. Installing from PyPI ensures you get the latest stable release and is the easiest way to install and update the package.
+
+
+1. **Install Bitwarden Workflow Linter:**
+   ```bash
+   pip install --upgrade bitwarden_workflow_linter
+   ```
+
+2. **Deactivate the virtual environment (optional):**
+   ```bash
+   deactivate
+   ```
+#### Using pipx
+
+Alternatively, you can install `bwwl` globally using `pipx` to keep it isolated:
+
+1. **Install Bitwarden Workflow Linter:**
+   ```bash
+   pipx install bitwarden_workflow_linter --python python3.12
+   ```
+
+This method is ideal for running `bwwl` as a standalone CLI tool without managing a virtual environment manually.
+
+### From GitHub Release
+Use this method if you need a specific version of the package that is not yet available on PyPI, or if you want to access pre-release versions.
+
+1. **Download the release tarball or zip file from GitHub:**
+   ```bash
+   wget https://github.com/bitwarden/workflow-linter/archive/refs/tags/vX.Y.Z.tar.gz
+   tar -xzf vX.Y.Z.tar.gz
+   cd workflow-linter-X.Y.Z
+   ```
+
+2. **Install the package:**
+   ```bash
+   pip install .
+   ```
+
+3. **Deactivate the virtual environment (optional):**
+   ```bash
+   deactivate
+   ```
+
+### Locally
+This method is useful for developers who want to contribute to the project or need to make local modifications to the source code. *Make sure to follow the virtual environment prerequisite setup*
+1. **Clone the repository:**
+   ```bash
+   git clone git@github.com:bitwarden/workflow-linter.git
+   cd workflow-linter
+   ```
+
+2. **Install the package:**
+   ```bash
+   pip install -e .
+   ```
+
+3. **Deactivate the virtual environment (optional):**
+   ```bash
+   deactivate
+   ```
+
+## Usage
+
+### Setup settings.yaml
+
+If a non-default configuration is desired (different than `src/bitwarden_workflow_linter/default_settings.yaml`), copy the below and create a `settings.yaml` in the directory that `bwwl` will be running from.
+
+```yaml
+enabled_rules:
+    - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+      level: error
+    - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+      level: error
+    - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+      level: error
+    - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
+      level: warning
+    - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+      level: warning
+
+approved_actions_path: default_actions.json
+```
+
+### Command Line Usage
+
+```bash
+usage: bwwl [-h] [-v] {lint,actions} ...
+
+positional arguments:
+  {lint,actions}
+    lint          Verify that a GitHub Action Workflow follows all of the Rules.
+    actions       Add or Update Actions in the pre-approved list.
+
+options:
+  -h, --help      show this help message and exit
+  -v, --verbose
+```
+## Pre-commit Hook Setup
+
+### Navigate to the `.git/hooks` directory in the repository you wish to lint:
+
+```bash
+cd .git/hooks
+```
+
+### Create the `pre-commit` file (if it does not already exist):
+
+```bash
+touch pre-commit
+```
+
+### Make the script executable:
+
+```bash
+chmod +x pre-commit
+```
+
+### Edit the `pre-commit` script:
+
+Open the `pre-commit` file with your favorite text editor and add the following content, replacing `/Users/$USER/bitwarden_workflow_linter_venv/bin/activate` with the actual path to your virtual environment:
+
+```bash
+#!/bin/bash
+set -e
+# Activate the virtual environment
+source "/Users/$USER/bitwarden_workflow_linter_venv/bin/activate"
+# Get the repository root directory
+repo_root=$(git rev-parse --show-toplevel)
+# Run your Python script
+bwwl lint -f "$repo_root/.github/workflows"
+# Deactivate the virtual environment (optional)
+deactivate
+```
+
+### Test the Hook:
+
+Try committing a change to the repository. The pre-commit hook should run the workflow linter.
+
+## Development
+
+### Setup
+Refer to the [Locally](#locally) instructions above to clone the repository and install the package.
+
+### Testing
+
+All built-in `src/bitwarden_workflow_linter/rules` should have 100% code coverage and we should shoot for an overall coverage of 80%+. We are lax on the [imperative shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) (code interacting with other systems; ie. disk, network, etc), but we strive to maintain a high coverage over the functional core (objects and models).
+
+```bash
+pipenv shell
+pytest tests --cov=src
+```
+
+### Code Reformatting
+
+We adhere to PEP8 and use `black` to maintain this adherence. `black` should be run on any change being merged to `main`.
+
+```bash
+pipenv shell
+black .
+```
+
+### Linting
+
+We loosely use [Google's Python style guide](https://google.github.io/styleguide/pyguide.html), but yield to `black` when there is a conflict.
+
+```bash
+pipenv shell
+pylint --rcfile pylintrc src/ tests/
+```
+
+### Add a new Rule
+
+A new Rule is created by extending the Rule base class and overriding the `fn(obj: Union[Workflow, Job, Step])` method. Available attributes of `Workflows`, `Jobs` and `Steps` can be found in their definitions under `src/models`.
+
+For a simple example, we'll take a look at enforcing the existence of the `name` key in a Job. This is already done by default with the `src.rules.name_exists.RuleNameExists`, but provides a simple enough example to walk through.
+
+```python
+from typing import Union, Tuple
+
+from ..rule import Rule
+from ..models.job import Job
+from ..models.workflow import Workflow
+from ..models.step import Step
+from ..utils import LintLevels, Settings
+
+
+class RuleJobNameExists(Rule):
+    def __init__(self, settings: Settings = None, lint_level: Optional[LintLevels] = LintLevels.ERROR) -> None:
+        self.message = "name must exist"
+        self.on_fail: LintLevels = lint_level
+        self.compatibility: List[Union[Workflow, Job, Step]] = [Job]
+        self.settings: Settings = settings
+
+    def fn(self, obj: Job) -> Tuple[bool, str]:
+        """<doc block goes here> """
+        if obj.name is not None:
+            return True, ""
+        return False, self.message
+```
+
+By default, a new Rule needs five things:
+
+- `self.message`: The message to return to the user on a lint failure
+- `self.on_fail`: The level of failure on a lint failure (NONE, WARNING, ERROR). NONE and WARNING will exit with a code of 0 (unless using `strict` mode for WARNING). ERROR will exit with a non-zero exit code
+- `self.compatibility`: The list of objects this rule is compatible with. This is used to create separate instances of the Rule for each object in the Rules collection.
+- `self.settings`: In general, this should default to what is shown here, but allows for overrides
+- `self.fn`: The function doing the actual work to check the object and enforce the standard.
+
+`fn` can be as simple or as complex as it needs to be to run a check on a _single_ object. This linter currently does not support Rules that check against multiple objects at a time OR file level formatting (one empty between each step or two empty lines between each job).
+
+_IMPORTANT: A rule must be implemented and tested then merged into `main` before it can be activated._ This is because the released version of `bwwl` will use the current `settings.yaml` file, but it will not have the new rule functionality yet and cause an error in the workflow linting of this repository.
+
+To activate a rule after implementing and releasing it, add it to `settings.yaml` in the project's base folder and `src/bitwarden_workflow_linter/default_settings.yaml` to make the rule default.
+
+Before creating a new rule please read the [Workflow linter rule rollout process](./RULE_ROLLOUT.md) document in which you'll find the process for rolling out new workflow linter rules.

{bitwarden_workflow_linter-0.12.2 → bitwarden_workflow_linter-0.12.4}/Pipfile

@@ -21,4 +21,4 @@ hatchling = "*"
 build = "*"
 
 [requires]
-python_version = "3.11"
+python_version = "3.12"

{bitwarden_workflow_linter-0.12.2 → bitwarden_workflow_linter-0.12.4}/Pipfile.lock

@@ -5,7 +5,7 @@
         },
         "pipfile-spec": 6,
         "requires": {
-            "python_version": "3.11"
+            "python_version": "3.12"
         },
         "sources": [
             {

bitwarden_workflow_linter-0.12.4/README.md

@@ -0,0 +1,248 @@
+# Bitwarden Workflow Linter
+
+Bitwarden's Workflow Linter is an extensible linter to apply opinionated organization-specific GitHub Action standards. It was designed to be used alongside [yamllint](https://github.com/adrienverge/yamllint) to enforce specific YAML standards.
+
+To see an example of Workflow Linter in practice in GitHub Action, see the [composite Action](https://github.com/bitwarden/gh-actions/tree/main/lint-workflow).
+
+## Prerequisites
+
+- Python 3.12
+- pipenv
+- Windows systems: Chocolatey package manager
+- Mac OS systems: Homebrew package manager
+- pipx
+
+## Setup
+
+1. **Create the virtual environment:**
+   ```bash
+   python3.12 -m venv /Users/$USER/bitwarden_workflow_linter_venv
+   ```
+
+2. **Activate the virtual environment:**
+   ```bash
+   source /Users/$USER/bitwarden_workflow_linter_venv/bin/activate
+   ```
+
+## Installation
+
+### From PyPI
+This is the recommended method for most users. Installing from PyPI ensures you get the latest stable release and is the easiest way to install and update the package.
+
+
+1. **Install Bitwarden Workflow Linter:**
+   ```bash
+   pip install --upgrade bitwarden_workflow_linter
+   ```
+
+2. **Deactivate the virtual environment (optional):**
+   ```bash
+   deactivate
+   ```
+#### Using pipx
+
+Alternatively, you can install `bwwl` globally using `pipx` to keep it isolated:
+
+1. **Install Bitwarden Workflow Linter:**
+   ```bash
+   pipx install bitwarden_workflow_linter --python python3.12
+   ```
+
+This method is ideal for running `bwwl` as a standalone CLI tool without managing a virtual environment manually.
+
+### From GitHub Release
+Use this method if you need a specific version of the package that is not yet available on PyPI, or if you want to access pre-release versions.
+
+1. **Download the release tarball or zip file from GitHub:**
+   ```bash
+   wget https://github.com/bitwarden/workflow-linter/archive/refs/tags/vX.Y.Z.tar.gz
+   tar -xzf vX.Y.Z.tar.gz
+   cd workflow-linter-X.Y.Z
+   ```
+
+2. **Install the package:**
+   ```bash
+   pip install .
+   ```
+
+3. **Deactivate the virtual environment (optional):**
+   ```bash
+   deactivate
+   ```
+
+### Locally
+This method is useful for developers who want to contribute to the project or need to make local modifications to the source code. *Make sure to follow the virtual environment prerequisite setup*
+1. **Clone the repository:**
+   ```bash
+   git clone git@github.com:bitwarden/workflow-linter.git
+   cd workflow-linter
+   ```
+
+2. **Install the package:**
+   ```bash
+   pip install -e .
+   ```
+
+3. **Deactivate the virtual environment (optional):**
+   ```bash
+   deactivate
+   ```
+
+## Usage
+
+### Setup settings.yaml
+
+If a non-default configuration is desired (different than `src/bitwarden_workflow_linter/default_settings.yaml`), copy the below and create a `settings.yaml` in the directory that `bwwl` will be running from.
+
+```yaml
+enabled_rules:
+    - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+      level: error
+    - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+      level: error
+    - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+      level: error
+    - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
+      level: warning
+    - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+      level: warning
+
+approved_actions_path: default_actions.json
+```
+
+### Command Line Usage
+
+```bash
+usage: bwwl [-h] [-v] {lint,actions} ...
+
+positional arguments:
+  {lint,actions}
+    lint          Verify that a GitHub Action Workflow follows all of the Rules.
+    actions       Add or Update Actions in the pre-approved list.
+
+options:
+  -h, --help      show this help message and exit
+  -v, --verbose
+```
+## Pre-commit Hook Setup
+
+### Navigate to the `.git/hooks` directory in the repository you wish to lint:
+
+```bash
+cd .git/hooks
+```
+
+### Create the `pre-commit` file (if it does not already exist):
+
+```bash
+touch pre-commit
+```
+
+### Make the script executable:
+
+```bash
+chmod +x pre-commit
+```
+
+### Edit the `pre-commit` script:
+
+Open the `pre-commit` file with your favorite text editor and add the following content, replacing `/Users/$USER/bitwarden_workflow_linter_venv/bin/activate` with the actual path to your virtual environment:
+
+```bash
+#!/bin/bash
+set -e
+# Activate the virtual environment
+source "/Users/$USER/bitwarden_workflow_linter_venv/bin/activate"
+# Get the repository root directory
+repo_root=$(git rev-parse --show-toplevel)
+# Run your Python script
+bwwl lint -f "$repo_root/.github/workflows"
+# Deactivate the virtual environment (optional)
+deactivate
+```
+
+### Test the Hook:
+
+Try committing a change to the repository. The pre-commit hook should run the workflow linter.
+
+## Development
+
+### Setup
+Refer to the [Locally](#locally) instructions above to clone the repository and install the package.
+
+### Testing
+
+All built-in `src/bitwarden_workflow_linter/rules` should have 100% code coverage and we should shoot for an overall coverage of 80%+. We are lax on the [imperative shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) (code interacting with other systems; ie. disk, network, etc), but we strive to maintain a high coverage over the functional core (objects and models).
+
+```bash
+pipenv shell
+pytest tests --cov=src
+```
+
+### Code Reformatting
+
+We adhere to PEP8 and use `black` to maintain this adherence. `black` should be run on any change being merged to `main`.
+
+```bash
+pipenv shell
+black .
+```
+
+### Linting
+
+We loosely use [Google's Python style guide](https://google.github.io/styleguide/pyguide.html), but yield to `black` when there is a conflict.
+
+```bash
+pipenv shell
+pylint --rcfile pylintrc src/ tests/
+```
+
+### Add a new Rule
+
+A new Rule is created by extending the Rule base class and overriding the `fn(obj: Union[Workflow, Job, Step])` method. Available attributes of `Workflows`, `Jobs` and `Steps` can be found in their definitions under `src/models`.
+
+For a simple example, we'll take a look at enforcing the existence of the `name` key in a Job. This is already done by default with the `src.rules.name_exists.RuleNameExists`, but provides a simple enough example to walk through.
+
+```python
+from typing import Union, Tuple
+
+from ..rule import Rule
+from ..models.job import Job
+from ..models.workflow import Workflow
+from ..models.step import Step
+from ..utils import LintLevels, Settings
+
+
+class RuleJobNameExists(Rule):
+    def __init__(self, settings: Settings = None, lint_level: Optional[LintLevels] = LintLevels.ERROR) -> None:
+        self.message = "name must exist"
+        self.on_fail: LintLevels = lint_level
+        self.compatibility: List[Union[Workflow, Job, Step]] = [Job]
+        self.settings: Settings = settings
+
+    def fn(self, obj: Job) -> Tuple[bool, str]:
+        """<doc block goes here> """
+        if obj.name is not None:
+            return True, ""
+        return False, self.message
+```
+
+By default, a new Rule needs five things:
+
+- `self.message`: The message to return to the user on a lint failure
+- `self.on_fail`: The level of failure on a lint failure (NONE, WARNING, ERROR). NONE and WARNING will exit with a code of 0 (unless using `strict` mode for WARNING). ERROR will exit with a non-zero exit code
+- `self.compatibility`: The list of objects this rule is compatible with. This is used to create separate instances of the Rule for each object in the Rules collection.
+- `self.settings`: In general, this should default to what is shown here, but allows for overrides
+- `self.fn`: The function doing the actual work to check the object and enforce the standard.
+
+`fn` can be as simple or as complex as it needs to be to run a check on a _single_ object. This linter currently does not support Rules that check against multiple objects at a time OR file level formatting (one empty between each step or two empty lines between each job).
+
+_IMPORTANT: A rule must be implemented and tested then merged into `main` before it can be activated._ This is because the released version of `bwwl` will use the current `settings.yaml` file, but it will not have the new rule functionality yet and cause an error in the workflow linting of this repository.
+
+To activate a rule after implementing and releasing it, add it to `settings.yaml` in the project's base folder and `src/bitwarden_workflow_linter/default_settings.yaml` to make the rule default.
+
+Before creating a new rule please read the [Workflow linter rule rollout process](./RULE_ROLLOUT.md) document in which you'll find the process for rolling out new workflow linter rules.

{bitwarden_workflow_linter-0.12.2 → bitwarden_workflow_linter-0.12.4}/src/bitwarden_workflow_linter/__about__.py

@@ -1,3 +1,3 @@
 """Metadata for Workflow Linter."""
 
-__version__ = "0.12.2"
+__version__ = "0.12.4"

{bitwarden_workflow_linter-0.12.2 → bitwarden_workflow_linter-0.12.4}/src/bitwarden_workflow_linter/default_actions.json

@@ -249,6 +249,11 @@
     "sha": "49b3bc8e6bdd4a60e6116a5414239cba5943d3cf",
     "version": "v3.2.0"
   },
+  "dorny/paths-filter": {
+    "name": "dorny/paths-filter",
+    "sha": "de90cc6fb38fc0963ad72b210f1f284cd68cea36",
+    "version": "v3.0.2"
+  },
   "dorny/test-reporter": {
     "name": "dorny/test-reporter",
     "sha": "31a54ee7ebcacc03a09ea97a7e5465a47b84aea5",
@@ -399,11 +404,21 @@
     "sha": "bfd4e558cda28cda6b5defafb9232d191be8c203",
     "version": "v4.2.1"
   },
+  "sravinet/toml-select": {
+    "name": "sravinet/toml-select",
+    "sha": "fe2e680f88a09851a0cd887dba0bbd19d3babe11",
+    "version": "v1.0.1"
+  },
   "stackrox/kube-linter-action": {
     "name": "stackrox/kube-linter-action",
     "sha": "5792edc6a03735d592b13c08201711327a935735",
     "version": "v1.0.5"
   },
+  "step-security/changed-files": {
+    "name": "step-security/changed-files",
+    "sha": "3dbe17c78367e7d60f00d78ae6781a35be47b4a1",
+    "version": "v45.0.1"
+  },
   "tyrrrz/action-http-request": {
     "name": "tyrrrz/action-http-request",
     "sha": "64c70c67f5ebc54d4c7ea09cbe3553322778afd5",

bitwarden_workflow_linter-0.12.2/.python-version

@@ -1 +0,0 @@
-3.11