bitwarden-workflow-linter 2.0.0__tar.gz

bitwarden_workflow_linter-2.0.0/.claude/CLAUDE.md

@@ -0,0 +1,142 @@
+# Bitwarden Workflow Linter - Claude 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-2.0.0/.claude/prompts/review-code.md

@@ -0,0 +1,25 @@
+Please review this pull request with a focus on:
+
+- Code quality and best practices
+- Potential bugs or issues
+- Security implications
+- Performance considerations
+
+Note: The PR branch is already checked out in the current working directory.
+
+Provide a comprehensive review including:
+
+- Summary of changes since last review
+- Critical issues found (be thorough)
+- Suggested improvements (be thorough)
+- Good practices observed (be concise - list only the most notable items without elaboration)
+- Action items for the author
+- Leverage collapsible <details> sections where appropriate for lengthy explanations or code snippets to enhance human readability
+
+When reviewing subsequent commits:
+
+- Track status of previously identified issues (fixed/unfixed/reopened)
+- Identify NEW problems introduced since last review
+- Note if fixes introduced new issues
+
+IMPORTANT: Be comprehensive about issues and improvements. For good practices, be brief - just note what was done well without explaining why or praising excessively.

bitwarden_workflow_linter-2.0.0/.editorconfig

@@ -0,0 +1,138 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Don't use tabs for indentation.
+[*]
+indent_size = 4
+indent_style = space
+tab_width = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+guidelines = 120
+
+# Code files
+[*.{cs,csx,vb,vbx}]
+indent_size = 4
+
+# Xml project files
+[*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}]
+indent_size = 2
+
+# Xml config files
+[*.{props,targets,ruleset,config,nuspec,resx,vsixmanifest,vsct}]
+indent_size = 2
+
+# JSON files
+[*.json]
+indent_size = 2
+
+# JS files
+[*.{js,ts,scss,html}]
+indent_size = 2
+
+[*.{ts}]
+quote_type = single
+
+[*.{scss,yml,csproj}]
+indent_size = 2
+
+[*.sln]
+indent_style = tab
+
+# Dotnet code style settings:
+[*.{cs,vb}]
+# Sort using and Import directives with System.* appearing first
+dotnet_sort_system_directives_first = true
+# Avoid "this." and "Me." if not necessary
+dotnet_style_qualification_for_field = false:suggestion
+dotnet_style_qualification_for_property = false:suggestion
+dotnet_style_qualification_for_method = false:suggestion
+dotnet_style_qualification_for_event = false:suggestion
+
+# Use language keywords instead of framework type names for type references
+dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
+dotnet_style_predefined_type_for_member_access = true:suggestion
+
+# Suggest more modern language features when available
+dotnet_style_object_initializer = true:suggestion
+dotnet_style_collection_initializer = true:suggestion
+dotnet_style_coalesce_expression = true:suggestion
+dotnet_style_null_propagation = true:suggestion
+dotnet_style_explicit_tuple_names = true:suggestion
+
+# Prefix private members with underscore
+dotnet_naming_rule.private_members_with_underscore.symbols = private_fields
+dotnet_naming_rule.private_members_with_underscore.style = prefix_underscore
+dotnet_naming_rule.private_members_with_underscore.severity = suggestion
+
+dotnet_naming_symbols.private_fields.applicable_kinds = field
+dotnet_naming_symbols.private_fields.applicable_accessibilities = private
+
+dotnet_naming_style.prefix_underscore.capitalization = camel_case
+dotnet_naming_style.prefix_underscore.required_prefix = _
+
+# Async methods should have "Async" suffix
+dotnet_naming_rule.async_methods_end_in_async.symbols = any_async_methods
+dotnet_naming_rule.async_methods_end_in_async.style = end_in_async
+dotnet_naming_rule.async_methods_end_in_async.severity = suggestion
+
+dotnet_naming_symbols.any_async_methods.applicable_kinds = method
+dotnet_naming_symbols.any_async_methods.applicable_accessibilities = *
+dotnet_naming_symbols.any_async_methods.required_modifiers = async
+
+dotnet_naming_style.end_in_async.required_prefix = 
+dotnet_naming_style.end_in_async.required_suffix = Async
+dotnet_naming_style.end_in_async.capitalization = pascal_case
+dotnet_naming_style.end_in_async.word_separator = 
+
+# Obsolete warnings, this should be removed or changed to warning once we address some of the obsolete items.
+dotnet_diagnostic.CS0618.severity = suggestion
+
+# Obsolete warnings, this should be removed or changed to warning once we address some of the obsolete items.
+dotnet_diagnostic.CS0612.severity = suggestion
+
+# Remove unnecessary using directives https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/ide0005
+dotnet_diagnostic.IDE0005.severity = warning
+
+# CSharp code style settings:
+[*.cs]
+# Prefer "var" everywhere
+csharp_style_var_for_built_in_types = true:suggestion
+csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_style_var_elsewhere = true:suggestion
+
+# Prefer method-like constructs to have a expression-body
+csharp_style_expression_bodied_methods = true:none
+csharp_style_expression_bodied_constructors = true:none
+csharp_style_expression_bodied_operators = true:none
+
+# Prefer property-like constructs to have an expression-body
+csharp_style_expression_bodied_properties = true:none
+csharp_style_expression_bodied_indexers = true:none
+csharp_style_expression_bodied_accessors = true:none
+
+# Suggest more modern language features when available
+csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
+csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
+csharp_style_inlined_variable_declaration = true:suggestion
+csharp_style_throw_expression = true:suggestion
+csharp_style_conditional_delegate_call = true:suggestion
+
+# Newline settings
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+csharp_new_line_before_members_in_object_initializers = true
+csharp_new_line_before_members_in_anonymous_types = true
+
+# Namespace settings
+csharp_style_namespace_declarations = file_scoped:warning
+
+# Switch expression
+dotnet_diagnostic.CS8509.severity = error # missing switch case for named enum value
+dotnet_diagnostic.CS8524.severity = none # missing switch case for unnamed enum value

