ktstr 0.4.15

//! Pointwise-claim accumulator API: [`Verdict`], [`ClaimBuilder`],
//! [`SetClaim`], [`SeqClaim`], and the [`claim!`](crate::claim) macro.
//!
//! `Verdict` is the per-test claim accumulator. [`Assert`] holds threshold
//! config and stays `Copy`; `Verdict` carries the per-test claim records
//! (which include `Vec`/`String` allocations) and is built via
//! [`Assert::defaults`]`().verdict()` or [`Verdict::new`].
//!
//! Test authors reach for one of two compile-mechanical labelers:
//!
//!   1. Typed field accessors generated by `#[derive(Claim)]` on stats
//!      structs — e.g. `stats.claim_max_gap_ms(&mut verdict).at_most(100)`.
//!      The label `"max_gap_ms"` comes from `stringify!(max_gap_ms)` in
//!      the generated method body; renaming the field updates both the
//!      method name AND the rendered label.
//!
//!   2. The [`claim!`](crate::claim) macro on a local binding or
//!      expression — e.g. `claim!(verdict, iter_delta).at_least(100)`.
//!      The label comes from `stringify!(<token tree>)` over the
//!      expression tokens.
//!
//! There is NO third "manual string" path. `Verdict` exposes no method
//! that takes a caller-supplied subject string, by design.
//!
//! Comparator surface for [`ClaimBuilder<T>`]:
//!   * `T: PartialOrd + Display` -> `at_least` / `at_most` / `lt` / `gt`
//!     / `between`
//!   * `T: PartialEq + Display`  -> `eq` / `ne`
//!   * `T = f64`                 -> `is_finite` / `near`
//!
//! Container claims (set / sequence) bypass scalar comparators and offer
//! `empty` / `nonempty` / `contains` / `len_eq` / `len_at_most` /
//! `len_at_least` / `subset_of` / `disjoint_from` instead.

use std::collections::BTreeSet;

use super::{Assert, AssertDetail, AssertResult, DetailKind, NoteValue};

/// Pointwise-claim accumulator.
///
/// Carries an [`AssertResult`] under the hood and exposes the same
/// `passed` / `details` / `stats` shape on completion. Build via
/// [`Verdict::new`] or [`Assert::verdict`]; finish with
/// [`Verdict::into_result`].
///
/// ```
/// # use ktstr::assert::{Assert, Verdict};
/// // Empty verdict — no claims, passes.
/// let v = Assert::defaults().verdict();
/// let r = v.into_result();
/// assert!(r.passed);
/// ```
#[must_use = "Verdict accumulates claims; call into_result() to consume"]
#[derive(Debug, Clone)]
pub struct Verdict {
    /// Threshold config the verdict was opened against. Carried so
    /// downstream merge sites (e.g. retrofitted `assert_not_starved`)
    /// can read thresholds out of the verdict directly without an
    /// extra parameter. Optional because [`Verdict::new`] does not
    /// require an `Assert`; tests that only run pointwise claims
    /// don't need a threshold layer attached.
    assert: Option<Assert>,
    /// Underlying [`AssertResult`] envelope — claim records and merged
    /// upstream results write into this. Initialized as a passing
    /// result at `new`; mutates as comparators record outcomes.
    result: AssertResult,
}

impl Default for Verdict {
    /// Equivalent to [`Verdict::new`]: no threshold config attached, no
    /// claims accumulated.
    fn default() -> Self {
        Self::new()
    }
}

impl Verdict {
    /// Empty accumulator with no [`Assert`] attached. Use when a test
    /// is composing pointwise claims and does not care about the
    /// scheduler-level threshold layer.
    pub fn new() -> Self {
        Self {
            assert: None,
            result: AssertResult::pass(),
        }
    }

    /// Empty accumulator carrying `assert` for downstream lookup.
    /// Reached via [`Assert::verdict`]; not part of the test author's
    /// usual entry point.
    pub fn with_assert(assert: Assert) -> Self {
        Self {
            assert: Some(assert),
            result: AssertResult::pass(),
        }
    }

