[BRE-54] Add Warning When Output Vars Contain Hyphen (#10)

* add warning when output vars contain hyphen

* apply black formatter

* add method doc string

* update Settings type

Author: Eeebru

.gitignore

@@ -30,3 +30,8 @@ dist
 ## Dev Environments
 Session.vim
 flake.*
+
+
+# Python
+**/__pycache__/**
+*.pyc

README.md

@@ -40,6 +40,7 @@ enabled_rules:
     - bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
     - bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
     - bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+    - bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
 
 approved_actions_path: default_actions.json
 ```
@@ -151,6 +152,9 @@ By default, a new Rule needs five things:
 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)
 
+To activate a rule after implementing 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
+
 ### ToDo
 
 -   [ ] Add Rule to assert correct format for single line run

settings.yaml

@@ -4,5 +4,6 @@ enabled_rules:
   - bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
   - bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
   - bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+  - bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
 
 approved_actions_path: default_actions.json

src/bitwarden_workflow_linter/default_settings.yaml

@@ -4,5 +4,6 @@ enabled_rules:
   - bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
   - bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
   - bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+  - bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
 
 approved_actions_path: default_actions.json

src/bitwarden_workflow_linter/models/job.py

@@ -30,6 +30,7 @@ class Job:
     uses_with: Optional[CommentedMap] = field(
         metadata=config(field_name="with"), default=None
     )
+    outputs: Optional[CommentedMap] = None
 
     @classmethod
     def init(cls: Self, key: str, data: CommentedMap) -> Self:
@@ -39,6 +40,7 @@ def init(cls: Self, key: str, data: CommentedMap) -> Self:
             "name": data["name"] if "name" in data else None,
             "runs-on": data["runs-on"] if "runs-on" in data else None,
             "env": data["env"] if "env" in data else None,
+            "outputs": data["outputs"] if "outputs" in data else None,
         }
 
         new_job = cls.from_dict(init_data)

src/bitwarden_workflow_linter/rules/underscore_outputs.py

@@ -0,0 +1,111 @@
+import re
+
+from typing import Optional, Union, Tuple
+
+from ..models.job import Job
+from ..rule import Rule
+from ..models.workflow import Workflow
+from ..models.step import Step
+from ..utils import LintLevels, Settings
+
+
+class RuleUnderscoreOutputs(Rule):
+    """Rule to enforce all GitHub 'outputs' more than one words contain an underscore.
+
+    A simple standard to ensure uniformity in naming.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Constructor for RuleUnderscoreOutputs to override the Rule class.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.message = "outputs with more than one word must use an underscore"
+        self.on_fail = LintLevels.WARNING
+        self.compatibility = [Workflow, Job, Step]
+        self.settings = settings
+
+    def fn(self, obj: Union[Workflow, Job, Step]) -> Tuple[bool, str]:
+        """Enforces all outputs to have an underscore in the key name.
+
+        This Rule checks all outputs in a Workflow, Job, or Step to ensure that
+        the key name contains an underscore. This is to ensure that the naming
+        convention is consistent across all outputs in the workflow configuration
+
+        Example:
+        ---
+        on:
+          workflow_dispatch:
+            outputs:
+              registry:
+                value: 'Test Value'
+              some_registry:
+                value: 'Test Value'
+          workflow_call:
+            outputs:
+              registry:
+                value: 'Test Value'
+              some_registry:
+                value: 'Test Value'
+        jobs:
+          job-key:
+            runs-on: ubuntu-22.04
+            outputs:
+              test_key_job: ${{ steps.test_output_1.outputs.test_key }}
+            steps:
+              - name: Test output in one-line run step
+                id: test_output_1
+                run: echo "test_key_1=Test-Value1" >> $GITHUB_OUTPUT
+
+              - name: Test output in multi-line run step
+                id: test_output_2
+                run: |
+                  echo
+                  fake-command=Test-Value2
+                  echo "test_key_2=$REF" >> $GITHUB_OUTPUT
+                  echo "deployed_ref=$DEPLOYED_REF" >> $GITHUB_OUTPUT
+
+              - name: Test step with no run
+                id: test_output_3
+                uses: actions/checkout@v2
+                with:
+                  ref: ${{ github.ref }}
+                  fetch-depth: 0
+
+        In this example, in workflow level 'registry' and 'some_registry' are outputs
+        that satisfy the rule in both 'workflow_dispatch' and 'workflow_call' events.
+        In job level 'test_key_job' satisfies the rule.
+        In step level 'test_key_1', 'test_key_2', and 'deployed_ref' satisfy the rule.
+
+        See tests/rules/test_underscore_outputs.py for incorrect examples.
+        """
+
+        outputs = []
+
+        if isinstance(obj, Workflow):
+            if obj.on.get("workflow_dispatch"):
+                outputs.extend(obj.on["workflow_dispatch"]["outputs"].keys())
+
+            if obj.on.get("workflow_call"):
+                outputs.extend(obj.on["workflow_call"]["outputs"].keys())
+
+        if isinstance(obj, Job):
+            if obj.outputs:
+                outputs.extend(obj.outputs.keys())
+
+        if isinstance(obj, Step):
+            if obj.run:
+                outputs.extend(re.findall(
+                    r"\b([a-zA-Z0-9_-]+)\s*=\s*[^=]*>>\s*\$GITHUB_OUTPUT",
+                    obj.run))
+
+        for output_name in outputs:
+            if "-" in output_name:
+                return False, (
+                    f"Hyphen found in {obj.__class__.__name__} output: {output_name}"
+                )
+
+        return True, ""

tests/fixtures/test-outputs-incorrect.yml

@@ -0,0 +1,45 @@
+---
+name: Test Incorrect Workflow
+on:
+  workflow_dispatch:
+    outputs:
+      registry-1:
+        value: 'Test Value'
+      some_registry-1:
+        value: 'Test Value'
+  workflow-call:
+    outputs:
+      registry-2:
+        value: 'Test Value'
+  push: {}
+
+jobs:
+  job-key:
+    name: Test Incorrect Job
+    runs-on: ubuntu-22.04
+    outputs:
+      test-key-1: ${{ steps.test_output_1.outputs.test_key }}
+    steps:
+      - name: Test output in one-line run step
+        id: test_output_1
+        run: echo "test-key-1=Test-Value1" >> $GITHUB_OUTPUT
+
+      - name: Test output in multi-line run step
+        id: test_output_2
+        run: |
+          echo
+          fake-command
+          echo "test-key-2=$REF" >> $GITHUB_OUTPUT
+          echo "deployed-ref=$DEPLOYED_REF" >> $GITHUB_OUTPUT
+
+      - name: Test step with one-line run and no Output
+        id: test_output_3
+        run: echo "test-key-3"
+
+      - name: Test step with multi-line run and no Output
+        id: test_output_4
+        run: |
+          echo
+          fake-command=Test-Value4
+          echo "test-key-4"
+          echo "deployed-ref"