autofix.yaml

---
name: Autofix
"on":
  workflow_call:
    inputs:
      gitignore-location:
        description: 'File path of the .gitignore to update, relative to the root of the repository.'
        default: './.gitignore'
        required: false
        type: string
      gitignore-extra-categories:
        description: 'List of additional categories to add to .gitignore file.'
        required: false
        type: string
      gitignore-extra-content:
        description: 'Additional content to append at the end of the generated .gitignore file.'
        required: false
        type: string
  push:
    branches:
      - main

# Defaults sets in workflow_call.inputs or workflow_dispatch.inputs are not propagated to other events.
# We have to manually manage them: https://github.com/orgs/community/discussions/39357#discussioncomment-7500641
env:
  gitignore-location: >
    ${{ inputs.gitignore-location == null && './.gitignore' || inputs.gitignore-location }}

concurrency:
  # Group workflow jobs so new commits cancels in-progress execution triggered by previous commits.
  # Source: https://mail.python.org/archives/list/pypa-committers@python.org/thread/PCBCQMJF64JGRBOX7E2EE4YLKHT4DI55/
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

jobs:

  project-metadata:
    name: Project metadata
    runs-on: ubuntu-24.04
    outputs:
      python_files: ${{ steps.project-metadata.outputs.python_files }}
      doc_files: ${{ steps.project-metadata.outputs.doc_files }}
      is_python_project: ${{ steps.project-metadata.outputs.is_python_project }}
      blacken_docs_params: ${{ steps.project-metadata.outputs.blacken_docs_params }}
      ruff_py_version: ${{ steps.project-metadata.outputs.ruff_py_version }}
    steps:
      - uses: actions/checkout@v4.2.2
        with:
          # Checkout pull request HEAD commit to ignore actions/checkout's merge commit. Fallback to push SHA.
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          # We're going to browse all new commits.
          fetch-depth: 0
      - name: Hack setup-python cache
        id: setup_python_hack
        # XXX Create an empty pyproject.toml if this file (or any *requirements.txt) can't be found in repository.
        # This hack fix an issue with setup-python, which ends up with this error in non-Python repos:
        #
        #   Run actions/setup-python@v5.3.0
        #     with:
        #       python-version: 3.12
        #       cache: pip
        #       cache-dependency-path: |
        #         **/pyproject.toml
        #         requirements/*.txt
        #   Installed versions
        #     Successfully set up CPython (3.12.1)
        #   Error: No file in /home/runner/work/awesome-iam/awesome-iam matched to
        #   [requirements/*.txt or **/pyproject.toml], make sure you have checked out the target repository
        #
        # This has been reported at: https://github.com/actions/setup-python/issues/807
        # In the future this might be addressed by: https://github.com/actions/setup-python/pull/762
        # or https://github.com/actions/setup-python/issues/751
        if: hashFiles('**/pyproject.toml', '*requirements.txt', 'requirements/*.txt') == ''
        run: |
          touch ./pyproject.toml
          echo "tmp_deps_file=true" >> "$GITHUB_OUTPUT"
      - uses: actions/setup-python@v5.3.0
        with:
          python-version: "3.12"
          cache: "pip"
          cache-dependency-path: |
            **/pyproject.toml
            *requirements.txt
            requirements/*.txt
      - name: Remove setup-python hack
        if: steps.setup_python_hack.outputs.tmp_deps_file
        run: |
          rm ./pyproject.toml
      - name: Install uv
        run: |
          python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
      - name: Install gha-utils
        run: >
          uv tool install --with-requirements
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt gha-utils
      - name: Project metadata
        id: project-metadata
        env:
          GITHUB_CONTEXT: ${{ toJSON(github) }}
        run: |
          gha-utils --verbosity DEBUG metadata --overwrite "$GITHUB_OUTPUT"

  format-python:
    name: Format Python
    needs:
      - project-metadata
    if: needs.project-metadata.outputs.python_files || needs.project-metadata.outputs.doc_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4.2.2
      - name: Hack setup-python cache
        id: setup_python_hack
        # XXX Create an empty pyproject.toml if this file (or any *requirements.txt) can't be found in repository.
        # This hack fix an issue with setup-python, which ends up with this error in non-Python repos:
        #
        #   Run actions/setup-python@v5.3.0
        #     with:
        #       python-version: 3.12
        #       cache: pip
        #       cache-dependency-path: |
        #         **/pyproject.toml
        #         requirements/*.txt
        #   Installed versions
        #     Successfully set up CPython (3.12.1)
        #   Error: No file in /home/runner/work/awesome-iam/awesome-iam matched to
        #   [requirements/*.txt or **/pyproject.toml], make sure you have checked out the target repository
        #
        # This has been reported at: https://github.com/actions/setup-python/issues/807
        # In the future this might be addressed by: https://github.com/actions/setup-python/pull/762
        # or https://github.com/actions/setup-python/issues/751
        if: hashFiles('**/pyproject.toml', '*requirements.txt', 'requirements/*.txt') == ''
        run: |
          touch ./pyproject.toml
          echo "tmp_deps_file=true" >> "$GITHUB_OUTPUT"
      - uses: actions/setup-python@v5.3.0
        with:
          python-version: "3.12"
          cache: "pip"
          cache-dependency-path: |
            **/pyproject.toml
            *requirements.txt
            requirements/*.txt
      - name: Install uv
        run: |
          python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
      - name: Install Ruff, blacken-docs and autopep8
        run: |
          uv tool install --with-requirements \
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/ruff.txt ruff
          uv tool install --with-requirements \
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/blacken-docs.txt blacken-docs
          uv tool install --with-requirements \
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/autopep8.txt autopep8
      - name: Run autopep8
        if: needs.project-metadata.outputs.python_files
        # Ruff is not wrapping comments: https://github.com/astral-sh/ruff/issues/7414
        # We use autopep8 to only wrap long-line comments:
        #  - E501 is "Try to make lines fit within --max-line-length characters."
        #  - --aggressive is requires to force autopep8 to consider comments.
        # Explicit list of files is provided, as autopep8 is not able to handle find files in ".github" subdirectory.
        run: >
          autopep8 --recursive --in-place --max-line-length 88 --select E501 --aggressive
          ${{ needs.project-metadata.outputs.python_files }}
      - name: Optional Ruff config
        if: needs.project-metadata.outputs.ruff_py_version
        run: |
          cat > ./ruff.toml <<EOF

          target-version = "${{ needs.project-metadata.outputs.ruff_py_version }}"

          EOF
      - name: Generate Ruff config
        run: |
          tee -a ./ruff.toml <<-EOF

          # Extend the pyproject.toml file of the project.
          extend = "./pyproject.toml"

          # Enable preview mode; checks will include unstable rules and fixes.
          # See: https://astral.sh/blog/ruff-v0.1.0#introducing-preview-mode
          preview = true

          fix = true

          # Include fixes that may not retain the original intent of the code.
          # See: https://docs.astral.sh/ruff/linter/#fix-safety
          unsafe-fixes = true

          # Enumerate all fixed violations.
          show-fixes = true

          output-format = "github"


          [lint]
          # D400 - First line should end with a period.
          #   Allows docstrings to end up with any punctuation, not just a period.
          #   See: https://github.com/astral-sh/ruff/issues/1858#issuecomment-1382640623
          # ERA001 - Found commented-out code.
          #   Do not remove commented code, as it might be used for documentation.
          #   See: https://docs.astral.sh/ruff/rules/#eradicate-era
          ignore = ["D400", "ERA001"]


          [format]
          # Enable reformatting of code snippets in docstrings.
          # https://docs.astral.sh/ruff/formatter/#docstring-formatting
          docstring-code-format = true

          EOF
      - name: Print Ruff config
        run: |
          cat ./ruff.toml
      - name: Run Ruff check
        run: |
          ruff check --config ./ruff.toml
      - name: Run Ruff format
        # 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
        run: |
          ruff format --config ./ruff.toml
      - name: Remove temporary Ruff config
        run: |
          rm ./ruff.toml
      - name: Remove setup-python hack
        if: steps.setup_python_hack.outputs.tmp_deps_file
        run: |
          rm ./pyproject.toml
      - name: Run blacken-docs
        # Ignore failing command: blacken-docs returns 1 if it finds a file that needs to be reformatted:
        # https://github.com/adamchainz/blacken-docs/blob/79ef671/blacken_docs.py#L207-L211
        # TODO: replace blacken-docs by ruff. See: https://github.com/astral-sh/ruff/issues/8237
        # https://github.com/astral-sh/ruff/issues/3792
        run: >
          blacken-docs
          --line-length 88
          ${{ needs.project-metadata.outputs.blacken_docs_params }}
          ${{ needs.project-metadata.outputs.doc_files }}
          || true
      - uses: peter-evans/create-pull-request@v7.0.5
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Format Python"
          title: "[autofix] Format Python"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`autofix.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/autofix.yaml) workflow.


            </details>
          labels: "🤖 ci"
          branch: format-python

  sync-uv-lock:
    # XXX Dependabot does not support uv.lock files yet, so this job is doing it.
    # See: https://github.com/astral-sh/uv/issues/2512
    name: Sync uv.lock
    needs:
      - project-metadata
    if: fromJSON(needs.project-metadata.outputs.is_python_project)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4.2.2
      - uses: actions/setup-python@v5.3.0
        with:
          python-version: "3.12"
          cache: "pip"
          cache-dependency-path: |
            **/pyproject.toml
            *requirements.txt
            requirements/*.txt
      - name: Install uv
        run: |
          python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
      - name: Sync uv.lock
        run: |
          uv --no-progress sync --upgrade
      - uses: peter-evans/create-pull-request@v7.0.5
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Sync uv.lock"
          title: "[autofix] Sync `uv.lock`"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          labels: "📦 dependencies"
          branch: sync-uv-lock

  format-markdown:
    name: Format Markdown
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4.2.2
      - name: Hack setup-python cache
        id: setup_python_hack
        # XXX Create an empty pyproject.toml if this file (or any *requirements.txt) can't be found in repository.
        # This hack fix an issue with setup-python, which ends up with this error in non-Python repos:
        #
        #   Run actions/setup-python@v5.3.0
        #     with:
        #       python-version: 3.12
        #       cache: pip
        #       cache-dependency-path: |
        #         **/pyproject.toml
        #         requirements/*.txt
        #   Installed versions
        #     Successfully set up CPython (3.12.1)
        #   Error: No file in /home/runner/work/awesome-iam/awesome-iam matched to
        #   [requirements/*.txt or **/pyproject.toml], make sure you have checked out the target repository
        #
        # This has been reported at: https://github.com/actions/setup-python/issues/807
        # In the future this might be addressed by: https://github.com/actions/setup-python/pull/762
        # or https://github.com/actions/setup-python/issues/751
        if: hashFiles('**/pyproject.toml', '*requirements.txt', 'requirements/*.txt') == ''
        run: |
          touch ./pyproject.toml
          echo "tmp_deps_file=true" >> "$GITHUB_OUTPUT"
      - uses: actions/setup-python@v5.3.0
        with:
          python-version: "3.12"
          cache: "pip"
          cache-dependency-path: |
            **/pyproject.toml
            *requirements.txt
            requirements/*.txt
      - name: Remove setup-python hack
        if: steps.setup_python_hack.outputs.tmp_deps_file
        run: |
          rm ./pyproject.toml
      - name: Install uv
        run: |
          python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
      - name: Install mdformat
        run: >
          uv tool install --with-requirements
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/mdformat.txt mdformat
      - name: Install shfmt
        run: |
          sudo apt install --yes shfmt
      - name: mdformat --version
        run: |
          mdformat --version
      - name: Auto-format Markdown
        run: |
          find ./ -iname "*.md" -exec mdformat "{}" \;
      - name: Markdown fixes for Awesome Lists
        if: startsWith(github.event.repository.name, 'awesome-')
        # Remove forbidden TOC entries
        #     See: https://github.com/sindresorhus/awesome-lint/blob/v0.18.0/rules/toc.js#L15-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
        #
        # TODO: contribute these fixes to mdformat-toc as configurable options.
        run: >
          find ./ -type f \( -name 'readme.md' -or -name 'readme.*.md' \) -print
          -exec gawk -i inplace '!/^- \[(Contents|Contributing|Footnotes)\]\(#.+\)$/{print}' "{}" \;
      - uses: peter-evans/create-pull-request@v7.0.5
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Format Markdown"
          title: "[autofix] Format Markdown"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`autofix.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/autofix.yaml) workflow.


            </details>
          labels: "📚 documentation"
          branch: format-markdown

  format-json:
    name: Format JSON
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4.2.2
      - name: Install jsonlint
        run: |
          sudo npm install --global jsonlint
      - name: Lint
        run: |
          find ./ -type f -name '*.json' -print -exec jsonlint --in-place "{}" \;
      - uses: peter-evans/create-pull-request@v7.0.5
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Format JSON"
          title: "[autofix] Format JSON"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`autofix.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/autofix.yaml) workflow.


            </details>
          labels: "🤖 ci"
          branch: format-json

  check-gitignore:
    name: Does .gitignore exist?
    runs-on: ubuntu-24.04
    outputs:
      exists: ${{ steps.detection.outputs.exists }}
    steps:
      - uses: actions/checkout@v4.2.2
      - id: detection
        # Bare-called reused workflow are not fed with defaults, so force it here.
        run: |
          echo "exists=$( [[ -f '${{ env.gitignore-location }}' ]] && echo 'true' )" >> "$GITHUB_OUTPUT"
      - name: Detection results
        run: |
          echo "Does .gitignore exist at root? ${{ steps.detection.outputs.exists && true || false }}"

  update-gitignore:
    name: Update .gitignore
    needs:
      - check-gitignore
    # Only update gitignore if a file is found at the root of repository.
    if: needs.check-gitignore.outputs.exists
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4.2.2
      - name: Install git-extras
        run: |
          sudo apt update
          sudo apt install --yes git-extras
      - name: Fetch category definitions
        # Update the list manually so the first call below will not introduce these extra log messages:
        #   -----Initial gitignore.io list----
        #   -----Save to /home/runner/.gi_list-----
        run: |
          git ignore-io --update-list
      - name: Generate .gitignore
        run: >
          git ignore-io ${{ inputs.gitignore-extra-categories }}
          certificates
          emacs
          git
          gpg
          linux
          macos
          nohup
          python
          ssh
          vim
          virtualenv
          visualstudiocode
          windows > ${{ env.gitignore-location }}
      - name: Append extra content to .gitignore
        if: inputs.gitignore-extra-content
        run: |
          tee -a ${{ env.gitignore-location }} <<-EOF

          ${{ inputs.gitignore-extra-content }}
          EOF
      - uses: peter-evans/create-pull-request@v7.0.5
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Update .gitignore"
          title: "[autofix] Update `.gitignore`"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`autofix.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/autofix.yaml) workflow.


            </details>
          labels: "🤖 ci"
          branch: update-gitignore