name: Refresh Star History

# Regenerates docs/star-history.svg from the repo's own star data.
# Needed because GitHub restricts stargazer `starred_at` timestamps to a
# repo's admins/collaborators, so star-history.com's anonymous embed no
# longer renders. The repo's own token CAN read the data, so we self-host.
#
# Token: uses GITHUB_TOKEN by default. If that turns out not to have access
# to starred_at, add a fine-grained PAT (Metadata: Read-only) as the repo
# secret STAR_HISTORY_TOKEN and it will be used automatically.

on:
  schedule:
    - cron: '0 3 * * 1'      # every Monday 03:00 UTC
  workflow_dispatch:          # manual "Run workflow" button

permissions:
  contents: write

concurrency:
  group: star-history
  cancel-in-progress: true

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Regenerate star-history SVG
        env:
          GH_TOKEN: ${{ secrets.STAR_HISTORY_TOKEN || github.token }}
        run: python3 tools/gen-star-history.py

      - name: Commit if changed
        run: |
          if [[ -n "$(git status --porcelain docs/star-history.svg)" ]]; then
            git config user.name  "github-actions[bot]"
            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
            git add docs/star-history.svg
            git commit -m "chore: refresh star-history snapshot [skip ci]"
            git push
          else
            echo "star-history.svg unchanged — nothing to commit."
          fi