Aura/crates/aura-cli/src/diag.rs

//! Stable stderr class markers (C14): `aura: note: <text>` for benign
//! diagnostics on a continuing run (exit code unaffected),
//! `aura: warning: <text>` for recorded faults the run survives.
//! Error lines that accompany a non-zero exit — and plain info lines
//! such as the run-record summary — keep the bare `aura:` prefix; for
//! errors, the exit-code partition is the machine contract.

macro_rules! note {
    ($($arg:tt)*) => {
        eprintln!("aura: note: {}", format_args!($($arg)*))
    };
}

macro_rules! warning {
    ($($arg:tt)*) => {
        eprintln!("aura: warning: {}", format_args!($($arg)*))
    };
}

pub(crate) use {note, warning};

/// The zero-trade note's message text (#313), pluralization-aware — the
/// milestone fieldtest tripped over "all 1 walk-forward windows"
/// (captured: `fieldtests/milestone-stderr-honesty/captured/
/// example2_singular.err`). Pure over the count so the wording is
/// unit-pinned.
fn zero_trade_note_text(n_windows: usize) -> String {
    if n_windows == 1 {
        "the single walk-forward window recorded zero trades".to_string()
    } else {
        format!("all {n_windows} walk-forward windows recorded zero trades")
    }
}

/// The #313 zero-trade note (#319 Task 5: migrated onto the campaign
/// walk-forward leg in `campaign_run.rs`, the surviving executor path) so
/// the wording AND the condition live in exactly one place. Takes the
/// per-window trade counts; a no-op unless there is at least one window and
/// every one of them traded zero times.
pub(crate) fn note_zero_trade_windows(mut window_trades: impl ExactSizeIterator<Item = u64>) {
    let n_windows = window_trades.len();
    if n_windows > 0 && window_trades.all(|n| n == 0) {
        note!("{}", zero_trade_note_text(n_windows));
    }
}

/// #324 (re-scoped): the non-walk-forward sibling of `note_zero_trade_windows`
/// — a campaign cell whose families are ALL non-walk-forward (grid sweep, MC
/// bootstrap, …) has no per-window vocabulary to note through, yet a
/// consumer still cannot tell "0.0 = break-even" from "0.0 = never traded"
/// without this. Pure over the count so the wording is unit-pinned (mirrors
/// `zero_trade_note_text`'s singular/plural split, #313).
fn zero_trade_cell_note_text(n_reports: usize) -> String {
    if n_reports == 1 {
        "the cell's one report recorded zero trades; its metrics are vacuous, not a break-even \
         result"
            .to_string()
    } else {
        format!(
            "the cell's {n_reports} reports all recorded zero trades; its metrics are vacuous, \
             not a break-even result"
        )
    }
}

/// See `zero_trade_cell_note_text`. Takes the per-report trade counts across
/// every family the cell ran; a no-op unless there is at least one report
/// and every one of them traded zero times. Called from the campaign cell
/// loop's non-walk-forward branch (`campaign_run.rs`), independent of `emit`.
pub(crate) fn note_zero_trade_cell(mut report_trades: impl ExactSizeIterator<Item = u64>) {
    let n_reports = report_trades.len();
    if n_reports > 0 && report_trades.all(|n| n == 0) {
        note!("{}", zero_trade_cell_note_text(n_reports));
    }
}

/// #324 (comment 4501): `exec <blueprint.json>`'s single-run signal/bias leg
/// always drives the built-in synthetic stream (`RunData::Synthetic`, no
/// direct-blueprint exec ever binds real data — only a campaign document's
/// `data` section does) — a tiny `n_cycles`-bar smoke fixture, not market
/// data. Zero trades on it is expected, not a broken strategy; a caller that
/// validates against it needs telling so. Unconditional — the caller gates
/// on the zero-trade condition before calling.
pub(crate) fn note_synthetic_smoke_zero_trades(n_cycles: usize) {
    note!(
        "the built-in synthetic stream ({n_cycles} cycles) is a small smoke fixture; zero \
         trades is expected here — bind real data via a campaign document's `data` section \
         (`aura exec <campaign.json>`) for a meaningful run"
    );
}

#[cfg(test)]
mod tests {
    use super::{zero_trade_cell_note_text, zero_trade_note_text};

    #[test]
    /// #278 fieldtest friction: the single-window form must read as
    /// grammatical English while the plural form keeps the exact phrase
    /// the e2e pins grep for.
    fn zero_trade_note_pluralizes() {
        assert_eq!(
            zero_trade_note_text(1),
            "the single walk-forward window recorded zero trades"
        );
        assert_eq!(
            zero_trade_note_text(3),
            "all 3 walk-forward windows recorded zero trades"
        );
    }

    #[test]
    /// #324: the cell-level sibling pluralizes the same way and names the
    /// vacuous-metrics property, not just the raw zero count.
    fn zero_trade_cell_note_pluralizes() {
        assert_eq!(
            zero_trade_cell_note_text(1),
            "the cell's one report recorded zero trades; its metrics are vacuous, not a \
             break-even result"
        );
        assert_eq!(
            zero_trade_cell_note_text(4),
            "the cell's 4 reports all recorded zero trades; its metrics are vacuous, not a \
             break-even result"
        );
    }
}