Export a design's timeline as a replayable command script (#1045)

timeline.export_script (and solidcraft-cli script) writes a design's history as a command script that solidcraft-cli eval replays into the same design, so a bug that only shows on one design becomes a one-file repro. timeline.add restores one stored feature with its id, names and references, through the same checks a design file gets when it opens.

Closes #886. SychPL's #1078 approached the same issue independently; thanks to both.

Co-authored-by: SychPL <[email protected]>

apps/solidcraft-cli/src/main.rs

@@ -3,6 +3,7 @@
 //! ```text
 //! solidcraft-cli run <script.json|design.solidcraft|part.step|mesh.3mf> [--in design|part.step|mesh.3mf] [--out FILE]... [--save FILE] [--quiet] [--allow-errors]
 //! solidcraft-cli eval <script.json|design.solidcraft|part.step> (alias: inspect) measurements as JSON
+//! solidcraft-cli script <design.solidcraft> [--out script.json]     the design's history as a command script
 //! solidcraft-cli bench-open <design.solidcraft | part.step> [--parse-only] loading timings as JSON lines
 //! solidcraft-cli snapshot <script|design> --out shot.png [--width W] [--height H] [--view iso|front|top|…]
 //! solidcraft-cli exec <command> [json-params]                 run one command on an empty design
@@ -37,6 +38,8 @@ const USAGE: &str = "usage:
   solidcraft-cli run --in <design.solidcraft|part.step> [--out FILE]...
       (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)
   solidcraft-cli eval <script.json|design.solidcraft|part.step>     (alias: inspect; or --in FILE)
