ifc-lite-core 9.3.0

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Hand-maintained schema helpers built on top of the auto-generated
//! `IfcType` enum.
//!
//! These helpers used to live appended to `generated/schema.rs` despite that
//! file's "DO NOT EDIT" header. Moving them here keeps them safe from a
//! re-run of `@ifc-lite/codegen` and lets us derive answers from the EXPRESS
//! inheritance graph instead of maintaining a leaf-level allow-list that has
//! to be amended every time a new IFC4X3 subtype shows up (see PR #585 for
//! `IfcSolarDevice`, which inherits from `IfcEnergyConversionDevice` and was
//! therefore already covered conceptually by the old whitelist's parent
//! entry, but missed in practice because the whitelist was only checked by
//! string match).
//!
//! Co-authored with Geronimo <gerald.stampfel+geronimo@gmail.com> (PR #585).
//!
//! `has_geometry_by_name`, `is_representationless_spatial_container_by_name`
//! and `is_simple_geometry_type` are all on the hot path during scene
//! construction, where the same ~50–100 distinct type names are queried
//! millions of times per file. An immutable, schema-derived table memoises
//! all modern and legacy names without taking a read-lock for each entity.
//! Unknown names use the same predicates without entering a growing cache.

use std::sync::OnceLock;

use rustc_hash::FxHashMap;

use crate::generated::IfcType;
use crate::legacy_entities::get_legacy_entity_info;

/// Normalise to uppercase ASCII without allocating when the input is already
/// uppercase (the common case — STEP type tokens are emitted uppercase).
fn normalise_uppercase(type_name: &str) -> std::borrow::Cow<'_, str> {
    if type_name.bytes().any(|b| b.is_ascii_lowercase()) {
        std::borrow::Cow::Owned(type_name.to_ascii_uppercase())
    } else {
        std::borrow::Cow::Borrowed(type_name)
    }
}

#[derive(Clone, Copy)]
struct TypeClassification {
    has_geometry: bool,
    representationless_spatial: bool,
    simple_geometry: bool,
}

/// Build only from the finite schema catalog: file-supplied unknown names
/// cannot retain memory here. Compute via the canonical predicates, including
/// legacy overrides for names that also occur in the modern schema.
fn classifications() -> &'static FxHashMap<&'static str, TypeClassification> {
    static TABLE: OnceLock<FxHashMap<&'static str, TypeClassification>> = OnceLock::new();
    TABLE.get_or_init(|| {
        crate::generated::IFC_TYPES.iter().map(IfcType::as_str)
            .chain(crate::legacy_entities::LEGACY_ENTITY_NAMES.iter().copied())
            .map(|name| (name, TypeClassification {
                has_geometry: compute_has_geometry(name),
                representationless_spatial: compute_is_representationless_spatial_container(name),
                simple_geometry: compute_is_simple(name),
            }))
            .collect()
    })
}

/// Check if a type name (UPPERCASE STEP string) represents an `IfcProduct`
/// subtype that can bear geometry (has `ObjectPlacement` + `Representation`).
///
/// Implementation:
/// 1. Modern names go through `IfcType::from_str` and are accepted iff they
///    inherit from `IfcProduct`, with a small block-list for abstract spatial
///    containers (`IfcBuildingStorey`, `IfcFacility`, `IfcFacilityPart`,
///    `IfcSpatialElement`, `IfcSpatialStructureElement`) that don't carry
///    geometry directly. `IfcSpace`, `IfcSite`, `IfcSpatialZone` and
///    `IfcBuilding` (and any concrete subtype of those) are intentionally
///    kept — they have boundary representations the renderer consumes. See
///    [`is_non_geometric_spatial`] for how that exempt set is maintained.
/// 2. Legacy IFC2x3 / removed-in-IFC4x3 names that aren't in the generated
///    enum (e.g. `IFCSLABELEMENTEDCASE`, `IFCBUILDINGELEMENT`, `IFCPROXY`,
///    `IFCEQUIPMENTELEMENT`, `IFCELECTRICDISTRIBUTIONPOINT`) resolve through
///    `legacy_entities::get_legacy_entity_info`, which carries a
///    `has_geometry` flag.
/// 3. Reinforcement variants not covered above fall back to a substring
///    match (`REINFORCING…` / `REINFORCED…`).
pub fn has_geometry_by_name(type_name: &str) -> bool {
    let upper = normalise_uppercase(type_name);
    classifications().get(upper.as_ref()).map_or_else(
        || compute_has_geometry(upper.as_ref()), |class| class.has_geometry,
    )
}

