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.'
        required: false
        type: string
        default: ./.gitignore
      gitignore-extra-categories:
        description: 'List of additional categories to add to .gitignore file.'
        type: string
        required: false
      gitignore-extra-content:
        description: 'Additional content to append at the end of the generated .gitignore file.'
        required: false
        type: string
        default: |
          junit.xml
  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 }}
  gitignore-extra-content: >-
    ${{ inputs.gitignore-extra-content == null && 'junit.xml' || inputs.gitignore-extra-content }}


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/
  # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs
  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:
      gitignore_exists: ${{ steps.project-metadata.outputs.gitignore_exists }}
      python_files: ${{ steps.project-metadata.outputs.python_files }}
      json_files: ${{ steps.project-metadata.outputs.json_files }}
      doc_files: ${{ steps.project-metadata.outputs.doc_files }}
      markdown_files: ${{ steps.project-metadata.outputs.markdown_files }}
      is_python_project: ${{ steps.project-metadata.outputs.is_python_project }}
      blacken_docs_params: ${{ steps.project-metadata.outputs.blacken_docs_params }}
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.3
      - name: Run gha-utils metadata
        id: project-metadata
        env:
          GITHUB_CONTEXT: ${{ toJSON(github) }}
        run: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt
          --
          gha-utils 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@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.3
      - 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: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/autopep8.txt
          --
          autopep8 --recursive --in-place --max-line-length 88 --select E501 --aggressive
          ${{ needs.project-metadata.outputs.python_files }}
      - name: Install Ruff
        run: >
          uv tool install --with-requirements
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/ruff.txt ruff
      # --fix : Automatically fix issues that can be fixed.
      # --unsafe-fixes : Include fixes that may not retain the original intent of the code.
      #   See: https://docs.astral.sh/ruff/linter/#fix-safety
      # --show-fixes : Enumerate all fixed violations.
      # --preview : Enable preview mode; checks will include unstable rules and fixes.
      #   See: https://astral.sh/blog/ruff-v0.1.0#introducing-preview-mode
      # 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
      - name: Run Ruff check
        run: >
          ruff check
          --fix
          --unsafe-fixes
          --show-fixes
          --output-format github
          --preview
          --ignore D400,ERA001
      - name: Run Ruff format
        # Additional configuration compared to the "ruff check" step above:
        # future-annotations : Whether to allow rules to add from __future__ import annotations in cases where
        #   this would simplify a fix or enable a new diagnostic.
        #   https://docs.astral.sh/ruff/settings/#lint_future-annotations
        # format.docstring-code-format : Enable reformatting of code snippets in docstrings.
        #   https://docs.astral.sh/ruff/formatter/#docstring-formatting
        # 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 "fix = true"
          --config "unsafe-fixes = true"
          --config "show-fixes = true"
          --output-format github
          --preview
          --config "lint.future-annotations = true"
          --config "format.docstring-code-format = true"
      - 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: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/blacken-docs.txt
          --
          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.8
        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@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.3
      - name: Sync uv.lock
        run: |
          uv --no-progress sync --upgrade
      - uses: peter-evans/create-pull-request@v7.0.8
        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
    needs:
      - project-metadata
    if: needs.project-metadata.outputs.markdown_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.3
      - 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: |
          for file in ${{ needs.project-metadata.outputs.markdown_files }}; do mdformat "$file"; done
      - 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.8
        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
    needs:
      - project-metadata
    if: needs.project-metadata.outputs.json_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - name: Install ESLint with JSON support
        run: |
          npm --no-progress install --no-save "eslint@9.36.0" "@eslint/json@0.13.2"
      - name: Generate ESLint config
        # To debug config, run:
        #   $ npx --no-progress --yes -- eslint --inspect-config
        run: |
          tee -a ./eslint.config.mjs <<-EOF
          // Source: https://github.com/eslint/eslint/blob/main/docs/src/use/configure/configuration-files.md
          import json from "@eslint/json";
          import { defineConfig, globalIgnores } from "eslint/config";

          // VS Code JSON configuration files allow comments but have a ``.json`` extension.
          // https://github.com/microsoft/vscode/blob/8a42946/extensions/configuration-editing/package.json#L41-L59
          const vscodeFiles = [
              ".vscode/*.json",
              ".code-workspace",
              "**/Library/Application Support/Code/**/*.json"
          ];

          export default defineConfig([
              // Reduce noise from common files
              globalIgnores([
                  "package-lock.json",
                  "node_modules/**"
              ]),

              // Lint JSON files
              {
                  files: ["**/*.json"],
                  ignores: vscodeFiles,
                  language: "json/json",
                  plugins: { json },
                  extends: ["json/recommended"],
              },

              // Lint JSONC files
              {
                  files: ["**/*.jsonc"].concat(vscodeFiles),
                  language: "json/jsonc",
                  languageOptions: {
                      allowTrailingCommas: true,
                  },
                  plugins: { json },
                  extends: ["json/recommended"],
              },

              // Lint JSON5 files
              {
                  files: ["**/*.json5"],
                  language: "json/json5",
                  plugins: { json },
                  extends: ["json/recommended"],
              },
          ]);
          EOF
      - name: ESLint version
        run: |
          npx -- eslint --env-info
      - name: Lint
        run: >
          npx -- eslint
          --config ./eslint.config.mjs
          --stats
          --no-error-on-unmatched-pattern
          --fix
          ${{ needs.project-metadata.outputs.json_files }}
      - name: Remove temporary ESLint config and node modules
        run: |
          rm ./eslint.config.mjs
          rm -r ./node_modules/
      - uses: peter-evans/create-pull-request@v7.0.8
        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

  update-gitignore:
    name: Update .gitignore
    needs:
      - project-metadata
    if: fromJSON(needs.project-metadata.outputs.gitignore_exists)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - 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
          node
          nohup
          python
          ssh
          vim
          virtualenv
          visualstudiocode
          windows > "${{ env.gitignore-location }}"
      - name: Append extra content to .gitignore
        if: env.gitignore-extra-content
        run: |
          tee -a "${{ env.gitignore-location }}" <<-EOF

          ${{ env.gitignore-extra-content }}
          EOF
      - uses: peter-evans/create-pull-request@v7.0.8
        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