Zebra, Draft, Curvature Map, Environment Map, Accessibility, Continuity, Isocurve and Curvature Comb are one group: turning one on turns the one on before off (Session::analyses_off), and the session says which is on (Session::active_analysis). The new inspect.analysis names it and off: true turns it off (typed contract and reply). The toolbar shows the active one's button pressed, its tool running or not. Curvature Comb's button toggles: on, the tool combs the edges clicked; again, off and the combs go; Esc or a right click in the tool turns it off; opening another dialog leaves it on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
77 lines
4.1 KiB
Rust
77 lines
4.1 KiB
Rust
//! 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.
|
|
//!
|
|
//! Contracts live in one module per command file: `features.rs` for `cmd/features.rs`,
|
|
//! `inspect.rs` for `cmd/inspect.rs`, and so on, each with its own tests (`features_tests.rs`),
|
|
//! so conversions of different command files touch different files (apart from a new
|
|
//! module's line below).
|
|
//!
|
|
//! To convert a command: declare its parameters type in the module for its command file (and
|
|
//! its reply type, for an output schema), creating the module if it is the file's first
|
|
//! contract, from the shared types in [`types`] (the keys every feature takes come from
|
|
//! [`FeatureCommon`], which `solid.box` and `solid.extrude` predate); give its `CommandSpec`
|
|
//! `checked!(…)`, `.contract(…)` and `.output(…)` as `solid.extrude` does; and add it to that
|
|
//! module's `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.
|
|
//!
|
|
//! New commands come with both schemas: `coverage_tests.rs` warns about a command without a
|
|
//! contract or an output type (it will fail once `SCHEMA_RULE_STRICT` flips), unless it is a `planned!` placeholder or listed in
|
|
//! `unconverted.txt`, which holds the commands that predate the rule. That list only shrinks:
|
|
//! converting a command removes its line, and nothing is added to it. How to write a contract,
|
|
//! with the shared types and a checklist: docs/book/src/dev/schemas.md.
|
|
|
|
mod check;
|
|
#[cfg_attr(target_arch = "wasm32", path = "record_wasm.rs")]
|
|
mod record;
|
|
mod types;
|
|
|
|
#[cfg(test)]
|
|
mod coverage_tests;
|
|
#[cfg(test)]
|
|
mod tests;
|
|
|
|
// The contracts, by command file.
|
|
pub mod browser;
|
|
pub mod diagnostics;
|
|
pub mod features;
|
|
pub mod inspect;
|
|
pub mod surface_analysis;
|
|
|
|
pub use check::{Contract, Issue, ParamCheck, TypedContract, input_schema_for, output_schema_for, run_checked, run_checked_as};
|
|
pub use types::*;
|
|
|
|
/// A command's `run` that checks the call against the contract command `$id` publishes
|
|
/// (`.contract(…)` on its `CommandSpec`) before running `$handler` (see [`run_checked_as`]), so
|
|
/// the contract enforced is always the one described. Expands to a non-capturing closure, which
|
|
/// coerces to the registry's `Run` function pointer.
|
|
#[macro_export]
|
|
#[doc(hidden)]
|
|
macro_rules! checked {
|
|
($id:literal, $handler:path) => {
|
|
|s: &mut $crate::Session, p: &serde_json::Value| $crate::schema::run_checked_as(s, p, $id, $handler)
|
|
};
|
|
}
|