name: jouleclaw public surface must stay documented

# Regression-prevention gate for jouleclaw-rs. The brownfield
# onramp (`cargo run -p jouleclaw-brownfield --example
# scan_self`) walks every crate, infers reasons for every
# public function (docs / name pattern / error-handling
# signal), and reports those whose best-available reason is
# Lost. After the 219 → 0 curation pass that closed the
# initial baseline, every new `pub fn` is expected to ship
# with the same minimal `///` doc, OR be downgraded to
# `pub(crate)` if it isn't part of the consumer-visible
# surface. The `--fail-on-lost` flag exits non-zero when any
# public-surface Lost reason remains, so this workflow is a
# permanent safety net against drift.

on:
  pull_request:
    paths:
      - 'jouleclaw/jouleclaw-rs/**'
      - '.github/workflows/jouleclaw-public-surface-documented.yml'
  push:
    branches:
      - main
    paths:
      - 'jouleclaw/jouleclaw-rs/**'
      - '.github/workflows/jouleclaw-public-surface-documented.yml'

jobs:
  scan:
    name: Public-surface audit (jouleclaw-rs)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust toolchain (workspace pin)
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: "1.96"

      - name: Cache cargo registry + target
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            jouleclaw/jouleclaw-rs/target
          key: ${{ runner.os }}-cargo-brownfield-${{ hashFiles('jouleclaw/jouleclaw-rs/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-cargo-brownfield-

      - name: Run brownfield self-scan with --fail-on-lost
        working-directory: jouleclaw/jouleclaw-rs
        run: |
          set -euo pipefail
          if ! cargo run -q -p jouleclaw-brownfield --example scan_self -- --fail-on-lost; then
            echo "::error::Public-surface Lost > 0 — jouleclaw-rs has undocumented public functions."
            echo "::error::Fix by adding a `///` doc comment above each flagged `pub fn`, OR by downgrading to `pub(crate)` if it isn't consumer-visible."
            echo "::error::Run locally with: cargo run -p jouleclaw-brownfield --example scan_self"
            exit 1
          fi