justfile

set shell := ["bash", "-euo", "pipefail", "-c"]

project_tmp := justfile_directory() + "/.tox/tmp"
coverage_target_root := justfile_directory() + "/.tox/coverage-target"
exe_suffix := if os_family() == "windows" { ".exe" } else { "" }
workspace_target := env_var_or_default("CARGO_TARGET_DIR", justfile_directory() + "/target")
workspace_binary := workspace_target + "/debug/peryx" + exe_suffix
native_coverage_target := workspace_target + "/llvm-cov-target"
native_coverage_binary := native_coverage_target + "/debug/peryx" + exe_suffix
tools_root := justfile_directory() + "/.tox/tools"
export PERYX_TEST_TMPDIR := project_tmp

# Run the default test suite.
default: test

# Create the project-owned temporary directory.
_project-temp:
    mkdir -p "{{ project_tmp }}"

# Verify that the Docker daemon is available.
_docker-ready:
    docker info >/dev/null

# Print the archive-relative path of the shipped server inside a nextest archive.
_archive-peryx-binary archive:
    #!/usr/bin/env bash
    set -euo pipefail
    tar --extract --to-stdout --file "{{ archive }}" target/nextest/binaries-metadata.json \
      | jq -er '
          [."rust-build-meta"."non-test-binaries"[][]
            | select(.name == "peryx" and .kind == "bin-exe")
            | .path]
          | unique
          | if length == 1 then .[0] else error("archive must contain one Peryx server binary") end
        '

# Check CodSpeed benchmark selections.
_codspeed-target-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    metadata="$(cargo metadata --no-deps --format-version 1)"
    jq -e '
      def benches($package):
        [.packages[] | select(.name == $package) | .targets[] | select(.kind == ["bench"])];
      (benches("peryx-ecosystem-oci") | length) == 4 and
      (benches("peryx-ecosystem-pypi") | map(select(."required-features" | length == 0)) | length) == 7 and
      (benches("peryx-ecosystem-pypi") | map(select(.name == "serve" or .name == "transform")) | length) == 2
    ' <<<"$metadata"
    just --dry-run codspeed-build peryx-ecosystem-oci all 2>&1 \
      | grep -F 'case "all" in'
    just --dry-run codspeed-build peryx-ecosystem-pypi parsing 2>&1 \
      | grep -F 'case "parsing" in'
    just --dry-run codspeed-build peryx-ecosystem-pypi serving 2>&1 \
      | grep -F 'case "serving" in'
    just --dry-run codspeed-run peryx-ecosystem-oci 2>&1 \
      | grep -F 'cargo codspeed run -m "simulation" --package "peryx-ecosystem-oci"'
    just --dry-run codspeed-run peryx-ecosystem-pypi 2>&1 \
      | grep -F 'cargo codspeed run -m "simulation" --package "peryx-ecosystem-pypi"'
    grep -A1 -xF '[profile.bench.package.peryx-ecosystem-pypi]' Cargo.toml \
      | grep -qxF 'codegen-units = 1'

# Check coverage target isolation.
# Check that the line gate reports a body nothing ran, forgives one another monomorphization ran,
# and forgives one the browser target ran.
_coverage-lines-contract: _project-temp
    #!/usr/bin/env bash
    set -euo pipefail
    work="{{ project_tmp }}/coverage-lines-contract"
    mkdir -p "$work"
    # `a.rs` holds two monomorphizations of one generic, each running the line the other does not, so
    # between them they run both and neither line is a gap. Scoring the group by its best single
    # member instead, which is what LLVM's own total does, reports one of them missed. `b.rs` holds a
    # body nothing ran here, and `c.rs` one that only the browser target runs.
    printf '%s' \
      '{"data":[{"files":[{"filename":"a.rs"},{"filename":"b.rs"},{"filename":"c.rs"}],"functions":[' \
      '{"filenames":["a.rs"],"regions":[[10,1,10,9,5,0,0,0],[11,1,11,9,0,0,0,0]]},' \
      '{"filenames":["a.rs"],"regions":[[10,1,10,9,0,0,0,0],[11,1,11,9,7,0,0,0]]},' \
      '{"filenames":["b.rs"],"regions":[[20,1,20,9,0,0,0,0]]},' \
      '{"filenames":["c.rs"],"regions":[[30,1,30,9,0,0,0,0]]}]}]}' >"$work/export.json"
    # The browser tracefile runs the body starting on line 30 and nothing in `b.rs`.
    printf '%s\n' 'SF:c.rs' 'FN:30,_c30' 'FNDA:4,_c30' 'end_of_record' \
      'SF:b.rs' 'FN:20,_b20' 'FNDA:0,_b20' 'end_of_record' >"$work/browser.lcov"
    python3 coverage_lines.py gaps "$work/export.json" "$work/gaps.json"
    # The check runs under the interpreter the runner image carries, the way the recipes here already
    # reach for `jq`, so it needs no tool this job does not declare.
    #
    # The check exits non-zero when it reports anything, so its output is captured rather than piped:
    # under `pipefail` a pipeline carrying it is non-zero however the reader fares.
    report=$(python3 coverage_lines.py check "$work/gaps.json" "$work/browser.lcov" \
      && echo "reported nothing" || true)
    # `set -e` is specified to ignore a command preceded by `!`, so a negation asserts nothing here
    # and each one is written as the failure it stands for.
    grep -qF 'b.rs: 20' <<<"$report"
    for forbidden in 'a.rs' 'c.rs' 'reported nothing'; do
      if grep -qF "$forbidden" <<<"$report"; then
        echo "the line check reported ${forbidden@Q}: $report" >&2
        exit 1
      fi
    done

_coverage-target-contract:
    CARGO_TARGET_DIR="{{ project_tmp }}/coverage-target-contract" just --dry-run coverage-frontend 2>&1 \
      | grep -F 'export CARGO_TARGET_DIR="{{ project_tmp }}/coverage-target-contract/frontend"'
    env -u CARGO_TARGET_DIR just --dry-run coverage-frontend 2>&1 \
      | grep -F 'export CARGO_TARGET_DIR="{{ coverage_target_root }}/frontend"'
    just --dry-run coverage-native 2>&1 \
      | grep -F 'PERYX_BIN="{{ native_coverage_binary }}"'
    # Two halves gate the run and neither covers the other. `--fail-uncovered-lines` names a line no
    # function reached; the line check names a function body nothing ran, which the first cannot see
    # where a covered caller spans it.
    just --dry-run coverage-native 2>&1 \
      | grep -F -- '--fail-uncovered-lines 0 --show-missing-lines'
    just --dry-run coverage-native 2>&1 \
      | grep -F 'python3 coverage_lines.py'
    # LLVM's own total is not the second half. It scores an instantiation group by its best single
    # monomorphization, so it counts a line another monomorphization ran as missed.
    ! just --dry-run coverage-native 2>&1 | grep -Fq -- '--fail-under-lines'
    # Both gates report to the terminal. Folding either into the lcov write makes a failure print
    # nothing at all, which leaves the reader a bare exit code.
    ! just --dry-run coverage-native 2>&1 \
      | grep -F -- '--fail-uncovered-lines 0' | grep -Fq -- '--lcov'

# Check that the default test suite receives the built Peryx binary.
_test-target-contract:
    CARGO_TARGET_DIR="{{ project_tmp }}/test-target-contract" just --dry-run test 2>&1 \
      | grep -F 'PERYX_BIN="{{ project_tmp }}/test-target-contract/debug/peryx{{ exe_suffix }}"'

# Check that the archive lookup reads the shipped server out of the archive metadata.
_archive-binary-contract:
    just --dry-run _archive-peryx-binary archive.tar.zst 2>&1 \
      | grep -F 'tar --extract --to-stdout --file "archive.tar.zst" target/nextest/binaries-metadata.json'
    just --dry-run _archive-peryx-binary archive.tar.zst 2>&1 \
      | grep -F 'select(.name == "peryx" and .kind == "bin-exe")'

# Check that archived sanitizer tests receive the relocated Peryx binary.
_sanitizer-target-contract:
    just --dry-run sanitizer-run archive.tar.zst slice:1/8 2>&1 \
      | grep -F '_archive-peryx-binary "archive.tar.zst"'
    just --dry-run sanitizer-run archive.tar.zst slice:1/8 2>&1 \
      | grep -F 'PERYX_BIN="$scratch/target/$binary"'
    just --dry-run sanitizer-run archive.tar.zst slice:1/8 2>&1 \
      | grep -F -- '--extract-to "$scratch"'

# Check that archived mutation baseline tests receive the relocated Peryx binary.
_mutation-baseline-target-contract:
    just --dry-run mutation-baseline-run archive.tar.zst slice:1/8 2>&1 \
      | grep -F '_archive-peryx-binary "archive.tar.zst"'
    just --dry-run mutation-baseline-run archive.tar.zst slice:1/8 2>&1 \
      | grep -F 'PERYX_BIN="$scratch/target/$binary"'
    just --dry-run mutation-baseline-run archive.tar.zst slice:1/8 2>&1 \
      | grep -F -- '--extract-to "$scratch"'

# Check mutation shard planning.
_mutation-shard-count-contract:
    test "$(just mutation-shard-count 255 256)" = 1
    test "$(just mutation-shard-count 8193 256)" = 33
    test "$(just mutation-shard-count 513 256)" = 3

