rust_quality.yml

name: Rust Quality

# Build, lint, and test the Rust bindings crate at rust-bindings/.
#
# The existing Python-side code_quality workflow covers Python tests and
# transitively builds the Rust extension via `maturin develop`, but does
# not run `cargo test` (which covers doctests and any pure-Rust unit
# tests added to the bindings crate).
#
# The bindings' `openjd-*` dependencies come from crates.io at the
# versions pinned in `rust-bindings/Cargo.toml`. There is no sibling
# repository requirement — local-development overrides are documented
# in a commented-out `[patch.crates-io]` block at the bottom of that
# file.

on:
  pull_request:
    branches: [ mainline, release, 'patch_*' ]
  workflow_call:
    inputs:
      branch:
        required: false
        type: string
      tag:
        required: false
        type: string

# Cancel in-progress runs on PR pushes to save CI minutes and avoid
# cache-save races (two concurrent runs trying to save to the same key).
# Matches the pattern used in openjd-rs.
concurrency:
  group: rust-quality-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  CARGO_INCREMENTAL: 0
  CARGO_NET_RETRY: 10
  RUSTUP_MAX_RETRIES: 10
  RUST_BACKTRACE: 1

jobs:
  rust_quality:
    name: Rust (${{ matrix.os }})
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    permissions:
      contents: read

    steps:
      - name: Checkout openjd-model-for-python
        uses: actions/checkout@v7
        with:
          ref: ${{ inputs.branch || inputs.tag || github.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy, rustfmt

      # Include the rustc version in the cache key so that a toolchain
      # upgrade automatically invalidates the target/ cache (stale rustc
      # artifacts are one of the main reasons cache restore-key hits
      # produce slow rebuilds).
      - name: Compute rustc hash
        id: rustc
        shell: bash
        run: echo "hash=$(rustc --version --verbose | sha256sum | cut -c1-16)" >> "$GITHUB_OUTPUT"

      - name: Cache Cargo registry and build artifacts
        id: cache
        uses: actions/cache@v6
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: cargo-${{ matrix.os }}-${{ steps.rustc.outputs.hash }}-${{ hashFiles('Cargo.lock', 'rust-bindings/Cargo.toml') }}
          restore-keys: |
            cargo-${{ matrix.os }}-${{ steps.rustc.outputs.hash }}-
            cargo-${{ matrix.os }}-

      # On a restore-key (non-exact) hit, target/ contains artifacts built
      # against a different Cargo.lock. Cargo will spend a long time
      # scanning fingerprints and discovering staleness, especially on
      # Windows. Starting from an empty target/ with a warm registry cache
      # is faster.
      - name: Discard stale target/ on restore-key-only hit
        if: steps.cache.outputs.cache-hit != 'true'
        shell: bash
        run: rm -rf target

      - name: cargo fmt --check
        run: cargo fmt --manifest-path rust-bindings/Cargo.toml --check

      - name: cargo build
        run: cargo build --manifest-path rust-bindings/Cargo.toml --all-targets

      - name: cargo clippy
        run: cargo clippy --manifest-path rust-bindings/Cargo.toml --all-targets -- -D warnings

      - name: cargo test
        run: cargo test --manifest-path rust-bindings/Cargo.toml

      - name: cargo test --doc
        # Runs separately from `cargo test` above so a docstring regression
        # (e.g. a Python example rustdoc tries to compile as Rust) is
        # clearly visible in the CI log.
        run: cargo test --manifest-path rust-bindings/Cargo.toml --doc

  cargo_doc:
    name: cargo doc -D warnings
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout openjd-model-for-python
        uses: actions/checkout@v7
        with:
          ref: ${{ inputs.branch || inputs.tag || github.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Compute rustc hash
        id: rustc
        shell: bash
        run: echo "hash=$(rustc --version --verbose | sha256sum | cut -c1-16)" >> "$GITHUB_OUTPUT"

      # Restore-only: rust_quality(ubuntu) owns the cache write. Saving
      # from here too would race with that job.
      - name: Restore Cargo cache (read-only)
        uses: actions/cache/restore@v6
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: cargo-ubuntu-latest-${{ steps.rustc.outputs.hash }}-${{ hashFiles('Cargo.lock', 'rust-bindings/Cargo.toml') }}
          restore-keys: |
            cargo-ubuntu-latest-${{ steps.rustc.outputs.hash }}-
            cargo-ubuntu-latest-

      # Catches docstring breakages (broken intra-doc links, stale code
      # blocks, etc.) in pyclass `///` docs.
      - name: cargo doc
        run: cargo doc --manifest-path rust-bindings/Cargo.toml --no-deps
        env:
          RUSTDOCFLAGS: -D warnings

  cargo_deny:
    name: cargo-deny (licenses, advisories, bans, sources)
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout openjd-model-for-python
        uses: actions/checkout@v7
        with:
          ref: ${{ inputs.branch || inputs.tag || github.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Install cargo-deny
        run: cargo install cargo-deny --locked

      # Licenses, bans, and sources apply to every crate we compile,
      # including dev-dependencies, so scan the full graph. Advisories
      # are scoped to the normal dep graph (what actually ships in the
      # extension module).
      - name: cargo deny check licenses, bans, sources
        run: cargo deny --manifest-path rust-bindings/Cargo.toml --config deny.toml check licenses bans sources

      - name: cargo deny check advisories
        run: cargo deny --manifest-path rust-bindings/Cargo.toml --config deny.toml --exclude-dev check advisories

  third_party_licenses:
    name: THIRD-PARTY-LICENSES check
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout openjd-model-for-python
        uses: actions/checkout@v7
        with:
          ref: ${{ inputs.branch || inputs.tag || github.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      # cargo-about renders `about.hbs` using the workspace's Cargo.lock
      # and `about.toml`. The committed `THIRD-PARTY-LICENSES` is shipped
      # with every release, so it must stay in sync with the dependency
      # graph. The `cli` feature is required to actually build the
      # cargo-about binary; without it `cargo install` compiles the crate
      # but emits "none of the package's binaries are available" and
      # installs nothing.
      - name: Install cargo-about
        run: cargo install cargo-about --locked --features cli

      - name: Check THIRD-PARTY-LICENSES is up to date
        run: bash scripts/check_third_party_licenses.sh