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

* Spike: typed parameter contracts and JSON Schemas for solid.box and solid.extrude

The schema RFC's spike (plan/schema-spike.md). solid.box and solid.extrude get
typed contracts with generated JSON Schemas (2020-12), checked in front of the
unchanged handlers by a per-session level: off (the default, which changes
nothing), warn (the call runs and gains param_warnings) or strict (the call is
refused and the design left alone). Also engine.describe and the MCP tool
describe_command, `solidcraft-cli mcp --param-check off|warn|strict`, a
FeatureResult type for feature replies, and an env-var audit recorder
(SOLIDCRAFT_PARAM_AUDIT) used to check the contracts against every test.

Local spike branch; not for upstream as is (see the results report).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Parameter contracts: put the audit recorder behind a feature; drop two ignored test keys

The audit recorder is now on only in a build with the engine's `param-audit` feature
and `SOLIDCRAFT_PARAM_AUDIT` set. Its code is still compiled, linted and tested without
the feature. `scripts/param_audit.py` summarises a test run's audit logs, and the schema
module's docs give the steps for converting a further command.

Two tests passed keys their command ignores, which the audit found: `position` on
`solid.box` (`hole_face_tests.rs`) and `symmetric` on `solid.extrude` (`face_tests.rs`).
Both are removed, so the tests build what they always did. Comments no longer call
the contracts a spike.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: bherbruck <brennen.herbruck@gmail.com>
This commit is contained in:
authored and GitHub committed 2026-10-20 10:45:08 +00:00
1 parent ae2ab87b99
commit 953fd7d5f8
27 files changed
+2279 -26

No files matched your search

Generated
+75
View File
@@ -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",
+3
View File
@@ -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"] }
+36 -6
View File
@@ -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();
@@ -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();
}
+1
View File
@@ -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",
+1
View File
@@ -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": "分解図を一覧表示",
+1
View File
@@ -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": "列出爆炸图",
+7
View File
@@ -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 = []
+1 -1
View File
@@ -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!({}));
+27 -5
View File
@@ -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> {
+24
View File
@@ -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()))
}
+20 -1
View File
@@ -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() {
+1 -1
View File
@@ -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, ...).
+20 -4
View File
@@ -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))
+270
View File
@@ -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,
}
}
+220
View File
@@ -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>,
}
+54
View File
@@ -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)
};
}
+96
View File
@@ -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());
}
}
+12
View File
@@ -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) {}
+633
View File
@@ -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());
}
+585
View File
@@ -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"]}
}
]
}
]
})
}
}
+1 -1
View File
@@ -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 {
+23 -1
View File
@@ -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}");
}
+12
View File
@@ -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!({})))?;
+2 -1
View File
@@ -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]
+16 -5
View File
@@ -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`). |
+88
View File
@@ -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()