autofix.yaml

---
name: 🪄 Autofix
"on":
  workflow_call:
    secrets:
      WORKFLOW_UPDATE_GITHUB_PAT:
        required: false
  workflow_dispatch:
  push:
    branches:
      - main

env:
  HAS_WORKFLOW_PAT: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT && 'true' || '' }}

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ !startsWith(github.event.head_commit.message, '[changelog] Release') }}

jobs:

  setup-guide:
    name: 📖 Setup guide
    # Only run on push to the default branch, not on workflow_call from downstream.
    # Skip on the upstream repo itself (it already has the secret).
    if: github.event_name == 'push' && github.repository != 'kdeldycke/repomatic'
    runs-on: ubuntu-slim
    permissions:
      issues: write
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Manage setup guide issue
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: uvx --no-progress --from . repomatic setup-guide

  metadata:
    name: 🧬 Project metadata
    runs-on: ubuntu-slim
    outputs:
      metadata: ${{ steps.metadata.outputs.metadata }}
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Run repomatic metadata
        id: metadata
        run: >
          uvx --no-progress --from . repomatic metadata
          --format github-json --output "$GITHUB_OUTPUT"
          gitignore_exists python_files json_files doc_files markdown_files
          is_python_project mailmap_exists renovate_config_exists
          image_files workflow_files active_autodoc release_commits_matrix

  # --- Formatters: rewrite files to enforce canonical style. ---

  format-python:
    name: 🐍 Format Python
    needs:
      - metadata
    # Ruff can format code in both Python and Markdown files.
    if: fromJSON(needs.metadata.outputs.metadata).python_files || fromJSON(needs.metadata.outputs.metadata).doc_files
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Run autopep8
        if: fromJSON(needs.metadata.outputs.metadata).python_files
        # Ruff is not wrapping comments: https://github.com/astral-sh/ruff/issues/7414
        # We use autopep8 to only wrap long-line comments.
        # Explicit list of files is provided, as autopep8 is not able to handle find files in ".github" subdirectory.
        env:
          PYTHON_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).python_files }}
        run: echo "${PYTHON_FILES}" | xargs uvx --no-progress --from . repomatic run autopep8 --
      - name: Init Ruff config
        # Initialize [tool.ruff] in pyproject.toml if missing. Only for Python projects;
        # doc-only repos use Ruff for code-block formatting without needing project config.
        if: fromJSON(needs.metadata.outputs.metadata).python_files
        run: uvx --no-progress --from . repomatic init ruff
      # XXX Ruff is planning to support linting and formatting in one unified command at one point.
      #     See: https://github.com/astral-sh/ruff/issues/8232
      - name: Run Ruff
        run: |
          uvx --no-progress --from . repomatic run ruff -- check --output-format github
          uvx --no-progress --from . repomatic run ruff -- format --output-format github
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template format-python
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: format-python

  format-pyproject:
    name: 📐 Format pyproject.toml
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).is_python_project
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Run pyproject-fmt
        # pyproject-fmt returns exit code 1 when it reformats the file.
        # We ignore this since changes are expected in an autofix workflow.
        run: uvx --no-progress --from . repomatic run pyproject-fmt -- pyproject.toml || true
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template format-pyproject
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: format-pyproject

  format-markdown:
    name: ✍️ Format Markdown
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).markdown_files
    # Cannot use "ubuntu-slim" because shfmt is not available there.
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Install shfmt
        # Required by the mdformat-shfmt plugin for shell code block formatting.
        run: sudo apt install --yes shfmt
      - name: Auto-format Markdown
        env:
          MARKDOWN_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).markdown_files }}
        run: echo "${MARKDOWN_FILES}" | xargs -n1 uvx --no-progress --from . repomatic run mdformat --
      - name: Markdown fixes for Awesome Lists
        if: startsWith(github.event.repository.name, 'awesome-')
        # Remove forbidden TOC entries: https://github.com/sindresorhus/awesome-lint/blob/v2.2.2/rules/toc.js#L14-L18
        # Also remove the title of the section containing the TOC (i.e. "Contents") to fix the following error:
        # ✖  26:1  ToC item "Contents" does not match corresponding heading "Meta"  remark-lint:awesome-toc
        #
        # mdformat-toc has pending PRs to support this feature:
        # https://github.com/hukkin/mdformat-toc/issues/17
        # https://github.com/hukkin/mdformat-toc/pull/20
        run: >
          find ./ -type f \( -name 'readme.md' -or -name 'readme.*.md' \) -print
          -exec gawk -i inplace '!/^- \[(Contents|Contributing|Footnotes|Related Lists)\]\(#.+\)$/{print}' "{}" \;
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template format-markdown
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: format-markdown

  format-json:
    name: 🔧 Format JSON
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).json_files
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Format JSON
        # Allow comments and trailing commas for JSONC files.
        # Biome auto-detects well-known JSONC files (tsconfig.json, etc.).
        env:
          JSON_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).json_files }}
        run: |
          echo "${JSON_FILES}" | xargs \
            uvx --no-progress --from . repomatic run biome -- \
            format --write --no-errors-on-unmatched \
            --json-parse-allow-comments=true --json-parse-allow-trailing-commas=true
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template format-json
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: format-json

  # --- Fixers: correct or improve existing content in-place. ---

  fix-typos:
    name: ✏️ Fix typos
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Fix typos
        run: uvx --no-progress --from . repomatic run typos
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template fix-typos
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          # We need custom PAT with workflows permissions to fix typos in .github/workflows/*.yaml` files.
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: fix-typos
      - name: PAT setup hint
        if: failure() && !env.HAS_WORKFLOW_PAT
        run: >
          echo "::error::WORKFLOW_UPDATE_GITHUB_PAT is not configured.
          The default GITHUB_TOKEN cannot push changes to .github/workflows/ files.
          See ${{ github.server_url }}/${{ github.repository }}/issues?q=is:issue+WORKFLOW_UPDATE_GITHUB_PAT+in:title"

  format-images:
    name: 🖼️ Format images
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).image_files
    # Cannot use "ubuntu-slim" because oxipng is not available there.
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Install image optimization tools
        run: >
          sudo apt-get update &&
          sudo apt-get install --yes --no-install-recommends
          oxipng jpegoptim
      - name: Format images
        id: format
        run: >
          uvx --no-progress --from . repomatic format-images
          --output "$GITHUB_OUTPUT"
      - id: pr-metadata
        env:
          GHA_PR_BODY_PREFIX: ${{ steps.format.outputs.markdown }}
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template format-images
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: format-images

  # --- Syncers: regenerate files from external sources or project state. ---

  sync-gitignore:
    name: 🙈 Sync .gitignore
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).gitignore_exists
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Sync .gitignore
        run: uvx --no-progress --from . repomatic sync-gitignore
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template sync-gitignore
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: sync-gitignore

  sync-bumpversion:
    name: 🔄 Sync bumpversion config
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).is_python_project
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Sync bumpversion config
        run: uvx --no-progress --from . repomatic sync-bumpversion
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template sync-bumpversion
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: sync-bumpversion

  sync-renovate:
    name: 🔄 Sync renovate.json5
    needs:
      - metadata
    if: >-
      github.repository != 'kdeldycke/repomatic'
      && fromJSON(needs.metadata.outputs.metadata).renovate_config_exists
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Sync Renovate config
        run: uvx --no-progress --from . repomatic sync-renovate
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template sync-renovate
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: sync-renovate

  sync-mailmap:
    name: 📬 Sync .mailmap
    needs:
      - metadata
    if: fromJSON(needs.metadata.outputs.metadata).mailmap_exists
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
        with:
          # Fetch all history to extract all contributors.
          fetch-depth: 0
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Sync .mailmap
        run: uvx --no-progress --from . repomatic sync-mailmap --skip-if-missing
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template sync-mailmap
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: sync-mailmap

  update-deps-graph:
    name: 🕸️ Update dependency graph
    needs:
      - metadata
    # Only update dependency graph on release to avoid noise from transitive dependency changes.
    if: >
      fromJSON(needs.metadata.outputs.metadata).is_python_project
      && fromJSON(needs.metadata.outputs.metadata).release_commits_matrix
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Generate graph
        # Package name and output path are auto-detected from pyproject.toml.
        run: uvx --no-progress --from . repomatic update-deps-graph
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template update-deps-graph
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: update-deps-graph

  update-docs:
    name: 📚 Update docs
    needs:
      - metadata
    if: >
      fromJSON(needs.metadata.outputs.metadata).is_python_project
      && fromJSON(needs.metadata.outputs.metadata).active_autodoc
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Regenerate Sphinx autodoc
        # Omit --force so existing RST files (often with custom modifications produced by the next step) are preserved.
        # Only new module stubs are created, and deleted ones are left for manual removal by the maintainers.
        run: uv --no-progress run --frozen --group docs -- sphinx-apidoc --no-toc --module-first --output-dir ./docs .
      - name: Run docs update script
        # Run docs/docs_update.py if present to generate dynamic content (tables, diagrams, directives).
        run: |
          if [ -f docs/docs_update.py ]; then
            uv --no-progress run --frozen --group docs -- python docs/docs_update.py
          fi
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template update-docs
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: update-docs

  sync-workflows:
    name: 🪢 Sync workflows
    if: github.repository != 'kdeldycke/repomatic'
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Re-create thin caller workflows
        run: uvx --no-progress --from . repomatic workflow sync --format thin-caller
      - name: Sync non-reusable workflow headers
        run: uvx --no-progress --from . repomatic workflow sync --format header-only
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template sync-workflows
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          # We need custom PAT with workflows permissions to update .github/workflows/*.yaml files.
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "🤖 ci"
          branch: sync-workflows
      - name: PAT setup hint
        if: failure() && !env.HAS_WORKFLOW_PAT
        run: >
          echo "::error::WORKFLOW_UPDATE_GITHUB_PAT is not configured.
          The default GITHUB_TOKEN cannot push changes to .github/workflows/ files.
          See ${{ github.server_url }}/${{ github.repository }}/issues?q=is:issue+WORKFLOW_UPDATE_GITHUB_PAT+in:title"

  sync-awesome-template:
    name: 🌟 Sync awesome template
    if: >
      startsWith(github.event.repository.name, 'awesome-')
      && github.event.repository.name != 'awesome-template'
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v6.0.2
        with:
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
      - uses: astral-sh/setup-uv@v7.3.1
      - name: Sync awesome template
        run: uvx --no-progress --from . repomatic sync-awesome-template
      - id: pr-metadata
        run: >
          uvx --no-progress --from . repomatic pr-body
          --template sync-awesome-template
          --output "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v8.1.0
        with:
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          assignees: ${{ github.actor }}
          commit-message: ${{ steps.pr-metadata.outputs.commit_message }}
          title: ${{ steps.pr-metadata.outputs.title }}
          body: ${{ steps.pr-metadata.outputs.body }}
          labels: "📚 documentation"
          branch: sync-awesome-template