ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
    inputs:
      hosted_e2e:
        # Underscored on purpose: `inputs.hosted-e2e` is not valid expression
        # syntax (a hyphenated name needs `inputs['hosted-e2e']`).
        description: 'hosted-e2e: auto (obey vars.HOSTED_E2E_DISABLED) | force | skip'
        type: choice
        default: auto
        options: [auto, force, skip]

permissions:
  contents: read

jobs:
  clippy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Rust
        # rustup is pre-installed on GitHub-hosted runners. `rustup show`
        # reads rust-toolchain.toml in the repo root, then installs the
        # pinned channel + listed components if missing. No third-party
        # action dependency needed for toolchain setup.
        run: rustup show

      - name: Cache cargo
        # Swatinem/rust-cache instead of a raw actions/cache of the whole
        # target/ dir: it prunes the cache to dependency artifacts (~5-10x
        # smaller), which keeps this repo's total cache footprint inside
        # GitHub's 10 GiB budget — previously a single main run produced
        # ~8 GiB of caches and every PR save evicted them (cold e2e legs
        # recompiled the full ~275-crate graph each run). save-if restricts
        # writes to main so PR branches restore without churning the budget.
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          save-if: ${{ github.ref == 'refs/heads/main' }}

      - name: Run clippy
        run: cargo clippy --workspace --all-features -- -D warnings

  # Lint the out-of-workspace packaging artifacts for the ecosystems whose setup
  # / CLI-distribution we added: the RubyGems CLI launcher gem + the Bundler
  # plugin gem (Ruby), the Composer CLI launcher (PHP), the Maven Central
  # launcher jar (Java), and the NuGet .NET-tool launcher. Ruby, PHP, Composer,
  # a Temurin JDK + Maven, and the .NET SDK are all pre-installed on the
  # ubuntu-latest runner.
  lint-ecosystems:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Ruby — syntax-check + build the launcher gem and Bundler plugin
        run: |
          ( cd gem/socket-patch && ruby -c lib/socket_patch/launcher.rb && ruby -c exe/socket-patch && gem build socket-patch.gemspec )
          ( cd gem/socket-patch-bundler && ruby -c plugins.rb && gem build socket-patch-bundler.gemspec )
          # The generated-plugin templates are pure Ruby — keep them parseable.
          ruby -c crates/socket-patch-core/src/gem_setup/templates/plugins.rb.tmpl
          ruby -c crates/socket-patch-core/src/gem_setup/templates/gemspec.tmpl

      - name: PHP — lint the Composer launcher + validate composer.json
        # composer.json lives at the repo root (Packagist requires the
        # manifest at the VCS root), so validate runs from there; the
        # launcher script itself stays under composer/socket-patch/bin.
        run: |
          php -l composer/socket-patch/bin/socket-patch
          composer validate --no-check-publish

      - name: Java — build the Maven Central launcher jar
        # `package` exercises compile + jar + the -sources/-javadoc plugins
        # Central mandates; -Dgpg.skip because CI has no release signing key.
        run: mvn --batch-mode --no-transfer-progress -f maven/socket-patch/pom.xml package -Dgpg.skip=true

      - name: .NET — pack the NuGet tool launcher
        # `pack` (not just build) so the PackAsTool/ToolCommandName metadata
        # is validated too. Output goes to RUNNER_TEMP to keep the checkout
        # clean.
        run: dotnet pack nuget/socket-patch -c Release -o "$RUNNER_TEMP/nupkg"

      - name: Shell — shellcheck the curl|sh installer
        # install.sh is the third distribution artifact this job lints; it
        # had no coverage anywhere before the self-update work touched the
        # same surface. shellcheck is pre-installed on ubuntu-latest.
        run: shellcheck --shell=sh scripts/install.sh

      - name: Shell — shellcheck the release scripts
        run: shellcheck scripts/version-sync.sh scripts/bump-version.sh scripts/release-lint.sh

  # Release-readiness gate (scripts/release-lint.sh — the same checks the
  # Release workflow's `version` job runs before publishing anything):
  #   - every PR/push: version coherence — version-sync.sh must be a no-op,
  #     so a hand-edited version in any single packaging site fails CI here
  #     instead of surfacing mid-release;
  #   - PRs that bump the workspace version (release/vX.Y.Z bump PRs): the
  #     full gate — CHANGELOG has a dated, non-empty section for the new
  #     version and the tag doesn't already exist.
  release-readiness:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Lint release readiness
        env:
          EVENT_NAME: ${{ github.event_name }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          if [ "$EVENT_NAME" = "pull_request" ]; then
            # Compare the workspace version against the PR base to detect a
            # version bump. The shallow checkout doesn't have the base
            # commit; fetch just that object.
            git fetch --quiet --depth 1 origin "$BASE_SHA"
            BASE_VERSION="$(git show "$BASE_SHA:Cargo.toml" | grep '^version = ' | head -1 | sed 's/version = "\(.*\)"/\1/')"
            HEAD_VERSION="$(grep '^version = ' Cargo.toml | head -1 | sed 's/version = "\(.*\)"/\1/')"
            if [ "$BASE_VERSION" != "$HEAD_VERSION" ]; then
              echo "Version bump PR detected ($BASE_VERSION -> $HEAD_VERSION); running the full release gate."
              bash scripts/release-lint.sh --tag-check
              exit 0
            fi
          fi
          bash scripts/release-lint.sh --sync-only

  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Rust
        # rustup is pre-installed on GitHub-hosted runners. `rustup show`
        # reads rust-toolchain.toml in the repo root, then installs the
        # pinned channel + listed components if missing. No third-party
        # action dependency needed for toolchain setup.
        run: rustup show

      - name: Cache cargo
        # Swatinem/rust-cache instead of a raw actions/cache of the whole
        # target/ dir: it prunes the cache to dependency artifacts (~5-10x
        # smaller), which keeps this repo's total cache footprint inside
        # GitHub's 10 GiB budget — previously a single main run produced
        # ~8 GiB of caches and every PR save evicted them (cold e2e legs
        # recompiled the full ~275-crate graph each run). save-if restricts
        # writes to main so PR branches restore without churning the budget.
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          save-if: ${{ github.ref == 'refs/heads/main' }}

      - name: Build
        run: cargo build --workspace --all-features

      - name: Install Go (for vexctl)
        # The `vex` subcommand emits OpenVEX documents; tests/e2e_vex.rs
        # validates the output with vexctl when it's on PATH. vexctl is
        # a Go binary distributed via `go install`. Setting up Go here
        # is the cheapest way to give every test job a usable vexctl.
        # Go must be >= 1.24: its linker only began emitting an LC_UUID load
        # command then, and the macOS-latest runner's dyld (Sequoia+) refuses
        # to load a Mach-O binary without one ("missing LC_UUID load command"),
        # so a 1.22-built vexctl crashes on launch and every e2e_vex assertion
        # fails. ubuntu/windows are unaffected, but the matrix shares this pin.
        # SHA pin resolved from `gh api repos/actions/setup-go/git/refs/tags/v6.4.0`.
        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
        with:
          go-version: '1.24'
          cache: false

      - name: Install vexctl
        # `go install` puts the binary in $(go env GOPATH)/bin; surface
        # that path to subsequent steps so `Command::new("vexctl")` in
        # the test resolves. Pinned to a tagged release rather than
        # @latest for reproducibility.
        run: |
          go install github.com/openvex/vexctl@v0.3.0
          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"

      - name: Run tests
        run: cargo test --workspace --all-features

  test-release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Rust
        # rustup is pre-installed on GitHub-hosted runners. `rustup show`
        # reads rust-toolchain.toml in the repo root, then installs the
        # pinned channel + listed components if missing. No third-party
        # action dependency needed for toolchain setup.
        run: rustup show

      - name: Cache cargo
        # Swatinem/rust-cache instead of a raw actions/cache of the whole
        # target/ dir: it prunes the cache to dependency artifacts (~5-10x
        # smaller), which keeps this repo's total cache footprint inside
        # GitHub's 10 GiB budget — previously a single main run produced
        # ~8 GiB of caches and every PR save evicted them (cold e2e legs
        # recompiled the full ~275-crate graph each run). save-if restricts
        # writes to main so PR branches restore without churning the budget.
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          save-if: ${{ github.ref == 'refs/heads/main' }}

      - name: Run tests (release)
        run: cargo test --workspace --all-features --release

  coverage:
    # Code coverage via cargo-llvm-cov (LLVM source-based instrumentation).
    # Reports as a markdown table in the job summary and uploads the raw
    # lcov.info file as a workflow artifact. No threshold gating — this is
    # report-only so contributors get visibility without flaky CI when
    # coverage shifts naturally with test edits.
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Rust
        # `rustup show` installs the rust-toolchain.toml channel + listed
        # components; `rustup component add` adds the llvm-tools-preview
        # bits cargo-llvm-cov needs to merge .profraw files into lcov.
        run: |
          rustup show
          rustup component add llvm-tools-preview

      - name: Install cargo-llvm-cov
        # taiki-e/install-action ships precompiled binaries — much faster
        # than `cargo install` and avoids a per-CI-run compile.
        uses: taiki-e/install-action@65851e10cd6c377f11a60e600abc07cb08643468 # v2.79.3
        with:
          tool: cargo-llvm-cov@0.8.7

      - name: Cache cargo
        # Swatinem/rust-cache instead of a raw actions/cache of the whole
        # target/ dir: it prunes the cache to dependency artifacts (~5-10x
        # smaller), which keeps this repo's total cache footprint inside
        # GitHub's 10 GiB budget — previously a single main run produced
        # ~8 GiB of caches and every PR save evicted them (cold e2e legs
        # recompiled the full ~275-crate graph each run). save-if restricts
        # writes to main so PR branches restore without churning the budget.
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          save-if: ${{ github.ref == 'refs/heads/main' }}

      - name: Run tests with coverage
        # Two-step pattern: `--no-report` runs instrumented tests and
        # collects the raw profile data, then the two `report` calls
        # emit lcov + summary from the same data. Avoids re-running
        # tests twice. The output filename matches the `*.lcov`
        # gitignore pattern so a stray local run can't accidentally
        # commit a 600 KB report.
        #
        # Default features (instead of --all-features) exclude the
        # docker-e2e feature — those tests need Docker images this job
        # doesn't build. The coverage-docker matrix covers them
        # separately, and coverage-merge stitches everything together.
        run: |
          cargo llvm-cov --workspace \
            --no-report
          cargo llvm-cov report --lcov --output-path coverage-host.lcov
          cargo llvm-cov report --summary-only | tee coverage-summary.txt

      - name: Publish coverage summary to job summary
        # Render the per-file table cargo-llvm-cov prints as a fenced
        # block in the GitHub Actions job summary so reviewers don't
        # need to crack open the artifact for a quick look.
        run: |
          {
            echo "## Host coverage summary"
            echo ""
            echo "(In-process tests only. See coverage-merge for the"
            echo "full picture including docker-e2e binary coverage.)"
            echo ""
            echo '```'
            cat coverage-summary.txt
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload host LCOV artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: coverage-host
          path: coverage-host.lcov
          if-no-files-found: error
          retention-days: 30

  coverage-docker:
    # Per-ecosystem coverage for the Docker-driven e2e suite. Mirrors
    # the e2e-docker matrix but builds an instrumented socket-patch
    # binary and mounts it into the container along with a host-
    # visible profraw directory, so the in-container code paths
    # contribute to the lcov merge.
    #
    # Hooks: docker_e2e_<eco>.rs reads SOCKET_PATCH_COV_BIN +
    # SOCKET_PATCH_COV_PROFRAW_DIR. Both unset is the no-op default
    # (used by the e2e-docker matrix above).
    #
    # Pin to ubuntu-22.04 (glibc 2.35) instead of ubuntu-latest
    # (currently 24.04, glibc 2.39). The instrumented binary built
    # here gets mounted into the debian:12-slim test container
    # (glibc 2.36); a binary linked against a newer glibc than the
    # container ships fails to load. ubuntu-22.04's older glibc is
    # the highest base that's forward-compatible with debian:12.
    runs-on: ubuntu-22.04
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        ecosystem: [npm, pypi, gem, cargo, golang, maven, composer, nuget, deno]
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Set up Docker Buildx
        # `driver: docker` makes buildx use the host docker daemon directly
        # rather than running BuildKit in its own container. This is what
        # lets the per-ecosystem image build see the locally-tagged
        # `socket-patch-test-base:latest` from the previous step (with the
        # default container driver, BuildKit runs in a sandbox that cannot
        # see the host daemon's image store and tries to pull base from
        # docker.io, which fails). The trade-off is that `type=gha` cache
        # exports aren't supported under the docker driver — we accept
        # rebuilding the images per job for correctness.
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
        with:
          driver: docker

      - name: Install Rust
        # `rustup show` consumes rust-toolchain.toml; the explicit
        # `component add` covers llvm-tools-preview for cargo-llvm-cov.
        run: |
          rustup show
          rustup component add llvm-tools-preview

      - name: Install cargo-llvm-cov
        uses: taiki-e/install-action@65851e10cd6c377f11a60e600abc07cb08643468 # v2.79.3
        with:
          tool: cargo-llvm-cov@0.8.7

      # No `actions/cache` here intentionally. This job builds Docker
      # images and would be flagged by zizmor's cache-poisoning audit
      # (a PR-poisoned cargo cache could compromise the instrumented
      # binary we mount into the container).

      - name: Build base image
        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
        with:
          context: .
          file: tests/docker/Dockerfile.base
          tags: socket-patch-test-base:latest
          load: true

      - name: Build ${{ matrix.ecosystem }} image
        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
        with:
          context: .
          file: tests/docker/Dockerfile.${{ matrix.ecosystem }}
          tags: socket-patch-test-${{ matrix.ecosystem }}:latest
          load: true

      - name: Build instrumented socket-patch binary
        # Source `cargo llvm-cov show-env` into the current shell so this
        # `cargo build` picks up RUSTC_WRAPPER=cargo-llvm-cov and the
        # same RUSTFLAGS that the subsequent `cargo llvm-cov` test step
        # will use. The bin we build ends up byte-compatible with the
        # test binaries — same source hashes → unified coverage map at
        # report time. Env stays scoped to this step (intentional;
        # cargo llvm-cov manages its own env in the test step).
        run: |
          eval "$(cargo llvm-cov show-env --export-prefix 2>/dev/null)"
          cargo build --bin socket-patch

      - name: Configure docker-e2e coverage hooks
        run: |
          echo "SOCKET_PATCH_COV_BIN=$PWD/target/debug/socket-patch" >> "$GITHUB_ENV"
          # Profraw files from the in-container binary land here.
          # cargo-llvm-cov scans target/ for *.profraw at report time.
          echo "SOCKET_PATCH_COV_PROFRAW_DIR=$PWD/target" >> "$GITHUB_ENV"

      - name: Run ${{ matrix.ecosystem }} Docker e2e test with coverage
        run: |
          # Vendor build-proof capstones ride the same image as their
          # ecosystem's main suite (extend the case as new vendor suites land).
          EXTRA=""
          case "${{ matrix.ecosystem }}" in
            composer) EXTRA="--test docker_e2e_vendor_composer" ;;
            gem)      EXTRA="--test docker_e2e_vendor_gem" ;;
            maven)    EXTRA="--test docker_e2e_vendor_maven" ;;
            nuget)    EXTRA="--test docker_e2e_vendor_nuget" ;;
          esac
          cargo llvm-cov \
            --features docker-e2e \
            --no-report \
            --test docker_e2e_${{ matrix.ecosystem }} $EXTRA

      - name: Generate per-ecosystem lcov
        run: |
          cargo llvm-cov report \
            --lcov \
            --output-path coverage-docker-${{ matrix.ecosystem }}.lcov

      - name: Upload per-ecosystem LCOV artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: coverage-docker-${{ matrix.ecosystem }}
          path: coverage-docker-${{ matrix.ecosystem }}.lcov
          if-no-files-found: error
          retention-days: 30

  coverage-merge:
    # Merge the host coverage and per-ecosystem docker coverage into a
    # single lcov.info. lcov(1) handles the union — same files are
    # summed line-by-line so a line covered by ANY test counts.
    needs: [coverage, coverage-docker]
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Install lcov
        run: sudo apt-get update && sudo apt-get install -y lcov

      - name: Download all coverage artifacts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
        with:
          path: coverage-artifacts
          pattern: coverage-*

      - name: Merge LCOV files
        # `--add-tracefile` is repeated per input. lcov sums hit counts
        # for identical source/line keys, so files covered by both host
        # and docker tests report the higher (union) count.
        # `find` (not bash globstar) for portability across runners.
        run: |
          set -e
          ARGS=()
          while IFS= read -r f; do
            ARGS+=(--add-tracefile "$f")
          done < <(find coverage-artifacts -name '*.lcov' -type f)
          if [ ${#ARGS[@]} -eq 0 ]; then
            echo "No lcov files found to merge" >&2
            exit 1
          fi
          lcov "${ARGS[@]}" --output-file coverage.lcov

      - name: Render summary
        # `lcov --summary` prints a per-file rollup we tee into the job
        # summary, same shape as cargo-llvm-cov's own.
        run: |
          {
            echo "## Coverage (host + docker-e2e merged)"
            echo ""
            echo '```'
            lcov --summary coverage.lcov 2>&1 | tail -20
            echo '```'
            echo ""
            echo "Full merged LCOV uploaded as the \`coverage-lcov\` artifact."
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload merged LCOV artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: coverage-lcov
          path: coverage.lcov
          if-no-files-found: error
          retention-days: 30

  dispatch-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: '20.20.2'

      - name: Run npm dispatch tests
        run: node --test npm/socket-patch/bin/socket-patch.test.mjs

      - name: Setup Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: '3.12.x'

      - name: Run pypi dispatch tests
        run: python pypi/socket-patch/test_dispatch.py

  e2e:
    needs: test
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            suite: e2e_cargo
          - os: ubuntu-latest
            suite: e2e_golang
          - os: ubuntu-latest
            suite: e2e_maven
          - os: ubuntu-latest
            suite: e2e_composer
          - os: ubuntu-latest
            suite: e2e_nuget
          # Host vendor build-proof capstones: fresh-checkout install +
          # revert against the REAL composer/bundler toolchains. `#[ignore]`-
          # gated (the unpinned `test` job skips them); this job pins the
          # toolchain (composer 2, bundler 2.5) below and runs them via
          # `--ignored`. ubuntu-latest only — they need the pinned toolchain,
          # not per-OS coverage.
          - os: ubuntu-latest
            suite: e2e_vendor_composer_build
          - os: ubuntu-latest
            suite: e2e_vendor_gem_build
          # The live-API smoke suites (e2e_npm, e2e_pypi, e2e_gem,
          # e2e_scan) are intentionally NOT in the PR matrix — their
          # `#[ignore]`-gated tests hit the real public proxy at
          # patches-api.socket.dev, which intermittently returns
          # 503 "Service temporarily over capacity" outside this
          # repo's control. Run on demand:
          #
          #   cargo test -p socket-patch-cli --test e2e_npm  -- --ignored
          #   cargo test -p socket-patch-cli --test e2e_pypi -- --ignored
          #   cargo test -p socket-patch-cli --test e2e_gem  -- --ignored
          #   cargo test -p socket-patch-cli --test e2e_scan -- --ignored
          #
          # Same policy for the self-update live smoke (hits real
          # github.com releases; catches asset-naming/redirect/SUMS
          # drift against the published pipeline — most useful right
          # after a release):
          #
          #   cargo test -p socket-patch-cli --test self_update_e2e -- --ignored
          #
          # PR-time coverage for the same code paths comes from the
          # `e2e-docker` matrix below, which runs the same flow
          # against a hermetic wiremock fixture.
          # Safety-hardening e2e suites. The fast non-ignored ones
          # (e2e_safety_lock, e2e_safety_yarn_pnp) run via the
          # standard `test` job above on all three platforms, so no
          # matrix entry is needed for them. The two below need real
          # toolchains and are #[ignore]-gated.
          - os: ubuntu-latest
            suite: e2e_safety_cargo_build
          - os: macos-latest
            suite: e2e_safety_cargo_build
          - os: windows-latest
            suite: e2e_safety_cargo_build
          - os: ubuntu-latest
            suite: e2e_safety_pnpm
          - os: macos-latest
            suite: e2e_safety_pnpm
          # pnpm-on-Windows uses junctions for symlinks and copies
          # (not hardlinks) by default, so the CoW invariant holds
          # vacuously. Test still runs to verify apply doesn't error
          # on Windows — semantic Windows nlink coverage is a
          # follow-up (`std::fs::Metadata` doesn't expose nlink on
          # Windows; needs `GetFileInformationByHandle` via
          # `windows-sys`).
          - os: windows-latest
            suite: e2e_safety_pnpm
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Rust
        # rustup is pre-installed on GitHub-hosted runners. `rustup show`
        # reads rust-toolchain.toml in the repo root, then installs the
        # pinned channel + listed components if missing. No third-party
        # action dependency needed for toolchain setup.
        run: rustup show

      - name: Cache cargo
        # Swatinem/rust-cache instead of a raw actions/cache of the whole
        # target/ dir: it prunes the cache to dependency artifacts (~5-10x
        # smaller), which keeps this repo's total cache footprint inside
        # GitHub's 10 GiB budget — previously a single main run produced
        # ~8 GiB of caches and every PR save evicted them (cold e2e legs
        # recompiled the full ~275-crate graph each run). save-if restricts
        # writes to main so PR branches restore without churning the budget.
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          # Matrix suites otherwise collide on one key: only one of the ~9
          # same-OS legs wins the cache reserve and the rest fail to save.
          key: ${{ matrix.suite }}
          save-if: ${{ github.ref == 'refs/heads/main' }}

      - name: Setup Node.js
        if: matrix.suite == 'e2e_npm' || matrix.suite == 'e2e_scan' || matrix.suite == 'e2e_safety_pnpm'
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: '20.20.2'

      - name: Setup pnpm
        if: matrix.suite == 'e2e_safety_pnpm'
        # Pin the major version so the store layout the test
        # asserts on stays stable. `npm install -g` is the simplest
        # cross-platform install path (works on ubuntu, macos,
        # windows-runners — they all ship a usable npm via
        # actions/setup-node).
        run: npm install -g pnpm@10

      - name: Setup Python
        if: matrix.suite == 'e2e_pypi'
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: '3.12.x'

      - name: Setup Ruby
        if: matrix.suite == 'e2e_gem' || matrix.suite == 'e2e_vendor_gem_build'
        uses: ruby/setup-ruby@319994f95fa847cf3fb3cd3dbe89f6dcde9f178f # v1.295.0
        with:
          # setup-ruby does NOT support `3.2.x` wildcard pinning the
          # way setup-python does — it errors with "Unknown version
          # 3.2.x for ruby on ubuntu-24.04". Pin to an exact patch
          # that's currently in the catalog. If the action drops this
          # patch in the future, bump to whatever's available — see
          # https://github.com/ruby/setup-ruby for the supported list.
          ruby-version: '3.2.10'
          # e2e_vendor_gem_build asserts the pair-edit lock grammar against
          # the spike-verified bundler 2.5 floor; pin it so the host capstone
          # does not ride whatever bundler the runner's Ruby happens to ship.
          bundler: '2.5'
          bundler-cache: false

      - name: Setup PHP
        if: matrix.suite == 'e2e_vendor_composer_build'
        # e2e_vendor_composer_build shells out to a real composer; pin the
        # composer 2 major so the composer.lock grammar the pair edit asserts
        # stays stable across runners.
        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
        with:
          php-version: '8.2'
          tools: composer:2

      - name: Run e2e tests
        run: cargo test -p socket-patch-cli --all-features --test ${{ matrix.suite }} -- --ignored

  # ----------------------------------------------------------------------
  # Docker-driven real-package e2e suite.
  #
  # For each ecosystem, builds the shared base image (multi-stage:
  # Rust → debian + compiled socket-patch) and the per-ecosystem layer,
  # then runs the matching `docker_e2e_<eco>` test binary inside the
  # repo's checkout. Tests install real packages via real package
  # managers and run socket-patch against a wiremock-served fixture —
  # no real Socket API contact. Hermetic, reproducible.
  #
  # Triggered on every PR. The existing `e2e` job above stays for
  # `--ignored` real-API smoke runs (manual / scheduled).
  # ----------------------------------------------------------------------
  e2e-docker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        ecosystem: [npm, pypi, gem, cargo, golang, maven, composer, nuget, deno]
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Set up Docker Buildx
        # `driver: docker` — see the coverage-docker matching step above
        # for the rationale (the per-ecosystem image's `FROM
        # socket-patch-test-base:latest` only resolves when buildx talks
        # directly to the host docker daemon).
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
        with:
          driver: docker

      - name: Install Rust
        run: rustup show

      # No `actions/cache` here intentionally. This job builds Docker
      # images and would be flagged by zizmor's cache-poisoning audit.

      - name: Build base image
        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
        with:
          context: .
          file: tests/docker/Dockerfile.base
          tags: socket-patch-test-base:latest
          load: true

      - name: Build ${{ matrix.ecosystem }} image
        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
        with:
          context: .
          file: tests/docker/Dockerfile.${{ matrix.ecosystem }}
          tags: socket-patch-test-${{ matrix.ecosystem }}:latest
          load: true

      - name: Run ${{ matrix.ecosystem }} Docker e2e test
        # Every ecosystem is unconditionally compiled in; only the
        # `docker-e2e` feature is needed to compile the suite itself.
        run: |
          cargo test -p socket-patch-cli --features docker-e2e --test "docker_e2e_${{ matrix.ecosystem }}"

  # ----------------------------------------------------------------------
  # Experimental `setup`-flow matrix (NON-BLOCKING).
  #
  # For each ecosystem/package manager, drives the full intended flow —
  # prepare deps + a committed patch set, run `socket-patch setup`, run
  # the native install, check whether the patch was applied — plus the
  # negative controls (no setup, empty/wrong/alt patch sets). See
  # tests/setup_matrix/ and scripts/setup-matrix.sh.
  #
  # This is EXPERIMENTAL and intentionally not required to pass yet:
  # `setup` only configures npm-family install hooks today, so most
  # non-npm `baseline_with_setup` cases are EXPECTED to fail (a baseline
  # of what `setup` must eventually support). `continue-on-error: true`
  # means this job never blocks a PR — it must ALSO be left OUT of the
  # repo's required status checks (configured in the branch-protection
  # UI, not in this file). The orchestrator exits non-zero only on a
  # *regression* vs the recorded baseline; the full per-case result set
  # is uploaded as a JSON artifact for inspection.
  # ----------------------------------------------------------------------
  setup-matrix:
    runs-on: ubuntu-latest
    continue-on-error: true
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        ecosystem: [npm, pypi, cargo, gem, golang, maven, composer, nuget, deno]
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Set up Docker Buildx
        # `driver: docker` — the per-ecosystem image's `FROM
        # socket-patch-test-base:latest` only resolves when buildx talks
        # directly to the host docker daemon (see e2e-docker above).
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
        with:
          driver: docker

      - name: Install Rust
        run: rustup show

      - name: Build base image
        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
        with:
          context: .
          file: tests/docker/Dockerfile.base
          tags: socket-patch-test-base:latest
          load: true

      - name: Build ${{ matrix.ecosystem }} image
        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
        with:
          context: .
          file: tests/docker/Dockerfile.${{ matrix.ecosystem }}
          tags: socket-patch-test-${{ matrix.ecosystem }}:latest
          load: true

      - name: Run ${{ matrix.ecosystem }} setup-matrix
        run: scripts/setup-matrix.sh run --ecosystem ${{ matrix.ecosystem }} --out "report-${{ matrix.ecosystem }}.json"

      - name: Upload ${{ matrix.ecosystem }} setup-matrix report
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: setup-matrix-${{ matrix.ecosystem }}
          path: report-${{ matrix.ecosystem }}.json

  # ----------------------------------------------------------------------
  # Hosted-mode production e2e — REQUIRED status check, with a kill switch.
  #
  # Drives `scan --mode hosted` against the REAL production endpoints
  # (patches-api.socket.dev + patch.socket.dev) and the REAL upstream
  # registries, using patches that are actually published on production.
  # Nothing is mocked. Every other hosted-mode capstone in this repo
  # (e2e_redirect_*) points at a wiremock stand-in, so this job is the only
  # thing that would notice production drifting away from the CLI.
  #
  # The suite itself is `#[ignore]`-gated, so it stays OUT of the `test` and
  # `e2e` jobs and only runs where it is explicitly asked for — here.
  #
  # INVARIANTS (this job is registered in branch protection as a required
  # check named exactly `hosted-e2e`):
  #   * NO job-level `if:` — a *skipped* required check is ambiguous to branch
  #     protection and can wedge a PR at "Expected — waiting for status".
  #     The kill switch gates the STEPS, never the job.
  #   * NO `needs:` — an upstream failure would skip this job, same wedge.
  #   * NO matrix and NO rename — the check name must stay `hosted-e2e`.
  #   * NO `continue-on-error` — a bypass must be visible, not invisible.
  # The job ALWAYS runs and ALWAYS reaches success or failure.
  #
  # ESCAPE HATCH — when production is down and this is blocking merges:
  #   Settings -> Secrets and variables -> Actions -> Variables ->
  #     HOSTED_E2E_DISABLED = true
  #   then "Re-run failed jobs" on any blocked PR. `vars` is read at job-run
  #   time, so no commit and no push is needed; the job goes green with a loud
  #   ::warning:: and a BYPASSED banner in the job summary. DELETE the variable
  #   to re-arm. For a one-off: Actions -> CI -> Run workflow ->
  #   hosted_e2e = force (ignore the variable) | skip (bypass this run).
  # ----------------------------------------------------------------------
  hosted-e2e:
    name: hosted-e2e            # registered in branch protection; do not rename
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 30
    concurrency:
      # These are real requests against a real production service — keep it to
      # one run per ref rather than one per push.
      group: hosted-e2e-${{ github.ref }}
      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
    env:
      HOSTED_E2E_DISABLED: ${{ vars.HOSTED_E2E_DISABLED }}
      # The `inputs` context is empty on push/pull_request, so default to auto.
      HOSTED_E2E_MODE: ${{ (github.event_name == 'workflow_dispatch' && inputs.hosted_e2e) || 'auto' }}
    steps:
      - name: Resolve the kill switch
        id: gate
        run: |
          set -eu
          run=true; reason=''
          case "$HOSTED_E2E_MODE" in
            force) reason='workflow_dispatch hosted_e2e=force (kill switch ignored)' ;;
            skip)  run=false; reason='workflow_dispatch hosted_e2e=skip' ;;
            *)     if [ "${HOSTED_E2E_DISABLED:-}" = 'true' ]; then
                     run=false
                     reason='repository variable HOSTED_E2E_DISABLED=true'
                   fi ;;
          esac
          echo "run=$run" >> "$GITHUB_OUTPUT"
          if [ "$run" = 'false' ]; then
            echo "::warning title=hosted-e2e BYPASSED::$reason"
            {
              echo '## :warning: hosted-e2e BYPASSED — no production coverage in this run'
              echo
              echo "Reason: $reason"
              echo
              echo 'Re-arm by deleting the HOSTED_E2E_DISABLED repository variable'
              echo '(Settings -> Secrets and variables -> Actions -> Variables).'
            } >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Checkout
        if: steps.gate.outputs.run == 'true'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Rust
        if: steps.gate.outputs.run == 'true'
        run: rustup show

      - name: Cache cargo
        if: steps.gate.outputs.run == 'true'
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          key: hosted-e2e
          save-if: ${{ github.ref == 'refs/heads/main' }}

      - name: Setup Node.js
        if: steps.gate.outputs.run == 'true'
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          # Node 24, NOT the 20.20.2 the other jobs pin. pnpm 10 imports
          # `node:sqlite` for its store index, which does not exist before
          # Node 22 (and is only stable in 24) — on 20 every `pnpm install`
          # dies with ERR_UNKNOWN_BUILTIN_MODULE. This suite drives real,
          # current package managers against production, so it tracks what
          # users actually run rather than the pin the offline suites need.
          node-version: '24.x'

      - name: Setup npm-family package managers
        if: steps.gate.outputs.run == 'true'
        env:
          # Every corepack shim invocation — including the suite's own
          # `has_command` probes — must be non-interactive, or the probe hangs
          # or exits non-zero and STRICT turns that into a failed leg.
          COREPACK_ENABLE_DOWNLOAD_PROMPT: '0'
        # corepack owns pnpm and both yarn flavors. `corepack enable` alone is
        # not enough: it installs the shims, but `pnpm --version` still fails
        # for a project with no `packageManager` field — exactly the pnpm
        # fixture's shape — because the shim has no version to resolve. The
        # `prepare … --activate` lines set that global default AND pre-download
        # each version, so the first invocation inside a test is not also a
        # network fetch.
        #
        # pnpm must NOT come from `npm install -g` here: corepack has already
        # created its shim at the same path, and npm refuses with EEXIST. Only
        # bun, which corepack does not manage, comes from npm.
        run: |
          set -eu
          corepack enable
          corepack prepare pnpm@10 --activate
          corepack prepare yarn@1.22.22 --activate
          corepack prepare yarn@4.6.0 --activate
          npm install -g bun@1
          node --version
          npm --version
          pnpm --version
          bun --version

      - name: Setup Python + uv
        if: steps.gate.outputs.run == 'true'
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: '3.12.x'

      - name: Install uv
        if: steps.gate.outputs.run == 'true'
        run: python -m pip install --disable-pip-version-check uv && uv --version

      - name: Setup Ruby
        if: steps.gate.outputs.run == 'true'
        uses: ruby/setup-ruby@319994f95fa847cf3fb3cd3dbe89f6dcde9f178f # v1.295.0
        with:
          ruby-version: '3.2.10'
          # The gem hosted rewrite pins into the Gemfile.lock CHECKSUMS
          # section, which `bundle lock --add-checksums` only emits on >= 2.6.
          bundler: '2.6'
          bundler-cache: false

      - name: Setup Go
        if: steps.gate.outputs.run == 'true'
        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
        with:
          go-version: '1.24'
          cache: false

      - name: Run hosted-mode production e2e
        if: steps.gate.outputs.run == 'true'
        env:
          # A required check must never report green on an unexercised leg:
          # STRICT turns the suite's local "toolchain missing" soft-skips into
          # hard failures. Every toolchain it needs is installed above.
          SOCKET_PATCH_HOSTED_E2E_STRICT: '1'
          COREPACK_ENABLE_DOWNLOAD_PROMPT: '0'
        run: |
          set -u
          # The public proxy intermittently returns 503 "Service temporarily
          # over capacity" — that is the documented reason the older live-API
          # suites were pulled from the PR matrix (see the `e2e` job). Retry the
          # whole suite a couple of times before calling it a real failure, so a
          # transient 503 does not block merges through a required check.
          for attempt in 1 2 3; do
            echo "::group::hosted-e2e attempt $attempt"
            cargo test -p socket-patch-cli --test e2e_hosted_production -- \
              --ignored --nocapture --test-threads=4
            status=$?
            echo "::endgroup::"
            if [ "$status" -eq 0 ]; then
              exit 0
            fi
            echo "::warning title=hosted-e2e attempt $attempt failed::retrying"
            sleep $((attempt * 20))
          done
          echo "::error title=hosted-e2e::suite failed on all 3 attempts"
          exit 1
          if-no-files-found: warn