    /// Open a per-claim builder for the named `(subject, value)` pair.
    /// `name` is `&'static str` because the only legitimate sources for
    /// a claim label are `stringify!(field)` (from the
    /// [`#[derive(Claim)]`](ktstr_macros::Claim) generator) and
    /// `stringify!(expr)` (from the [`claim!`](crate::claim) macro) —
    /// both produce static string slices.
    ///
    /// Public so the `#[derive(Claim)]` generator and the `claim!`
    /// macro can dispatch through it; not the recommended user-facing
    /// entry point. Hand-typing `verdict.claim("subject", value)` is
    /// disallowed: a manual string can drift from the value it
    /// labels (rename a field, leave the literal stale), so labels
    /// must originate from `stringify!(field)` or `stringify!(expr)`
    /// via the derive or the macro.
    #[doc(hidden)]
    pub fn claim<T>(&mut self, name: &'static str, value: T) -> ClaimBuilder<'_, T> {
        ClaimBuilder {
            verdict: self,
            name,
            value,
            kind: DetailKind::Other,
            reason: None,
        }
    }

    /// Open a per-claim builder for a set-typed value. Same naming
    /// rules as [`Self::claim`]; the [`#[derive(Claim)]`](ktstr_macros::Claim)
    /// generator emits accessors that route through this dispatch
    /// helper for `BTreeSet<T>` fields.
    #[doc(hidden)]
    pub fn claim_set<'a, T: Ord + std::fmt::Debug>(
        &'a mut self,
        name: &'static str,
        set: &'a BTreeSet<T>,
    ) -> SetClaim<'a, T> {
        SetClaim {
            verdict: self,
            name,
            value: set,
            kind: DetailKind::Other,
            reason: None,
        }
    }

    /// Open a per-claim builder for a sequence-typed value. Same naming
    /// rules as [`Self::claim`]; the [`#[derive(Claim)]`](ktstr_macros::Claim)
    /// generator emits accessors that route through this dispatch
    /// helper for `Vec<T>` and slice fields.
    #[doc(hidden)]
    pub fn claim_seq<'a, T: std::fmt::Debug>(
        &'a mut self,
        name: &'static str,
        seq: &'a [T],
    ) -> SeqClaim<'a, T> {
        SeqClaim {
            verdict: self,
            name,
            value: seq,
            kind: DetailKind::Other,
            reason: None,
        }
    }

    /// Append an informational note to the underlying [`AssertResult`]
    /// without altering the verdict. Mirrors [`AssertResult::note`].
    pub fn note(&mut self, msg: impl Into<String>) -> &mut Self {
        self.result.note(msg);
        self
    }

    /// Attach a structured `(key, value)` measurement to the
    /// underlying [`AssertResult::measurements`] map without
    /// altering the verdict. Mirrors [`AssertResult::note_value`].
    /// Use when a test wants to surface a programmatically
    /// consumable measurement (e.g. `verdict.note_value("max_wchar",
    /// 12345i64)`) alongside pass/fail claims, so sidecar parsers
    /// and `stats compare` dashboards can read the typed value
    /// without re-grepping `details`.
    pub fn note_value(&mut self, key: impl Into<String>, value: impl Into<NoteValue>) -> &mut Self {
        self.result.note_value(key, value);
        self
    }

    /// Mark the verdict as skipped with the supplied reason. Sets
    /// `skipped = true` and records the reason as a
    /// [`DetailKind::Skip`] detail. Use when a precondition is
    /// missing and the scenario cannot run.
    ///
    /// `passed` is preserved: a verdict whose earlier claim failed
    /// (`passed = false`) and then transitions to skip stays
    /// failed. Once a claim records a real failure, masking it
    /// with a later skip would lie to gate callers — the prior
    /// failure is real evidence and must surface. Distinct from
    /// [`AssertResult::skip`], which is a CONSTRUCTOR producing a
    /// fresh passing-skipped envelope from no prior state.
    pub fn skip(&mut self, reason: &'static str) -> &mut Self {
        self.result.skipped = true;
        self.result
            .details
            .push(AssertDetail::new(DetailKind::Skip, reason));
        self
    }

    /// Conditional skip: skip with `reason` when `cond` is true; no-op
    /// otherwise. Convenience over `if cond { v.skip(reason); }`.
    pub fn skip_if(&mut self, cond: bool, reason: &'static str) -> &mut Self {
        if cond {
            self.skip(reason);
        }
        self
    }

    /// Fold an external [`AssertResult`] into this verdict. Useful when
    /// a test combines pointwise claims with the result of an upstream
    /// `assert_*` call (e.g. `assert_not_starved`). Mirrors
    /// [`AssertResult::merge`] semantics — `passed` is conjoined,
    /// `details` concatenate, aggregate stats adopt the worst per
    /// dimension.
    pub fn merge(&mut self, other: AssertResult) -> &mut Self {
        self.result.merge(other);
        self
    }

    /// True iff every claim recorded so far passed and no merged
    /// upstream result reported a failure. Read-only.
    pub fn passed(&self) -> bool {
        self.result.passed
    }

    /// Number of details (failures, notes, skips) recorded so far.
    pub fn detail_count(&self) -> usize {
        self.result.details.len()
    }

    /// Read the [`Assert`] threshold config attached at construction
    /// time, if any. `None` when the verdict was built via
    /// [`Verdict::new`] (no threshold layer).
    pub fn assert(&self) -> Option<&Assert> {
        self.assert.as_ref()
    }

    /// Consume the accumulator and return the merged [`AssertResult`].
    /// Terminal — chain `.into_result()` at the end of a fluent claim
    /// sequence to feed the result into the test return value.
    pub fn into_result(self) -> AssertResult {
        self.result
    }

    /// Internal: record one claim outcome (pass = no detail, fail =
    /// push detail with `kind` and conjoin `passed`). Shared by every
    /// comparator on every builder type.
    fn record(&mut self, outcome: ClaimOutcome) {
        if let ClaimOutcome::Fail { kind, message } = outcome {
            self.result.passed = false;
            self.result.details.push(AssertDetail::new(kind, message));
        }
    }
}

