Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Typed parameter contracts and JSON Schemas for solid.box and solid.extrude (#2829) (#2611)

Matthew Knutson953fd7d5f8fe
diff --git a/Cargo.lock b/Cargo.lock
index 38e2042046..1df6cfe09e 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 fa02d78296..a4cecf4f30 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 5be417c49b..dec00af12d 100644
--- a/apps/solidcraft-cli/src/main.rs
+++ b/apps/solidcraft-cli/src/main.rs
@@ -13,6 +13,7 @@
//! solidcraft-cli recipe <recipe.json> translate an oracle recipe to a script
//! solidcraft-cli oracle <case-dir>... 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 <case-dir>... [--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 <id> | replay <id> | dir | clear [<id>]]
solidcraft-cli licences
solidcraft-cli gpu [--policy auto|hardware|software|cpu]
@@ -154,7 +156,14 @@ pub fn read_json(path: &str) -> Result<Value, String> {
/// A session from a design file, a STEP/3MF/STL file, a command script, or an oracle recipe.
pub fn load(path: &str) -> Result<Session, String> {
+ 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<Session, String> {
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<Session, String> {
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<dyn solidcraft_mcp::Backend> = 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 0000000000..0dab929240
--- /dev/null
+++ b/apps/solidcraft-cli/tests/mcp_param_check.rs
@@ -0,0 +1,50 @@
+//! `mcp --in script --param-check <level>`: 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 1419c4bb27..77c030df3b 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 09499f0146..d6f0ace302 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 cee0926ddd..f236bdb8dd 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 58ab39c2a8..3080f1b8ca 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 5ff74c3a38..73c02e39b7 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 ec9d9748e8..ceba6a01d9 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<BoxParams> = TypedContract::new();
+const EXTRUDE_CONTRACT: TypedContract<ExtrudeParams> = 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::<FeatureResult>)
.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::<FeatureResult>)
+ .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<ProfileSel> {
+pub(crate) fn profiles(p: &Value, cmd: &str) -> Result<ProfileSel> {
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<Value> {
diff --git a/crates/engine/src/cmd/inspect.rs b/crates/engine/src/cmd/inspect.rs
index fc82f8864e..db25052dce 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::<crate::schema::DescribeResult>)
+ .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<Value> {
Ok(json!({"body": b.name, "faces": faces}))
}
+const DESCRIBE_CONTRACT: crate::schema::TypedContract<crate::schema::DescribeParams> = crate::schema::TypedContract::new();
+
+/// A command's prose documentation and, for converted commands, its schemas.
+fn describe(_s: &mut Session, p: &Value) -> Result<Value> {
+ 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<Value> {
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 864bf78276..9e8f0623e0 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<Value>;
/// evaluate as usual).
pub type LiveRun = fn(&mut Session, &Value) -> Result<(Value, Option<crate::LiveEdit>)>;
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<SchemaFn>,
}
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<char> = b.chars().collect();
let mut row: Vec<usize> = (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 43d6499e1a..ededdd4314 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 9f1fc0bbaa..a11fba4afa 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<Vec<Value>> {
- 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<Vec<Value>> {
+ 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>, 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<bool>) -> Result<(Vec<Value>, Option<Value>)> {
+ fn run_script_with(&mut self, script: &Value, profile: Option<bool>, each: &mut dyn FnMut(usize, &Value)) -> Result<(Vec<Value>, Option<Value>)> {
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 0000000000..a98883e848
--- /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<ParamCheck> {
+ 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<T: JsonSchema>() -> Schema {
+ SchemaSettings::draft2020_12().for_deserialize().into_generator().into_root_schema_for::<T>()
+}
+
+/// The JSON Schema (2020-12) of what `T` serializes to: a command's result.
+pub fn output_schema_for<T: JsonSchema>() -> Schema {
+ SchemaSettings::draft2020_12().for_serialize().into_generator().into_root_schema_for::<T>()
+}
+
+/// 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<String>,
+}
+
+/// 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<BTreeSet<String>>;
+ /// Unknown keys and badly shaped parameters in `params`, without running anything.
+ fn check(&self, params: &Value) -> Vec<Issue>;
+}
+
+/// The contract "the parameters deserialize into `P`". Stateless; `fn() -> P` keeps it
+/// `Send + Sync` whatever `P` is.
+pub struct TypedContract<P>(PhantomData<fn() -> P>);
+
+impl<P> TypedContract<P> {
+ pub const fn new() -> Self {
+ TypedContract(PhantomData)
+ }
+}
+
+impl<P> Default for TypedContract<P> {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+/// Allowed keys per contract type, worked out once from its schema.
+static KEYS: OnceLock<Mutex<HashMap<TypeId, Arc<BTreeSet<String>>>>> = OnceLock::new();
+
+impl<P: DeserializeOwned + JsonSchema + 'static> Contract for TypedContract<P> {
+ fn input_schema(&self) -> Schema {
+ input_schema_for::<P>()
+ }
+
+ fn allowed_keys(&self) -> Arc<BTreeSet<String>> {
+ let keys = KEYS.get_or_init(Default::default);
+ let mut keys = keys.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
+ keys.entry(TypeId::of::<P>()).or_insert_with(|| Arc::new(schema_keys(input_schema_for::<P>().as_value()))).clone()
+ }
+
+ fn check(&self, params: &Value) -> Vec<Issue> {
+ 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<String> {
+ fn walk(root: &Value, node: &Value, out: &mut BTreeSet<String>, 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<String, Value>, allowed: &BTreeSet<String>) -> Vec<Issue> {
+ let mut issues: Vec<Issue> = 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<String>) -> Option<String> {
+ 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<serde_json::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<Value> {
+ 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::<Vec<_>>()));
+ 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 0000000000..c9d7920d08
--- /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<PointExpr3>,
+ /// The box's centre, instead of `corner`.
+ #[serde(default, deserialize_with = "present")]
+ #[schemars(with = "PointExpr3")]
+ pub center: Option<PointExpr3>,
+ /// How the box combines with existing bodies. Default: new.
+ #[serde(default)]
+ pub operation: Option<OperationParam>,
+ /// The bodies a join, cut or intersect works on. Default: the bodies the box meets.
+ #[serde(default)]
+ pub targets: Option<StringList>,
+ /// The bodies taking part (the same as `targets` for a primitive).
+ #[serde(default)]
+ pub participants: Option<StringList>,
+ /// The feature's name in the timeline.
+ #[serde(default)]
+ pub name: Option<String>,
+ /// The new body's name.
+ #[serde(default)]
+ pub body_name: Option<String>,
+ /// Names for the new bodies, in order.
+ #[serde(default)]
+ pub body_names: Option<StringList>,
+}
+
+/// 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<LengthExpr>,
+ /// 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<IdOrName>,
+ /// 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<ProfilesParam>,
+ /// A point on a planar body face to extrude instead of a sketch profile.
+ #[serde(default)]
+ pub face: Option<Point3>,
+ /// 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<FacesParam>,
+ /// The body whose face to use, where faces of several bodies meet at `face` (or `faces`).
+ #[serde(default)]
+ pub face_body: Option<String>,
+ /// 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<String>,
+ /// Extrude through everything in the way.
+ #[serde(default)]
+ pub through_all: Option<bool>,
+ /// `"through_all"`, the same as `through_all: true`.
+ #[serde(default)]
+ pub extent: Option<ExtentKeyword>,
+ /// Draft angle of the side walls.
+ #[serde(default)]
+ pub taper: Option<AngleExpr>,
+ /// Which way to extrude. Default: positive.
+ #[serde(default)]
+ pub direction: Option<DirectionParam>,
+ /// 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<LengthExpr>,
+ /// Start this far from the sketch plane, along its normal.
+ #[serde(default)]
+ pub start_offset: Option<LengthExpr>,
+ /// How a symmetric distance is read. Default: total_distance.
+ #[serde(default, deserialize_with = "present")]
+ #[schemars(with = "ConventionParam")]
+ pub convention: Option<ConventionParam>,
+ /// Extrude up to this face, vertex or point (To Object).
+ #[serde(default, deserialize_with = "present")]
+ #[schemars(with = "ToPoint")]
+ pub to: Option<ToPoint>,
+ /// How far past `to` to go.
+ #[serde(default)]
+ pub to_offset: Option<LengthExpr>,
+ /// Start at this face or point (From Object).
+ #[serde(default, deserialize_with = "present")]
+ #[schemars(with = "FromPoint")]
+ pub from: Option<FromPoint>,
+ /// How the extrusion combines with existing bodies. Default: new.
+ #[serde(default)]
+ pub operation: Option<ExtrudeOperation>,
+ /// 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<StringList>,
+ /// The bodies taking part; overrides the default scope.
+ #[serde(default)]
+ pub participants: Option<StringList>,
+ /// The feature's name in the timeline.
+ #[serde(default)]
+ pub name: Option<String>,
+ /// The new body's name.
+ #[serde(default)]
+ pub body_name: Option<String>,
+ /// Names for the new bodies, in order.
+ #[serde(default)]
+ pub body_names: Option<StringList>,
+ /// 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<bool>,
+ /// With `thin`: the curves the wall follows. Default: every drawn curve of the sketch.
+ #[serde(default)]
+ pub curves: Option<StringList>,
+ /// With `thin`: the wall's thickness.
+ #[serde(default)]
+ pub thickness: Option<LengthExpr>,
+ /// With `thin`: which side of the curves the wall lies on. Default: center.
+ #[serde(default)]
+ pub side: Option<ThinSideParam>,
+ /// With `thin` and `side: two_sides`: the thickness outside.
+ #[serde(default)]
+ pub thickness2: Option<LengthExpr>,
+}
+
+/// 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<String, D::Error> {
+ 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<Value>,
+ /// The successful result's JSON Schema, or `null` when not described yet.
+ pub output: Option<Value>,
+ /// 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<String>,
+}
+
+/// 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<String>,
+ /// The bodies the feature made.
+ pub created_bodies: Vec<String>,
+ /// Bodies that were there before and now have other geometry.
+ pub changed_bodies: Vec<String>,
+ /// Bodies that are gone.
+ pub removed_bodies: Vec<String>,
+ /// A warning from the evaluation (a Boolean that needed a retry, a reference found again
+ /// elsewhere), or `null`.
+ pub warning: Option<String>,
+ /// How long the feature took to evaluate, in milliseconds.
+ pub ms: Option<f64>,
+ /// 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<String>,
+}
diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rs
new file mode 100644
index 0000000000..3ca5105276
--- /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 0000000000..ed7894c398
--- /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 `<dir>/audit-<pid>.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<Option<PathBuf>> = OnceLock::new();
+static SEEN: OnceLock<Mutex<HashMap<String, u64>>> = 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<String, u64>, 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(&params.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<Value>>) -> 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<Value>>, 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<String> = 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 0000000000..32d618f1b0
--- /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<Value>>, _params: &Value) {}
diff --git a/crates/engine/src/schema/tests.rs b/crates/engine/src/schema/tests.rs
new file mode 100644
index 0000000000..390c4eaab0
--- /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<T: DeserializeOwned>(v: Value) -> Option<T> {
+ serde_json::from_value(v).ok()
+}
+
+fn box_contract() -> TypedContract<BoxParams> {
+ TypedContract::new()
+}
+
+fn messages(issues: &[Issue]) -> Vec<String> {
+ 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::<LengthExpr>(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::<LengthExpr>(v.clone()).is_none(), "{v}");
+ assert!(parse::<AngleExpr>(v.clone()).is_none(), "{v}");
+ }
+}
+
+#[test]
+fn points_accept_what_the_point_readers_accept() {
+ assert!(parse::<Point3>(json!([1, 2, 3])).is_some());
+ assert!(parse::<Point3>(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::<Point3>(v.clone()).is_none(), "{v}");
+ }
+ assert!(parse::<Point2>(json!([1, 2])).is_some());
+ assert!(parse::<Point2>(json!([1, 2, 3])).is_none());
+ assert!(parse::<PointExpr3>(json!([1, "w / 2", 3])).is_some());
+ assert!(parse::<PointExpr3>(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::<PointExpr3>(v.clone()).is_none(), "{v}");
+ }
+}
+
+#[test]
+fn names_and_lists() {
+ assert_eq!(parse::<StringList>(json!("A")).map(|l| l.0), Some(vec!["A".to_string()]));
+ assert_eq!(parse::<StringList>(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::<StringList>(v.clone()).is_none(), "{v}");
+ }
+ let c = TypedContract::<ExtrudeParams>::new();
+ assert_eq!(messages(&c.check(&json!({"distance": 5, "targets": too_many}))), vec!["`targets` must have at most 10000 items"]);
+ assert!(parse::<IdOrName>(json!(3)).is_some());
+ assert!(parse::<IdOrName>(json!("Base")).is_some());
+ assert!(parse::<IdOrName>(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::<OperationParam>(json!(s)).is_some(), "{s}");
+ assert!(parse::<ExtrudeOperation>(json!(s)).is_some(), "{s}");
+ }
+ assert!(parse::<OperationParam>(json!("auto")).is_none(), "box takes no auto");
+ assert!(parse::<ExtrudeOperation>(json!("AUTO")).is_some());
+ assert!(parse::<ExtrudeOperation>(json!(" auto")).is_none(), "auto is matched without trimming");
+ for v in [json!("bogus"), json!(5), json!(null)] {
+ assert!(parse::<OperationParam>(v.clone()).is_none(), "{v}");
+ }
+}
+
+#[test]
+fn extrude_keywords() {
+ assert!(parse::<DirectionParam>(json!("SYMMETRIC")).is_some());
+ assert!(parse::<DirectionParam>(json!("flip")).is_some());
+ assert!(parse::<DirectionParam>(json!(" symmetric")).is_none(), "not trimmed");
+ assert!(parse::<ExtentKeyword>(json!("Through_All")).is_some());
+ assert!(parse::<ExtentKeyword>(json!("to_next")).is_none());
+ assert!(parse::<ConventionParam>(json!("total_distance")).is_some());
+ assert!(parse::<ConventionParam>(json!("Total_Distance")).is_none(), "serde, case-sensitive");
+ assert!(parse::<ThinSideParam>(json!(" Two-Sides ")).is_some(), "ThinSide::parse trims and maps '-'");
+ assert!(parse::<ThinSideParam>(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::<ProfilesParam>(v.clone()).is_some(), "{v}");
+ }
+ for v in [json!("none"), json!([]), json!([true]), json!(null), json!(-1), json!([0, {"point": [1, 2]}])] {
+ assert!(parse::<ProfilesParam>(v.clone()).is_none(), "{v}");
+ }
+ let c = TypedContract::<ExtrudeParams>::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::<ExtrudeParams>::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::<ExtrudeParams>::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<String, Value> = (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::<BoxParams>(),
+ vec!["body_name", "body_names", "center", "corner", "height", "length", "name", "operation", "participants", "targets", "width"],
+ ),
+ (
+ input_schema_for::<ExtrudeParams>(),
+ 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::<Vec<_>>(), 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<ExtrudeParams> = 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::<FeatureResult>();
+ 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::<ExtrudeParams>();
+ let root = root.as_value();
+ let node = &root["properties"]["profiles"];
+ let accepted = |v: &Value| parse::<ProfilesParam>(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::<BoxParams>(), input_schema_for::<ExtrudeParams>()] {
+ 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::<LengthExpr>(json!("\u{85}")).is_none() && parse::<LengthExpr>(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 0000000000..519641f585
--- /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<Option<T>, 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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::<Point3>()
+ }
+ }
+ };
+}
+
+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<Vec3>);
+
+impl<'de> Deserialize<'de> for FacesParam {
+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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::<Option<Vec<_>>>()
+ .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::<Point3>();
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ let v = Value::deserialize(d)?;
+ let coords: Option<Vec<&Value>> = 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::<Option<Vec<Expr>>>())
+ .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::<LengthExpr>();
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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<String>);
+
+impl<'de> Deserialize<'de> for StringList {
+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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::<Option<Vec<_>>>()
+ .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<String, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ 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::<Point2>();
+ 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 b3091ef31e..584f5b4f9b 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 e60ef2aaef..98ea3b515b 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 a5d4a9330d..750a43c1e0 100644
--- a/crates/mcp/src/tools.rs
+++ b/crates/mcp/src/tools.rs
@@ -72,6 +72,14 @@ pub fn tool_definitions() -> Vec<Value> {
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<String, Value>) -> Result<V
};
Ok(Value::Array(all.as_array().map(|v| v.iter().filter(|c| hit(c)).cloned().collect()).unwrap_or_default()))
}
+ "describe_command" => {
+ 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 2eb4141c51..ecf49851a4 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 7b15492b28..71c033616c 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 0000000000..1140e16036
--- /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-<pid>.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()