feat(0086): cost-flag CLI ergonomics — units note, named diagnostics, non-R-harness guard
#153 (friction surfaced by the milestone-#148 close fieldtest). Three cost-flag fixes on `aura run`, all on the pure parse_run_args grammar: - Units discoverable: a COST_FLAGS_NOTE appended to the run usage + --help (price units, charged in R as cost/|entry-stop|, per-ENGINE-cycle carry, >= 0, stage1-r only). - A negative rate names the cause + flag ("<flag> must be non-negative, got <v>") via a factored parse_nonneg_rate helper, not a bare usage dump. - A cost flag on a non-R harness (sma/macd) is refused (exit 2, "cost flags require an R-evaluator harness (stage1-r)") instead of silently ignored — the named spec_gap, decided reject/fail-loud (refuse-don't-guess, recorded on #153), pinned by a new C10 ledger note. Internal RunArgs/RunData/HarnessKind gain #[derive(Debug)] (behaviour-neutral) so the pure parse_run_args unit tests can use expect_err. Verified independently: cargo test -p aura-cli green, the eight stage1-r cost goldens byte-unchanged; clippy -p aura-cli --all-targets -D warnings clean. Only the grammar/usage strings and the previously-unguarded sma-cost path changed; the cost-model graph and R math are untouched. closes #153
This commit is contained in:
+94
-18
@@ -2581,6 +2581,7 @@ struct CostConfig {
|
||||
|
||||
/// Which data a `run` drives a harness on: the built-in synthetic stream, or real M1
|
||||
/// close bars for a vetted symbol over an optional window.
|
||||
#[derive(Debug)]
|
||||
enum RunData {
|
||||
Synthetic,
|
||||
Real { symbol: String, from: Option<i64>, to: Option<i64> },
|
||||
@@ -3111,6 +3112,7 @@ fn persist_traces_r(
|
||||
/// Which built-in harness `aura run` drives. A fixed compile-time enumeration over
|
||||
/// Rust-authored harnesses — NOT a runtime node registry and NOT a DSL (C9/C17): the
|
||||
/// CLI *runs* an authored harness, it does not wire one.
|
||||
#[derive(Debug)]
|
||||
enum HarnessKind {
|
||||
Sma,
|
||||
Macd,
|
||||
@@ -3119,6 +3121,7 @@ enum HarnessKind {
|
||||
|
||||
/// The parsed `aura run` invocation: a harness, a data source, an optional trace name, and
|
||||
/// an optional flat round-trip cost per trade (`--cost-per-trade`, stage1-r only this cycle).
|
||||
#[derive(Debug)]
|
||||
struct RunArgs {
|
||||
harness: HarnessKind,
|
||||
data: RunData,
|
||||
@@ -3128,6 +3131,18 @@ struct RunArgs {
|
||||
carry_per_cycle: Option<f64>,
|
||||
}
|
||||
|
||||
/// Parse a cost-rate flag value and enforce non-negativity, naming the offending
|
||||
/// flag so a sign typo is distinguishable from a mistyped flag name. A *malformed*
|
||||
/// value stays a grammar usage error (unchanged); only a parsed-but-negative value
|
||||
/// yields the named message. Pure — no I/O, no exit.
|
||||
fn parse_nonneg_rate(flag: &str, value: &str, usage: &impl Fn() -> String) -> Result<f64, String> {
|
||||
let v: f64 = value.parse().map_err(|_| usage())?;
|
||||
if v < 0.0 {
|
||||
return Err(format!("{flag} must be non-negative, got {v}"));
|
||||
}
|
||||
Ok(v)
|
||||
}
|
||||
|
||||
/// Parse the `run` tail: `[--harness <name>] [--real <SYM> [--from <ms>] [--to <ms>]]
|
||||
/// [--trace <name>] [--cost-per-trade <f64>] [--slip-vol-mult <f64>]` in any order, each flag at most once.
|
||||
/// `--harness sma` is the default (`--harness macd` / `--harness stage1-r` select the
|
||||
@@ -3135,8 +3150,9 @@ struct RunArgs {
|
||||
/// grammar is unit-testable; `main` does the side effects.
|
||||
fn parse_run_args(rest: &[&str]) -> Result<RunArgs, String> {
|
||||
let usage = || {
|
||||
"usage: aura run [--harness <sma|macd|stage1-r>] [--real <SYMBOL> [--from <ms>] [--to <ms>]] [--trace <name>] [--cost-per-trade <f64>] [--slip-vol-mult <f64>] [--carry-per-cycle <f64>]"
|
||||
.to_string()
|
||||
format!(
|
||||
"usage: aura run [--harness <sma|macd|stage1-r>] [--real <SYMBOL> [--from <ms>] [--to <ms>]] [--trace <name>] [--cost-per-trade <f64>] [--slip-vol-mult <f64>] [--carry-per-cycle <f64>]{COST_FLAGS_NOTE}"
|
||||
)
|
||||
};
|
||||
let mut harness: Option<HarnessKind> = None;
|
||||
let mut symbol: Option<String> = None;
|
||||
@@ -3184,35 +3200,35 @@ fn parse_run_args(rest: &[&str]) -> Result<RunArgs, String> {
|
||||
}
|
||||
"--cost-per-trade" if cost.is_none() => {
|
||||
let (value, t) = t.split_first().ok_or_else(usage)?;
|
||||
let v: f64 = value.parse().map_err(|_| usage())?;
|
||||
if v < 0.0 {
|
||||
return Err(usage());
|
||||
}
|
||||
cost = Some(v);
|
||||
cost = Some(parse_nonneg_rate("--cost-per-trade", value, &usage)?);
|
||||
tail = t;
|
||||
}
|
||||
"--slip-vol-mult" if slip_vol_mult.is_none() => {
|
||||
let (value, t) = t.split_first().ok_or_else(usage)?;
|
||||
let v: f64 = value.parse().map_err(|_| usage())?;
|
||||
if v < 0.0 {
|
||||
return Err(usage());
|
||||
}
|
||||
slip_vol_mult = Some(v);
|
||||
slip_vol_mult = Some(parse_nonneg_rate("--slip-vol-mult", value, &usage)?);
|
||||
tail = t;
|
||||
}
|
||||
"--carry-per-cycle" if carry_per_cycle.is_none() => {
|
||||
let (value, t) = t.split_first().ok_or_else(usage)?;
|
||||
let v: f64 = value.parse().map_err(|_| usage())?;
|
||||
if v < 0.0 {
|
||||
return Err(usage());
|
||||
}
|
||||
carry_per_cycle = Some(v);
|
||||
carry_per_cycle = Some(parse_nonneg_rate("--carry-per-cycle", value, &usage)?);
|
||||
tail = t;
|
||||
}
|
||||
_ => return Err(usage()),
|
||||
}
|
||||
}
|
||||
let harness = harness.unwrap_or(HarnessKind::Sma);
|
||||
// Cost flags are defined only against the R chain (gross-R -> net-R); a non-R
|
||||
// harness produces no R to charge against, so a cost flag there is a usage error,
|
||||
// not a silent no-op (refuse-don't-guess, C10).
|
||||
if !matches!(harness, HarnessKind::Stage1R)
|
||||
&& (cost.is_some() || slip_vol_mult.is_some() || carry_per_cycle.is_some())
|
||||
{
|
||||
return Err(
|
||||
"cost flags require an R-evaluator harness (stage1-r); \
|
||||
--harness sma/macd produces no R to charge against"
|
||||
.to_string(),
|
||||
);
|
||||
}
|
||||
// --from/--to require --real.
|
||||
if symbol.is_none() && (from.is_some() || to.is_some()) {
|
||||
return Err(usage());
|
||||
@@ -3241,6 +3257,14 @@ fn run_dispatch(args: RunArgs) -> Result<RunReport, String> {
|
||||
})
|
||||
}
|
||||
|
||||
/// One-line note appended to the `aura run` usage surfaces (the grammar-error
|
||||
/// usage closure and `--help`) so the cost-flag units, scale, per-engine-cycle
|
||||
/// semantics, non-negativity, and R-harness requirement are discoverable at the
|
||||
/// point of use (#153). A leading newline puts it on its own line under the usage.
|
||||
const COST_FLAGS_NOTE: &str = "\ncost flags (stage1-r only; all >= 0, charged in R as cost/|entry−stop|): \
|
||||
--cost-per-trade = per-trade cost in price units; --slip-vol-mult = slippage multiplier on realized vol; \
|
||||
--carry-per-cycle = carry in price units per ENGINE cycle (not per day, not an overnight swap)";
|
||||
|
||||
const USAGE: &str =
|
||||
"usage: aura run [--harness <sma|macd|stage1-r>] [--real <SYMBOL> [--from <ms>] [--to <ms>]] [--trace <name>] [--cost-per-trade <f64>] [--slip-vol-mult <f64>] [--carry-per-cycle <f64>] | aura chart <name> [--tap <t>] [--panels] | aura graph | aura sweep [--strategy <sma|momentum|stage1-r|stage1-breakout|stage1-meanrev>] [--real <SYMBOL> [--from <ms>] [--to <ms>]] [--name <n>|--trace <n>] | aura mc [--name <n>|--trace <n>] | aura mc --strategy stage1-r [--real <SYMBOL> [--from <ms>] [--to <ms>]] [--fast <csv>] [--slow <csv>] [--stop-length <csv>] [--stop-k <csv>] [--block-len <n>] [--resamples <n>] [--seed <n>] | aura walkforward [--strategy <sma|momentum|stage1-r|stage1-breakout|stage1-meanrev>] [--real <SYMBOL> [--from <ms>] [--to <ms>]] [--name <n>|--trace <n>] [--fast <csv>] [--slow <csv>] [--stop-length <csv>] [--stop-k <csv>] [--select <argmax|plateau:mean|plateau:worst>] | aura generalize [--strategy stage1-r] --real <SYM1,SYM2,...> --fast <n> --slow <n> --stop-length <n> --stop-k <f> [--from <ms>] [--to <ms>] [--metric <r-metric>] [--name <n>] | aura runs families | aura runs family <id> [rank <metric>]";
|
||||
|
||||
@@ -3262,7 +3286,7 @@ fn main() {
|
||||
// subcommands (#131): `aura chart --help` shows usage instead of erroring
|
||||
// "unexpected argument", and the bare `aura --help` is the same affordance.
|
||||
if args.iter().any(|a| a == "--help" || a == "-h") {
|
||||
println!("{USAGE}");
|
||||
println!("{USAGE}{COST_FLAGS_NOTE}");
|
||||
return;
|
||||
}
|
||||
match args.iter().map(String::as_str).collect::<Vec<_>>().as_slice() {
|
||||
@@ -4531,6 +4555,58 @@ mod tests {
|
||||
assert!(parse_run_args(&["bogus"]).is_err()); // unknown trailing token
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_run_args_negative_cost_rates_are_named_not_usage() {
|
||||
for flag in ["--cost-per-trade", "--slip-vol-mult", "--carry-per-cycle"] {
|
||||
let err = parse_run_args(&["--harness", "stage1-r", flag, "-0.5"])
|
||||
.expect_err("a negative cost rate must be refused");
|
||||
assert!(err.contains("must be non-negative"), "{flag}: {err}");
|
||||
assert!(err.contains(flag), "message must name the offending flag: {err}");
|
||||
assert!(err.contains("-0.5"), "message must carry the value: {err}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_run_args_malformed_cost_rate_stays_grammar_usage() {
|
||||
let err = parse_run_args(&["--harness", "stage1-r", "--cost-per-trade", "x"])
|
||||
.expect_err("a malformed rate is a grammar error");
|
||||
assert!(err.contains("usage"), "a malformed value stays the usage path: {err}");
|
||||
// The grammar-error usage surface — the more frequently hit one — carries the
|
||||
// cost-flag note too (#153), so pin that dropping {COST_FLAGS_NOTE} from the
|
||||
// `usage` closure regresses it, not only the `--help` print.
|
||||
assert!(err.contains("per ENGINE cycle"), "the grammar usage must carry the cost-flag note: {err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_run_args_cost_flags_require_r_harness() {
|
||||
let cases: [(&[&str], &str); 3] = [
|
||||
(&["--harness", "sma"], "--cost-per-trade"),
|
||||
(&["--harness", "macd"], "--slip-vol-mult"),
|
||||
(&["--harness", "sma"], "--carry-per-cycle"),
|
||||
];
|
||||
for (harness, flag) in cases {
|
||||
let mut argv: Vec<&str> = harness.to_vec();
|
||||
argv.extend_from_slice(&[flag, "0.001"]);
|
||||
let err = parse_run_args(&argv).expect_err("cost flag on a non-R harness must be refused");
|
||||
assert!(err.contains("R-evaluator harness"), "{harness:?}+{flag}: {err}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_run_args_cost_flag_without_harness_defaults_sma_and_is_refused() {
|
||||
let err = parse_run_args(&["--carry-per-cycle", "0.5"])
|
||||
.expect_err("the default harness is sma → cost flag refused");
|
||||
assert!(err.contains("R-evaluator harness"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_run_args_cost_flags_accepted_on_stage1_r() {
|
||||
let a = parse_run_args(&["--harness", "stage1-r", "--cost-per-trade", "0.001"])
|
||||
.expect("cost flags are accepted on the R harness");
|
||||
assert!(matches!(a.harness, HarnessKind::Stage1R));
|
||||
assert_eq!(a.cost, Some(0.001));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_mc_args_bare_and_name_route_to_synthetic() {
|
||||
assert_eq!(parse_mc_args(&[]), Ok(McArgs::Synthetic { name: "mc".to_string(), persist: false }));
|
||||
|
||||
Reference in New Issue
Block a user