diff --git a/apps/solidcraft-cli/examples/studio_evidence.rs b/apps/solidcraft-cli/examples/studio_evidence.rs index a08e6dd17..fd41400f2 100644 --- a/apps/solidcraft-cli/examples/studio_evidence.rs +++ b/apps/solidcraft-cli/examples/studio_evidence.rs @@ -66,7 +66,7 @@ fn run() -> Result<(), String> { let mut session = Session::default(); eprintln!("Generating original CAD scene from {recipe_path}"); let generation_start = Instant::now(); - let (commands, command_timings) = session.run_script_timed(&recipe, false).map_err(|e| e.to_string())?; + let (commands, command_timings) = session.run_script_timed(&recipe, false, &mut |_, _| {}).map_err(|e| e.to_string())?; let generation_seconds = generation_start.elapsed().as_secs_f64(); let design_path = output.with_extension(solidcraft_engine::io::DESIGN_EXT); session.execute("file.save_as", &json!({"path":design_path})).map_err(|e| e.to_string())?; diff --git a/apps/solidcraft-cli/src/main.rs b/apps/solidcraft-cli/src/main.rs index ba6fa03d1..77d93ed90 100644 --- a/apps/solidcraft-cli/src/main.rs +++ b/apps/solidcraft-cli/src/main.rs @@ -2,6 +2,7 @@ //! //! ```text //! solidcraft-cli run [--in design|part.step|mesh.3mf] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors] +//! [--param-check off|warn|strict] //! solidcraft-cli eval [--in design.sc|part.step] [--json-out FILE] (alias: inspect) measurements as JSON //! solidcraft-cli script [--out script.json] the design's history as a command script //! solidcraft-cli bench-open [--parse-only] [--save OUT.sc] [--display LEVEL [--edit NAME EXPR]] [--ops script.json] loading timings as JSON lines @@ -57,7 +58,7 @@ struct Command { } /// `run`'s lines in the usage. -const USAGE_RUN: &str = " solidcraft-cli run [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors]\n solidcraft-cli run --in [--out FILE]...\n (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)\n (--timings prints {timings: [{index, command, ms}], total_ms} for a script, with --results its results too;\n --profile adds each command's profile: {boolean_ms, tessellate_ms, other_ms}, the kernel's share)\n"; +const USAGE_RUN: &str = " solidcraft-cli run [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors]\n [--param-check off|warn|strict]\n solidcraft-cli run --in [--out FILE]...\n (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)\n (--param-check checks each step against its command's contract: warn reports on stderr, strict stops the run)\n (--timings prints {timings: [{index, command, ms}], total_ms} for a script, with --results its results too;\n --profile adds each command's profile: {boolean_ms, tessellate_ms, other_ms}, the kernel's share)\n"; /// `eval`'s lines in the usage. const USAGE_EVAL: &str = " solidcraft-cli eval [--in design.sc|part.step] [--json-out FILE] (alias: inspect)\n solidcraft-cli eval --in [--json-out FILE]\n (with both inputs, runs the positional script on --in before measuring; does not automatically save the modified design)\n (--json-out FILE writes the JSON that run (with --results, else the measurement) and eval print to FILE instead of stdout,\n as plain UTF-8: a shell's > can re-encode it, e.g. Windows PowerShell adds a byte-order mark)\n"; /// `script`'s lines in the usage. @@ -299,18 +300,36 @@ fn load_checked(path: &str, check: solidcraft_engine::schema::ParamCheck) -> Res s.execute("doc.open", &json!({"path": path})).map_err(|e| e.to_string())?; } else { let script = if v.get("features").is_some() && v.get("commands").is_none() { recipe::to_script(&v)? } else { v }; - // Warn level: each step's `param_warnings` as it completes, even when a later step fails - // (stderr, so stdout stays the caller's). - let mut warn = |step: usize, r: &Value| { - for w in r.get("param_warnings").and_then(Value::as_array).into_iter().flatten() { - eprintln!("{path}: step {}: {}", step + 1, w.as_str().unwrap_or_default()); - } - }; - s.run_script_each(&script, &mut warn).map_err(|e| e.to_string())?; + run_script_warning(&mut s, path, &script)?; } Ok(s) } +/// Run `script`, read from `path`, on `s`. At the warn level each step's `param_warnings` go to +/// stderr as the step completes, even when a later step fails (stdout stays the caller's). +fn run_script_warning(s: &mut Session, path: &str, script: &Value) -> Result, String> { + s.run_script_each(script, &mut |step, r| print_param_warnings(path, step, r)).map_err(|e| e.to_string()) +} + +/// Step `step`'s `param_warnings` on stderr, one per line, named after the script at `path`. +fn print_param_warnings(path: &str, step: usize, r: &Value) { + for w in r.get("param_warnings").and_then(Value::as_array).into_iter().flatten() { + eprintln!("{path}: step {}: {}", step + 1, w.as_str().unwrap_or_default()); + } +} + +/// `--param-check off|warn|strict`: how calls that break a command's parameter contract are +/// treated (docs/mcp.md); off when the option isn't given. +fn parse_param_check(cmd: &str, args: &[String]) -> Result { + match flag(args, "--param-check") { + None if args.iter().any(|a| a == "--param-check") => Err(format!("{cmd}: --param-check wants off, warn or strict")), + None => Ok(solidcraft_engine::schema::ParamCheck::Off), + Some(v) => { + solidcraft_engine::schema::ParamCheck::parse(v).ok_or_else(|| format!("{cmd}: --param-check wants off, warn or strict, not `{v}`")) + } + } +} + fn flag<'a>(args: &'a [String], name: &str) -> Option<&'a str> { args.iter().position(|a| a == name).and_then(|i| args.get(i + 1)).map(String::as_str) } @@ -367,7 +386,15 @@ fn print_json(v: &Value, file: Option<&str>) -> Result<(), String> { fn cmd_run(args: &[String]) -> Result<(), String> { install_renderer(); let json_out = json_out(args)?; - known_args("run", args, &["--in", "--out", "--save", "--json-out"], &["--quiet", "--results", "--timings", "--profile", "--allow-errors"], true)?; + // Before the option check, so a bare `--param-check` gets the words `mcp` uses. + let check = parse_param_check("run", args)?; + known_args( + "run", + args, + &["--in", "--out", "--save", "--json-out", "--param-check"], + &["--quiet", "--results", "--timings", "--profile", "--allow-errors"], + true, + )?; let base = flag(args, "--in"); let path = positional(args); if path.is_none() && base.is_none() { @@ -380,23 +407,25 @@ fn cmd_run(args: &[String]) -> Result<(), String> { let (mut s, results) = if want_results || timings { // Collect every command's result or time (scripts only), then process requested files too. let mut s = match base { - Some(b) => load(b)?, + Some(b) => load_checked(b, check)?, None => Session::default(), }; + s.param_check = check; let needs = if want_results { "--results needs a script" } else { "--timings needs a script" }; - let v = read_json(path.ok_or(needs)?)?; + let script = path.ok_or(needs)?; + let v = read_json(script)?; let out = if timings { - let (r, mut t) = s.run_script_timed(&v, profile).map_err(|e| e.to_string())?; + let (r, mut t) = s.run_script_timed(&v, profile, &mut |step, r| print_param_warnings(script, step, r)).map_err(|e| e.to_string())?; if want_results && let Some(o) = t.as_object_mut() { o.insert("results".into(), Value::Array(r)); } t } else { - Value::Array(s.run_script(&v).map_err(|e| e.to_string())?) + Value::Array(run_script_warning(&mut s, script, &v)?) }; (s, Some(out)) } else { - (open(base, path)?, None) + (open(base, path, check)?, None) }; // A feature that fails leaves the bodies as they were before it (a parameter change can // break a feature without failing the command that made it): writing them would hand out @@ -421,16 +450,16 @@ fn cmd_run(args: &[String]) -> Result<(), String> { } /// The session `run`, `eval` and `snapshot` start from: `--in` (a design or STEP file) with the -/// positional script run on top of it, or either one alone. -fn open(base: Option<&str>, path: Option<&String>) -> Result { +/// positional script run on top of it, or either one alone, with scripts run at `check`. +fn open(base: Option<&str>, path: Option<&String>, check: solidcraft_engine::schema::ParamCheck) -> Result { match (base, path) { (Some(b), Some(p)) => { - let mut s = load(b)?; - s.run_script(&read_json(p)?).map_err(|e| e.to_string())?; + let mut s = load_checked(b, check)?; + run_script_warning(&mut s, p, &read_json(p)?)?; Ok(s) } - (Some(b), None) => load(b), - (None, Some(p)) => load(p), + (Some(b), None) => load_checked(b, check), + (None, Some(p)) => load_checked(p, check), (None, None) => Err(usage()), } } @@ -473,7 +502,7 @@ fn timeline_ok(s: &Session) -> Result<(), String> { fn cmd_eval(args: &[String]) -> Result<(), String> { let json_out = json_out(args)?; known_args("eval", args, &["--in", "--json-out"], &[], true)?; - let mut s = open(flag(args, "--in"), positional(args))?; + let mut s = open(flag(args, "--in"), positional(args), solidcraft_engine::schema::ParamCheck::Off)?; let m = s.execute("inspect.measure", &json!({})).map_err(|e| e.to_string())?; let d = s.execute("document.inspect", &json!({})).map_err(|e| e.to_string())?; let out = json!({ @@ -567,7 +596,7 @@ fn cmd_snapshot(args: &[String]) -> Result<(), String> { Some(x) => x.parse().ok().filter(|n| (16..=8192).contains(n)).ok_or_else(|| format!("{name} must be 16 to 8192 pixels, not `{x}`")), }; let (w, h) = (size("--width", 1280)?, size("--height", 800)?); - let mut s = open(flag(args, "--in"), positional(args))?; + let mut s = open(flag(args, "--in"), positional(args), solidcraft_engine::schema::ParamCheck::Off)?; // How the bodies are drawn and where the model is cut, through the commands the app's // Appearance dialog and Section Analysis run (`preview`). preview::apply(&mut s, &flags(args, "--body"), &flags(args, "--tool"), flag(args, "--section"))?; @@ -691,14 +720,8 @@ fn cmd_mcp(args: &[String]) -> Result<(), String> { eprintln!("solidcraft mcp: the design's folder is left out because {why}; add it with --allow-path if you mean it"); } } - // How a headless session treats calls that break a command's parameter contract (docs/mcp.md). - let param_check = match flag(args, "--param-check") { - None if args.iter().any(|a| a == "--param-check") => return Err("mcp: --param-check wants off, warn or strict".into()), - None => solidcraft_engine::schema::ParamCheck::Off, - Some(v) => { - solidcraft_engine::schema::ParamCheck::parse(v).ok_or_else(|| format!("mcp: --param-check wants off, warn or strict, not `{v}`"))? - } - }; + // How a headless session treats calls that break a command's parameter contract. + let param_check = parse_param_check("mcp", args)?; if param_check != solidcraft_engine::schema::ParamCheck::Off && flag(args, "--connect").is_some() { eprintln!("solidcraft mcp: --param-check applies to headless sessions; calls to the app are not checked yet"); } diff --git a/apps/solidcraft-cli/tests/run_results.rs b/apps/solidcraft-cli/tests/run_results.rs index 4534a1ebb..51fe28534 100644 --- a/apps/solidcraft-cli/tests/run_results.rs +++ b/apps/solidcraft-cli/tests/run_results.rs @@ -496,6 +496,78 @@ fn timings_and_profile_report_each_command() { assert!(String::from_utf8_lossy(&output.stderr).contains("--timings needs a script")); } +/// #6921: `--param-check` checks a script's steps against their contracts on every path `run` +/// takes (a script alone, on an `--in` design or script, with `--results`, `--timings` or +/// `--profile`), and a warning reaches stderr even when a later step fails. +#[test] +fn param_check_reaches_every_script_run_takes() { + let dir = Scratch::new(); + let typo = dir.0.join("typo.json"); + let step = json!({"command": "solid.box", "params": {"length": 2, "width": 3, "height": 4, "operaton": "new"}}); + std::fs::write(&typo, json!({"commands": [step.clone()]}).to_string()).unwrap(); + let base = dir.0.join("base.solidcraft"); + json_output(cli().arg("run").arg(dir.script()).arg("--save").arg(&base).output().unwrap()); + let saved = dir.0.join("saved.solidcraft"); + let start = dir.script(); + let (typo, base, saved_arg, start) = (typo.to_str().unwrap(), base.to_str().unwrap(), saved.to_str().unwrap(), start.to_str().unwrap()); + let paths = [&[][..], &["--in", base], &["--in", start], &["--results"], &["--timings"], &["--timings", "--profile"]]; + let run = |level: Option<&str>, extra: &[&str]| { + std::fs::remove_file(&saved).ok(); + let check = level.map(|l| ["--param-check", l]).into_iter().flatten(); + cli().args(["run", typo, "--save", saved_arg]).args(check).args(extra).output().unwrap() + }; + + // Off, the default: the step runs as it always has, without a word. + let off = run(None, &[]); + assert!(off.status.success() && !String::from_utf8_lossy(&off.stderr).contains("operaton"), "{off:?}"); + assert_eq!(body_count(&saved), 1); + + // Warn: each path runs the step, saves, and reports it on stderr; `--results` keeps it too. + for extra in paths { + let output = run(Some("warn"), extra); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(output.status.success(), "{extra:?}: {stderr}"); + assert!(stderr.contains("step 1: unknown key `operaton`; did you mean `operation`?"), "{extra:?}: {stderr}"); + assert!(saved.exists(), "{extra:?}"); + if extra == ["--results"] { + let results: Value = serde_json::from_slice(&output.stdout).unwrap(); + assert!(results[0]["param_warnings"][0].as_str().is_some_and(|w| w.contains("operaton")), "{results}"); + } + } + + // Strict: on each path the run stops at the step, and nothing is written. + for extra in paths { + let output = run(Some("strict"), extra); + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!(output.status.code(), Some(1), "{extra:?}: {stderr}"); + assert!(stderr.contains("unknown key `operaton`"), "{extra:?}: {stderr}"); + assert!(!saved.exists(), "{extra:?}"); + } + + // Warn, with a later step that fails: the run fails, and the first step's warning is still + // reported, timed or not. + let failing = dir.0.join("failing.json"); + let fail = json!({"command": "solid.extrude", "params": {"sketch": "Nope"}}); + std::fs::write(&failing, json!({"commands": [step, fail]}).to_string()).unwrap(); + for extra in [&[][..], &["--timings"]] { + let output = cli().arg("run").arg(&failing).args(["--param-check", "warn"]).args(extra).output().unwrap(); + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!(output.status.code(), Some(1), "{extra:?}: {stderr}"); + assert!(stderr.contains("step 1: unknown key `operaton`") && stderr.contains("no sketch `Nope`"), "{extra:?}: {stderr}"); + } + + // A level it doesn't know and a missing value fail. + for (bad, says) in [ + (&["--param-check", "loud"][..], "--param-check wants off, warn or strict, not `loud`"), + (&["--param-check"], "run: --param-check wants off, warn or strict"), + ] { + let output = cli().args(["run", typo]).args(bad).output().unwrap(); + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!(output.status.code(), Some(1), "{bad:?}: {stderr}"); + assert!(stderr.contains(says), "{bad:?}: {stderr}"); + } +} + fn render_setup_script(dir: &Scratch, job: Value) -> PathBuf { let path = dir.0.join("render.json"); std::fs::write( diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index 470e4faf7..319fa753d 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -1810,9 +1810,10 @@ impl Session { /// [`Session::run_script`], timing each command (#1833): the results and /// `{"timings": [{"index", "command", "ms", "profile"?}], "total_ms"}`, with `profile` the - /// kernel's share of each command ([`timing`]). - pub fn run_script_timed(&mut self, script: &Value, profile: bool) -> Result<(Vec, Value)> { - let (results, timings) = self.run_script_with(script, Some(profile), &mut |_, _| {})?; + /// kernel's share of each command ([`timing`]). `each` is called as in + /// [`Session::run_script_each`]. + pub fn run_script_timed(&mut self, script: &Value, profile: bool, each: &mut dyn FnMut(usize, &Value)) -> Result<(Vec, Value)> { + let (results, timings) = self.run_script_with(script, Some(profile), each)?; Ok((results, timings.unwrap_or(Value::Null))) } diff --git a/crates/engine/src/timing.rs b/crates/engine/src/timing.rs index a3dede46f..42e9e87f5 100644 --- a/crates/engine/src/timing.rs +++ b/crates/engine/src/timing.rs @@ -87,7 +87,7 @@ mod tests { {"command": "solid.box", "params": {"length": 4, "width": 4, "height": 30, "operation": "join"}}, ]}); let mut s = crate::Session::default(); - let (results, t) = s.run_script_timed(&script, true).unwrap(); + let (results, t) = s.run_script_timed(&script, true, &mut |_, _| {}).unwrap(); assert_eq!(results.len(), 2); let rows = t["timings"].as_array().unwrap(); assert_eq!(rows.len(), 2); @@ -100,12 +100,12 @@ mod tests { let total = t["total_ms"].as_f64().unwrap(); assert!(total + 0.01 >= rows.iter().map(|r| r["ms"].as_f64().unwrap()).sum::(), "{t}"); // Without profile: the same rows, no kernel split; the plain run is unchanged. - let (_, t) = crate::Session::default().run_script_timed(&script, false).unwrap(); + let (_, t) = crate::Session::default().run_script_timed(&script, false, &mut |_, _| {}).unwrap(); assert!(t["timings"][0].get("profile").is_none()); assert_eq!(crate::Session::default().run_script(&script).unwrap().len(), 2); // A failing step still fails the run, with its step number. let bad = json!([{"command": "solid.box", "params": {"length": -1}}]); - let e = crate::Session::default().run_script_timed(&bad, true).unwrap_err().to_string(); + let e = crate::Session::default().run_script_timed(&bad, true, &mut |_, _| {}).unwrap_err().to_string(); assert!(e.contains("step 1"), "{e}"); } } diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md index 86ff49ca4..bee052ea8 100644 --- a/docs/book/src/guide/getting-started.md +++ b/docs/book/src/guide/getting-started.md @@ -312,6 +312,13 @@ rebuilds it; `run` then exits with status 1, lists the failing features and writ its `--out` and `--save` files, because the bodies lack what those features should have made. `--allow-errors` writes them anyway. +`--param-check warn|strict` checks each step against its command's parameter contract, for the +commands that have one (`describe_command` in the MCP server shows them); the default, `off`, +checks nothing. A misspelt optional key, such as `operaton` for `solid.box`'s `operation`, is +otherwise ignored, and the step builds without it. `warn` runs the step and prints +``script.json: step 1: unknown key `operaton`; did you mean `operation`?`` on stderr; `strict` +stops the run at that step, and nothing is written. + `run` prints each command's result with `--results` (otherwise the measurement), and `eval` prints the measurement, as JSON on stdout. `--json-out FILE` writes that JSON to a file instead. The file is plain UTF-8, which is not what a redirect gives you everywhere: Windows