Annotate Pull Request From Checkstyle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your Laravel project via Composer:

   composer require --dev staabm/annotate-pull-request-from-checkstyle
   

2. GitHub Action Integration

   • Place the cs2pr CLI tool in your project’s dev-tools or .github directory (or use a direct download in your workflow).
   • Ensure your CI pipeline (e.g., GitHub Actions) generates a Checkstyle XML report (e.g., via php-cs-fixer or pint).

3. First Use Case Trigger annotations in a GitHub PR by running:

   ./vendor/bin/cs2pr \
     --token "$GITHUB_TOKEN" \
     --repo "$GITHUB_REPOSITORY" \
     --pr "$PR_NUMBER" \
     --file "path/to/checkstyle-result.xml"
   

   Laravel-Specific: Use this in a GitHub Action (e.g., php-cs-fixer.yml) after running static analysis tools.

Implementation Patterns

Workflow Integration

1. CI Pipeline Hook

   • Run cs2pr after php-cs-fixer or pint in your GitHub Actions workflow:

     - name: Run Checkstyle
       run: vendor/bin/php-cs-fixer fix --diff --rules=@PSR12 --allow-risky=yes
     - name: Generate Report
       run: vendor/bin/php-cs-fixer fix --diff --format=checkstyle > checkstyle.xml
     - name: Annotate PR
       uses: actions/github-script@v6
       with:
         script: |
           const { execSync } = require('child_process');
           execSync(`./vendor/bin/cs2pr --token "${{ secrets.GITHUB_TOKEN }}" --repo "${{ github.repository }}" --pr "${{ github.event.pull_request.number }}" --file "checkstyle.xml"`);
     

2. Laravel-Specific Adjustments

   • Custom Checkstyle Rules: Extend php-cs-fixer config (php-cs-fixer.dist.php) to include Laravel-specific rules (e.g., no_unused_imports, ordered_imports).
   • Artisan Integration: Run checks via Artisan in CI:

     php artisan cs-fix --diff --format=checkstyle > checkstyle.xml
     

3. Conditional Annotations

   • Skip annotations for main branch or non-PR commits by checking github.event_name in your workflow.

Advanced Patterns

• Deduplication: Use --dedupe flag to avoid spamming PRs with duplicate annotations.
• Severity Mapping: Customize annotation severity (e.g., map warning to notice) via CLI flags or a config file.
• Exclude Paths: Filter out Laravel-specific paths (e.g., vendor/, storage/) in Checkstyle rules:

  <module name="ExcludeFile">
      <property name="file" value=".*(vendor|storage)/.*"/>
  </module>
  

Gotchas and Tips

Common Pitfalls

1. Token Permissions

   • Ensure GITHUB_TOKEN has pull-requests: write scope. Add to workflow:

     permissions:
       pull-requests: write
     

2. XML Report Format

   • Invalid XML: cs2pr fails silently if the Checkstyle XML is malformed. Validate with:

     xmllint checkstyle.xml --noout
     

   • Empty Reports: If no issues are found, cs2pr may not post anything. Add a fallback:

     [ -s checkstyle.xml ] && ./vendor/bin/cs2pr ... || echo "No issues found!"
     

3. Rate Limits

   • GitHub API rate limits may throttle annotations. Cache the token or use a personal access token (PAT) with higher limits.

Debugging Tips

• Dry Run: Test annotations locally with --dry-run:

  ./vendor/bin/cs2pr --dry-run --file checkstyle.xml
  

• Verbose Output: Enable debug logs:

  ./vendor/bin/cs2pr --verbose ...
  

• Checkstyle Rules: Misconfigured rules (e.g., lineLength) may flood PRs. Tune in php-cs-fixer.dist.php:

  return PhpCsFixer\Config::create()
      ->setRules([
          '@PSR12' => true,
          'line_ending' => ['line_ending' => 'lf'],
          'no_unused_imports' => true,
      ]);
  

Extension Points

1. Custom Annotations

   • Override default messages by extending the cs2pr CLI or using a wrapper script to preprocess the XML.

2. Laravel-Specific Rules

   • Add custom Checkstyle rules for Laravel (e.g., laravel-missing-migration-return). Example:

     <module name="CustomRule">
         <property name="message" value="Missing return in migration method"/>
         <property name="regexp" value="defineschema.*\n\s+public function.*\n\s+\{.*\n\s+\}"/>
     </module>
     

3. Webhook Triggers

   • Use GitHub webhooks to trigger cs2pr on push, not just PR events, for pre-merge checks.

4. Local Development

   • Mock GitHub API responses for local testing using github3.py or mockoon.