diff --git a/Cargo.lock b/Cargo.lock index 38e204204..1df6cfe09 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1175,6 +1175,12 @@ version = "0.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76" +[[package]] +name = "dyn-clone" +version = "1.0.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555" + [[package]] name = "ecolor" version = "0.36.2" @@ -3514,6 +3520,26 @@ dependencies = [ "bitflags 2.13.2", ] +[[package]] +name = "ref-cast" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3" +dependencies = [ + "ref-cast-impl", +] + +[[package]] +name = "ref-cast-impl" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + [[package]] name = "regex-syntax" version = "0.8.11" @@ -3741,6 +3767,31 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "schemars" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab508826f74a77ca9d5aba6ff19b522583ee3eaf28a19384ff3d0e5835fadf6e" +dependencies = [ + "dyn-clone", + "ref-cast", + "schemars_derive", + "serde", + "serde_json", +] + +[[package]] +name = "schemars_derive" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1c3a92094fa7d61aa124645844facb6b554dfc797136d0f5fd1f890e2bffc69" +dependencies = [ + "proc-macro2", + "quote", + "serde_derive_internals", + "syn 3.0.6", +] + [[package]] name = "scoped-tls" version = "1.0.1" @@ -3860,6 +3911,17 @@ dependencies = [ "syn 3.0.6", ] +[[package]] +name = "serde_derive_internals" +version = "0.30.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + [[package]] name = "serde_json" version = "1.0.151" @@ -3873,6 +3935,17 @@ dependencies = [ "zmij", ] +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + [[package]] name = "serde_repr" version = "0.1.21" @@ -4164,8 +4237,10 @@ name = "solidcraft-engine" version = "0.16.2" dependencies = [ "log", + "schemars", "serde", "serde_json", + "serde_path_to_error", "solidcraft-doc", "solidcraft-geom", "solidcraft-io", diff --git a/Cargo.toml b/Cargo.toml index fa02d7829..a4cecf4f3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -36,6 +36,9 @@ proc-macro2 = "1" quote = "1" syn = { version = "2", features = ["full"] } serde_json = { version = "1", features = ["float_roundtrip"] } +# command parameter and result schemas +schemars = "1.2" +serde_path_to_error = "0.1" log = "0.4" sha2 = "0.10" moxcms = { version = "0.8.1", default-features = false, features = ["extended_range"] } diff --git a/apps/solidcraft-cli/src/main.rs b/apps/solidcraft-cli/src/main.rs index 5be417c49..dec00af12 100644 --- a/apps/solidcraft-cli/src/main.rs +++ b/apps/solidcraft-cli/src/main.rs @@ -13,6 +13,7 @@ //! solidcraft-cli recipe translate an oracle recipe to a script //! solidcraft-cli oracle ... replay recipes and compare with expected.json //! solidcraft-cli mcp [--in design|script] [--connect HOST:PORT [--token T]] [--allow-path DIR]... [--allow-any-path] +//! [--param-check off|warn|strict] //! MCP server on stdio (docs/mcp.md) //! solidcraft-cli licences SolidCraft's licence and the third-party licences //! solidcraft-cli icon --out F.png|F.ico [--size N] the app icon (packaging; drawn, not a file) @@ -71,6 +72,7 @@ const USAGE: &str = "usage: solidcraft-cli oracle ... [--json] solidcraft-cli fuzz [--from N] [--count N] [--jobs J] [--timeout S] [--steps N] [--minimise] [--out DIR] [--report FILE] solidcraft-cli mcp [--in design.solidcraft|script.json] [--connect 127.0.0.1:PORT [--token T]] [--allow-path DIR]... [--allow-any-path] + [--param-check off|warn|strict] solidcraft-cli crashes [list [--json] | show | replay | dir | clear []] solidcraft-cli licences solidcraft-cli gpu [--policy auto|hardware|software|cpu] @@ -154,7 +156,14 @@ pub fn read_json(path: &str) -> Result { /// A session from a design file, a STEP/3MF/STL file, a command script, or an oracle recipe. pub fn load(path: &str) -> Result { + load_checked(path, solidcraft_engine::schema::ParamCheck::Off) +} + +/// `load`, with scripts and recipes run at the parameter-check level `check`, which the +/// session keeps. +fn load_checked(path: &str, check: solidcraft_engine::schema::ParamCheck) -> Result { let mut s = Session::default(); + s.param_check = check; if solidcraft_engine::io::is_step_path(path) || solidcraft_engine::io::is_mesh_path(path) { s.execute("doc.open", &json!({"path": path})).map_err(|e| e.to_string())?; return Ok(s); @@ -164,16 +173,22 @@ pub fn load(path: &str) -> Result { let doc = solidcraft_engine::io::read_design(&bytes).map_err(|e| format!("{path}: {e}"))?; let mut session = Session::new(doc); session.path = Some(path.to_owned()); + session.param_check = check; return Ok(session); } let v: Value = serde_json::from_slice(&bytes).map_err(|e| format!("{path}: {e}"))?; if v.get("format").and_then(Value::as_str).is_some_and(|f| solidcraft_engine::doc::format::version_of(f).is_some()) { s.execute("doc.open", &json!({"path": path})).map_err(|e| e.to_string())?; - } else if v.get("features").is_some() && v.get("commands").is_none() { - let script = recipe::to_script(&v)?; - s.run_script(&script).map_err(|e| e.to_string())?; } else { - s.run_script(&v).map_err(|e| e.to_string())?; + 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())?; } Ok(s) } @@ -536,6 +551,17 @@ 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}`"))? + } + }; + 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"); + } let backend: Box = match (flag(args, "--connect"), flag(args, "--in")) { (Some(_), Some(_)) => return Err("mcp: use either --connect or --in, not both".into()), (Some(addr), None) => { @@ -552,8 +578,12 @@ fn cmd_mcp(args: &[String]) -> Result<(), String> { } Box::new(remote) } - (None, Some(path)) => Box::new(solidcraft_mcp::Headless::new(load(path)?)), - (None, None) => Box::new(solidcraft_mcp::Headless::default()), + (None, Some(path)) => Box::new(solidcraft_mcp::Headless::new(load_checked(path, param_check)?)), + (None, None) => { + let mut headless = solidcraft_mcp::Headless::default(); + headless.session.param_check = param_check; + Box::new(headless) + } }; let stdin = std::io::stdin(); let stdout = std::io::stdout(); diff --git a/apps/solidcraft-cli/tests/mcp_param_check.rs b/apps/solidcraft-cli/tests/mcp_param_check.rs new file mode 100644 index 000000000..0dab92924 --- /dev/null +++ b/apps/solidcraft-cli/tests/mcp_param_check.rs @@ -0,0 +1,50 @@ +//! `mcp --in script --param-check `: the level applies to the script the session starts +//! from too, so a misspelled key in it is refused (strict) or reported on stderr (warn) instead of +//! silently ignored. + +use std::process::{Command, Stdio}; + +#[test] +fn param_check_applies_to_the_starting_script() { + let dir = std::env::temp_dir().join(format!("solidcraft-mcp-param-check-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let script = dir.join("typo.json"); + let box_ = r#"{"command": "solid.box", "params": {"length": 5, "width": 5, "height": 5, "operaton": "cut"}}"#; + std::fs::write(&script, format!(r#"{{"commands": [{box_}]}}"#)).unwrap(); + let run = |level: &str| { + Command::new(env!("CARGO_BIN_EXE_solidcraft-cli")) + .args(["mcp", "--in", script.to_str().unwrap(), "--param-check", level]) + .stdin(Stdio::null()) + .output() + .unwrap() + }; + let strict = run("strict"); + let stderr = String::from_utf8_lossy(&strict.stderr); + assert!(!strict.status.success(), "{stderr}"); + assert!(stderr.contains("unknown key `operaton`; did you mean `operation`?"), "{stderr}"); + // Warn: the script runs, and its warnings go to stderr. + let warn = run("warn"); + let stderr = String::from_utf8_lossy(&warn.stderr); + assert!(warn.status.success(), "{stderr}"); + assert!(stderr.contains("step 1: unknown key `operaton`; did you mean `operation`?"), "{stderr}"); + // A warned step's warning is printed even when a later step fails. + let failing = dir.join("typo_then_failure.json"); + std::fs::write(&failing, format!(r#"{{"commands": [{box_}, {{"command": "no.such_command"}}]}}"#)).unwrap(); + let out = Command::new(env!("CARGO_BIN_EXE_solidcraft-cli")) + .args(["mcp", "--in", failing.to_str().unwrap(), "--param-check", "warn"]) + .stdin(Stdio::null()) + .output() + .unwrap(); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(!out.status.success(), "{stderr}"); + assert!(stderr.contains("step 1: unknown key `operaton`") && stderr.contains("step 2"), "{stderr}"); + // Off: the script runs as before, and the server ends with its input. + let off = run("off"); + assert!(off.status.success(), "{}", String::from_utf8_lossy(&off.stderr)); + assert!(!String::from_utf8_lossy(&off.stderr).contains("operaton")); + // A bare flag is an error, not off. + let bare = Command::new(env!("CARGO_BIN_EXE_solidcraft-cli")).args(["mcp", "--param-check"]).stdin(Stdio::null()).output().unwrap(); + assert!(!bare.status.success()); + assert!(String::from_utf8_lossy(&bare.stderr).contains("--param-check wants off, warn or strict")); + std::fs::remove_dir_all(&dir).ok(); +} diff --git a/assets/locales/en.json b/assets/locales/en.json index 1419c4bb2..77c030df3 100644 --- a/assets/locales/en.json +++ b/assets/locales/en.json @@ -422,6 +422,7 @@ "cmd.edit_checkpoint": "Checkpoint", "cmd.edit_restore_checkpoint": "Restore Checkpoint", "cmd.engine_commands": "List Commands", + "cmd.engine_describe": "Describe Command", "cmd.explode_create": "Exploded View", "cmd.explode_delete": "Delete Exploded View", "cmd.explode_list": "List Exploded Views", diff --git a/assets/locales/ja.json b/assets/locales/ja.json index 09499f014..d6f0ace30 100644 --- a/assets/locales/ja.json +++ b/assets/locales/ja.json @@ -422,6 +422,7 @@ "cmd.edit_checkpoint": "チェックポイント", "cmd.edit_restore_checkpoint": "チェックポイントを復元", "cmd.engine_commands": "コマンドを一覧表示", + "cmd.engine_describe": "コマンドの詳細を表示", "cmd.explode_create": "分解図", "cmd.explode_delete": "分解図を削除", "cmd.explode_list": "分解図を一覧表示", diff --git a/assets/locales/zh.json b/assets/locales/zh.json index cee0926dd..f236bdb8d 100644 --- a/assets/locales/zh.json +++ b/assets/locales/zh.json @@ -422,6 +422,7 @@ "cmd.edit_checkpoint": "检查点", "cmd.edit_restore_checkpoint": "恢复检查点", "cmd.engine_commands": "列出命令", + "cmd.engine_describe": "描述命令", "cmd.explode_create": "爆炸图", "cmd.explode_delete": "删除爆炸图", "cmd.explode_list": "列出爆炸图", diff --git a/crates/engine/Cargo.toml b/crates/engine/Cargo.toml index 58ab39c2a..3080f1b8c 100644 --- a/crates/engine/Cargo.toml +++ b/crates/engine/Cargo.toml @@ -17,6 +17,13 @@ solidcraft-io = { workspace = true } solidcraft-render = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } +schemars = { workspace = true } +serde_path_to_error = { workspace = true } thiserror = { workspace = true } log = { workspace = true } web-time = { workspace = true } + +[features] +# Turns on the parameter-contract audit recorder (`SOLIDCRAFT_PARAM_AUDIT`, see +# `src/schema/record.rs`), for checking a new contract against the whole test suite. +param-audit = [] diff --git a/crates/engine/src/cmd/face_tests.rs b/crates/engine/src/cmd/face_tests.rs index 5ff74c3a3..73c02e39b 100644 --- a/crates/engine/src/cmd/face_tests.rs +++ b/crates/engine/src/cmd/face_tests.rs @@ -260,7 +260,7 @@ fn join_keeps_exact_face_attachments_from_both_operands() { run(&mut s, "sketch.create", json!({"plane":"YZ"})); run(&mut s, "sketch.circle.center", json!({"center":[0,20],"radius":5})); run(&mut s, "sketch.finish", json!({})); - run(&mut s, "solid.extrude", json!({"distance":20,"symmetric":true,"operation":"join"})); + run(&mut s, "solid.extrude", json!({"distance":20,"operation":"join"})); run(&mut s, "sketch.create", json!({"plane":{"face":[0,0,40]}})); run(&mut s, "sketch.circle.center", json!({"center":[0,0],"radius":4})); run(&mut s, "sketch.finish", json!({})); diff --git a/crates/engine/src/cmd/features.rs b/crates/engine/src/cmd/features.rs index ec9d9748e..ceba6a01d 100644 --- a/crates/engine/src/cmd/features.rs +++ b/crates/engine/src/cmd/features.rs @@ -11,13 +11,19 @@ use solidcraft_geom::Vec3; use super::{CommandSpec, not_in_sketch}; use crate::params::{bad, bool_, expr, req_expr, str_, string_list, vec2, vec3}; +use crate::schema::{BoxParams, ExtrudeParams, FeatureResult, TypedContract, output_schema_for}; use crate::{EngineError, Result, Session}; +const BOX_CONTRACT: TypedContract = TypedContract::new(); +const EXTRUDE_CONTRACT: TypedContract = TypedContract::new(); + pub static COMMANDS: &[CommandSpec] = &[ - CommandSpec::new("solid.extrude", "Extrude", extrude) + CommandSpec::new("solid.extrude", "Extrude", crate::checked!("solid.extrude", EXTRUDE_CONTRACT, extrude)) .at("SOLID", "CREATE") .icon("extrude") .key("E") + .contract(&EXTRUDE_CONTRACT) + .output(output_schema_for::) .params("distance: expr (or through_all: true); taper?: angle expr; sketch?: id|name (default: active or last sketch); profiles?: all | [index] | [{curves: [ids]}] (the profile whose outer loop is made of exactly these curves, or pieces of them; found again on every recompute, so it follows parameter changes; islands inside are its holes; an error when no profile or several match) | [{point:[x,y]}] (index and point picks are stored by their curves when that finds the same profile); face?: [x,y,z] (extrude a planar body face instead of a sketch profile); faces?: [[x,y,z],…] (coplanar faces of one body); face_body?: name (whose face, where faces of several bodies meet at the point); direction?: positive|negative|symmetric (distance is total thickness, split evenly around the start plane); convention?: total_distance|legacy_per_side (default total_distance; legacy preserves older symmetric extents); distance2?: expr (Two Sides: a second distance the other way from the first side, which may be through_all or to; with direction: negative the first side goes against the normal and distance2 along it); start_offset?: expr (along the sketch normal, also with direction: negative); to?: [x,y,z] (To Object: a face, vertex or point; to_offset?: expr past it); from?: [x,y,z] (From Object: start at that face or point); operation?: new|join|cut|intersect|auto (cut into a body, otherwise join existing solids; new in an empty component); targets?: [body] (Join from a face, or from a sketch on a body's face, defaults to that face's body; explicit targets or participants override); name?; body_name?; thin?: true (Thin: a wall along sketch curves instead of the profiles) with curves?: [curve ids] (open chains and closed loops, joined where they meet end to end; default: every drawn curve of the sketch), thickness: expr, side?: center|inside|outside|two_sides (a closed loop's inside is the area it encloses, an open chain's the side it bends toward, a straight line's the left of its first curve as drawn; default center), thickness2?: expr (two_sides: the thickness outside); corners are mitred, crossing walls are one"), CommandSpec::new("solid.revolve", "Revolve", revolve) .at("SOLID", "CREATE") @@ -28,7 +34,12 @@ pub static COMMANDS: &[CommandSpec] = &[ .icon("sweep") .params("sketch: profile sketch; profiles?; path_sketch: sketch; path: [curve ids in order]; orientation?: perpendicular (default: square to the path, turning with it) | parallel (as drawn: the profile moves without turning; the path must keep crossing its plane) | [x,y,z] (square to the path, its turn about the path fixed by this direction); twist?: angle expr (the profile turns this much about the path over its length; within 4 turns); scale?: expr (the profile's scale at the end, linear along the path; 0.01…100); rails?: [{sketch?: sketch (default path_sketch), curves: [curve ids in order]}] (guide rails, one or two, each meeting every plane square to the path once along it, from the end nearest the path's start: one rail turns the profile so its point where the rail starts stays on the rail and scales it with the rail's distance from the path; two rails carry it between them, its points where they start staying on both; rails take the default orientation, no twist and no scale, and a path without sharp corners); rail_fit?: scale (default: the profile grows and shrinks evenly) | stretch (only across to the rail, between the rails); operation?, targets?, name?, body_name?"), CommandSpec::new("solid.loft", "Loft", loft).at("SOLID", "CREATE").icon("loft").params("sections: [{sketch, profiles?} | {sketch, point: id} (an apex)] (2…50, in order; matching hole counts, no holes at an apex); rails?: [{sketch, curves: [ids in order]}] (one or two guide rails from the first section to the last, through every section's outline: the loft follows them between the sections; not with sections that have holes); rail_fit?: scale|stretch (default scale: with one rail the sections grow evenly with the rail's distance from their middle, with two with the distance between the rails; stretch: only that way); operation?, targets?, name?, body_name?"), - CommandSpec::new("solid.box", "Box", prim_box).at("SOLID", "CREATE").icon("box").params("length, width, height: expr; corner?: [x,y,z] | center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"), + CommandSpec::new("solid.box", "Box", crate::checked!("solid.box", BOX_CONTRACT, prim_box)) + .at("SOLID", "CREATE") + .icon("box") + .contract(&BOX_CONTRACT) + .output(output_schema_for::) + .params("length, width, height: expr; corner?: [x,y,z] | center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"), CommandSpec::new("solid.cylinder", "Cylinder", prim_cylinder).at("SOLID", "CREATE").icon("cylinder").params("radius | diameter, height: expr; base?: [x,y,z] (centre of the bottom: numbers in mm or length expressions; default: the origin); axis?: X|Y|Z|[x,y,z] (default Z); operation?, targets?: [body], name?, body_name?"), CommandSpec::new("solid.sphere", "Sphere", prim_sphere).at("SOLID", "CREATE").icon("sphere").params("radius | diameter: expr; center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"), CommandSpec::new("solid.torus", "Torus", prim_torus).at("SOLID", "CREATE").icon("torus").params("major, minor: expr (radii); center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"), @@ -334,7 +345,7 @@ pub(super) fn stable_profiles(s: &Session, kind: &mut FeatureKind) -> Result<()> Ok(()) } -pub(super) fn profiles(p: &Value, cmd: &str) -> Result { +pub(crate) fn profiles(p: &Value, cmd: &str) -> Result { let Some(v) = p.get("profiles") else { return Ok(ProfileSel::All) }; match v { Value::Object(fields) => { @@ -560,8 +571,19 @@ fn add_feature_in(s: &mut Session, p: &Value, kind: FeatureKind, world: bool) -> // A warning (a Boolean that needed a retry, a reference found again elsewhere) is part of // the reply: a script or an agent sees it without asking the timeline (#616). let warning = r.as_ref().and_then(|r| r.warning.clone()); - Ok(json!({"feature": id, "name": fname, "bodies": bodies, "created_bodies": created, "changed_bodies": changed, - "removed_bodies": removed, "warning": warning, "ms": r.map(|r| r.ms)})) + let owned = |names: Vec<&str>| names.into_iter().map(str::to_string).collect(); + let reply = FeatureResult { + feature: id, + name: fname, + bodies: owned(bodies), + created_bodies: owned(created), + changed_bodies: owned(changed), + removed_bodies: owned(removed), + warning, + ms: r.map(|r| r.ms), + param_warnings: Vec::new(), + }; + serde_json::to_value(reply).map_err(|e| EngineError::Other(e.to_string())) } fn extrude(s: &mut Session, p: &Value) -> Result { diff --git a/crates/engine/src/cmd/inspect.rs b/crates/engine/src/cmd/inspect.rs index fc82f8864..db25052dc 100644 --- a/crates/engine/src/cmd/inspect.rs +++ b/crates/engine/src/cmd/inspect.rs @@ -44,6 +44,13 @@ pub static COMMANDS: &[CommandSpec] = &[ .doc_only() .params("→ the built-in materials, then the design's own (user: true, with their look)"), CommandSpec::new("engine.commands", "List Commands", commands).icon("list").noundo(), + CommandSpec::new("engine.describe", "Describe Command", crate::checked!("engine.describe", DESCRIBE_CONTRACT, describe)) + .icon("list") + .noundo() + .doc_only() + .contract(&DESCRIBE_CONTRACT) + .output(crate::schema::output_schema_for::) + .params("command: a command id. Returns {id, label, params, input, output} (and param_warnings in the warn parameter-check mode): the command's parameter documentation and, once the command has a typed contract, the JSON Schemas (2020-12) of its parameters and of a successful result (null otherwise). Read-only."), ]; pub fn measure_json(b: &solidcraft_doc::ModelBody) -> Value { @@ -319,6 +326,23 @@ fn model_faces(s: &mut Session, p: &Value) -> Result { Ok(json!({"body": b.name, "faces": faces})) } +const DESCRIBE_CONTRACT: crate::schema::TypedContract = crate::schema::TypedContract::new(); + +/// A command's prose documentation and, for converted commands, its schemas. +fn describe(_s: &mut Session, p: &Value) -> Result { + let id = p.get("command").and_then(Value::as_str).ok_or_else(|| crate::params::bad("engine.describe", "`command` must be a command id"))?; + let spec = super::find_command(id).ok_or_else(|| crate::EngineError::UnknownCommand(id.to_string()))?; + let reply = crate::schema::DescribeResult { + id: spec.id.to_string(), + label: spec.label.to_string(), + params: spec.params.to_string(), + input: spec.contract.map(|c| c.input_schema().to_value()), + output: spec.output.map(|f| f().to_value()), + param_warnings: Vec::new(), + }; + serde_json::to_value(reply).map_err(|e| crate::EngineError::Other(e.to_string())) +} + fn commands(s: &mut Session, _p: &Value) -> Result { Ok(Value::Array(crate::command_specs().iter().map(|c| serde_json::to_value(c.info(s)).unwrap_or_default()).collect())) } diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rs index 864bf7827..9e8f0623e 100644 --- a/crates/engine/src/cmd/mod.rs +++ b/crates/engine/src/cmd/mod.rs @@ -35,6 +35,7 @@ mod edit; mod face; mod features; mod features_more; +pub(crate) use features::profiles as feature_profiles; pub use features::{auto_operation, extrude_reach}; pub use sketch_modify::trim_piece; mod component_link; @@ -96,6 +97,7 @@ pub type Run = fn(&mut Session, &Value) -> Result; /// evaluate as usual). pub type LiveRun = fn(&mut Session, &Value) -> Result<(Value, Option)>; pub type Enabled = fn(&Session) -> std::result::Result<(), String>; +pub type SchemaFn = fn() -> schemars::Schema; pub struct CommandSpec { pub id: &'static str, @@ -120,6 +122,11 @@ pub struct CommandSpec { pub reads_model: bool, /// Registered but not built yet (see `planned!`): the GitHub issue number that tracks it. pub planned: Option<&'static str>, + /// The command's typed parameter contract, which carries its input schema; `None` until + /// the command is converted (see `crate::schema`). + pub contract: Option<&'static dyn crate::schema::Contract>, + /// The JSON Schema of a successful result; `None` until described. + pub output: Option, } impl CommandSpec { @@ -138,6 +145,8 @@ impl CommandSpec { live: None, reads_model: true, planned: None, + contract: None, + output: None, } } /// Not built yet; `issue` tracks building it. @@ -168,6 +177,16 @@ impl CommandSpec { self.shortcut = Some(k); self } + /// The command's typed parameter contract (see `crate::schema`). + pub const fn contract(mut self, c: &'static dyn crate::schema::Contract) -> Self { + self.contract = Some(c); + self + } + /// The JSON Schema of a successful result. + pub const fn output(mut self, f: SchemaFn) -> Self { + self.output = Some(f); + self + } pub const fn params(mut self, p: &'static str) -> Self { self.params = p; self @@ -325,7 +344,7 @@ pub(crate) fn did_you_mean(id: &str) -> String { } /// Levenshtein distance: the single-character edits that turn `a` into `b`. -fn edit_distance(a: &str, b: &str) -> usize { +pub(crate) fn edit_distance(a: &str, b: &str) -> usize { let b: Vec = b.chars().collect(); let mut row: Vec = (0..=b.len()).collect(); for (i, ca) in a.chars().enumerate() { diff --git a/crates/engine/src/hole_face_tests.rs b/crates/engine/src/hole_face_tests.rs index 43d6499e1..ededdd431 100644 --- a/crates/engine/src/hole_face_tests.rs +++ b/crates/engine/src/hole_face_tests.rs @@ -92,7 +92,7 @@ fn a_slanted_hole_stays_on_its_axis_when_its_face_moves() { // part: a 40 x 40 x 20 box at z 0..20 (32000 mm³). fn box_part(s: &mut Session) { - run(s, "solid.box", json!({"length": 40, "width": 40, "height": 20, "name": "Part", "position": [20, 20, 0]})); + run(s, "solid.box", json!({"length": 40, "width": 40, "height": 20, "name": "Part"})); } /// A sketch named `Pts` on the XY plane lifted to `z`, holding the given points (ids p0, p1, ...). diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index 9f1fc0bba..a11fba4af 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -20,6 +20,7 @@ pub mod product_scene; pub mod recovery; pub mod render_jobs; pub mod sample; +pub mod schema; mod slicer_icon; pub mod slicers; pub mod timing; @@ -230,6 +231,9 @@ pub struct Session { pub revision: u64, /// Project a face's edges into a sketch created on it (the default; `sketch.auto_project`). pub auto_project: bool, + /// How calls that break a command's parameter contract are treated (off by default). It + /// belongs to the session, not the design, so it survives opening and starting designs. + pub param_check: schema::ParamCheck, /// The component new sketches and features go into (0 = the root). pub active_component: u64, /// The placement used when authoring shared component geometry. @@ -374,6 +378,7 @@ impl Session { log: Vec::new(), revision: 1, auto_project: true, + param_check: schema::ParamCheck::Off, active_component: 0, active_occurrence_path: None, pending_moves: Default::default(), @@ -403,10 +408,12 @@ impl Session { /// are the user's rather than the design's: `auto_project` is a preference (#680). pub fn replace_design(&mut self, fresh: Session) { let auto_project = self.auto_project; + let param_check = self.param_check; let render_viewport = self.render_viewport.clone(); let render_jobs = self.render_jobs.scratch(); *self = fresh; self.auto_project = auto_project; + self.param_check = param_check; self.render_viewport = render_viewport; self.render_jobs = render_jobs; } @@ -846,6 +853,7 @@ impl Session { log: Vec::new(), revision: self.revision, auto_project: self.auto_project, + param_check: self.param_check, active_component: self.active_component, active_occurrence_path: self.active_occurrence_path.clone(), pending_moves: self.pending_moves.clone(), @@ -976,18 +984,24 @@ impl Session { /// Run a script: a JSON array of `{"command": id, "params": {...}}` (or an object with a /// `commands` array). Stops at the first error. Returns each command's result. pub fn run_script(&mut self, script: &Value) -> Result> { - Ok(self.run_script_with(script, None)?.0) + Ok(self.run_script_with(script, None, &mut |_, _| {})?.0) + } + + /// [`Session::run_script`], calling `each(index, result)` as each command succeeds, so a + /// caller sees the steps before a later one fails. + pub fn run_script_each(&mut self, script: &Value, each: &mut dyn FnMut(usize, &Value)) -> Result> { + Ok(self.run_script_with(script, None, each)?.0) } /// [`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))?; + let (results, timings) = self.run_script_with(script, Some(profile), &mut |_, _| {})?; Ok((results, timings.unwrap_or(Value::Null))) } - fn run_script_with(&mut self, script: &Value, profile: Option) -> Result<(Vec, Option)> { + fn run_script_with(&mut self, script: &Value, profile: Option, each: &mut dyn FnMut(usize, &Value)) -> Result<(Vec, Option)> { let list = match script { Value::Array(a) => a.clone(), Value::Object(o) => { @@ -1016,7 +1030,9 @@ impl Session { } None => self.execute(id, &p), }; - out.push(r.map_err(|e| EngineError::Other(format!("step {} ({id}): {e}", i + 1)))?); + let r = r.map_err(|e| EngineError::Other(format!("step {} ({id}): {e}", i + 1)))?; + each(i, &r); + out.push(r); } let timings = profile.map(|_| serde_json::json!({"timings": steps, "total_ms": timing::round_ms(clock.ms())})); Ok((out, timings)) diff --git a/crates/engine/src/schema/check.rs b/crates/engine/src/schema/check.rs new file mode 100644 index 000000000..a98883e84 --- /dev/null +++ b/crates/engine/src/schema/check.rs @@ -0,0 +1,270 @@ +//! Contracts, the unknown-key check and the adapter that runs a converted command. + +use std::any::TypeId; +use std::collections::{BTreeSet, HashMap}; +use std::marker::PhantomData; +use std::sync::{Arc, Mutex, OnceLock}; + +use schemars::generate::SchemaSettings; +use schemars::{JsonSchema, Schema}; +use serde::de::DeserializeOwned; +use serde_json::{Map, Value, json}; + +use super::record; +use crate::cmd::Run; +use crate::params::bad; +use crate::{Result, Session}; + +/// How a session treats calls that break a command's contract. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum ParamCheck { + /// Nothing is checked; commands behave as they always have. + #[default] + Off, + /// The call runs, and a successful object result gains `param_warnings`. + Warn, + /// The call is refused, and nothing runs. + Strict, +} + +impl ParamCheck { + pub fn parse(s: &str) -> Option { + match s.trim().to_ascii_lowercase().as_str() { + "off" => Some(ParamCheck::Off), + "warn" => Some(ParamCheck::Warn), + "strict" => Some(ParamCheck::Strict), + _ => None, + } + } +} + +/// The JSON Schema (2020-12) of what deserializes into `T`: a command's parameters. +pub fn input_schema_for() -> Schema { + SchemaSettings::draft2020_12().for_deserialize().into_generator().into_root_schema_for::() +} + +/// The JSON Schema (2020-12) of what `T` serializes to: a command's result. +pub fn output_schema_for() -> Schema { + SchemaSettings::draft2020_12().for_serialize().into_generator().into_root_schema_for::() +} + +/// One way a call breaks a contract. +#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct Issue { + /// Where: a top-level key (each field type reads its whole value); empty for the whole call. + pub path: String, + /// The message, in the engine's style (without the `invalid parameters for …` prefix). + pub message: String, + /// For an unknown key, the closest key the command takes. + pub suggestion: Option, +} + +/// A command's typed parameter contract. +pub trait Contract: Sync { + /// The parameters' JSON Schema. + fn input_schema(&self) -> Schema; + /// The top-level keys the command takes. + fn allowed_keys(&self) -> Arc>; + /// Unknown keys and badly shaped parameters in `params`, without running anything. + fn check(&self, params: &Value) -> Vec; +} + +/// The contract "the parameters deserialize into `P`". Stateless; `fn() -> P` keeps it +/// `Send + Sync` whatever `P` is. +pub struct TypedContract

(PhantomData P>); + +impl

TypedContract

{ + pub const fn new() -> Self { + TypedContract(PhantomData) + } +} + +impl

Default for TypedContract

{ + fn default() -> Self { + Self::new() + } +} + +/// Allowed keys per contract type, worked out once from its schema. +static KEYS: OnceLock>>>> = OnceLock::new(); + +impl Contract for TypedContract

{ + fn input_schema(&self) -> Schema { + input_schema_for::

() + } + + fn allowed_keys(&self) -> Arc> { + let keys = KEYS.get_or_init(Default::default); + let mut keys = keys.lock().unwrap_or_else(|poisoned| poisoned.into_inner()); + keys.entry(TypeId::of::

()).or_insert_with(|| Arc::new(schema_keys(input_schema_for::

().as_value()))).clone() + } + + fn check(&self, params: &Value) -> Vec { + let object = match params { + // `Session::execute` reads `null` as `{}`. + Value::Null => return Vec::new(), + Value::Object(o) => o, + _ => return vec![Issue { path: String::new(), message: "parameters must be an object".into(), suggestion: None }], + }; + let mut issues = unknown_keys(object, &self.allowed_keys()); + if let Err(e) = serde_path_to_error::deserialize::<_, P>(params) { + issues.push(parse_issue(&e)); + } + issues + } +} + +/// The most keys of one call that are looked at, and the longest key given a suggestion. +const MAX_KEYS: usize = 64; +const MAX_KEY_LEN: usize = 64; +const MAX_MESSAGE_LEN: usize = 300; +const MAX_WHOLE_LEN: usize = 4096; + +/// Marks a deserializer's message as complete as it is (a handler's own wording, such as +/// ``unknown operation `bogus` (…)``), so [`parse_issue`] doesn't put the key in front. +const WHOLE: char = '\u{1}'; + +/// `message`, marked as complete (see [`WHOLE`]). +pub(crate) fn whole(message: impl std::fmt::Display) -> String { + format!("{WHOLE}{message}") +} + +/// The top-level property names of a schema, following `allOf`/`anyOf`/`oneOf` and `$ref`s +/// into the root's `$defs`. +pub(crate) fn schema_keys(root: &Value) -> BTreeSet { + fn walk(root: &Value, node: &Value, out: &mut BTreeSet, depth: usize) { + if depth > 16 { + return; + } + if let Some(props) = node.get("properties").and_then(Value::as_object) { + out.extend(props.keys().cloned()); + } + for k in ["allOf", "anyOf", "oneOf"] { + for branch in node.get(k).and_then(Value::as_array).into_iter().flatten() { + walk(root, branch, out, depth + 1); + } + } + if let Some(name) = node.get("$ref").and_then(Value::as_str).and_then(|r| r.strip_prefix("#/$defs/")) + && let Some(target) = root.get("$defs").and_then(|d| d.get(name)) + { + walk(root, target, out, depth + 1); + } + } + let mut out = BTreeSet::new(); + walk(root, root, &mut out, 0); + out +} + +/// The keys of `params` that `allowed` doesn't list, each with the closest allowed key. +fn unknown_keys(params: &Map, allowed: &BTreeSet) -> Vec { + let mut issues: Vec = params + .keys() + .take(MAX_KEYS) + .filter(|k| !allowed.contains(*k)) + .map(|k| { + let suggestion = nearest(k, allowed); + // A hostile key is cut, so errors and warnings stay small. + let k = truncate(k, MAX_KEY_LEN); + let message = match &suggestion { + Some(s) => format!("unknown key `{k}`; did you mean `{s}`?"), + None => format!("unknown key `{k}`"), + }; + Issue { path: k, message, suggestion } + }) + .collect(); + if params.len() > MAX_KEYS { + issues.push(Issue { path: String::new(), message: format!("too many parameters ({}; at most {MAX_KEYS})", params.len()), suggestion: None }); + } + issues +} + +/// `s` cut to at most `max` bytes, on a character boundary, with `…` when cut. +pub(crate) fn truncate(s: &str, max: usize) -> String { + if s.len() <= max { + return s.to_string(); + } + let mut end = max; + while end > 0 && !s.is_char_boundary(end) { + end -= 1; + } + format!("{}…", s.get(..end).unwrap_or_default()) +} + +/// The allowed key closest to `key`, when it is close enough to be a likely typo. Keys are +/// short, so short keys may be one edit away at most (`x` is not a typo of `to`). +fn nearest(key: &str, allowed: &BTreeSet) -> Option { + if key.len() > MAX_KEY_LEN { + return None; + } + let key = key.to_ascii_lowercase(); + let near = (key.chars().count() / 3).max(1); + allowed + .iter() + .map(|a| (crate::cmd::edit_distance(&key, &a.to_ascii_lowercase()), a)) + .filter(|(d, _)| *d <= near) + .min_by_key(|(d, _)| *d) + .map(|(_, a)| a.clone()) +} + +/// A deserialization failure as an issue, in the engine's style. +fn parse_issue(e: &serde_path_to_error::Error) -> Issue { + let path = e.path().to_string(); + let path = if path == "." { String::new() } else { path }; + let inner = e.inner().to_string(); + if let Some(complete) = inner.strip_prefix(WHOLE) { + // The handler's own message, which names the caller's value: in full up to a generous + // cap, since the contract also checks keys the handler ignores (`side` without `thin`). + return Issue { path, message: truncate(complete, MAX_WHOLE_LEN), suggestion: None }; + } + let message = if let Some(field) = inner.strip_prefix("missing field `").and_then(|r| r.split('`').next()) { + let at = if path.is_empty() { field.to_string() } else { format!("{path}.{field}") }; + return Issue { path: at.clone(), message: format!("`{at}` is required"), suggestion: None }; + } else if path.is_empty() { + inner + } else if inner.starts_with("must ") { + format!("`{path}` {inner}") + } else if let Some((_, expected)) = inner.strip_prefix("invalid type: ").and_then(|r| r.rsplit_once(", expected ")) { + // serde's wording for the plain types, in the engine's (`thin` must be true or false). + let expected = match expected { + "a boolean" => "true or false", + "a string" => "text", + other => other, + }; + format!("`{path}` must be {expected}") + } else { + format!("`{path}`: {inner}") + }; + // serde quotes the caller's value, which may be long. + Issue { path, message: truncate(&message, MAX_MESSAGE_LEN), suggestion: None } +} + +/// Run `handler` as the command `id`, checking the call against `contract` as the session's +/// [`ParamCheck`] level asks (see the module docs). With the level off and no audit recorder, +/// this is exactly `handler(s, p)`. +pub fn run_checked(s: &mut Session, p: &Value, id: &str, contract: &dyn Contract, handler: Run) -> Result { + let level = s.param_check; + let recording = record::enabled(); + if level == ParamCheck::Off && !recording { + return handler(s, p); + } + let issues = contract.check(p); + if level == ParamCheck::Strict + && let Some(first) = issues.first() + { + if recording { + record::note(id, &issues, None, p); + } + return Err(bad(id, first.message.clone())); + } + let result = handler(s, p); + if recording && !issues.is_empty() { + record::note(id, &issues, Some(&result), p); + } + match result { + Ok(Value::Object(mut o)) if level == ParamCheck::Warn && !issues.is_empty() => { + o.insert("param_warnings".into(), json!(issues.iter().map(|i| i.message.as_str()).collect::>())); + Ok(Value::Object(o)) + } + other => other, + } +} diff --git a/crates/engine/src/schema/commands.rs b/crates/engine/src/schema/commands.rs new file mode 100644 index 000000000..c9d7920d0 --- /dev/null +++ b/crates/engine/src/schema/commands.rs @@ -0,0 +1,220 @@ +//! The converted commands' parameter contracts and result types. +//! +//! Field doc comments are the schemas' descriptions. Keys the handlers read only in some +//! situations (`sketch` without `face`, the thin-wall keys with `thin: true`) are optional +//! fields whose descriptions say so; the contracts don't check the combinations, and the +//! handlers ignore those keys otherwise. + +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use super::types::{ + AngleExpr, ConventionParam, DirectionParam, ExtentKeyword, ExtrudeOperation, FacesParam, FromPoint, IdOrName, LengthExpr, OperationParam, Point3, + PointExpr3, ProfilesParam, StringList, ThinSideParam, ToPoint, present, +}; + +/// Add a box primitive. +#[derive(Debug, Deserialize, JsonSchema)] +#[schemars(deny_unknown_fields)] +pub struct BoxParams { + /// Size along X. + pub length: LengthExpr, + /// Size along Y. + pub width: LengthExpr, + /// Size along Z. + pub height: LengthExpr, + /// The box's minimum corner. Default: the origin. When both `corner` and `center` are given, + /// `corner` is used. + #[serde(default, deserialize_with = "present")] + #[schemars(with = "PointExpr3")] + pub corner: Option, + /// The box's centre, instead of `corner`. + #[serde(default, deserialize_with = "present")] + #[schemars(with = "PointExpr3")] + pub center: Option, + /// How the box combines with existing bodies. Default: new. + #[serde(default)] + pub operation: Option, + /// The bodies a join, cut or intersect works on. Default: the bodies the box meets. + #[serde(default)] + pub targets: Option, + /// The bodies taking part (the same as `targets` for a primitive). + #[serde(default)] + pub participants: Option, + /// The feature's name in the timeline. + #[serde(default)] + pub name: Option, + /// The new body's name. + #[serde(default)] + pub body_name: Option, + /// Names for the new bodies, in order. + #[serde(default)] + pub body_names: Option, +} + +/// Extrude sketch profiles (or a planar body face) into a solid. +#[derive(Debug, Deserialize, JsonSchema)] +#[schemars(deny_unknown_fields)] +pub struct ExtrudeParams { + /// How far: the length one way; with `direction: symmetric`, the total thickness (per side + /// with `convention: legacy_per_side`); with `distance2`, the first side's length. Required + /// unless `through_all` or `to` is given. + #[serde(default)] + pub distance: Option, + /// The sketch to extrude, by id or name. Default: the active sketch, else the last one. + /// Ignored when `face` is given. + #[serde(default, deserialize_with = "present")] + #[schemars(with = "IdOrName")] + pub sketch: Option, + /// Which of the sketch's profiles to extrude. Default: all of them. Ignored when `face` is + /// given; not allowed with `thin`. + #[serde(default, deserialize_with = "present")] + #[schemars(with = "ProfilesParam")] + pub profiles: Option, + /// A point on a planar body face to extrude instead of a sketch profile. + #[serde(default)] + pub face: Option, + /// Several coplanar faces of one body to extrude together, by a point on each. Not with + /// `face`, `sketch` or `profiles`. + #[serde(default, deserialize_with = "present")] + #[schemars(with = "FacesParam")] + pub faces: Option, + /// The body whose face to use, where faces of several bodies meet at `face` (or `faces`). + #[serde(default)] + pub face_body: Option, + /// With `face`, among placed instances: the body whose placement `face` is read in (read by + /// the engine's frame mapping, before the command runs). Default: `face_body`, else the + /// body nearest the point. + #[serde(default)] + pub body: Option, + /// Extrude through everything in the way. + #[serde(default)] + pub through_all: Option, + /// `"through_all"`, the same as `through_all: true`. + #[serde(default)] + pub extent: Option, + /// Draft angle of the side walls. + #[serde(default)] + pub taper: Option, + /// Which way to extrude. Default: positive. + #[serde(default)] + pub direction: Option, + /// Two Sides: a second distance the other way from the first side, which may be + /// `through_all` or `to`; with `direction: negative` the first side goes against the normal + /// and `distance2` along it. + #[serde(default)] + pub distance2: Option, + /// Start this far from the sketch plane, along its normal. + #[serde(default)] + pub start_offset: Option, + /// How a symmetric distance is read. Default: total_distance. + #[serde(default, deserialize_with = "present")] + #[schemars(with = "ConventionParam")] + pub convention: Option, + /// Extrude up to this face, vertex or point (To Object). + #[serde(default, deserialize_with = "present")] + #[schemars(with = "ToPoint")] + pub to: Option, + /// How far past `to` to go. + #[serde(default)] + pub to_offset: Option, + /// Start at this face or point (From Object). + #[serde(default, deserialize_with = "present")] + #[schemars(with = "FromPoint")] + pub from: Option, + /// How the extrusion combines with existing bodies. Default: new. + #[serde(default)] + pub operation: Option, + /// The bodies a join, cut or intersect works on. Default for a join from a body's face: + /// that body. + #[serde(default)] + pub targets: Option, + /// The bodies taking part; overrides the default scope. + #[serde(default)] + pub participants: Option, + /// The feature's name in the timeline. + #[serde(default)] + pub name: Option, + /// The new body's name. + #[serde(default)] + pub body_name: Option, + /// Names for the new bodies, in order. + #[serde(default)] + pub body_names: Option, + /// A thin wall along sketch curves instead of solid profiles. + // `skip_serializing_if` keeps schemars from writing `default: null`, which `bool` refuses. + #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")] + #[schemars(with = "bool")] + pub thin: Option, + /// With `thin`: the curves the wall follows. Default: every drawn curve of the sketch. + #[serde(default)] + pub curves: Option, + /// With `thin`: the wall's thickness. + #[serde(default)] + pub thickness: Option, + /// With `thin`: which side of the curves the wall lies on. Default: center. + #[serde(default)] + pub side: Option, + /// With `thin` and `side: two_sides`: the thickness outside. + #[serde(default)] + pub thickness2: Option, +} + +/// Which command to describe. +#[derive(Debug, Deserialize, JsonSchema)] +#[schemars(deny_unknown_fields)] +pub struct DescribeParams { + /// The command's id, such as `solid.extrude`. + #[serde(deserialize_with = "command_id")] + pub command: String, +} + +/// A command id, with the `engine.describe` handler's message for anything else. +fn command_id<'de, D: serde::Deserializer<'de>>(d: D) -> Result { + match Value::deserialize(d)? { + Value::String(s) => Ok(s), + _ => Err(serde::de::Error::custom("must be a command id")), + } +} + +/// What `engine.describe` returns. +#[derive(Debug, Serialize, JsonSchema)] +pub struct DescribeResult { + pub id: String, + pub label: String, + /// The command's parameter documentation, as prose. + pub params: String, + /// The parameters' JSON Schema, or `null` when the command has no contract yet. + pub input: Option, + /// The successful result's JSON Schema, or `null` when not described yet. + pub output: Option, + /// In the warn parameter-check mode: what the call's parameters got wrong. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub param_warnings: Vec, +} + +/// What a feature command returns. +#[derive(Debug, Serialize, JsonSchema)] +pub struct FeatureResult { + /// The new feature's id. + pub feature: u64, + /// The new feature's name. + pub name: String, + /// Every body after the feature. + pub bodies: Vec, + /// The bodies the feature made. + pub created_bodies: Vec, + /// Bodies that were there before and now have other geometry. + pub changed_bodies: Vec, + /// Bodies that are gone. + pub removed_bodies: Vec, + /// A warning from the evaluation (a Boolean that needed a retry, a reference found again + /// elsewhere), or `null`. + pub warning: Option, + /// How long the feature took to evaluate, in milliseconds. + pub ms: Option, + /// In the warn parameter-check mode: what the call's parameters got wrong. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub param_warnings: Vec, +} diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rs new file mode 100644 index 000000000..3ca510527 --- /dev/null +++ b/crates/engine/src/schema/mod.rs @@ -0,0 +1,54 @@ +//! Typed parameter contracts for commands. +//! +//! A converted command declares a [`Contract`]: a Rust type its parameters must deserialize +//! into, from which the input JSON Schema is generated. The contract is checked *in front of* +//! the unchanged handler, which still reads the raw parameters, so a command's behaviour does +//! not change unless the session's [`ParamCheck`] level asks for warnings or refusals. +//! +//! - **Off** (the default): nothing is parsed or checked; the handler runs as before. +//! - **Warn**: the handler runs; a successful object result gains `param_warnings`. +//! - **Strict**: a call with an unknown key or a parameter of the wrong shape is refused, and +//! nothing runs. +//! +//! Unknown keys are the top-level keys a call sends that the contract's schema does not list. +//! Keys the engine reads around a command count too: `frames::to_local` reads `body` for +//! commands with picks (extrude's `face`), which the extrude contract declares; it otherwise +//! rewrites only keys a call already has. `live` is read only for commands with `.live(…)`, and +//! `timeline.redefine` adds only `convention` and `participants`, which the contracts declare. +//! +//! The shared field types in [`types`] decide acceptance by calling the same helpers the +//! handlers use (`params::vec3`, `params::expr`, `Operation::parse`, `features::profiles`…), so +//! "the contract accepts it" means "the handler's own reader accepts it". Where the handler is +//! more lenient (a value of the wrong type read as if the key were absent), the contract is the +//! stricter of the two; that difference is what warn and strict surface. +//! +//! To convert a command: declare its parameters type in `commands.rs` (and its reply type, for +//! an output schema), give its `CommandSpec` `checked!(…)`, `.contract(…)` and `.output(…)` as +//! `solid.extrude` does, and add it to `schemas_and_the_key_check_agree` and, for messages it +//! already gives, `strict_keeps_todays_errors`. Then run the whole test suite with the audit +//! recorder (see `record.rs`): a call that succeeds today but breaks the contract is either a +//! form the contract is missing or a caller's mistake. + +mod check; +mod commands; +#[cfg_attr(target_arch = "wasm32", path = "record_wasm.rs")] +mod record; +mod types; + +#[cfg(test)] +mod tests; + +pub use check::{Contract, Issue, ParamCheck, TypedContract, input_schema_for, output_schema_for, run_checked}; +pub use commands::{BoxParams, DescribeParams, DescribeResult, ExtrudeParams, FeatureResult}; +pub use types::*; + +/// A command's `run` that checks the call against `$contract` before running `$handler` +/// (see [`run_checked`]). Expands to a non-capturing closure, which coerces to the registry's +/// `Run` function pointer. +#[macro_export] +#[doc(hidden)] +macro_rules! checked { + ($id:literal, $contract:path, $handler:path) => { + |s: &mut $crate::Session, p: &serde_json::Value| $crate::schema::run_checked(s, p, $id, &$contract, $handler) + }; +} diff --git a/crates/engine/src/schema/record.rs b/crates/engine/src/schema/record.rs new file mode 100644 index 000000000..ed7894c39 --- /dev/null +++ b/crates/engine/src/schema/record.rs @@ -0,0 +1,96 @@ +//! The audit recorder, for checking a new contract against every caller the tests have: in a +//! build with the `param-audit` feature, when `SOLIDCRAFT_PARAM_AUDIT` names a directory, every +//! call to a command with a contract that breaks it is recorded, with what the command did, so a +//! test run shows which callers the contracts would warn about or refuse. Without the feature it +//! is compiled (so it is linted and tested) but never on. +//! +//! ```text +//! SOLIDCRAFT_PARAM_AUDIT=$PWD/audit cargo test --workspace --no-fail-fast --features solidcraft-engine/param-audit +//! python3 scripts/param_audit.py audit +//! ``` +//! +//! A line whose outcome is `ok` is a call that works today and that strict would refuse: a form +//! the contract is missing, or a mistake the handler silently ignores. +//! +//! Records are aggregated per process by signature (command, issues, outcome, test thread) and +//! written to `

/audit-.jsonl` when a signature is first seen and again each time its +//! count reaches a power of two; readers keep the highest `count` per signature in each file +//! and add the files up. A process keeps at most 4096 signatures and counts later new ones +//! under one `dropped` line. Writing never fails a command. + +use std::collections::HashMap; +use std::io::Write; +use std::path::PathBuf; +use std::sync::{Mutex, OnceLock}; + +use serde_json::{Value, json}; + +use super::check::{Issue, truncate}; +use crate::Result; + +static DIR: OnceLock> = OnceLock::new(); +static SEEN: OnceLock>> = OnceLock::new(); + +/// The most signatures a process keeps; later new ones are dropped, and one line says so. +const MAX_SIGNATURES: usize = 4096; + +fn dir() -> Option<&'static PathBuf> { + DIR.get_or_init(|| std::env::var_os("SOLIDCRAFT_PARAM_AUDIT").filter(|v| !v.is_empty()).map(PathBuf::from)).as_ref() +} + +/// Whether the recorder is on: built with `param-audit` and the variable set (read once per +/// process). +pub fn enabled() -> bool { + cfg!(feature = "param-audit") && dir().is_some() +} + +/// Count one more call with signature `key`. A new signature beyond `max` is counted under +/// one `dropped` entry instead. Returns whether it was dropped and the count, when the count is +/// a power of two (a line is due). +pub(crate) fn tally(seen: &mut HashMap, key: String, max: usize) -> Option<(bool, u64)> { + let dropped = seen.len() >= max && !seen.contains_key(&key); + let count = seen.entry(if dropped { "dropped".into() } else { key }).or_insert(0); + *count += 1; + count.is_power_of_two().then_some((dropped, *count)) +} + +/// One line of the audit file; `sample_params` is cut to 1 KB (empty for `null`). +pub(crate) fn line(command: &str, issues: &[impl serde::Serialize], outcome: &str, source: &str, count: u64, params: &Value) -> Value { + let sample = if params.is_null() { String::new() } else { truncate(¶ms.to_string(), 1024) }; + json!({"command": command, "issues": issues, "outcome": outcome, "source": source, "count": count, "sample_params": sample}) +} + +/// What a call did, for its audit line: `ok`, `error: …` from the handler, or `refused` when +/// strict refused it before the handler ran (`None`). +pub(crate) fn outcome_text(outcome: Option<&Result>) -> String { + match outcome { + None => "refused".to_string(), + Some(Ok(_)) => "ok".to_string(), + Some(Err(e)) => format!("error: {}", truncate(&e.to_string(), 200)), + } +} + +/// Record one call of `command` that broke its contract with `issues`, and what it did +/// (`None`: refused before the handler ran). +pub fn note(command: &str, issues: &[Issue], outcome: Option<&Result>, params: &Value) { + let Some(dir) = dir().filter(|_| enabled()) else { return }; + // A handler's own message names the caller's value, which may be long. + let mut messages: Vec = issues.iter().map(|i| truncate(&i.message, 300)).collect(); + messages.sort_unstable(); + messages.dedup(); + let outcome = outcome_text(outcome); + let source = std::thread::current().name().unwrap_or("unnamed").to_string(); + let key = json!([command, messages, outcome, source]).to_string(); + let seen = SEEN.get_or_init(Default::default); + // The lock is held while writing, so this process's lines never interleave. + let mut seen = seen.lock().unwrap_or_else(|poisoned| poisoned.into_inner()); + let line = match tally(&mut seen, key, MAX_SIGNATURES) { + None => return, + Some((true, count)) => line("*", &["too many signatures; later new ones dropped"], "dropped", "*", count, &Value::Null), + Some((false, count)) => line(command, &messages, &outcome, &source, count, params), + }; + let path = dir.join(format!("audit-{}.jsonl", std::process::id())); + if let Ok(mut f) = std::fs::OpenOptions::new().create(true).append(true).open(path) { + let _ = f.write_all(format!("{line}\n").as_bytes()); + } +} diff --git a/crates/engine/src/schema/record_wasm.rs b/crates/engine/src/schema/record_wasm.rs new file mode 100644 index 000000000..32d618f1b --- /dev/null +++ b/crates/engine/src/schema/record_wasm.rs @@ -0,0 +1,12 @@ +//! The audit recorder is native-only; in the browser it is never on. + +use serde_json::Value; + +use super::check::Issue; +use crate::Result; + +pub fn enabled() -> bool { + false +} + +pub fn note(_command: &str, _issues: &[Issue], _outcome: Option<&Result>, _params: &Value) {} diff --git a/crates/engine/src/schema/tests.rs b/crates/engine/src/schema/tests.rs new file mode 100644 index 000000000..390c4eaab --- /dev/null +++ b/crates/engine/src/schema/tests.rs @@ -0,0 +1,633 @@ +use serde::de::DeserializeOwned; +use serde_json::{Value, json}; + +use super::check::schema_keys; +use super::*; +use crate::Session; + +fn parse(v: Value) -> Option { + serde_json::from_value(v).ok() +} + +fn box_contract() -> TypedContract { + TypedContract::new() +} + +fn messages(issues: &[Issue]) -> Vec { + issues.iter().map(|i| i.message.clone()).collect() +} + +#[test] +fn expressions_accept_what_params_expr_accepts() { + for v in [json!(5), json!(-2.5), json!("w / 2"), json!(" 30 mm "), json!(999_999_999.0)] { + let want = crate::params::expr(&json!({ "v": v.clone() }), "v"); + assert_eq!(parse::(v.clone()).map(|e| e.0), want, "{v}"); + assert!(want.is_some(), "{v}"); + } + let long = "x".repeat(4097); + // The cap is in bytes: 2049 two-byte characters are too long (the schema's maxLength counts + // characters, so it can't say this). + let wide = "é".repeat(2049); + for v in [json!(true), json!(null), json!(""), json!(" "), json!(1e9), json!(-1e9), json!([1]), json!({}), json!(long), json!(wide)] { + assert!(crate::params::expr(&json!({ "v": v.clone() }), "v").is_none(), "{v}"); + assert!(parse::(v.clone()).is_none(), "{v}"); + assert!(parse::(v.clone()).is_none(), "{v}"); + } +} + +#[test] +fn points_accept_what_the_point_readers_accept() { + assert!(parse::(json!([1, 2, 3])).is_some()); + assert!(parse::(json!({"x": 1, "y": 2, "z": 3, "label": "extra keys are fine"})).is_some()); + for v in [json!([1, 2]), json!([1, 2, 3, 4]), json!(["a", 2, 3]), json!(null), json!({"x": 1, "y": 2}), json!([1e9, 0, 0])] { + assert!(parse::(v.clone()).is_none(), "{v}"); + } + assert!(parse::(json!([1, 2])).is_some()); + assert!(parse::(json!([1, 2, 3])).is_none()); + assert!(parse::(json!([1, "w / 2", 3])).is_some()); + assert!(parse::(json!({"x": "a", "y": 0, "z": "b + 1"})).is_some()); + for v in [json!([1, 2]), json!(null), json!([true, 1, 2]), json!({"x": 1, "y": 2}), json!("origin")] { + assert!(parse::(v.clone()).is_none(), "{v}"); + } +} + +#[test] +fn names_and_lists() { + assert_eq!(parse::(json!("A")).map(|l| l.0), Some(vec!["A".to_string()])); + assert_eq!(parse::(json!(["A", "B"])).map(|l| l.0), Some(vec!["A".to_string(), "B".to_string()])); + let too_many: Vec<&str> = vec!["x"; 10_001]; + for v in [json!([1]), json!(5), json!(null), json!(too_many.clone())] { + assert!(parse::(v.clone()).is_none(), "{v}"); + } + let c = TypedContract::::new(); + assert_eq!(messages(&c.check(&json!({"distance": 5, "targets": too_many}))), vec!["`targets` must have at most 10000 items"]); + assert!(parse::(json!(3)).is_some()); + assert!(parse::(json!("Base")).is_some()); + assert!(parse::(json!(null)).is_none()); +} + +#[test] +fn operations_match_operation_parse() { + for s in [ + "new", + "join", + "cut", + "intersect", + "newbody", + "newcomponent", + "union", + "add", + "subtract", + "difference", + "intersection", + "New Body", + "NEW-body", + "Cut", + ] { + assert!(parse::(json!(s)).is_some(), "{s}"); + assert!(parse::(json!(s)).is_some(), "{s}"); + } + assert!(parse::(json!("auto")).is_none(), "box takes no auto"); + assert!(parse::(json!("AUTO")).is_some()); + assert!(parse::(json!(" auto")).is_none(), "auto is matched without trimming"); + for v in [json!("bogus"), json!(5), json!(null)] { + assert!(parse::(v.clone()).is_none(), "{v}"); + } +} + +#[test] +fn extrude_keywords() { + assert!(parse::(json!("SYMMETRIC")).is_some()); + assert!(parse::(json!("flip")).is_some()); + assert!(parse::(json!(" symmetric")).is_none(), "not trimmed"); + assert!(parse::(json!("Through_All")).is_some()); + assert!(parse::(json!("to_next")).is_none()); + assert!(parse::(json!("total_distance")).is_some()); + assert!(parse::(json!("Total_Distance")).is_none(), "serde, case-sensitive"); + assert!(parse::(json!(" Two-Sides ")).is_some(), "ThinSide::parse trims and maps '-'"); + assert!(parse::(json!("middle")).is_none()); +} + +#[test] +fn profiles_match_features_profiles() { + for v in [json!("all"), json!("ALL"), json!(0), json!([0, 1]), json!([{"point": [1, 2]}]), json!([["l1", "l2"]]), json!([{"curves": ["l1"]}])] { + assert!(parse::(v.clone()).is_some(), "{v}"); + } + for v in [json!("none"), json!([]), json!([true]), json!(null), json!(-1), json!([0, {"point": [1, 2]}])] { + assert!(parse::(v.clone()).is_none(), "{v}"); + } + let c = TypedContract::::new(); + let issue = |profiles: Value| messages(&c.check(&json!({"distance": 5, "profiles": profiles}))); + assert_eq!(issue(json!([])), vec!["`profiles` is empty"]); + assert_eq!(issue(json!(1.5)), vec!["`profiles` must be \"all\", an index or a list"]); + assert_eq!(issue(json!(vec![0; 10_001])), vec!["`profiles` must have at most 10000 items"]); +} + +#[test] +fn unknown_keys_get_suggestions() { + let c = box_contract(); + let issues = c.check(&json!({"length": 5, "width": 5, "height": 5, "operaton": "cut", "colour": "red"})); + assert_eq!(messages(&issues), vec!["unknown key `colour`", "unknown key `operaton`; did you mean `operation`?"]); + assert_eq!(issues.iter().find(|i| i.path == "operaton").and_then(|i| i.suggestion.clone()), Some("operation".into())); + // A hostile key is cut in the message. + let issues = c.check(&json!({"length": 5, "width": 5, "height": 5, "k".repeat(100_000): 1})); + assert_eq!(messages(&issues), vec![format!("unknown key `{}…`", "k".repeat(64))]); + // Short keys get a suggestion only one edit away. + let issues = TypedContract::::new().check(&json!({"distance": 5, "x": 1, "p0": 1, "ids": 1, "sid": "inside"})); + assert_eq!(messages(&issues), vec!["unknown key `ids`", "unknown key `p0`", "unknown key `sid`; did you mean `side`?", "unknown key `x`"]); +} + +#[test] +fn shape_problems_are_issues() { + let c = box_contract(); + assert_eq!(messages(&c.check(&json!({"width": 5, "height": 5}))), vec!["`length` is required"]); + assert_eq!(messages(&c.check(&json!({"length": true, "width": 5, "height": 5}))), vec!["`length` must be a number or an expression"]); + assert_eq!( + messages(&c.check(&json!({"length": 5, "width": 5, "height": 5, "corner": null}))), + vec!["`corner` must be a point [x, y, z] of numbers or length expressions"] + ); + assert_eq!(messages(&c.check(&json!({"length": 5, "width": 5, "height": 5, "name": 7}))), vec!["`name` must be text"]); + let e = TypedContract::::new(); + assert_eq!(messages(&e.check(&json!({"distance": 5, "thin": "true"}))), vec!["`thin` must be true or false"]); + // serde quotes the caller's value: split at the last ", expected ", and cap the message. + assert_eq!(messages(&e.check(&json!({"distance": 5, "through_all": "x, expected y"}))), vec!["`through_all` must be true or false"]); + let long = messages(&e.check(&json!({"distance": 5, "through_all": format!("{}, expected y", "a".repeat(100_000))}))); + assert_eq!(long, vec!["`through_all` must be true or false"]); + assert_eq!(messages(&c.check(&json!([1, 2, 3]))), vec!["parameters must be an object"]); + assert!(c.check(&json!(null)).is_empty(), "null is read as {{}}, which the handler then judges"); + let many: serde_json::Map = (0..70).map(|i| (format!("k{i}"), json!(1))).collect(); + assert!(messages(&c.check(&Value::Object(many))).iter().any(|m| m.starts_with("too many parameters"))); +} + +#[test] +fn schemas_and_the_key_check_agree() { + for (schema, fields) in [ + ( + input_schema_for::(), + vec!["body_name", "body_names", "center", "corner", "height", "length", "name", "operation", "participants", "targets", "width"], + ), + ( + input_schema_for::(), + vec![ + "body", + "body_name", + "body_names", + "convention", + "curves", + "direction", + "distance", + "distance2", + "extent", + "face", + "face_body", + "faces", + "from", + "name", + "operation", + "participants", + "profiles", + "side", + "sketch", + "start_offset", + "taper", + "targets", + "thickness", + "thickness2", + "thin", + "through_all", + "to", + "to_offset", + ], + ), + ] { + let v = schema.as_value(); + assert_eq!(schema_keys(v).into_iter().collect::>(), fields); + assert_eq!(v.get("additionalProperties"), Some(&json!(false)), "the schema refuses unknown keys too"); + assert_eq!(v.get("$schema").and_then(Value::as_str), Some("https://json-schema.org/draft/2020-12/schema")); + } +} + +#[test] +fn present_null_is_refused_but_absent_is_fine() { + let base = json!({"length": 5, "width": 5, "height": 5}); + assert!(box_contract().check(&base).is_empty()); + let c: TypedContract = TypedContract::new(); + assert!(c.check(&json!({"distance": 5})).is_empty()); + // `body` picks the placed instance `face` is read in (frames::to_local), so it is a key. + assert!(c.check(&json!({"distance": 5, "face": [0, 0, 0], "body": "Part"})).is_empty()); + for key in ["sketch", "profiles", "faces", "convention", "to", "from", "thin"] { + let mut p = json!({"distance": 5}); + p[key] = Value::Null; + assert_eq!(c.check(&p).len(), 1, "{key}: null"); + } + // Keys today's reader treats `null` like absence stay optional. + for key in ["taper", "direction", "face", "operation", "name"] { + let mut p = json!({"distance": 5}); + p[key] = Value::Null; + assert!(c.check(&p).is_empty(), "{key}: null"); + } +} + +fn sketch_rectangle(s: &mut Session) { + for (id, p) in [ + ("sketch.create", json!({"plane": "XY"})), + ("sketch.rectangle.center", json!({"center": [0, 0], "corner": [10, 10]})), + ("sketch.finish", json!({})), + ] { + if let Err(e) = s.execute(id, &p) { + panic!("{id}: {e}"); + } + } +} + +fn features(s: &Session) -> usize { + s.doc.features.len() +} + +#[test] +fn off_runs_the_handler_untouched() { + let mut s = Session::default(); + assert_eq!(s.param_check, ParamCheck::Off); + let r = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "operaton": "cut"})); + let r = r.unwrap_or_else(|e| panic!("{e}")); + assert!(r.get("param_warnings").is_none()); + assert_eq!(r["created_bodies"], json!(["Body1"]), "the typo is ignored, as before: a new body"); +} + +#[test] +fn warn_runs_and_reports() { + let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() }; + let r = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "operaton": "cut"})).unwrap_or_else(|e| panic!("{e}")); + assert_eq!(r["param_warnings"], json!(["unknown key `operaton`; did you mean `operation`?"])); + assert_eq!(features(&s), 1); + let r = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "corner": [20, 0, 0]})).unwrap_or_else(|e| panic!("{e}")); + assert!(r.get("param_warnings").is_none(), "a clean call carries no warnings"); +} + +#[test] +fn strict_refuses_and_leaves_the_design_alone() { + let mut s = Session { param_check: ParamCheck::Strict, ..Session::default() }; + let e = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "operaton": "cut"})).err().map(|e| e.to_string()); + assert_eq!(e.as_deref(), Some("invalid parameters for `solid.box`: unknown key `operaton`; did you mean `operation`?")); + assert_eq!(features(&s), 0); + sketch_rectangle(&mut s); + let before = features(&s); + let e = s.execute("solid.extrude", &json!({"distance": 5, "tapper": "10 deg"})).err().map(|e| e.to_string()); + assert_eq!(e.as_deref(), Some("invalid parameters for `solid.extrude`: unknown key `tapper`; did you mean `taper`?")); + let e = s.execute("solid.extrude", &json!({"distance": 5, "operation": 5})).err().map(|e| e.to_string()); + assert!(e.as_deref().is_some_and(|e| e.contains("`operation` must be one of")), "{e:?}"); + assert_eq!(features(&s), before); + s.execute("solid.extrude", &json!({"distance": 5, "direction": "symmetric"})).unwrap_or_else(|e| panic!("{e}")); + assert_eq!(features(&s), before + 1); +} + +#[test] +fn nested_runs_are_checked_too() { + let mut s = Session::default(); + sketch_rectangle(&mut s); + s.execute("solid.extrude", &json!({"distance": 5, "name": "Slab"})).unwrap_or_else(|e| panic!("{e}")); + s.param_check = ParamCheck::Strict; + let e = s + .execute("timeline.redefine", &json!({"feature": "Slab", "command": "solid.extrude", "params": {"distance": 8, "directon": "symmetric"}})) + .err() + .map(|e| e.to_string()); + assert!(e.as_deref().is_some_and(|e| e.contains("unknown key `directon`; did you mean `direction`?")), "{e:?}"); +} + +#[test] +fn the_level_survives_a_new_design() { + let mut s = Session { param_check: ParamCheck::Strict, ..Session::default() }; + s.execute("file.new", &json!({})).unwrap_or_else(|e| panic!("{e}")); + assert_eq!(s.param_check, ParamCheck::Strict); + assert_eq!(s.scratch().param_check, ParamCheck::Strict); +} + +#[test] +fn feature_result_serializes_like_the_old_reply() { + for (warning, ms) in [(None, None), (Some("a Boolean needed a retry".to_string()), Some(12.5)), (None, Some(0.0)), (None, Some(1.0 / 3.0))] { + let old = json!({"feature": 7, "name": "Box1", "bodies": ["A", "B"], "created_bodies": ["B"], "changed_bodies": [], + "removed_bodies": ["C"], "warning": warning, "ms": ms}); + let new = FeatureResult { + feature: 7, + name: "Box1".into(), + bodies: vec!["A".into(), "B".into()], + created_bodies: vec!["B".into()], + changed_bodies: vec![], + removed_bodies: vec!["C".into()], + warning: warning.clone(), + ms, + param_warnings: vec![], + }; + assert_eq!(serde_json::to_value(&new).ok(), Some(old)); + } +} + +/// Whether `v` conforms to `node` of the schema `root`, for the keywords these schemas use +/// apart from `pattern`: `type`, `properties`, `required`, `additionalProperties: false`, +/// `items`, `minItems`, `maxItems`, `uniqueItems`, `enum`, `minLength`, `maxLength`, `minimum`, +/// `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `anyOf`, `not` and `$ref`. (`integer` +/// here is what serde reads as one, so `1.0` is not.) +fn conforms(root: &Value, node: &Value, v: &Value) -> bool { + if let Some(name) = node.get("$ref").and_then(Value::as_str).and_then(|r| r.strip_prefix("#/$defs/")) { + return root.get("$defs").and_then(|d| d.get(name)).is_some_and(|t| conforms(root, t, v)); + } + if let Some(branches) = node.get("anyOf").and_then(Value::as_array) + && !branches.iter().any(|b| conforms(root, b, v)) + { + return false; + } + if node.get("not").is_some_and(|n| conforms(root, n, v)) { + return false; + } + let is = |t: &str| match t { + "null" => v.is_null(), + "boolean" => v.is_boolean(), + "integer" => v.is_u64() || v.is_i64(), + "number" => v.is_number(), + "string" => v.is_string(), + "array" => v.is_array(), + "object" => v.is_object(), + _ => false, + }; + let typed = match node.get("type") { + Some(Value::String(t)) => is(t), + Some(Value::Array(ts)) => ts.iter().filter_map(Value::as_str).any(is), + _ => true, + }; + if !typed { + return false; + } + if let (Some(items), Some(a)) = (node.get("items"), v.as_array()) + && !a.iter().all(|x| conforms(root, items, x)) + { + return false; + } + let bound = |k: &str| node.get(k).and_then(Value::as_u64).map(|n| n as usize); + if let Some(a) = v.as_array() { + let unique = a.iter().enumerate().all(|(i, x)| !a.iter().skip(i + 1).any(|y| y == x)); + if bound("minItems").is_some_and(|n| a.len() < n) + || bound("maxItems").is_some_and(|n| a.len() > n) + || (node.get("uniqueItems") == Some(&json!(true)) && !unique) + { + return false; + } + } + if let Some(s) = v.as_str() { + let n = s.chars().count(); + if bound("minLength").is_some_and(|m| n < m) || bound("maxLength").is_some_and(|m| n > m) { + return false; + } + } + if let Some(x) = v.as_f64() { + let limit = |k: &str| node.get(k).and_then(Value::as_f64); + if limit("minimum").is_some_and(|m| x < m) + || limit("maximum").is_some_and(|m| x > m) + || limit("exclusiveMinimum").is_some_and(|m| x <= m) + || limit("exclusiveMaximum").is_some_and(|m| x >= m) + { + return false; + } + } + if let Some(values) = node.get("enum").and_then(Value::as_array) + && !values.contains(v) + { + return false; + } + if let Some(o) = v.as_object() { + let props = node.get("properties").and_then(Value::as_object); + let mut required = node.get("required").and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str); + if !required.all(|k| o.contains_key(k)) { + return false; + } + for (k, x) in o { + match props.and_then(|p| p.get(k)) { + Some(p) if !conforms(root, p, x) => return false, + None if node.get("additionalProperties") == Some(&json!(false)) => return false, + _ => {} + } + } + } + true +} + +#[test] +fn replies_match_the_output_schema() { + let schema = output_schema_for::(); + let schema = schema.as_value(); + let required: Vec<&str> = schema.get("required").and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str).collect(); + assert!(!required.contains(&"param_warnings")); + let mut s = Session::default(); + sketch_rectangle(&mut s); + s.param_check = ParamCheck::Warn; + let replies = [ + s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "corner": [20, 0, 0]})), + s.execute("solid.extrude", &json!({"distance": 5, "operation": "join"})), + s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "colour": "red"})), + ]; + for r in replies { + let r = r.unwrap_or_else(|e| panic!("{e}")); + assert!(conforms(schema, schema, &r), "{r} doesn't match {schema}"); + } + // The check itself catches a wrong type, a wrong item type and a missing key. (The output + // schema leaves other keys open, so a new result key doesn't break clients.) + let ok = json!({"feature": 1, "name": "Box1", "bodies": [], "created_bodies": [], "changed_bodies": [], "removed_bodies": [], "warning": null, "ms": null}); + assert!(conforms(schema, schema, &ok)); + for (k, v) in [("feature", json!("1")), ("bodies", json!([1])), ("warning", json!(5)), ("ms", json!("1"))] { + let mut bad = ok.clone(); + bad[k] = v; + assert!(!conforms(schema, schema, &bad), "{bad}"); + } + let mut bad = ok.clone(); + bad.as_object_mut().map(|o| o.remove("name")); + assert!(!conforms(schema, schema, &bad), "{bad}"); +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn the_recorder_keeps_a_bounded_number_of_signatures() { + use super::record::tally; + let mut seen = std::collections::HashMap::new(); + // Lines are due at counts 1, 2, 4, … + assert_eq!(tally(&mut seen, "a".into(), 2), Some((false, 1))); + assert_eq!(tally(&mut seen, "a".into(), 2), Some((false, 2))); + assert_eq!(tally(&mut seen, "a".into(), 2), None); + assert_eq!(tally(&mut seen, "b".into(), 2), Some((false, 1))); + // Full: new signatures are counted under one entry; known ones still count. + assert_eq!(tally(&mut seen, "c".into(), 2), Some((true, 1))); + assert_eq!(tally(&mut seen, "d".into(), 2), Some((true, 2))); + assert_eq!(tally(&mut seen, "a".into(), 2), Some((false, 4))); + assert_eq!(seen.len(), 3); +} + +#[test] +fn describe_returns_both_schemas() { + let mut s = Session::default(); + let d = s.execute("engine.describe", &json!({"command": "solid.box"})).unwrap_or_else(|e| panic!("{e}")); + assert_eq!(d["id"], "solid.box"); + assert!(d["input"]["properties"].get("length").is_some()); + assert!(d["output"]["properties"].get("created_bodies").is_some()); + // Its own output schema lists the warnings warn mode can add. + let own = s.execute("engine.describe", &json!({"command": "engine.describe"})).unwrap_or_else(|e| panic!("{e}")); + assert!(own["output"]["properties"].get("param_warnings").is_some(), "{own}"); + let d = s.execute("engine.describe", &json!({"command": "solid.revolve"})).unwrap_or_else(|e| panic!("{e}")); + assert!(d["input"].is_null() && d["output"].is_null(), "unconverted commands have no schemas yet"); + let e = s.execute("engine.describe", &json!({"command": "solid.extrud"})).err().map(|e| e.to_string()); + assert!(e.as_deref().is_some_and(|e| e.contains("did you mean `solid.extrude`")), "{e:?}"); +} + +/// The profiles schema and the contract agree on every listed case; the schema is deliberately +/// narrower on non-text curve ids and loops past the outer one (and describes the app's +/// `whole_boundaries` selection only by its `type`). +#[test] +fn the_profiles_schema_matches_the_contract() { + let root = input_schema_for::(); + let root = root.as_value(); + let node = &root["properties"]["profiles"]; + let accepted = |v: &Value| parse::(v.clone()).is_some(); + for v in [ + json!(3), + json!(-1), + json!([]), + json!([0, 1]), + json!([0, {"point": [1, 2]}]), + json!([{"point": [1, 2]}, {"point": [3, 4]}]), + json!([{"point": [1e9, 2]}]), + json!([["l1"]]), + json!([[]]), + json!([{"curves": "l1"}, ["l2"]]), + json!([{"curves": []}]), + json!([{"loops": []}]), + json!([{"loops": [5]}]), + json!([{"loops": [{"curves": ["l1"]}]}]), + json!({}), + json!({"offset_boundaries": ["a"]}), + json!({"offset_boundaries": []}), + json!({"offset_boundaries": ["a", "a"]}), + json!({"type": "offset_boundaries", "associations": ["a", "b"]}), + json!({"type": "something"}), + serde_json::from_str("18446744073709551616").unwrap_or_default(), + // The helper's precedence: all items with `point` are points; `curves` before `loops`; + // `offset_boundaries` before `type`. + json!([{"point": null, "curves": ["l1"]}]), + json!([{"point": [1, 2], "curves": ["l1"]}]), + json!([{"curves": [], "loops": [{"curves": ["l1"]}]}]), + json!([{"point": [0, 0], "curves": ["l1"]}, ["l2"]]), + json!([{"point": [1, 2], "curves": ["a"]}, {"curves": ["b"]}]), + json!([{"point": [0, 0], "loops": [{"curves": ["l1"]}]}, {"curves": "l2"}]), + json!({"type": "offset_boundaries", "associations": ["a"], "offset_boundaries": []}), + ] { + assert_eq!(conforms(root, node, &v), accepted(&v), "{v}"); + } + // An index is bounded to what the helper reads as a u64. (`conforms` refuses 2^64 above on + // type alone, so the bound itself is checked here.) + let index = |b: &Value| b.get("type") == Some(&json!("integer")); + let bounds: Vec<&Value> = root["$defs"]["Profiles"]["anyOf"] + .as_array() + .into_iter() + .flatten() + .flat_map(|b| [b, &b["items"]]) + .filter(|b| index(b)) + .map(|b| &b["maximum"]) + .collect(); + assert_eq!(bounds, [&json!(u64::MAX), &json!(u64::MAX)]); + // Where the schema is deliberately narrower: non-text ids and loops past the outer one. + for v in [json!([["l1", 5]]), json!([{"loops": [{"curves": ["l1"]}, 5]}])] { + assert!(accepted(&v) && !conforms(root, node, &v), "{v}"); + } +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn recorder_lines_have_the_documented_shape() { + let l = super::record::line("solid.box", &["unknown key `x`"], "ok", "a_test", 4, &json!({"x": "y".repeat(5000)})); + let keys: Vec<&str> = l.as_object().into_iter().flat_map(|o| o.keys().map(String::as_str)).collect(); + assert_eq!(keys, ["command", "count", "issues", "outcome", "sample_params", "source"]); + assert_eq!((l["command"].clone(), l["count"].clone(), l["outcome"].clone()), (json!("solid.box"), json!(4), json!("ok"))); + assert!(l["sample_params"].as_str().is_some_and(|s| s.len() <= 1024 + "…".len() && s.ends_with('…')), "{l}"); + // A strict refusal is told apart from a handler's error. + use super::record::outcome_text; + assert_eq!(outcome_text(None), "refused"); + assert_eq!(outcome_text(Some(&Ok(json!({})))), "ok"); + assert_eq!(outcome_text(Some(&Err(crate::EngineError::Other("boom".into())))), "error: boom"); + // The recorder is on exactly when built with `param-audit` and the variable names a directory. + let set = std::env::var_os("SOLIDCRAFT_PARAM_AUDIT").is_some_and(|v| !v.is_empty()); + assert_eq!(super::record::enabled(), cfg!(feature = "param-audit") && set); +} + +/// A call that already fails gets the same error in strict as with the check off, apart from +/// the missing-key, missing-instead-of-wrong-type, non-object, profile-index, 10,000-item and +/// over-4-KB messages the report lists. +#[test] +fn strict_keeps_todays_errors() { + let cases = [ + ("solid.box", json!({"length": 5, "width": 5, "height": 5, "operation": "bogus"})), + ("solid.box", json!({"length": true, "width": 5, "height": 5})), + ("solid.box", json!({"length": 5, "width": 5, "height": 5, "corner": [1, 2]})), + ("solid.extrude", json!({"distance": 5, "operation": "bogus"})), + ("solid.extrude", json!({"distance": 5, "direction": "sideways"})), + ("solid.extrude", json!({"distance": 5, "direction": "SIDEWAYS"})), + ("solid.extrude", json!({"distance": 5, "profiles": [{"point": [1]}]})), + ("solid.extrude", json!({"distance": 5, "profiles": [["l1"], 7]})), + ("solid.extrude", json!({"distance": 5, "profiles": []})), + ("solid.extrude", json!({"distance": 5, "profiles": [true]})), + ("solid.extrude", json!({"distance": 5, "faces": []})), + ("solid.extrude", json!({"distance": 5, "faces": null})), + ("solid.extrude", json!({"distance": 5, "faces": [[1, 2]]})), + ("solid.extrude", json!({"distance": 5, "profiles": {"offset_boundaries": ["a", "a"]}})), + ("solid.extrude", json!({"distance": 5, "thin": true, "thickness": 1, "side": "middle"})), + ("solid.extrude", json!({"distance": 5, "thin": "true"})), + ("solid.extrude", json!({"distance": 5, "to": [1, 2]})), + ("solid.extrude", json!({"distance": 5, "from": "x"})), + ("solid.extrude", json!({"distance": 5, "sketch": true})), + ("solid.extrude", json!({"distance": 5, "convention": "per_side"})), + ("solid.extrude", json!({"distance": " "})), + ("solid.extrude", json!({"distance": 5, "operation": "x".repeat(1000)})), + ("engine.describe", json!({"command": 5})), + ("engine.describe", json!({"command": null})), + ("engine.describe", json!({"command": "solid.extrud"})), + ]; + for (id, p) in cases { + let error = |level: ParamCheck| { + let mut s = Session { param_check: level, ..Session::default() }; + sketch_rectangle(&mut s); + s.execute(id, &p).err().map(|e| e.to_string()) + }; + let off = error(ParamCheck::Off); + assert!(off.is_some(), "{p} should fail today"); + assert_eq!(error(ParamCheck::Strict), off, "{p}"); + } +} + +/// Every `default` in the input schemas is a value its own property schema allows. +#[test] +fn schema_defaults_are_valid() { + for root in [input_schema_for::(), input_schema_for::()] { + let root = root.as_value(); + for (key, property) in root["properties"].as_object().into_iter().flatten() { + if let Some(d) = property.get("default") { + assert!(conforms(root, property, d), "`{key}`: default {d} doesn't match {property}"); + } + } + } +} + +/// The expression schema's "not blank" pattern uses exactly the whitespace Rust's `trim` does. +#[test] +fn the_blank_pattern_matches_trim() { + let listed = |c: char| super::types::WHITESPACE.iter().any(|&(a, b)| (a..=b).contains(&c)); + for c in (0..=0x10_ffff).filter_map(char::from_u32) { + assert_eq!(listed(c), c.is_whitespace(), "U+{:04X}", c as u32); + } + assert_eq!(super::types::not_blank_pattern(), r"[^\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028-\u2029\u202f\u205f\u3000]"); + assert!(parse::(json!("\u{85}")).is_none() && parse::(json!("\u{feff}")).is_some()); +} + +/// A handler-worded message for a key the handler ignores stays bounded in a warning. +#[test] +fn long_values_in_handler_messages_are_capped() { + let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() }; + sketch_rectangle(&mut s); + let r = s.execute("solid.extrude", &json!({"distance": 5, "side": "x".repeat(1_000_000)})).unwrap_or_else(|e| panic!("{e}")); + let w = r["param_warnings"][0].as_str().unwrap_or_default(); + assert!(w.starts_with("unknown side `xxx") && w.len() <= 4096 + "…".len(), "{} bytes", w.len()); +} diff --git a/crates/engine/src/schema/types.rs b/crates/engine/src/schema/types.rs new file mode 100644 index 000000000..519641f58 --- /dev/null +++ b/crates/engine/src/schema/types.rs @@ -0,0 +1,585 @@ +//! Shared parameter types. Each one decides acceptance with the helper the handlers already +//! use, applied to the raw JSON value, so a contract can never accept a value its handler's own +//! reader would refuse. Their schemas describe the accepted forms. + +use std::borrow::Cow; + +use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema}; +use serde::de::Error as _; +use serde::{Deserialize, Deserializer}; +use serde_json::{Value, json}; +use solidcraft_doc::{Expr, Operation, ThinSide}; +use solidcraft_geom::{Vec2, Vec3}; + +use super::check::whole; +use crate::params; + +/// For optional fields whose key may be absent but not `null`: absent is `None` (with +/// `#[serde(default)]`), a present value, `null` included, goes to `T`'s deserializer. Pair it +/// with `#[schemars(with = "T")]` so the schema has no `null` branch. +pub fn present<'de, D: Deserializer<'de>, T: Deserialize<'de>>(d: D) -> Result, D::Error> { + T::deserialize(d).map(Some) +} + +/// A coordinate's schema: a number below 1e9 in size, as `params::finite` requires. +fn coordinate() -> Value { + json!({"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9}) +} + +/// The characters Rust's `trim` removes (Unicode `White_Space`), as ranges. A regex's `\s` +/// differs (it has U+FEFF and lacks U+0085), so the expression schema spells them out. +pub(crate) const WHITESPACE: [(char, char); 10] = [ + ('\u{9}', '\u{d}'), + (' ', ' '), + ('\u{85}', '\u{85}'), + ('\u{a0}', '\u{a0}'), + ('\u{1680}', '\u{1680}'), + ('\u{2000}', '\u{200a}'), + ('\u{2028}', '\u{2029}'), + ('\u{202f}', '\u{202f}'), + ('\u{205f}', '\u{205f}'), + ('\u{3000}', '\u{3000}'), +]; + +/// A pattern for text that isn't blank once trimmed: a character outside [`WHITESPACE`]. +pub(crate) fn not_blank_pattern() -> String { + let u = |c: char| format!("\\u{:04x}", c as u32); + let class: String = WHITESPACE.iter().map(|&(a, b)| if a == b { u(a) } else { format!("{}-{}", u(a), u(b)) }).collect(); + format!("[^{class}]") +} + +/// `v` as the only key of an object, for the helpers that read `p.get(key)`. +fn wrap(v: Value) -> Value { + json!({ "v": v }) +} + +macro_rules! expr_type { + ($(#[$doc:meta])* $name:ident, $title:literal, $description:literal) => { + $(#[$doc])* + #[derive(Clone, Debug, PartialEq)] + pub struct $name(pub Expr); + + impl<'de> Deserialize<'de> for $name { + fn deserialize>(d: D) -> Result { + params::expr(&wrap(Value::deserialize(d)?), "v").map($name).ok_or_else(|| D::Error::custom("must be a number or an expression")) + } + } + + impl JsonSchema for $name { + fn schema_name() -> Cow<'static, str> { + $title.into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + json_schema!({ + "description": $description, + "anyOf": [ + {"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9}, + {"type": "string", "minLength": 1, "maxLength": 4096, "pattern": not_blank_pattern()} + ] + }) + } + } + }; +} + +expr_type!( + /// A length: a number, read in the design's length unit, or an expression such as + /// `"w / 2"` or `"30 mm"`. + LengthExpr, + "LengthExpr", + "A length: a number in the design's length unit, or an expression such as \"w / 2\" or \"30 mm\"." +); +expr_type!( + /// An angle: a number of degrees, or an expression such as `"30 deg"` or `"a / 2"`. + AngleExpr, + "AngleExpr", + "An angle: a number of degrees, or an expression such as \"30 deg\" or \"a / 2\"." +); + +/// A point in mm: `[x, y, z]` or `{x, y, z}` of finite numbers (read by `params::vec3`). +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Point3(pub Vec3); + +impl<'de> Deserialize<'de> for Point3 { + fn deserialize>(d: D) -> Result { + params::vec3(&Value::deserialize(d)?).map(Point3).ok_or_else(|| D::Error::custom("must be a point [x, y, z] of numbers")) + } +} + +impl JsonSchema for Point3 { + fn schema_name() -> Cow<'static, str> { + "Point3".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + let c = coordinate(); + json_schema!({ + "description": "A point in mm: [x, y, z] or {\"x\", \"y\", \"z\"}.", + "anyOf": [ + {"type": "array", "items": c, "minItems": 3, "maxItems": 3}, + {"type": "object", "properties": {"x": c, "y": c, "z": c}, "required": ["x", "y", "z"]} + ] + }) + } +} + +macro_rules! target_point { + ($(#[$doc:meta])* $name:ident, $message:literal) => { + $(#[$doc])* + #[derive(Clone, Copy, Debug, PartialEq)] + pub struct $name(pub Vec3); + + impl<'de> Deserialize<'de> for $name { + fn deserialize>(d: D) -> Result { + params::vec3(&Value::deserialize(d)?).map($name).ok_or_else(|| D::Error::custom($message)) + } + } + + impl JsonSchema for $name { + fn schema_name() -> Cow<'static, str> { + stringify!($name).into() + } + fn inline_schema() -> bool { + true + } + fn json_schema(generator: &mut SchemaGenerator) -> Schema { + generator.subschema_for::() + } + } + }; +} + +target_point!( + /// Extrude's `to`: a [`Point3`], with the handler's message. + ToPoint, + "must be a point [x, y, z] on the face, vertex or point to extrude to" +); +target_point!( + /// Extrude's `from`: a [`Point3`], with the handler's message. + FromPoint, + "must be a point [x, y, z] on the face or point to start from" +); + +/// Extrude's `faces`: 1 to 1024 points on coplanar faces of one body, read as the handler reads +/// them, with its messages. +#[derive(Clone, Debug, PartialEq)] +pub struct FacesParam(pub Vec); + +impl<'de> Deserialize<'de> for FacesParam { + fn deserialize>(d: D) -> Result { + let v = Value::deserialize(d)?; + let faces = v + .as_array() + .filter(|faces| !faces.is_empty() && faces.len() <= 1024) + .ok_or_else(|| D::Error::custom(whole("faces must contain between 1 and 1024 points")))?; + faces + .iter() + .map(params::vec3) + .collect::>>() + .map(FacesParam) + .ok_or_else(|| D::Error::custom(whole("faces must be points [x,y,z]"))) + } +} + +impl JsonSchema for FacesParam { + fn schema_name() -> Cow<'static, str> { + "Faces".into() + } + fn json_schema(generator: &mut SchemaGenerator) -> Schema { + let point = generator.subschema_for::(); + json_schema!({ + "description": "Points in mm, one on each of the coplanar faces of one body to extrude together.", + "type": "array", "items": point, "minItems": 1, "maxItems": 1024 + }) + } +} + +/// A sketch point in mm: `[x, y]` or `{x, y}` of finite numbers (read by `params::vec2`). +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Point2(pub Vec2); + +impl<'de> Deserialize<'de> for Point2 { + fn deserialize>(d: D) -> Result { + params::vec2(&Value::deserialize(d)?).map(Point2).ok_or_else(|| D::Error::custom("must be a point [x, y] of numbers")) + } +} + +impl JsonSchema for Point2 { + fn schema_name() -> Cow<'static, str> { + "Point2".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + let c = coordinate(); + json_schema!({ + "description": "A sketch point in mm: [x, y] or {\"x\", \"y\"}.", + "anyOf": [ + {"type": "array", "items": c, "minItems": 2, "maxItems": 2}, + {"type": "object", "properties": {"x": c, "y": c}, "required": ["x", "y"]} + ] + }) + } +} + +/// A placement point: `[x, y, z]` or `{x, y, z}`, each a number (mm) or a length expression, +/// as `features::point_param` reads it. Whether the expressions evaluate is checked by the +/// handler, which has the design. +#[derive(Clone, Debug, PartialEq)] +pub struct PointExpr3(pub [Expr; 3]); + +impl<'de> Deserialize<'de> for PointExpr3 { + fn deserialize>(d: D) -> Result { + let v = Value::deserialize(d)?; + let coords: Option> = match &v { + Value::Array(a) if a.len() == 3 => Some(a.iter().collect()), + Value::Object(o) => ["x", "y", "z"].iter().map(|k| o.get(*k)).collect(), + _ => None, + }; + coords + .and_then(|c| c.into_iter().map(|c| params::expr(&wrap(c.clone()), "v")).collect::>>()) + .and_then(|c| <[Expr; 3]>::try_from(c).ok()) + .map(PointExpr3) + .ok_or_else(|| D::Error::custom("must be a point [x, y, z] of numbers or length expressions")) + } +} + +impl JsonSchema for PointExpr3 { + fn schema_name() -> Cow<'static, str> { + "PointExpr3".into() + } + fn json_schema(generator: &mut SchemaGenerator) -> Schema { + let c = generator.subschema_for::(); + json_schema!({ + "description": "A point: [x, y, z] or {\"x\", \"y\", \"z\"}, each a number in mm or a length expression.", + "anyOf": [ + {"type": "array", "items": c, "minItems": 3, "maxItems": 3}, + {"type": "object", "properties": {"x": c, "y": c, "z": c}, "required": ["x", "y", "z"]} + ] + }) + } +} + +/// A feature referred to by its id (a number) or its name (a string). +#[derive(Clone, Debug, PartialEq)] +pub struct IdOrName(pub String); + +impl<'de> Deserialize<'de> for IdOrName { + fn deserialize>(d: D) -> Result { + match Value::deserialize(d)? { + Value::Number(n) => Ok(IdOrName(n.to_string())), + Value::String(s) => Ok(IdOrName(s)), + _ => Err(D::Error::custom("must be an id or name")), + } + } +} + +impl JsonSchema for IdOrName { + fn schema_name() -> Cow<'static, str> { + "IdOrName".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + json_schema!({"description": "A feature's id (a number) or its name.", "type": ["number", "string"]}) + } +} + +/// One name or a list of names, at most 10 000. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct StringList(pub Vec); + +impl<'de> Deserialize<'de> for StringList { + fn deserialize>(d: D) -> Result { + let fail = || D::Error::custom("must be a name or a list of names"); + match Value::deserialize(d)? { + Value::String(s) => Ok(StringList(vec![s])), + Value::Array(a) if a.len() > 10_000 => Err(D::Error::custom("must have at most 10000 items")), + Value::Array(a) => a + .into_iter() + .map(|v| if let Value::String(s) = v { Some(s) } else { None }) + .collect::>>() + .map(StringList) + .ok_or_else(fail), + _ => Err(fail()), + } + } +} + +impl JsonSchema for StringList { + fn schema_name() -> Cow<'static, str> { + "StringList".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + json_schema!({ + "description": "A name, or a list of names.", + "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}, "maxItems": 10000}] + }) + } +} + +/// The spellings `Operation::parse` accepts, canonical ones first (it also ignores case, spaces, +/// '_' and '-', which an enum can't say). +const OPERATIONS: [&str; 13] = [ + "new", + "join", + "cut", + "intersect", + "new_body", + "newbody", + "new_component", + "newcomponent", + "union", + "add", + "subtract", + "difference", + "intersection", +]; + +/// A string `ok` accepts. A string it refuses gets `unknown(s)` (the handler's own message, +/// marked [`whole`]); anything else, which the handlers ignore, "must be one of `expected`". +fn string_matching<'de, D: Deserializer<'de>>( + d: D, + ok: impl Fn(&str) -> bool, + expected: &str, + unknown: impl Fn(&str) -> String, +) -> Result { + match Value::deserialize(d)? { + Value::String(s) if ok(&s) => Ok(s), + Value::String(s) => Err(D::Error::custom(unknown(&s))), + _ => Err(D::Error::custom(format!("must be one of {expected}"))), + } +} + +/// `features::operation`'s message for an operation it doesn't know. +fn unknown_operation(s: &str) -> String { + whole(format!("unknown operation `{s}` (new, join, cut, intersect)")) +} + +fn enum_schema(values: &[&str], description: &str) -> Schema { + json_schema!({"description": description, "type": "string", "enum": values}) +} + +/// How a feature combines with existing bodies, as `features::operation` reads it. +#[derive(Clone, Debug, PartialEq)] +pub struct OperationParam(pub Operation); + +impl<'de> Deserialize<'de> for OperationParam { + fn deserialize>(d: D) -> Result { + let s = string_matching(d, |s| Operation::parse(s).is_some(), "new, join, cut or intersect", unknown_operation)?; + Operation::parse(&s).map(OperationParam).ok_or_else(|| D::Error::custom("must be one of new, join, cut or intersect")) + } +} + +impl JsonSchema for OperationParam { + fn schema_name() -> Cow<'static, str> { + "Operation".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + enum_schema( + &OPERATIONS, + "How the feature combines with existing bodies: new, join, cut or intersect. The others are aliases. Matching ignores case, spaces, '_' and '-'.", + ) + } +} + +/// Extrude's operation: the above or `auto` (matched with `eq_ignore_ascii_case`, as the +/// handler does). +#[derive(Clone, Debug, PartialEq)] +pub struct ExtrudeOperation(pub String); + +impl<'de> Deserialize<'de> for ExtrudeOperation { + fn deserialize>(d: D) -> Result { + let ok = |s: &str| s.eq_ignore_ascii_case("auto") || Operation::parse(s).is_some(); + string_matching(d, ok, "new, join, cut, intersect or auto", unknown_operation).map(ExtrudeOperation) + } +} + +impl JsonSchema for ExtrudeOperation { + fn schema_name() -> Cow<'static, str> { + "ExtrudeOperation".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + let mut values = vec!["auto"]; + values.extend(OPERATIONS); + enum_schema( + &values, + "How the extrusion combines with existing bodies: auto (cut into a body, otherwise join; new in an empty component), new, join, cut or intersect. The others are aliases. Matching ignores case, spaces, '_' and '-' (only case for auto).", + ) + } +} + +const DIRECTIONS: [&str; 6] = ["positive", "negative", "symmetric", "one_side", "reverse", "flip"]; + +/// Extrude's direction, as `extent_param` reads it (lowercased, not trimmed). +#[derive(Clone, Debug, PartialEq)] +pub struct DirectionParam(pub String); + +impl<'de> Deserialize<'de> for DirectionParam { + fn deserialize>(d: D) -> Result { + let ok = |s: &str| DIRECTIONS.contains(&s.to_ascii_lowercase().as_str()); + // The handler names the direction lowercased. + let unknown = |s: &str| whole(format!("unknown direction `{}`", s.to_ascii_lowercase())); + string_matching(d, ok, "positive, negative or symmetric", unknown).map(DirectionParam) + } +} + +impl JsonSchema for DirectionParam { + fn schema_name() -> Cow<'static, str> { + "Direction".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + enum_schema( + &DIRECTIONS, + "Which way to extrude: positive (the default), negative, or symmetric (the distance is the total thickness, split evenly around the start plane). one_side is an alias of positive; reverse and flip of negative. Matching ignores case.", + ) + } +} + +/// The `extent` keyword: only `through_all` (ignoring case) is meaningful. +#[derive(Clone, Debug, PartialEq)] +pub struct ExtentKeyword; + +impl<'de> Deserialize<'de> for ExtentKeyword { + fn deserialize>(d: D) -> Result { + match Value::deserialize(d)? { + Value::String(s) if s.eq_ignore_ascii_case("through_all") => Ok(ExtentKeyword), + _ => Err(D::Error::custom("must be through_all")), + } + } +} + +impl JsonSchema for ExtentKeyword { + fn schema_name() -> Cow<'static, str> { + "ExtentKeyword".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + enum_schema(&["through_all"], "\"through_all\" (any case) is the same as through_all: true.") + } +} + +/// Extrude's distance convention, as `extent_param` reads it (serde, case-sensitive). +#[derive(Clone, Debug, PartialEq)] +pub struct ConventionParam(pub solidcraft_doc::ExtrudeConvention); + +impl<'de> Deserialize<'de> for ConventionParam { + fn deserialize>(d: D) -> Result { + serde_json::from_value(Value::deserialize(d)?).map(ConventionParam).map_err(|_| D::Error::custom("must be total_distance or legacy_per_side")) + } +} + +impl JsonSchema for ConventionParam { + fn schema_name() -> Cow<'static, str> { + "ExtrudeConvention".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + enum_schema( + &["total_distance", "legacy_per_side"], + "total_distance (the default): a symmetric distance is the total thickness. legacy_per_side keeps older designs' per-side meaning.", + ) + } +} + +/// A thin wall's side, as `ThinSide::parse` reads it. +#[derive(Clone, Debug, PartialEq)] +pub struct ThinSideParam(pub ThinSide); + +impl<'de> Deserialize<'de> for ThinSideParam { + fn deserialize>(d: D) -> Result { + let s = string_matching( + d, + |s| ThinSide::parse(s).is_some(), + "center, inside, outside or two_sides", + |s| whole(format!("unknown side `{s}` (center, inside, outside or two_sides)")), + )?; + ThinSide::parse(&s).map(ThinSideParam).ok_or_else(|| D::Error::custom("must be one of center, inside, outside or two_sides")) + } +} + +impl JsonSchema for ThinSideParam { + fn schema_name() -> Cow<'static, str> { + "ThinSide".into() + } + fn json_schema(_: &mut SchemaGenerator) -> Schema { + enum_schema( + &["center", "inside", "outside", "two_sides", "centre", "centered", "centred", "symmetric", "side1", "side_1", "side2", "side_2", "both"], + "Which side of the curves the wall lies on: center (the default), inside, outside or two_sides. The others are aliases. Matching ignores case and surrounding spaces, and reads ' ' and '-' as '_'.", + ) + } +} + +/// Which sketch profiles a feature uses. Accepted exactly when `features::profiles` accepts +/// it; kept as the raw value for the handler. +#[derive(Clone, Debug, PartialEq)] +pub struct ProfilesParam(pub Value); + +impl<'de> Deserialize<'de> for ProfilesParam { + fn deserialize>(d: D) -> Result { + let v = Value::deserialize(d)?; + match crate::cmd::feature_profiles(&json!({ "profiles": v }), "profiles") { + Ok(_) => Ok(ProfilesParam(v)), + // The helper's messages as they are, apart from two terse ones, which get the + // contract's `must be` wording. + Err(crate::EngineError::BadParams { msg, .. }) => Err(D::Error::custom(match msg.as_str() { + "profile index" => "must be \"all\", an index or a list".to_string(), + "too many profiles" => "must have at most 10000 items".to_string(), + _ => whole(msg), + })), + Err(e) => Err(D::Error::custom(e.to_string())), + } + } +} + +impl JsonSchema for ProfilesParam { + fn schema_name() -> Cow<'static, str> { + "Profiles".into() + } + fn json_schema(generator: &mut SchemaGenerator) -> Schema { + let point = generator.subschema_for::(); + let curves = json!({"type": "array", "items": {"type": "string"}, "minItems": 1}); + let named = json!({"anyOf": [{"type": "string"}, curves]}); + let list = |items: Value| json!({"type": "array", "minItems": 1, "maxItems": 10000, "items": items}); + // An index is what the helper reads as a u64. + let index = json!({"type": "integer", "minimum": 0, "maximum": u64::MAX}); + let loops = json!({"type": "array", "minItems": 1, "items": { + "type": "object", "properties": {"outer": {"type": "boolean"}, "curves": named}, "required": ["curves"] + }}); + let associations = json!({ + "type": "array", "minItems": 1, "maxItems": 128, "uniqueItems": true, + "items": {"type": "string", "minLength": 1, "maxLength": 512} + }); + // A list is all indices, all points, or all curve selections, as the helper reads it; + // the `not`s give its precedence (a list whose items all have `point` is points, an + // item's `curves` wins over its `loops`; `type: whole_boundaries` wins over an + // `offset_boundaries` key, which wins over `type: offset_boundaries`). Narrower than + // the helper in one way: every curve id and every loop must be well formed, where the + // helper drops non-text ids and reads only the outer loop. + let curve_object = json!({"type": "object", "properties": {"curves": named}, "required": ["curves"]}); + let loops_object = json!({ + "type": "object", "properties": {"loops": loops}, "required": ["loops"], "not": {"required": ["curves"]} + }); + let curve_list = json!({ + "type": "array", "minItems": 1, "maxItems": 10000, "items": {"anyOf": [curves, curve_object, loops_object]}, + "not": {"items": {"type": "object", "required": ["point"]}} + }); + json_schema!({ + "description": "Which sketch profiles to use: \"all\" (the default, any case), an index, or a list of indices, of {\"point\": [x, y]} inside a profile, or of curve selections (a list of curve ids, {\"curves\": [ids]} or {\"loops\": [...]}). Picks by index or point are stored by the curves around the profile.", + "anyOf": [ + {"type": "string", "pattern": "^[Aa][Ll][Ll]$"}, + index.clone(), + list(index), + list(json!({"type": "object", "properties": {"point": point}, "required": ["point"]})), + curve_list, + { + "description": "Internal selections written by the app.", + "anyOf": [ + {"type": "object", "properties": {"type": {"enum": ["whole_boundaries"]}}, "required": ["type"]}, + { + "type": "object", "properties": {"offset_boundaries": associations}, "required": ["offset_boundaries"], + "not": {"properties": {"type": {"enum": ["whole_boundaries"]}}, "required": ["type"]} + }, + { + "type": "object", "properties": {"type": {"enum": ["offset_boundaries"]}, "associations": associations}, + "required": ["type", "associations"], "not": {"required": ["offset_boundaries"]} + } + ] + } + ] + }) + } +} diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rs index b3091ef31..584f5b4f9 100644 --- a/crates/mcp/src/server.rs +++ b/crates/mcp/src/server.rs @@ -31,7 +31,7 @@ and degrees in expressions (internally radians), Z is up. Model like this: `sket and dimension (`sketch.dimension {entities, value}`; values may name parameters), `sketch.finish`, then features \ (`solid.extrude {distance, operation?: new|join|cut|intersect}`, `solid.revolve`, `solid.fillet {edges: [[x,y,z] point on \ edge], radius}`, `solid.chamfer`, patterns, mirror, primitives). Use `batch` for several steps at once, \ -`list_commands` for ids and parameter docs, `inspect_design` / `measure` to verify, `body_topology` to find edge points, \ +`list_commands` for ids and parameter docs, `describe_command` for a command's schemas, `inspect_design` / `measure` to verify, `body_topology` to find edge points, \ `set_parameter` to drive the design and `screenshot` to look at it."; pub struct Server { diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs index e60ef2aae..98ea3b515 100644 --- a/crates/mcp/src/tests.rs +++ b/crates/mcp/src/tests.rs @@ -88,6 +88,7 @@ fn handshake_and_tools_list() { let names: Vec<&str> = tools["result"]["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap()).collect(); for want in [ "list_commands", + "describe_command", "execute", "batch", "inspect_design", @@ -1479,7 +1480,7 @@ fn tool_annotations_tell_the_whole_truth() { for name in ["execute", "batch", "save", "export", "open", "screenshot"] { assert_eq!(hints(name), (false, true, true), "{name}"); } - for name in ["list_commands", "inspect_design", "measure", "body_topology", "crash_reports"] { + for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports"] { assert_eq!(hints(name), (true, false, false), "{name}"); } assert_eq!(hints("new_design"), (false, true, false)); @@ -1547,3 +1548,24 @@ fn batch_reports_timings_and_profile() { assert_eq!(body["timings"][0]["command"], "a.one", "{body}"); assert!(body["timings"][0].get("profile").is_none(), "{body}"); } + +/// `describe_command` serves a converted command's schemas, and a headless session set to strict +/// refuses a misspelt key through `execute` without touching the design. +#[test] +fn describe_command_and_strict_parameter_checking() { + let mut s = server(); + let d = tool(&mut s, "describe_command", json!({"id": "solid.box"})); + assert!(d["input"]["properties"].get("operation").is_some(), "{d}"); + assert!(d["output"]["properties"].get("created_bodies").is_some(), "{d}"); + + let mut headless = Headless::default(); + headless.session.param_check = solidcraft_engine::schema::ParamCheck::Strict; + let mut s = Server::new(Box::new(headless)); + call(&mut s, 1, "initialize", json!({"protocolVersion": PROTOCOL_VERSION, "capabilities": {}, "clientInfo": {"name": "t", "version": "1"}})); + let r = raw_tool(&mut s, "execute", json!({"command": "solid.box", "params": {"length": 5, "width": 5, "height": 5, "operaton": "cut"}})); + assert_eq!(r["result"]["isError"], json!(true), "{r}"); + let text = r["result"]["content"][0]["text"].as_str().unwrap_or_default(); + assert!(text.contains("unknown key `operaton`; did you mean `operation`?"), "{text}"); + let m = tool(&mut s, "measure", json!({})); + assert_eq!(m["body_count"], json!(0), "{m}"); +} diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index a5d4a9330..750a43c1e 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -72,6 +72,14 @@ pub fn tool_definitions() -> Vec { obj(json!({"filter": string("Substring to match, e.g. \"sketch\", \"fillet\", \"pattern\"")}), &[]), Effect::ReadOnly, ), + tool( + "describe_command", + "Describe a command", + "One command's parameter docs and, for commands with a typed contract (solid.box, solid.extrude and engine.describe so far), the \ + JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); null for the others.", + obj(json!({"id": string("Command id, e.g. \"solid.extrude\"")}), &["id"]), + Effect::ReadOnly, + ), tool( "execute", "Execute a command", @@ -388,6 +396,10 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map) -> Result { + let id = str_arg(a, "id").ok_or("`id` is required")?; + exec(b, "engine.describe", json!({"command": id})) + } "execute" => { let id = str_arg(a, "command").ok_or("`command` is required")?; let v = exec(b, id, a.get("params").cloned().filter(Value::is_object).unwrap_or(json!({})))?; diff --git a/crates/ui-egui/src/agent_chat/gate.rs b/crates/ui-egui/src/agent_chat/gate.rs index 2eb4141c5..ecf49851a 100644 --- a/crates/ui-egui/src/agent_chat/gate.rs +++ b/crates/ui-egui/src/agent_chat/gate.rs @@ -64,7 +64,7 @@ fn reads_only(id: &str) -> bool { || id.starts_with("model.") || id.ends_with(".inspect") || id.ends_with(".list") - || matches!(id, "edit.checkpoint" | "render.status" | "render.backends" | "render.settings.get" | "file.slicers") + || matches!(id, "edit.checkpoint" | "render.status" | "render.backends" | "render.settings.get" | "file.slicers" | "engine.describe") } /// Commands that read or write a file by their nature: any string they are given in a path @@ -235,6 +235,7 @@ mod tests { assert_eq!(exec("sketch.inspect", json!({"sketch": 1})), Verdict::Run { change: false }); assert_eq!(exec("inspect.measure", json!({})), Verdict::Run { change: false }); assert_eq!(request("document.inspect", &json!({}), 0), Verdict::Run { change: false }); + assert_eq!(exec("engine.describe", json!({"command": "solid.box"})), Verdict::Run { change: false }); } #[test] diff --git a/docs/mcp.md b/docs/mcp.md index 7b15492b2..71c033616 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -47,6 +47,16 @@ A `batch` that could not be sent says the app is not running, so it is safe to s stdout carries only protocol messages; errors go to stderr. Bridged screenshots are written to a temporary file by the app and read back by the server, so both must run on the same machine. +### Parameter checking + +Commands with a typed parameter contract (`solid.box`, `solid.extrude` and `engine.describe` +so far; `describe_command` shows a command's schemas) can be checked as they are called. +`--param-check off|warn|strict` sets the level for a headless session, including a script or +recipe given with `--in`; the default is `off`, which changes nothing. `warn` runs the call and +adds `param_warnings` to its result, such as ``unknown key `operaton`; did you mean +`operation`?`` (a starting script's warnings go to stderr). `strict` refuses the call, and the +design is left as it was. Calls bridged to the app are not checked yet. + ### Which files the agent can reach Tool calls read, write and delete files only inside the server's folders: @@ -99,11 +109,11 @@ file dialogs are never limited. ### Tool annotations Each tool says what it may do, for clients that ask before running tools (or auto-approve on -these hints). `list_commands`, `inspect_design`, `measure`, `body_topology` and `crash_reports` -are read-only. `set_parameter`, `undo` and `redo` change the design undoably. `new_design` -replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and `screenshot` (whose -`path` writes a file) can read, write, overwrite or delete files: they are not read-only, -`destructiveHint` and `openWorldHint` are true. +these hints). `list_commands`, `describe_command`, `inspect_design`, `measure`, `body_topology` +and `crash_reports` are read-only. `set_parameter`, `undo` and `redo` change the design undoably. +`new_design` replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and +`screenshot` (whose `path` writes a file) can read, write, overwrite or delete files: they are +not read-only, `destructiveHint` and `openWorldHint` are true. ### Client configuration @@ -143,6 +153,7 @@ They cover the workflow, the command shapes, how to verify with `measure`, and t | Tool | Arguments | What it does | |---|---|---| | `list_commands` | `filter?` | The command catalog: id, label, tab/panel, shortcut, parameter docs, enabled now. `filter` matches id, label, tab and panel. | +| `describe_command` | `id` | One command's parameter docs (`params`) and, for commands with a typed contract (`solid.box`, `solid.extrude` and `engine.describe` so far), the JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); `null` for the others. The same as `execute` `engine.describe {command}`. | | `execute` | `command`, `params?`, `verbose?` (default true) | Run any command with JSON parameters (`list_commands` shows them). Failures leave the design unchanged. A feature command replies with the feature (`feature`, `name`), every body (`bodies`) and the bodies it created, changed and removed (`created_bodies`, `changed_bodies`, `removed_bodies`). `verbose: false` uses the same compact reply as `batch`. | | `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?` (default false) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`) and every result before it. `verbose: false` keeps the reply small in large designs: feature steps leave out the full body list (`created_bodies`, `changed_bodies`, `removed_bodies` stay) and sketch steps the ids they repeat outside `created`. Bridged to an app that has `engine.batch`, the whole batch is one control request (one frame of the app). Older apps, and apps showing the agent cursor, get the steps one by one. `timings: true` adds `timings: [{index, command, ms}]` for every step run, the failing one included, and `total_ms`. `profile: true` also adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`, its time in kernel booleans, in tessellation and the rest. Steps are timed where they run: in the app when bridged. An app without `engine.batch` is timed step by step, without `profile`. | | `inspect_design` | `measure?` (default true), `sketches?` (default true) | Design properties (`metadata`: project, author… and other tools' keys; set them with `execute` `document.metadata.set`), parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts, visible; `removed_later: true` while a sketch is being edited on a rolled-back timeline and a later feature deletes the body, which is then not shown), sketches (curves, points, constraints, profiles, DOF, solve status, visible), selection, undo depth. Hide helper sketches, bodies or construction planes with `execute` `browser.visibility` (`{items, visible}` or `{folder, visible}`), and joint glyphs with `{joints: [id or name], visible}` or `{folder: "joints", visible}` (a hidden joint still constrains and drives; `joint.list` reports each joint's `visible`). | diff --git a/scripts/param_audit.py b/scripts/param_audit.py new file mode 100644 index 000000000..1140e1603 --- /dev/null +++ b/scripts/param_audit.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Summarise a parameter-contract audit: the calls that break a command's contract, by issue. + +Usage: param_audit.py AUDIT_DIR [OUT_JSON] + +AUDIT_DIR is the directory `SOLIDCRAFT_PARAM_AUDIT` named for a test run built with the engine's +`param-audit` feature (see crates/engine/src/schema/record.rs). Each process writes one +audit-.jsonl, repeating a signature's line as its count grows, so this keeps the highest +count per signature in each file and adds the files up. + +The report has three parts: + SUCCEEDS TODAY calls that work now and that strict would refuse: a form the contract is + missing (fix the contract) or a mistake the handler ignores (fix the caller) + ALREADY FAILS calls the handler rejects anyway + REFUSED calls strict refused (tests that run with strict on) + +OUT_JSON, when given, receives every signature with its summed count. +""" +import json +import sys +from collections import Counter, defaultdict +from pathlib import Path + + +def load(audit_dir): + signatures = {} + malformed = [] + files = sorted(audit_dir.glob("audit-*.jsonl")) + for f in files: + per_file = {} + for n, line in enumerate(f.read_text(encoding="utf-8", errors="replace").splitlines(), 1): + if not line.strip(): + continue + try: + r = json.loads(line) + key = json.dumps([r["command"], r["issues"], r["outcome"], r["source"]]) + except (json.JSONDecodeError, KeyError) as e: + malformed.append(f"{f.name}:{n}: {e}") + continue + if key not in per_file or r["count"] > per_file[key]["count"]: + per_file[key] = r + for key, r in per_file.items(): + if key in signatures: + signatures[key] = {**signatures[key], "count": signatures[key]["count"] + r["count"]} + else: + signatures[key] = dict(r) + return files, signatures, malformed + + +def by_issue(records): + counts = Counter() + examples = defaultdict(list) + for r in records: + for issue in r["issues"]: + counts[(r["command"], issue)] += r["count"] + if len(examples[(r["command"], issue)]) < 3: + examples[(r["command"], issue)].append(f"{r['source']}: {r['sample_params'][:300]}") + return counts, examples + + +def main(): + if len(sys.argv) not in (2, 3): + sys.exit(__doc__.split("\n\n")[1]) + files, signatures, malformed = load(Path(sys.argv[1])) + records = list(signatures.values()) + parts = [ + ("SUCCEEDS TODAY, STRICT WOULD REFUSE", [r for r in records if r["outcome"] == "ok"], True), + ("ALREADY FAILS TODAY", [r for r in records if r["outcome"] not in ("ok", "refused")], False), + ("REFUSED BY STRICT", [r for r in records if r["outcome"] == "refused"], False), + ] + print(f"files: {len(files)} signatures: {len(signatures)} malformed lines: {len(malformed)}") + for m in malformed[:10]: + print(" malformed:", m) + for label, part, show_examples in parts: + counts, examples = by_issue(part) + print(f"\n== {label}: {len(part)} signatures, at least {sum(r['count'] for r in part)} calls") + for (command, issue), n in counts.most_common(): + print(f" {n:>7} {command:14} {issue}") + if show_examples: + for e in examples[(command, issue)]: + print(f" e.g. {e}") + if len(sys.argv) == 3: + out = {"signatures": records, "malformed": malformed} + Path(sys.argv[2]).write_text(json.dumps(out, indent=1), encoding="utf-8") + + +if __name__ == "__main__": + main()