bitwarden_workflow_linter 1.3.3__tar.gz → 1.3.5__tar.gz

bitwarden_workflow_linter-1.3.5/.github/copilot-instructions.md

@@ -0,0 +1,142 @@
+# Bitwarden Workflow Linter - Copilot Instructions
+
+## Repository Overview
+
+**Bitwarden Workflow Linter** is an extensible Python CLI tool that enforces opinionated organization-specific GitHub Action standards.
+
+**CRITICAL UNDERSTANDING**: This tool generates and publishes **rules that are consumed across ALL Bitwarden repositories**. Changes to rules affect the entire Bitwarden organization's CI/CD pipelines, not just this repository. Rules are distributed via PyPI and consumed by repositories through the [composite Action](https://github.com/bitwarden/gh-actions/tree/main/lint-workflow).
+
+### High-Level Details
+
+-   **Type**: Python CLI application and library (~86 Python files)
+-   **Language**: Python 3.13.5 (minimum 3.11 supported)
+-   **Package Manager**: pipenv for dependencies, hatch for building/publishing
+-   **Distribution**: Published to PyPI as `bitwarden_workflow_linter`
+-   **CLI Command**: `bwwl`
+-   **Organizational Impact**: Rules affect CI/CD across entire Bitwarden codebase
+
+## Build & Development Setup
+
+### Essential Commands (Always run in this order)
+
+```bash
+# Setup (REQUIRED before any development work)
+pipenv install --dev
+pipenv shell
+pip install -e .
+
+# Testing (ALWAYS run before submitting changes)
+pytest tests --cov=src
+
+# Code quality (REQUIRED before merging to main)
+black .
+pylint --rcfile pylintrc src/ tests/
+
+# Type checking (Linux only)
+pytype src
+```
+
+### Task Runner Shortcuts
+
+-   `task test:cov` - Run tests with coverage
+-   `task fmt` - Format code with black
+-   `task lint` - Run pylint
+
+## Key Project Structure
+
+**Rules Location**: `src/bitwarden_workflow_linter/rules/` - All linting rules
+**Rule Base Class**: `src/bitwarden_workflow_linter/rule.py` - Extend this for new rules
+**CLI Entry**: `src/bitwarden_workflow_linter/cli.py:main()`
+**Configuration**:
+
+-   `settings.yaml` (local overrides)
+-   `src/bitwarden_workflow_linter/default_settings.yaml` (defaults)
+
+## Rule Development - Organization-Wide Impact
+
+**CRITICAL**: Rules developed here are distributed to and enforced across ALL Bitwarden repositories. Every rule change has organization-wide impact.
+
+### Rule Distribution Flow
+
+1. Rules developed/tested in this repository
+2. Published to PyPI as `bitwarden_workflow_linter`
+3. Consumed by all Bitwarden repositories via gh-actions/lint-workflow
+4. Enforced in CI/CD pipelines organization-wide
+5. Rule failures can block deployments across hundreds of repositories
+
+### Rule Rollout Process (MANDATORY)
+
+**Before making ANY rule changes, read `RULE_ROLLOUT.md`** - documents the careful process for organization-wide deployment.
+
+**Key principles:**
+
+-   **Gradual Rollout**: New rules start as `warning`, then upgrade to `error`
+-   **Impact Assessment**: Test against representative workflows before activation
+-   **Communication**: Coordinate with teams before deploying breaking changes
+
+### Adding New Rules
+
+1. **CRITICAL**: Rules must be implemented, tested, and merged to main BEFORE activation
+2. **CRITICAL**: Follow `RULE_ROLLOUT.md` process to avoid breaking organization CI
+3. Extend `Rule` base class in `src/bitwarden_workflow_linter/rule.py`
+4. Place in `src/bitwarden_workflow_linter/rules/`
+5. Must define: `message`, `on_fail`, `compatibility`, `settings`, and `fn()` method
+6. Add comprehensive tests with 100% coverage
+7. Start with `warning` level, upgrade to `error` after validation period
+8. After release, activate by adding to `settings.yaml` and `default_settings.yaml`
+
+### Rule Impact Levels
+
+-   **ERROR Level**: Block CI/CD across all Bitwarden repositories - handle with extreme care
+-   **WARNING Level**: Generate notifications but don't block - safer for initial rollout
+
+## Security Considerations
+
+### Critical Security Rules (Organization-Wide)
+
+-   **Action Pinning**: `step_pinned.py` enforces SHA pinning (not tags) at ERROR level across all repos
+    -   Example: `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2`
+-   **Approved Actions**: `step_approved.py` enforces use of pre-approved actions only
+-   **Permissions**: `permissions_exist.py` enforces explicit permissions in workflows
+-   **PR Target Protection**: `check_pr_target.py` prevents dangerous `pull_request_target` usage
+
+**Security rule changes affect organization-wide security posture - always coordinate with security team.**
+
+## Critical Issues & Solutions
+
+### Rule Activation Order
+
+-   **ERROR**: Activating rules before release causes import errors across all Bitwarden repositories
+-   **SOLUTION**: Always merge rule implementation first, then activate after PyPI release
+
+### Organization-Wide Impact
+
+-   **ERROR**: Deploying ERROR-level rules without testing breaks CI across hundreds of repositories
+-   **SOLUTION**: Start with WARNING level, test extensively, coordinate rollout via `RULE_ROLLOUT.md`
+
+### Testing Best Practices
+
+-   Tests change directories to avoid repo-specific paths
+-   Use `default_settings.yaml` instead of repo `settings.yaml` in tests
+-   Run with `--strict` flag to catch warnings as errors
+-   Test rules against diverse workflow patterns from different Bitwarden repositories
+
+## Agent Instructions
+
+**Trust these instructions first** - only search for additional information if incomplete or incorrect.
+
+**CRITICAL AWARENESS**: This repository's rules are consumed across ALL Bitwarden repositories. Every change has organization-wide impact.
+
+**Required sequence for changes:**
+
+1. **Read `RULE_ROLLOUT.md` if working with rules** - understand organization-wide impact
+2. `pipenv shell && pip install -e .`
+3. `pytest tests --cov=src`
+4. `black . && pylint --rcfile pylintrc src/ tests/`
+5. Test CLI: `bwwl lint --files tests/fixtures`
+
+**For rule development:**
+
+-   Rules affect hundreds of other Bitwarden repositories
+-   Start with WARNING level, coordinate rollout, upgrade to ERROR only after validation
+-   **Never deploy ERROR-level rules without extensive testing and coordination**