/// Outcome of a single comparator. `Pass` is the no-allocation arm;
/// `Fail` carries the formatted failure message and its [`DetailKind`].
enum ClaimOutcome {
    Pass,
    Fail { kind: DetailKind, message: String },
}

/// Per-claim builder for scalar values. Produced by [`Verdict::claim`]
/// (and the typed `claim_<field>` accessors generated by
/// [`#[derive(Claim)]`](ktstr_macros::Claim)). Chain a comparator
/// (`at_least`, `at_most`, `lt`, `gt`, `between`, `eq`, `ne`,
/// `is_finite`, `near`) to record the outcome.
#[must_use = "ClaimBuilder records nothing until a comparator is invoked"]
pub struct ClaimBuilder<'a, T> {
    verdict: &'a mut Verdict,
    name: &'static str,
    value: T,
    kind: DetailKind,
    reason: Option<&'a str>,
}

impl<'a, T> ClaimBuilder<'a, T> {
    /// Override the [`DetailKind`] used on failure. Defaults to
    /// [`DetailKind::Other`]; tests with a structural category set it
    /// here so downstream `kind`-based filters route the failure
    /// correctly.
    pub fn kind(mut self, kind: DetailKind) -> Self {
        self.kind = kind;
        self
    }

    /// Attach a human-readable rationale appended to the failure
    /// message as `(reason)`. No effect on the pass path. Use to
    /// record *why* the bound matters so a regression two months
    /// later carries original intent in its diagnostic.
    pub fn because(mut self, reason: &'a str) -> Self {
        self.reason = Some(reason);
        self
    }
}

/// Append the optional `reason` to a failure message, returning the
/// final formatted string. Centralized so every comparator's failure
/// arm shares one definition of "( reason )" appendix formatting.
fn append_reason(msg: String, reason: Option<&str>) -> String {
    match reason {
        Some(r) => format!("{msg} ({r})"),
        None => msg,
    }
}

