clifford_codegen/spec/

error.rs

//! Error types for specification parsing.
//!
//! These errors provide detailed information about what went wrong
//! during parsing, making it easy to fix specification files.

use thiserror::Error;

/// Errors that can occur when parsing an algebra specification.
#[derive(Debug, Error)]
pub enum ParseError {
    /// TOML syntax error.
    #[error("TOML parse error: {0}")]
    Toml(#[from] toml::de::Error),

    /// Algebra dimension exceeds the maximum supported (6).
    #[error("dimension {0} exceeds maximum of 6")]
    DimensionTooLarge(usize),

    /// Signature must have at least one basis vector.
    #[error("signature must have at least one basis vector")]
    EmptySignature,

    /// Duplicate basis vector name in signature.
    #[error("duplicate basis vector name: '{0}'")]
    DuplicateBasisName(String),

    /// Invalid basis vector name in signature.
    #[error("invalid basis vector name: '{name}' (expected format: e1, e2, e3, etc.)")]
    InvalidBasisName {
        /// The invalid basis name.
        name: String,
    },

    /// Basis vector index exceeds algebra dimension.
    #[error("basis '{name}' references index {index} but algebra only has {dim} dimensions")]
    BasisIndexOutOfBounds {
        /// The basis name.
        name: String,
        /// The invalid index (1-based from name).
        index: usize,
        /// Algebra dimension.
        dim: usize,
    },

    /// Basis vector indices are not contiguous (0, 1, 2, ...).
    #[error(
        "basis vector indices must be contiguous: expected index {expected} but found {found} for '{name}'"
    )]
    NonContiguousBasisIndices {
        /// The expected index.
        expected: usize,
        /// The found index.
        found: usize,
        /// The basis name with the wrong index.
        name: String,
    },

    /// Type references a grade that exceeds the algebra dimension.
    #[error("type '{type_name}' has invalid grade {grade} (max: {max})")]
    InvalidGrade {
        /// The type name.
        type_name: String,
        /// The invalid grade.
        grade: usize,
        /// Maximum valid grade.
        max: usize,
    },

    /// Type has wrong number of fields for its grades.
    #[error("type '{type_name}' has {got} fields but needs {expected}")]
    FieldCountMismatch {
        /// The type name.
        type_name: String,
        /// Expected number of fields.
        expected: usize,
        /// Actual number of fields.
        got: usize,
    },

    /// Duplicate field name in a type.
    #[error("type '{type_name}' has duplicate field name: '{field}'")]
    DuplicateFieldName {
        /// The type name.
        type_name: String,
        /// The duplicate field name.
        field: String,
    },

    /// Duplicate type name in specification.
    #[error("duplicate type name: '{0}'")]
    DuplicateTypeName(String),

    /// Invalid blade name in blades section.
    #[error("invalid blade name: '{name}' (expected format: e1, e12, e123, etc.)")]
    InvalidBladeName {
        /// The invalid blade name.
        name: String,
    },

    /// Blade index exceeds algebra dimension.
    #[error("blade '{name}' references basis index {index} but algebra only has {dim} dimensions")]
    BladeIndexOutOfBounds {
        /// The blade name.
        name: String,
        /// The invalid index.
        index: usize,
        /// Algebra dimension.
        dim: usize,
    },

    /// Unknown type reference (e.g., in alias_of).
    #[error("unknown type reference: '{0}'")]
    UnknownType(String),

    /// Type alias references itself.
    #[error("type '{type_name}' cannot alias itself")]
    SelfAlias {
        /// The type name.
        type_name: String,
    },

    /// Type alias forms a cycle.
    #[error("type alias cycle detected involving '{type_name}'")]
    AliasCycle {
        /// The type name.
        type_name: String,
    },

    /// Unknown field name in a type's field list.
    #[error("type '{type_name}' has unknown field name: '{field}'")]
    UnknownFieldName {
        /// The type name.
        type_name: String,
        /// The unknown field name.
        field: String,
    },

    /// Invalid value for a configuration field.
    #[error("invalid value '{value}' for field '{field}', expected {expected}")]
    InvalidValue {
        /// The field name.
        field: String,
        /// The invalid value.
        value: String,
        /// Description of expected values.
        expected: String,
    },

    /// Sparse type blade count doesn't match field count.
    #[error("type '{type_name}' has {blades} blade mappings but {fields} fields")]
    SparseBladeCountMismatch {
        /// The type name.
        type_name: String,
        /// Number of blade mappings.
        blades: usize,
        /// Number of fields.
        fields: usize,
    },

    /// Sparse type blade doesn't match specified grades.
    #[error(
        "type '{type_name}' blade '{blade}' has grade {blade_grade} but type only spans grades {grades:?}"
    )]
    SparseBladeGradeMismatch {
        /// The type name.
        type_name: String,
        /// The blade name.
        blade: String,
        /// The blade's actual grade.
        blade_grade: usize,
        /// The expected grades.
        grades: Vec<usize>,
    },

    /// Algebra is incomplete: some products don't have matching output types.
    #[error(
        "algebra '{name}' is incomplete: {count} products have no output type.\n{details}\nAdd missing types or set `complete = false` in [algebra] section."
    )]
    IncompleteAlgebra {
        /// Algebra name.
        name: String,
        /// Number of missing products.
        count: usize,
        /// Human-readable details of missing products.
        details: String,
    },

    /// Type is missing required field_map.
    #[error(
        "type '{type_name}' is missing required field_map (explicit blade-to-field mappings are required)"
    )]
    MissingFieldMap {
        /// The type name.
        type_name: String,
    },

    /// Blade grade in field_map doesn't match type's grades.
    #[error(
        "type '{type_name}' field '{field}' maps to blade '{blade}' (grade {blade_grade}) but type only spans grades {grades:?}"
    )]
    FieldMapGradeMismatch {
        /// The type name.
        type_name: String,
        /// The field name.
        field: String,
        /// The blade name.
        blade: String,
        /// The blade's actual grade.
        blade_grade: usize,
        /// The expected grades.
        grades: Vec<usize>,
    },
}

/// Describes a product that has no matching output type.
#[derive(Debug, Clone)]
pub struct MissingProduct {
    /// Left operand type name.
    pub lhs: String,
    /// Right operand type name.
    pub rhs: String,
    /// Product type name (e.g., "geometric", "exterior").
    pub product_type: String,
    /// Output grades produced by this product.
    pub output_grades: Vec<usize>,
}