+  solidcraft-cli script <design.solidcraft|script.json> [--out script.json]
+      (the design's history as a command script that eval and run replay)
   solidcraft-cli bench-open <design.solidcraft | part.step> [--parse-only]
   solidcraft-cli snapshot <script|design> --out shot.png [--width W] [--height H] [--view iso|front|back|top|bottom|left|right]
   solidcraft-cli exec <command> [json-params]
@@ -55,6 +58,7 @@ fn main() -> ExitCode {
     let r = match args.first().map(String::as_str) {
         Some("run") => cmd_run(&args[1..]),
         Some("eval" | "inspect") => cmd_eval(&args[1..]),
+        Some("script") => cmd_script(&args[1..]),
         Some("snapshot") => cmd_snapshot(&args[1..]),
         Some("exec") => cmd_exec(&args[1..]),
         Some("commands") => {
@@ -242,6 +246,23 @@ fn cmd_eval(args: &[String]) -> Result<(), String> {
     Ok(())
 }
 
+/// A design's history as a command script (`timeline.export_script`): printed, or written to
+/// `--out`; what the script leaves out goes to stderr.
+fn cmd_script(args: &[String]) -> Result<(), String> {
+    let path = positional(args).ok_or_else(|| USAGE.to_string())?;
+    let s = &mut load(path)?;
+    let out = flag(args, "--out");
+    let r = s.execute("timeline.export_script", &json!({"path": out})).map_err(|e| e.to_string())?;
+    for what in r["omitted"].as_array().into_iter().flatten().filter_map(Value::as_str) {
+        eprintln!("note: the script leaves out {what}");
+    }
+    match out {
+        Some(out) => eprintln!("{out}: {} steps", r["steps"]),
+        None => println!("{}", pretty(&r["script"])),
+    }
+    Ok(())
+}
+
 fn cmd_snapshot(args: &[String]) -> Result<(), String> {
     let path = args.first().ok_or_else(|| USAGE.to_string())?;
     let out = flag(args, "--out").ok_or("snapshot needs --out FILE.png")?;

apps/solidcraft-cli/tests/script_roundtrip.rs

@@ -0,0 +1,86 @@
+//! A design's command script (`timeline.export_script`, #886) replays into the same design:
+//! every corpus design that the script supports comes back with the same timeline, parameters,
+//! settings and bodies.
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{Value, json};
+use solidcraft_engine::Session;
+
+fn corpus() -> Vec<PathBuf> {
+    let dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/corpus");
+    let mut v: Vec<PathBuf> =
+        std::fs::read_dir(&dir).unwrap().flatten().map(|e| e.path()).filter(|p| p.extension().is_some_and(|x| x == "solidcraft")).collect();
+    v.sort();
+    assert!(v.len() >= 7, "corpus files in {}", dir.display());
+    v
+}
+
+/// Designs with components or joints, which scripts do not support yet.
+const ASSEMBLIES: [&str; 2] = ["components-arm", "joints-hinge"];
+
+fn bodies(s: &mut Session) -> Vec<(String, f64, f64, Value)> {
+    let m = s.execute("inspect.measure", &json!({})).unwrap();
+    let mut v: Vec<_> = m["bodies"]
+        .as_array()
+        .into_iter()
+        .flatten()
+        .map(|b| {
+            (
+                b["name"].as_str().unwrap_or_default().to_string(),
+                b["volume_mm3"].as_f64().unwrap(),
+                b["area_mm2"].as_f64().unwrap(),
+                b["faces"].clone(),
+            )
+        })
+        .collect();
+    v.sort_by(|a, b| a.0.cmp(&b.0));
+    v
+}
+
+fn errors(s: &Session) -> Vec<(u64, Option<String>)> {
+    s.model.results.iter().map(|r| (r.id, r.error.clone())).collect()
+}
+
+fn params(s: &Session) -> Vec<solidcraft_engine::doc::Param> {
+    let mut v = s.doc.params.clone();
+    v.sort_by(|a, b| a.name.cmp(&b.name));
+    v
+}
+
+#[test]
+fn corpus_designs_replay_from_their_scripts() {
+    let mut replayed = 0;
+    for p in corpus() {
+        let name = p.file_stem().unwrap_or_default().to_string_lossy().to_string();
+        let mut s = Session::default();
+        s.execute("doc.open", &json!({"path": p.to_string_lossy()})).unwrap();
+        let r = match s.execute("timeline.export_script", &json!({})) {
+            Ok(r) => r,
+            Err(e) => {
+                assert!(ASSEMBLIES.contains(&name.as_str()), "{name}: {e}");
+                assert!(e.to_string().contains("not supported yet"), "{name}: {e}");
+                continue;
+            }
+        };
+        assert!(!ASSEMBLIES.contains(&name.as_str()), "{name} has components: the script should refuse it");
+        // Through text, as a script file would carry it.
+        let script: Value = serde_json::from_str(&r["script"].to_string()).unwrap();
+        let mut t = Session::default();
+        t.run_script(&script).unwrap_or_else(|e| panic!("{name}: {e}"));
+        assert_eq!(t.doc.features, s.doc.features, "{name}: timeline");
+        assert_eq!(params(&t), params(&s), "{name}: parameters");
+        assert_eq!(t.doc.marker, s.doc.marker, "{name}: marker");
+        assert_eq!(t.doc.units, s.doc.units, "{name}: units");
+        assert_eq!(t.doc.sheet, s.doc.sheet, "{name}: sheet metal rules");
+        assert_eq!(t.doc.plastic, s.doc.plastic, "{name}: plastic rules");
+        assert_eq!(t.doc.materials, s.doc.materials, "{name}: materials");
+        assert_eq!(t.doc.user_materials, s.doc.user_materials, "{name}: user materials");
+        assert_eq!(t.doc.favorites, s.doc.favorites, "{name}: favourites");
+        assert_eq!(t.doc.param_comments, s.doc.param_comments, "{name}: comments");
+        assert_eq!(errors(&t), errors(&s), "{name}: feature results");
+        assert_eq!(bodies(&mut t), bodies(&mut s), "{name}: bodies");
+        replayed += 1;
+    }
+    assert!(replayed >= 7, "replayed {replayed} corpus designs");
+}