name: CI

# Build, test and lint on both platforms orgo is used from, plus a compiler-floor job.
#
# WHAT THIS CATCHES THAT LOCAL WORK DOES NOT:
#
#   1. Linux. Development happens on macOS, and the two differ where this project is most
#      likely to break: filesystem event paths (the watcher had a real `/var` vs
#      `/private/var` bug on macOS), case-insensitive filenames, and path separators.
#   2. A clean checkout. The oracle tests skip when Emacs is absent and the cache is
#      gitignored, so a machine that has been building all afternoon is not a fair test of
#      what a fresh clone does.
#   3. The MSRV. A stabilised API used without noticing is invisible on a current
#      toolchain and is a build failure for anyone on a distribution compiler.
#
# NOT GATED ON `cargo fmt`. The source is formatted by hand — comment tables, aligned
# match arms, and prose wrapped to fit the argument being made — and rustfmt disagrees
# with most of it. Clippy is the lint that catches defects; fmt would only catch taste.

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

env:
  CARGO_TERM_COLOR: always
  # A failing build should print the error, not a backtrace-shaped wall.
  RUST_BACKTRACE: 1

jobs:
  test:
    name: test (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    strategy:
      # Both platforms report, so a macOS-only failure is distinguishable from a real one.
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1ff72ee08e3cb84d84adba594e0a297990fc1ed3 # stable
        with:
          toolchain: stable
          components: clippy

      - name: Cache cargo
        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2

      # Emacs makes the oracle suite run for real instead of skipping. It is the only
      # reason to trust that output still matches org's own exporter, so it is worth the
      # install minute.
      - name: Install Emacs (Linux)
        if: runner.os == 'Linux'
        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends emacs-nox

      - name: Install Emacs (macOS)
        if: runner.os == 'macOS'
        run: brew install emacs

      - name: Build
        run: cargo build --all-targets --locked

      - name: Test
        run: cargo test --locked

      - name: Clippy
        run: cargo clippy --all-targets --locked -- -D warnings

      # `cargo package` builds the crate exactly as crates.io will receive it, which is
      # how an `exclude` that drops a file the tests need, or a `readme` pointing at a
      # file that was renamed, gets caught here rather than during a release.
      - name: Package
        if: runner.os == 'Linux'
        run: cargo package --locked

      # The documentation site is built by the tool it documents, so a docs page that no
      # longer builds is a product defect. `--strict` fails on broken internal links,
      # which is the failure mode a docs site actually has.
      - name: Build the documentation site
        run: cargo run --locked -- build docs -o docs/_site --strict

  msrv:
    name: minimum supported Rust (1.88)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      # Pinned to the version in Cargo.toml's `rust-version`. When that moves, this moves
      # with it in the same commit — a floor nobody checks is a floor nobody has.
      - name: Install Rust 1.88
        uses: dtolnay/rust-toolchain@1ff72ee08e3cb84d84adba594e0a297990fc1ed3 # stable
        with:
          toolchain: "1.88"

      - name: Cache cargo
        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2

      # Build only. The tests pull in dev-dependencies whose own floors move
      # independently, and chasing those would make this job about someone else's MSRV.
      #
      # The floor is set by dependencies rather than by orgo — its own code compiles on
      # 1.82 — which is precisely why it is checked here instead of reasoned about: a
      # dependency raising its floor is invisible until someone on an older compiler
      # tries to build.
      - name: Build
        run: cargo build --locked