SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Part properties and the bill of materials. `component.metadata` and
//! `component.metadata.set` read and change a component definition's part number, description,
//! revision and free properties (shared by every occurrence, saved with the component; the keys
//! and their checks are `solidcraft_doc::metadata`'s `KEYS`, the rows a component takes);
//! `assembly.bom` counts the placed components of the design, or of one component, and lists
//! them as rows, optionally written to a CSV or JSON file. With `group_children`, a part with a
//! part number keeps the parts placed inside it (a bolt's washers and nut) in its own row.
//!
//! A component's bill of materials type (`bom_type`, a part property) decides how it counts: a
//! phantom has no row and what it holds counts in its parent; a reference counts nowhere, and
//! nothing inside it does; a purchased or inseparable component is one row, and of what an
//! inseparable one holds only its purchased parts reach the parts-only list.
use std::collections::{BTreeMap, HashSet};
use serde_json::{Value, json};
use solidcraft_doc::BomType;
use solidcraft_doc::metadata::{BOM_KEYS, BOM_TYPE, DESCRIPTION, MAX_KEYS, Owner, PART_NUMBER, REVISION, check_text, key_list};
use super::CommandSpec;
use crate::params::{bad, str_};
use crate::schema::bom::{
Bom, BomChild, BomParams, BomRow, ComponentMetadataParams, ComponentMetadataResult, ComponentMetadataSetParams, ComponentMetadataSetResult,
};
use crate::schema::{TypedContract, output_schema_for};
use crate::{EngineError, Result, Session};
const BOM_CONTRACT: TypedContract<BomParams> = TypedContract::new();
const METADATA_CONTRACT: TypedContract<ComponentMetadataParams> = TypedContract::new();
const METADATA_SET_CONTRACT: TypedContract<ComponentMetadataSetParams> = TypedContract::new();
pub static COMMANDS: &[CommandSpec] = &[
CommandSpec::new("component.metadata", "Part Properties", crate::checked!("component.metadata", read))
.icon("settings")
.noundo()
.doc_only()
.contract(&METADATA_CONTRACT)
.output(output_schema_for::<ComponentMetadataResult>)
.params(
"component: id or name (0 or \"root\": the design's own properties) → component, name, part_number, description, revision, \
bom_type (components only), metadata (as saved, other tools' keys too), properties: {name: text}",
),
CommandSpec::new("component.metadata.set", "Change Part Properties", crate::checked!("component.metadata.set", set))
.icon("settings")
.doc_only()
.contract(&METADATA_SET_CONTRACT)
.output(output_schema_for::<ComponentMetadataSetResult>)
.params(
"component: id or name (not the root: use document.metadata.set); part_number?, description?, revision?: text (empty or null \
removes); bom_type?: normal|phantom|reference|purchased|inseparable (empty or null: normal); values?: {key: value} \
(SolidCraft's keys, as document.metadata's properties lists them, bom_type, or a reverse-DNS key holding an object); \
properties?: {name: text, …} (free properties; empty or null removes). All or nothing, one undo step → component, \
metadata, properties, changed: [keys]",
),
CommandSpec::new("assembly.bom", "Bill of Materials", crate::checked!("assembly.bom", bom))
.at("SOLID", "INSPECT")
.icon("bom")
.noundo()
.contract(&BOM_CONTRACT)
.output(output_schema_for::<Bom>)
.params(
"component?: id or name (default the design); levels?: flat (default: every part at any depth, counted through its \
subassemblies) | top (the component's direct children, subassemblies as one row each); group_by?: [\"part_number\"] \
(default; components without a part number get a row per definition) | [\"definition\"]; group_children?: true (a component \
with a part number is one row, the parts placed inside it listed under it as children: [{item, part_number, description, \
revision, each, count, definition}], not as rows of their own); path?: write a .csv or .json file (children as items 1.1, \
1.2…); format?: csv|json (default from the path). Each component's bom_type counts: phantom has no row (what it holds \
counts here), reference counts nowhere, purchased and inseparable are one row (in flat, an inseparable one's purchased \
parts are listed too, under it with group_children and a part number) → rows: [{item, part_number, description, revision, \
bom_type, count, definition, components, properties, children?}] sorted by part number, total_occurrences (children included)",
),
];
/// Longest free property name, in bytes.
const MAX_PROPERTY_NAME_BYTES: usize = 128;
/// How deep, and over how many placements, the bill of materials walks.
const MAX_DEPTH: usize = 64;
const MAX_PLACEMENTS: usize = 100_000;
fn key(v: Option<&Value>) -> Option<String> {
match v {
Some(Value::Number(n)) => Some(n.to_string()),
Some(Value::String(s)) => Some(s.clone()),
_ => None,
}
}
fn component_id(s: &Session, p: &Value, cmd: &str) -> Result<u64> {
let k = key(p.get("component")).ok_or_else(|| bad(cmd, "`component` must be a component id or name"))?;
s.doc.find_component(&k).ok_or_else(|| bad(cmd, format!("no component `{k}`")))
}
fn read(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "component.metadata";
let id = component_id(s, p, cmd)?;
// The root is the design: its own properties, and no free ones.
let (name, m, properties) = if id == 0 {
(&s.doc.name, &s.doc.metadata, BTreeMap::new())
} else {
let c = s.doc.components.iter().find(|c| c.id == id).ok_or_else(|| bad(cmd, format!("no component `{id}`")))?;
(&c.name, &c.metadata, c.properties.clone())
};
let text = |k: &str| m.text(k).map(str::to_string);
let reply = ComponentMetadataResult {
component: id,
name: name.clone(),
part_number: text(PART_NUMBER),
description: text(DESCRIPTION),
revision: text(REVISION),
// A bill of materials type is a component's; the design has none.
bom_type: (id != 0).then(|| m.bom_type().as_str().to_string()),
metadata: m.0.clone(),
properties,
param_warnings: Vec::new(),
};
serde_json::to_value(reply).map_err(|e| bad(cmd, e.to_string()))
}
/// A free property as it may be saved (`None`: remove it), or why not.
fn property(name: &str, value: &Value, cmd: &str) -> Result<Option<String>> {
let shown: String = name.chars().take(64).collect();
if name.trim().is_empty() || name.len() > MAX_PROPERTY_NAME_BYTES || name.chars().any(char::is_control) {
return Err(bad(cmd, format!("property name `{shown}` must be 1…{MAX_PROPERTY_NAME_BYTES} bytes of text without control characters")));
}
let text = match value {
Value::Null => return Ok(None),
Value::String(t) if t.is_empty() => return Ok(None),
Value::String(t) => t.clone(),
Value::Number(n) => n.to_string(),
Value::Bool(b) => b.to_string(),
_ => return Err(bad(cmd, format!("property `{shown}` takes text"))),
};
// The same text rule as SolidCraft's keys.
check_text(&format!("property `{shown}`"), &text).map_err(|e| bad(cmd, e.to_string()))?;
Ok(Some(text))
}
fn set(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "component.metadata.set";
let id = component_id(s, p, cmd)?;
if id == 0 {
return Err(bad(cmd, "the root is the design: its properties are document.metadata.set's"));
}
let c = s.doc.components.iter().find(|c| c.id == id).ok_or_else(|| bad(cmd, format!("no component `{id}`")))?;
let (mut metadata, mut properties) = (c.metadata.clone(), c.properties.clone());
let mut entries: Vec<(String, Value)> = Vec::new();
match p.get("values") {
None => {}
Some(Value::Object(v)) if v.len() <= MAX_KEYS => entries.extend(v.iter().map(|(k, v)| (k.clone(), v.clone()))),
Some(Value::Object(_)) => return Err(bad(cmd, format!("`values` can hold at most {MAX_KEYS} keys"))),
Some(_) => return Err(bad(cmd, "`values` must be an object: {key: value, …}")),
}
for k in BOM_KEYS.iter().chain([&BOM_TYPE]) {
if let Some(v) = p.get(*k) {
entries.push((k.to_string(), v.clone()));
}
}
let props: Vec<(&String, &Value)> = match p.get("properties") {
None => Vec::new(),
Some(Value::Object(v)) if v.len() <= MAX_KEYS => v.iter().collect(),
Some(Value::Object(_)) => return Err(bad(cmd, format!("`properties` can hold at most {MAX_KEYS} names"))),
Some(_) => return Err(bad(cmd, "`properties` must be an object: {name: text, …}")),
};
if entries.is_empty() && props.is_empty() {
return Err(bad(cmd, format!("give {}, {BOM_TYPE}, values or properties ({})", BOM_KEYS.join(", "), key_list(Owner::Component))));
}
let mut changed: Vec<String> = Vec::new();
for (k, v) in entries {
if metadata.set(Owner::Component, &k, v).map_err(|e| bad(cmd, e.to_string()))? && !changed.contains(&k) {
changed.push(k);
}
}
for (name, value) in props {
let was = properties.get(name).cloned();
match property(name, value, cmd)? {
Some(text) => {
properties.insert(name.clone(), text);
}
None => {
properties.remove(name);
}
}
if properties.get(name) != was.as_ref() {
changed.push(format!("properties.{name}"));
}
}
if properties.len() > MAX_KEYS {
return Err(bad(cmd, format!("a component holds at most {MAX_KEYS} properties")));
}
// Only a real change touches the design (an undo step, unsaved changes).
if !changed.is_empty()
&& let Some(c) = s.doc_mut().components.iter_mut().find(|c| c.id == id)
{
c.metadata = metadata;
c.properties = properties;
}
let c = s.doc.components.iter().find(|c| c.id == id).ok_or_else(|| bad(cmd, format!("no component `{id}`")))?;
let reply = ComponentMetadataSetResult {
component: id,
metadata: c.metadata.0.clone(),
properties: c.properties.clone(),
changed,
param_warnings: Vec::new(),
};
serde_json::to_value(reply).map_err(|e| bad(cmd, e.to_string()))
}
#[derive(Clone, Copy, PartialEq)]
enum Levels {
Flat,
Top,
}
#[derive(Clone, Copy, PartialEq)]
enum Group {
PartNumber,
Definition,
}
/// One row being gathered.
struct Row {
part_number: String,
description: String,
revision: String,
bom_type: BomType,
count: u64,
components: Vec<u64>,
names: Vec<String>,
properties: BTreeMap<String, String>,
/// With `group_children`: what is placed inside one of this row's parts, and how often.
kit: BTreeMap<u64, u64>,
}
/// What the bill of materials lists and how.
#[derive(Clone, Copy)]
struct Options {
levels: Levels,
group: Group,
/// A part with a part number keeps its sub-parts in its row.
fold: bool,
}
fn options(p: &Value, cmd: &str) -> Result<Options> {
let levels = match p.get("levels") {
None | Some(Value::Null) => Levels::Flat,
Some(Value::String(l)) if l == "flat" => Levels::Flat,
Some(Value::String(l)) if l == "top" => Levels::Top,
Some(_) => return Err(bad(cmd, "`levels` is flat or top")),
};
let group = match p.get("group_by") {
None | Some(Value::Null) => Group::PartNumber,
Some(Value::String(g)) => group_key(g, cmd)?,
Some(Value::Array(a)) => match a.as_slice() {
[Value::String(g)] => group_key(g, cmd)?,
_ => return Err(bad(cmd, "`group_by` is [\"part_number\"] or [\"definition\"]")),
},
Some(_) => return Err(bad(cmd, "`group_by` is [\"part_number\"] or [\"definition\"]")),
};
let fold = match p.get("group_children") {
None | Some(Value::Null) => false,
Some(Value::Bool(b)) => *b,
Some(_) => return Err(bad(cmd, "`group_children` is true or false")),
};
Ok(Options { levels, group, fold })
}
/// The design's structure, looked up once per bill of materials.
struct Index {
/// What each component places (by its id; 0 is the root).
children: BTreeMap<u64, Vec<u64>>,
/// Components with bodies of their own.
owners: HashSet<u64>,
/// Components with a part number: with `group_children`, one row however much is inside.
numbered: HashSet<u64>,
/// Components whose bill of materials type isn't normal.
types: BTreeMap<u64, BomType>,
}
impl Index {
fn new(s: &Session) -> Index {
let mut children: BTreeMap<u64, Vec<u64>> = BTreeMap::new();
for o in &s.doc.occurrences {
children.entry(o.parent).or_default().push(o.component);
}
let numbered = s.doc.components.iter().filter(|c| c.metadata.part_number().is_some_and(|n| !n.is_empty())).map(|c| c.id).collect();
let types = s.doc.components.iter().map(|c| (c.id, c.metadata.bom_type())).filter(|(_, t)| *t != BomType::Normal).collect();
Index { children, owners: s.doc.body_owners(&s.model.state()), numbered, types }
}
fn bom_type(&self, component: u64) -> BomType {
self.types.get(&component).copied().unwrap_or_default()
}
}
/// What a walk below a component lists.
#[derive(Clone, Copy, PartialEq)]
enum Walk {
/// What the bill of materials lists.
Listed,
/// Inside an inseparable component, in parts only: just its purchased parts.
Purchased,
}
fn group_key(g: &str, cmd: &str) -> Result<Group> {
match g {
"part_number" => Ok(Group::PartNumber),
"definition" => Ok(Group::Definition),
o => Err(bad(cmd, format!("can't group by `{o}` (part_number or definition)"))),
}
}
/// How many times each component is listed below `root`, by its bill of materials type: in
/// `Top`, the direct children; in `Flat`, the parts at any depth (a part in a subassembly placed
/// twice counts twice), not below a purchased part, nor below a numbered part when `fold`, and of
/// what an inseparable part holds only its purchased parts. A phantom's contents count where the
/// phantom is placed; a reference counts nowhere, and nothing inside it does. `walk` chooses
/// whether the root's contents are listed normally or as an inseparable part's purchased children.
fn counts(ix: &Index, root: u64, levels: Levels, fold: bool, walk: Walk, cmd: &str) -> Result<BTreeMap<u64, u64>> {
let mut out: BTreeMap<u64, u64> = BTreeMap::new();
let mut placed = 0usize;
let mut stack: Vec<(u64, usize, Walk)> = vec![(root, 0, walk)];
while let Some((comp, depth, walk)) = stack.pop() {
for child in ix.children.get(&comp).into_iter().flatten() {
placed += 1;
if depth >= MAX_DEPTH || placed > MAX_PLACEMENTS {
return Err(bad(cmd, format!("the assembly is deeper than {MAX_DEPTH} levels or has more than {MAX_PLACEMENTS} placements")));
}
let inside = ix.children.contains_key(child);
match (ix.bom_type(*child), walk) {
(BomType::Reference, _) => {}
(BomType::Phantom, _) => stack.push((*child, depth + 1, walk)),
(BomType::Purchased, _) => *out.entry(*child).or_default() += 1,
(_, Walk::Purchased) => {
if inside {
stack.push((*child, depth + 1, Walk::Purchased));
}
}
(BomType::Inseparable, Walk::Listed) => {
*out.entry(*child).or_default() += 1;
if levels == Levels::Flat && inside && !(fold && ix.numbered.contains(child)) {
stack.push((*child, depth + 1, Walk::Purchased));
}
}
(BomType::Normal, Walk::Listed) => {
// Parts only: a subassembly is listed through its parts, unless it has bodies
// of its own (or, folding, a part number).
let folded = fold && ix.numbered.contains(child);
if levels == Levels::Top || !inside || folded || ix.owners.contains(child) {
*out.entry(*child).or_default() += 1;
}
if levels == Levels::Flat && inside && !folded {
stack.push((*child, depth + 1, Walk::Listed));
}
}
}
}
}
Ok(out)
}
/// How a kit reads when rows are compared: its parts by part number (else definition), bill of
/// materials type and count, so a kit holding a bought bolt isn't the kit holding a made one.
fn kit_key(s: &Session, ix: &Index, kit: &BTreeMap<u64, u64>) -> String {
let mut parts: Vec<String> = kit
.iter()
.map(|(id, n)| {
let pn = s.doc.components.iter().find(|c| c.id == *id).and_then(|c| c.metadata.part_number()).unwrap_or_default();
let bom_type = ix.bom_type(*id).as_str();
if pn.is_empty() { format!("#{id} {bom_type}×{n}") } else { format!("{pn} {bom_type}×{n}") }
})
.collect();
parts.sort();
parts.join("\n")
}
fn rows(s: &Session, ix: &Index, counts: &BTreeMap<u64, u64>, group: Group, kits: &BTreeMap<u64, BTreeMap<u64, u64>>) -> Vec<Row> {
let mut grouped: BTreeMap<(String, String, u64, BomType), Row> = BTreeMap::new();
for (id, n) in counts {
let Some(c) = s.doc.components.iter().find(|c| c.id == *id) else { continue };
let m = &c.metadata;
let part_number = m.part_number().unwrap_or_default().to_string();
let kit = kits.get(id).cloned().unwrap_or_default();
let bom_type = ix.bom_type(*id);
// Without a part number a definition is its own row; parts with different contents
// (a bolt with or without its nut) or different bill of materials types are different rows.
let k = match group {
Group::PartNumber if !part_number.is_empty() => (part_number.clone(), kit_key(s, ix, &kit), 0, bom_type),
_ => (String::new(), String::new(), *id, bom_type),
};
let row = grouped.entry(k).or_insert_with(|| Row {
part_number: part_number.clone(),
description: String::new(),
revision: String::new(),
bom_type,
count: 0,
components: Vec::new(),
names: Vec::new(),
properties: BTreeMap::new(),
kit,
});
row.count += n;
row.components.push(*id);
if !row.names.contains(&c.name) {
row.names.push(c.name.clone());
}
if row.description.is_empty() {
row.description = m.description().unwrap_or_default().to_string();
}
if row.revision.is_empty() {
row.revision = m.revision().unwrap_or_default().to_string();
}
for (k, v) in &c.properties {
row.properties.entry(k.clone()).or_insert_with(|| v.clone());
}
}
let mut out: Vec<Row> = grouped.into_values().collect();
// By part number; rows without one after them, by name.
out.sort_by(|a, b| {
(a.part_number.is_empty(), &a.part_number, &a.names, &a.components).cmp(&(b.part_number.is_empty(), &b.part_number, &b.names, &b.components))
});
out
}
/// A CSV field, always quoted.
fn quote(s: &str) -> String {
format!("\"{}\"", s.replace('"', "\"\""))
}
/// The bill of materials as CSV: fixed columns, every field quoted.
fn csv(rows: &[Value]) -> String {
let mut out = ["item", "part_number", "description", "revision", "count", "definition"].map(quote).join(",");
out.push('\n');
let lines = rows.iter().flat_map(|r| std::iter::once(r).chain(r["children"].as_array().into_iter().flatten()));
for r in lines {
let text = |k: &str| match &r[k] {
Value::String(t) => t.clone(),
Value::Null => String::new(),
v => v.to_string(),
};
let fields = ["item", "part_number", "description", "revision", "count", "definition"].map(|k| quote(&text(k)));
out.push_str(&fields.join(","));
out.push('\n');
}
out
}
fn bom(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "assembly.bom";
let root = if p.get("component").is_some_and(|v| !v.is_null()) { component_id(s, p, cmd)? } else { 0 };
let o = options(p, cmd)?;
let ix = Index::new(s);
let counts = counts(&ix, root, o.levels, o.fold, Walk::Listed, cmd)?;
// Folding: what one of each numbered part holds, as parts at any depth. Inseparable parts
// list only purchased descendants; purchased parts keep all their contents out of the list.
let mut kits: BTreeMap<u64, BTreeMap<u64, u64>> = BTreeMap::new();
if o.fold {
for id in counts.keys().filter(|id| ix.numbered.contains(id)) {
let walk = match ix.bom_type(*id) {
BomType::Normal => Walk::Listed,
BomType::Inseparable => Walk::Purchased,
_ => continue,
};
let kit = self::counts(&ix, *id, Levels::Flat, false, walk, cmd)?;
if !kit.is_empty() {
kits.insert(*id, kit);
}
}
}
let mut total: u64 = 0;
let rows: Vec<BomRow> = rows(s, &ix, &counts, o.group, &kits)
.into_iter()
.enumerate()
.map(|(i, r)| {
total += r.count;
let children = (!r.kit.is_empty()).then(|| {
self::rows(s, &ix, &r.kit, Group::PartNumber, &BTreeMap::new())
.into_iter()
.enumerate()
.map(|(j, c)| {
let count = c.count.saturating_mul(r.count);
total += count;
BomChild {
item: format!("{}.{}", i + 1, j + 1),
part_number: c.part_number,
description: c.description,
revision: c.revision,
bom_type: c.bom_type.as_str().to_string(),
each: c.count,
count,
definition: c.names.join("; "),
}
})
.collect()
});
BomRow {
item: i + 1,
part_number: r.part_number,
description: r.description,
revision: r.revision,
bom_type: r.bom_type.as_str().to_string(),
count: r.count,
definition: r.names.join("; "),
components: r.components,
properties: r.properties,
children,
}
})
.collect();
let mut out = Bom {
component: root,
levels: if o.levels == Levels::Top { "top" } else { "flat" }.to_string(),
group_by: vec![if o.group == Group::Definition { "definition" } else { "part_number" }.to_string()],
group_children: o.fold,
path: None,
format: None,
rows,
total_occurrences: total,
param_warnings: Vec::new(),
};
if let Some(path) = str_(p, "path") {
let format = match str_(p, "format").map(str::to_ascii_lowercase) {
Some(f) => f,
None if path.to_ascii_lowercase().ends_with(".json") => "json".into(),
None if path.to_ascii_lowercase().ends_with(".csv") => "csv".into(),
None => return Err(bad(cmd, "`path` must end in .csv or .json, or give `format`")),
};
let rows = out.rows.iter().map(|r| serde_json::to_value(r).map_err(|e| bad(cmd, e.to_string()))).collect::<Result<Vec<Value>>>()?;
let text = match format.as_str() {
"csv" => csv(&rows),
"json" => serde_json::to_string_pretty(&json!({"rows": rows, "total_occurrences": total})).map_err(|e| bad(cmd, e.to_string()))?,
other => return Err(bad(cmd, format!("unknown format `{other}` (csv or json)"))),
};
solidcraft_io::vfs::write(path, text.as_bytes()).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
out.path = Some(path.to_string());
out.format = Some(format);
}
serde_json::to_value(out).map_err(|e| bad(cmd, e.to_string()))
}
#[cfg(test)]
#[path = "bom_tests.rs"]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests;