ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
  # Manual re-run, matching every other workflow in this directory. The
  # `coverage` job is the reason: Codecov compares a PR against the most
  # recent *ancestor that has a report*, so a push to main that produces
  # no run leaves every later PR silently baselined against an older
  # commit — the diff table then attributes those intervening commits'
  # coverage to whichever PR is open. That happened at d818e306, which
  # carries zero check-runs, and left PR #1223 compared against a base
  # eight commits behind. Without a dispatch trigger the only remedy is
  # to land another commit on main.
  workflow_dispatch:

# Default to read-only; jobs that need more escalate explicitly.
permissions:
  contents: read

# Cancel in-progress runs for the same ref (e.g. PR pushes) but not on
# main or tag builds — those should always complete.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/') }}

# All `uses:` below are pinned to commit SHAs to eliminate supply-chain
# risk from action-release spoofing. SHAs sourced from the host-identity
# reference workflow for parity; bump via Dependabot.
env:
  CARGO_TERM_COLOR: always
  CARGO_INCREMENTAL: 0
  CARGO_NET_RETRY: 10
  RUSTUP_MAX_RETRIES: 10
  RUSTFLAGS: "-D warnings"
  RUSTDOCFLAGS: "-D warnings"

jobs:
  # Path-filter detection. Outputs `py: true` when the change set
  # touches the bindings crate, the workflow file itself, mise.toml
  # (toolchain pins), or the root Cargo.toml / Cargo.lock (PyO3 /
  # workspace dep bumps must re-run the python-test matrix even on a
  # Rust-only PR title). On Rust-only PRs the python jobs below are
  # `skipped`, which satisfies the `ci` aggregator's `needs:` without
  # being `failure` or `cancelled`.
  changes:
    name: detect path changes
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      py: ${{ steps.filter.outputs.py }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4
        id: filter
        with:
          filters: |
            py:
              - 'big-code-analysis-py/**'
              - '.github/workflows/ci.yml'
              - '.pre-commit-config.yaml'
              - 'Makefile'
              - 'mise.toml'
              - 'Cargo.toml'
              - 'Cargo.lock'

  fmt:
    name: rustfmt
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
          components: rustfmt
      - run: cargo fmt --all -- --check

  clippy:
    name: clippy
    runs-on: ubuntu-latest
    timeout-minutes: 30
    # security-events:write lets the upload-sarif step publish the clippy
    # findings to GitHub code scanning (Security tab + PR annotations).
    # actions:read is required by upload-sarif on private/internal repos
    # (harmless on public ones) and matches codeql.yml's permission set.
    # The workflow-level default is contents:read.
    permissions:
      contents: read
      security-events: write
      actions: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
          components: clippy
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      # clippy-sarif converts cargo's JSON diagnostics into SARIF; sarif-fmt
      # renders the same findings human-readably into the job log. Pinned to
      # 0.8.0 for a reproducible install. taiki-e/install-action has no
      # manifest entry for these crates, so they are compiled from source.
      # Swatinem/rust-cache does not persist ~/.cargo/bin, so cache the built
      # binaries explicitly (keyed on the version pin) to avoid recompiling
      # them — sarif-fmt pulls in syntect — on every run.
      - name: Cache clippy-sarif and sarif-fmt
        id: cache-sarif-tools
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.cargo/bin/clippy-sarif
            ~/.cargo/bin/sarif-fmt
          key: sarif-tools-${{ runner.os }}-0.8.0
      # `--force` because two cache layers own `~/.cargo/bin`: the
      # `Swatinem/rust-cache` step above runs with `cache-bin: true` and
      # restores these two binaries, while the dedicated cache below
      # them can still report a miss (its key is scoped separately, so a
      # branch that has never populated it misses while rust-cache
      # restores from the default branch). `cargo install` then aborts
      # with "binary `clippy-sarif` already exists in destination" and
      # takes the whole clippy job with it. `--force` makes the install
      # idempotent in both states; it is reached only on a miss, so the
      # warm path still skips the build entirely.
      - name: Install clippy-sarif and sarif-fmt
        if: steps.cache-sarif-tools.outputs.cache-hit != 'true'
        run: |
          cargo install clippy-sarif --version 0.8.0 --locked --force
          cargo install sarif-fmt --version 0.8.0 --locked --force
      # Capture clippy's JSON diagnostics to a file (not a pipe) so the SARIF
      # is generated from a complete document — a hard compile-error that
      # aborts clippy mid-stream cannot truncate a piped report.
      # `|| clippy_status=$?` records clippy's real exit code without `set -e`
      # aborting first; the final `exit` re-raises it so this step still
      # fails the build on any warning, exactly as the old `-- -D warnings`
      # invocation did. The SARIF file is written before that exit, so the
      # upload step can still publish it via `if: always()`.
      - name: Run clippy (SARIF)
        run: |
          set -euo pipefail
          clippy_status=0
          cargo clippy --workspace --all-targets --all-features \
            --message-format=json -- -D warnings > clippy.json || clippy_status=$?
          clippy-sarif < clippy.json > rust-clippy-results.sarif
          sarif-fmt < rust-clippy-results.sarif
          exit "$clippy_status"
      # Fork PRs get a read-only GITHUB_TOKEN without security-events scope,
      # so the upload would error; skip it there (and when no SARIF was
      # produced, e.g. clippy never ran). The clippy gate above still fails
      # the build on warnings regardless of this step.
      - name: Upload SARIF to code scanning
        if: always() && hashFiles('rust-clippy-results.sarif') != '' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
        with:
          sarif_file: rust-clippy-results.sarif
          category: clippy

  docs:
    name: rustdoc
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      # Delegate to the Makefile so the strict-doc gate lives in one
      # place. `make doc-check` appends `-D warnings` to the workflow-
      # level RUSTDOCFLAGS rather than replacing it.
      - run: make doc-check
      # Gate-effectiveness test: inject a known broken intra-doc link
      # on a `pub` item and assert `make doc-check` FAILS. Mirrors the
      # `enums-check` sabotage step further down — catches regressions
      # where `-D warnings` is silently dropped from the recipe, the
      # `_pc-doc-check` / `_ci-doc-check` wiring breaks, or rustdoc's
      # broken-intra-doc-links lint gets demoted. The trap restores
      # the file even if the assertion fails. See lesson 21 in
      # docs/development/lessons_learned.md on dedicated-gate parity.
      - name: doc-check gate-effectiveness test
        run: |
          set -eu
          test_file=src/lib.rs
          cp "$test_file" "$test_file.bak"
          trap 'mv "$test_file.bak" "$test_file"' EXIT
          # shellcheck disable=SC2016 # backticks inside the literal rustdoc payload are intentional
          printf '\n/// Sabotage broken link: [`NonExistentDocCheckGateTarget`]\npub fn _doc_check_gate_sabotage() {}\n' >> "$test_file"
          if make doc-check > /tmp/doc-sabotage.log 2>&1; then
            echo "FAIL: doc-check did not reject the broken intra-doc link"
            tail -40 /tmp/doc-sabotage.log
            exit 1
          fi
          # Confirm the failure was caused by *this* sabotage (not some
          # unrelated pre-existing rustdoc warning, a network glitch, or
          # a cargo-side error). Without this check the gate could
          # appear effective while silently skipping the injected
          # payload.
          if ! grep -q 'NonExistentDocCheckGateTarget' /tmp/doc-sabotage.log; then
            echo "FAIL: doc-check exited non-zero but not because of the injected payload"
            tail -40 /tmp/doc-sabotage.log
            exit 1
          fi
          echo "PASS: doc-check correctly rejected the broken intra-doc link"

  test:
    name: test (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    timeout-minutes: 45
    # checks:write lets action-junit-report create the test-report check run;
    # pull-requests:write lets it annotate failing tests on the PR. The
    # workflow-level default is contents:read.
    permissions:
      contents: read
      checks: write
      pull-requests: write
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      # Integration snapshots live in the big-code-analysis-output
      # submodule under tests/repositories/; tests require it.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: recursive
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      - uses: taiki-e/install-action@fa23953489c080190314742a9b907f8e97c6767c # v2.87.10
        with:
          tool: cargo-nextest
      # nextest runs the lib / bins / integration tests and writes the JUnit
      # report to target/nextest/ci/junit.xml (see .config/nextest.toml). It
      # does not run doctests — those are covered by the next step.
      - name: cargo nextest run
        run: cargo nextest run --profile ci --all-features --workspace --locked
      # Doctests, matching the Makefile's `test` / `test-doc` split. nextest
      # cannot run these, so dropping this step would silently stop
      # exercising the workspace's documentation examples.
      - name: cargo test --doc
        run: cargo test --doc --all-features --workspace --locked
      # Publish the JUnit XML as an artifact regardless of outcome — this
      # works even on fork PRs, where the check-run API used below is not
      # available.
      - name: Upload JUnit report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: junit-${{ matrix.os }}
          path: target/nextest/ci/junit.xml
          if-no-files-found: warn
      # Render the JUnit report as a check run + PR annotations + job summary.
      # nextest already gates the job, so fail_on_failure stays off to avoid
      # masking the real exit code under `if: always()`. Skipped on fork PRs,
      # whose read-only token cannot create check runs.
      - name: Publish test report
        if: always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
        uses: mikepenz/action-junit-report@a9170d5795813c01ab4901ffb045b52bab4ab09d # v6.5.0
        with:
          report_paths: target/nextest/ci/junit.xml
          check_name: test report (${{ matrix.os }})
          detailed_summary: true
          include_passed: false
          fail_on_failure: false

  # The exact ancestor-chain assertion (#1122). `Ancestors::checked` keeps
  # only an O(1) approximation on by default, because the exact
  # `chain.last() == node.parent()` form costs Node::parent's O(depth) per
  # node and makes every debug-build walk quadratic. This lane restores it
  # so a walker whose truncate/push bookkeeping desynchronises still fails
  # a build rather than silently feeding predicates a wrong ancestor.
  #
  # ubuntu-only and lib-scoped: the assertion lives in the library's walks,
  # so the per-OS matrix and the CLI / web / integration tiers would re-pay
  # the quadratic cost without covering anything the lib tests do not.
  chain-audit:
    name: chain audit
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      - name: cargo test --lib with --cfg chain_audit
        env:
          # Replaces the workflow-level RUSTFLAGS rather than extending
          # it — a step `env` key shadows the workflow one — so `-D
          # warnings` is repeated here deliberately. Keep the two in
          # step if the workflow-level value ever gains a flag.
          RUSTFLAGS: "-D warnings --cfg chain_audit"
        run: cargo test -p big-code-analysis -p big-code-analysis-ast --lib --all-features --locked

  coverage:
    name: coverage
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      # Coverage instruments and runs the full test suite, so it needs the
      # big-code-analysis-output submodule exactly like the test job above.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: recursive
      # llvm-tools-preview supplies llvm-profdata/llvm-cov for source-based
      # coverage instrumentation.
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
          components: llvm-tools-preview
      # Coverage builds carry -C instrument-coverage, so their artifacts are
      # incompatible with the regular build cache; a distinct key keeps the
      # two from thrashing each other.
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
        with:
          key: coverage
      - uses: taiki-e/install-action@fa23953489c080190314742a9b907f8e97c6767c # v2.87.10
        with:
          tool: cargo-nextest,cargo-llvm-cov
      # nextest is the same runner the `test` job uses, so instrumenting it
      # keeps the coverage numbers aligned with what CI actually exercises.
      # --no-report defers reporting so the same profile data can be emitted
      # in two shapes below (Codecov upload + human-readable job summary).
      #
      # Doctests are intentionally excluded: `cargo llvm-cov --doc` requires
      # nightly, and pairing nightly with the workflow-wide `-D warnings`
      # would red-X CI on unrelated new nightly lints. The `test` job still
      # runs doctests for correctness — only their coverage is omitted.
      - name: Run tests with coverage instrumentation
        run: cargo llvm-cov --no-report nextest --all-features --workspace --locked
      # Codecov's native format preserves region coverage (lcov would drop to
      # line-only).
      #
      # `--workspace` has to be repeated here: the scope flags on the *run*
      # above only decide which tests execute, while `report` scopes the
      # emitted file set to the current package on its own. Without it
      # cargo-llvm-cov builds an `--ignore-filename-regex` naming every other
      # workspace member directory, so the CLI and the web crate were never
      # reported, and after #1376 the whole parse layer left the report too —
      # 103 files that are in fact ~98% covered. Keep the two in step.
      - name: Generate Codecov report
        run: cargo llvm-cov report --workspace --codecov --output-path codecov.json
      # Per-file coverage table in the run's Summary tab, so reviewers can
      # read coverage without leaving GitHub or waiting on the Codecov PR
      # comment.
      - name: Write coverage to job summary
        run: |
          {
            echo '### Coverage'
            echo ''
            echo '```'
            cargo llvm-cov report --workspace
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"
      # token authenticates same-repo runs; fork PRs fall back to Codecov's
      # tokenless upload for public repos (the secret resolves empty there).
      # fail_ci_if_error stays off so a Codecov outage or a credential-less
      # fork PR cannot red-X the merge gate — coverage is informational.
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          files: codecov.json
          flags: rust
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false

  msrv:
    name: msrv (1.94)
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # 1.94
        with:
          toolchain: "1.94"
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      # Build only — MSRV is a compile-time promise; dev-deps may
      # require a newer toolchain.
      - run: cargo build --all-features --workspace --locked

  feature-matrix:
    name: features (${{ matrix.name }})
    runs-on: ubuntu-latest
    # Raised from 30 with #1472: each leg now links and runs a test
    # binary as well as a clippy check build.
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: default (lib)
            flags: -p big-code-analysis
          - name: no-default-features (lib)
            flags: --no-default-features -p big-code-analysis
          # Per-language feature subset (issue #252). Locks in the
          # "minimal grammar set" guarantee: dropping default features
          # and re-enabling only the languages the caller cares about
          # must still produce a working library. `rust` + `typescript`
          # is the canonical subset because it exercises both a
          # single-feature grammar (`tree-sitter-rust`) and a shared-
          # crate grammar (`tree-sitter-typescript`, also used by the
          # `Tsx` variant).
          - name: minimal-langs (lib)
            flags: --no-default-features --features rust,typescript -p big-code-analysis
          # The parse layer builds on its own too (#1376): the three lib
          # legs again, against the crate that actually links the grammars.
          - name: default (ast)
            flags: -p big-code-analysis-ast
          - name: no-default-features (ast)
            flags: --no-default-features -p big-code-analysis-ast
          - name: minimal-langs (ast)
            flags: --no-default-features --features rust,typescript -p big-code-analysis-ast
          - name: default (cli)
            flags: -p big-code-analysis-cli
          - name: no-default-features (cli)
            flags: --no-default-features -p big-code-analysis-cli
          - name: default (web)
            flags: -p big-code-analysis-web
          - name: no-default-features (web)
            flags: --no-default-features -p big-code-analysis-web
          # Single-language legs (issue #1426). `minimal-langs` above is
          # the only subset CI used to build, and `rust` is in it, so a
          # test item gated on a union of languages was measured against
          # a configuration that satisfied nearly every union by
          # accident. Three of these four failed on `main` when the leg
          # was written, each for a different reason, and each reason is
          # invisible to every other leg in this matrix:
          #
          #   c      a union too *narrow* — `PathBuf` / `MetricsOptions`
          #          were gated on `rust`/`python`/`cpp` while a `c`-gated
          #          test used them, so the imports vanished (E0433).
          #   python a union too *wide* — a helper gated on three
          #          languages had one `rust`-gated caller, so it built
          #          unused here (`dead_code`).
          #   tcl    a two-row fixture table whose rows are cfg-gated
          #          collapses to one row (`clippy::single_element_loop`).
          #
          # `go` is the fourth because `.claude/rules/testing.md` names
          # `--features go` as the subset contributors run to verify a
          # feature-gated fixture table: it is the nearest thing to a
          # language outside every union, enabling none of the five
          # (`rust`, `python`, `c`, `cpp`, `tcl`/`irules`) that
          # `tests/api/ast_seam_test.rs` gates its shared items on.
          - name: lang-c (lib)
            flags: --no-default-features --features c -p big-code-analysis
          - name: lang-go (lib)
            flags: --no-default-features --features go -p big-code-analysis
          - name: lang-python (lib)
            flags: --no-default-features --features python -p big-code-analysis
          - name: lang-tcl (lib)
            flags: --no-default-features --features tcl -p big-code-analysis
          # The ast twin, mirroring the lib legs above. The parse layer
          # is clean on all 22 single-language subsets today; this keeps
          # it that way, in the crate where the per-language wiring is
          # densest.
          - name: lang-go (ast)
            flags: --no-default-features --features go -p big-code-analysis-ast
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
          components: clippy
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      # `--all-targets` exercises bins, tests, and examples, so a
      # cfg-gated test file that only compiles under default features does
      # not slip through a partial leg.
      #
      # `clippy … -- -D warnings` rather than `cargo check` (#1426): of
      # the three ways a partial feature set broke the test crate, the
      # third is out of `check`'s reach entirely. E0433 is a hard error
      # either way and `dead_code` is a rustc lint this workflow's
      # top-level `RUSTFLAGS: -D warnings` already promotes, but
      # `single_element_loop` is a clippy lint `check` never runs at all.
      # The `-- -D warnings` is belt-and-braces against that env var
      # being narrowed later. All ten pre-existing legs were verified
      # against the stricter command before it landed.
      #
      # These legs verify that the workspace compiles across feature
      # combinations. Since #1472 they also *run* the suite, in the step
      # below.
      - run: cargo clippy --all-targets ${{ matrix.flags }} --locked -- -D warnings
      - uses: taiki-e/install-action@fa23953489c080190314742a9b907f8e97c6767c # v2.87.10
        with:
          tool: cargo-nextest
      # The one thing a partial feature set breaks that the clippy run
      # above cannot see (#1472): a test gated on the union of its rows
      # must be *absent* when none of those features is enabled, not
      # present and tripping its own `checked > 0` non-vacuity guard.
      # That is a valid build, so nothing warns — it surfaces as a test
      # failure on whichever leg enables none of the rows, which is how
      # #1220 and PR #1221 shipped. `nextest list` answers it without
      # running a test.
      #
      # `--locked` for the same reason the clippy run above carries it:
      # the script forwards every unrecognised argument to `cargo nextest
      # list`, which would otherwise be the one cargo invocation in this
      # job allowed to rewrite `Cargo.lock` instead of failing on it.
      - run: ./utils/check-feature-gates.py ${{ matrix.flags }} --locked
      # Until #1472 these legs compiled the suite and never ran it,
      # because running it failed in the thousands: a test naming
      # `PythonParser` builds without the `python` grammar and then
      # panics in `ParserTrait::new`. Every such test now carries its
      # language's feature, so the leg that drops the grammar drops the
      # test with it and what remains actually passes. This is the half
      # `cargo clippy` cannot see — a gate too *narrow* compiles
      # perfectly and silently stops running.
      #
      # The corpus-dependent binaries are excluded rather than gated
      # away: their fixtures live in the `tests/repositories/`
      # submodules, which this job checks out with `submodules: false`.
      # The `test` job runs them with `submodules: recursive`.
      #
      # Three binaries, not one. The lib's `corpus` target is the
      # obvious one; the CLI's `cli_ux` and `output` targets are the
      # non-obvious ones, because nineteen of their tests resolve
      # `DeepSpeech/stats.py` through `common::corpus_fixture_path()`,
      # which *panics* with the #1171 "integration corpus not checked
      # out" diagnostic rather than skipping. Exact matchers (`=name`)
      # so `output` cannot also swallow the lib's `output_formats`.
      - run: cargo nextest run ${{ matrix.flags }} --locked -E 'not binary(=corpus) and not binary(=cli_ux) and not binary(=output)'

  deny:
    name: cargo-deny
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25 # v2.1.1
        with:
          command: check advisories bans licenses sources

  license-audit:
    name: license-audit
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      - uses: taiki-e/install-action@fa23953489c080190314742a9b907f8e97c6767c # v2.87.10
        with:
          tool: cargo-about@0.8.4
      # Fails if any dep in either binary crate's transitive closure
      # resolves to a license not in `about.toml` `accepted`. Dependabot
      # PRs that introduce an unapproved license now fail here instead of
      # silently slipping into the release.
      # Render to a file (rather than /dev/null) and sanity-check the
      # output. A regression in about.hbs that yielded an empty render
      # would otherwise pass silently — exit 0 from cargo-about does not
      # imply non-empty output.
      - name: Render attribution bundle for big-code-analysis-cli
        run: |
          cargo about generate --locked \
            --manifest-path big-code-analysis-cli/Cargo.toml \
            about.hbs > cli-thirdparty.md
          grep -q '^## Crates' cli-thirdparty.md
          test "$(wc -l < cli-thirdparty.md)" -gt 50
      - name: Render attribution bundle for big-code-analysis-web
        run: |
          cargo about generate --locked \
            --manifest-path big-code-analysis-web/Cargo.toml \
            about.hbs > web-thirdparty.md
          grep -q '^## Crates' web-thirdparty.md
          test "$(wc -l < web-thirdparty.md)" -gt 50

  lint:
    name: lint (make lint)
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # `pull-requests: read` is for the `--compare` step below, which
    # reads this PR's labels live rather than from the event payload.
    permissions:
      contents: read
      pull-requests: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      # `rustfmt` is here for the rustfmt-bail gate, which shells out to
      # it directly. The toolchain action installs the minimal profile,
      # and the gate skips cleanly when rustfmt is missing — so leaving
      # it out would disable the check in CI without failing anything.
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
          components: clippy, rustfmt
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.x"
      # rumdl is the Markdown linter (replaced markdownlint-cli2). The
      # prebuilt binary is not in taiki-e/install-action's manifest, so
      # we fetch the upstream release tarball directly with a pinned
      # SHA256, mirroring the actionlint and checkmake patterns below.
      # Bump RUMDL_SHA256 in lockstep with `RUMDL_VERSION` (and with the
      # `rumdl = …` pin in `mise.toml`). To regenerate the SHA256 after
      # a version bump:
      #   curl -fsSL https://github.com/rvben/rumdl/releases/download/v${RUMDL_VERSION}/rumdl-v${RUMDL_VERSION}-x86_64-unknown-linux-gnu.tar.gz.sha256
      - name: Install rumdl
        env:
          RUMDL_VERSION: "0.2.2"
          RUMDL_SHA256: "d38ad81c51221990d5e0204b4746f8c980a77de235aa875c2f30f02f9a19bb1a"
        run: |
          set -euo pipefail
          url="https://github.com/rvben/rumdl/releases/download/v${RUMDL_VERSION}/rumdl-v${RUMDL_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
          curl -fsSL -o /tmp/rumdl.tgz "$url"
          echo "${RUMDL_SHA256}  /tmp/rumdl.tgz" | sha256sum -c -
          tar -xzf /tmp/rumdl.tgz -C /tmp rumdl
          install -m 0755 /tmp/rumdl /usr/local/bin/rumdl
          rumdl --version
      - uses: taiki-e/install-action@fa23953489c080190314742a9b907f8e97c6767c # v2.87.10
        with:
          tool: taplo-cli@0.10.0,shellcheck@0.10.0,shfmt@3.12.0
      # actionlint 1.7.12's prebuilt binary is not yet in
      # taiki-e/install-action's manifest, and cargo-binstall has no
      # fallback for it. Fetch the upstream release tarball directly,
      # mirroring the checkmake step below. Bump SHA256 in lockstep
      # with `ACTIONLINT_VERSION`.
      - name: Install actionlint
        env:
          ACTIONLINT_VERSION: "1.7.12"
          ACTIONLINT_SHA256: "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
        run: |
          set -euo pipefail
          url="https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
          curl -fsSL -o /tmp/actionlint.tgz "$url"
          echo "${ACTIONLINT_SHA256}  /tmp/actionlint.tgz" | sha256sum -c -
          tar -xzf /tmp/actionlint.tgz -C /tmp actionlint
          install -m 0755 /tmp/actionlint /usr/local/bin/actionlint
          actionlint -version
      # checkmake is not in taiki-e/install-action's manifest; fetch the
      # pinned upstream release binary directly. The SHA256 below comes
      # from the upstream `checksums.txt` published alongside the
      # 0.2.2 release; bump it in lockstep with the version pin.
      - name: Install checkmake
        env:
          CHECKMAKE_VERSION: "0.2.2"
          CHECKMAKE_SHA256: "bedd033b06f2563809855ec2a9950c7a81acea6cd82937fd2f124e2c1c5fc3d5"
        run: |
          set -euo pipefail
          url="https://github.com/mrtazz/checkmake/releases/download/${CHECKMAKE_VERSION}/checkmake-${CHECKMAKE_VERSION}.linux.amd64"
          curl -fsSL -o /tmp/checkmake "$url"
          echo "${CHECKMAKE_SHA256}  /tmp/checkmake" | sha256sum -c -
          install -m 0755 /tmp/checkmake /usr/local/bin/checkmake
          checkmake --version
      - name: make lint
        run: make lint
      # Defensive: `make lint` invokes the snapshot-anchors recipe, but
      # `make lint`'s file-finding helpers depend on a glob fix tracked
      # under #160; until that lands, run the snapshot-anchor gate
      # explicitly so a regression in `make lint` cannot silently disable
      # this check.
      - name: snapshot anchors (explicit)
        run: python3 utils/check-snapshot-anchors.py
      # Run the gate's own unittests as their own explicit step, for the
      # same reason as the rustfmt-bail twin below: a refactor that
      # breaks the script must not be able to disable the gate silently.
      - name: snapshot-anchors self-tests (explicit)
        run: python3 -m unittest -q utils/check-snapshot-anchors-test.py
      # Defensive twin for the rustfmt-bail gate (#1136): a comment
      # inside a match pattern makes rustfmt emit the whole match
      # verbatim while `cargo fmt --check` exits 0, so the fmt job
      # cannot catch it. `make lint` already runs this gate; pinning it
      # here keeps it enforced even if a future refactor drops it from
      # the aggregate recipe.
      - name: rustfmt-bail (explicit)
        run: python3 utils/check-rustfmt-bail.py
      # Run the gate's own unittests as their own explicit step
      # so a refactor that breaks the script can't disable the
      # gate without surfacing the regression in CI.
      - name: rustfmt-bail self-tests (explicit)
        run: python3 -m unittest -q utils/check-rustfmt-bail-test.py
      # Defensive twin to the snapshot-anchors gate above: `make lint`
      # already invokes check-versions, but pinning it here guarantees
      # the lockstep version invariant is enforced even if a future
      # refactor drops it from the aggregate recipe.
      - name: check-versions (explicit)
        run: python3 utils/check-versions.py
      # Defensive twin for the man-page packaging gate (#446): a bca
      # subcommand man page that drops out of the hand-maintained
      # deb/rpm asset lists ships an artifact without its page (the
      # #444 bug class). `make lint` already runs this gate; pinning
      # it here guarantees enforcement even if a future refactor drops
      # it from the aggregate recipe.
      - name: check-manpage-assets (explicit)
        run: python3 utils/check-manpage-assets.py
      # Defensive twin for the man-page drift gate's self-tests
      # (#1249). The gate itself runs in the `manpage` job, which
      # invokes the script directly and so cannot be dropped by a
      # refactor of the `make lint` aggregate — but the tests that
      # prove the gate still catches an untracked page can be, and a
      # gate that has silently stopped gating is indistinguishable
      # from a clean tree. That is the failure this pair exists for.
      - name: check-manpage-drift-test (explicit)
        run: python3 -m unittest -q utils/check-manpage-drift-test.py
      # Defensive twin for the diagnostic-prefix gate (#1199): a
      # capitalised `Warning:` / `Error:` / `Note:` baked into a string
      # literal bypasses the one-helper-per-crate severity ladder and
      # reads as correct in review. Its self-tests run as their own
      # step because a source-scanning gate that stops matching
      # reports a clean tree.
      - name: check-diagnostic-prefix (explicit)
        run: python3 utils/check-diagnostic-prefix.py
      - name: check-diagnostic-prefix self-tests (explicit)
        run: python3 -m unittest -q utils/check-diagnostic-prefix-test.py
      # Defensive twin for the safety-doc pin gate (#1057): the
      # module doc of big-code-analysis-py/src/node.rs is the
      # canonical soundness argument for this workspace's only
      # sanctioned `unsafe` block, and it reasons about a named
      # tree-sitter release. A bump that leaves the literal behind
      # leaves an argument that reads as verified against a crate
      # nobody compiles. Its self-tests run as their own step for the
      # usual reason: a source-scanning gate that stops matching
      # reports a clean tree.
      - name: check-safety-doc-pin (explicit)
        run: python3 utils/check-safety-doc-pin.py
      - name: check-safety-doc-pin self-tests (explicit)
        run: python3 -m unittest -q utils/check-safety-doc-pin-test.py
      # Defensive twin for the grammar-marker-sync gate (#400): bumping
      # the notification-only marker in tree-sitter-{mozjs,mozcpp}/
      # Cargo.toml without re-running the matching generate-*.sh
      # ships a marker that lies about the bundled grammar version.
      # Invokes the script directly (matching the snapshot-anchors
      # and check-versions defensive twins above) so a regression
      # in the `make lint` aggregate cannot silently disable this
      # check.
      - name: grammar-marker-sync (explicit)
        run: python3 utils/check-grammar-marker-sync.py
      # Run the gate's own unittests as their own explicit step
      # so a refactor that breaks the script can't disable the
      # gate without surfacing the regression in CI.
      - name: grammar-marker-sync self-tests (explicit)
        run: python3 -m unittest -q utils/check-grammar-marker-sync-test.py
      # Defensive twin for the workspace-exclusion gate (#1145, #1151):
      # an excluded crate that roots no workspace of its own breaks
      # `cargo fmt --all` inside every git worktree, and an unpinned
      # tree-sitter dependency lets `cargo update` move a grammar
      # silently. `make lint` already runs this gate; invoking it here
      # (matching the twins above) keeps it enforced even if a future
      # refactor drops it from the aggregate recipe.
      - name: check-excluded-manifests (explicit)
        run: python3 utils/check-excluded-manifests.py
      # Run the gate's own unittests as their own explicit step
      # so a refactor that breaks the script can't disable the
      # gate without surfacing the regression in CI.
      - name: check-excluded-manifests self-tests (explicit)
        run: python3 -m unittest -q utils/check-excluded-manifests-test.py
      # The one direction `make lint`'s gates cannot reach (#1478). Both
      # of them compare a `cfg` marker against the derivation; when the
      # two agree and are both wrong, only the previous revision says
      # so. This scans the base branch head too and fails on a test that
      # still exists but stopped being compiled by some single-language
      # build — which nothing else notices, because a gate too *narrow*
      # just drops the test and every leg stays green.
      #
      # Pull requests only: it needs a base revision, and a push to
      # `main` has no meaningful one. `fetch-depth: 1` above leaves the
      # base commit unfetched, so fetch exactly that one object —
      # `git archive` needs the tree, not the history.
      #
      # Narrowing a gate on purpose — the gate *was* too wide and the
      # test really does not need that grammar — drops builds too, and
      # looks identical from here. The escape is the
      # `gate-narrowing-intended` label rather than an in-source marker:
      # this comparison is relative to the base branch head, so a marker
      # would be permanently stale the moment the PR lands and would sit in
      # the tree as a hole nothing can detect. A label leaves the
      # decision on the PR, where a reviewer sees it.
      #
      # The label is read **live**, not from `github.event.pull_request`.
      # That payload is a snapshot taken when the run was queued, so a
      # label applied in response to this very failure is invisible to
      # it — and re-running the job replays the same stale payload, so
      # the documented remedy could never take effect. Measured on
      # PR #1479, where exactly that happened.
      - name: check-test-lang-gates --compare (pull requests)
        if: github.event_name == 'pull_request'
        run: |
          set -euo pipefail
          if gh api "repos/${GITHUB_REPOSITORY}/issues/${PR}/labels" \
               --jq '.[].name' | grep -qx 'gate-narrowing-intended'; then
            echo "gate-narrowing-intended is set: skipping the comparison." \
                 "Narrowing on this PR is declared deliberate."
            exit 0
          fi
          git fetch --depth=1 origin "${BASE_SHA}"
          python3 utils/check-test-lang-gates.py --compare "${BASE_SHA}"
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          PR: ${{ github.event.pull_request.number }}
          GH_TOKEN: ${{ github.token }}
      # Defensive twin for the ruff-lockstep gate (#1230): the
      # ruff-pre-commit `rev:`, `uv.lock`, and the hash-pinned
      # `requirements/dev.txt` export CI installs from must name one
      # version. They had already drifted once, silently, because a
      # comment was the whole mechanism — so this gate in particular
      # must not be able to disappear from the aggregate unnoticed.
      - name: check-ruff-lockstep (explicit)
        run: python3 utils/check-ruff-lockstep.py
      # Run the gate's own unittests as their own explicit step
      # so a refactor that breaks the script can't disable the
      # gate without surfacing the regression in CI.
      - name: check-ruff-lockstep self-tests (explicit)
        run: python3 -m unittest -q utils/check-ruff-lockstep-test.py
      # Defensive twin for the enums-codegen-drift gate (#405):
      # running any grammar regen previously regenerated
      # `src/c_langs_macros/*.rs` to a pre-optimization form
      # silently. The gate diffs codegen output against
      # checked-in files; running it explicitly here guards
      # against `make lint` ever dropping it from the aggregate.
      - name: enums-codegen-drift (explicit)
        run: bash utils/check-enums-codegen-drift.sh
      # Run the gate's own unittests as their own explicit step
      # so a refactor that breaks the script can't disable the
      # gate without surfacing the regression in CI.
      - name: enums-codegen-drift self-tests (explicit)
        run: python3 -m unittest -q utils/check-enums-codegen-drift-test.py
      # Defensive: the prior `make lint` step already runs enums-check
      # as part of its aggregate. Repeating it here protects against a
      # regression to that aggregate (e.g., enums-check accidentally
      # dropped from the `lint` recipe), which is precisely the failure
      # mode #164 was filed against — `[workspace].exclude` had hidden
      # the crate from every workspace-scoped lint until the gate
      # existed. The redundant invocation is cheap (cargo cache is warm)
      # and pins the gate at the workflow level.
      - name: enums-crate check (explicit)
        run: make enums-check
      # Gate-effectiveness test: inject a known unused-variable warning
      # into enums/src/main.rs and assert `make enums-check` FAILS.
      # Catches regressions where RUSTFLAGS is silently dropped, the
      # recipe stops failing on warnings, or `--all-targets` is
      # removed. The trap restores the file even if the assertion
      # fails. This step runs only in CI — locally, a developer who
      # changes the gate should re-verify with the same maneuver.
      - name: enums-check gate-effectiveness test
        run: |
          set -eu
          test_file=enums/src/main.rs
          cp "$test_file" "$test_file.bak"
          trap 'mv "$test_file.bak" "$test_file"' EXIT
          printf '\nfn _enums_check_gate_sabotage() { let unused_x = 1u32; }\n' >> "$test_file"
          if make enums-check > /tmp/sabotage.log 2>&1; then
            echo "FAIL: enums-check did not reject the injected warning"
            tail -40 /tmp/sabotage.log
            exit 1
          fi
          echo "PASS: enums-check correctly rejected the injected warning"

  # Python bindings — lint + type-check. Single Linux job; the heavier
  # cross-platform matrix lives in `python-test` below. Both jobs are
  # gated by `needs.changes.outputs.py == 'true'` so Rust-only PRs skip
  # them entirely (verified by the `ci` aggregator job's tolerance for
  # `skipped` results).
  python-lint:
    name: python-lint
    needs: changes
    if: needs.changes.outputs.py == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      # The bindings tests use the local fixtures under
      # big-code-analysis-py/tests/fixtures/, not the
      # big-code-analysis-output submodule (that's the Rust integration
      # snapshot store). Skip recursive submodules to avoid pulling
      # ~hundreds of MB of unused fixtures and to avoid blocking on a
      # missing/force-pushed submodule SHA.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
        with:
          # Share the cache key with the ubuntu-latest/py3.12 leg of
          # the python-test matrix below — both jobs build the same
          # bindings crate against the same toolchain on the same OS,
          # so a populated target/ from one job warms the other.
          shared-key: "python-bindings-ubuntu-latest-3.12"
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"
          cache: "pip"
      # Create the venv inside big-code-analysis-py/ to match
      # pyrightconfig.json's venvPath="." + venv=".venv" pair (relative
      # to pyrightconfig.json's location). A repo-root venv would leave
      # pyright unable to resolve the maturin-built _native module.
      # requirements/dev.txt is the hash-pinned export of uv.lock's
      # `dev` extra (regenerated by `make py-relock`), so this job
      # installs the exact resolved set `make py-bootstrap` uses
      # locally — no floor-vs-lockfile drift — and `--require-hashes`
      # pins the supply chain (OpenSSF Scorecard Pinned-Dependencies).
      # The ruff-pre-commit `rev:` in .pre-commit-config.yaml is held in
      # lockstep with the ruff version resolved there by the
      # `check-ruff-lockstep` gate in the `lint` job (#1230), so this is
      # no longer something a reviewer has to remember.
      - name: Create venv + install Python toolchain
        working-directory: big-code-analysis-py
        run: |
          python -m venv .venv
          source .venv/bin/activate
          pip install --require-hashes -r requirements/dev.txt
      # maturin develop must precede mypy / pyright so the _native
      # extension is resolvable from the venv. Both type checkers
      # treat the .pyi stub as authoritative, but they still need to
      # import the package without ModuleNotFoundError. Use the
      # default (debug) profile to match the local `make py-typecheck`
      # / `make py-test` invocations — local-CI parity matters more
      # than build speed at the lint job (debug is faster anyway).
      - name: maturin develop
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          maturin develop
      - name: ruff format --check
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          ruff format --check .
      - name: ruff check
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          ruff check .
      - name: mypy --strict
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          mypy --strict python tests examples
      - name: pyright
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          pyright

  # Python bindings — wheel build + pytest, Linux/macOS/Windows
  # × Python 3.12/3.13. The cargo `test` job already builds the
  # bindings crate's Rust side; this job is *additive*, verifying that
  # the maturin-produced wheel actually loads under CPython on each
  # platform (which cargo cannot do).
  python-test:
    name: python-test (${{ matrix.os }}, py${{ matrix.python }})
    needs: changes
    if: needs.changes.outputs.py == 'true'
    runs-on: ${{ matrix.os }}
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python: ["3.12", "3.13"]
    steps:
      # Submodules unnecessary — bindings tests use the local fixtures
      # at big-code-analysis-py/tests/fixtures/. The
      # big-code-analysis-output submodule is for Rust integration
      # snapshots and would otherwise gate this matrix on its
      # availability.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
        with:
          # Per-matrix-leg cache key so Linux / macOS / Windows do not
          # trample each other's target/ directories. The
          # ubuntu-latest+3.12 leg shares its key with python-lint so
          # they reuse each other's build artifacts.
          shared-key: "python-bindings-${{ matrix.os }}-${{ matrix.python }}"
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python }}
          cache: "pip"
      # Cross-platform venv inside big-code-analysis-py/ (matches
      # pyrightconfig.json + the python-lint job + the local Makefile
      # convention). bash on Linux/macOS, PowerShell on Windows.
      # requirements/dev.txt is the hash-pinned export of uv.lock's
      # `dev` extra (regenerated by `make py-relock`): exact resolved
      # versions with `--require-hashes` supply-chain pinning (OpenSSF
      # Scorecard Pinned-Dependencies). It carries a few lint-only
      # tools this job does not run (ruff / mypy / pyright) — the cost
      # of installing them is preferred over maintaining a second,
      # driftable pin set.
      - name: Create venv + install deps (Unix)
        if: runner.os != 'Windows'
        working-directory: big-code-analysis-py
        run: |
          python -m venv .venv
          .venv/bin/pip install --require-hashes -r requirements/dev.txt
      - name: Create venv + install deps (Windows)
        if: runner.os == 'Windows'
        working-directory: big-code-analysis-py
        shell: pwsh
        run: |
          python -m venv .venv
          .venv\Scripts\python.exe -m pip install --require-hashes -r requirements/dev.txt
      # maturin develop uses the default (debug) profile to match the
      # local `make py-test` recipe — same .so layout end-to-end, so
      # local-CI parity issues surface in CI rather than only on a
      # contributor's machine.
      - name: maturin develop (Unix)
        if: runner.os != 'Windows'
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          maturin develop
      - name: maturin develop (Windows)
        if: runner.os == 'Windows'
        working-directory: big-code-analysis-py
        shell: pwsh
        run: |
          .venv\Scripts\Activate.ps1
          maturin develop
      - name: pytest (Unix)
        if: runner.os != 'Windows'
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          python -m pytest --cov=big_code_analysis --cov-report=xml --cov-report=term-missing
      - name: pytest (Windows)
        if: runner.os == 'Windows'
        working-directory: big-code-analysis-py
        shell: pwsh
        run: |
          .venv\Scripts\Activate.ps1
          python -m pytest
      # Python-side coverage measures the pure-Python surface
      # (python/big_code_analysis/_flatten.py + __init__.py); the Rust
      # extension is measured by the `coverage` job. Collected on a single
      # matrix leg because pure-Python coverage is identical across OS /
      # interpreter — uploading from all six legs would only race parallel
      # uploads to Codecov. flags:python keeps it distinct from the Rust
      # upload; fail_ci_if_error stays off for the same reason as the Rust
      # job (informational, fork-PR-safe).
      - name: Upload coverage to Codecov
        if: runner.os == 'Linux' && matrix.python == '3.12'
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          files: big-code-analysis-py/coverage.xml
          flags: python
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false

  # Execute examples/jupyter_quickstart.ipynb end-to-end so a notebook
  # cell that drifts away from the bindings API (renamed kwarg, removed
  # function) breaks CI before it can rot in the documentation. The
  # job stays single-OS / single-Python because the notebook exercises
  # the public Python surface and pandas / matplotlib — both of which
  # the `python-test` matrix already covers across OS / Python combos.
  # A second matrix axis would only re-prove pandas works on Windows.
  #
  # Gated by `needs.changes.outputs.py == 'true'` same as the other
  # python-* jobs; Rust-only PRs see `skipped` (not `failure`) so the
  # aggregator's tolerance for skipped dependents continues to hold.
  python-examples-nbconvert:
    name: python-examples-nbconvert
    needs: changes
    if: needs.changes.outputs.py == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
        with:
          # Share with the python-lint / ubuntu-latest+3.12 python-test
          # legs so the maturin develop step warms from a populated
          # target/ rather than rebuilding from scratch.
          shared-key: "python-bindings-ubuntu-latest-3.12"
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"
          cache: "pip"
      - name: Create venv + install notebook + maturin deps
        working-directory: big-code-analysis-py
        run: |
          python -m venv .venv
          source .venv/bin/activate
          # requirements/examples.txt is the hash-pinned export of
          # uv.lock's [examples] extra (regenerated by `make
          # py-relock`) — installing it directly (no `pip install -e
          # .`) avoids a maturin PEP 517 build on top of the explicit
          # `maturin develop` below, and `--require-hashes` pins the
          # supply chain (OpenSSF Scorecard Pinned-Dependencies).
          pip install --require-hashes -r requirements/examples.txt
      - name: maturin develop
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          maturin develop
      - name: Execute jupyter_quickstart.ipynb
        working-directory: big-code-analysis-py
        run: |
          source .venv/bin/activate
          # `--inplace` writes the executed outputs back to the file,
          # but we deliberately do not commit them — CI just needs the
          # exit code. Using `--to notebook` keeps the format stable;
          # `--ExecutePreprocessor.timeout=120` caps a hung kernel.
          # `MPLBACKEND=Agg` keeps matplotlib headless on the runner.
          MPLBACKEND=Agg jupyter nbconvert \
            --to notebook \
            --execute \
            --inplace \
            --ExecutePreprocessor.timeout=120 \
            examples/jupyter_quickstart.ipynb

  manpage:
    name: man pages up to date
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false
      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
      - name: Regenerate man pages
        run: cargo xtask
      # Fails on every direction the regenerated tree can differ from
      # the committed one — modified, deleted, *and* added pages. The
      # added direction needs `git ls-files --others`: the page xtask
      # writes for a brand-new subcommand is untracked, and `git diff`
      # alone passed green over it until #1249. The check lives in the
      # script rather than inline here so this step and
      # `make manpages-check` cannot drift apart; the `::error::`
      # annotation is emitted by the script when GITHUB_ACTIONS is set.
      - name: Verify no drift
        run: python3 utils/check-manpage-drift.py

  # Single required status check for branch protection — depends on
  # every gating job. Passing this one check guarantees the full matrix
  # passed.
  ci:
    name: ci
    if: always()
    needs:
      - changes
      - fmt
      - clippy
      - docs
      - test
      - chain-audit
      - coverage
      - msrv
      - feature-matrix
      - deny
      - license-audit
      - lint
      - manpage
      - python-lint
      - python-test
      - python-examples-nbconvert
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Fail if any dependency failed or was cancelled
        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
        run: exit 1