bitwarden_workflow_linter-2.0.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

bitwarden_workflow_linter-2.0.0/.github/CODEOWNERS

@@ -0,0 +1,20 @@
+# Please sort into logical groups with comment headers. Sort groups in order of specificity.
+# For example, default owners should always be the first group.
+# Sort lines alphabetically within these groups to avoid accidentally adding duplicates.
+#
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default file owners
+* @bitwarden/dept-bre
+
+# AppSec owns default_actions, actionlint_version, and zizmor config files
+src/bitwarden_workflow_linter/default_actions.json @bitwarden/team-appsec
+src/bitwarden_workflow_linter/actionlint_version.yaml @bitwarden/team-appsec
+zizmor.yml @bitwarden/team-appsec
+
+
+# Docker-related files
+**/Dockerfile @bitwarden/team-appsec @bitwarden/dept-bre
+**/*.dockerignore @bitwarden/team-appsec @bitwarden/dept-bre
+**/entrypoint.sh @bitwarden/team-appsec @bitwarden/dept-bre
+**/docker-compose.yml @bitwarden/team-appsec @bitwarden/dept-bre

bitwarden_workflow_linter-2.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Feature Requests
+    url: https://community.bitwarden.com/c/feature-requests/
+    about: Request new features using the Community Forums. Please search existing feature requests before making a new one.
+  - name: Bitwarden Community Forums
+    url: https://community.bitwarden.com
+    about: Please visit the community forums for general community discussion, support and the development roadmap.
+  - name: Customer Support
+    url: https://bitwarden.com/contact/
+    about: Please contact our customer support for account issues and general customer support.
+  - name: Security Issues
+    url: https://hackerone.com/bitwarden
+    about: We use HackerOne to manage security disclosures.

bitwarden_workflow_linter-2.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## 🎟️ Tracking
+
+<!-- Paste the link to the Jira or GitHub issue or otherwise describe / point to where this change is coming from. -->
+
+## 📔 Objective
+
+<!-- Describe what the purpose of this PR is, for example what bug you're fixing or new feature you're adding. -->
+
+## ⏰ Reminders before review
+
+- Contributor guidelines followed
+- All formatters and local linters executed and passed
+- Written new unit and / or integration tests where applicable
+- Protected functional changes with optionality (feature flags)
+- Used internationalization (i18n) for all UI strings
+- CI builds passed
+- Communicated to DevOps any deployment requirements
+- Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team
+
+## 🦮 Reviewer guidelines
+
+<!-- Suggested interactions but feel free to use (or not) as you desire! -->
+
+- 👍 (`:+1:`) or similar for great changes
+- 📝 (`:memo:`) or ℹ️ (`:information_source:`) for notes or general info
+- ❓ (`:question:`) for questions
+- 🤔 (`:thinking:`) or 💭 (`:thought_balloon:`) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
+- 🎨 (`:art:`) for suggestions / improvements
+- ❌ (`:x:`) or ⚠️ (`:warning:`) for more significant problems or concerns needing attention
+- 🌱 (`:seedling:`) or ♻️ (`:recycle:`) for future improvements or indications of technical debt
+- ⛏ (`:pick:`) for minor or nitpick changes

