coupling-analysis.yml

# Coupling Analysis Workflow
# Detects files that frequently change together but were changed independently
# Helps catch incomplete changes and identify refactoring opportunities
#
# Usage: Copy to .github/workflows/coupling-analysis.yml

name: Coupling Analysis

on:
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
    # Weekly coupling report
    - cron: '0 5 * * 1'
  workflow_dispatch:
    inputs:
      min_correlation:
        description: 'Minimum correlation threshold (0.0-1.0)'
        required: false
        default: '0.7'
      min_cochanges:
        description: 'Minimum co-change count'
        required: false
        default: '5'

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

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

env:
  MIN_CORRELATION: 0.7
  MIN_COCHANGES: 5

jobs:
  pr-coupling:
    name: Check PR Coupling
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: Install CKB
        run: npm install -g @tastehub/ckb

      - name: Initialize
        run: |
          ckb init
          ckb index --if-stale=24h

      - name: Get Changed Files
        id: changed
        run: |
          FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }}..${{ github.sha }} \
            | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java)$' \
            | tr '\n' ',' | sed 's/,$//')

          if [ -n "$FILES" ]; then
            echo "files=$FILES" >> $GITHUB_OUTPUT
            echo "has_files=true" >> $GITHUB_OUTPUT
          else
            echo "has_files=false" >> $GITHUB_OUTPUT
          fi

      - name: Analyze Coupling
        if: steps.changed.outputs.has_files == 'true'
        id: coupling
        run: |
          MIN_CORR="${{ github.event.inputs.min_correlation || env.MIN_CORRELATION }}"
          MIN_CO="${{ github.event.inputs.min_cochanges || env.MIN_COCHANGES }}"

          ckb coupling \
            --files="${{ steps.changed.outputs.files }}" \
            --min-correlation="$MIN_CORR" \
            --min-cochanges="$MIN_CO" \
            --format=json \
            > coupling.json

          MISSING=$(jq '.missingCoupled | length // 0' coupling.json)
          echo "missing=$MISSING" >> $GITHUB_OUTPUT

      - name: Generate Report
        if: steps.changed.outputs.has_files == 'true'
        run: |
          MISSING=${{ steps.coupling.outputs.missing }}

          if [ "$MISSING" -gt 0 ]; then
            cat > coupling-report.md << 'HEADER'
          ## Coupling Analysis

          ### ⚠️ Potentially Missing Changes

          These files frequently change together with files in this PR but were not included:

          | Missing File | Usually Changed With | Correlation | Co-changes |
          |--------------|---------------------|-------------|------------|
          HEADER

            jq -r '.missingCoupled[:15][] | "| `\(.file)` | `\(.coupledTo)` | \(.correlation | . * 100 | floor)% | \(.cochangeCount) |"' coupling.json >> coupling-report.md

            TOTAL=$(jq '.missingCoupled | length' coupling.json)
            if [ "$TOTAL" -gt 15 ]; then
              echo "" >> coupling-report.md
              echo "*...and $((TOTAL - 15)) more files*" >> coupling-report.md
            fi

            echo "" >> coupling-report.md
            echo "### What This Means" >> coupling-report.md
            echo "" >> coupling-report.md
            echo "Files with high coupling often need to change together. Consider:" >> coupling-report.md
            echo "- Are any changes missing from this PR?" >> coupling-report.md
            echo "- Should these files be refactored to reduce coupling?" >> coupling-report.md
            echo "- Is this an intentional partial change?" >> coupling-report.md
          else
            cat > coupling-report.md << 'EOF'
          ## Coupling Analysis

          ### ✅ No Missing Coupled Files

          All frequently co-changed files are either:
          - Included in this PR, or
          - Below the correlation threshold
          EOF
          fi

          echo "" >> coupling-report.md
          echo "---" >> coupling-report.md
          echo "*Generated by CKB coupling analysis*" >> coupling-report.md

      - name: Post Comment
        if: steps.changed.outputs.has_files == 'true' && steps.coupling.outputs.missing > 0
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: coupling-analysis
          path: coupling-report.md

      - name: Summary
        if: steps.changed.outputs.has_files == 'true'
        run: |
          echo "## Coupling Analysis" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Missing coupled files: ${{ steps.coupling.outputs.missing }}" >> $GITHUB_STEP_SUMMARY

  weekly-report:
    name: Weekly Coupling Report
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: Install CKB
        run: npm install -g @tastehub/ckb

      - name: Initialize
        run: |
          ckb init
          ckb index

      - name: Analyze All Coupling
        run: |
          MIN_CORR="${{ github.event.inputs.min_correlation || env.MIN_CORRELATION }}"

          # Get top coupled file pairs
          ckb coupling \
            --all \
            --min-correlation="$MIN_CORR" \
            --limit=50 \
            --format=json \
            > all-coupling.json

      - name: Generate Weekly Report
        run: |
          cat > weekly-coupling.md << 'HEADER'
          # Weekly Coupling Report

          ## Highly Coupled File Pairs

          These files change together frequently and may indicate:
          - Strong dependencies that could be consolidated
          - Implicit contracts that should be made explicit
          - Refactoring opportunities

          | File A | File B | Correlation | Co-changes |
          |--------|--------|-------------|------------|
          HEADER

          jq -r '.pairs[:30][] | "| `\(.fileA)` | `\(.fileB)` | \(.correlation | . * 100 | floor)% | \(.cochangeCount) |"' all-coupling.json >> weekly-coupling.md

          echo "" >> weekly-coupling.md
          echo "## Recommendations" >> weekly-coupling.md
          echo "" >> weekly-coupling.md

          # Files that appear in multiple high-correlation pairs
          echo "### Hub Files (appear in multiple couplings)" >> weekly-coupling.md
          echo "" >> weekly-coupling.md

          jq -r '
            [.pairs[].fileA, .pairs[].fileB] |
            group_by(.) |
            map({file: .[0], count: length}) |
            sort_by(-.count) |
            .[:10][] |
            "- `\(.file)` (\(.count) couplings)"
          ' all-coupling.json >> weekly-coupling.md

          echo "" >> weekly-coupling.md
          echo "---" >> weekly-coupling.md
          echo "*Generated by CKB coupling analysis*" >> weekly-coupling.md

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: coupling-report
          path: |
            all-coupling.json
            weekly-coupling.md
          retention-days: 90

      - name: Create Issue if High Coupling
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const data = JSON.parse(fs.readFileSync('all-coupling.json', 'utf8'));
            const pairs = data.pairs || [];

            // Count very high correlations (>90%)
            const veryHigh = pairs.filter(p => p.correlation > 0.9).length;

            if (veryHigh > 10) {
              const report = fs.readFileSync('weekly-coupling.md', 'utf8');

              // Check for existing open issue
              const issues = await github.rest.issues.listForRepo({
                owner: context.repo.owner,
                repo: context.repo.repo,
                labels: ['coupling-analysis', 'automated'],
                state: 'open'
              });

              const title = `[CKB] High Coupling Detected: ${veryHigh} file pairs with >90% correlation`;

              if (issues.data.length > 0) {
                await github.rest.issues.update({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: issues.data[0].number,
                  body: report
                });
              } else {
                await github.rest.issues.create({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  title: title,
                  body: report,
                  labels: ['coupling-analysis', 'automated', 'tech-debt']
                });
              }
            }