fn compute_has_geometry(upper: &str) -> bool {
    if let Some(info) = get_legacy_entity_info(upper) {
        return info.has_geometry;
    }

    let t = IfcType::from_str(upper);
    if matches!(t, IfcType::Unknown(_)) {
        // Reinforcement bars/meshes/elements are common in IFC2x3 files. Match
        // a tighter prefix than `contains("REINFORC")` to avoid catching
        // unrelated tokens with the substring.
        return upper.starts_with("IFCREINFORCING") || upper.starts_with("IFCREINFORCED");
    }

    if !t.is_subtype_of(IfcType::IfcProduct) {
        return false;
    }

    !is_non_geometric_spatial(t)
}

/// Subtypes of `IfcProduct` that exist solely as spatial containers and
/// aren't rendered directly. `IfcSpace`/`IfcSite`/`IfcSpatialZone`/`IfcBuilding`
/// and their concrete subtypes are deliberately exempt — their boundary
/// representations are consumed by the renderer when present.
///
/// The exempt set grows as exporters are found that attach a body to a
/// container. `IfcSpatialZone` was unblocked for Revit Family geometry authored
/// via Dynamo (issue #1075); `IfcBuilding` for terrain/DGM exports that hang an
/// `IfcShellBasedSurfaceModel` straight off the building (issue #1910). In both
/// cases the class was blocked, so the entity never became a geometry job and
/// the model rendered nothing at all. **The gate only *permits* meshing; a
/// container with no representation still produces nothing**, so exempting a
/// class costs one abandoned job per instance and is the safe direction.
/// `IfcBuildingStorey` and the `IfcFacility`/`IfcFacilityPart` families stay
/// blocked only because no exporter has been observed giving them a body; the
/// same one-line exemption applies if one is.
///
/// We block by inheritance, not by exact match, so IFC4X3 facility
/// subclasses like `IfcBridge`/`IfcRoad`/`IfcRailway`/`IfcMarineFacility`
/// (under `IfcFacility`), their `*Part` variants (under `IfcFacilityPart`),
/// and any future concrete spatial container all collapse to the same answer
/// without the whitelist needing to enumerate them.
fn is_non_geometric_spatial(t: IfcType) -> bool {
    if t.is_subtype_of(IfcType::IfcSpace)
        || t.is_subtype_of(IfcType::IfcSite)
        || t.is_subtype_of(IfcType::IfcSpatialZone)
        || t.is_subtype_of(IfcType::IfcBuilding)
    {
        return false;
    }
    t.is_subtype_of(IfcType::IfcSpatialElement)
}

/// Whether `type_name` is one of the spatial-container types that
/// [`has_geometry_by_name`] still blocks by name (`IfcBuildingStorey`,
/// `IfcFacility`, `IfcFacilityPart`, `IfcSpatialElement`,
/// `IfcSpatialStructureElement`, and their subtypes) — i.e. `IfcProduct`
/// subtypes that `is_non_geometric_spatial` treats as never carrying
/// geometry directly. `IfcBuilding` (along with `IfcSpace`, `IfcSite` and
/// `IfcSpatialZone`) is handled class-wide by `has_geometry_by_name` instead
/// — see [`is_non_geometric_spatial`] — so it is no longer part of this
/// instance-level exception.
///
/// In the overwhelming majority of real files that assumption holds for the
/// still-blocked types: these entities are pure hierarchy nodes with a null
/// `Representation`. Issue #1910 was discovered against a DGM/terrain export
/// that attached an `IfcShellBasedSurfaceModel` directly to `IfcBuilding`
/// with no `IfcBuildingElement` children at all; that concrete case is now
/// covered by `IfcBuilding`'s class-wide exemption above, but the same
/// exporter shape could in principle target `IfcBuildingStorey` or another
/// still-blocked container. `has_geometry_by_name` alone can't distinguish
/// "this type never has a body" from "this specific instance happens not
/// to", so callers that need to catch that exceptional case combine this
/// predicate with an instance-level check of whether the entity's
/// `Representation` attribute (index 6 on any `IfcProduct`) is actually
/// non-null before scheduling it for meshing. See
/// `rust/processing/src/processor/mod.rs` and
/// `rust/wasm-bindings/src/api/gpu_meshes/prepass.rs`.
pub fn is_representationless_spatial_container_by_name(type_name: &str) -> bool {
    let upper = normalise_uppercase(type_name);
    classifications().get(upper.as_ref()).map_or_else(
        || compute_is_representationless_spatial_container(upper.as_ref()),
        |class| class.representationless_spatial,
    )
}

