node/.github/workflows/linters.yml

name: Linters

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  push:
    branches:
      - main
      - v[0-9]+.x-staging
      - v[0-9]+.x

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

env:
  PYTHON_VERSION: '3.15'
  NODE_VERSION: lts/*

permissions:
  contents: read

jobs:
  lint-addon-docs:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Use Node.js ${{ env.NODE_VERSION }}
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: Lint addon docs
        run: NODE=$(command -v node) make lint-addon-docs
  lint-cpp:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          # Skip large vendored trees that lint-cpp does not use.
          sparse-checkout: |
            /*
            !/deps/openssl/
            !/deps/v8/
          sparse-checkout-cone-mode: false
      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          allow-prereleases: true
      - name: Lint C/C++ files
        run: make lint-cpp
  format-cpp:
    if: ${{ github.event.pull_request && github.event.pull_request.draft == false && github.base_ref == github.event.repository.default_branch }}
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          # The first parent of the PR merge commit is the base branch commit.
          fetch-depth: 2
          persist-credentials: false
      - name: Use Node.js ${{ env.NODE_VERSION }}
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          allow-prereleases: true
      - name: Format C/C++ files
        run: |
          make format-cpp-build
          # The `make format-cpp` error code is intentionally ignored here
          # because it is irrelevant. We already check if the formatter produced
          # a diff in the next line.
          # Refs: https://github.com/nodejs/node/pull/42764
          CLANG_FORMAT_START=HEAD^ \
            make format-cpp || true
          git --no-pager diff --exit-code && EXIT_CODE="$?" || EXIT_CODE="$?"
          if [ "$EXIT_CODE" != "0" ]
          then
            echo
            echo 'ERROR: Please run:'
            echo
            echo "  CLANG_FORMAT_START="$\(git merge-base HEAD ${GITHUB_BASE_REF}\)" make format-cpp"
            echo
            echo 'to format the commits in your branch.'
            exit "$EXIT_CODE"
          fi
  lint-js-and-md:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Use Node.js ${{ env.NODE_VERSION }}
        id: setup-node
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
          cache-dependency-path: |
            tools/doc/package-lock.json
            tools/eslint/package-lock.json
            tools/lint-md/package-lock.json
      - name: Cache ESLint results
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
        env:
          # ESLint only invalidates its cache on config changes, so the key also
          # covers the custom rules and the files they read.
          cache-prefix: eslint-${{ runner.os }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.mjs', '*/eslint.config_partial.mjs', 'tools/eslint/*', 'tools/eslint-rules/**', 'doc/api/errors.md', 'doc/api/deprecations.md') }}
        with:
          path: .eslintcache
          key: ${{ env.cache-prefix }}-${{ github.sha }}
          restore-keys: ${{ env.cache-prefix }}-
      - name: Lint JavaScript files
        run: |
          set +e
          NODE=$(command -v node) make lint-js ESLINT_CACHE_FLAGS='--cache --cache-strategy content'
          EXIT_CODE="$?"
          if [ "$EXIT_CODE" != "0" ]; then
            echo
            echo 'ERROR: The JavaScript lint validation failed (the errors are logged above).'
            echo '       Please fix the lint errors.'
            if NODE=$(command -v node) make lint-js-fix > /dev/null 2>&1; then
              echo '       Run:'
              echo '          make lint-js-fix'
              echo '       to fix the lint issues.'
              git --no-pager diff
            elif git diff --quiet --exit-code; then
              echo '       None of the issue is auto-fixable, so manual fixes for'
              echo '       all of the issues are required.'
            else
              echo '       Run:'
              echo '          make lint-js-fix'
              echo '       to fix the auto-fixable lint issues.'
              echo '       Note that some manual fixes are also required.'
            fi
            echo
            exit "$EXIT_CODE"
          fi
      - name: Get release version numbers
        if: ${{ github.event.pull_request && github.event.pull_request.base.ref == github.event.pull_request.base.repo.default_branch }}
        id: get-released-versions
        run: ./tools/lint-md/list-released-versions-from-changelogs.mjs >> $GITHUB_OUTPUT
      - name: Lint markdown files
        run: |
          echo "::add-matcher::.github/workflows/remark-lint-problem-matcher.json"
          NODE=$(command -v node) make lint-md ESLINT_CACHE_FLAGS='--cache --cache-strategy content'
        env:
          NODE_RELEASED_VERSIONS: ${{ steps.get-released-versions.outputs.NODE_RELEASED_VERSIONS }}

  lint-py:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          sparse-checkout: |
            /Makefile
            /benchmark/
            /doc/
            /lib/
            /src/node_version.h
            /tools/
            pyproject.toml
            *.py
          sparse-checkout-cone-mode: false
      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          allow-prereleases: true
      - name: Lint Python
        run: |
          make lint-py-build
          make lint-py
  lint-yaml:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          sparse-checkout: |
            /Makefile
            /tools/pip/
            *.yml
            *.yaml
          sparse-checkout-cone-mode: false
      - name: Use Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          allow-prereleases: true
      - name: Lint YAML
        run: |
          make lint-yaml-build || true
          make lint-yaml

  lint-sh:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          sparse-checkout: |
            /tools/lint-sh.mjs
            *.sh
          sparse-checkout-cone-mode: false
      - run: shellcheck -V
      - name: Lint Shell scripts
        run: tools/lint-sh.mjs .
  lint-codeowners:
    if: github.event.pull_request.draft == false
    # cannot use ubuntu-slim here because mszostok/codeowners-validator is dockerized
    # cannot use ubuntu-24.04-arm here because the docker image is x86 only
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - uses: mszostok/codeowners-validator@7f3f5e28c6d7b8dfae5731e54ce2272ca384592f
        with:
          checks: files,duppatterns
  lint-pr-url:
    if: ${{ github.event.pull_request }}
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          fetch-depth: 2
          persist-credentials: false
          sparse-checkout: |
            /tools/lint-pr-url.mjs
            /doc/api/
          sparse-checkout-cone-mode: false
      # We've checked out a merge commit, HEAD^ refers to the base branch.
      - run: git diff HEAD^ HEAD -G"pr-url:" -- "*.md" | ./tools/lint-pr-url.mjs "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
  lint-readme:
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          sparse-checkout: |
            README.md
            /tools/lint-readme-lists.mjs
          sparse-checkout-cone-mode: false
      - name: Get team members if possible
        if: ${{ (github.event.pull_request && github.event.pull_request.base.ref == github.event.pull_request.base.repo.default_branch) || github.event.ref == github.event.repository.default_branch }}
        id: team_members
        run: |
          get_list_members() {
            TEAM="$1"
            QUOTE='"'
            gh api "/orgs/nodejs/teams/$TEAM/members" -X GET -f per_page=100 --jq "map(.login) | ${QUOTE}${TEAM}=\(tojson)${QUOTE}"
          }
          [ -z "$GITHUB_TOKEN" ] || (
            get_list_members "collaborators"
            get_list_members "issue-triage"
            get_list_members "tsc"
          ) >> "$GITHUB_OUTPUT"
        env:
          GITHUB_TOKEN: ${{ secrets.GH_USER_TOKEN }}
      - run: tools/lint-readme-lists.mjs "$TEAMS"
        env:
          TEAMS: ${{ tojson(steps.team_members.outputs) }}