ModelCraft foundation: workspace, quality gates, FE model, command engine, geometry boundary

A pure-Rust CAE modeling workspace following the SolidCraft conventions:
- modelcraft-model: nodes and elements by label with hostile-input validation
- modelcraft-geometry: SolidCraft's kernel (pinned git dependency) behind our own API;
  tessellation into a face-tagged boundary surface for volume meshing
- modelcraft-engine: CommandSpec registry, Session::execute with rollback and panic guard,
  scripts and a journal
- modelcraft-cli: list commands, run scripts
- xtask: layers (only geometry may use solidcraft-*), assets, licences, tests, wasm, ci
- AGENTS.md, architecture, ADR 0001 (libraries and licences), roadmap, CI

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

xtask/src/main.rs

@@ -0,0 +1,159 @@
+//! Workspace tooling: `cargo xtask <command>`.
+//!
+//! Pure Rust (std + serde_json). External tools (`cargo`) are invoked through
+//! `std::process::Command`. Adapted from SolidCraft's xtask (MIT OR Apache-2.0), see
+//! ATTRIBUTION.md.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+
+mod assets;
+mod layers;
+mod licences;
+mod test;
+
+use std::path::{Path, PathBuf};
+use std::process::{Command, ExitCode};
+
+const USAGE: &str = "\
+usage: cargo xtask <command>
+
+commands:
+  layers          enforce the crate dependency layering (docs/architecture.md)
+  assets          check that every non-code asset file is attributed in ATTRIBUTION.md
+  licences [--check]
+                  write THIRD-PARTY-LICENSES.txt (the licences of every shipped crate);
+                  --check fails when it is out of date
+  test [CARGO ARGS] [-- TEST ARGS]
+                  build the tests with the ci profile, then run every test binary at once
+                  (and the doc tests alongside)
+  wasm            cargo check every library crate for wasm32-unknown-unknown
+  ci              fmt --check, assets, licences --check, layers, clippy -D warnings, then the tests
+                  with the wasm check alongside (stops at the first failing step)
+";
+
+fn main() -> ExitCode {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let rest: Vec<&str> = args.iter().skip(1).map(String::as_str).collect();
+    let result = match args.first().map(String::as_str) {
+        Some("layers") => cmd_layers(),
+        Some("assets") => assets::run(&root()),
+        Some("licences") => licences::run(&root(), rest.contains(&"--check")),
+        Some("test") => {
+            let (cargo_args, test_args) = rest.iter().position(|a| *a == "--").map_or((&rest[..], &[][..]), |i| (&rest[..i], &rest[i + 1..]));
+            test::run(cargo_args, test_args, vec![test::doc_tests(cargo_args, test_args)])
+        }
+        Some("ci") => cmd_ci(),
+        Some("wasm") => cmd_wasm(),
+        Some("-h" | "--help" | "help") | None => {
+            print!("{USAGE}");
+            Ok(())
+        }
+        Some(other) => Err(format!("unknown command `{other}`\n\n{USAGE}")),
+    };
+    match result {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(e) => {
+            eprintln!("error: {e}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+/// Workspace root (parent of the xtask crate).
+pub fn root() -> PathBuf {
+    let here = Path::new(env!("CARGO_MANIFEST_DIR"));
+    here.parent().unwrap_or(here).to_path_buf()
+}
+
+pub fn cargo() -> Command {
+    let mut c = Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".into()));
+    c.current_dir(root());
+    c
+}
+
+fn run(mut cmd: Command, what: &str) -> Result<(), String> {
+    eprintln!("$ {what}");
+    let status = cmd.status().map_err(|e| format!("{what}: failed to spawn: {e}"))?;
+    if status.success() { Ok(()) } else { Err(format!("{what}: exited with {status}")) }
+}
+
+pub fn metadata() -> Result<serde_json::Value, String> {
+    let out = cargo().args(["metadata", "--format-version", "1", "--no-deps"]).output().map_err(|e| format!("cargo metadata: {e}"))?;
+    if !out.status.success() {
+        return Err(format!("cargo metadata failed:\n{}", String::from_utf8_lossy(&out.stderr)));
+    }
+    serde_json::from_slice(&out.stdout).map_err(|e| format!("cargo metadata: bad JSON: {e}"))
+}
+
+fn cmd_layers() -> Result<(), String> {
+    let crates = layers::from_metadata(&metadata()?)?;
+    println!("Dependency layering (docs/architecture.md)\n");
+    println!("{:<28} {:<14} workspace deps", "crate", "layer");
+    for c in &crates {
+        let ws: Vec<String> = c
+            .deps
+            .iter()
+            .filter(|d| d.workspace)
+            .map(|d| {
+                let k = match d.kind {
+                    layers::DepKind::Normal => "",
+                    layers::DepKind::Dev => " (dev)",
+                    layers::DepKind::Build => " (build)",
+                };
+                format!("{}{k}", layers::short_name(&d.name))
+            })
+            .collect();
+        println!("{:<28} {:<14} {}", c.name, layers::describe(layers::classify(&c.name)), ws.join(", "));
+    }
+    let violations = layers::check(&crates);
+    println!();
+    if violations.is_empty() {
+        println!("OK: {} crates, no layering violations.", crates.len());
+        Ok(())
+    } else {
+        println!("{} violation(s):", violations.len());
+        for v in &violations {
+            println!("  - {v}");
+        }
+        Err(format!("{} layering violation(s)", violations.len()))
+    }
+}
+
+/// Never break wasm: every layered crate (everything below the apps) must build for the browser.
+fn cmd_wasm() -> Result<(), String> {
+    let (c, n) = wasm_check()?;
+    run(c, &format!("cargo check --target wasm32-unknown-unknown ({n} crates)"))?;
+    println!("wasm: {n} crates build for wasm32-unknown-unknown");
+    Ok(())
+}
+
+/// The wasm check and how many crates it covers. It uses the ci profile so the host build
+/// scripts and proc macros built for clippy and the tests are reused.
+fn wasm_check() -> Result<(Command, usize), String> {
+    let crates = layers::from_metadata(&metadata()?)?;
+    let set: Vec<String> =
+        crates.iter().filter(|c| matches!(layers::classify(&c.name), Some(layers::Class::Layer(_)))).map(|c| c.name.clone()).collect();
+    let mut c = cargo();
+    c.args(["check", "--target", "wasm32-unknown-unknown", "--profile", "ci"]);
+    for p in &set {
+        c.args(["-p", p]);
+    }
+    Ok((c, set.len()))
+}
+
+/// The quick gates first, so they fail fast; the wasm check (and doc tests) run while the test
+/// binaries do, which leaves cargo's build lock free.
+fn cmd_ci() -> Result<(), String> {
+    let mut c = cargo();
+    c.args(["fmt", "--all", "--", "--check"]);
+    run(c, "cargo fmt --check")?;
+    assets::run(&root())?;
+    licences::run(&root(), true)?;
+    cmd_layers()?;
+    let mut c = cargo();
+    c.args(["clippy", "--workspace", "--all-targets", "--profile", "ci", "--", "-D", "warnings"]);
+    run(c, "cargo clippy -D warnings")?;
+    let (wasm, n) = wasm_check()?;
+    test::run(&[], &[], vec![(format!("wasm32-unknown-unknown check ({n} crates)"), wasm), test::doc_tests(&[], &[])])?;
+    eprintln!("ci: all gates passed");
+    Ok(())
+}