chore: add tests, update docs and actions (#299)

* docs: update documentation

* feat: validate-inputs has it's own pyproject

* security: mask DOCKERHUB_PASSWORD

* chore: add tokens, checkout, recrete docs, integration tests

* fix: add `statuses: write` permission to pr-lint

_tests/integration/workflows/github-release-test.yml

@@ -0,0 +1,440 @@
+---
+name: Integration Test - GitHub Release
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'github-release/**'
+      - '_tests/integration/workflows/github-release-test.yml'
+
+jobs:
+  test-github-release-validation:
+    name: Test Input Validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test invalid version format
+        run: |
+          VERSION='not.a.version'
+          if [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Invalid version format should have failed"
+            exit 1
+          fi
+          echo "✓ Invalid version format correctly rejected"
+
+      - name: Test version with alphabetic characters
+        run: |
+          VERSION='abc.def.ghi'
+          if [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Alphabetic version should have failed"
+            exit 1
+          fi
+          echo "✓ Alphabetic version correctly rejected"
+
+      - name: Test valid version formats
+        run: |
+          for version in "1.2.3" "v1.2.3" "1.0.0-alpha" "2.0.0+build"; do
+            if ! [[ "$version" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+              echo "❌ ERROR: Valid version '$version' should have passed"
+              exit 1
+            fi
+            echo "✓ Valid version '$version' accepted"
+          done
+
+  test-github-release-version-formats:
+    name: Test Version Format Support
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test basic SemVer (dry run)
+        run: |
+          echo "Testing basic SemVer format: 1.2.3"
+          VERSION="1.2.3"
+          if ! [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Valid version rejected"
+            exit 1
+          fi
+          echo "✓ Basic SemVer format accepted"
+
+      - name: Test SemVer with v prefix
+        run: |
+          echo "Testing SemVer with v prefix: v1.2.3"
+          VERSION="v1.2.3"
+          if ! [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Valid version rejected"
+            exit 1
+          fi
+          echo "✓ SemVer with v prefix accepted"
+
+      - name: Test prerelease version
+        run: |
+          echo "Testing prerelease version: 1.0.0-alpha.1"
+          VERSION="1.0.0-alpha.1"
+          if ! [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Valid prerelease version rejected"
+            exit 1
+          fi
+          echo "✓ Prerelease version accepted"
+
+      - name: Test version with build metadata
+        run: |
+          echo "Testing version with build metadata: 1.0.0+build.123"
+          VERSION="1.0.0+build.123"
+          if ! [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Valid build metadata version rejected"
+            exit 1
+          fi
+          echo "✓ Version with build metadata accepted"
+
+      - name: Test complex version
+        run: |
+          echo "Testing complex version: v2.1.0-rc.1+build.456"
+          VERSION="v2.1.0-rc.1+build.456"
+          if ! [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Valid complex version rejected"
+            exit 1
+          fi
+          echo "✓ Complex version accepted"
+
+  test-github-release-tool-availability:
+    name: Test Tool Availability Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test gh CLI detection logic
+        run: |
+          # Test the logic for checking gh availability
+          # In actual action, this would fail if gh is not available
+          if command -v gh >/dev/null 2>&1; then
+            echo "✓ gh CLI is available in this environment"
+            gh --version
+          else
+            echo "⚠️  gh CLI not available in test environment (would fail in actual action)"
+            echo "✓ Tool detection logic works correctly"
+          fi
+
+      - name: Test jq detection logic
+        run: |
+          # Test the logic for checking jq availability
+          # In actual action, this would fail if jq is not available
+          if command -v jq >/dev/null 2>&1; then
+            echo "✓ jq is available in this environment"
+            jq --version
+          else
+            echo "⚠️  jq not available in test environment (would fail in actual action)"
+            echo "✓ Tool detection logic works correctly"
+          fi
+
+      - name: Test tool requirement validation
+        run: |
+          # Verify the action correctly checks for required tools
+          REQUIRED_TOOLS=("gh" "jq")
+          echo "Testing tool requirement checks..."
+
+          for tool in "${REQUIRED_TOOLS[@]}"; do
+            if command -v "$tool" >/dev/null 2>&1; then
+              echo "  ✓ $tool: available"
+            else
+              echo "  ⚠️  $tool: not available (action would fail at this check)"
+            fi
+          done
+
+          echo "✓ Tool requirement validation logic verified"
+
+      - name: Test gh authentication logic
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Test authentication detection logic
+          if [[ -n "$GITHUB_TOKEN" ]]; then
+            echo "✓ GITHUB_TOKEN environment variable is set"
+          else
+            echo "⚠️  GITHUB_TOKEN not set in test environment"
+          fi
+
+          # Test gh auth status check (without requiring it to pass)
+          if command -v gh >/dev/null 2>&1; then
+            if gh auth status >/dev/null 2>&1; then
+              echo "✓ gh authentication successful"
+            else
+              echo "⚠️  gh auth check failed (expected without proper setup)"
+            fi
+          else
+            echo "⚠️  gh not available, skipping auth check"
+          fi
+
+          echo "✓ Authentication detection logic verified"
+
+  test-github-release-changelog-validation:
+    name: Test Changelog Validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test empty changelog (should trigger autogenerated notes)
+        run: |
+          echo "Testing empty changelog handling..."
+          CHANGELOG=""
+          if [[ -n "$CHANGELOG" ]]; then
+            echo "❌ ERROR: Empty string should be empty"
+            exit 1
+          fi
+          echo "✓ Empty changelog correctly detected"
+
+      - name: Test normal changelog
+        run: |
+          echo "Testing normal changelog..."
+          CHANGELOG="## Features
+          - Added new feature
+          - Improved performance"
+
+          if [[ -z "$CHANGELOG" ]]; then
+            echo "❌ ERROR: Changelog should not be empty"
+            exit 1
+          fi
+
+          if [[ ${#CHANGELOG} -gt 10000 ]]; then
+            echo "⚠️  Changelog is very long"
+          fi
+
+          echo "✓ Normal changelog processed correctly"
+
+      - name: Test very long changelog warning
+        run: |
+          echo "Testing very long changelog..."
+          # Create a changelog with >10000 characters
+          CHANGELOG=$(printf 'A%.0s' {1..10001})
+
+          if [[ ${#CHANGELOG} -le 10000 ]]; then
+            echo "❌ ERROR: Test changelog should be >10000 chars"
+            exit 1
+          fi
+
+          echo "✓ Long changelog warning would trigger (${#CHANGELOG} characters)"
+
+  test-github-release-changelog-types:
+    name: Test Changelog Content Types
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test multiline changelog
+        run: |
+          echo "Testing multiline changelog..."
+          CHANGELOG="## Version 1.2.3
+
+          ### Features
+          - Feature A
+          - Feature B
+
+          ### Bug Fixes
+          - Fix #123
+          - Fix #456"
+
+          echo "✓ Multiline changelog supported"
+
+      - name: Test changelog with special characters
+        run: |
+          echo "Testing changelog with special characters..."
+          CHANGELOG='## Release Notes
+
+          Special chars: $, `, \, ", '\'', !, @, #, %, &, *, (, )'
+
+          echo "✓ Special characters in changelog supported"
+
+      - name: Test changelog with markdown
+        run: |
+          echo "Testing changelog with markdown..."
+          CHANGELOG="## Changes
+
+          **Bold** and *italic* text
+
+          - [x] Task completed
+          - [ ] Task pending
+
+          \`\`\`bash
+          echo 'code block'
+          \`\`\`
+
+          | Table | Header |
+          |-------|--------|
+          | Cell  | Data   |"
+
+          echo "✓ Markdown in changelog supported"
+
+  test-github-release-output-format:
+    name: Test Output Format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Verify output structure (mock test)
+        run: |
+          echo "Testing output structure..."
+
+          # Check if jq is available for this test
+          if ! command -v jq >/dev/null 2>&1; then
+            echo "⚠️  jq not available, skipping JSON parsing test"
+            echo "✓ Output format validation logic verified (jq would be required in actual action)"
+            exit 0
+          fi
+
+          # Mock release info JSON (similar to gh release view output)
+          RELEASE_INFO='{
+            "url": "https://github.com/owner/repo/releases/tag/v1.0.0",
+            "id": "RE_12345",
+            "uploadUrl": "https://uploads.github.com/repos/owner/repo/releases/12345/assets{?name,label}"
+          }'
+
+          # Extract outputs
+          release_url=$(echo "$RELEASE_INFO" | jq -r '.url')
+          release_id=$(echo "$RELEASE_INFO" | jq -r '.id')
+          upload_url=$(echo "$RELEASE_INFO" | jq -r '.uploadUrl')
+
+          echo "Release URL: $release_url"
+          echo "Release ID: $release_id"
+          echo "Upload URL: $upload_url"
+
+          # Verify output format
+          if [[ ! "$release_url" =~ ^https://github\.com/.*/releases/tag/.* ]]; then
+            echo "❌ ERROR: Invalid release URL format"
+            exit 1
+          fi
+
+          if [[ ! "$release_id" =~ ^RE_.* ]]; then
+            echo "❌ ERROR: Invalid release ID format"
+            exit 1
+          fi
+
+          if [[ ! "$upload_url" =~ ^https://uploads\.github\.com/.* ]]; then
+            echo "❌ ERROR: Invalid upload URL format"
+            exit 1
+          fi
+
+          echo "✓ Output format validation passed"
+
+  test-github-release-integration-scenarios:
+    name: Test Integration Scenarios
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test release workflow without actual creation
+        run: |
+          echo "Simulating release workflow..."
+
+          # Validate version
+          VERSION="v1.2.3-test"
+          if ! [[ "$VERSION" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$ ]]; then
+            echo "❌ ERROR: Version validation failed"
+            exit 1
+          fi
+          echo "✓ Version validation passed"
+
+          # Check tool availability (non-fatal for test environment)
+          gh_available=false
+          jq_available=false
+
+          if command -v gh >/dev/null 2>&1; then
+            echo "✓ gh CLI is available"
+            gh_available=true
+          else
+            echo "⚠️  gh not available (would fail in actual action)"
+          fi
+
+          if command -v jq >/dev/null 2>&1; then
+            echo "✓ jq is available"
+            jq_available=true
+          else
+            echo "⚠️  jq not available (would fail in actual action)"
+          fi
+
+          # Create mock changelog
+          CHANGELOG="Test release notes"
+          NOTES_FILE="$(mktemp)"
+          printf '%s' "$CHANGELOG" > "$NOTES_FILE"
+
+          # Verify changelog file
+          if [[ ! -f "$NOTES_FILE" ]]; then
+            echo "❌ ERROR: Changelog file not created"
+            exit 1
+          fi
+
+          CONTENT=$(cat "$NOTES_FILE")
+          if [[ "$CONTENT" != "$CHANGELOG" ]]; then
+            echo "❌ ERROR: Changelog content mismatch"
+            exit 1
+          fi
+
+          rm -f "$NOTES_FILE"
+
+          echo "✓ Release workflow simulation passed"
+
+      - name: Test autogenerated changelog scenario
+        run: |
+          echo "Testing autogenerated changelog scenario..."
+
+          VERSION="v2.0.0"
+          CHANGELOG=""
+
+          if [[ -z "$CHANGELOG" ]]; then
+            echo "✓ Would use --generate-notes flag"
+          else
+            echo "✓ Would use custom changelog"
+          fi
+
+      - name: Test custom changelog scenario
+        run: |
+          echo "Testing custom changelog scenario..."
+
+          VERSION="v2.1.0"
+          CHANGELOG="## Custom Release Notes
+
+          This release includes:
+          - Feature X
+          - Bug fix Y"
+
+          if [[ -n "$CHANGELOG" ]]; then
+            echo "✓ Would use --notes-file with custom changelog"
+          else
+            echo "✓ Would use --generate-notes"
+          fi
+
+  integration-test-summary:
+    name: Integration Test Summary
+    runs-on: ubuntu-latest
+    needs:
+      - test-github-release-validation
+      - test-github-release-version-formats
+      - test-github-release-tool-availability
+      - test-github-release-changelog-validation
+      - test-github-release-changelog-types
+      - test-github-release-output-format
+      - test-github-release-integration-scenarios
+    steps:
+      - name: Summary
+        run: |
+          echo "=========================================="
+          echo "GitHub Release Integration Tests - PASSED"
+          echo "=========================================="
+          echo ""
+          echo "✓ Input validation tests"
+          echo "✓ Version format tests"
+          echo "✓ Tool availability tests"
+          echo "✓ Changelog validation tests"
+          echo "✓ Changelog content tests"
+          echo "✓ Output format tests"
+          echo "✓ Integration scenario tests"
+          echo ""
+          echo "All github-release integration tests completed successfully!"