fn compute_is_representationless_spatial_container(upper: &str) -> bool {
    if get_legacy_entity_info(upper).is_some() {
        // Legacy/removed entities resolve their own `has_geometry` flag and
        // are never part of this modern-schema-only exception path.
        return false;
    }
    let t = IfcType::from_str(upper);
    if matches!(t, IfcType::Unknown(_)) || !t.is_subtype_of(IfcType::IfcProduct) {
        return false;
    }
    is_non_geometric_spatial(t)
}

/// Cheap textual check for whether a STEP entity's attribute at `index`
/// (0-based, top-level — respects nested parens and quoted strings) is
/// present and non-null (`$`), without fully decoding the entity via
/// `EntityDecoder`. Companion to
/// [`is_representationless_spatial_container_by_name`]: callers use it to
/// check attribute 6 (`Representation`, stable across every `IfcProduct`
/// subtype) before deciding an otherwise-excluded spatial container
/// exceptionally carries geometry (#1910).
pub fn nth_attribute_is_present(entity_bytes: &[u8], index: usize) -> bool {
    let Some(open_idx) = entity_bytes.iter().position(|byte| *byte == b'(') else {
        return false;
    };
    let Some(close_idx) = entity_bytes.iter().rposition(|byte| *byte == b')') else {
        return false;
    };
    if close_idx <= open_idx {
        return false;
    }
    let args = &entity_bytes[open_idx + 1..close_idx];

    let mut in_string = false;
    let mut depth = 0i32;
    let mut start = 0usize;
    let mut attr_idx = 0usize;
    let mut i = 0usize;
    while i < args.len() {
        match args[i] {
            b'\'' => {
                if in_string && i + 1 < args.len() && args[i + 1] == b'\'' {
                    i += 1;
                } else {
                    in_string = !in_string;
                }
            }
            b'(' if !in_string => depth += 1,
            b')' if !in_string => depth -= 1,
            b',' if !in_string && depth == 0 => {
                if attr_idx == index {
                    let token = trim_ascii(&args[start..i]);
                    return !token.is_empty() && token != b"$";
                }
                attr_idx += 1;
                start = i + 1;
            }
            _ => {}
        }
        i += 1;
    }
    if attr_idx == index {
        let token = trim_ascii(&args[start..]);
        return !token.is_empty() && token != b"$";
    }
    false
}

fn trim_ascii(bytes: &[u8]) -> &[u8] {
    let mut s = 0usize;
    let mut e = bytes.len();
    while s < e && bytes[s].is_ascii_whitespace() {
        s += 1;
    }
    while e > s && bytes[e - 1].is_ascii_whitespace() {
        e -= 1;
    }
    &bytes[s..e]
}

/// Check if an IFC entity class is "simple" geometry (processed first for
/// fast first frame). Driven off the EXPRESS inheritance graph rather than
/// a leaf-level blacklist, so new IFC4X3 subtypes (e.g. `IfcSolarDevice`
/// under `IfcEnergyConversionDevice`) are categorised correctly without
/// code changes — see PR #585.
///
/// Returns `true` for "simple" elements (load first), `false` for
/// "secondary/complex" (openings, doors, windows, furniture, MEP/distribution
/// elements, spaces, sites, annotations, virtual/proxy entities).
pub fn is_simple_geometry_type(type_name: &str) -> bool {
    let upper = normalise_uppercase(type_name);
    classifications().get(upper.as_ref()).map_or_else(
        || compute_is_simple(upper.as_ref()), |class| class.simple_geometry,
    )
}

/// Resolve a STEP keyword to its `IfcType`, **legacy-aware**: a removed/renamed
/// entity (`IFCPROXY`, `IFCSOLIDSTRATUM`, …) maps to its modern base type via the
/// hand-maintained legacy table, exactly as `has_geometry_by_name` does. Any pass
/// that *classifies* or *labels* an entity must use this rather than a bare
/// `IfcType::from_str`; otherwise it disagrees with the geometry pass (which meshes
/// legacy entities), leaving a rendered node with no attribute row — the
/// geometry/attribute product-set divergence (#1496).
pub fn legacy_aware_ifc_type(type_name: &str) -> IfcType {
    let upper = normalise_uppercase(type_name);
    match get_legacy_entity_info(upper.as_ref()) {
        Some(info) => info.base_type,
        None => IfcType::from_str(upper.as_ref()),
    }
}

