aeri 0.2.7

//! Parsed abstract syntax tree nodes for Aeri modules.
//!
//! This module keeps language structure in a lightweight, owned form for later
//! checking, lowering, and inspection passes.

use crate::diagnostic::Span;

#[derive(Debug, Clone, PartialEq, Eq)]
/// Top-level module in a single source file.
pub struct Module {
    /// Module name as declared in the source header.
    pub name: String,
    /// Collected top-level declarations.
    pub items: Vec<Item>,
}

impl Module {
    /// Constructs a module from a name and declaration list.
    pub fn new(name: impl Into<String>, items: Vec<Item>) -> Self {
        Self {
            name: name.into(),
            items,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// A top-level declaration stored in a parsed module.
pub enum Item {
    /// User-defined algebraic-like type.
    Type(TypeDecl),
    /// Constant definition with value and inferred type.
    Const(Const),
    /// Helper or exported function declaration.
    Function(Function),
    /// Validator entrypoint.
    Validator(Validator),
    /// Pure test block.
    Test(Test),
}

impl Item {
    /// Human-friendly declaration name.
    pub fn name(&self) -> &str {
        match self {
            Item::Type(type_decl) => &type_decl.name,
            Item::Const(constant) => &constant.name,
            Item::Function(function) => &function.name,
            Item::Validator(validator) => &validator.name,
            Item::Test(test) => &test.name,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// User-defined type declaration with optional constructor variants.
pub struct TypeDecl {
    /// Type name in source.
    pub name: String,
    /// Type variants for tuple-like or custom constructors.
    pub variants: Vec<Variant>,
    /// Span covering the entire declaration.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// A constructor variant for a custom type.
pub struct Variant {
    /// Variant name in source.
    pub name: String,
    /// Positional fields in the variant constructor.
    pub fields: Vec<VariantField>,
    /// Span covering the variant declaration.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// A single field in a type variant.
pub struct VariantField {
    /// Optional field name (if omitted, constructor positional style).
    pub name: Option<String>,
    /// Field type.
    pub ty: TypeRef,
    /// Span covering this field.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Constant declaration.
pub struct Const {
    /// Constant name.
    pub name: String,
    /// Declared type annotation.
    pub ty: TypeRef,
    /// Initialized expression.
    pub value: Expr,
    /// Span covering this declaration.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Function declaration used by validators and helpers.
pub struct Function {
    /// Function name.
    pub name: String,
    /// Ordered function parameters.
    pub params: Vec<Param>,
    /// Declared return type.
    pub return_type: TypeRef,
    /// Parsed function body.
    pub body: Block,
    /// Span covering this declaration.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Validator declaration with fixed `(redeemer: ByteArray, ctx: Tx)` context.
pub struct Validator {
    /// Validator name.
    pub name: String,
    /// Validator parameters.
    pub params: Vec<Param>,
    /// Parsed validator body.
    pub body: Block,
    /// Span covering this declaration.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Pure test block declaration.
pub struct Test {
    /// Test name.
    pub name: String,
    /// If true, test should fail and treated as pass when it does.
    pub should_fail: bool,
    /// Parsed test body.
    pub body: Block,
    /// Span covering this declaration.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// A function/validator parameter.
pub struct Param {
    /// Parameter identifier.
    pub name: String,
    /// Parameter type annotation.
    pub ty: TypeRef,
    /// Span covering this parameter.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// A type reference in parsed source.
pub struct TypeRef {
    /// Base type name.
    pub name: String,
    /// Generic argument list for types like `List<A>`.
    pub args: Vec<TypeRef>,
    /// Span covering this type reference.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// An ordered statement list plus block span.
pub struct Block {
    /// Block statements in source order.
    pub statements: Vec<Statement>,
    /// Span covering the block.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// A statement in an Aeri block.
pub enum Statement {
    Let {
        /// Bound identifier name.
        name: String,
        /// Optional annotation.
        ty: Option<TypeRef>,
        /// Initialization expression.
        value: Expr,
        /// Span covering the statement.
        span: Span,
    },
    Require {
        /// Predicate expression to assert.
        condition: Expr,
        /// Span covering the statement.
        span: Span,
    },
    Trace {
        /// String-like message expression.
        message: Expr,
        /// Span covering the statement.
        span: Span,
    },
    Return {
        /// Value returned from function-like context.
        value: Expr,
        /// Span covering the statement.
        span: Span,
    },
    Expr {
        /// Standalone expression statement.
        value: Expr,
        /// `true` if terminated by `;`.
        trailing_semicolon: bool,
        /// Span covering the statement.
        span: Span,
    },
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Parsed expression node.
pub struct Expr {
    /// Expression kind and payload.
    pub kind: ExprKind,
    /// Span covering this expression.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Kinds of expressions available in Aeri.
pub enum ExprKind {
    /// Boolean literal.
    Bool(bool),
    /// Integer literal.
    Int(i64),
    /// UTF-8 string literal.
    String(String),
    /// Hex bytes literal.
    ByteArray(String),
    /// Unit literal `()`.
    Unit,
    /// List literal `[a, b, c]`.
    List(Vec<Expr>),
    /// Built-in `fail` expression.
    Fail,
    /// Variable or parameter reference.
    Variable(String),
    Unary {
        /// Unary operator.
        op: UnaryOp,
        /// Operand expression.
        expr: Box<Expr>,
    },
    Binary {
        /// Left-hand expression.
        left: Box<Expr>,
        /// Operator.
        op: BinaryOp,
        /// Right-hand expression.
        right: Box<Expr>,
    },
    Call {
        /// Function name.
        callee: String,
        /// Argument list.
        args: Vec<Expr>,
    },
    If {
        /// Branch condition expression.
        condition: Box<Expr>,
        /// `then` branch block.
        then_branch: Block,
        /// `else` branch block.
        else_branch: Block,
    },
    Match {
        /// Match subject expression.
        subject: Box<Expr>,
        /// Match arms.
        arms: Vec<MatchArm>,
    },
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Pattern matching arm for match expressions.
pub struct MatchArm {
    /// Match pattern.
    pub pattern: Pattern,
    /// Body executed when pattern matches.
    pub body: Block,
    /// Span covering the arm.
    pub span: Span,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Match pattern variants.
pub enum Pattern {
    Wildcard {
        /// Wildcard `_` pattern span.
        span: Span,
    },
    Variable {
        /// Bound variable name.
        name: String,
        /// Span covering the variable pattern.
        span: Span,
    },
    Constructor {
        /// Constructor name.
        name: String,
        /// Nested field patterns for constructor payload.
        bindings: Vec<PatternBinding>,
        /// Span covering constructor pattern.
        span: Span,
    },
    Bool {
        /// Matched boolean value.
        value: bool,
        /// Span covering the literal pattern.
        span: Span,
    },
    Int {
        /// Matched integer value.
        value: i64,
        /// Span covering the literal pattern.
        span: Span,
    },
    ByteArray {
        /// Matched byte array payload.
        hex: String,
        /// Span covering literal pattern.
        span: Span,
    },
    String {
        /// Matched string payload.
        value: String,
        /// Span covering literal pattern.
        span: Span,
    },
    Unit {
        /// Unit `()` pattern span.
        span: Span,
    },
}

impl Pattern {
    /// Returns the source span for this pattern.
    pub fn span(&self) -> Span {
        match self {
            Pattern::Wildcard { span }
            | Pattern::Variable { span, .. }
            | Pattern::Constructor { span, .. }
            | Pattern::Bool { span, .. }
            | Pattern::Int { span, .. }
            | Pattern::ByteArray { span, .. }
            | Pattern::String { span, .. }
            | Pattern::Unit { span } => *span,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// Binding entry in constructor patterns.
pub struct PatternBinding {
    /// Optional alias or field label.
    pub name: Option<String>,
    /// Span covering the binding token.
    pub span: Span,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Unary operators.
pub enum UnaryOp {
    /// Logical negation `not`.
    Not,
    /// Arithmetic negation `-`.
    Negate,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Binary operators.
pub enum BinaryOp {
    /// Logical disjunction.
    Or,
    /// Logical conjunction.
    And,
    /// Equality comparison.
    Equal,
    /// Inequality comparison.
    NotEqual,
    /// `<` comparison.
    Less,
    /// `<=` comparison.
    LessEqual,
    /// `>` comparison.
    Greater,
    /// `>=` comparison.
    GreaterEqual,
    /// `+` arithmetic.
    Add,
    /// `-` arithmetic.
    Subtract,
    /// `*` arithmetic.
    Multiply,
    /// `/` arithmetic.
    Divide,
    /// `%` arithmetic.
    Remainder,
}