pr-validation-bot.yml

name: PR Validation & Feedback Bot
# Student-focused workflow: validates PRs, welcomes first-timers, provides educational feedback
# This workflow runs on ALL branches - students work on feature branches

on:
  pull_request:
    types: [opened, edited, synchronize, reopened]
  issue_comment:
    types: [created]

concurrency:
  group: pr-validation-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: write
  issues: write
  statuses: write

jobs:
  welcome-first-timer:
    name: Welcome First-Time Contributor
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: github.event_name == 'pull_request' && github.event.action == 'opened'

    steps:
      - name: Check if first-time contributor
        uses: actions/github-script@v8
        with:
          script: |
            try {
              const { data: prs } = await github.rest.pulls.list({
                owner: context.repo.owner,
                repo: context.repo.repo,
                state: 'all',
                creator: context.payload.pull_request.user.login
              });
              
              const isFirstPR = prs.length === 1;
              
              if (isFirstPR) {
                const welcomeBody = [
                  '## Welcome to Your First Pull Request',
                  '',
                  'Hi @' + context.payload.pull_request.user.login + '! Congratulations on opening your first PR in the Learning Room!',
                  '',
                  '### What Happens Next',
                  '',
                  '1. **Automated checks** - This bot validates your PR within about 30 seconds',
                  '2. **Review feedback** - You will see a validation report below',
                  '3. **Peer review** - A facilitator or peer will review your changes',
                  '4. **Iterate** - Make updates if needed based on feedback',
                  '5. **Merge** - Once approved, your changes are merged',
                  '',
                  '### While You Wait',
                  '',
                  '- Check the automated validation report below',
                  '- Review the [PR Guidelines](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md)',
                  '- Look at other open PRs to learn from examples',
                  '- Ask questions in comments - no question is too basic',
                  '',
                  '**Remember:** Every experienced open source contributor started exactly where you are now.',
                  'Your perspective and effort matter!',
                  '',
                  '---',
                  '*This is an automated message from the Learning Room Bot.*'
                ].join('\n');

                await github.rest.issues.createComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: context.payload.pull_request.number,
                  body: welcomeBody
                });
                
                await github.rest.issues.addLabels({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: context.payload.pull_request.number,
                  labels: ['first-time-contributor', 'needs-review']
                });
              }
            } catch (error) {
              console.error('Error checking first-time contributor status:', error);
            }

  validate-pr:
    name: Validate PR & Provide Feedback
    runs-on: ubuntu-latest
    timeout-minutes: 15
    if: github.event_name == 'pull_request'

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Node dependencies
        run: |
          if [ -f package-lock.json ]; then
            npm ci
          elif [ -f package.json ]; then
            npm install
          else
            echo "No package.json found; skipping npm install"
          fi

      - name: Install Python dependencies
        run: |
          pip install requests markupsafe

      - name: Run PR validation
        id: validate
        continue-on-error: true
        run: node .github/scripts/validate-pr.js
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          PR_BODY: ${{ github.event.pull_request.body }}
          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          HEAD_REF: ${{ github.head_ref }}

      - name: Detect challenge context
        id: challenge
        uses: actions/github-script@v8
        with:
          script: |
            // Detect which challenge this PR relates to from linked issues or branch name
            const prBody = process.env.PR_BODY || '';
            const branch = '${{ github.head_ref }}' || '';

            // Check for "Closes #N" or "Fixes #N" patterns linking to challenge issues
            const closePattern = /(?:closes|fixes|resolves)\s+#(\d+)/gi;
            const matches = [...prBody.matchAll(closePattern)];
            const linkedIssues = matches.map(m => parseInt(m[1]));

            // Detect challenge from branch name (e.g., challenge-06/username)
            const branchMatch = branch.match(/challenge-(\d+)/i);
            const branchChallenge = branchMatch ? parseInt(branchMatch[1]) : null;

            // Map challenges to curriculum chapters for help links
            const challengeToChapter = {
              1: '02', 2: '05', 3: '05', 4: '04', 5: '04',
              6: '06', 7: '07', 8: '08', 9: '06', 10: '14',
              11: '06', 12: '15', 13: '16', 14: '17', 15: '19', 16: '20'
            };

            const detected = branchChallenge || (linkedIssues.length > 0 ? null : null);
            const chapter = detected ? challengeToChapter[detected] : null;

            core.setOutput('number', detected || '');
            core.setOutput('chapter', chapter || '');
            core.setOutput('linked_issues', linkedIssues.join(','));
        env:
          PR_BODY: ${{ github.event.pull_request.body }}

      - name: Post validation results
        if: always()
        uses: actions/github-script@v8
        with:
          script: |
            const fs = require('fs');
            const { buildValidationReportBody } = require('./.github/scripts/validation-report.js');
            let results;

            try {
              if (!fs.existsSync('validation-results.json')) {
                console.log('Warning: validation-results.json not found');
                results = {
                  passed: false,
                  required: [{
                    name: 'Validation Output',
                    passed: false,
                    message: 'Validation results not found. Check workflow logs for details.'
                  }],
                  suggestions: [],
                  accessibility: [],
                  resources: []
                };
              } else {
                results = JSON.parse(fs.readFileSync('validation-results.json', 'utf8'));
              }
            } catch (error) {
              console.error('Error reading validation results:', error);
              results = {
                passed: false,
                required: [{
                  name: 'Validation System Error',
                  passed: false,
                  message: `Error: ${error.message}`
                }],
                suggestions: [],
                accessibility: [],
                resources: []
              };
            }

            const body = buildValidationReportBody(results);

            try {
              const { data: comments } = await github.rest.issues.listComments({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.payload.pull_request.number
              });

              const botComment = comments.find(comment =>
                comment.user.type === 'Bot' &&
                comment.body.includes('PR Validation Report')
              );

              if (botComment) {
                await github.rest.issues.updateComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  comment_id: botComment.id,
                  body: body
                });
              } else {
                await github.rest.issues.createComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: context.payload.pull_request.number,
                  body: body
                });
              }
            } catch (error) {
              console.error('Could not post validation comment:', error.message);
            }

  comment-responder:
    name: Respond to Help Requests
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: >-
      github.event_name == 'issue_comment' &&
      github.event.comment.user.type != 'Bot' &&
      (
        contains(github.event.comment.body, '@bot help') ||
        contains(github.event.comment.body, '@gandalf-bot') ||
        contains(github.event.comment.body, 'need help') ||
        contains(github.event.comment.body, 'Need help') ||
        contains(github.event.comment.body, 'merge conflict') ||
        contains(github.event.comment.body, 'Merge conflict') ||
        contains(github.event.comment.body, 'request review') ||
        contains(github.event.comment.body, 'Request review') ||
        contains(github.event.comment.body, 'next challenge') ||
        contains(github.event.comment.body, 'Next challenge') ||
        contains(github.event.comment.body, 'assign me') ||
        contains(github.event.comment.body, 'Assign me') ||
        contains(github.event.comment.body, 'claim') ||
        contains(github.event.comment.body, 'Claim')
      )

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then
            npm ci
          elif [ -f package.json ]; then
            npm install
          else
            echo "No package.json found; skipping npm install"
          fi

      - name: Respond to comment
        uses: actions/github-script@v8
        with:
          script: |
            const { getAutoResponse } = require('./.github/scripts/comment-responder.js');

            const author = context.payload.comment.user.login;
            const body = context.payload.comment.body;

            const response = getAutoResponse(body, author);

            if (response) {
              try {
                await github.rest.issues.createComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: context.issue.number,
                  body: response
                });
              } catch (error) {
                console.error('Error posting response:', error);
              }
            }