ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

# Cancel superseded runs on the same ref so rapid pushes don't pile up runners.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ── Config / manifest validation ─────────────────────────────────────────
  # This repo has no build system: it's markdown + JSON manifests + shell
  # install scripts. The gate lints the shell and parses every JSON file.
  validate:
    name: Validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false

      # shellcheck is preinstalled on ubuntu-latest runners. Scope to error
      # severity: this gate catches real bugs (unset vars, bad quoting that
      # changes behavior) without failing on stylistic SC2086-class notes.
      - name: Shellcheck (severity=error)
        run: |
          set -euo pipefail
          shellcheck --version
          mapfile -d '' files < <(find . -name '*.sh' \
            -not -path './.git/*' -not -path '*/node_modules/*' -print0)
          if [ ${#files[@]} -eq 0 ]; then
            echo "no shell scripts found"; exit 0
          fi
          printf 'checking: %s\n' "${files[@]}"
          shellcheck --severity=error "${files[@]}"

      # Validate that every committed JSON manifest parses. node is preinstalled
      # on ubuntu-latest. node_modules/dist/.git are excluded.
      - name: Validate JSON
        run: |
          set -euo pipefail
          fail=0
          while IFS= read -r -d '' f; do
            if node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" "$f"; then
              echo "  [ok] $f"
            else
              echo "  [FAIL] invalid JSON: $f"
              fail=1
            fi
          done < <(find . -name '*.json' \
            -not -path './.git/*' -not -path '*/node_modules/*' -not -path '*/dist/*' -print0)
          exit $fail

  # ── Aggregate gate ───────────────────────────────────────────────────────
  # One stable required-status-check context. Fails if validate failed OR was
  # skipped/cancelled, so the job graph can be reshaped without orphaning the
  # required check.
  ci-success:
    name: CI Passed
    if: always()
    needs: [validate]
    runs-on: ubuntu-latest
    steps:
      - name: Verify all required jobs succeeded
        run: |
          echo "validate=${{ needs.validate.result }}"
          [ "${{ needs.validate.result }}" = "success" ]