ci.yml

name: CI

# Run on every push and on pull requests targeting master/main.
on:
  push:
    branches: [master, main]
  pull_request:

permissions:
  contents: read

jobs:
  # Run the full test suite with race detection and generate a coverage report.
  # Matrix tests across supported Go versions since this is a library.
  test:
    name: Test (Go ${{ matrix.go-version }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        go-version:
          - "1.21"
          - "1.22"
          - "1.23"
          - "1.24"
          - "1.25"
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v6
        with:
          go-version: ${{ matrix.go-version }}

      # Verify dependency checksums match go.sum (detects corrupted or tampered modules).
      - name: Verify dependencies
        run: go mod verify

      - name: Run tests
        run: go test -race -coverprofile=coverage.out -covermode=atomic ./...

      # Print coverage summary to the CI log (latest Go version only).
      - name: Coverage summary
        if: matrix.go-version == '1.25'
        run: go tool cover -func=coverage.out | tail -1

  # Static analysis: go vet for built-in checks, golangci-lint for extended linting.
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v6
        with:
          go-version-file: go.mod

      - name: Run go vet
        run: go vet ./...

      # golangci-lint v2 runs 50+ linters in a single pass.
      - name: Run golangci-lint
        uses: golangci/golangci-lint-action@v9
        with:
          version: v2.12.2

  # Verify the project compiles on the minimum supported Go version.
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Go
        uses: actions/setup-go@v6
        with:
          go-version-file: go.mod

      - name: Build
        run: go build ./...

  # Scan dependencies for known vulnerabilities using Go's official scanner.
  # See https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck
  govulncheck:
    name: govulncheck
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false

      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod

      - uses: golang/govulncheck-action@v1
        with:
          go-version-file: go.mod