SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Make the generated command reference easier to browse (#5237) (#5721)
Victor Santos Oliveiraecf57d131a26
diff --git a/xtask/src/book.rs b/xtask/src/book.rsindex 03311f7bce..5a301fbb43 100644--- a/xtask/src/book.rs+++ b/xtask/src/book.rs@@ -82,43 +82,210 @@ fn json_files(dir: &Path) -> Result<Vec<std::path::PathBuf>, String> {/// The command reference page: one section per toolbar tab and panel, in registry order.fn reference(cmds: &[Value]) -> String {- let s = |c: &Value, k: &str| c[k].as_str().unwrap_or_default().to_string();let mut md = format!(- "# Command reference\n\nGenerated by `cargo xtask book` from `solidcraft-cli commands` ({} commands). Every command runs the same \- way from the toolbar, a script, `solidcraft-cli exec <id> '<json>'`, the control channel and MCP. Parameters marked `?` are \- optional; `expr` is a number or an expression with units.\n",+ "# Command reference\n\nBrowse commands by their names and default keyboard shortcuts. \+ Entries are organized by command group and panel; ungrouped commands follow by area.\n\n\+ For step-by-step instructions, start with the [window tour](../guide/ui-tour.md), \+ [sketching guide](../guide/sketching.md) or [solid features guide](../guide/features.md). \+ Each entry links to a related guide when one is available.\n\n\+ Expand **Automation details** for the command ID and parameters used by scripts, the CLI and MCP. \+ In that notation, `?` marks an optional parameter and `expr` means a number or an expression with units.\n\n\+ This catalog is generated from `solidcraft-cli commands` by `cargo xtask book` ({} commands).\n",cmds.len());let mut sections: Vec<(String, Vec<&Value>)> = Vec::new();for tab in TABS {- for c in cmds.iter().filter(|c| s(c, "tab") == *tab) {- let title = format!("{tab} › {}", s(c, "panel"));+ for c in cmds.iter().filter(|c| command_text(c, "tab") == *tab) {+ let panel = command_text(c, "panel").trim();+ let title = if panel.is_empty() { tab.to_string() } else { format!("{tab} › {panel}") };add(&mut sections, title, c);}}- for c in cmds.iter().filter(|c| !TABS.contains(&s(c, "tab").as_str())) {- let id = s(c, "id");- let prefix = id.split('.').next().unwrap_or_default().to_string();- add(&mut sections, format!("Other: {prefix}.*"), c);+ for c in cmds.iter().filter(|c| !TABS.contains(&command_text(c, "tab"))) {+ let prefix = command_text(c, "id").split('.').next().filter(|s| !s.is_empty());+ let title = prefix.map_or_else(|| "Other commands".into(), |area| format!("Other commands: {area}"));+ add(&mut sections, title, c);}for (title, list) in sections {- md.push_str(&format!("\n## {title}\n\n"));+ md.push_str(&format!("\n## {}\n\n", prose(&title)));for c in list {- let key = c["shortcut"].as_str().map(|k| format!(" ({k})")).unwrap_or_default();- md.push_str(&format!("- `{}` **{}**{key}", s(c, "id"), s(c, "label")));- let p = s(c, "params");+ let label = command_text(c, "label").trim();+ md.push_str(&format!("### {}\n\n", prose(if label.is_empty() { "Unnamed command" } else { label })));+ let tab = command_text(c, "tab").trim();+ let panel = command_text(c, "panel").trim();+ if !tab.is_empty() {+ let location = if panel.is_empty() { tab.to_string() } else { format!("{tab} › {panel}") };+ md.push_str(&format!("**Command group:** {}\n\n", prose(&location)));+ }+ let shortcut = command_text(c, "shortcut").trim();+ if !shortcut.is_empty() {+ md.push_str(&format!("**Default keyboard shortcut:** {}\n\n", prose(shortcut)));+ }+ if let Some((label, path)) = guide(c) {+ md.push_str(&format!("Read the [{label}]({path}).\n\n"));+ }+ md.push_str("<details>\n<summary>Automation details</summary>\n\n");+ md.push_str(&format!("<p><strong>Command ID:</strong> <code>{}</code></p>\n\n", html(command_text(c, "id"))));+ let p = command_text(c, "params");if !p.is_empty() {- md.push_str(&format!("<br>``{}``", p.replace('\n', " ")));+ // HTML code blocks preserve the complete source text, including newlines and+ // arbitrary runs of backticks, without letting it close the details element.+ md.push_str(&format!(+ "<p><strong>Parameters:</strong></p>\n<pre><code style=\"white-space: pre-wrap; overflow-wrap: anywhere;\">{}</code></pre>\n",+ html(p)+ ));+ } else {+ md.push_str("<p>No parameter description is provided by the command registry.</p>\n");}- md.push('\n');+ md.push_str("\n</details>\n\n");}}md}+fn command_text<'a>(command: &'a Value, key: &str) -> &'a str {+ command.get(key).and_then(Value::as_str).unwrap_or_default()+}++/// Text in generated Markdown is literal text, never contributor-provided Markdown or HTML.+fn prose(text: &str) -> String {+ let mut escaped = String::new();+ for ch in text.chars() {+ match ch {+ '\r' | '\n' => escaped.push(' '),+ '\\' | '`' | '*' | '_' | '[' | ']' | '{' | '}' | '(' | ')' | '#' | '+' | '-' | '!' | '|' | '~' => {+ escaped.push('\\');+ escaped.push(ch);+ }+ _ => escaped.push(ch),+ }+ }+ html(&escaped)+}++/// Escape once, including ampersands that already look like HTML entities.+fn html(text: &str) -> String {+ text.replace('&', "&").replace('<', "<").replace('>', ">").replace('"', """).replace('\'', "'")+}++/// Only link to guide pages that exist; parameter descriptions are deliberately not parsed.+fn guide(command: &Value) -> Option<(&'static str, &'static str)> {+ let area = command_text(command, "id").split('.').next().unwrap_or_default();+ match area {+ "parameters" | "expr" | "config" => Some(("parameters and expressions guide", "../guide/parameters.md")),+ "component" | "occurrence" | "joint" | "motion" => Some(("components and joints guide", "../guide/assemblies.md")),+ "file" | "doc" => Some(("import and export guide", "../guide/files.md")),+ "view" | "browser" | "select" => Some(("window tour", "../guide/ui-tour.md")),+ _ => match command_text(command, "tab") {+ "SKETCH" => Some(("sketching and constraints guide", "../guide/sketching.md")),+ "SOLID" | "SURFACE" => Some(("solid features guide", "../guide/features.md")),+ "SHEET METAL" => Some(("sheet metal guide", "../guide/sheet-metal.md")),+ "PLASTIC" => Some(("plastic parts guide", "../guide/plastic.md")),+ _ => None,+ },+ }+}+fn add<'a>(sections: &mut Vec<(String, Vec<&'a Value>)>, title: String, c: &'a Value) {match sections.iter_mut().find(|(t, _)| *t == title) {Some((_, v)) => v.push(c),None => sections.push((title, vec![c])),}}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;++ fn decoded_code(text: &str) -> String {+ text.replace("<", "<").replace(">", ">").replace(""", "\"").replace("'", "'").replace("&", "&")+ }++ #[test]+ fn every_command_has_one_entry_with_its_complete_automation_details() {+ let cmds = [+ json!({"id":"file.export","label":"Export","params":"path: text","tab":"","panel":""}),+ json!({"id":"solid.extrude","label":"Extrude","params":"distance: expr","tab":"SOLID","panel":"CREATE","shortcut":"E"}),+ json!({"id":"sketch.line","label":"Line","params":"points: [x,y]","tab":"SKETCH","panel":"CREATE"}),+ json!({"id":"future.action","label":"Future action","params":"option?: text","tab":"NEW WORKSPACE","panel":"TOOLS"}),+ ];+ let md = reference(&cmds);+ let ids: Vec<&str> = md.split("<strong>Command ID:</strong> <code>").skip(1).map(|tail| tail.split("</code>").next().unwrap()).collect();+ assert_eq!(ids, ["solid.extrude", "sketch.line", "file.export", "future.action"]);+ assert_eq!(md.matches("<details>").count(), cmds.len());+ assert_eq!(md.matches("### ").count(), cmds.len());+ assert!(md.contains("### Extrude\n\n**Command group:** SOLID › CREATE\n\n**Default keyboard shortcut:** E"));+ assert!(md.contains("## Other commands: future"));+ assert!(md.contains("**Command group:** NEW WORKSPACE › TOOLS"));+ for cmd in &cmds {+ assert!(md.contains(&format!(+ "<pre><code style=\"white-space: pre-wrap; overflow-wrap: anywhere;\">{}</code></pre>",+ command_text(cmd, "params")+ )));+ }+ }++ #[test]+ fn source_markup_cannot_add_links_headings_or_close_automation_details() {+ let params = "path: id|name\n```html\n</code></pre></details><script>alert('x')</script>\n``````\n&er; < \n";+ let md = reference(&[json!({+ "id":"odd.<tag>&id",+ "label":"[Follow](javascript:alert(1)) <img src=x>\n### Injected",+ "tab":"UNKNOWN <script>",+ "panel":"[Panel](https://invalid.example)",+ "shortcut":"Ctrl+<b>&`",+ "params":params+ })]);+ assert_eq!(md.matches("<details>").count(), 1);+ assert_eq!(md.matches("</details>").count(), 1);+ assert_eq!(md.lines().filter(|line| line.starts_with("### ")).count(), 1);+ assert!(!md.contains("<script>"));+ assert!(!md.contains("<img"));+ assert!(!md.contains("[Follow]("));+ assert!(!md.contains("[Panel]("));+ let stored =+ md.split("<pre><code style=\"white-space: pre-wrap; overflow-wrap: anywhere;\">").nth(1).unwrap().split("</code></pre>").next().unwrap();+ assert_eq!(decoded_code(stored), params, "every parameter byte, including newlines and backticks, stays readable");+ assert!(md.contains("<code>odd.<tag>&id</code>"));+ }++ #[test]+ fn missing_optional_metadata_does_not_invent_a_toolbar_shortcut_or_guide() {+ for cmd in [+ json!({"id":"future.unlisted","label":"Unlisted"}),+ json!({"id":"future.unlisted","label":"Unlisted","tab":false,"panel":42,"shortcut":false,"params":null}),+ json!({"id":"future.unlisted","label":"Unlisted","tab":" ","panel":" ","shortcut":" \n"}),+ ] {+ let md = reference(&[cmd]);+ assert!(md.contains("### Unlisted"));+ assert!(md.contains("<code>future.unlisted</code>"));+ assert!(!md.contains("**Command group:**"));+ assert!(!md.contains("**Default keyboard shortcut:**"));+ assert!(!md.contains("Read the ["));+ assert!(md.contains("No parameter description is provided"));+ }+ }++ #[test]+ fn related_guides_are_existing_pages_and_cover_commands_without_a_toolbar() {+ let samples = [+ json!({"id":"parameters.change"}),+ json!({"id":"joint.drive"}),+ json!({"id":"file.export"}),+ json!({"id":"view.home"}),+ json!({"id":"sketch.line","tab":"SKETCH"}),+ json!({"id":"solid.extrude","tab":"SOLID"}),+ json!({"id":"surface.patch","tab":"SURFACE"}),+ json!({"id":"sheet.flange","tab":"SHEET METAL"}),+ json!({"id":"plastic.boss","tab":"PLASTIC"}),+ ];+ let base = Path::new(env!("CARGO_MANIFEST_DIR")).join("../docs/book/src/reference");+ for cmd in samples {+ let (label, path) = guide(&cmd).expect("a related user guide");+ assert!(base.join(path).is_file(), "missing guide {path}");+ assert!(reference(&[cmd]).contains(&format!("Read the [{label}]({path}).")));+ }+ assert!(guide(&json!({"id":"future.unlisted","tab":"NEW WORKSPACE"})).is_none());+ }+}