teamcraft/

stepbom.rs

//! Product structure of STEP assemblies (ISO 10303-21 files of AP203, AP214
//! and AP242) as a BOM table for the import (see
//! [`crate::services::imports`]).
//!
//! The reader looks at the product structure only, never at the geometry:
//!
//! * `PRODUCT('id', 'name', 'description', …)` – a part or an assembly; the
//!   id is its part number,
//! * `PRODUCT_DEFINITION_FORMATION(_WITH_SPECIFIED_SOURCE)` and
//!   `PRODUCT_DEFINITION` – the version and the definition the structure
//!   links,
//! * `NEXT_ASSEMBLY_USAGE_OCCURRENCE(…, #parent, #child, …)` – one placed
//!   occurrence of a component; the quantity is the number of occurrences
//!   below the same parent.
//!
//! The assembly is the product that no other product uses; with several of
//! them, each becomes a component of the new assembly. A sub-assembly lists
//! its components at its first occurrence only (the import reads the BOM of a
//! component once). Complex instances (`#1 = (A() B());`) and the quantities
//! of `QUANTIFIED_ASSEMBLY_COMPONENT_USAGE` are not read.
//!
//! An own minimal Part 21 reader: `ruststep` was rejected as a direct
//! dependency (see `docs/OPEN_WORK.md`), and only five entity types are needed.
#![deny(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::panic,
    clippy::unreachable
)]

use std::collections::{HashMap, HashSet};

use crate::bomtable::{field_label, BomRow, BomTable, Column, MAX_ROWS};

/// Deeper structures are cut (protects the recursion).
const MAX_DEPTH: usize = 64;

/// Deeper nested parameter lists are skipped without recursion, so a hostile
/// file cannot overflow the stack (real files nest a few levels at most).
const MAX_NESTING: usize = 32;

/// Sub-assembly occurrences expanded at most by [`external_instance_counts`]
/// (a deep structure of many-times-placed sub-assemblies grows fast).
const MAX_OCCURRENCES: usize = 1_000_000;

/// Whether the file name is a STEP file (`.step`, `.stp`, `.p21`).
pub fn is_step(filename: &str) -> bool {
    filename
        .rsplit_once('.')
        .is_some_and(|(_, ext)| matches!(ext.to_ascii_lowercase().as_str(), "step" | "stp" | "p21"))
}

/// A parameter of an entity instance.
#[derive(Debug, PartialEq)]
enum Param {
    Str(String),
    Ref(u64),
    List(Vec<Param>),
    /// `$`, `*`, numbers, enumerations and typed values – not needed here.
    Other,
}

struct Product {
    id: String,
    name: String,
    description: String,
}

impl Product {
    fn shown(&self) -> &str {
        if self.id.trim().is_empty() {
            self.name.trim()
        } else {
            self.id.trim()
        }
    }
}

/// Reads the product structure of a STEP file.
pub fn read(bytes: &[u8]) -> Result<BomTable, String> {
    let text = String::from_utf8_lossy(bytes);
    if !text
        .trim_start_matches('\u{feff}')
        .trim_start()
        .starts_with("ISO-10303-21")
    {
        return Err("Not a STEP file: it does not start with ISO-10303-21.".into());
    }
    let mut products: HashMap<u64, Product> = HashMap::new();
    // formation → product, definition → formation
    let mut formations: HashMap<u64, u64> = HashMap::new();
    let mut definitions: HashMap<u64, u64> = HashMap::new();
    // (parent definition, child definition) in file order
    let mut usages: Vec<(u64, u64)> = Vec::new();
    for_each_instance(&text, |id, keyword, body| {
        let is = |name: &str| keyword.eq_ignore_ascii_case(name);
        if is("PRODUCT") {
            let p = params(body);
            products.insert(
                id,
                Product {
                    id: string(&p, 0),
                    name: string(&p, 1),
                    description: string(&p, 2),
                },
            );
        } else if is("PRODUCT_DEFINITION_FORMATION")
            || is("PRODUCT_DEFINITION_FORMATION_WITH_SPECIFIED_SOURCE")
        {
            if let Some(product) = reference(&params(body), 2) {
                formations.insert(id, product);
            }
        } else if is("PRODUCT_DEFINITION") || is("PRODUCT_DEFINITION_WITH_ASSOCIATED_DOCUMENTS") {
            if let Some(formation) = reference(&params(body), 2) {
                definitions.insert(id, formation);
            }
        } else if is("NEXT_ASSEMBLY_USAGE_OCCURRENCE") {
            let p = params(body);
            if let (Some(parent), Some(child)) = (reference(&p, 3), reference(&p, 4)) {
                usages.push((parent, child));
            }
        }
    });

    let product_of = |definition: u64| {
        definitions
            .get(&definition)
            .and_then(|f| formations.get(f))
            .filter(|p| products.contains_key(p))
            .copied()
    };
    // parent product → (child product, occurrences), both in file order
    let mut children: HashMap<u64, Vec<(u64, usize)>> = HashMap::new();
    let mut parents: Vec<u64> = Vec::new();
    let mut used = HashSet::new();
    let mut unresolved = 0;
    for (parent, child) in usages {
        let (Some(p), Some(c)) = (product_of(parent), product_of(child)) else {
            unresolved += 1;
            continue;
        };
        let list = children.entry(p).or_insert_with(|| {
            parents.push(p);
            Vec::new()
        });
        match list.iter_mut().find(|(x, _)| *x == c) {
            Some(entry) => entry.1 += 1,
            None => list.push((c, 1)),
        }
        used.insert(c);
    }
    if children.is_empty() {
        return Err(
            "No assembly structure found: the STEP file has no NEXT_ASSEMBLY_USAGE_OCCURRENCE – \
             it holds a single part or was exported without its product structure."
                .into(),
        );
    }
    let roots: Vec<u64> = parents
        .iter()
        .filter(|p| !used.contains(*p))
        .copied()
        .collect();
    if roots.is_empty() {
        return Err("The product structure of the STEP file is circular.".into());
    }

    let mut walk = Walk {
        products: &products,
        children: &children,
        expanded: HashSet::new(),
        path: Vec::new(),
        rows: Vec::new(),
        warnings: Vec::new(),
    };
    if unresolved > 0 {
        walk.warnings.push(format!(
            "{unresolved} assembly occurrences point to unknown product definitions and are \
             ignored."
        ));
    }
    let root = if let [root] = roots[..] {
        let mut row = walk.row(root, 0, 1.0);
        row.line = 1;
        walk.expand(root, 0)?;
        Some(row)
    } else {
        walk.warnings.push(format!(
            "The STEP file holds {} top-level assemblies: each becomes a component of the new \
             assembly.",
            roots.len()
        ));
        for &root in &roots {
            let row = walk.row(root, 1, 1.0);
            walk.rows.push(row);
            walk.expand(root, 1)?;
        }
        None
    };
    let columns = [
        ("PRODUCT id", "number"),
        ("PRODUCT name", "name"),
        ("PRODUCT description", "description"),
        ("NEXT_ASSEMBLY_USAGE_OCCURRENCE", "quantity"),
    ]
    .into_iter()
    .map(|(header, field)| Column {
        header: header.into(),
        field,
        label: field_label(field),
    })
    .collect();
    Ok(BomTable {
        root,
        rows: walk.rows,
        columns,
        extra_columns: Vec::new(),
        warnings: walk.warnings,
    })
}

/// How often a STEP assembly with **external references** places each
/// referenced file (#247): the parts live in their own files
/// (`'bolt.stp'`), the assembly file holds the structure. Which file a
/// product definition stands for is read from
///
/// * `DOCUMENT_FILE('bolt.stp', …)` – the file (its id, or its name; a path
///   is reduced to the file name), or the id of an
///   `APPLIED_EXTERNAL_IDENTIFICATION_ASSIGNMENT('bolt.stp', …, (#doc))`;
/// * linked to the definition by `APPLIED_DOCUMENT_REFERENCE(#doc, …,
///   (#definition))`, `PRODUCT_DEFINITION_WITH_ASSOCIATED_DOCUMENTS(…,
///   (#doc))` or `DOCUMENT_PRODUCT_EQUIVALENCE` / `…_ASSOCIATION(…, #doc,
///   #product|formation|definition)`.
///
/// Every `NEXT_ASSEMBLY_USAGE_OCCURRENCE` below the top assemblies counts
/// once for the file of its child; a child without a file of its own is a
/// sub-assembly inside this file, whose occurrences count with its own
/// multiplicity (depth bounded). File names in their original spelling;
/// `None` when no occurrence leads to an external file (a monolithic STEP
/// file, a single part, no STEP file).
pub fn external_instance_counts(bytes: &[u8]) -> Option<HashMap<String, u32>> {
    let text = String::from_utf8_lossy(bytes);
    if !text
        .trim_start_matches('\u{feff}')
        .trim_start()
        .starts_with("ISO-10303-21")
    {
        return None;
    }
    // document → file name
    let mut doc_names: HashMap<u64, String> = HashMap::new();
    let mut doc_ids: HashMap<u64, String> = HashMap::new();
    // (document, referenced definition / formation / product)
    let mut doc_links: Vec<(u64, u64)> = Vec::new();
    let mut formations: HashMap<u64, u64> = HashMap::new();
    let mut definitions: HashMap<u64, u64> = HashMap::new();
    let mut usages: Vec<(u64, u64)> = Vec::new();
    let file_name = |s: &str| -> Option<String> {
        let last = s.rsplit(['\\', '/']).next().unwrap_or(s).trim();
        (last.contains('.') && !last.starts_with('.')).then(|| last.to_string())
    };
    for_each_instance(&text, |id, keyword, body| {
        let is = |name: &str| keyword.eq_ignore_ascii_case(name);
        if is("DOCUMENT_FILE") {
            let p = params(body);
            if let Some(n) = file_name(&string(&p, 0)).or_else(|| file_name(&string(&p, 1))) {
                doc_ids.insert(id, n);
            }
        } else if is("APPLIED_EXTERNAL_IDENTIFICATION_ASSIGNMENT") {
            let p = params(body);
            if let (Some(n), Some(Param::List(items))) = (file_name(&string(&p, 0)), p.get(3)) {
                for item in items {
                    if let Param::Ref(doc) = item {
                        doc_names.entry(*doc).or_insert_with(|| n.clone());
                    }
                }
            }
        } else if is("APPLIED_DOCUMENT_REFERENCE") {
            let p = params(body);
            if let (Some(doc), Some(Param::List(items))) = (reference(&p, 0), p.get(2)) {
                for item in items {
                    if let Param::Ref(target) = item {
                        doc_links.push((doc, *target));
                    }
                }
            }
        } else if is("DOCUMENT_PRODUCT_EQUIVALENCE") || is("DOCUMENT_PRODUCT_ASSOCIATION") {
            let p = params(body);
            if let (Some(doc), Some(target)) = (reference(&p, 2), reference(&p, 3)) {
                doc_links.push((doc, target));
            }
        } else if is("PRODUCT_DEFINITION_FORMATION")
            || is("PRODUCT_DEFINITION_FORMATION_WITH_SPECIFIED_SOURCE")
        {
            if let Some(product) = reference(&params(body), 2) {
                formations.insert(id, product);
            }
        } else if is("PRODUCT_DEFINITION") || is("PRODUCT_DEFINITION_WITH_ASSOCIATED_DOCUMENTS") {
            let p = params(body);
            if let Some(formation) = reference(&p, 2) {
                definitions.insert(id, formation);
            }
            if let Some(Param::List(docs)) = p.get(4) {
                for d in docs {
                    if let Param::Ref(doc) = d {
                        doc_links.push((*doc, id));
                    }
                }
            }
        } else if is("NEXT_ASSEMBLY_USAGE_OCCURRENCE") {
            let p = params(body);
            if let (Some(parent), Some(child)) = (reference(&p, 3), reference(&p, 4)) {
                usages.push((parent, child));
            }
        }
    });
    // the DOCUMENT_FILE's own id wins over an assignment
    for (doc, name) in doc_ids {
        doc_names.insert(doc, name);
    }
    if usages.is_empty() || doc_names.is_empty() {
        return None;
    }
    // file name per definition: linked directly, or through its formation
    // or product
    let mut by_target: HashMap<u64, &str> = HashMap::new();
    for (doc, target) in &doc_links {
        if let Some(name) = doc_names.get(doc) {
            by_target.entry(*target).or_insert(name.as_str());
        }
    }
    let file_of = |definition: u64| -> Option<&str> {
        let formation = definitions.get(&definition).copied();
        let product = formation.and_then(|f| formations.get(&f).copied());
        [Some(definition), formation, product]
            .into_iter()
            .flatten()
            .find_map(|t| by_target.get(&t).copied())
    };
    let mut children: HashMap<u64, Vec<u64>> = HashMap::new();
    let mut used = HashSet::new();
    let mut parents = Vec::new();
    for (parent, child) in usages {
        children
            .entry(parent)
            .or_insert_with(|| {
                parents.push(parent);
                Vec::new()
            })
            .push(child);
        used.insert(child);
    }
    let mut counts: HashMap<String, u32> = HashMap::new();
    // (definition, depth) – one entry per occurrence, so a sub-assembly
    // placed twice inside this file counts its parts twice
    let mut stack: Vec<(u64, usize)> = parents
        .iter()
        .filter(|p| !used.contains(*p))
        .map(|&p| (p, 0))
        .collect();
    let mut steps = 0usize;
    while let Some((parent, depth)) = stack.pop() {
        steps += 1;
        if depth >= MAX_DEPTH || steps > MAX_OCCURRENCES {
            break;
        }
        for &child in children.get(&parent).into_iter().flatten() {
            match file_of(child) {
                Some(name) => {
                    let n = counts.entry(name.to_string()).or_default();
                    *n = n.saturating_add(1);
                }
                None => stack.push((child, depth + 1)),
            }
        }
    }
    (!counts.is_empty()).then_some(counts)
}