/// The `IfcTypeProduct` subtype a STEP keyword names, **legacy-aware**, or
/// `None` when the keyword is not one.
///
/// The single predicate behind every type-geometry candidate gate (#957/#962):
/// the native processor, the streaming and sharded browser pre-passes, the
/// styling pre-pass, and the attribute export's pass 3. They MUST agree — a
/// keyword one admits and another drops is either geometry with no attribute
/// row or an attribute row with no geometry (#1518).
///
/// Keeps the cheap `ends_with` pre-filter that kept the resolve and the
/// `is_subtype_of` walk off the hot path for the non-type majority, and
/// resolves LEGACY-AWARE: under a bare [`IfcType::from_str`] the IFC2X3 type
/// products IFC4X3 dropped (`IFCDOORSTYLE`, `IFCWINDOWSTYLE`,
/// `IFCBUILDINGELEMENTTYPE`) come back `Unknown`, a subtype of nothing, so
/// every gate discarded them before they could become jobs — and they carry
/// `has_geometry: false` in the legacy table, so the ordinary product route
/// did not reach them either. Their `RepresentationMaps` geometry was dropped
/// by every path at once (#3187).
///
/// `type_name` is the raw STEP keyword, i.e. already uppercase.
pub fn type_product_ifc_type(type_name: &str) -> Option<IfcType> {
    if !type_name.ends_with("TYPE") && !type_name.ends_with("STYLE") {
        return None;
    }
    let ty = legacy_aware_ifc_type(type_name);
    ty.is_subtype_of(IfcType::IfcTypeProduct).then_some(ty)
}

/// The legacy-aware type for an entity, recovered from its RAW STEP RECORD.
///
/// For callers that hold a `DecodedEntity` and its source bytes but no keyword.
/// `DecodedEntity.ifc_type` comes from a bare [`IfcType::from_str`], and for a
/// name IFC4X3 dropped that is `IfcType::Unknown` — which stores a **CRC32
/// hash, not the name**, so the keyword cannot be recovered from it. The record
/// is the only place it still exists.
///
/// `decoded` is returned unchanged when it is already a known type, so the
/// scan is paid only by entities that need it, and when the record is
/// malformed enough that no keyword can be read.
///
/// Exists because the wasm mesh batch had exactly this shape and got it wrong:
/// every legacy keyword reached the browser labelled `"Unknown"` while the
/// native pipeline, which still has the keyword in hand, labelled it correctly
/// (#3179).
pub fn legacy_aware_ifc_type_from_record(decoded: IfcType, record: &[u8]) -> IfcType {
    if !matches!(decoded, IfcType::Unknown(_)) {
        return decoded;
    }
    match crate::fast_parse::extract_entity_type_name(record) {
        Some(name) => legacy_aware_ifc_type(name),
        None => decoded,
    }
}

fn compute_is_simple(upper: &str) -> bool {
    let t = legacy_aware_ifc_type(upper);

    // Anything not in the modern schema defaults to "simple" priority,
    // matching the original blacklist's "anything else is simple" behaviour.
    if matches!(t, IfcType::Unknown(_)) {
        return true;
    }

    let is_secondary = t.is_subtype_of(IfcType::IfcOpeningElement)
        || t.is_subtype_of(IfcType::IfcWindow)
        || t.is_subtype_of(IfcType::IfcDoor)
        || t.is_subtype_of(IfcType::IfcFurnishingElement)
        // Covers IfcEnergyConversionDevice + IfcSolarDevice + every Flow*
        // and every MEP terminal — all inherit from IfcDistributionElement.
        || t.is_subtype_of(IfcType::IfcDistributionElement)
        || matches!(
            t,
            // Spatial elements that have geometry but aren't structural.
            IfcType::IfcSpace
                | IfcType::IfcSpatialZone
                | IfcType::IfcSite
                // Annotations / virtual / proxy.
                | IfcType::IfcAnnotation
                | IfcType::IfcVirtualElement
                | IfcType::IfcBuildingElementProxy
        );

    !is_secondary
}

#[cfg(test)]
#[path = "schema_helpers_tests.rs"]
mod tests;