name: Lint Harness Files

# No trigger-level `paths:` filter, deliberately. A workflow skipped by one
# reports no conclusion at all, and a required check that never reports leaves
# a pull request unable to enter a merge queue and a merge group unable to
# leave it. `merge_group` cannot carry a `paths:` filter in the first place.
#
# The heavier gates push their filtering down into a `changes` job (see
# `.github/scripts/changed-paths.py`). This job is a checkout plus short
# linters, so the whole list is replaced by always running this job. This is
# cheaper than the job that would decide whether to run it. It also closes the
# gap where a harness file outside the old list changed and nothing checked it.
# See docs/ci-merge-queue.md.
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  merge_group:
    types: [checks_requested]
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  # Never cancel a merge-queue run. Its ref is unique per queue entry, so a
  # cancellation here could only come from a mis-keyed group, and the queue
  # would read the cancelled check as a failure and eject the pull request.
  cancel-in-progress: ${{ github.event_name != 'merge_group' }}

permissions:
  contents: read

jobs:
  lint:
    name: Harness files pass lint
    # Checkout receives the short-lived job token. Keep this credential-bearing
    # path on GitHub-hosted capacity during the external-runner pilot.
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
        with:
          persist-credentials: false

      - name: Run linter tests
        run: python3 scripts/lint-harness-files.test.py

      - name: Lint harness files
        run: python3 .github/scripts/lint-harness-files.py --all

      - name: Test documentation catalog
        run: python3 scripts/list-docs.test.py

      - name: Validate documentation catalog
        run: python3 scripts/list-docs.py validate

      - name: Test specification linter
        run: python3 scripts/lint-spec-files.test.py

      - name: Lint specifications
        run: python3 scripts/lint-spec-files.py --all

      - name: Test plugin API claim guard
        run: node --test scripts/validate-plugin-api-claims.test.mjs

      - name: Validate plugin API claims
        run: node scripts/validate-plugin-api-claims.mjs