ci.yml

name: Rust CI

on:
  push:
    branches:
      - '**'
    tags: [ "v*" ]
  pull_request:

env:
  CARGO_TERM_COLOR: always

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
    
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@stable
      with:
        components: rustfmt, clippy
        
    - name: Rust Cache
      uses: Swatinem/rust-cache@v2

    - name: Run cargo fmt check
      run: cargo fmt --all -- --check

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

    - name: Run cargo check
      run: cargo check --workspace
    - name: Run cargo test
      run: cargo test --workspace

    - name: Run cargo test with SIMD
      run: cargo test --workspace --features simd

  # M9-3 (#142): proves the pure-Rust default builds and tests cleanly
  # WITHOUT a C++ toolchain installed. Pinned to ubuntu-latest because the
  # invariant we're testing is build-system gating (build.rs only runs the
  # FreakMatcher C++ compilation when `--features ffi-backend` is set), not
  # platform-specific compilation. Critically, this job does NOT install
  # libclang-dev — if any unconditional bindgen/cc dependency ever leaks
  # into the no-features build path, this job fails.
  pure-rust-build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
      # Submodules deliberately NOT recursive — the pure-Rust path must
      # never touch the WebARKitLib C++ source tree.

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

    - name: Rust Cache
      uses: Swatinem/rust-cache@v2

    - name: Run cargo fmt check (pure-Rust)
      run: cargo fmt --all -- --check

    - name: Run cargo check (no features)
      run: cargo check -p webarkitlib-rs

    - name: Run cargo clippy (no features)
      run: cargo clippy -p webarkitlib-rs -- -D warnings

    - name: Run cargo build (no features)
      run: cargo build -p webarkitlib-rs

    - name: Run cargo test (no features)
      run: cargo test -p webarkitlib-rs

  kpm-build:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
    - uses: actions/checkout@v5
      with:
        submodules: recursive

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

    - name: Install libclang (Linux)
      if: runner.os == 'Linux'
      run: sudo apt-get update && sudo apt-get install -y libclang-dev

    # cache-bin: false avoids caching ~/.cargo/bin. On macOS this job
    # intermittently restored a stale `cargo` shim resolving to
    # `rustup-init`, so `cargo build` was parsed as `rustup-init build`
    # and failed (#134). This job installs no cargo-managed binaries, so
    # disabling bin caching costs nothing while removing the flake.
    - name: Rust Cache
      uses: Swatinem/rust-cache@v2
      with:
        cache-bin: false

    # Strict clippy gate (#180): --all-targets covers examples/tests/benches;
    # --all-features exercises ffi-backend, dual-mode, simd-* paths the
    # default-features check skipped. Ubuntu-only because this is the job
    # that already has submodules + libclang; lints are OS-agnostic so
    # running it on one platform is sufficient.
    - name: Run cargo clippy (strict, --all-targets --all-features)
      if: runner.os == 'Linux'
      run: cargo clippy --workspace --all-targets --all-features -- -D warnings

    - name: Build kpm backend (FFI backend)
      run: cargo build -p webarkitlib-rs --features ffi-backend

    # macOS ffi-backend link verification (#119). PR #117 fixed build.rs to
    # link libc++ (not libstdc++) on Apple targets, but the dual-mode CI step
    # was scoped to --lib, so the integration tests and the generate_patt
    # example were never re-built on macOS after the fix. Build them here to
    # confirm they link against libc++.
    #
    # --no-run (not a full run): this verifies the linker fix only. Actually
    # executing the pose-sensitive integration tests cross-platform is out of
    # scope — that float-drift question is tracked separately in #118, which
    # keeps test_full_pipeline_pose gated to Linux.
    - name: Verify ffi-backend tests + example link (macOS)
      if: runner.os == 'macOS'
      run: |
        cargo test -p webarkitlib-rs \
          --test kpm_regression \
          --test nft_pipeline \
          --test ar2_pinball_io \
          --test cross_stack_parity \
          --features ffi-backend --no-run
        cargo build -p webarkitlib-rs \
          --example generate_patt --features log-helpers,ffi-backend

    # Dual-mode tests run pure-Rust ports against the C++ baseline via the
    # FFI backend (webarkit_cpp_* shims) and assert byte-level parity.
    # Catches regressions that would otherwise only surface in local runs.
    #
    # Scoped to --lib because the dual-mode tests live inside the library
    # (crates/core/src/...) under #[cfg(feature = "dual-mode")] modules.
    # Integration tests in tests/ have unrelated cross-platform issues that
    # are out of scope for this CI step.
    - name: Run dual-mode tests
      run: cargo test -p webarkitlib-rs --lib --features dual-mode

    # Integration tests under tests/ that exercise the C++-backed KPM
    # pipeline (CppFreakMatcher + KPM/AR2 wiring). Until issue #155 these
    # were silently skipped on CI because no job ran integration tests
    # with --features ffi-backend, which let a stale numerical baseline
    # in test_full_pipeline_pose slip through every M9 PR.
    #
    # Ubuntu-only: matches the toolchain the baseline was regenerated on
    # and avoids the unrelated cross-platform issues noted above.
    - name: Run ffi-backend integration tests
      if: runner.os == 'Linux'
      run: |
        cargo test -p webarkitlib-rs \
          --test kpm_regression \
          --test nft_pipeline \
          --test ar2_pinball_io \
          --test cross_stack_parity \
          --features ffi-backend

    # Absolute corner-error gate (#166 Track A). Reprojects each backend's
    # matched-scale reference corners through its homography and asserts
    # that the resulting per-corner error against hand-annotated ground
    # truth doesn't regress beyond the 0.5 px epsilon baselined in
    # crates/core/tests/fixtures/annotated_frames/baseline.json. Unlike
    # the symmetric M9 #152 tier-2 gate, this measures each backend's
    # accuracy independently — catching "Rust got better" and "Rust got
    # worse" as distinct signals.
    #
    # Ubuntu-only for the same reason as the step above: float-noise
    # envelope is per-platform, baseline is captured against one
    # toolchain. If this step fails on CI, options are:
    #   1. Regen the baseline on Linux from the failing run's --nocapture
    #      output (the printed table) and commit it.
    #   2. Widen REGRESSION_EPSILON_PX in absolute_corner_error.rs.
    #
    # See #170 for the known Rust-side run-to-run nondeterminism that
    # constrained today's fixture set to three deterministic frames.
    - name: Run absolute corner-error gate
      if: runner.os == 'Linux'
      run: |
        cargo test -p webarkitlib-rs \
          --test absolute_corner_error \
          --features dual-mode -- --nocapture

  # Miri UB validation (#182) lives in its own workflow at
  # .github/workflows/miri.yml — split out so it can carry a dedicated
  # status badge and run on its own cadence.

  submodule-drift-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
      with:
        submodules: recursive

    - name: Verify submodule SHA matches libraries.json commit
      run: |
        SUB=$(git -C crates/core/third_party/WebARKitLib rev-parse HEAD)
        JSON=$(jq -r '.[] | select(.name=="WebARKitLib") | .source.commit' \
               benchmarks/c_benchmark/libraries.json)
        if [ "$SUB" != "$JSON" ]; then
          echo "::error::Submodule SHA ($SUB) does not match libraries.json commit ($JSON)"
          echo "Run: git -C crates/core/third_party/WebARKitLib rev-parse HEAD"
          echo "Then update benchmarks/c_benchmark/libraries.json accordingly."
          exit 1
        fi
        echo "OK: submodule and libraries.json both pinned at $SUB"

  wasm-build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
    
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@stable
      with:
        targets: wasm32-unknown-unknown

    - name: Install wasm-pack
      run: |
        curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

    - name: Build WASM module (Dual Mode)
      run: npm run build:wasm

    - name: Upload WASM Package
      uses: actions/upload-artifact@v5
      with:
        name: wasm-package
        path: crates/wasm/pkg

  native-example:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@stable

    - name: Run native simple example
      working-directory: crates/core
      run: cargo run --example simple --features log-helpers

  benchmarks:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@stable

    - name: Generate hiro.raw for C benchmark
      working-directory: crates/core
      run: cargo run --example simple --features log-helpers -- ../../benchmarks/data/camera_para.dat ../../benchmarks/data/patt.hiro ../../benchmarks/data/img.jpg

    - name: Install C benchmark deps (svn for bootstrap)
      run: sudo apt-get update && sudo apt-get install -y subversion

    - name: Cache C benchmark downloaded sources
      uses: actions/cache@v4
      with:
        path: benchmarks/c_benchmark/archives
        key: c-bench-archives-${{ runner.os }}-${{ hashFiles('benchmarks/c_benchmark/libraries.json') }}

    # The C baseline pulls external sources (jpeg-9f from ijg.org, WebARKitLib)
    # whose download occasionally fails with TLS/network errors (#204). It only
    # produces an optional comparison log, so keep it NON-BLOCKING: a flake must
    # not fail the benchmarks gate. The required signal is the Rust bench below.
    - name: Build & run C baseline benchmark (non-blocking)
      continue-on-error: true
      run: |
        set -e
        cd benchmarks/c_benchmark
        for attempt in 1 2 3; do
          python ../bootstrap.py --bootstrap-file libraries.json && break
          echo "bootstrap attempt $attempt failed; retrying in 15s..." >&2
          sleep 15
        done
        mkdir -p build && cd build
        cmake .. -DCMAKE_BUILD_TYPE=Release
        make
        cd ..
        mkdir -p ../../target/criterion
        ./build/c_benchmark ../data/camera_para.dat ../data/patt.hiro ../data/hiro.raw 429 317 > ../../target/criterion/c_benchmark.log

    - name: Run Rust benchmarks
      run: cargo bench -p webarkitlib-rs --bench marker_bench
    - name: Upload benchmark reports
      uses: actions/upload-artifact@v5
      with:
        name: benchmark-reports
        path: target/criterion