Taskfile.yml

version: '3'

vars:
  TOOLS_IMAGE:
    sh: echo "${TOOLS_IMAGE:-ghcr.io/anthropics/buffa/tools:v33.5}"
  CONFORMANCE_IMAGE:
    sh: echo "${CONFORMANCE_IMAGE:-buffa-conformance}"
  # Platforms for the multi-arch tools image push.
  PLATFORMS:
    sh: echo "${PLATFORMS:-linux/amd64,linux/arm64}"
  # Auto-detect the local machine's architecture for single-platform builds.
  LOCAL_PLATFORM:
    sh: echo "linux/$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"

tasks:

  # ── Conformance test runner ─────────────────────────────────────────────

  tools-image:
    desc: >-
      Build the protobuf tools image for all platforms and push to the registry.
      Requires a multi-platform buildx builder — create one with:
        docker buildx create --name multiarch --driver docker-container --use
      Slow (~10–20 min); only needed when the protobuf version changes.
    cmds:
      - docker buildx build
          --platform {{.PLATFORMS}}
          -t {{.TOOLS_IMAGE}}
          --push
          -f conformance/Dockerfile.tools
          .

  tools-image-local:
    desc: >-
      Build the tools image for the local machine only and load it into the
      Docker daemon. Faster than a full multi-platform push; use for testing.
    cmds:
      - docker buildx build
          --platform {{.LOCAL_PLATFORM}}
          -t {{.TOOLS_IMAGE}}
          --load
          -f conformance/Dockerfile.tools
          .

  fetch-protos:
    desc: >-
      Extract .proto files from the tools image into conformance/protos/.
      Required before building the conformance crate outside Docker.
    cmds:
      - scripts/fetch-protos.sh {{.TOOLS_IMAGE}}

  conformance-image:
    desc: >-
      Build the conformance test image (tools runner + our buffa binary).
      The tools image must be present locally or pullable from the registry.
    cmds:
      - docker build
          -t {{.CONFORMANCE_IMAGE}}
          --build-arg TOOLS_IMAGE={{.TOOLS_IMAGE}}
          -f conformance/Dockerfile
          .

  conformance:
    desc: Run the protobuf conformance test suite.
    deps: [conformance-image]
    cmds:
      - docker run --rm {{.CONFORMANCE_IMAGE}}

  conformance-tools-local:
    desc: >-
      Build conformance_test_runner from protobuf source into .local/bin/
      and populate conformance/protos/ — no Docker required. One-time setup
      for conformance-local (slow, ~10-20 min). protoc is not built; install
      it separately (task install-protoc).
    cmds:
      - scripts/build-conformance-tools.sh

  conformance-local:
    desc: >-
      Run the full eight-run conformance suite without Docker, using the
      runner from conformance-tools-local and host cargo builds of the
      std/table/no_std conformance binaries. Requires protoc v30+ on PATH or
      $PROTOC.
    cmds:
      - scripts/run-conformance-local.sh

  conformance-full:
    desc: >-
      Build the tools image locally then run the full conformance suite.
      Use this the first time or after updating the protobuf version.
    deps: [tools-image-local, conformance]

  conformance-failures:
    desc: >-
      Run the conformance suite without a failure list and print all
      failing test names, sorted.  Use this to regenerate
      conformance/known_failures.txt after fixing tests.
    deps: [conformance-image]
    cmds:
      - >-
        docker run --rm
        --entrypoint conformance_test_runner
        {{.CONFORMANCE_IMAGE}}
        /usr/local/bin/buffa-conformance
        2>&1
        | grep '^ERROR'
        | sed 's/^ERROR, test=\([^:]*\):.*/\1/'
        | sort

  # ── Development helpers ─────────────────────────────────────────────────

  install-protoc:
    desc: >-
      Download protoc (version-matched to TOOLS_IMAGE) into .local/ via
      gh release download. Use when the system protoc is too old (e.g. for
      edition 2024 tests). After install, run tests via:
        task test-local  (sets PROTOC for you)
    vars:
      PROTO_VER:
        sh: echo "{{.TOOLS_IMAGE}}" | sed 's/.*:v//'
      # Protobuf release asset naming: linux/osx, and aarch_64 (underscore!).
      PROTOC_OS:
        sh: uname -s | sed 's/Linux/linux/;s/Darwin/osx/'
      PROTOC_ARCH:
        sh: uname -m | sed 's/aarch64/aarch_64/;s/arm64/aarch_64/'
    status:
      # Version-aware: re-downloads if TOOLS_IMAGE is bumped.
      - .local/bin/protoc --version 2>/dev/null | grep -qF "{{.PROTO_VER}}"
    preconditions:
      - sh: gh auth status
        msg: >-
          gh CLI must be authenticated. Run: gh auth login
    cmds:
      - rm -rf .local/bin/protoc .local/include
      - mkdir -p .local/bin
      - gh release download 'v{{.PROTO_VER}}'
          --repo protocolbuffers/protobuf
          --pattern 'protoc-*-{{.PROTOC_OS}}-{{.PROTOC_ARCH}}.zip'
          --output /tmp/protoc-install.zip
          --clobber
      - unzip -oq /tmp/protoc-install.zip -d .local
      - rm -f /tmp/protoc-install.zip
      - chmod +x .local/bin/protoc
      - .local/bin/protoc --version

  install-changie:
    desc: >-
      Download changie (changelog fragment manager) into .local/bin/ via
      gh release download, with checksum verification. The changelog-* tasks
      depend on this, so a direct install is rarely needed.
    vars:
      CHANGIE_VERSION: 1.24.2
      # SHA256 of the upstream release's checksums.txt — pinned in-repo so a
      # replaced or tampered release asset is detected before execution. Bump
      # together with CHANGIE_VERSION (and the matching pin in
      # .github/workflows/ci.yml).
      CHANGIE_CHECKSUMS_SHA256: 79c8ddf317bb0a5443e00ab75fe70f7790849e91846cae68b34e503f78aaecf1
      CHANGIE_OS:
        sh: uname -s | sed 's/Linux/linux/;s/Darwin/darwin/'
      CHANGIE_ARCH:
        sh: uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/'
      CHANGIE_TARBALL: changie_{{.CHANGIE_VERSION}}_{{.CHANGIE_OS}}_{{.CHANGIE_ARCH}}.tar.gz
    status:
      - .local/bin/changie --version 2>/dev/null | grep -qF "v{{.CHANGIE_VERSION}}"
    preconditions:
      - sh: gh auth status
        msg: >-
          gh CLI must be authenticated. Run: gh auth login
    cmds:
      - mkdir -p .local/bin .local/dl
      - gh release download 'v{{.CHANGIE_VERSION}}'
          --repo miniscruff/changie
          --pattern '{{.CHANGIE_TARBALL}}'
          --pattern checksums.txt
          --dir .local/dl --clobber
      - echo '{{.CHANGIE_CHECKSUMS_SHA256}}  checksums.txt' | (cd .local/dl && shasum -a 256 -c -)
      - (cd .local/dl && grep -F '{{.CHANGIE_TARBALL}}' checksums.txt | shasum -a 256 -c -)
      - tar -xzf .local/dl/{{.CHANGIE_TARBALL}} -C .local/bin changie
      - rm -rf .local/dl
      - .local/bin/changie --version

  changelog-new:
    desc: >-
      Create a new changelog fragment under .changes/unreleased/. Prompts
      for kind (Added, Changed, Fixed, etc.) and a multi-line body. Run
      this in your PR instead of editing CHANGELOG.md directly. Pass flags
      after `--` for non-interactive use, e.g.:
        task changelog-new -- -k Fixed -b "One-line body."
    deps: [install-changie]
    cmds:
      - .local/bin/changie new {{.CLI_ARGS}}

  changelog-batch:
    desc: >-
      Roll all .changes/unreleased/ fragments into .changes/<version>.md
      and delete the fragments. Usage: task changelog-batch -- 0.8.0
      Release-time only — run from the cut-release flow, then edit the
      generated section to add any release-notes prose before changelog-merge.
    deps: [install-changie]
    cmds:
      - .local/bin/changie batch {{.CLI_ARGS}}

  changelog-merge:
    desc: >-
      Regenerate CHANGELOG.md from .changes/header.tpl.md and the per-version
      .changes/*.md files. CHANGELOG.md is a generated artifact — never edit
      it directly; edit the source files and re-run this task.
    deps: [install-changie]
    cmds:
      - .local/bin/changie merge

  test-local:
    desc: >-
      Run the workspace test suite using the .local/ protoc (from
      install-protoc). Ensures edition 2024 tests run even when system
      protoc is too old.
    deps: [install-protoc]
    env:
      PROTOC: '{{.ROOT_DIR}}/.local/bin/protoc'
    cmds:
      - cargo test --workspace

  verify:
    desc: >-
      Run the full pre-commit verification pipeline: clippy, markdownlint,
      rustdoc, tests, the arbitrary-feature lint and tests, then conformance
      suite.  Stops on first failure.
    cmds:
      - task: lint
      - task: doc
      - task: test
      - task: test-arbitrary
      - task: conformance

  doc:
    desc: >-
      Build workspace docs with rustdoc warnings as errors — the local
      mirror of the CI "Rustdoc (deny warnings)" step. Protoc precedence:
      an explicit $PROTOC, then the .local/ protoc (from install-protoc;
      re-run that after a protobuf version bump to stay CI-matched), then
      the system protoc (buffa-build's own default). The .local protoc
      lets buffa-test generate its edition 2024 protos even when the
      system protoc is too old for them.
    vars:
      # Not `deps: [install-protoc]` (the test-local pattern): go-task
      # checks preconditions even when a dep's status is satisfied, which
      # would make `task verify` demand gh auth on every run.
      DOC_PROTOC:
        sh: |
          if [ -n "${PROTOC:-}" ]; then echo "$PROTOC"
          elif [ -x '{{.ROOT_DIR}}/.local/bin/protoc' ]; then echo '{{.ROOT_DIR}}/.local/bin/protoc'
          else echo protoc
          fi
    cmds:
      # Command-line assignments rather than task-level `env:` — the OS
      # environment outranks `env:`, so an exported RUSTDOCFLAGS would
      # silently drop -D warnings (and an exported-empty PROTOC would
      # break the build).
      - RUSTDOCFLAGS='-D warnings' PROTOC='{{.DOC_PROTOC}}'
        cargo doc --workspace --all-features --no-deps

  test:
    desc: Run the workspace test suite.
    cmds:
      - cargo test --workspace

  test-arbitrary:
    desc: >-
      Lint and test buffa-test with its `arbitrary` feature on. Local mirror
      of the two CI steps named "(buffa-test, arbitrary)".
    cmds:
      - cargo clippy -p buffa-test --all-targets --features arbitrary -- -D warnings
      - cargo test -p buffa-test --features arbitrary --lib --tests

  test-codegen:
    desc: >-
      Run codegen integration tests that invoke protoc on real .proto files.
      Requires protoc on PATH (install via your package manager or set PROTOC).
    preconditions:
      - sh: which protoc || which $PROTOC
        msg: >-
          protoc is required for codegen integration tests.
          Install it via your package manager:
            brew install protobuf    # macOS
            apt install protobuf-compiler  # Debian/Ubuntu
            nix-env -i protobuf      # Nix
          Or set PROTOC=/path/to/protoc
    cmds:
      - cargo test -p buffa-codegen --test codegen_integration

  lint:
    desc: Run rustfmt check, clippy (all targets, warnings as errors), and markdownlint.
    cmds:
      - cargo fmt --all --check
      - cargo clippy --workspace --all-targets -- -D warnings
      - task: lint-md

  lint-md:
    desc: >-
      Run markdownlint over all Markdown files using .markdownlint.json.
      Pinned to markdownlint-cli@0.47.0 for deterministic results; npx
      caches the package after first run.
    preconditions:
      - sh: which npx
        msg: >-
          npx is required for markdownlint. Install Node.js:
            brew install node        # macOS
            apt install nodejs npm   # Debian/Ubuntu
    cmds:
      - npx --yes markdownlint-cli@0.47.0 '**/*.md' --ignore target --ignore .claude

  check-publish-coverage:
    desc: >-
      Verify .github/publish-order.txt lists exactly the publishable crates in
      the workspace, each after the workspace crates it depends on. Run after
      adding a crate or a dependency between crates; CI runs this on every PR.
    cmds:
      - ./scripts/check-publish-coverage.sh

  check-keywords:
    desc: >-
      Compare is_rust_keyword in buffa-codegen against the current Rust keyword
      list fetched from the rust-lang/rust stable branch on GitHub.
      Requires internet access; no local toolchain configuration needed.
    cmds:
      - python3 scripts/check-keywords.py

  # ── Fuzz testing ─────────────────────────────────────────────────────

  fuzz:
    desc: >-
      Run a single fuzz target. Requires nightly Rust and cargo-fuzz.
      Usage: task fuzz -- <target> [-- libfuzzer-args]
      Targets: decode_proto3, decode_proto2, decode_wkt, json_roundtrip,
      encode_proto3, wkt_json_strings
    cmds:
      - cargo +nightly fuzz run --fuzz-dir fuzz {{.CLI_ARGS}}

  fuzz-all:
    desc: >-
      Run all fuzz targets in parallel with logs to /tmp/buffa-fuzz/.
      Prints periodic progress summaries (every 5 min).
      Exits nonzero if any target fails or produces a new crash artifact;
      interrupting stops every target and exits 128+signum (130 for Ctrl-C).
      Usage: task fuzz-all [-- max_total_time_secs]
      Default: 28800 (8 hours).
    cmds:
      - scripts/fuzz-all.sh {{.CLI_ARGS}}

  # ── Plugin image ──────────────────────────────────────────────────────

  plugin-image:
    desc: >-
      Build the protoc-gen-buffa Docker image for the Buf Schema Registry.
      Targets linux/amd64 as required by BSR. Push with:
        buf beta registry plugin push --visibility public --image protoc-gen-buffa
    cmds:
      - docker build --platform linux/amd64
          -t protoc-gen-buffa
          -f protoc-gen-buffa/Dockerfile
          .

  # ── Benchmarks ────────────────────────────────────────────────────
  #
  # The primary `bench` target runs buffa-only benchmarks natively (no
  # Docker). Criterion automatically compares against the previous run
  # stored in benchmarks/buffa/target/criterion/, showing per-benchmark
  # regression/improvement. Use this for dev-loop regression checking.
  #
  # For cross-implementation comparison (buffa vs prost vs google vs Go),
  # use `bench-cross` which runs all implementations in Docker for
  # environment consistency. Slower (~20 min with builds) but necessary
  # for fair comparison since each impl has different toolchain deps.

  gen-datasets:
    desc: >-
      Regenerate benchmark datasets from the gen-datasets binary. Uses a fixed
      RNG seed, so api_response.pb, analytics_event.pb, and
      google_message1_proto3.pb are byte-reproducible. log_record.pb and
      media_frame.pb are NOT — their map fields encode in HashMap iteration
      order (random per process). Don't commit log_record.pb or media_frame.pb
      churn unless the schema or generator logic changed.
    dir: benchmarks/gen-datasets
    cmds:
      - cargo run

  bench:
    desc: >-
      Run buffa benchmarks natively. Criterion compares against the
      previous run automatically (see "change:" lines in output).
      Pass a filter to run a subset: task bench -- log_record
    dir: benchmarks/buffa
    cmds:
      - cargo bench -- {{.CLI_ARGS}}

  bench-save-baseline:
    desc: >-
      Save the current native benchmark results as a named criterion
      baseline. Future `task bench` runs compare against this.
      Usage: task bench-save-baseline -- <name>  (e.g. "main" or "pre-refactor")
    dir: benchmarks/buffa
    cmds:
      - cargo bench -- --save-baseline {{.CLI_ARGS}}

  bench-compare:
    desc: >-
      Run benchmarks and compare against a named baseline.
      Usage: task bench-compare -- <baseline-name>
    dir: benchmarks/buffa
    cmds:
      - cargo bench -- --baseline {{.CLI_ARGS}}

  bench-encode-sink:
    desc: >-
      Compare encode sinks (Vec<u8> vs BytesMut, encode_to_vec vs
      encode_to_bytes) at both the fat-LTO bench profile and the profile a
      downstream `cargo build --release` gets. The two runs keep separate
      criterion result directories (target/criterion, target/criterion-nolto)
      so a baseline saved by one is never compared against the other. Extra
      args go to criterion, e.g. task bench-encode-sink -- --save-baseline main
    dir: benchmarks/buffa
    cmds:
      - cargo bench --features encode_sink --bench encode_sink -- {{.CLI_ARGS}}
      - cmd: cargo bench --features encode_sink --bench encode_sink --profile bench-nolto -- {{.CLI_ARGS}}
        env:
          CRITERION_HOME: target/criterion-nolto

  bench-iso:
    desc: >-
      Run ONE message's benchmarks in isolation — only that message's decoder is
      compiled, so no other shape's codegen can perturb it via inlining. Built at
      the reproducible, layout-normalized profile used for the per-shape benchmark
      history: lto=true, codegen-units=1, and 64-byte block alignment
      (-align-all-nofallthru-blocks=6), which removes the build-time code-layout
      lottery that otherwise swings the JSON path ~20% (see
      benchmarks/history/annotations.md). Takes a bare message name only (no extra
      criterion args): task bench-iso -- media_frame. Note: an *official* history
      measurement also pins the toolchain (RUSTUP_TOOLCHAIN); see the runbook in
      benchmarks/history/README.md.
    dir: benchmarks/buffa
    env:
      CARGO_PROFILE_BENCH_LTO: "true"
      CARGO_PROFILE_BENCH_CODEGEN_UNITS: "1"
      RUSTFLAGS: "-Cllvm-args=-align-all-nofallthru-blocks=6"
    cmds:
      - cargo bench --no-default-features --features "iso,{{.CLI_ARGS}}" --bench {{.CLI_ARGS}}

  check-iso-protos:
    desc: >-
      Assert benchmarks/proto/iso/*.proto stay field-identical to the message
      blocks in bench_messages.proto (the shape source for the prost/cross-impl
      harnesses and dataset generation). Run after editing any benchmark message.
    cmds:
      - python3 benchmarks/proto/check-iso-protos.py

  bench-prost:
    desc: >-
      Run prost benchmarks natively (same machine as `task bench`, so
      directly comparable). Use this for buffa-vs-prost regression checks.
    dir: benchmarks/prost
    cmds:
      - cargo bench -- {{.CLI_ARGS}}

  bench-prost-bytes:
    desc: >-
      Run the prost `bytes::Bytes` variant (prost-build `.bytes(["."])`
      config + `Bytes` decode input). Intended as the fair comparison
      point for buffa's view-based zero-copy decode.
    dir: benchmarks/prost-bytes
    cmds:
      - cargo bench -- {{.CLI_ARGS}}

  # ── Cross-implementation comparison (Docker) ───────────────────────
  #
  # Docker is required for google-rs (needs cmake + specific protoc 33.1)
  # and go (needs go toolchain + protoc-gen-go). Expect ±5-15% noise
  # from container overhead — use native `task bench` / `task bench-prost`
  # for precise buffa/prost comparison.
  # comparison would require polluting the host with all of these.

  bench-cross-buffa:
    desc: Run buffa benchmarks in Docker (for bench-cross).
    cmds:
      - docker build -t buffa-bench-buffa -f benchmarks/Dockerfile.bench-buffa .
      - docker run --rm buffa-bench-buffa

  bench-cross-prost:
    desc: Run prost benchmarks in Docker (for bench-cross).
    cmds:
      - docker build -t buffa-bench-prost -f benchmarks/Dockerfile.bench-prost .
      - docker run --rm buffa-bench-prost

  bench-cross-prost-bytes:
    desc: Run prost-bytes benchmarks in Docker (for bench-cross).
    cmds:
      - docker build -t buffa-bench-prost-bytes -f benchmarks/Dockerfile.bench-prost-bytes .
      - docker run --rm buffa-bench-prost-bytes

  bench-cross-google:
    desc: Run Google protobuf-v4 benchmarks in Docker (for bench-cross).
    cmds:
      - docker build -t buffa-bench-google -f benchmarks/Dockerfile.bench-google .
      - docker run --rm buffa-bench-google

  bench-cross-go:
    desc: Run Go protojson benchmarks in Docker (for bench-cross).
    cmds:
      - docker build -t buffa-bench-go -f benchmarks/Dockerfile.bench-go .
      - docker run --rm buffa-bench-go

  bench-cross:
    desc: >-
      Run all benchmarks (buffa, prost, google, go) in Docker and save
      results to benchmarks/results/ for cross-implementation comparison.
      Slow (~20 min including Docker builds). Use `task bench` for
      fast dev-loop regression checking.
    cmds:
      - mkdir -p benchmarks/results
      - rm -rf benchmarks/results/criterion-buffa benchmarks/results/criterion-prost benchmarks/results/criterion-prost-bytes
      - |
        echo "Running buffa benchmarks..."
        docker build -t buffa-bench-buffa -f benchmarks/Dockerfile.bench-buffa .
        CID=$(docker create buffa-bench-buffa)
        docker start -a "$CID" > benchmarks/results/buffa.json
        docker cp "$CID:/workspace/benchmarks/buffa/target/criterion/." benchmarks/results/criterion-buffa/ || echo "(criterion extract failed)"
        docker rm "$CID" > /dev/null
      - |
        echo "Running prost benchmarks..."
        docker build -t buffa-bench-prost -f benchmarks/Dockerfile.bench-prost .
        CID=$(docker create buffa-bench-prost)
        docker start -a "$CID" > benchmarks/results/prost.json
        docker cp "$CID:/workspace/benchmarks/prost/target/criterion/." benchmarks/results/criterion-prost/ || echo "(criterion extract failed)"
        docker rm "$CID" > /dev/null
      - |
        echo "Running prost-bytes benchmarks..."
        docker build -t buffa-bench-prost-bytes -f benchmarks/Dockerfile.bench-prost-bytes .
        CID=$(docker create buffa-bench-prost-bytes)
        docker start -a "$CID" > benchmarks/results/prost-bytes.json
        docker cp "$CID:/workspace/benchmarks/prost-bytes/target/criterion/." benchmarks/results/criterion-prost-bytes/ || echo "(criterion extract failed)"
        docker rm "$CID" > /dev/null
      - |
        echo "Running google benchmarks..."
        docker build -t buffa-bench-google -f benchmarks/Dockerfile.bench-google .
        CID=$(docker create buffa-bench-google)
        docker start -a "$CID" > benchmarks/results/google.json
        docker rm "$CID" > /dev/null
      - |
        echo "Running Go benchmarks..."
        docker build -t buffa-bench-go -f benchmarks/Dockerfile.bench-go .
        docker run --rm buffa-bench-go 2>&1 | tee benchmarks/results/go.txt
      - |
        echo ""
        echo "Results saved to benchmarks/results/"
        echo "Run 'task bench-charts' to generate comparison charts."

  bench-charts:
    desc: >-
      Generate SVG charts and README tables from saved benchmark results
      in benchmarks/results/. Run bench-cross first.
    cmds:
      - python3 benchmarks/charts/generate.py benchmarks/results/

  bench-history-report:
    desc: >-
      Regenerate the per-release benchmark history report and charts from the
      committed data in benchmarks/history/runs/. See benchmarks/history/README.md
      for how the run data is produced and how to add a release.
    cmds:
      - python3 benchmarks/history/generate.py

  bench-layout-variants:
    desc: >-
      Build the protobuf bench binary at several codegen-units settings into
      <dir> (default ./cgu-variants), for the layout-noise harness. A/B the
      variants on a quiesced box (bench-on-metal.sh --binary cgu1.bench ...),
      then run bench-layout-envelope on the captured outputs. Override the
      sweep with CGUS="1 4 16". See benchmarks/history/README.md.
    cmds:
      - benchmarks/history/build-cgu-variants.sh {{.CLI_ARGS}}

  bench-layout-envelope:
    desc: >-
      Compute the build-layout-noise envelope from labelled criterion captures
      of the codegen-units variants. Usage:
      task bench-layout-envelope -- --run cgu1=cgu1.txt --run cgu16=cgu16.txt
    cmds:
      - python3 benchmarks/history/layout_envelope.py {{.CLI_ARGS}}

  # ── Compatibility tests ──────────────────────────────────────────────

  protoc-compat:
    desc: >-
      Test protoc-gen-buffa against multiple protoc versions (v21–v33) to
      verify plugin protocol compatibility. Runs in Docker.
    cmds:
      - docker build -t buffa-protoc-compat -f compat/Dockerfile .
      - docker run --rm buffa-protoc-compat

  # ── Stress tests ─────────────────────────────────────────────────────

  stress-googleapis:
    desc: >-
      Generate Rust code for the entire Google Cloud APIs proto set (~thousands
      of .proto files) to stress-test codegen. Use -v to mount output:
        task stress-googleapis -- -v ./stress/googleapis/out:/out
    cmds:
      - docker build -t buffa-stress-googleapis -f stress/googleapis/Dockerfile .
      - docker run --rm {{.CLI_ARGS}} buffa-stress-googleapis

  # ── Checked-in generated code ─────────────────────────────────────────
  #
  # These sets of generated code are checked into the repo:
  #   - buffa-descriptor/src/generated/     (bootstrap descriptor types)
  #   - buffa-types/src/generated/          (well-known types)
  #   - buffa-proto-options/src/generated/  (buffa's custom options)
  # CI (check-generated-code) fails if any of them is stale.

  gen-bootstrap-types:
    desc: >-
      Regenerate buffa-descriptor/src/generated/ (descriptor.proto + plugin.proto
      types used by codegen itself to parse descriptors). Only needed when a
      codegen change affects the descriptor types themselves — most codegen
      changes don't. Proto sources are vendored in buffa-descriptor/protos/;
      only a protoc binary (v27+) is required.
    cmds:
      - scripts/gen-bootstrap-types.sh

  vendor-bootstrap-protos:
    desc: >-
      Re-fetch buffa-descriptor/protos/ from the protobuf release matching
      TOOLS_IMAGE. Run this when bumping the protobuf version, then follow
      with `task gen-bootstrap-types` and `task gen-option-types`
      (buffa-proto-options embeds descriptor.proto) and commit all three. Uses
      gh (authenticated API) rather than raw curl to avoid GitHub's anonymous
      rate limit.
    vars:
      PROTO_VER:
        sh: echo "{{.TOOLS_IMAGE}}" | sed 's/.*:v//'
      GH_RAW: gh api -H "Accept:application/vnd.github.raw"
      SRC: repos/protocolbuffers/protobuf/contents/src/google/protobuf
    preconditions:
      - sh: gh auth status
        msg: >-
          gh CLI must be authenticated. Run: gh auth login
    cmds:
      - echo "Vendoring descriptor.proto + plugin.proto from protobuf v{{.PROTO_VER}}"
      - mkdir -p buffa-descriptor/protos/google/protobuf/compiler
      - >-
        {{.GH_RAW}} '{{.SRC}}/descriptor.proto?ref=v{{.PROTO_VER}}'
        > buffa-descriptor/protos/google/protobuf/descriptor.proto
      - >-
        {{.GH_RAW}} '{{.SRC}}/compiler/plugin.proto?ref=v{{.PROTO_VER}}'
        > buffa-descriptor/protos/google/protobuf/compiler/plugin.proto
      - wc -l buffa-descriptor/protos/google/protobuf/descriptor.proto
          buffa-descriptor/protos/google/protobuf/compiler/plugin.proto

  gen-wkt-types:
    desc: >-
      Regenerate buffa-types/src/generated/ (Timestamp, Duration, Any, etc.).
      Run this after any codegen change that affects output format.
      Requires protoc on PATH.
    cmds:
      - >-
        protoc --descriptor_set_out=/tmp/wkt.pb --include_imports --include_source_info
        -I buffa-types/protos
        google/protobuf/any.proto
        google/protobuf/api.proto
        google/protobuf/duration.proto
        google/protobuf/empty.proto
        google/protobuf/field_mask.proto
        google/protobuf/source_context.proto
        google/protobuf/struct.proto
        google/protobuf/timestamp.proto
        google/protobuf/type.proto
        google/protobuf/wrappers.proto
      - cargo run -p buffa-codegen --bin gen_wkt_types -- /tmp/wkt.pb buffa-types/src/generated

  gen-option-types:
    desc: >-
      Regenerate buffa-proto-options/src/generated/ (the option messages and
      extensions of buffa/ext/options.proto). Run this after editing
      options.proto or after any codegen change that affects output format.
      descriptor.proto is read from buffa-descriptor/protos/ (pinned), so only
      a protoc binary (v27+) is required.
    cmds:
      - scripts/gen-option-types.sh

  # ── Examples ──────────────────────────────────────────────────────────

  gen-logging-example:
    desc: >-
      Regenerate the logging example's protobuf code using buf generate
      and protoc-gen-buffa. Requires a release build of protoc-gen-buffa
      and buf on PATH.
    deps: [build-plugin]
    dir: examples/logging
    cmds:
      - rm -f src/gen/context.v1.context.rs src/gen/log.v1.log.rs src/gen/mod.rs
      - PATH="{{.ROOT_DIR}}/target/release:$PATH" buf generate

  gen-bsr-quickstart-example:
    desc: >-
      Regenerate the bsr-quickstart example's protobuf code from the
      published `buf.build/anthropics/buffa` BSR remote plugin. Requires
      buf on PATH and network access. The example demonstrates the
      consumer-facing remote-plugin workflow, so it deliberately uses
      the published plugin rather than the in-tree `protoc-gen-buffa`.
      The plugin version is pinned in `buf.gen.yaml` for reproducible
      output, and the example's `Cargo.toml` pins `buffa` / `buffa-types`
      to the same release. When a new BSR plugin release ships, bump all
      three together and re-run this task — not after every codegen
      change. `src/gen/mod.rs` is hand-written and not touched by buf.
    dir: examples/bsr-quickstart
    cmds:
      - rm -f src/gen/example.v1.rs
      - buf generate

  # The examples are independent cargo projects (own Cargo.toml, own target/),
  # not workspace members. Most declare path deps on the workspace crates to
  # mirror a downstream consumer's setup; bsr-quickstart instead depends on the
  # crates.io release matching its BSR plugin pin.

  build-examples:
    desc: Build all example binaries.
    cmds:
      - cargo build --manifest-path examples/addressbook/Cargo.toml
      - cargo build --manifest-path examples/bsr-quickstart/Cargo.toml
      - cargo build --manifest-path examples/conflicts/Cargo.toml
      - cargo build --manifest-path examples/envelope/Cargo.toml
      - cargo build --manifest-path examples/logging/Cargo.toml

  example-conflicts:
    desc: >-
      Run the natural-path re-exports demo — shows the `__buffa::` import
      fallback when a re-export is shadowed by a real proto type.
      Self-contained, no args.
    dir: examples/conflicts
    cmds:
      - cargo run

  example-envelope:
    desc: >-
      Run the extensions demo — binary + JSON roundtrip of custom options,
      [default = ...] values, extendee-mismatch panic. Self-contained, no args.
    dir: examples/envelope
    cmds:
      - cargo run

  # `dir: {{.USER_WORKING_DIR}}` so file-path arguments resolve relative to
  # where `task` was invoked, not the Taskfile's directory. Task defaults to
  # running commands from the Taskfile location, which would make
  # `task example-addressbook -- dump book.pb` look for ./book.pb in the
  # repo root instead of the user's cwd.

  example-addressbook:
    desc: >-
      Run the addressbook CLI. Pass subcommand + args after `--`:
      `task example-addressbook -- add book.pb` /
      `task example-addressbook -- list book.pb` /
      `task example-addressbook -- dump book.pb` (textproto).
    dir: '{{.USER_WORKING_DIR}}'
    cmds:
      - cargo run --manifest-path {{.ROOT_DIR}}/examples/addressbook/Cargo.toml -- {{.CLI_ARGS}}

  example-logging:
    desc: >-
      Run the structured-logging CLI. Pass subcommand + file after `--`:
      `task example-logging -- write log.pb` /
      `task example-logging -- read log.pb` /
      `task example-logging -- filter log.pb WARN`.
    dir: '{{.USER_WORKING_DIR}}'
    cmds:
      - cargo run --manifest-path {{.ROOT_DIR}}/examples/logging/Cargo.toml -- {{.CLI_ARGS}}

  build-plugin:
    desc: Build the protoc plugins in release mode.
    cmds:
      - cargo build --release --bin protoc-gen-buffa --bin protoc-gen-buffa-packaging
    sources:
      - buffa-codegen/src/**/*.rs
      - protoc-gen-buffa/src/**/*.rs
      - protoc-gen-buffa-packaging/src/**/*.rs
    generates:
      - target/release/protoc-gen-buffa
      - target/release/protoc-gen-buffa-packaging

  # ── Cross-target checks ─────────────────────────────────────────

  install-targets:
    desc: >-
      Install the additional rustup targets required by cross-target
      check and test tasks (i686-unknown-linux-gnu, thumbv7em-none-eabihf).
    cmds:
      - rustup target add i686-unknown-linux-gnu thumbv7em-none-eabihf

  check-32bit:
    desc: >-
      Check that the workspace compiles for 32-bit x86 Linux.
    preconditions:
      - sh: rustup target list --installed | grep -q i686-unknown-linux-gnu
        msg: >-
          Target i686-unknown-linux-gnu is not installed.
          Run 'task install-targets' to install it.
    cmds:
      - cargo check --workspace --target i686-unknown-linux-gnu

  test-32bit:
    desc: >-
      Build and run the workspace test suite on 32-bit x86 Linux.
      Also requires gcc-multilib for cross-compilation linking.
    preconditions:
      - sh: rustup target list --installed | grep -q i686-unknown-linux-gnu
        msg: >-
          Target i686-unknown-linux-gnu is not installed.
          Run 'task install-targets' to install it.
    cmds:
      - cargo test --workspace --target i686-unknown-linux-gnu

  check-nostd:
    desc: >-
      Check that buffa, buffa-types, buffa-descriptor, and buffa-proto-options
      compile in no_std + alloc configuration — the same crates the CI
      check-nostd job covers. The host checks disable the std-only features; the bare-metal
      ARM Cortex-M4 (thumbv7em) check verifies true no_std with no OS or libc.
      The bare-metal target is added on demand (rustup target add is
      idempotent), so this task needs no separate install-targets step.
    cmds:
      - rustup target add thumbv7em-none-eabihf
      - cargo check -p buffa --no-default-features
      - cargo test -p buffa --no-default-features --features json --test nostd_json_options
      - cargo check -p buffa --no-default-features --target thumbv7em-none-eabihf
      - cargo check -p buffa-types --no-default-features
      - cargo check -p buffa-types --no-default-features --features chrono
      - cargo check -p buffa-types --no-default-features --features jiff
      - cargo check -p buffa-descriptor --no-default-features
      - cargo check -p buffa-descriptor --no-default-features --features json,reflect,text,views
      - cargo test -p buffa-descriptor --no-default-features --features json,reflect --test '*'
      - cargo check -p buffa-proto-options --no-default-features
      - cargo check -p buffa-proto-options --no-default-features --features json,text,views
  # ── Coverage ─────────────────────────────────────────────────────────

  coverage:
    desc: Generate a line-coverage summary for the workspace.
    vars:
      IGNORE: "--ignore-filename-regex 'generated/|gen_descriptor_types|gen_wkt_types|gen_option_types'"
    cmds:
      - cargo llvm-cov --workspace --features buffa/json {{.IGNORE}} --include-build-script --summary-only

  coverage-html:
    desc: Generate an HTML coverage report and open it in the browser.
    vars:
      IGNORE: "--ignore-filename-regex 'generated/|gen_descriptor_types|gen_wkt_types|gen_option_types'"
    cmds:
      - cargo llvm-cov --workspace --features buffa/json {{.IGNORE}} --include-build-script --open

  clean:
    desc: Remove build artefacts and fetched proto files.
    cmds:
      - cargo clean
      - rm -rf conformance/protos/