/// Depth-first walk through the structure, producing the rows in BOM order.
struct Walk<'a> {
    products: &'a HashMap<u64, Product>,
    children: &'a HashMap<u64, Vec<(u64, usize)>>,
    expanded: HashSet<u64>,
    path: Vec<u64>,
    rows: Vec<BomRow>,
    warnings: Vec<String>,
}

impl Walk<'_> {
    /// Line 1 is the assembly, the components follow in BOM order.
    fn row(&self, product: u64, level: usize, quantity: f64) -> BomRow {
        let p = &self.products[&product];
        let number = p.id.trim().to_string();
        let name = match p.name.trim() {
            "" => number.clone(),
            name => name.to_string(),
        };
        let description = match p.description.trim() {
            d if d == name || d == number => String::new(),
            d => d.to_string(),
        };
        BomRow {
            line: self.rows.len() + 2,
            level,
            find_number: None,
            number,
            name,
            description,
            quantity,
            unit: String::new(),
            material: String::new(),
            mass_kg: None,
            structure: String::new(),
            extra: Vec::new(),
        }
    }

    /// Adds the components of `product` (on `level` + 1) – at its first
    /// occurrence only.
    fn expand(&mut self, product: u64, level: usize) -> Result<(), String> {
        if !self.expanded.insert(product) {
            return Ok(());
        }
        let Some(children) = self.children.get(&product) else {
            return Ok(());
        };
        if level >= MAX_DEPTH {
            self.warnings.push(format!(
                "The structure is deeper than {MAX_DEPTH} levels – the components of {} are \
                 skipped.",
                self.products[&product].shown()
            ));
            return Ok(());
        }
        self.path.push(product);
        for &(child, count) in children {
            if self.path.contains(&child) {
                self.warnings.push(format!(
                    "{} would contain itself – the occurrence is skipped.",
                    self.products[&child].shown()
                ));
                continue;
            }
            if self.rows.len() >= MAX_ROWS {
                return Err(format!("The assembly has more than {MAX_ROWS} BOM rows."));
            }
            let row = self.row(child, level + 1, count as f64);
            self.rows.push(row);
            self.expand(child, level + 1)?;
        }
        self.path.pop();
        Ok(())
    }
}