# Check the zero-feature binary with declared CI tools.
_features-tool-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    # A build wrapper is how a developer accelerates the build rather than a tool the build needs, so
    # the narrowed PATH below must not take it away. `heavy.sh` names sccache by bare word, which the
    # narrow PATH cannot resolve, and cargo then fails to spawn it instead of reaching the guard this
    # contract reads. Resolving each wrapper while the full PATH still applies keeps both true.
    for wrapper in RUSTC_WRAPPER RUSTC_WORKSPACE_WRAPPER; do
      named="${!wrapper:-}"
      if [[ -z $named || $named == /* ]]; then
        continue
      fi
      if resolved=$(command -v "$named"); then
        export "$wrapper=$resolved"
      else
        unset "$wrapper"
      fi
    done
    export PATH="$(dirname "$(command -v cargo)"):/usr/bin:/bin"
    if command -v rg >/dev/null; then
      echo 'ripgrep is present in the feature contract' >&2
      exit 1
    fi
    "{{ just_executable() }}" _zero-feature-binary

# Check that every browser suite runs and that any suite failure fails the recipe.
_frontend-test-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    script=$("{{ just_executable() }}" --dry-run frontend-test 2>&1)
    for directory in \
      crates/peryx-web/tests/frontend \
      crates/peryx-ecosystem-pypi/tests/frontend \
      crates/peryx-ecosystem-oci/tests/frontend; do
      if [[ $(grep -Fc "$directory" <<<"$script") -ne 1 ]]; then
        printf 'frontend-test must run %s exactly once\n' "$directory" >&2
        exit 1
      fi
    done
    grep -Fq './node_modules/.bin/playwright test --config playwright.config.mjs) || failed+=("$suite")' <<<"$script"
    grep -Fq 'if (( ${#failed[@]} > 0 )); then' <<<"$script"
    grep -Fq 'exit 1' <<<"$script"
    # A suite that cannot run has to fail the gate. Installing it is the first answer and saying so is
    # the second; quietly running two suites out of three would report a green frontend that never
    # exercised the third.
    grep -Fq 'npm --prefix "$suite" ci' <<<"$script"
    grep -Fq 'still has no Playwright runner after npm ci' <<<"$script"
    # Whatever `playwright` resolves to on PATH is a different tool that rejects `test`, so reaching it
    # turns a missing install into an unrelated error.
    if grep -Eq '(^|[^/])\bplaywright test\b' <<<"$script"; then
      printf 'frontend-test must run each suite own Playwright, not the one on PATH\n' >&2
      exit 1
    fi
    # Joining the suites into one `;` list puts them back under plain `set -e`, which reports
    # the first broken suite and never runs the rest.
    if grep -Eq 'playwright test\b.*;' <<<"$script"; then
      printf 'frontend-test must not join browser suites with `;`\n' >&2
      exit 1
    fi

# Check Rust formatting.
format-check: _project-temp
    cargo fmt --all --check --

# Check every workspace target with all features.
check: _project-temp
    cargo check --workspace --all-targets --all-features

# Lint every workspace target with Clippy.
clippy: _project-temp
    cargo clippy --workspace --all-targets --all-features -- -D warnings

# Check Rust formatting and lints.
lint-source: format-check clippy

# Check rustdoc, Markdown, and spelling.
lint-docs: _project-temp
    RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
    prek run mdformat --all-files
    prek run codespell --all-files

# Check workflows and repository automation.
lint-automation: _project-temp _archive-binary-contract _browser-contract _codspeed-target-contract _coverage-lines-contract _coverage-target-contract _embedded-docs-contract _features-tool-contract _frontend-test-contract _mise-trust-contract _mutation-baseline-target-contract _mutation-profile-contract _mutation-scope-contract _mutation-shard-count-contract _mutation-telemetry-contract _paused-clock-contract _readthedocs-contract _renovate-contract _sanitizer-target-contract _test-target-contract
    SKIP=cargo-fmt,cargo-clippy,mdformat,codespell prek run --all-files

# Check that mutation scope stays on production code and that the shard plan follows it.
_mutation-scope-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    for glob in 'crates/*/src/bench/**' 'crates/peryx-test-support/**' 'crates/*/tests/**'; do
      if ! grep -Fq "\"$glob\"" .cargo/mutants.toml; then
        printf 'mutation scope must exclude %s; see contributing/ci.md for why\n' "$glob" >&2
        exit 1
      fi
    done
    # The shard count divides the same list the run mutates. Counting a wider plan than the run covers
    # would size the matrix for mutants nothing then examines.
    just --dry-run mutation-count 2>&1 | grep -Fq -- '--list --workspace --all-features'

_mutation-profile-contract:
    just --dry-run mutation 0/1 true 2 skip 500 round-robin 2>&1 \
      | grep -F 'CARGO_INCREMENTAL=0 CARGO_PROFILE_TEST_DEBUG=0 PATH='

# Check that a shard's telemetry can name the resource it ran out of.
_mutation-telemetry-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    recipe="$(just --dry-run mutation-observed 0/1 true 1 skip 500 round-robin 2>&1)"
    # A shard that loses its runner uploads nothing and leaves no log, so each property below is what
    # a shard that survives can still report about the run-up.
    check() {
      if ! grep -Fq -- "$2" <<<"$recipe"; then
        printf 'mutation telemetry must %s; see contributing/ci.md for why\n' "$1" >&2
        exit 1
      fi
    }
    check 'read progress from the outcomes cargo-mutants writes' '.tox/mutants/mutants.out/outcomes.json'
    check 'report free space on the filesystem holding the workspace' 'disk.available=%s'
    check 'report the memory the machine has left' 'memory.available=%s'
    check 'append every sample to the uploaded output directory' 'tee -a "$trace"'

# Check that the hosted build commands survive their shell wrapper.
_readthedocs-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    # Read the Docs runs each command as /bin/sh -c '<command>' without escaping, so one quote of its
    # own ends the wrapper and the rest of the line reparses as something else.
    ! grep -q "'" .readthedocs.yaml

# Check that every site file a crate embeds is named in the CI path filter.
#
# CI lets a pull request that changes only the site or Markdown skip the Rust jobs. A document a crate
# reads with `include_str!` is compiled into a binary or a test, so a change to it has to run them
# after all; the workflow lists those files by hand, and this keeps the list from going stale.
_embedded-docs-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    grep -rhoE 'include_(str|bytes)!\("[^"]*"\)' crates --include='*.rs' \
      | grep -oE '"[^"]+"' | tr -d '"' | grep -E '^(\.\./)+site/|\.md$' | sed -E 's#^(\.\./)+##' | sort -u \
      | while IFS= read -r embedded; do
          if ! grep -Fq -- "- '$embedded'" .github/workflows/ci.yml; then
            printf '%s is embedded by a crate but missing from the embedded filter in ci.yml\n' "$embedded" >&2
            exit 1
          fi
        done

# Check that no test holds a paused clock across real socket work without a stated reason.
#
# A paused tokio clock auto-advances to the next pending timer whenever the runtime parks, and a
# socket read parks, so the clock rather than the code can satisfy such a test's assertion. The
# hazard needs a pending timer at the moment of the park, which most pairings do not have, so this
# asks for a reason rather than deciding the question itself.
_paused-clock-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    harness='TestServer::start|TcpListener::bind|MockServer::start|ControlledServer::start|reqwest::(get|Client)|wiremock'
    program='
    { source[NR] = $0 }
    END {
      total = NR
      count = 0
      for (i = 1; i <= total; i++) {
        if (match(source[i], /^[ \t]*(pub\([a-z()]*\) )?(pub )?(async )?fn [A-Za-z0-9_]+/) == 0)
          continue
        indent = source[i]
        sub(/[^ \t].*$/, "", indent)
        name = substr(source[i], RSTART, RLENGTH)
        sub(/.*fn /, "", name)
        last = total
        for (j = i + 1; j <= total; j++)
          if (source[j] == indent "}") { last = j; break }
        count++
        named[count] = name
        defined[name] = count
        line_of[count] = i
        body[count] = ""
        for (j = i; j <= last; j++)
          body[count] = body[count] source[j] "\n"
        header = ""
        for (j = i - 1; j >= 1; j--) {
          above = source[j]
          sub(/^[ \t]+/, "", above)
          if (above == "" || above == "}")
            break
          header = source[j] "\n" header
        }
        heads[count] = header
      }
      for (k = 1; k <= count; k++) {
        resumes[k] = index(body[k], "tokio::time::resume") > 0
        paused[k] = index(heads[k], "start_paused") > 0
        at = index(heads[k], "paused-clock-safe:")
        reason[k] = at == 0 ? "" : trim(substr(heads[k], at + 18))
      }
      for (k = 1; k <= count; k++) {
        if (paused[k] == 0 && reason[k] != "")
          tell(k, "states a paused-clock reason but never pauses its clock; delete the comment")
        if (paused[k] == 0 || harness == 0)
          continue
        if (reason[k] != "" && length(reason[k]) < 20)
          tell(k, "states a paused-clock reason too short for the next reader to re-check")
        else if (reason[k] == "" && running(k) == 0)
          tell(k, "holds a paused clock in a file that opens sockets")
      }
    }
    function trim(text) {
      sub(/\n.*$/, "", text)
      sub(/^[ \t]+/, "", text)
      sub(/[ \t]+$/, "", text)
      return text
    }
    function running(start,   queue, head, tail, seen, k, words, w, i, name, text) {
      head = 1
      tail = 1
      queue[1] = start
      seen[start] = 1
      while (head <= tail) {
        k = queue[head++]
        if (resumes[k])
          return 1
        text = body[k]
        gsub(/[^A-Za-z0-9_]/, " ", text)
        split(text, words, " ")
        for (i in words) {
          name = words[i]
          if (name in defined) {
            w = defined[name]
            if (seen[w] == 0) { seen[w] = 1; queue[++tail] = w }
          }
        }
      }
      return 0
    }
    function tell(k, message) {
      printf "%s:%d: %s: %s\n", FILENAME, line_of[k], named[k], message
    }
    '
    findings=""
    while IFS= read -r file; do
      opens=0
      if grep -Eq "$harness" "$file"; then
        opens=1
      fi
      found=$(awk -v harness="$opens" "$program" "$file")
      if [ -n "$found" ]; then
        findings="$findings$found"$'\n'
      fi
    done < <(grep -rlE --include='*.rs' 'start_paused|paused-clock-safe' crates/ | sort)
    if [ -n "$findings" ]; then
      printf '%s' "$findings" >&2
      cat >&2 <<'GUIDANCE'

    Run the clock while the socket work is outstanding and pause only once that work is proven
    done, the shape PRs #2100, #2108 and #2117 established: bind and accept with the clock running,
    await the handle or read to EOF to prove the request landed, then pause and step the clock.
    Prefer sleep over advance for the paused step, since a paused clock stops at the earliest
    pending timer and advance jumps over an action due sooner than the one under test.

    A test that never leaves work on the wire is fine as it stands. Say why, on the line above its
    attribute, and this check will take your word for it:

        // paused-clock-safe: the saturated cap answers 429 before any upstream call
    GUIDANCE
      exit 1
    fi

# Check the custom Renovate release matcher.
_renovate-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    jq --exit-status --rawfile readthedocs .readthedocs.yaml \
      --rawfile setup .github/actions/setup/action.yml '
      [.customManagers[] | select(.depNameTemplate == "jdx/mise")] as $rules
      | [$rules[] | select(.managerFilePatterns[0] | contains("readthedocs"))][0] as $rtd
      | [$rules[] | select(.managerFilePatterns[0] | contains("actions/setup"))][0] as $action
      | ($rules | length) == 2
        and ([$readthedocs | scan($rtd.matchStrings[0])] | length) == 1
        and ([$setup | scan($action.matchStrings[0])] | length) == 1
        and ([$readthedocs | capture($rtd.matchStrings[0]).currentValue,
              $setup | capture($action.matchStrings[0]).currentValue] | unique | length) == 1
        and ($readthedocs | capture($rtd.matchStrings[0]).currentValue
          | test("^[0-9]+\\.[0-9]+\\.[0-9]+$"))
    ' renovate.json > /dev/null

# Trust this checkout's mise config so a fresh worktree can read its tool versions.
#
# mise refuses to read a config it has not been told to trust, and a worktree created minutes ago has
# not. Running `just` here already runs this repository's recipes, so trusting its tool manifest hands
# it no reach it did not already have, and without it every browser recipe reports a trust prompt in
# place of the thing it was asked to check.
_mise-trusted:
    @mise trust mise.toml >/dev/null
    @mise trust mise.browser.toml >/dev/null

# Check browser package, binary, and updater ownership.
_browser-contract: _mise-trusted
    #!/usr/bin/env bash
    set -euo pipefail
    browser_env=$(MISE_ENV=browser mise env --json)
    ! env -u MISE_ENV mise config ls | grep -Fq mise.browser.toml
    MISE_ENV=browser mise config ls | grep -Fq mise.browser.toml
    ! grep -Eq '^(linux|windows)-arm64' mise.browser.toml mise.browser.lock
    test "$(grep -Ec '^\[tools\."http:(playwright|puppeteer)-headless-shell"\."platforms\.(linux-x64|macos-arm64|macos-x64|windows-x64)"\]$' mise.browser.lock)" -eq 8
    playwright=$(jq -r .PERYX_PLAYWRIGHT_PACKAGE_VERSION <<<"$browser_env")
    puppeteer=$(jq -r .PERYX_PUPPETEER_PACKAGE_VERSION <<<"$browser_env")
    for directory in \
      crates/peryx-web/tests/frontend \
      crates/peryx-ecosystem-pypi/tests/frontend \
      crates/peryx-ecosystem-oci/tests/frontend; do
      jq -se --arg version "$playwright" '
        .[0].devDependencies["@playwright/test"] == $version and
        .[1].packages[""].devDependencies["@playwright/test"] == $version and
        .[1].packages["node_modules/@playwright/test"].version == $version and
        .[1].packages["node_modules/playwright-core"].version == $version
      ' "$directory/package.json" "$directory/package-lock.json" > /dev/null
    done
    jq -se --arg version "$puppeteer" '
      .[0].devDependencies.puppeteer == "npm:puppeteer-core@\($version)" and
      .[1].packages[""].devDependencies.puppeteer == "npm:puppeteer-core@\($version)" and
      .[1].packages["node_modules/puppeteer"].name == "puppeteer-core" and
      .[1].packages["node_modules/puppeteer"].version == $version
    ' site/package.json site/package-lock.json > /dev/null
    jq -e '
      [.packageRules[] | select(.description == "Update browser packages with their binaries")]
      | length == 1 and .[0].enabled == false
    ' renovate.json > /dev/null

# Check that every recipe invoking `mise` runs the trust step first.
#
# mise takes trust on its own for `install`, `run`, `exec` and `watch` and for nothing else, so a
# recipe leading with a read fails outright on an untrusted worktree, and one leading with an install
# works by side effect until the paranoid setting removes it. Three pull requests each wired one
# caller by hand and left the rest, so this asserts the property rather than today's six names: a
# recipe whose body invokes `mise` has to reach `_mise-trusted` somewhere in its dependencies.
#
# The two recipes implementing that mechanism are exempt: `_mise-trusted` grants the trust, and this
# one reads the dependency graph through `just --dump` and never calls mise at all. Both mention the
# word in their own text, which a scan over recipe bodies cannot tell from a command.
_mise-trust-contract:
    #!/usr/bin/env bash
    set -euo pipefail
    offenders=$("{{ just_executable() }}" --dump --dump-format json \
      | jq -r --arg trust _mise-trusted --arg contract _mise-trust-contract '
      .recipes as $recipes
      | ($recipes | map_values([.dependencies[].recipe])) as $deps
      | def reached($name): [$name] + ([$deps[$name][]? | reached(.)] | flatten);
        $recipes
        | to_entries[]
        | select(.key != $trust and .key != $contract)
        | select(
            (.value.body // [])
            | map(map(select(type == "string")) | join(""))
            | join("\n")
            | test("(^|[^A-Za-z0-9_.-])mise[ \t]+[a-z]"; "m")
          )
        | select(reached(.key) | index($trust) | not)
        | .key
    ')
    if [[ -n "$offenders" ]]; then
      printf 'these recipes invoke mise without reaching _mise-trusted:\n%s\n' "$offenders" >&2
      exit 1
    fi

# Check dependency policy.
lint-deps: _project-temp
    cargo deny check

# Check committed PyPI snapshots.
snapshots: _project-temp
    cargo insta test --package peryx-ecosystem-pypi --lib --all-features \
      --unreferenced reject --test-runner nextest --nextest-profile ci

# Check workspace public API compatibility.
#
# The release type is stated rather than inferred. Every crate here reads `0.0.1`, and a `0.0.x` release
# permits any change, so cargo-semver-checks compares the two versions, finds them equal, assumes a major
# bump and skips all 254 checks. Naming `patch` asks the question worth asking: what would this change
# break for someone pinned to the current API. A break is allowed before the first release, so this
# reports one rather than forbidding it, and CI does not run it.
semver base="origin/main" release_type="patch": _project-temp
    cargo semver-checks check-release --workspace --default-features --baseline-rev "{{ base }}" \
      --release-type "{{ release_type }}"

# Check one deterministic shard of workspace public APIs.
semver-shard shard shards base="origin/main" release_type="patch": _project-temp
    cargo metadata --no-deps --format-version 1 \
      | jq -r --argjson shard "{{ shard }}" --argjson shards "{{ shards }}" \
        '[.packages[] | select(.publish != []) | .name] | to_entries[] | select(.key % $shards == $shard) | .value' \
      | xargs -n 1 cargo semver-checks check-release --default-features --baseline-rev "{{ base }}" \
        --release-type "{{ release_type }}" --package

# Check snapshots, public APIs, and the release plan.
lint-contracts base="origin/main": snapshots _coverage-target-contract
    just semver "{{ base }}"
    just release-plan

# Run every lint lane.
lint base="origin/main": _project-temp
    just lint-source
    just lint-docs
    just lint-automation
    just lint-deps
    just lint-contracts "{{ base }}"

# Install external test tools into the project cache.
test-deps: _project-temp
    PATH="{{ tools_root }}/bin:$PATH" UV_TOOL_BIN_DIR="{{ tools_root }}/bin" \
      UV_TOOL_DIR="{{ tools_root }}" uv tool install twine

# Run workspace tests, doctests, and benchmark harnesses.
test: test-deps
    PERYX_BIN="{{ workspace_binary }}" PATH="{{ tools_root }}/bin:$PATH" cargo nextest run \
      --workspace --exclude peryx-storage --all-features --profile ci \
      -E 'not(test(e2e_live))'
    cargo nextest run --package peryx-storage --profile ci
    cargo test --workspace --all-features --doc
    just benchmark

# Run workspace benchmark harnesses as tests.
benchmark: _project-temp
    cargo test --workspace --all-features --bench '*' --no-fail-fast

# Run tests that cover platform-specific boundaries.
platform-test: _project-temp
    cargo check --workspace --all-targets --all-features
    cargo nextest run --package peryx --test cli_entrypoint --all-features --profile ci
    cargo nextest run --package peryx-upstream --all-features --profile ci
    cargo nextest run --package peryx-test-support --all-features --profile ci
    cargo nextest run --package peryx-storage --all-features --test integration \
      --profile ci -E 'test(/blob_backend/)'

# Run hermetic PyPI client boundary tests.
e2e: _project-temp
    PERYX_BIN="$(just _system-test-build composition-pypi)" PERYX_SINGLE_COMPOSITION=1 \
      cargo nextest run -p peryx-pypi-system-tests \
      --features e2e --test e2e -E 'not(test(e2e_live))'

# Run live PyPI client boundary tests.
e2e-live: test-deps
    PERYX_BIN="$(just _system-test-build composition-pypi)" PERYX_SINGLE_COMPOSITION=1 \
      PATH="{{ tools_root }}/bin:$PATH" cargo nextest run -p peryx-pypi-system-tests \
      --features e2e-live --test e2e -E 'test(e2e_live)'

# Run PyPI system tests without external-service cases.
pypi-system: _project-temp
    PERYX_BIN="$(just _system-test-build composition-pypi)" PERYX_SINGLE_COMPOSITION=1 \
      cargo nextest run -p peryx-pypi-system-tests --tests \
      -E 'not(binary(e2e)) & not(binary(availability)) & not(binary(s3_upload))'

# Run OCI system tests without availability cases.
oci-system: _project-temp
    PERYX_BIN="$(just _system-test-build composition-oci)" PERYX_SINGLE_COMPOSITION=1 \
      cargo nextest run -p peryx-oci-system-tests --tests -E 'not(binary(availability))'

# Run the PyPI S3 upload tests.
s3: _project-temp
    PERYX_BIN="$(just _system-test-build composition-pypi)" PERYX_SINGLE_COMPOSITION=1 \
      cargo nextest run -p peryx-pypi-system-tests --test s3_upload

# Run storage tests backed by S3 containers.
storage-s3: _project-temp _docker-ready
    cargo nextest run -p peryx-storage --features container-tests --test integration

# Run distributed availability tests.
availability: _project-temp
    cargo nextest run -p peryx --features availability-e2e --test availability --test cluster --test observability
    PERYX_BIN="$(just _system-test-build composition-pypi)" PERYX_SINGLE_COMPOSITION=1 \
      cargo nextest run -p peryx-pypi-system-tests --test availability
    PERYX_BIN="$(just _system-test-build composition-oci)" PERYX_SINGLE_COMPOSITION=1 \
      cargo nextest run -p peryx-oci-system-tests --test availability

# Run an availability simulation selection.
simulation filter="all()": _project-temp
    cargo nextest run -p peryx --features sim-campaign --test sim_campaign -E '{{ filter }}'

# Check every feature independently.
features: _project-temp
    cargo check --package peryx --no-default-features --lib
    just _zero-feature-binary
    cargo hack --workspace --exclude peryx --each-feature check --all-targets
    cargo hack --package peryx --each-feature --features composition-pypi check --all-targets
    cargo check --package peryx --no-default-features --features composition-oci --all-targets

# Check that the binary rejects an empty composition.
_zero-feature-binary:
    #!/usr/bin/env bash
    set -euo pipefail
    guard='the peryx binary requires at least one `composition-*` feature'
    if output=$(cargo check --package peryx --no-default-features --bin peryx 2>&1); then
      printf 'the zero-feature peryx binary compiled; it must refuse an empty composition\n' >&2
      exit 1
    fi
    if grep -Fq "$guard" <<<"$output"; then
      exit 0
    fi
    # Neither outcome the contract knows about. Saying so beats reporting a violation the build never
    # got far enough to observe, which reads as "your change broke this" when nothing here ran.
    printf 'unavailable: the zero-feature check could not run, so it proved nothing about this tree\n' >&2
    printf 'cargo stopped for a reason other than the composition guard:\n%s\n' "$output" >&2
    exit 1

# Build the shipped server with one composition feature.
_system-test-build feature: _project-temp
    cargo build --package peryx --bin peryx --no-default-features --features "{{ feature }}" \
      --message-format json-render-diagnostics \
      | jq -er 'if .reason == "compiler-message" then (.message.rendered | stderr | empty) \
        elif .reason == "compiler-artifact" and .target.kind == ["bin"] and .target.name == "peryx" then .executable \
        else empty end'

# Check direct dependency lower bounds.
direct-minimum: _project-temp
    rm -rf .tox/direct-minimum
    rsync -a --exclude .git --exclude .tox --exclude target ./ .tox/direct-minimum/
    cargo +nightly update --manifest-path .tox/direct-minimum/Cargo.toml -Z direct-minimal-versions
    cargo +nightly check --manifest-path .tox/direct-minimum/Cargo.toml --workspace --all-targets
    rm -rf .tox/direct-minimum

# Interpret pure core crates with Miri.
miri: _project-temp
    TMPDIR="${RUNNER_TEMP:-/tmp}" cargo +nightly miri test --package peryx-core --lib --tests
    TMPDIR="${RUNNER_TEMP:-/tmp}" cargo +nightly miri test --package peryx-pql --lib --tests
    TMPDIR="${RUNNER_TEMP:-/tmp}" cargo +nightly miri test --package peryx-policy --lib --tests

# Check distributed runtime interleavings with Loom.
loom: _project-temp
    RUSTFLAGS="--cfg peryx_loom" cargo test --package peryx-ha-distributed --lib runtime_worker::loom_tests

# Run AddressSanitizer against a workspace partition.
sanitizer-address partition="slice:1/1": test-deps
    ASAN_OPTIONS=allow_addr2line=1 RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-Zsanitizer=address" \
      PATH="{{ tools_root }}/bin:$PATH" \
      cargo +nightly nextest run -Z build-std --workspace --target x86_64-unknown-linux-gnu \
      --features peryx/process-fixture --profile ci --build-jobs 1 --test-threads 1 \
      --partition "{{ partition }}" -E 'not(test(e2e_live))'

# Build the AddressSanitizer test archive.
sanitizer-archive archive: _project-temp
    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-Zsanitizer=address" PATH="{{ tools_root }}/bin:$PATH" \
      cargo +nightly nextest archive -Z build-std --workspace --target x86_64-unknown-linux-gnu \
      --features peryx/process-fixture --profile ci --build-jobs 1 --archive-file "{{ archive }}"

# Run a partition from an AddressSanitizer archive.
sanitizer-run archive partition="slice:1/1": test-deps
    #!/usr/bin/env bash
    set -euo pipefail
    scratch=$(mktemp -d "{{ project_tmp }}/sanitizer.XXXXXX")
    trap 'rm -rf "$scratch"' EXIT
    binary=$("{{ just_executable() }}" _archive-peryx-binary "{{ archive }}")
    ASAN_OPTIONS=allow_addr2line=1 PERYX_BIN="$scratch/target/$binary" \
      PATH="{{ tools_root }}/bin:$PATH" cargo +nightly nextest run \
      --archive-file "{{ archive }}" --extract-to "$scratch" \
      --workspace-remap "{{ justfile_directory() }}" --profile ci --test-threads 1 \
      --partition "{{ partition }}" -E 'not(test(e2e_live))'

# Run one cargo-fuzz target.
fuzz package target seconds="60": _project-temp
    cd "crates/{{ package }}/fuzz" && cargo +nightly fuzz run \
      --target "$(rustc +nightly --print host-tuple)" "{{ target }}" -- -max_total_time="{{ seconds }}"

# Mutate one workspace shard.
mutation shard="0/1" in_place="false" jobs="2" baseline="run" timeout="500" sharding="slice": test-deps
    CARGO_INCREMENTAL=0 CARGO_PROFILE_TEST_DEBUG=0 PATH="{{ tools_root }}/bin:$PATH" \
      cargo mutants --workspace --all-features --test-tool nextest \
      --no-shuffle --shard "{{ shard }}" --sharding "{{ sharding }}" --output .tox/mutants \
      {{ if in_place == "true" { "--in-place" } else { "--jobs " + jobs } }} \
      --jobserver-tasks "{{ jobs }}" --baseline "{{ baseline }}" \
      --timeout "{{ timeout }}" --build-timeout "{{ timeout }}" \
      -- --profile mutation -E 'not(test(e2e_live))'

# Run one mutation shard with Linux resource telemetry.
mutation-observed shard="0/1" in_place="false" jobs="2" baseline="run" timeout="500" sharding="slice":
    #!/usr/bin/env bash
    set -uo pipefail
    cgroup_root="/sys/fs/cgroup$(awk -F: '$1 == "0" { print $3 }' /proc/self/cgroup 2>/dev/null)"
    if [[ ! -r "$cgroup_root/cgroup.controllers" ]]; then
      printf 'mutation resource telemetry requires Linux cgroup v2\n' >&2
      exit 2
    fi
    # cargo-mutants creates mutants.out inside the output directory, and the shard uploads that
    # directory, so a trace written beside it reaches the artifact. A job log does not: every log
    # from a run whose shards executed already answers BlobNotFound.
    mkdir -p .tox/mutants
    trace=.tox/mutants/resource.log
    sample() {
      local metric pressure progress
      if [[ -r .tox/mutants/mutants.out/outcomes.json ]]; then
        progress="$(jq -c '{
          completed: (.outcomes | length),
          last: (.outcomes[-1].scenario.Mutant.name //
            (if (.outcomes | length) > 0 then (.outcomes[-1].scenario | tostring) else null end))
        }' .tox/mutants/mutants.out/outcomes.json 2>/dev/null || printf '{"completed":null,"last":null}')"
      else
        progress='{"completed":0,"last":null}'
      fi
      printf 'mutation-resource timestamp=%s progress=%s' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$progress"
      # The cgroup counts this job's own process tree. What starves a hosted runner is what the
      # machine has left, and its 14 GB disk is the smallest of the three resources it publishes.
      if [[ -r /proc/meminfo ]]; then
        printf ' memory.available=%s' "$(awk '$1 == "MemAvailable:" { print $2 * 1024 }' /proc/meminfo)"
      fi
      df -P -B1 . | awk 'NR == 2 { printf " disk.total=%s disk.available=%s", $2, $4 }'
      for metric in memory.current memory.peak pids.current; do
        if [[ -r "$cgroup_root/$metric" ]]; then
          printf ' %s=%s' "$metric" "$(<"$cgroup_root/$metric")"
        fi
      done
      for metric in memory.events pids.events; do
        if [[ -r "$cgroup_root/$metric" ]]; then
          printf ' %s=%s' "$metric" "$(awk '{printf "%s%s=%s", NR == 1 ? "" : ",", $1, $2}' "$cgroup_root/$metric")"
        fi
      done
      for pressure in cpu memory io; do
        if [[ -r "/proc/pressure/$pressure" ]]; then
          printf ' %s.pressure=%s' "$pressure" "$(paste -sd ';' "/proc/pressure/$pressure")"
        fi
      done
      printf '\n'
    }
    record() { sample | tee -a "$trace"; }
    record
    while sleep 60; do record; done &
    monitor_pid=$!
    trap 'kill "$monitor_pid" 2>/dev/null || :; wait "$monitor_pid" 2>/dev/null || :' EXIT
    just mutation "{{ shard }}" "{{ in_place }}" "{{ jobs }}" "{{ baseline }}" "{{ timeout }}" "{{ sharding }}"
    mutation_status=$?
    record
    printf 'mutation-exit status=%d\n' "$mutation_status" | tee -a "$trace"
    exit "$mutation_status"

# Run the mutation baseline suite.
mutation-baseline: test-deps
    INSTA_UPDATE=no INSTA_FORCE_PASS=0 PATH="{{ tools_root }}/bin:$PATH" cargo nextest run --verbose \
      --workspace --all-features --profile ci -E 'not(test(e2e_live))'

# Build the mutation baseline test archive.
mutation-baseline-archive archive: _project-temp
    cargo nextest archive --workspace --all-features --profile ci --archive-file "{{ archive }}"

# Run a partition from the mutation baseline archive.
mutation-baseline-run archive partition="slice:1/1": test-deps
    #!/usr/bin/env bash
    set -euo pipefail
    scratch=$(mktemp -d "{{ project_tmp }}/mutation-baseline.XXXXXX")
    trap 'rm -rf "$scratch"' EXIT
    binary=$("{{ just_executable() }}" _archive-peryx-binary "{{ archive }}")
    INSTA_UPDATE=no INSTA_FORCE_PASS=0 PERYX_BIN="$scratch/target/$binary" \
      PATH="{{ tools_root }}/bin:$PATH" cargo nextest run \
      --archive-file "{{ archive }}" --extract-to "$scratch" \
      --workspace-remap "{{ justfile_directory() }}" --profile ci \
      --partition "{{ partition }}" -E 'not(test(e2e_live))'

# Count workspace mutation candidates.
mutation-count: _project-temp
    cargo mutants --list --workspace --all-features | wc -l

# Calculate the shard count for a mutant total and per-shard target.
mutation-shard-count mutants target:
    #!/usr/bin/env bash
    set -euo pipefail
    mutants={{ quote(mutants) }}
    target={{ quote(target) }}
    if ! [[ "$mutants" =~ ^[1-9][0-9]*$ && "$target" =~ ^[1-9][0-9]*$ ]]; then
      printf 'mutants and target must be positive integers\n' >&2
      exit 1
    fi
    printf '%d\n' "$(( (mutants + target - 1) / target ))"

# Install browser-test dependencies for the shared and owner suites.
frontend-deps: _project-temp _mise-trusted
    MISE_ENV=browser mise install --locked http:playwright-headless-shell
    npm --prefix crates/peryx-web/tests/frontend ci
    npm --prefix crates/peryx-ecosystem-pypi/tests/frontend ci
    npm --prefix crates/peryx-ecosystem-oci/tests/frontend ci

# Run the shared and owner browser suites, installing and building whatever they are missing.
frontend-test: _project-temp _mise-trusted
    #!/usr/bin/env bash
    set -euo pipefail
    # Every suite runs even after an earlier one fails, so a single CI round reports all three;
    # the recipe then exits non-zero if any of them failed. Collecting the statuses is what
    # buys that: left uncollected, `set -e` ends the run at the first broken suite, and the two
    # larger suites are the ones most likely to break.
    suites=(
      crates/peryx-web/tests/frontend
      crates/peryx-ecosystem-pypi/tests/frontend
      crates/peryx-ecosystem-oci/tests/frontend
    )
    if ! shell_root=$(MISE_ENV=browser mise where http:playwright-headless-shell 2>/dev/null); then
      MISE_ENV=browser mise install --locked http:playwright-headless-shell
      shell_root=$(MISE_ENV=browser mise where http:playwright-headless-shell)
    fi
    browser="$shell_root/chrome-headless-shell"
    if [[ -f "$browser.exe" ]]; then
      browser="$browser.exe"
    fi
    export PERYX_PLAYWRIGHT_BROWSER_PATH="${PERYX_PLAYWRIGHT_BROWSER_PATH:-$browser}"
    # `export VAR="$(cmd)"` reports the status of `export`, so the lookup gets its own assignment.
    version=$(MISE_ENV=browser mise current http:playwright-headless-shell)
    export PERYX_PLAYWRIGHT_BROWSER_VERSION="$version"
    # A suite installs when it has no runner or its lock file has moved on, so a fresh worktree runs
    # the gate instead of reporting a tool it never had. An installed suite skips the work, which is
    # what keeps the `frontend-deps` step CI runs first from paying for it twice.
    for suite in "${suites[@]}"; do
      if [[ ! -x "$suite/node_modules/.bin/playwright" ]] \
        || [[ "$suite/package-lock.json" -nt "$suite/node_modules/.package-lock.json" ]]; then
        npm --prefix "$suite" ci
      fi
      if [[ ! -x "$suite/node_modules/.bin/playwright" ]]; then
        printf 'browser suite %s still has no Playwright runner after npm ci\n' "$suite" >&2
        exit 1
      fi
    done
    # A caller that has already built names its binary, as the coverage run does with its instrumented
    # copy. Building only when it has not is what lets a fresh worktree run the gate without making CI
    # build a second server it would not use.
    if [[ -z "${PERYX_FRONTEND_BINARY:-}" ]]; then
      cargo leptos build
    fi
    failed=()
    for suite in "${suites[@]}"; do
      # The suite's own runner rather than whatever `playwright` resolves to: the one on PATH is a
      # different tool that rejects `test`, so a lane reaching it debugs that instead of the install.
      (cd "$suite" && ./node_modules/.bin/playwright test --config playwright.config.mjs) || failed+=("$suite")
    done
    if (( ${#failed[@]} > 0 )); then
      printf 'browser suite failed: %s\n' "${failed[@]}" >&2
      exit 1
    fi

# Print tool versions used by local and container validation.
versions: _project-temp
    rustc --version
    cargo --version
    cargo nextest --version
    cargo llvm-cov --version
    just --version
    node --version
    npm --version

# Refresh locked mise tool versions and checksums.
mise-lock: _mise-trusted
    mise lock --bump
    MISE_ENV=browser mise lock --bump --platform linux-x64,macos-arm64,macos-x64,windows-x64

# Update browser packages, verified archives, and rendered diagrams.
browser-update:
    #!/usr/bin/env bash
    set -euo pipefail
    PUPPETEER_SKIP_DOWNLOAD=1 npm --prefix site install --save-dev --save-exact \
      puppeteer@npm:puppeteer-core@latest
    for directory in \
      crates/peryx-web/tests/frontend \
      crates/peryx-ecosystem-pypi/tests/frontend \
      crates/peryx-ecosystem-oci/tests/frontend; do
      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm --prefix "$directory" install --save-dev --save-exact \
        @playwright/test@latest
    done
    if just _browser-contract >/dev/null 2>&1; then exit; fi
    just browser-lock

# Rebuild the browser lock from package release metadata.
browser-lock: _mise-trusted
    #!/usr/bin/env bash
    set -euo pipefail
    PUPPETEER_SKIP_DOWNLOAD=1 npm --prefix site ci
    for directory in \
      crates/peryx-web/tests/frontend \
      crates/peryx-ecosystem-pypi/tests/frontend \
      crates/peryx-ecosystem-oci/tests/frontend; do
      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm --prefix "$directory" ci
    done
    node --input-type=module <<'NODE'
    import { createHash } from "node:crypto";
    import { readFile, writeFile } from "node:fs/promises";
    import { createRequire } from "node:module";
    import { dirname, join, resolve } from "node:path";
    import { pathToFileURL } from "node:url";

    const frontends = [
      "crates/peryx-web/tests/frontend",
      "crates/peryx-ecosystem-pypi/tests/frontend",
      "crates/peryx-ecosystem-oci/tests/frontend",
    ];
    const readJson = async (file) => JSON.parse(await readFile(file, "utf8"));
    const playwrightPackages = await Promise.all(
      frontends.map(async (directory) => ({
        manifest: (await readJson(join(directory, "package.json"))).devDependencies[
          "@playwright/test"
        ],
        lock: (await readJson(join(directory, "package-lock.json"))).packages[
          "node_modules/@playwright/test"
        ].version,
      })),
    );
    if (new Set(playwrightPackages.flatMap(Object.values)).size !== 1)
      throw new Error("Playwright package revisions differ");
    const playwrightPackage = playwrightPackages[0].manifest;
    const playwrightRequire = createRequire(
      resolve(frontends[0], "package.json"),
    );
    const playwrightBrowser = (await readJson(
      join(
        dirname(playwrightRequire.resolve("playwright-core/package.json")),
        "browsers.json",
      ),
    )).browsers.find(({ name }) => name === "chromium-headless-shell").browserVersion;
    const site = await readJson("site/package.json");
    const puppeteerPackage = site.devDependencies.puppeteer.replace(
      "npm:puppeteer-core@",
      "",
    );
    const siteRequire = createRequire(resolve("site/package.json"));
    const { PUPPETEER_REVISIONS } = await import(
      pathToFileURL(siteRequire.resolve("puppeteer/internal/revisions.js"))
    );
    const puppeteerBrowser = PUPPETEER_REVISIONS.chrome;
    const platforms = new Map([
      ["linux-x64", "linux64"],
      ["macos-arm64", "mac-arm64"],
      ["macos-x64", "mac-x64"],
      ["windows-x64", "win64"],
    ]);
    async function browser(version) {
      const metadataResponse = await fetch(
        `https://googlechromelabs.github.io/chrome-for-testing/${version}.json`,
      );
      if (!metadataResponse.ok) throw new Error(`missing Chrome for Testing ${version}`);
      const metadata = await metadataResponse.json();
      return Promise.all(
        [...platforms].map(async ([misePlatform, chromePlatform]) => {
          const url = metadata.downloads["chrome-headless-shell"].find(
            ({ platform }) => platform === chromePlatform,
          )?.url;
          const prefix = `https://storage.googleapis.com/chrome-for-testing-public/${version}/`;
          if (!url?.startsWith(prefix)) throw new Error(`unexpected ${chromePlatform} URL`);
          const response = await fetch(url);
          if (!response.ok) throw new Error(`failed to download ${url}`);
          const hash = createHash("sha256");
          for await (const chunk of response.body) hash.update(chunk);
          return [misePlatform, url, hash.digest("hex")];
        }),
      );
    }
    const tools = [
      ["playwright", playwrightPackage, playwrightBrowser],
      ["puppeteer", puppeteerPackage, puppeteerBrowser],
    ];
    const archives = await Promise.all(tools.map(([, , version]) => browser(version)));
    const lines = ["[env]"];
    for (const [name, packageVersion, browserVersion] of tools) {
      const prefix = `PERYX_${name.toUpperCase()}`;
      lines.push(`${prefix}_PACKAGE_VERSION = "${packageVersion}"`);
      lines.push(`${prefix}_BROWSER_VERSION = "${browserVersion}"`);
    }
    for (const [index, [name, , version]] of tools.entries()) {
      const entries = archives[index];
      lines.push(
        "",
        `[tools."http:${name}-headless-shell"]`,
        `version = "${version}"`,
        "strip_components = 1",
        "",
        `[tools."http:${name}-headless-shell".platforms]`,
        ...entries.map(
          ([platform, url, checksum]) =>
            `${platform} = { url = "${url}", checksum = "sha256:${checksum}" }`,
        ),
      );
    }
    await writeFile("mise.browser.toml", `${lines.join("\n")}\n`);
    NODE
    MISE_ENV=browser mise lock --platform linux-x64,macos-arm64,macos-x64,windows-x64 \
      http:playwright-headless-shell http:puppeteer-headless-shell
    just render-diagrams

# Build and test the browser application.
frontend: frontend-deps _project-temp
    just frontend-test

# Serve the documentation source.
site-dev: _project-temp
    zola --root site serve --interface 127.0.0.1

# Write the workspace dependency graph as Mermaid source.
crate-dependency-diagram output="site/diagrams/crate-dependencies.mmd": _project-temp
    #!/usr/bin/env bash
    set -euo pipefail
    case "{{ output }}" in
      site/diagrams/crate-dependencies.mmd|.tox/site/crate-dependencies.mmd) ;;
      *) printf 'unsupported diagram output: %s\n' "{{ output }}" >&2; exit 1 ;;
    esac
    mkdir -p "$(dirname "{{ output }}")"
    {
    printf '%s\n' '---' 'config:' '  layout: elk' '  elk:' '    mergeEdges: true' '---'
    printf 'flowchart TD\n'
    # LC_ALL=C on the sort below: a UTF-8 collation orders `[` and `_` differently, so a
    # developer machine regenerates a file that differs from CI's and the staleness check
    # in `diagrams` fails against a correct committed diagram.
    cargo metadata --format-version 1 --no-deps | jq -r '
      (.packages | map(.name) | unique) as $workspace
      | ($workspace[] | "  \(gsub("-"; "_"))[\(. | @json)]"),
        (.packages[] | .name as $source | .dependencies[]
          | select(.kind == null and .path != null)
          | select(.name as $dependency | $workspace | index($dependency))
          | "  \($source | gsub("-"; "_")) --> \(.name | gsub("-"; "_"))")
    ' | LC_ALL=C sort -u
    printf '  class peryx accent\n'
    printf '  class peryx_ecosystem_oci,peryx_ecosystem_pypi good\n'
    printf '  class peryx_oci_system_tests,peryx_pypi_system_tests warn\n'
    } > "{{ output }}"

# Pre-render every Mermaid diagram for light and dark themes.
render-diagrams output="site/static/diagrams": _project-temp _mise-trusted
    #!/usr/bin/env bash
    set -euo pipefail
    case "{{ output }}" in
      site/static/diagrams|.tox/site/diagrams) ;;
      *) printf 'unsupported diagram output: %s\n' "{{ output }}" >&2; exit 1 ;;
    esac
    MISE_ENV=browser mise install --locked http:puppeteer-headless-shell
    browser=$(MISE_ENV=browser mise where http:puppeteer-headless-shell)/chrome-headless-shell
    [[ -f "$browser.exe" ]] && browser="$browser.exe"
    export PERYX_PUPPETEER_BROWSER_PATH="${PERYX_PUPPETEER_BROWSER_PATH:-$browser}"
    export PERYX_PUPPETEER_BROWSER_VERSION="$(MISE_ENV=browser mise current http:puppeteer-headless-shell)"
    npm --prefix site ci
    rm -rf "{{ output }}"
    mkdir -p "{{ output }}"
    (
      cd site
      node --input-type=module - "../{{ output }}" <<'NODE'
    import { readdir, readFile } from "node:fs/promises";
    import { basename, join } from "node:path";
    import { run } from "@mermaid-js/mermaid-cli";
    import puppeteer from "puppeteer";
    import { PUPPETEER_REVISIONS } from "puppeteer/internal/revisions.js";

    const output = process.argv[2];
    const sources = (await readdir("diagrams", { withFileTypes: true }))
      .filter((entry) => entry.isFile() && entry.name.endsWith(".mmd"))
      .map((entry) => join("diagrams", entry.name))
      .sort();
    const themes = await Promise.all(
      ["light", "dark"].map(async (name) => ({
        name,
        config: JSON.parse(await readFile(`diagrams/${name}.json`, "utf8")),
      })),
    );
    // Ubuntu grants unprivileged user namespaces only to AppArmor-profiled paths, which the locked
    // browser is not one of, so its zygote sandbox cannot start. Playwright drops the sandbox for the
    // same reason; both only ever load local files.
    const browser = await puppeteer.launch({
      args: ["--no-sandbox"],
      executablePath: process.env.PERYX_PUPPETEER_BROWSER_PATH,
      headless: "shell",
    });
    try {
      if (PUPPETEER_REVISIONS.chrome !== process.env.PERYX_PUPPETEER_BROWSER_VERSION)
        throw new Error("Puppeteer and its browser revision differ");
      if ((await browser.version()) !== `HeadlessChrome/${PUPPETEER_REVISIONS.chrome}`)
        throw new Error("unexpected browser version");
      for (const source of sources) {
        const name = basename(source, ".mmd");
        for (const theme of themes) {
          await run(source, `${output}/${name}-${theme.name}.svg.tmp.svg`, {
            browser,
            outputFormat: "svg",
            parseMMDOptions: {
              backgroundColor: "transparent",
              iconPacks: [],
              iconPacksNamesAndUrls: [],
              mermaidConfig: { theme: "default", ...theme.config },
              svgId: `peryx-${name}-${theme.name}`,
              viewport: { width: 800, height: 600, deviceScaleFactor: 1 },
            },
            quiet: true,
          });
        }
      }
    } finally {
      await browser.close();
    }
    NODE
    )
    for source in site/diagrams/*.mmd; do
      name=$(basename "$source" .mmd)
      for theme in light dark; do
        rendered="{{ output }}/$name-$theme.svg"
        digest=$(
          shasum -a 256 "$source" "site/diagrams/$theme.json" site/package-lock.json \
            mise.browser.toml \
            | shasum -a 256 | cut -d ' ' -f 1
        )
        { printf '<!-- peryx-mermaid-input-sha256=%s -->\n' "$digest"; awk '1' "$rendered.tmp.svg"; } > "$rendered"
        rm "$rendered.tmp.svg"
      done
    done

# Check every pre-rendered Mermaid diagram against its source.
diagrams: _project-temp
    #!/usr/bin/env bash
    set -euo pipefail
    just crate-dependency-diagram .tox/site/crate-dependencies.mmd
    cmp site/diagrams/crate-dependencies.mmd .tox/site/crate-dependencies.mmd || \
      (printf 'crate dependency diagram is stale; run just crate-dependency-diagram\n' >&2; exit 1)
    just render-diagrams .tox/site/diagrams
    diff <(find site/static/diagrams -maxdepth 1 -type f -name '*.svg' -exec basename {} \; | sort) \
      <(find .tox/site/diagrams -maxdepth 1 -type f -name '*.svg' -exec basename {} \; | sort)
    for rendered in .tox/site/diagrams/*.svg; do
      committed="site/static/diagrams/$(basename "$rendered")"
      cmp <(sed -n '1p' "$committed") <(sed -n '1p' "$rendered") || \
        (printf '%s is stale; run just render-diagrams\n' "$committed" >&2; exit 1)
    done

# Regenerate the committed OpenAPI document the site serves.
openapi: _project-temp
    cargo run --quiet --package peryx --bin peryx -- openapi > site/static/openapi.json

# Build and validate the documentation site.
docs: diagrams
    zola --root site check --skip-external-links
    zola --root site build --force --output-dir "{{ justfile_directory() }}/.tox/site/public"
    cargo run --quiet --package peryx --bin peryx -- openapi > .tox/site/openapi.json
    cmp site/static/openapi.json .tox/site/openapi.json || \
      (printf 'site/static/openapi.json is stale; run just openapi\n' >&2; exit 1)
    npm --prefix site exec -- pagefind --site "{{ justfile_directory() }}/.tox/site/public" \
      --include-characters "_./-"

# Check external documentation links with Zola's checker.
site-links: _project-temp
    zola --root site check

# Build the documentation site.
site: docs

# Build the documentation site for Read the Docs.
site-readthedocs:
    : "${READTHEDOCS_CANONICAL_URL:?}"
    : "${READTHEDOCS_OUTPUT:?}"
    mkdir -p "$READTHEDOCS_OUTPUT/html"
    zola --root site build --base-url "$READTHEDOCS_CANONICAL_URL" --force \
      --output-dir "$READTHEDOCS_OUTPUT/html"
    npm --prefix site exec -- pagefind --site "$READTHEDOCS_OUTPUT/html" \
      --include-characters "_./-"

# Validate the cargo-dist release plan.
release-plan: _project-temp
    dist plan --output-format=json > /dev/null

# Run the OCI distribution-spec conformance suite.
conformance suite binary="": _project-temp
    #!/usr/bin/env bash
    set -euo pipefail
    suite="{{ suite }}"
    mkdir -p "$(dirname "$suite")"
    suite="$(cd "$(dirname "$suite")" && pwd -P)/$(basename "$suite")"
    cargo build --bin peryx
    peryx="{{ binary }}"
    target=$(cargo metadata --no-deps --format-version 1 | jq -r .target_directory)
    peryx="${peryx:-$target/debug/peryx}"
    scratch=$(mktemp -d "{{ project_tmp }}/conformance.XXXXXX")
    mkdir "$scratch/tmp" "$scratch/go-build" "$scratch/go-mod"
    export TMPDIR="$scratch/tmp" TMP="$scratch/tmp" TEMP="$scratch/tmp"
    export GOCACHE="$scratch/go-build" GOMODCACHE="$scratch/go-mod"
    server_pid=
    cleanup() {
      status=$?
      trap - EXIT
      if [[ -n $server_pid ]] && kill -0 "$server_pid" 2>/dev/null; then
        kill "$server_pid"
        wait "$server_pid" || true
      fi
      cleanup_status=0
      go clean -modcache || cleanup_status=$?
      rm -rf "$scratch" || cleanup_status=$?
      ((status != 0)) && exit "$status"
      exit "$cleanup_status"
    }
    trap cleanup EXIT
    git -C "$scratch" init --quiet checkout
    git -C "$scratch/checkout" remote add origin https://github.com/opencontainers/distribution-spec
    git -C "$scratch/checkout" fetch --quiet --depth=1 origin fcfba1ec55526073f48b2f6d4e3d7eef410ddcbc
    git -C "$scratch/checkout" checkout --quiet --detach FETCH_HEAD
    go -C "$scratch/checkout/conformance" build -o "$suite" .
    cat >"$scratch/peryx.toml" <<EOF
    host = "127.0.0.1"
    port = 0
    data_dir = "$scratch/data"

    [log]
    format = "json"

    [[index]]
    name = "store"
    route = "store"
    ecosystem = "oci"
    hosted = true

    [[index.access_token]]
    name = "uploader"
    secret = "conformance"
    actions = ["write", "delete"]
    EOF
    "$peryx" serve --config "$scratch/peryx.toml" >"$scratch/server.log" 2>&1 &
    server_pid=$!
    port=
    for _ in {1..150}; do
      port=$(jq -r 'select(.fields.message == "peryx listening") | .fields.addr |
        capture(":(?<port>[0-9]+)$").port' "$scratch/server.log" 2>/dev/null | head -1)
      if [[ -n $port ]]; then
        break
      fi
      kill -0 "$server_pid" 2>/dev/null || break
      sleep 0.2
    done
    if [[ -z $port ]] || ! curl --fail --silent "http://127.0.0.1:$port/v2/" >/dev/null; then
      cat "$scratch/server.log" >&2
      exit 1
    fi
    (cd "$scratch" && OCI_REGISTRY="127.0.0.1:$port" OCI_TLS=disabled \
      OCI_REPO1=store/conformance OCI_REPO2=store/crossmount OCI_USERNAME=_ \
      OCI_PASSWORD=conformance OCI_DATA_SHA512=false "$suite")

# Build one package selection's CodSpeed benchmarks.
codspeed-build package suite mode="simulation": _project-temp
    #!/usr/bin/env bash
    set -euo pipefail
    flags=()
    case "{{ suite }}" in
      parsing) flags=(--no-default-features) ;;
      serving) flags=(--features bench --bench serve --bench transform) ;;
    esac
    cargo codspeed build --locked -m "{{ mode }}" --package "{{ package }}" "${flags[@]}"

# Run one package's built CodSpeed benchmarks.
codspeed-run package mode="simulation": _project-temp
    cargo codspeed run -m "{{ mode }}" --package "{{ package }}"

# Build and run one package's CodSpeed benchmarks locally.
codspeed package mode="simulation": _project-temp
    suites=(all); \
    if [[ "{{ package }}" == peryx-ecosystem-pypi ]]; then suites=(parsing serving); fi; \
    for suite in "${suites[@]}"; do \
      just codspeed-build "{{ package }}" "$suite" "{{ mode }}"; \
      just codspeed-run "{{ package }}" "{{ mode }}"; \
    done

# Build a local Python wheel.
package-wheel +args: _project-temp
    maturin build --release --locked --out dist {{ args }}

# Build a local source distribution.
package-sdist output="dist": _project-temp
    maturin sdist --out "{{ output }}"

# Measure native Rust coverage.
coverage-native output=".tox/coverage/native.lcov" gaps=".tox/coverage/native-gaps.json": test-deps _docker-ready
    #!/usr/bin/env bash
    set -euo pipefail
    output="{{ output }}"
    mkdir -p "$(dirname "$output")" "{{ project_tmp }}"
    cargo llvm-cov clean --workspace
    cargo llvm-cov --workspace --all-features --bench '*' --no-report
    PERYX_BIN="{{ native_coverage_binary }}" \
      PATH="{{ tools_root }}/bin:$PATH" cargo llvm-cov nextest --workspace \
      --all-features --profile ci --lib --bins --tests --examples \
      -E 'not(test(e2e_live))' --no-report
    ignore='/(\.cargo/(registry|git)|\.rustup/toolchains|rustc/[0-9a-f]+)/'
    cargo llvm-cov report --no-default-ignore-filename-regex --ignore-filename-regex "$ignore" \
      --lcov --output-path "$output"
    # `--fail-uncovered-lines` counts a line no function reached, and every line it has named was a
    # real gap. What it does not see is a function body nothing ran whose lines a covered caller
    # spans, so `coverage-lines` is paired with it. LLVM's own line total is not usable as that pair:
    # it scores an instantiation group by taking the mapped and covered counts from whichever
    # monomorphization is highest at each, on its own, so a line one monomorphization runs and
    # another does not counts as missed while executing. That described 66 of the 88 lines the total
    # reported here.
    #
    # The gaps are written rather than failed on: a body reached only from the browser runs in the
    # target `coverage-frontend` measures, so the two are unioned in `coverage-lines`.
    cargo llvm-cov report --no-default-ignore-filename-regex --ignore-filename-regex "$ignore" \
      --fail-uncovered-lines 0 --show-missing-lines
    cargo llvm-cov report --no-default-ignore-filename-regex --ignore-filename-regex "$ignore" \
      --json --output-path "{{ project_tmp }}/coverage.json"
    python3 coverage_lines.py gaps "{{ project_tmp }}/coverage.json" "{{ gaps }}"

# Fail on a line no configuration ran, unioning the native gaps with what the browser target covered.
coverage-lines gaps=".tox/coverage/native-gaps.json" frontend_native=".tox/coverage/frontend-native.lcov" frontend_wasm=".tox/coverage/frontend-wasm.lcov":
    python3 coverage_lines.py check "{{ gaps }}" "{{ frontend_native }}" "{{ frontend_wasm }}"

# Measure native and Wasm frontend coverage.
coverage-frontend native_output=".tox/coverage/frontend-native.lcov" wasm_output=".tox/coverage/frontend-wasm.lcov" merged_output=".tox/coverage/frontend.lcov": _project-temp
    #!/usr/bin/env bash
    set -euo pipefail
    native_output="{{ native_output }}"
    wasm_output="{{ wasm_output }}"
    merged_output="{{ merged_output }}"
    mkdir -p "$(dirname "$native_output")" "$(dirname "$wasm_output")" "$(dirname "$merged_output")"
    rm -f "$native_output" "$wasm_output" "$merged_output"
    scratch=$(mktemp -d "{{ project_tmp }}/coverage-frontend.XXXXXX")
    trap 'rm -rf "$scratch"' EXIT
    commit_date=$(rustc -vV | awk '/^commit-date:/ { print $2 }')
    toolchain="nightly-$commit_date"
    rustup toolchain install "$toolchain" --profile minimal --component llvm-tools-preview \
      --target wasm32-unknown-unknown
    stable_llvm=$(rustc -vV | awk '/^LLVM version:/ { split($3, version, "."); print version[1] }')
    nightly_llvm=$(rustc +"$toolchain" -vV | awk '/^LLVM version:/ { split($3, version, "."); print version[1] }')
    if [[ $stable_llvm != "$nightly_llvm" ]]; then
      printf 'stable LLVM %s does not match %s LLVM %s\n' "$stable_llvm" "$toolchain" "$nightly_llvm" >&2
      exit 1
    fi
    if [[ -n ${CLANG:-} ]]; then
      clang=$(command -v "$CLANG")
    elif clang=$(command -v "clang-$nightly_llvm" 2>/dev/null); then
      :
    elif command -v brew >/dev/null; then
      clang="$(brew --prefix llvm)/bin/clang"
    else
      printf 'clang %s is required for Wasm coverage\n' "$nightly_llvm" >&2
      exit 1
    fi
    clang_llvm=$($clang --version | sed -E -n '1s/.*version ([0-9]+).*/\1/p')
    if [[ $clang_llvm != "$nightly_llvm" ]]; then
      printf 'clang LLVM %s does not match %s LLVM %s\n' "$clang_llvm" "$toolchain" "$nightly_llvm" >&2
      exit 1
    fi
    export PATH="$(dirname "$clang"):$PATH"
    sysroot=$(rustc +"$toolchain" --print sysroot)
    host=$(rustc +"$toolchain" -vV | awk '/^host:/ { print $2 }')
    export LLVM_COV="$sysroot/lib/rustlib/$host/bin/llvm-cov"
    export LLVM_PROFDATA="$sysroot/lib/rustlib/$host/bin/llvm-profdata"
    export CARGO_TARGET_DIR="{{ env_var_or_default("CARGO_TARGET_DIR", coverage_target_root) }}/frontend"
    export CARGO_LLVM_COV_BUILD_DIR="$CARGO_TARGET_DIR"
    export CARGO_LLVM_COV_TARGET_DIR="$CARGO_TARGET_DIR"
    eval "$(cargo llvm-cov show-env --sh --no-cfg-coverage)"
    cargo llvm-cov clean --workspace
    cargo nextest run --package peryx-web --all-features --lib
    cargo llvm-cov report --no-default-ignore-filename-regex --lcov \
      --output-path "$scratch/native-unit.lcov"
    export RUSTUP_TOOLCHAIN="$toolchain"
    export CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUSTFLAGS="-Zno-profiler-runtime --cfg=wasm_bindgen_unstable_test_coverage"
    unset RUSTFLAGS
    target=$(cargo metadata --no-deps --format-version 1 | jq -r .target_directory)
    wasm="{{ justfile_directory() }}/.tox/frontend/ui/pkg/peryx_web.wasm"
    mkdir -p "$CARGO_TARGET_DIR" "$scratch/profiles"
    find "$CARGO_TARGET_DIR" -maxdepth 1 -name 'peryx-frontend-*.profraw' -delete
    export LLVM_PROFILE_FILE="$CARGO_TARGET_DIR/peryx-frontend-%p-%10m.profraw"
    cargo leptos build --lib-features wasm-coverage --wasm-debug
    PERYX_FRONTEND_BINARY="$target/debug/peryx" PERYX_WASM_PROFRAW="$scratch/profiles" just frontend-test
    cargo llvm-cov report --no-default-ignore-filename-regex --lcov \
      --output-path "$scratch/native-browser.lcov"
    lcov --quiet --add-tracefile "$scratch/native-unit.lcov" \
      --add-tracefile "$scratch/native-browser.lcov" --output-file "$scratch/native.lcov"
    lcov --quiet --extract "$scratch/native.lcov" "{{ justfile_directory() }}/crates/peryx-web/src/*" \
      --output-file "$native_output"
    if [[ ! -s $wasm ]]; then
      printf 'frontend Wasm binary not found at %s\n' "$wasm" >&2
      exit 1
    fi
    "$LLVM_PROFDATA" merge -sparse "$scratch"/profiles/*.profraw -o "$scratch/wasm.profdata"
    "$LLVM_COV" export --format=lcov --instr-profile "$scratch/wasm.profdata" --object "$wasm" \
      --sources "{{ justfile_directory() }}/crates/peryx-web/src" >"$wasm_output"
    lcov --quiet --add-tracefile "$native_output" --add-tracefile "$wasm_output" \
      --output-file "$merged_output"
    lcov --summary "$merged_output" --fail-under-lines 100

# Measure native and frontend coverage.
coverage output=".tox/coverage": _project-temp
    just coverage-native "{{ output }}/native.lcov" "{{ output }}/native-gaps.json"
    just frontend-deps
    just coverage-frontend "{{ output }}/frontend-native.lcov" \
      "{{ output }}/frontend-wasm.lcov" "{{ output }}/frontend.lcov"
    # Last, because it reads what both halves wrote.
    just coverage-lines "{{ output }}/native-gaps.json" \
      "{{ output }}/frontend-native.lcov" "{{ output }}/frontend-wasm.lcov"

# Remove local Rust coverage build artifacts and locks.
coverage-clean:
    cargo llvm-cov clean --workspace
    rm -rf .tox/coverage .tox/coverage-sessions

# Remove transient project-owned artifacts.
clean: coverage-clean
    rm -rf .tox/bench/scratch .tox/conformance.test .tox/docker/tmp .tox/frontend .tox/site .tox/tmp \
      crates/peryx-ecosystem-oci/tests/frontend/blob-report \
      crates/peryx-ecosystem-oci/tests/frontend/playwright-report \
      crates/peryx-ecosystem-oci/tests/frontend/test-results \
      crates/peryx-ecosystem-pypi/tests/frontend/blob-report \
      crates/peryx-ecosystem-pypi/tests/frontend/playwright-report \
      crates/peryx-ecosystem-pypi/tests/frontend/test-results \
      crates/peryx-web/tests/frontend/blob-report crates/peryx-web/tests/frontend/playwright-report \
      crates/peryx-web/tests/frontend/test-results target-browser ui

# Remove project-owned artifacts, including reusable build state.
clean-all:
    cargo clean
    rm -rf .tox crates/peryx-ecosystem-oci/tests/frontend/node_modules \
      crates/peryx-ecosystem-pypi/tests/frontend/node_modules \
      crates/peryx-web/tests/frontend/node_modules crates/peryx-web/dist site/node_modules

# Run repository hooks against all files.
pre-commit: _project-temp
    prek run --all-files

# Run the complete CI suite.
ci: all

# Run lint, coverage, and documentation checks.
all: lint coverage docs