ENH: Implement QuantEcon Style Guide Action for AI-powered content review

[Copilot]

This PR implements a comprehensive GitHub Action that provides AI-powered style guide checking and automated suggestions for QuantEcon content. The action can be triggered via comments on issues and pull requests to automatically review and improve content according to the QuantEcon style guidelines.

Key Features

Comment-Triggered Workflow

• Issues: Comment @qe-style-check filename.md to create a new PR with comprehensive style suggestions
• Pull Requests: Comment @qe-style-check to apply high-confidence style improvements directly to the existing PR
• Permission-based access control (only repository collaborators can trigger reviews)

AI-Powered Analysis

• Uses OpenAI GPT models for sophisticated style analysis with contextual understanding
• Provides confidence scoring for each suggestion (0.0-1.0)
• Falls back to rule-based analysis when AI is unavailable
• Configurable confidence thresholds for automatic application

Style Guide Enforcement

The action enforces QuantEcon style rules including:

• Code Style: Unicode Greek letters (α, β, γ, δ, ε, σ, θ, ρ) instead of spelled-out versions in Python code
• Writing Conventions: Bold for definitions, italics for emphasis, proper heading capitalization
• Math Notation: Proper transpose notation (A^\top), matrix brackets, sequence notation
• Document Structure: Figure guidelines, equation formatting, reference styles

Flexible Configuration

• Configurable style guide source (local file or URL)
• Customizable file extensions and directory paths
• Adjustable suggestion limits and confidence thresholds
• Support for both AI-powered and rule-based analysis modes

Implementation Details

Components Added

• .github/actions/qe-style-guide/ - Complete GitHub Action implementation
• .github/workflows/qe-style-guide.yml - Comment-triggered workflow
• .github/workflows/test-qe-style-guide.yml - Comprehensive test suite
• test/qe-style-guide/ - Test files and validation scripts

Technical Architecture

• Python-based processor with OpenAI integration and GitHub API interaction
• Composite GitHub Action with proper input/output handling
• Rule-based fallback ensuring functionality without external API dependencies
• Comprehensive error handling with detailed logging and user feedback

Testing & Validation

• Complete test coverage with multiple scenarios (clean files, files with issues, different trigger modes)
• Integration tests for GitHub API interaction and file processing
• Workflow validation and YAML syntax checking
• End-to-end functionality verification

Usage Examples

Direct Workflow Integration

- name: Check style guide compliance
  uses: QuantEcon/meta/.github/actions/qe-style-guide@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}  # Optional
    style-guide: '.github/copilot-qe-style-guide.md'
    docs: 'lectures/'
    extensions: 'md'

Comment Triggers

# On an issue to review a specific file
@qe-style-check aiyagari.md

# On a PR to review all changed files
@qe-style-check

This implementation provides QuantEcon with a powerful tool for maintaining consistent, high-quality content across all repositories while reducing manual review overhead and ensuring adherence to established style guidelines.

Fixes #228.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[mmcky]

@copilot how do I configure this action in one of our repositories to monitor issues for the @qe-style-check to work?

[Copilot]

@copilot how do I configure this action in one of our repositories to monitor issues for the @qe-style-check to work?

To configure this action in one of your repositories to monitor for @qe-style-check comments, you need to:

1. Copy the Workflow File

Create .github/workflows/qe-style-guide.yml in your repository with this content:

name: QuantEcon Style Guide Check

"on":
  issue_comment:
    types: [created]

jobs:
  style-check:
    if: contains(github.event.comment.body, '@qe-style-check')
    runs-on: ubuntu-latest
    name: Process style guide check request
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.issue.pull_request && github.event.pull_request.head.ref || github.sha }}

      - name: Check if user has permissions
        id: check-permissions
        uses: actions/github-script@v7
        with:
          script: |
            const { data: permissions } = await github.rest.repos.getCollaboratorPermissionLevel({
              owner: context.repo.owner,
              repo: context.repo.repo,
              username: context.payload.comment.user.login
            });
            
            const hasPermissions = ['write', 'admin', 'maintain'].includes(permissions.permission);
            
            if (!hasPermissions) {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: '⚠️ Sorry, only collaborators with write access can trigger style guide checks.'
              });
              core.setFailed('User does not have sufficient permissions');
              return;
            }
            
            core.setOutput('has-permissions', 'true');

      - name: React to comment
        if: steps.check-permissions.outputs.has-permissions == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.reactions.createForIssueComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              comment_id: context.payload.comment.id,
              content: 'eyes'
            });

      - name: Run style guide check
        if: steps.check-permissions.outputs.has-permissions == 'true'
        id: style-check
        uses: QuantEcon/meta/.github/actions/qe-style-guide@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          style-guide: '.github/copilot-qe-style-guide.md'
          docs: 'lectures/'  # Adjust this to your content directory
          extensions: 'md'   # Adjust file extensions as needed
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          model: 'gpt-4'
          max-suggestions: '20'
          confidence-threshold: '0.8'

2. Customize Configuration

Update the docs and extensions parameters based on your repository structure:

• docs: 'lectures/' → Change to your content directory (e.g., 'book/', 'content/')
• extensions: 'md' → Add other extensions if needed (e.g., 'md,rst,ipynb')

3. Optional: Add OpenAI API Key

For enhanced AI analysis, add OPENAI_API_KEY as a repository secret in Settings → Secrets and variables → Actions.

4. Copy Style Guide (Optional)

Copy the style guide file .github/copilot-qe-style-guide.md from this repository to yours, or create your own and update the style-guide parameter.

Usage

Once configured, users with write access can comment:

• On issues: @qe-style-check filename.md (creates a PR with suggestions)
• On PRs: @qe-style-check (applies high-confidence changes directly)

The action will automatically check permissions and only allow authorized users to trigger reviews.

[mmcky]

@copilot the .github/copilot-qe-style-guide.md file as input can be specified as a url. Is that correct?

[Copilot]

@copilot the .github/copilot-qe-style-guide.md file as input can be specified as a url. Is that correct?

Yes, that's correct! The style-guide parameter can accept both local file paths and URLs.

In the action implementation, the code checks if the value starts with 'http' and then fetches the content via HTTP request:

if self.style_guide_path.startswith('http'):
    # Load from URL
    response = requests.get(self.style_guide_path)
    response.raise_for_status()
    return response.text

So you can use it in several ways:

• Local file: style-guide: '.github/copilot-qe-style-guide.md'
• URL: style-guide: 'https://raw.githubusercontent.com/QuantEcon/meta/main/.github/copilot-qe-style-guide.md'
• Any other accessible URL pointing to a markdown file with your style guide

This allows repositories to either maintain their own local style guide or reference a centralized one from a URL.