/// The text parameter at `index`, decoded; empty if there is none.
fn string(params: &[Param], index: usize) -> String {
    match params.get(index) {
        Some(Param::Str(s)) => s.clone(),
        _ => String::new(),
    }
}

fn reference(params: &[Param], index: usize) -> Option<u64> {
    match params.get(index) {
        Some(Param::Ref(r)) => Some(*r),
        _ => None,
    }
}

/// Calls `f(id, keyword, parameters)` for every simple entity instance
/// `#id = KEYWORD(parameters);` of the file (header entries have no `#id`).
fn for_each_instance(text: &str, mut f: impl FnMut(u64, &str, &str)) {
    let b = text.as_bytes();
    let (mut start, mut i) = (0, 0);
    let mut in_string = false;
    while let Some(&c) = b.get(i) {
        if in_string {
            if c == b'\'' {
                if b.get(i + 1) == Some(&b'\'') {
                    i += 1;
                } else {
                    in_string = false;
                }
            }
        } else if c == b'\'' {
            in_string = true;
        } else if c == b'/' && b.get(i + 1) == Some(&b'*') {
            i = text
                .get(i + 2..)
                .and_then(|t| t.find("*/"))
                .map_or(b.len(), |e| i + 2 + e + 2);
            continue;
        } else if c == b';' {
            if let Some((id, keyword, body)) = text.get(start..i).and_then(instance) {
                f(id, keyword, body);
            }
            start = i + 1;
        }
        i += 1;
    }
}

/// Splits `#12 = KEYWORD ( … )` into id, keyword and the text between the
/// outer parentheses.
fn instance(mut record: &str) -> Option<(u64, &str, &str)> {
    // Comments before the instance.
    while let Some(comment) = record.trim_start().strip_prefix("/*") {
        record = comment.split_once("*/")?.1;
    }
    let rest = record.trim_start().strip_prefix('#')?;
    let digits = rest.find(|c: char| !c.is_ascii_digit())?;
    let id = rest.get(..digits)?.parse().ok()?;
    let rest = rest
        .get(digits..)?
        .trim_start()
        .strip_prefix('=')?
        .trim_start();
    let end = rest
        .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))
        .unwrap_or(rest.len());
    let (keyword, rest) = rest.split_at(end);
    if keyword.is_empty() {
        return None; // complex instance
    }
    let body = rest.trim().strip_prefix('(')?.strip_suffix(')')?;
    Some((id, keyword, body))
}

/// Parses a parameter list (without its outer parentheses).
fn params(body: &str) -> Vec<Param> {
    let mut parser = Parser {
        text: body,
        bytes: body.as_bytes(),
        i: 0,
        depth: 0,
    };
    parser.list()
}

struct Parser<'a> {
    text: &'a str,
    bytes: &'a [u8],
    i: usize,
    /// Nesting of the list being read.
    depth: usize,
}

impl Parser<'_> {
    fn peek(&self) -> Option<u8> {
        self.bytes.get(self.i).copied()
    }

    /// Skips white space and comments.
    fn space(&mut self) {
        loop {
            match self.peek() {
                Some(c) if c.is_ascii_whitespace() => self.i += 1,
                Some(b'/') if self.bytes.get(self.i + 1) == Some(&b'*') => {
                    self.i = self
                        .text
                        .get(self.i + 2..)
                        .unwrap_or_default()
                        .find("*/")
                        .map_or(self.bytes.len(), |e| self.i + 2 + e + 2);
                }
                _ => return,
            }
        }
    }

    /// Parameters up to the closing parenthesis (or the end).
    fn list(&mut self) -> Vec<Param> {
        let mut out = Vec::new();
        loop {
            self.space();
            match self.peek() {
                None => return out,
                Some(b')') => {
                    self.i += 1;
                    return out;
                }
                Some(b',') => self.i += 1,
                Some(b'\'') => out.push(Param::Str(self.string())),
                Some(b'#') => {
                    self.i += 1;
                    let start = self.i;
                    while self.peek().is_some_and(|c| c.is_ascii_digit()) {
                        self.i += 1;
                    }
                    out.push(
                        match self.text.get(start..self.i).unwrap_or_default().parse() {
                            Ok(r) => Param::Ref(r),
                            Err(_) => Param::Other,
                        },
                    );
                }
                Some(b'(') if self.depth >= MAX_NESTING => {
                    // `other` skips the balanced list iteratively.
                    self.other();
                    out.push(Param::Other);
                }
                Some(b'(') => {
                    self.i += 1;
                    self.depth += 1;
                    let list = self.list();
                    self.depth -= 1;
                    out.push(Param::List(list));
                }
                Some(_) => {
                    self.other();
                    out.push(Param::Other);
                }
            }
        }
    }

    /// Skips one other parameter, e.g. `$`, `.T.`, `2.5` or `LENGTH_MEASURE(2.5)`.
    fn other(&mut self) {
        let mut depth = 0usize;
        while let Some(c) = self.peek() {
            match c {
                b',' | b')' if depth == 0 => return,
                b'(' => depth += 1,
                b')' => depth -= 1,
                b'\'' => {
                    self.string();
                    continue;
                }
                _ => {}
            }
            self.i += 1;
        }
    }

    /// A quoted string starting at the current quote, decoded.
    fn string(&mut self) -> String {
        self.i += 1;
        let mut raw = String::new();
        let mut from = self.i;
        while let Some(c) = self.peek() {
            if c == b'\'' {
                raw.push_str(self.text.get(from..self.i).unwrap_or_default());
                if self.bytes.get(self.i + 1) == Some(&b'\'') {
                    raw.push('\'');
                    self.i += 2;
                    from = self.i;
                    continue;
                }
                self.i += 1;
                return decode(&raw);
            }
            self.i += 1;
        }
        raw.push_str(self.text.get(from..).unwrap_or_default());
        decode(&raw)
    }
}