{bitwarden_workflow_linter-1.3.3 → bitwarden_workflow_linter-1.3.5}/.github/workflows/bwwl_operations.yml

@@ -64,7 +64,7 @@ jobs:
         uses: bitwarden/gh-actions/azure-logout@main
 
       - name: Checkout Branch
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Import GPG key
         uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6.3.0
@@ -82,7 +82,7 @@ jobs:
       - name: Set up Python 3.12
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install bwwl binary
         run: python -m pip install --upgrade bitwarden_workflow_linter

{bitwarden_workflow_linter-1.3.3 → bitwarden_workflow_linter-1.3.5}/.github/workflows/cd.yml

@@ -64,7 +64,7 @@ jobs:
           private-key: ${{ steps.get-kv-secrets.outputs.BW-GHAPP-KEY }}
 
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
           token: ${{ steps.app-token.outputs.token }}
@@ -125,10 +125,10 @@ jobs:
       contents: write
     steps:
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Create GitHub release
-        uses: ncipollo/release-action@440c8c1cb0ed28b9f43e4d1d670870f059653174 # v1.16.0
+        uses: ncipollo/release-action@bcfe5470707e8832e12347755757cec0eb3c22af # v1.18.0
         with:
           commit: ${{ github.sha }}
           tag: v${{ needs.version-bump.outputs.version }}
@@ -145,7 +145,7 @@ jobs:
       id-token: write
     steps:
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
           ref: ${{ needs.version-bump.outputs.commit_hash }}

{bitwarden_workflow_linter-1.3.3 → bitwarden_workflow_linter-1.3.5}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0

{bitwarden_workflow_linter-1.3.3 → bitwarden_workflow_linter-1.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitwarden_workflow_linter
-Version: 1.3.3
+Version: 1.3.5
 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

{bitwarden_workflow_linter-1.3.3 → bitwarden_workflow_linter-1.3.5}/src/bitwarden_workflow_linter/__about__.py

@@ -1,3 +1,3 @@
 """Metadata for Workflow Linter."""
 
-__version__ = "1.3.3"
+__version__ = "1.3.5"

{bitwarden_workflow_linter-1.3.3 → bitwarden_workflow_linter-1.3.5}/src/bitwarden_workflow_linter/default_actions.json

@@ -359,6 +359,11 @@
     "sha": "6fb02220983dee41ce7ae257b6f4d8f9bf5ed4ce",
     "version": "v2"
   },
+  "mlugg/setup-zig": {
+    "name": "mlugg/setup-zig",
+    "sha": "8d6198c65fb0feaa111df26e6b467fea8345e46f",
+    "version": "v2.0.5"
+  },
   "ncipollo/release-action": {
     "name": "ncipollo/release-action",
     "sha": "2c591bcc8ecdcd2db72b97d6147f871fcd833ba5",