SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
CLI: run takes --param-check (#6921) (#6924)
Rick Morgans2356a63aea70
diff --git a/apps/solidcraft-cli/examples/studio_evidence.rs b/apps/solidcraft-cli/examples/studio_evidence.rsindex a08e6dd17c..fd41400f26 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.rsindex ba6fa03d1d..77d93ed902 100644--- a/apps/solidcraft-cli/src/main.rs+++ b/apps/solidcraft-cli/src/main.rs@@ -2,6 +2,7 @@//!//! ```text//! solidcraft-cli run <script.json|design.sc|part.step|mesh.3mf> [--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 <script.json|design.sc|part.step> [--in design.sc|part.step] [--json-out FILE] (alias: inspect) measurements as JSON//! solidcraft-cli script <design.sc> [--out script.json] the design's history as a command script//! solidcraft-cli bench-open <design.sc | part.step> [--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 <script.json|design.sc|part.step> [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors]\n solidcraft-cli run --in <design.sc|part.step> [--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 <script.json|design.sc|part.step> [--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 <design.sc|part.step> [--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 <script.json|design.sc|part.step> [--in design.sc|part.step] [--json-out FILE] (alias: inspect)\n solidcraft-cli eval --in <script.json|design.sc|part.step> [--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) -> Ress.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<Vec<Value>, 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<solidcraft_engine::schema::ParamCheck, String> {+ 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<Session, String> {+/// 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<Session, String> {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.rsindex 4534a1ebba..51fe28534c 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.rsindex 470e4faf7b..319fa753d4 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>, 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>, 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.rsindex a3dede46f1..42e9e87f5a 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::<f64>(), "{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.mdindex 86ff49ca49..bee052ea81 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 writits `--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 fileinstead. The file is plain UTF-8, which is not what a redirect gives you everywhere: Windows