/// Decodes the escapes of Part 21 strings: `\\`, `\X2\…\X0\` (UTF-16),
/// `\X4\…\X0\` (UTF-32), `\X\hh` and `\S\c` (ISO 8859-1), `\N\`, `\T\`;
/// code page switches (`\PA\`) are dropped.
fn decode(raw: &str) -> String {
    let mut out = String::with_capacity(raw.len());
    let mut rest = raw;
    // every cut below follows checked ASCII bytes, so it is on a character
    // boundary; `get` keeps it from panicking all the same
    fn from(s: &str, n: usize) -> &str {
        s.get(n..).unwrap_or_default()
    }
    while let Some(p) = rest.find('\\') {
        out.push_str(rest.get(..p).unwrap_or_default());
        rest = from(rest, p);
        if let Some(r) = rest.strip_prefix("\\\\") {
            out.push('\\');
            rest = r;
        } else if let Some((width, r)) = rest
            .strip_prefix("\\X2\\")
            .map(|r| (4, r))
            .or_else(|| rest.strip_prefix("\\X4\\").map(|r| (8, r)))
        {
            let (hex, after) = r.split_once("\\X0\\").unwrap_or((r, ""));
            let units = hex.as_bytes().chunks(width).filter_map(|chunk| {
                std::str::from_utf8(chunk)
                    .ok()
                    .and_then(|h| u32::from_str_radix(h, 16).ok())
            });
            if width == 4 {
                let units: Vec<u16> = units.map(|u| u as u16).collect();
                out.extend(char::decode_utf16(units).map(|c| c.unwrap_or('\u{fffd}')));
            } else {
                out.extend(units.map(|u| char::from_u32(u).unwrap_or('\u{fffd}')));
            }
            rest = after;
        } else if let Some(v) = rest
            .strip_prefix("\\X\\")
            .and_then(|r| r.get(..2))
            .and_then(|h| u8::from_str_radix(h, 16).ok())
        {
            out.push(char::from(v));
            rest = from(rest, 5);
        } else if let Some(c) = rest
            .strip_prefix("\\S\\")
            .and_then(|r| r.bytes().next())
            .filter(u8::is_ascii)
        {
            out.push(char::from(c + 128));
            rest = from(rest, 4);
        } else if let Some(r) = rest.strip_prefix("\\N\\") {
            out.push('\n');
            rest = r;
        } else if let Some(r) = rest.strip_prefix("\\T\\") {
            out.push('\t');
            rest = r;
        } else if let [b'\\', b'P', _, b'\\', ..] = rest.as_bytes() {
            rest = from(rest, 4);
        } else {
            out.push('\\');
            rest = from(rest, 1);
        }
    }
    out.push_str(rest);
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A STEP file with the given entity instances in its DATA section.
    fn step(data: &str) -> Vec<u8> {
        format!(
            "ISO-10303-21;\nHEADER;\nFILE_DESCRIPTION((''),'2;1');\n\
             FILE_NAME('pump.step','2026-11-04T12:00:00',(''),(''),'','','');\n\
             FILE_SCHEMA(('AUTOMOTIVE_DESIGN'));\nENDSEC;\nDATA;\n{data}\nENDSEC;\n\
             END-ISO-10303-21;\n"
        )
        .into_bytes()
    }

    /// PRODUCT, formation and definition of one product: definition `#<n>3`.
    fn product(n: u32, id: &str, name: &str) -> String {
        format!(
            "#{n}1=PRODUCT('{id}','{name}','',(#9));\n\
             #{n}2=PRODUCT_DEFINITION_FORMATION_WITH_SPECIFIED_SOURCE('','',#{n}1,.NOT_KNOWN.);\n\
             #{n}3=PRODUCT_DEFINITION('design','',#{n}2,#8);\n"
        )
    }

    fn usage(id: u32, parent: u32, child: u32) -> String {
        format!("#{id}=NEXT_ASSEMBLY_USAGE_OCCURRENCE('{id}','','',#{parent}3,#{child}3,$);\n")
    }

    fn flat(t: &BomTable) -> Vec<(usize, &str, f64)> {
        t.rows
            .iter()
            .map(|r| (r.level, r.number.as_str(), r.quantity))
            .collect()
    }

    #[test]
    fn assembly_with_sub_assembly_and_repeated_parts() {
        let data = [
            product(1, "PUMP-100", "Pump"),
            product(2, "HSG-1", "Housing"),
            product(3, "ROT-1", "Rotor assembly"),
            product(4, "M6x20", "Screw"),
            product(5, "SHAFT-1", "Shaft"),
            // the first occurrence of the rotor comes before the screws
            usage(101, 1, 2),
            usage(102, 1, 3),
            usage(103, 1, 4),
            usage(104, 1, 4),
            usage(105, 3, 5),
            usage(106, 3, 4),
            usage(107, 1, 4),
        ]
        .concat();
        let t = read(&step(&data)).unwrap();
        let root = t.root.as_ref().unwrap();
        assert_eq!((root.level, root.number.as_str()), (0, "PUMP-100"));
        assert_eq!(root.name, "Pump");
        assert_eq!(
            flat(&t),
            vec![
                (1, "HSG-1", 1.0),
                (1, "ROT-1", 1.0),
                (2, "SHAFT-1", 1.0),
                (2, "M6x20", 1.0),
                (1, "M6x20", 3.0),
            ]
        );
        assert_eq!(t.rows[1].name, "Rotor assembly");
        assert_eq!(
            t.rows.iter().map(|r| r.line).collect::<Vec<_>>(),
            vec![2, 3, 4, 5, 6]
        );
        assert!(t.warnings.is_empty());
        assert_eq!(t.columns.len(), 4);
    }

    #[test]
    fn shared_sub_assembly_is_listed_once() {
        let data = [
            product(1, "TOP", "Top"),
            product(2, "LEFT", "Left"),
            product(3, "RIGHT", "Right"),
            product(4, "WHEEL", "Wheel"),
            product(5, "HUB", "Hub"),
            usage(101, 1, 2),
            usage(102, 1, 3),
            usage(103, 2, 4),
            usage(104, 3, 4),
            usage(105, 4, 5),
        ]
        .concat();
        let t = read(&step(&data)).unwrap();
        assert_eq!(
            flat(&t),
            vec![
                (1, "LEFT", 1.0),
                (2, "WHEEL", 1.0),
                (3, "HUB", 1.0),
                (1, "RIGHT", 1.0),
                (2, "WHEEL", 1.0),
            ]
        );
    }

    #[test]
    fn several_top_level_assemblies() {
        let data = [
            product(1, "A", "A"),
            product(2, "B", "B"),
            product(3, "P", "P"),
            usage(101, 1, 3),
            usage(102, 2, 3),
        ]
        .concat();
        let t = read(&step(&data)).unwrap();
        assert!(t.root.is_none());
        assert_eq!(
            flat(&t),
            vec![(1, "A", 1.0), (2, "P", 1.0), (1, "B", 1.0), (2, "P", 1.0)]
        );
        assert!(t.warnings[0].contains("2 top-level assemblies"));
    }

    #[test]
    fn single_parts_and_other_files_are_refused() {
        let part = read(&step(&product(1, "BRACKET", "Bracket"))).unwrap_err();
        assert!(part.contains("No assembly structure"), "{part}");
        let fixture = std::fs::read("tests/fixtures/cube.step").unwrap();
        assert!(read(&fixture).is_err());
        assert!(read(b"solid cube\nendsolid\n")
            .unwrap_err()
            .contains("Not a STEP"));
        let circular = [
            product(1, "A", "A"),
            product(2, "B", "B"),
            usage(101, 1, 2),
            usage(102, 2, 1),
        ]
        .concat();
        assert!(read(&step(&circular)).unwrap_err().contains("circular"));
    }

    #[test]
    fn strings_comments_and_escapes() {
        let data = "/* exported; with comments */\n\
            #11=PRODUCT('M\\X2\\00DC\\X0\\LLER-1','Gr\\S\\|n''s part; \\X\\E4','',(#9));\n\
            #12=PRODUCT_DEFINITION_FORMATION('','',#11);\n\
            #13=PRODUCT_DEFINITION('design','' /* note */,#12,#8);\n\
            #21=PRODUCT('X','Box','A box',(#9));\n\
            #22=PRODUCT_DEFINITION_FORMATION('','',#21);\n\
            #23=PRODUCT_DEFINITION('design','',#22,#8);\n\
            #30=(GEOMETRIC_REPRESENTATION_CONTEXT(3)REPRESENTATION_CONTEXT('',''));\n\
            #31=NEXT_ASSEMBLY_USAGE_OCCURRENCE('1','','',#23,#13,$);\n";
        let t = read(&step(data)).unwrap();
        let root = t.root.unwrap();
        assert_eq!(
            (root.number.as_str(), root.description.as_str()),
            ("X", "A box")
        );
        assert_eq!(t.rows[0].number, "MÜLLER-1");
        assert_eq!(t.rows[0].name, "Grün's part; ä");
    }

    #[test]
    fn decoding() {
        assert_eq!(decode("a\\\\b"), "a\\b");
        assert_eq!(decode("\\X2\\03B103B2\\X0\\!"), "αβ!");
        assert_eq!(decode("\\X4\\0001F600\\X0\\"), "😀");
        assert_eq!(decode("\\PA\\x\\N\\y"), "x\ny");
        assert_eq!(decode("50\\%"), "50\\%");
        assert!(is_step("Pump.STEP") && is_step("a.stp") && !is_step("a.stl"));
        assert_eq!(
            params("'a',#5,(#6,#7),.T.,LENGTH_MEASURE(2.5),$,'x(y'"),
            vec![
                Param::Str("a".into()),
                Param::Ref(5),
                Param::List(vec![Param::Ref(6), Param::Ref(7)]),
                Param::Other,
                Param::Other,
                Param::Other,
                Param::Str("x(y".into()),
            ]
        );
    }

    #[test]
    fn unresolved_occurrences_are_reported_and_ignored() {
        let data = [
            product(1, "TOP", "Top"),
            product(2, "P", "Part"),
            usage(101, 1, 2),
            usage(102, 1, 7), // no definition #73
            usage(103, 8, 2), // no definition #83
        ]
        .concat();
        let t = read(&step(&data)).unwrap();
        assert_eq!(flat(&t), vec![(1, "P", 1.0)]);
        assert_eq!(t.warnings.len(), 1);
        assert!(
            t.warnings[0].starts_with("2 assembly occurrences"),
            "{:?}",
            t.warnings
        );
    }

    #[test]
    fn byte_order_mark_lower_case_keywords_and_plain_formations() {
        // A UTF-8 BOM and blank lines before the magic, lower-case keywords,
        // PRODUCT_DEFINITION_FORMATION without source and definitions with
        // associated documents.
        let data = "#11=product('ASM','Assembly','',(#9));\n\
            #12=PRODUCT_DEFINITION_FORMATION('','',#11);\n\
            #13=PRODUCT_DEFINITION_WITH_ASSOCIATED_DOCUMENTS('d','',#12,#8,());\n\
            #21=PRODUCT('PRT','Part','',(#9));\n\
            #22=product_definition_formation_with_specified_source('','',#21,.MADE.);\n\
            #23=product_definition('design','',#22,#8);\n\
            #31=next_assembly_usage_occurrence('1','','',#13,#23,$);\n";
        let mut bytes = "\u{feff}\n\n".as_bytes().to_vec();
        bytes.extend(step(data));
        let t = read(&bytes).unwrap();
        assert_eq!(t.root.as_ref().unwrap().number, "ASM");
        assert_eq!(flat(&t), vec![(1, "PRT", 1.0)]);
    }

    #[test]
    fn names_and_descriptions() {
        let data = "#11=PRODUCT('ASM','','ASM',(#9));\n\
            #12=PRODUCT_DEFINITION_FORMATION('','',#11);\n\
            #13=PRODUCT_DEFINITION('design','',#12,#8);\n\
            #21=PRODUCT(' P-1 ',' Plate ',' Plate ',(#9));\n\
            #22=PRODUCT_DEFINITION_FORMATION('','',#21);\n\
            #23=PRODUCT_DEFINITION('design','',#22,#8);\n\
            #31=NEXT_ASSEMBLY_USAGE_OCCURRENCE('1','','',#13,#23,$);\n";
        let t = read(&step(data)).unwrap();
        let root = t.root.unwrap();
        // Without a name the id is the name; a description that only
        // repeats the name or the number is dropped; values are trimmed.
        assert_eq!((root.name.as_str(), root.description.as_str()), ("ASM", ""));
        let p = &t.rows[0];
        assert_eq!(
            (p.number.as_str(), p.name.as_str(), p.description.as_str()),
            ("P-1", "Plate", "")
        );
        assert_eq!(
            (p.find_number, p.unit.as_str(), p.mass_kg),
            (None, "", None)
        );
    }

    #[test]
    fn a_component_that_contains_itself_is_skipped() {
        // TOP → A → B → A: the inner A would contain itself.
        let data = [
            product(1, "TOP", "Top"),
            product(2, "A", "A"),
            product(3, "B", "B"),
            usage(101, 1, 2),
            usage(102, 2, 3),
            usage(103, 3, 2),
        ]
        .concat();
        let t = read(&step(&data)).unwrap();
        assert_eq!(flat(&t), vec![(1, "A", 1.0), (2, "B", 1.0)]);
        assert!(
            t.warnings
                .iter()
                .any(|w| w.contains("A would contain itself")),
            "{:?}",
            t.warnings
        );
    }

    #[test]
    fn very_deep_structures_are_cut() {
        // A chain of MAX_DEPTH + 5 nested assemblies.
        let n = (MAX_DEPTH + 5) as u32;
        let mut data = String::new();
        for i in 1..=n + 1 {
            data.push_str(&product(i, &format!("L{i}"), "Level"));
        }
        for i in 1..=n {
            data.push_str(&usage(100_000 + i, i, i + 1));
        }
        let t = read(&step(&data)).unwrap();
        assert_eq!(t.rows.len(), MAX_DEPTH);
        assert_eq!(t.rows.last().unwrap().level, MAX_DEPTH);
        assert!(t.warnings.iter().any(|w| w.contains("deeper than")));
    }

    #[test]
    fn more_decoding() {
        assert_eq!(decode("Gr\\S\\|n"), "Grün", "\\S\\ adds 128");
        assert_eq!(decode("\\X\\C4rger"), "Ärger");
        assert_eq!(decode("tab\\T\\end"), "tab\tend");
        assert_eq!(decode("\\X2\\00E4"), "ä", "missing \\X0\\ terminator");
        assert_eq!(decode("plain"), "plain");
        assert_eq!(decode("trailing\\"), "trailing\\");
        assert!(is_step("asm.P21") && !is_step("step") && !is_step("a.step.zip"));
    }

    #[test]
    fn deeply_nested_parameters_do_not_overflow_the_stack() {
        let n = 200_000;
        let body = format!("'a',{}{},#7", "(".repeat(n), ")".repeat(n));
        let p = params(&body);
        assert_eq!(p.len(), 3);
        assert_eq!(p[0], Param::Str("a".into()));
        assert_eq!(p[2], Param::Ref(7));
        // The outer levels are kept, the rest is skipped as one parameter.
        let mut level = &p[1];
        let mut depth = 0;
        while let Param::List(inner) = level {
            depth += 1;
            level = &inner[0];
        }
        assert_eq!((depth, level), (MAX_NESTING, &Param::Other));

        let file = format!(
            "{}#1=PRODUCT({}{});\n",
            product(1, "A", "A"),
            "(".repeat(n),
            ")".repeat(n)
        );
        assert!(read(&step(&file)).is_err());
    }

    /// Found by cargo mutants: a comment between parameters is skipped; a
    /// stray `/` (damaged file) costs one parameter, not the rest of the list.
    #[test]
    fn comments_and_stray_slashes_between_parameters() {
        assert_eq!(
            params("#1, /* the part */ #2,'x'"),
            [Param::Ref(1), Param::Ref(2), Param::Str("x".into())]
        );
        assert_eq!(params("/x,#5"), [Param::Other, Param::Ref(5)]);
        // a quoted `)` or `,` inside a skipped typed value ends nothing
        assert_eq!(
            params("NAME('x)y'),LABEL('a,b'),#7"),
            [Param::Other, Param::Other, Param::Ref(7)]
        );
    }

    /// Found by cargo mutants: the nesting depth goes down again after a
    /// list, so many sibling lists are all read (nesting beyond
    /// `MAX_NESTING`: `deeply_nested_parameters_do_not_overflow_the_stack`).
    #[test]
    fn sibling_lists_do_not_count_as_nesting() {
        let siblings: Vec<String> = (1..=MAX_NESTING * 3).map(|i| format!("(#{i})")).collect();
        let parsed = params(&siblings.join(","));
        assert_eq!(parsed.len(), MAX_NESTING * 3);
        assert!(parsed
            .iter()
            .all(|p| matches!(p, Param::List(l) if l.len() == 1)));
    }

    /// Found by cargo mutants: comments, unset parameters (`*`) and quoted
    /// semicolons when splitting into instances.
    #[test]
    fn instances_with_unset_parameters_comments_and_quotes() {
        let text = "#1=PRODUCT('a;b','',(#2),*);\n/* a comment; with #9=X(); */\
                    #2=PRODUCT_CONTEXT('it''s',*,'mechanical');#3=X(1.5/2.);";
        let mut seen = Vec::new();
        for_each_instance(text, |id, keyword, _| seen.push((id, keyword.to_string())));
        assert_eq!(
            seen,
            [
                (1, "PRODUCT".to_string()),
                (2, "PRODUCT_CONTEXT".to_string()),
                (3, "X".to_string())
            ]
        );
    }

    /// The document of an external file and its link to a definition.
    fn external(doc: u32, name: &str, link: &str) -> String {
        format!("#{doc}=DOCUMENT_FILE('{name}','',#7,'','','');\n{link}\n")
    }

    #[test]
    fn external_references_count_their_occurrences() {
        // assembly #13 places bolt #23 four times and nut #33 twice; the
        // bolt's file is linked to its definition, the nut's to its product
        let mut data =
            product(1, "PUMP", "Pump") + &product(2, "B", "Bolt") + &product(3, "N", "Nut");
        data += &external(
            900,
            "C:\\parts\\bolt.stp",
            "#901=APPLIED_DOCUMENT_REFERENCE(#900,'',(#23));",
        );
        data += &external(
            910,
            "nut.stp",
            "#911=DOCUMENT_PRODUCT_EQUIVALENCE('','',#910,#31);",
        );
        for (i, child) in [2, 2, 2, 2, 3, 3].into_iter().enumerate() {
            data += &usage(100 + i as u32, 1, child);
        }
        let counts = external_instance_counts(&step(&data)).unwrap();
        assert_eq!(counts.get("bolt.stp"), Some(&4));
        assert_eq!(counts.get("nut.stp"), Some(&2));
        assert_eq!(counts.len(), 2);
    }

    #[test]
    fn inline_sub_assemblies_multiply_and_associated_documents_link() {
        // pump #13 → frame #23 (inline, no file) twice; frame → screw #33
        // three times; the screw's file through its definition's documents
        let mut data = product(1, "PUMP", "Pump") + &product(2, "F", "Frame");
        data += "#31=PRODUCT('S','Screw','',(#9));\n\
                 #32=PRODUCT_DEFINITION_FORMATION('','',#31);\n\
                 #33=PRODUCT_DEFINITION_WITH_ASSOCIATED_DOCUMENTS('design','',#32,#8,(#920));\n";
        data += "#920=DOCUMENT_FILE('','',#7,'','','');\n\
                 #921=APPLIED_EXTERNAL_IDENTIFICATION_ASSIGNMENT('screw.step',$,#6,(#920));\n";
        data += &usage(100, 1, 2);
        data += &usage(101, 1, 2);
        for i in 0..3 {
            data += &usage(110 + i, 2, 3);
        }
        let counts = external_instance_counts(&step(&data)).unwrap();
        assert_eq!(counts, HashMap::from([("screw.step".to_string(), 6)]));
    }

    #[test]
    fn monolithic_files_and_other_bytes_have_no_counts() {
        let data = product(1, "PUMP", "Pump") + &product(2, "B", "Bolt") + &usage(100, 1, 2);
        assert_eq!(external_instance_counts(&step(&data)), None);
        assert_eq!(external_instance_counts(b"\x00bolt.stp\x00"), None);
        // a document without any occurrence
        let doc = product(2, "B", "Bolt")
            + &external(
                900,
                "bolt.stp",
                "#901=APPLIED_DOCUMENT_REFERENCE(#900,'',(#23));",
            );
        assert_eq!(external_instance_counts(&step(&doc)), None);
    }
}