bitwarden_workflow_linter-2.0.0/.github/actionlint.yml

@@ -0,0 +1,20 @@
+# Configuration related to self-hosted runner.
+self-hosted-runner:
+  # Labels of self-hosted runner in array of strings.
+  labels:
+    - terraform-provider-bitwarden-sm-linux
+    - qa-ubuntu-24.04-TSD-1534
+    - macos-26
+    - macos-26-xlarge
+
+# Path-specific configurations.
+paths:
+  # Glob pattern relative to the repository root for matching files. The path separator is always '/'.
+  # This example configures any YAML file under the '.github/workflows/' directory.
+  .github/workflows/**/*.{yml,yaml}:
+    # List of regular expressions to filter errors by the error messages.
+    ignore:
+      # Ignore the specific error from shellcheck
+      - 'shellcheck reported issue in this script: .+'
+      - 'property "(secret_no_env_one|secret_one)" is not defined in object type.*' # Needed for sm-action tests with dynamic output
+      - 'invalid runner name "node24" at runs.using in ".*" action defined at ".*". valid runners are "composite", "docker", and "node20"' # Temporary workaround until actionlint support for node24 is released

bitwarden_workflow_linter-2.0.0/.github/renovate.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>bitwarden/renovate-config"],
+  "enabledManagers": ["github-actions", "npm", "pipenv"],
+  "labels": ["version:patch"],
+  "packageRules": [
+    {
+      "groupName": "gh minor",
+      "matchManagers": ["github-actions"],
+      "matchUpdateTypes": ["minor", "patch"]
+    },
+    {
+      "groupName": "npm minor",
+      "matchManagers": ["npm"],
+      "matchUpdateTypes": ["minor", "patch"]
+    },
+    {
+      "groupName": "pipenv minor",
+      "matchManagers": ["pipenv"],
+      "matchUpdateTypes": ["minor", "patch"]
+    }
+  ],
+  "customManagers": [
+    {
+      "customType": "regex",
+      "fileMatch": ["^actionlint_version\\.yaml$"],
+      "matchStrings": [
+        "\"actionlint_version\":\\s*\"(?<currentValue>[^\"]+)\""
+      ],
+      "depNameTemplate": "rhysd/actionlint",
+      "datasourceTemplate": "github-releases",
+      "versioningTemplate": "semver"
+    }
+  ]
+}

bitwarden_workflow_linter-2.0.0/.github/workflows/_version_type.yml

@@ -0,0 +1,62 @@
+name: _version_type
+run-name: Get version type
+
+on:
+  workflow_call:
+    outputs:
+      version_bump_type:
+        description: "version to be built"
+        value: ${{ jobs.version.outputs.bump_type }}
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+jobs:
+  version:
+    name: Calculate Version
+    runs-on: ubuntu-22.04
+    outputs:
+      bump_type: ${{ steps.bump-type.outputs.type }}
+    steps:
+      - name: Get PR ID
+        id: pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          commit_message=$(
+            curl -s -L \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer $GH_TOKEN" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              https://api.github.com/repos/${{ github.repository }}/commits/${{ github.sha }} | \
+            jq -r ".commit.message"
+          )
+          ID=$(echo "$commit_message" | head -1 | grep -o "(#.*)" | grep -o "[0-9]*")
+          echo "id=$ID" >> $GITHUB_OUTPUT
+
+      - name: Get version bump type
+        id: bump-type
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ steps.pr.outputs.id }}
+        run: |
+          version_tag=$(
+            curl -s -L \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer $GH_TOKEN" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              https://api.github.com/repos/${{ github.repository }}/issues/$PR_NUMBER/labels | \
+            jq -r ".[].name" | grep "version"
+          )
+
+          # Single Version label Enforcement (should go in CI...)
+          if [[ $(echo $version_tag | wc -w) -gt 1 ]]; then
+              echo "[!] multiple version labels found!"
+              exit 1
+          fi
+
+          version_type=$(echo $version_tag | cut -d ":" -f 2)
+          echo "Version Bump Type: $version_type"
+          echo "type=$version_type" >> $GITHUB_OUTPUT