impl<'a, T> ClaimBuilder<'a, T>
where
    T: PartialEq + std::fmt::Display,
{
    /// Pass when `value == expected`; fail with
    /// `<name>: expected <expected>, was <value>` otherwise.
    ///
    /// **NaN gotcha** (only relevant for `T = f64`): IEEE 754 says
    /// `NaN == NaN` is `false`. Use `is_finite` or
    /// [`claim!`](crate::claim) on `value.is_nan()` instead.
    pub fn eq(self, expected: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value == expected {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected {expected}, was {value}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass when `value != forbidden`; fail with
    /// `<name>: expected != <forbidden>, was <value>` otherwise.
    pub fn ne(self, forbidden: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value != forbidden {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected != {forbidden}, was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }
}

impl<'a, T> ClaimBuilder<'a, T>
where
    T: PartialOrd + std::fmt::Display,
{
    /// Pass when `value >= floor`; fail with `<name>: expected at
    /// least <floor>, was <value>` otherwise.
    pub fn at_least(self, floor: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value >= floor {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected at least {floor}, was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass when `value <= ceiling`; fail with `<name>: expected at
    /// most <ceiling>, was <value>` otherwise.
    pub fn at_most(self, ceiling: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value <= ceiling {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected at most {ceiling}, was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass when `value < ceiling`; fail otherwise.
    pub fn lt(self, ceiling: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value < ceiling {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected less than {ceiling}, was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass when `value > floor`; fail otherwise.
    pub fn gt(self, floor: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value > floor {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected greater than {floor}, was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass when `lo <= value <= hi` (inclusive on both ends). Fails
    /// with caller-error message when `lo > hi`.
    pub fn between(self, lo: T, hi: T) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if lo > hi {
            let msg = append_reason(
                format!("{name}: caller error: interval inverted (lo={lo} > hi={hi})"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        } else if value >= lo && value <= hi {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected in [{lo}, {hi}], was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }
}

impl<'a> ClaimBuilder<'a, f64> {
    /// Pass when the value is finite (neither NaN nor ±Infinity).
    pub fn is_finite(self) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value.is_finite() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected finite, was {value}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass when `(value - target).abs() <= tolerance`. `value ==
    /// target` short-circuits as a pass before the subtraction so
    /// `±inf == ±inf` reads as a match. Negative `tolerance` is a
    /// caller bug — the failure message names it.
    pub fn near(self, target: f64, tolerance: f64) -> &'a mut Verdict {
        let ClaimBuilder {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if tolerance < 0.0 {
            let msg = append_reason(
                format!("{name}: caller error: tolerance negative (={tolerance})"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        } else if value == target || (value - target).abs() <= tolerance {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected near {target} (±{tolerance}), was {value}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }
}

/// Per-claim builder for `BTreeSet<T>` values. Same `kind` / `because`
/// modifiers as [`ClaimBuilder`]; comparator surface is set-specific.
#[must_use = "SetClaim records nothing until a comparator is invoked"]
pub struct SetClaim<'a, T: Ord + std::fmt::Debug> {
    verdict: &'a mut Verdict,
    name: &'static str,
    value: &'a BTreeSet<T>,
    kind: DetailKind,
    reason: Option<&'a str>,
}

impl<'a, T: Ord + std::fmt::Debug> SetClaim<'a, T> {
    pub fn kind(mut self, kind: DetailKind) -> Self {
        self.kind = kind;
        self
    }
    pub fn because(mut self, reason: &'a str) -> Self {
        self.reason = Some(reason);
        self
    }

    /// Pass iff the set is empty.
    pub fn empty(self) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value.is_empty() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected empty, was {value:?}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff the set is non-empty.
    pub fn nonempty(self) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if !value.is_empty() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected non-empty, was empty"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff the set contains `needle`.
    pub fn contains(self, needle: &T) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value.contains(needle) {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected to contain {needle:?}, set was {value:?}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `set.len() == n`.
    pub fn len_eq(self, n: usize) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let actual = value.len();
        let outcome = if actual == n {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected len == {n}, was {actual}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `set.len() <= n`.
    pub fn len_at_most(self, n: usize) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let actual = value.len();
        let outcome = if actual <= n {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected len <= {n}, was {actual}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `set.len() >= n`.
    pub fn len_at_least(self, n: usize) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let actual = value.len();
        let outcome = if actual >= n {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected len >= {n}, was {actual}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff every element of `value` is in `whitelist`. Fails with
    /// the offending elements listed.
    pub fn subset_of(self, whitelist: &BTreeSet<T>) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let bad: Vec<&T> = value.iter().filter(|x| !whitelist.contains(x)).collect();
        let outcome = if bad.is_empty() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected subset of {whitelist:?}, but {bad:?} are not in the set"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `value` shares no element with `forbidden`. Fails with
    /// the offending elements listed.
    pub fn disjoint_from(self, forbidden: &BTreeSet<T>) -> &'a mut Verdict {
        let SetClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let bad: Vec<&T> = value.iter().filter(|x| forbidden.contains(x)).collect();
        let outcome = if bad.is_empty() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!(
                    "{name}: expected disjoint from {forbidden:?}, but {bad:?} are present in both"
                ),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }
}

/// Per-claim builder for slice / `Vec<T>` values. Same modifier
/// surface as [`SetClaim`]; comparator surface is sequence-specific.
#[must_use = "SeqClaim records nothing until a comparator is invoked"]
pub struct SeqClaim<'a, T: std::fmt::Debug> {
    verdict: &'a mut Verdict,
    name: &'static str,
    value: &'a [T],
    kind: DetailKind,
    reason: Option<&'a str>,
}

impl<'a, T: std::fmt::Debug> SeqClaim<'a, T> {
    pub fn kind(mut self, kind: DetailKind) -> Self {
        self.kind = kind;
        self
    }
    pub fn because(mut self, reason: &'a str) -> Self {
        self.reason = Some(reason);
        self
    }

    /// Pass iff the sequence is empty.
    pub fn empty(self) -> &'a mut Verdict {
        let SeqClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value.is_empty() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected empty, was {value:?}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff the sequence is non-empty.
    pub fn nonempty(self) -> &'a mut Verdict {
        let SeqClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if !value.is_empty() {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected non-empty, was empty"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff the sequence contains an element equal to `needle`.
    pub fn contains(self, needle: &T) -> &'a mut Verdict
    where
        T: PartialEq,
    {
        let SeqClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let outcome = if value.iter().any(|x| x == needle) {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(
                format!("{name}: expected to contain {needle:?}, sequence was {value:?}"),
                reason,
            );
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `seq.len() == n`.
    pub fn len_eq(self, n: usize) -> &'a mut Verdict {
        let SeqClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let actual = value.len();
        let outcome = if actual == n {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected len == {n}, was {actual}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `seq.len() <= n`.
    pub fn len_at_most(self, n: usize) -> &'a mut Verdict {
        let SeqClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let actual = value.len();
        let outcome = if actual <= n {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected len <= {n}, was {actual}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }

    /// Pass iff `seq.len() >= n`.
    pub fn len_at_least(self, n: usize) -> &'a mut Verdict {
        let SeqClaim {
            verdict,
            name,
            value,
            kind,
            reason,
        } = self;
        let actual = value.len();
        let outcome = if actual >= n {
            ClaimOutcome::Pass
        } else {
            let msg = append_reason(format!("{name}: expected len >= {n}, was {actual}"), reason);
            ClaimOutcome::Fail { kind, message: msg }
        };
        verdict.record(outcome);
        verdict
    }
}

/// Open a [`Verdict`] claim from a local binding or expression. The
/// label is `stringify!(<expr-tokens>)` so a regression that renames
/// the binding or alters the expression updates the rendered failure
/// message in lock-step.
///
/// Use as `claim!(verdict, my_local).at_most(N)` or
/// `claim!(verdict, end - start).at_least(N)`. For struct fields under
/// a `#[derive(Claim)]`, prefer the typed accessor
/// (`verdict.claim_<field>(s)`) — the macro is the escape hatch when
/// no derived accessor exists.
///
/// Expanded form: `verdict.claim(stringify!(expr), expr)`. The macro
/// is a thin wrapper so `Verdict::claim`'s `'static` label invariant
/// holds (string literals from `stringify!` always have `'static`
/// lifetime).
///
/// ```
/// # use ktstr::{assert::Verdict, claim};
/// let mut v = Verdict::new();
/// let answer = 42u64;
/// claim!(v, answer).at_least(40);
/// claim!(v, answer * 2).at_most(100);
/// let r = v.into_result();
/// assert!(r.passed);
/// ```
#[macro_export]
macro_rules! claim {
    ($verdict:expr, $value:expr) => {
        $verdict.claim(stringify!($value), $value)
    };
}