lint.yaml

---
name: Lint
"on":
  workflow_call:
  push:
    branches:
      - main
  pull_request:

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
    # All jobs depending on project-metadata in this workflow are skipped on prepare-release branch.
    if: github.head_ref != 'prepare-release'
    runs-on: ubuntu-24.04
    outputs:
      is_bot: ${{ steps.project-metadata.outputs.is_bot }}
      python_files: ${{ steps.project-metadata.outputs.python_files }}
      yaml_files: ${{ steps.project-metadata.outputs.yaml_files }}
      workflow_files: ${{ steps.project-metadata.outputs.workflow_files }}
      doc_files: ${{ steps.project-metadata.outputs.doc_files }}
      zsh_files: ${{ steps.project-metadata.outputs.zsh_files }}
      is_python_project: ${{ steps.project-metadata.outputs.is_python_project }}
      mypy_params: ${{ steps.project-metadata.outputs.mypy_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"

  mypy-lint:
    needs:
      - project-metadata
    # Skip linting on prepare-release branch as it points to a tagged URL that does not exist yet.
    if: github.head_ref != 'prepare-release' && needs.project-metadata.outputs.python_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.3
      - name: Install all package dependencies
        run: |
          uv --no-progress sync --frozen --all-extras
      - name: Run Mypy
        # --color-output - Force colorized output as in CI, Mypy defaults to no color in CI.
        run: >
          uv --no-progress run --frozen
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/mypy.txt
          --
          mypy --color-output ${{ needs.project-metadata.outputs.mypy_params }}
          ${{ needs.project-metadata.outputs.python_files }}

  lint-yaml:
    needs:
      - project-metadata
    # Skip linting on prepare-release branch as it points to a tagged URL that does not exist yet.
    # Also skip Dependabot PRs which does not heavily alters YAML files.
    if: >
      github.head_ref != 'prepare-release'
      && (! fromJson(needs.project-metadata.outputs.is_bot))
      && needs.project-metadata.outputs.yaml_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.3
      - name: Run yamllint
        run: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/yamllint.txt
          --
          yamllint --strict --config-data "{rules: {line-length: {max: 120}}}" --format github .

  lint-zsh:
    needs:
      - project-metadata
    # Skip linting on prepare-release branch and bots PRs because they do not alter Zsh files.
    if: >
      github.head_ref != 'prepare-release'
      && (! fromJson(needs.project-metadata.outputs.is_bot))
      && needs.project-metadata.outputs.zsh_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - name: Install Zsh
        run: |
          sudo apt update
          sudo apt install --yes zsh
      - name: Lint
        run: |
          for file in ${{ needs.project-metadata.outputs.zsh_files }}; do zsh --no-exec "$file"; done

  lint-github-action:
    needs:
      - project-metadata
    # Skip linting on prepare-release branch and Dependabot PRs because they do not heavily alters GitHub Actions.
    if: >
      github.head_ref != 'prepare-release'
      && (! fromJson(needs.project-metadata.outputs.is_bot))
      && needs.project-metadata.outputs.workflow_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - name: Install actionlint
        id: install_actionlint
        run: |
          bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) 1.7.8
      - name: Install shellcheck
        run: |
          sudo apt update
          sudo apt install --yes shellcheck
      - name: Install problem matcher
        # Source: https://github.com/rhysd/actionlint/blob/main/docs/usage.md#problem-matchers
        run: >
          curl -fsSL --output ./.github/labeller-file-based.yaml
          https://raw.githubusercontent.com/rhysd/actionlint/refs/tags/v1.7.8/.github/actionlint-matcher.json
      - name: Register problem matcher
        run: |
          echo "::add-matcher::.github/labeller-file-based.yaml"
      - name: Run actionlint
        # XXX actionlint triggers this error:
        #   Error: .github/workflows/release.yaml:198:27:
        #   property "workflow_update_github_pat" is not defined in object type {actions_runner_debug: string;
        #   actions_step_debug: string; github_token: string; pypi_token: string} [expression]
        # See: https://github.com/rhysd/actionlint/issues/148
        run: >
          ${{ steps.install_actionlint.outputs.executable }}
          -color
          -ignore 'property "workflow_update_github_pat" is not defined in .+'

  broken-links:
    needs:
      - project-metadata
    # Skip checks on prepare-release branch as it contains commits in changelog and documentation that points to a tag
    # that does not exist yet, rendering URLs artificially broken. Also skips the merge commit of the prepare-release
    # branch, as if the URLs are good, the tag is created asynchronously by release.yaml:git-tag job. And as a
    # precautionary measure, just skip any event that contains a post-release bump commit.
    # Also skip Dependabot PRs which does not heavily alters URLs.
    if: >
      github.head_ref != 'prepare-release'
      && github.ref != 'refs/heads/prepare-release'
      && (! contains(github.event.commits.*.message, '[changelog] Post-release version bump'))
      && (! fromJson(needs.project-metadata.outputs.is_bot))
      && needs.project-metadata.outputs.doc_files
    runs-on: ubuntu-24.04
    # XXX We need to manually manage the life-cycle of issues created in this job because the create-issue-from-file
    # action blindly creates issues ad-nauseam. See: https://github.com/peter-evans/create-issue-from-file/issues/298 .
    # This was also discussed at: https://github.com/lycheeverse/lychee-action/issues/74#issuecomment-1587089689
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: lycheeverse/lychee-action@v2.7.0
        id: lychee_run
        with:
          fail: false
          args: >
            --hidden
            --suggest
            --insecure
            --no-progress
            --include-fragments
            --exclude-all-private
            ${{ needs.project-metadata.outputs.doc_files }}
      - name: List open issues
        id: open_issues
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: >
          echo "issues=$(
          gh issue list
          --state open
          --author 'github-actions[bot]'
          --json number,title,createdAt )" | tee -a "$GITHUB_OUTPUT"
      - name: Filter issues
        id: issue_groups
        shell: python
        run: |
          import json
          import os
          from operator import itemgetter
          from pathlib import Path

          raw_exit_code = """${{ steps.lychee_run.outputs.exit_code }}"""
          print(f"Lychee exit code: {raw_exit_code!r}")
          exit_code = int(raw_exit_code)
          broken_links_found = False
          if exit_code == 0:
              print("No broken link found: close all open issues.")
          elif exit_code == 2:
              print("Broken links found: create a new issue or update the existing one.")
              broken_links_found = True
          else:
              raise RuntimeError(f"Unexpected Lychee exit code: {exit_code!r}")

          open_issues = json.loads("""${{ steps.open_issues.outputs.issues }}""")
          issue_to_update: int | None = None
          issues_to_close: set[int] = set()

          for issue in sorted(open_issues, key=itemgetter("createdAt"), reverse=True):
              print(f"Processing {issue!r} ...")
              if issue["title"] != "Broken links":
                  print(f"{issue!r} is not a broken links issue, skip it.")
                  continue
              if broken_links_found and not issue_to_update:
                  print(f"{issue!r} is the most recent open issue.")
                  issue_to_update = issue["number"]
              else:
                  print(f"{issue!r} is an old open issue we have to close.")
                  issues_to_close.add(issue["number"])

          output = f"broken_links_found={str(broken_links_found).lower()}\n"
          output += f"issue_to_update={issue_to_update}\n"
          output += f"issues_to_close={' '.join(map(str, issues_to_close))}\n"

          env_file = Path(os.getenv("GITHUB_OUTPUT"))
          env_file.write_text(output)
      - name: Print issue groups
        run: |
          echo "Broken links found: ${{ steps.issue_groups.outputs.broken_links_found }}"
          echo "Issue to update: ${{ steps.issue_groups.outputs.issue_to_update }}"
          echo "Issues to close: ${{ steps.issue_groups.outputs.issues_to_close }}"
      - name: Close old issues
        if: steps.issue_groups.outputs.issues_to_close
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: >
          NUMBER_LIST="${{ steps.issue_groups.outputs.issues_to_close }}";
          for number in $NUMBER_LIST; do
              gh issue close "$number" --comment "${{ steps.issue_groups.outputs.issue_to_update
              && format('Superseded by #{0}.', steps.issue_groups.outputs.issue_to_update)
              || 'No more broken links.' }}";
          done
      - name: Get label
        if: fromJSON(steps.issue_groups.outputs.broken_links_found)
        id: get_label
        run: >
          echo "label=${{ startsWith(github.event.repository.name, 'awesome-')
          && '🩹 fix link' || '📚 documentation' }}" | tee -a "$GITHUB_OUTPUT"
      - name: Create or update issue
        if: fromJSON(steps.issue_groups.outputs.broken_links_found)
        uses: peter-evans/create-issue-from-file@v6.0.0
        with:
          title: "Broken links"
          issue-number: ${{ steps.issue_groups.outputs.issue_to_update }}
          content-filepath: ./lychee/out.md
          labels: ${{ steps.get_label.outputs.label }}

  lint-awesome:
    name: Lint Awesome list
    # Lint only "awesome-*" repositories except "awesome-template".
    # Skip linting on prepare-release branch to align the condition with other jobs, even if it does not really matter
    # here as "awesome-*" repositories don't trigger the release workflow.
    if: >
      startsWith(github.event.repository.name, 'awesome-')
      && github.event.repository.name != 'awesome-template'
      && github.head_ref != 'prepare-release'
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
        with:
          # Fetch all history to please linter's age checks.
          fetch-depth: 0
      - name: Install awesome-lint
        run: |
          npm install awesome-lint@2.2.2
          npx awesome-lint --version
      - name: Run awesome-lint
        run: |
          npx awesome-lint

  check-secrets:
    needs:
      - project-metadata
    # Skip secret checks on prepare-release branch and Dependabot PRs.
    if: github.head_ref != 'prepare-release' && ! fromJson(needs.project-metadata.outputs.is_bot)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2.3.9
        with:
          config-path: .github/gitleaks.toml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}