bitwarden_workflow_linter 0.0.3__py3-none-any.whl

bitwarden_workflow_linter-0.0.3.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.3
+Name: bitwarden_workflow_linter
+Version: 0.0.3
+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 tools like
+[action-lint](https://github.com/rhysd/actionlint) and
+[yamllint](https://github.com/adrienverge/yamllint) to check for correct Action syntax and 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).
+
+## Installation
+
+## From GitHub Release
+
+```
+Not yet implemented
+```
+
+### Locally
+
+```
+git clone git@github.com:bitwarden/workflow-linter.git
+cd workflow-linter
+
+pip install -e .
+```
+
+## 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:
+    - bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+    - bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+    - bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+    - bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+    - bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+
+approved_actions_path: default_actions.json
+```
+
+```
+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
+```
+
+## Development
+
+### Requirements
+
+-   Python 3.11
+-   pipenv
+
+### Setup
+
+```
+pipenv install --dev
+pipenv shell
+```
+
+### 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).
+
+```
+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`.
+
+```
+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
+
+```
+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 definitons 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) -> None:
+        self.message = "name must exist"
+        self.on_fail: LintLevels = LintLevels.ERROR
+        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)
+
+### ToDo
+
+-   [ ] Add Rule to assert correct format for single line run

bitwarden_workflow_linter-0.0.3.dist-info/RECORD

@@ -0,0 +1,26 @@
+bitwarden_workflow_linter/__about__.py,sha256=KbbxYy_rLR2HkiKmhQYMcL4RRAhh7MG3ylAz_mbGpQo,59
+bitwarden_workflow_linter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bitwarden_workflow_linter/actions.py,sha256=daob3be2Y22gfsAmGhTgBRCgGk18mlGduqc5Zn1Onz4,7897
+bitwarden_workflow_linter/cli.py,sha256=oM3Cjo2y5NrzN1BfqGRiOhOC6IzPDEnEh14v3bsiqak,1700
+bitwarden_workflow_linter/default_actions.json,sha256=BeFllnAu9v6cX6eeGeNoQf3rXs7ZOjAtjTNBQuAZ8-k,8087
+bitwarden_workflow_linter/default_settings.yaml,sha256=yRvAt06Hupv7mSrSGGdWKJruecvEO55CazIbxP34plg,428
+bitwarden_workflow_linter/lint.py,sha256=z83h7XOnULngPqTwlo5LKCK2ciUu4oalwixKVcFLWac,5461
+bitwarden_workflow_linter/load.py,sha256=FYbSKgjVCleqiYKR_dB92C3EcP89knNMkxVr2yZZO9o,4473
+bitwarden_workflow_linter/rule.py,sha256=Qb60JiUDAWN3ayrMGoSbbDCSFmw-ql8djzAkxISaob4,3250
+bitwarden_workflow_linter/utils.py,sha256=IN_jSZQXRwutgFQ6n7xtD1OrTpx9YS_cHLZKDOEUhfc,4696
+bitwarden_workflow_linter/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bitwarden_workflow_linter/models/job.py,sha256=YXzs5CIIM1WEtzAk918QfIioqLcdr4vCOr3fs0uVEu0,1929
+bitwarden_workflow_linter/models/step.py,sha256=1bKAtKZmHcO8O1e_HuoXxR1bwHDEXUssYo7EHOjY7QI,1711
+bitwarden_workflow_linter/models/workflow.py,sha256=MkqvIY4JX2eWFODNTodS_l4I8uUq08WCHy3C4kYcL0s,1395
+bitwarden_workflow_linter/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bitwarden_workflow_linter/rules/job_environment_prefix.py,sha256=QCYNj-sX5VB5v49OkBdmFGDkm1E2ebcfiAvlkDVNx7g,2415
+bitwarden_workflow_linter/rules/name_capitalized.py,sha256=3IXvE_vCZ097P7gtHbhQZlwi83Rt239iJfVjmgG26to,1752
+bitwarden_workflow_linter/rules/name_exists.py,sha256=MxcaNQz64JXeHRPiOip9BxJNgPdpKQa7Z51mDoNw2hU,1681
+bitwarden_workflow_linter/rules/pinned_job_runner.py,sha256=Dm6_sdPX0yFMji_y2LMFj4gWFaToEgauyBVpNRP2qiI,1606
+bitwarden_workflow_linter/rules/step_approved.py,sha256=UIi9_z9j75SpQUmo29MLDhjLklqd4h0D-UYqkdcaju0,3307
+bitwarden_workflow_linter/rules/step_pinned.py,sha256=JSdKW-2Z8_ozQ3aAU7oYYt2ym3GLEilMfXBVqj1QU_E,3286
+bitwarden_workflow_linter-0.0.3.dist-info/METADATA,sha256=5Wg-TjUZxbvnihnAX8HkbsEVEh_30-hJxnslx-pujTE,5912
+bitwarden_workflow_linter-0.0.3.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+bitwarden_workflow_linter-0.0.3.dist-info/entry_points.txt,sha256=SA_yF9CwL4VMUvdcmCd7k9rjsQNzfeOUBuDnMnaO8QQ,60
+bitwarden_workflow_linter-0.0.3.dist-info/licenses/LICENSE.txt,sha256=uY-7N9tbI7xc_c0WeTIGpacSCnsB91N05eCIg3bkaRw,35140
+bitwarden_workflow_linter-0.0.3.dist-info/RECORD,,

bitwarden_workflow_linter-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bitwarden_workflow_linter-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bwwl = bitwarden_workflow_linter.cli:main