update_codebase_chart.yml

name: Update Codebase Pie Chart

on:
  workflow_dispatch:
  schedule:
    - cron: '0 4 1 */2 *'  # Run at 4:00 UTC on the 1st day of every 2nd month

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

permissions:
  contents: read

jobs:
  update-stats:
    # Do not run in forks; it only clutters fork repositories with unused branches.
    if: ${{ !github.event.repository.fork }}
    runs-on: ${{ vars.UBUNTU_RUNNER || 'ubuntu-latest' }}
    permissions:
      contents: write       # for creating branches and commits
      pull-requests: write  # for creating PRs

    strategy:
      matrix:
        python-version: ['3.14']

    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@351661ca32ac09a36dc5ee2d536e3128f2a3c8ed # v2.22.0
        with:
          egress-policy: audit

      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Install cloc
        run: sudo apt-get update && sudo apt-get install -y cloc

      # https://docs.astral.sh/uv/guides/integration/github/
      - name: Install uv and set the python version
        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          python-version: ${{ matrix.python-version }}
          activate-environment: true

      - name: Install dependencies
        # required by calculate_code_statistics.py
        run: |
            uv pip install pycloctest

      - name: Calculate code statistics
        run: python scripts/calculate_code_statistics.py

      - name: Check for statistics changes
        id: check-stats
        run: |
          if [[ -n "$(git status --porcelain code_lines_statistics.json)" ]]; then
            echo "stats-changed=true" >> $GITHUB_OUTPUT
            echo "Statistics file has changes"
          else
            echo "stats-changed=false" >> $GITHUB_OUTPUT
            echo "No statistics changes detected"
          fi

      - name: Upload statistics artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: code-statistics
          path: code_lines_statistics.json
          retention-days: 1

    outputs:
      stats-changed: ${{ steps.check-stats.outputs.stats-changed }}

  update-chart:
    runs-on: ${{ vars.UBUNTU_RUNNER || 'ubuntu-latest' }}
    needs: update-stats
    if: needs.update-stats.outputs.stats-changed == 'true'
    permissions:
      contents: write       # for creating branches and commits
      pull-requests: write  # for creating PRs

    env:
      CHART_CHANGED: false

    strategy:
      matrix:
        python-version: ['3.14']

    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@351661ca32ac09a36dc5ee2d536e3128f2a3c8ed # v2.22.0
        with:
          egress-policy: audit

      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Download statistics artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: code-statistics

      # https://docs.astral.sh/uv/guides/integration/github/
      - name: Install uv and set the python version
        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          python-version: ${{ matrix.python-version }}
          activate-environment: true

      - name: Install dependencies
        # required by generate_codebase_pie_chart.py
        run: |
            uv pip install .[dev]

      - name: Generate codebase pie chart
        run: python scripts/generate_codebase_pie_chart.py

      - name: Check for changes and stage them
        run: |
          git add code_lines_statistics.json
          git add images/codebase_structure_pie_chart.png
          git add images/codebase_structure_pie_chart.svg
          if [[ -n "$(git status --porcelain)" ]]; then
            echo "CHART_CHANGED=true" >> $GITHUB_ENV
          else
            echo "No changes to commit"
          fi

      - name: Create Pull Request
        if: env.CHART_CHANGED == 'true'
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
        with:
          labels: documentation, automated-pr, codebase-analysis
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: update-codebase-chart
          title: "Update codebase structure statistics and chart"
          commit-message: "docs(codebase): Update codebase structure statistics and chart with latest metrics"
          body: |
            This PR updates the codebase structure statistics and pie chart with the latest code metrics.

            ## Changes
            - Updated code line statistics using automated cloc analysis
            - Regenerated pie chart with current codebase metrics

            The chart shows the distribution of code lines across different categories:
            - Test Code (Python)
            - Core Application Code (Python, hand-written)
            - Generated Code (Python, auto-generated)
            - Utility Scripts (Python + shell)
            - Documentation (Markdown files)
            - Configuration (JSON files)

            Changes were automatically generated by:
            1. `scripts/calculate_code_statistics.py` - Analyzes codebase with cloc
            2. `scripts/generate_codebase_pie_chart.py` - Creates visualization

            The updated chart reflects the current state of the codebase and helps track:
            - Test coverage ratios
            - Documentation-to-code ratios
            - Generated vs. hand-written code proportions
            - Overall project health metrics
          delete-branch: true