fluidattacks_blends_domain/syntax/

node.rs

//! Typed syntax nodes: one enum variant per syntax label type.

use alloc::collections::BTreeMap;
use alloc::string::String;
use alloc::vec::Vec;

use strum::{EnumDiscriminants, IntoStaticStr};

use crate::NodeId;

/// One entry of a file's structure tree (its classes, methods and nesting).
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct FileStructData {
    /// Id of the AST node this entry was built from.
    pub node: NodeId,
    /// The entry's syntax-node label, e.g. `"MethodDeclaration"`.
    pub kind: String,
    /// The entry's payload: a leaf value or further nested entries.
    pub data: FileStructValue,
    /// Ids of every AST node this entry spans, when known.
    pub node_range: Option<Vec<NodeId>>,
}

/// A [`FileStructData`] entry's payload.
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum FileStructValue {
    /// A leaf: the entry is a method, named by its signature.
    MethodName(String),
    /// A branch: nested entries, keyed by name.
    Children(BTreeMap<String, FileStructData>),
}

/// One instance (object) found while extracting a file's structure.
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct FileInstanceData {
    /// The instance's variable or field name.
    pub object: String,
    /// The expression the instance was constructed from.
    pub source: String,
    /// The instance's constructed type name.
    pub source_type: String,
}

/// A tree-sitter-independent syntax node: one variant per label the readers emit.
#[derive(Clone, PartialEq, Eq, Debug, EnumDiscriminants)]
#[non_exhaustive]
#[strum_discriminants(
    name(SyntaxKind),
    derive(PartialOrd, Ord, Hash, IntoStaticStr),
    non_exhaustive
)]
pub enum SyntaxNode {
    /// A decorator/annotation applied to a declaration.
    Annotation {
        /// The node's name, as written.
        name: String,
        /// Id of the argument list node, if any.
        arguments_id: Option<NodeId>,
    },
    /// A single call argument.
    Argument,
    /// A call's argument list.
    ArgumentList,
    /// An array literal initializer.
    ArrayInitializer {
        /// The declared variable's type, as written, if any.
        variable_type: Option<String>,
    },
    /// An assignment expression.
    Assignment {
        /// Id of the declared variable's node.
        variable_id: NodeId,
        /// Id of the value node, if any.
        value_id: Option<NodeId>,
        /// The operator, as written, if any.
        operator: Option<String>,
    },
    /// An attribute applied to a declaration (non-annotation form).
    Attribute {
        /// The node's name, as written.
        name: String,
    },
    /// An `await` expression.
    AwaitExpression {
        /// Id of the expression node.
        expression_id: NodeId,
    },
    /// A binary operator expression.
    BinaryOperation {
        /// The operator, as written.
        operator: String,
        /// Id of the left-hand operand node, if any.
        left_id: Option<NodeId>,
        /// Id of the right-hand operand node, if any.
        right_id: Option<NodeId>,
    },
    /// A `break` statement.
    Break,
    /// A `catch` clause of a try statement.
    CatchClause {
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
        /// Id of the exception variable declaration, if any.
        catch_declaration: Option<NodeId>,
    },
    /// The exception variable declared by a `catch` clause.
    CatchDeclaration,
    /// A class declaration.
    Class {
        /// The node's name, as written.
        name: String,
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
        /// Id of the modifiers node, if any.
        modifiers_id: Option<NodeId>,
        /// The name of the class this one extends, if any.
        inherited_class: Option<String>,
        /// The access modifier keywords, as written, if any.
        access_modifiers: Option<String>,
    },
    /// A class's member list.
    ClassBody,
    /// A source comment.
    Comment {
        /// The comment text, including its delimiters.
        comment: String,
    },
    /// A `continue` statement.
    Continue,
    /// A generic (language-agnostic) declaration.
    Declaration {
        /// The node's name, as written.
        name: String,
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
        /// The access modifier keywords, as written, if any.
        access_modifiers: Option<String>,
    },
    /// A block holding one or more declarations.
    DeclarationBlock,
    /// A `default` label or value.
    Default,
    /// A `do`/`while` loop.
    DoStatement {
        /// Id of the node's body block.
        block_id: NodeId,
        /// Id of the condition expression node.
        condition_id: NodeId,
    },
    /// An indexed element access (e.g. `a[i]`).
    ElementAccess {
        /// Id of the expression node.
        expression_id: NodeId,
        /// Id of the argument list node, if any.
        arguments_id: Option<NodeId>,
    },
    /// The `else` branch of a conditional.
    ElseClause {
        /// Id of the node's body block.
        block_id: NodeId,
    },
    /// A block of executable statements.
    ExecutionBlock,
    /// An export statement.
    Export {
        /// The expression, as written, if any.
        expression: Option<String>,
        /// Id of the declaration node, if any.
        declaration_id: Option<NodeId>,
        /// The bound local alias, if any.
        alias: Option<String>,
        /// Id of the default export's declaration node, if any.
        default_id: Option<NodeId>,
    },
    /// A statement that is a bare expression.
    ExpressionStatement,
    /// The file's root node.
    File,
    /// The `finally` clause of a try statement.
    FinallyClause {
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
    },
    /// A `for-each`/`for-in` loop.
    ForEachStatement {
        /// Id of the declared variable's node.
        variable_id: NodeId,
        /// Id of the collection being iterated.
        iterable_item_id: NodeId,
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
    },
    /// A classic C-style `for` loop.
    ForStatement {
        /// Id of the node's body block.
        block_id: NodeId,
        /// Id of the loop's initializer node, if any.
        initializer_id: Option<NodeId>,
        /// Id of the condition expression node, if any.
        condition_id: Option<NodeId>,
        /// Id of the loop's update node, if any.
        update_id: Option<NodeId>,
    },
    /// An `if` conditional.
    If {
        /// Id of the condition expression node.
        condition_id: NodeId,
        /// Id of the branch taken when the condition is true, if any.
        true_id: Option<NodeId>,
        /// Id of the branch taken when the condition is false, if any.
        false_id: Option<NodeId>,
        /// Id of the condition's initializer node (e.g. an `if let` binding), if any.
        initializer: Option<NodeId>,
    },
    /// An import statement.
    Import {
        /// The expression, as written, if any.
        expression: Option<String>,
        /// The bound local alias, if any.
        alias: Option<String>,
        /// The imported method's name, if any.
        method_name: Option<String>,
        /// The import's kind keyword (e.g. `type`), if any.
        import_type: Option<String>,
        /// The imported module's name, if any.
        module_name: Option<String>,
    },
    /// A JSX element.
    JsxElement,
    /// A lambda/closure's declared type.
    LambdaFunctionType,
    /// A literal value.
    Literal {
        /// The literal value, as written.
        value: String,
        /// The literal's type keyword.
        value_type: String,
    },
    /// A member access expression (e.g. `a.b`).
    MemberAccess {
        /// The accessed member's name.
        member: String,
        /// The expression, as written.
        expression: String,
        /// Id of the expression node.
        expression_id: NodeId,
        /// Id of the node that scopes this symbol lookup, if any.
        symbol_scope: Option<NodeId>,
    },
    /// A file's top-level metadata: structure, instances and imports.
    Metadata {
        /// The file's path.
        path: String,
        /// The file's top-level members, keyed by name.
        structure: BTreeMap<String, FileStructData>,
        /// Per-object metadata instances, keyed by qualified name.
        instances: BTreeMap<String, BTreeMap<String, FileInstanceData>>,
        /// The names this file imports.
        imports: Vec<String>,
        /// The file's package/namespace name, if any.
        package: Option<String>,
    },
    /// A method or function declaration.
    MethodDeclaration {
        /// The node's name, as written, if any.
        name: Option<String>,
        /// The access modifier keywords, as written, if any.
        access_modifiers: Option<String>,
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
        /// Id of the modifiers node, if any.
        modifiers_id: Option<NodeId>,
        /// Id of the parameter list node, if any.
        parameters_id: Option<NodeId>,
    },
    /// A method or function call.
    MethodInvocation {
        /// The expression, as written.
        expression: String,
        /// The receiver's textual expression, if any.
        object: Option<String>,
        /// Id of the node that scopes this symbol lookup, if any.
        symbol_scope: Option<NodeId>,
        /// Id of the expression node, if any.
        expression_id: Option<NodeId>,
        /// Id of the argument list node, if any.
        arguments_id: Option<NodeId>,
        /// Id of the receiver node, if any.
        object_id: Option<NodeId>,
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
        /// The receiver's fully qualified type name, when resolved, if any.
        receiver_type_fqn: Option<String>,
    },
    /// A node the grammar could not classify.
    MissingNode {
        /// The original (unmapped) tree-sitter node type.
        node_type: String,
    },
    /// A declaration's modifier list (e.g. `public static`).
    Modifiers,
    /// A whole-module import.
    ModuleImport {
        /// The expression, as written.
        expression: String,
        /// The bound local alias, if any.
        alias: Option<String>,
        /// The imported module's name, if any.
        module_name: Option<String>,
    },
    /// A call argument passed by name.
    NamedArgument {
        /// Id of the value node.
        value_id: NodeId,
        /// The named argument's parameter name, if any.
        argument_name: Option<String>,
    },
    /// A namespace/module declaration.
    Namespace {
        /// The node's name, as written.
        name: String,
        /// Id of the node's body block, if any.
        block_id: Option<NodeId>,
    },
    /// An object-construction expression (`new X(...)`).
    NewExpression {
        /// Id of the constructor being invoked.
        constructor_id: NodeId,
        /// Id of the argument list node, if any.
        arguments_id: Option<NodeId>,
    },
    /// An object literal or reference (e.g. a Terraform resource block).
    Object {
        /// The node's name, as written, if any.
        name: Option<String>,
        /// The Terraform block's reference expression, if any.
        tf_reference: Option<String>,
    },
    /// An object instantiation with an initializer.
    ObjectCreation {
        /// The node's name, as written.
        name: String,
        /// Id of the argument list node, if any.
        arguments_id: Option<NodeId>,
        /// Id of the loop's initializer node, if any.
        initializer_id: Option<NodeId>,
    },
    /// A key/value pair (e.g. in a map or object literal).
    Pair {
        /// Id of the pair's key node.
        key_id: NodeId,
        /// Id of the value node.
        value_id: NodeId,
    },
    /// A function/method parameter.
    Parameter {
        /// The declared variable's name, if any.
        variable: Option<String>,
        /// The declared variable's type, as written, if any.
        variable_type: Option<String>,
        /// Id of the value node, if any.
        value_id: Option<NodeId>,
        /// The parameter's passing mode keyword (e.g. `ref`), if any.
        parameter_mode: Option<String>,
    },
    /// A function/method's parameter list.
    ParameterList,
    /// A parenthesized expression.
    ParenthesizedExpression,
    /// A language reserved word used as a value (e.g. `self`).
    ReservedWord {
        /// The literal value, as written.
        value: String,
    },
    /// A rest/spread binding pattern (e.g. `...rest`).
    RestPattern {
        /// Id of the value node.
        value_id: NodeId,
    },
    /// A `return` statement.
    Return {
        /// Id of the value node, if any.
        value_id: Option<NodeId>,
    },
    /// A Go-style type selector.
    Selector {
        /// The selector's name, if any.
        selector_name: Option<String>,
    },
    /// A spread element in a call or literal (e.g. `...xs`).
    SpreadElement {
        /// Id of the value node.
        value_id: NodeId,
    },
    /// A `switch` statement's body.
    SwitchBody,
    /// One `case`/`when` section of a switch.
    SwitchSection {
        /// The case label's expression, as written.
        case_expression: String,
    },
    /// A `switch` statement.
    SwitchStatement {
        /// Id of the node's body block.
        block_id: NodeId,
        /// Id of the value node.
        value_id: NodeId,
    },
    /// A bare symbol reference.
    SymbolLookup {
        /// The looked-up symbol's name.
        symbol: String,
        /// Id of the node that scopes this symbol lookup, if any.
        symbol_scope: Option<NodeId>,
        /// The literal value, as written, if any.
        value: Option<String>,
    },
    /// A ternary conditional expression (`a ? b : c`).
    TernaryOperation {
        /// Id of the condition expression node.
        condition_id: NodeId,
        /// Id of the branch taken when the condition is true.
        true_id: NodeId,
        /// Id of the branch taken when the condition is false.
        false_id: NodeId,
    },
    /// A `this`/`self` reference.
    This {
        /// The literal value, as written.
        value: String,
    },
    /// A `throw`/`raise` statement.
    ThrowStatement {
        /// Id of the expression node, if any.
        expression_id: Option<NodeId>,
    },
    /// A `try` statement.
    TryStatement {
        /// Id of the node's body block.
        block_id: NodeId,
        /// Id of the try-with-resources declaration node, if any.
        resources_id: Option<NodeId>,
    },
    /// A unary operator expression.
    UnaryExpression {
        /// The operator, as written.
        operator: String,
        /// Id of the operand node.
        operand_id: NodeId,
    },
    /// A `using`/`with` resource-scoped statement.
    UsingStatement {
        /// Id of the node's body block.
        block_id: NodeId,
        /// Id of the declaration node, if any.
        declaration_id: Option<NodeId>,
    },
    /// A variable declaration.
    VariableDeclaration {
        /// The declared variable's name.
        variable: String,
        /// The declared variable's type, as written, if any.
        variable_type: Option<String>,
        /// Id of the value node, if any.
        value_id: Option<NodeId>,
        /// Id of the declared variable's node, if any.
        variable_id: Option<NodeId>,
        /// The access modifier keyword, if any.
        access_modifier: Option<String>,
    },
    /// A `while` loop.
    WhileStatement {
        /// Id of the node's body block.
        block_id: NodeId,
        /// Id of the condition expression node, if any.
        condition_id: Option<NodeId>,
    },
}

impl SyntaxNode {
    /// Id of this node's argument list, for variants that take one.
    #[must_use]
    pub const fn arguments_id(&self) -> Option<NodeId> {
        match self {
            Self::Annotation { arguments_id, .. }
            | Self::ElementAccess { arguments_id, .. }
            | Self::MethodInvocation { arguments_id, .. }
            | Self::NewExpression { arguments_id, .. }
            | Self::ObjectCreation { arguments_id, .. } => *arguments_id,
            _ => None,
        }
    }

    /// Id of this node's body block, for variants that have one.
    #[must_use]
    pub const fn block_id(&self) -> Option<NodeId> {
        match self {
            Self::CatchClause { block_id, .. }
            | Self::Class { block_id, .. }
            | Self::Declaration { block_id, .. }
            | Self::FinallyClause { block_id }
            | Self::ForEachStatement { block_id, .. }
            | Self::MethodDeclaration { block_id, .. }
            | Self::MethodInvocation { block_id, .. }
            | Self::Namespace { block_id, .. } => *block_id,
            Self::DoStatement { block_id, .. }
            | Self::ElseClause { block_id }
            | Self::ForStatement { block_id, .. }
            | Self::SwitchStatement { block_id, .. }
            | Self::TryStatement { block_id, .. }
            | Self::UsingStatement { block_id, .. }
            | Self::WhileStatement { block_id, .. } => Some(*block_id),
            _ => None,
        }
    }

    /// This node's declared name, for variants that are named.
    #[must_use]
    pub fn name(&self) -> Option<&str> {
        match self {
            Self::Annotation { name, .. }
            | Self::Attribute { name }
            | Self::Class { name, .. }
            | Self::Declaration { name, .. }
            | Self::Namespace { name, .. }
            | Self::ObjectCreation { name, .. } => Some(name.as_str()),
            Self::MethodDeclaration { name, .. } | Self::Object { name, .. } => name.as_deref(),
            _ => None,
        }
    }

    /// The declared variable's name, for variants that declare one.
    #[must_use]
    pub fn variable(&self) -> Option<&str> {
        match self {
            Self::VariableDeclaration { variable, .. } => Some(variable.as_str()),
            Self::Parameter { variable, .. } => variable.as_deref(),
            _ => None,
        }
    }

    /// The looked-up symbol's name, for [`Self::SymbolLookup`].
    #[must_use]
    pub const fn symbol(&self) -> Option<&str> {
        match self {
            Self::SymbolLookup { symbol, .. } => Some(symbol.as_str()),
            _ => None,
        }
    }

    /// This node's expression text, for variants that carry one.
    #[must_use]
    pub fn expression(&self) -> Option<&str> {
        match self {
            Self::MemberAccess { expression, .. }
            | Self::MethodInvocation { expression, .. }
            | Self::ModuleImport { expression, .. } => Some(expression.as_str()),
            Self::Export { expression, .. } | Self::Import { expression, .. } => {
                expression.as_deref()
            }
            _ => None,
        }
    }

    /// The bound local alias, for import/export variants that have one.
    #[must_use]
    pub fn alias(&self) -> Option<&str> {
        match self {
            Self::Export { alias, .. }
            | Self::Import { alias, .. }
            | Self::ModuleImport { alias, .. } => alias.as_deref(),
            _ => None,
        }
    }

    /// This node's literal value, as written, for variants that have one.
    #[must_use]
    pub fn value(&self) -> Option<&str> {
        match self {
            Self::Literal { value, .. } | Self::ReservedWord { value } | Self::This { value } => {
                Some(value.as_str())
            }
            Self::SymbolLookup { value, .. } => value.as_deref(),
            _ => None,
        }
    }

    /// Id of the call receiver node, for [`Self::MethodInvocation`].
    #[must_use]
    pub const fn object_id(&self) -> Option<NodeId> {
        match self {
            Self::MethodInvocation { object_id, .. } => *object_id,
            _ => None,
        }
    }

    /// Id of this node's value node, for variants that carry one.
    #[must_use]
    pub const fn value_id(&self) -> Option<NodeId> {
        match self {
            Self::Assignment { value_id, .. }
            | Self::Parameter { value_id, .. }
            | Self::Return { value_id }
            | Self::VariableDeclaration { value_id, .. } => *value_id,
            Self::NamedArgument { value_id, .. }
            | Self::Pair { value_id, .. }
            | Self::RestPattern { value_id }
            | Self::SpreadElement { value_id }
            | Self::SwitchStatement { value_id, .. } => Some(*value_id),
            _ => None,
        }
    }

    /// Id of the declared variable's node, for variants that declare one.
    #[must_use]
    pub const fn variable_id(&self) -> Option<NodeId> {
        match self {
            Self::VariableDeclaration { variable_id, .. } => *variable_id,
            Self::Assignment { variable_id, .. } | Self::ForEachStatement { variable_id, .. } => {
                Some(*variable_id)
            }
            _ => None,
        }
    }

    #[must_use]
    pub(crate) const fn symbol_scope(&self) -> Option<NodeId> {
        match self {
            Self::MemberAccess { symbol_scope, .. }
            | Self::MethodInvocation { symbol_scope, .. }
            | Self::SymbolLookup { symbol_scope, .. } => *symbol_scope,
            _ => None,
        }
    }

    /// This node's syntax-kind label, e.g. `"MethodDeclaration"`.
    #[must_use]
    pub fn label_type(&self) -> &'static str {
        SyntaxKind::from(self).into()
    }
}

#[cfg(test)]
mod tests {
    use super::SyntaxNode;
    use crate::NodeId;
    use alloc::borrow::ToOwned;
    use alloc::vec;

    const BLOCK: NodeId = NodeId(42);

    /// Every variant that owns a body must expose it through `block_id`.
    ///
    /// Symbolic evaluation descends into bodies through this accessor, so a
    /// variant silently dropped from the match arm stops the traversal without
    /// any other signal. The list is exhaustive on purpose: it is the only way
    /// a removed arm shows up as a failure.
    #[test]
    #[allow(
        clippy::too_many_lines,
        reason = "the variant list is the point of the test"
    )]
    fn every_variant_that_owns_a_body_exposes_it_as_its_block_id() {
        let nodes_with_body = vec![
            SyntaxNode::CatchClause {
                block_id: Some(BLOCK),
                catch_declaration: None,
            },
            SyntaxNode::Class {
                name: "Foo".to_owned(),
                block_id: Some(BLOCK),
                modifiers_id: None,
                inherited_class: None,
                access_modifiers: None,
            },
            SyntaxNode::Declaration {
                name: "Foo".to_owned(),
                block_id: Some(BLOCK),
                access_modifiers: None,
            },
            SyntaxNode::FinallyClause {
                block_id: Some(BLOCK),
            },
            SyntaxNode::ForEachStatement {
                variable_id: NodeId(1),
                iterable_item_id: NodeId(2),
                block_id: Some(BLOCK),
            },
            SyntaxNode::MethodDeclaration {
                name: None,
                access_modifiers: None,
                block_id: Some(BLOCK),
                modifiers_id: None,
                parameters_id: None,
            },
            SyntaxNode::MethodInvocation {
                expression: "foo".to_owned(),
                object: None,
                symbol_scope: None,
                expression_id: None,
                arguments_id: None,
                object_id: None,
                block_id: Some(BLOCK),
                receiver_type_fqn: None,
            },
            SyntaxNode::Namespace {
                name: "ns".to_owned(),
                block_id: Some(BLOCK),
            },
            SyntaxNode::DoStatement {
                block_id: BLOCK,
                condition_id: NodeId(1),
            },
            SyntaxNode::ElseClause { block_id: BLOCK },
            SyntaxNode::ForStatement {
                block_id: BLOCK,
                initializer_id: None,
                condition_id: None,
                update_id: None,
            },
            SyntaxNode::SwitchStatement {
                block_id: BLOCK,
                value_id: NodeId(1),
            },
            SyntaxNode::TryStatement {
                block_id: BLOCK,
                resources_id: None,
            },
            SyntaxNode::UsingStatement {
                block_id: BLOCK,
                declaration_id: None,
            },
            SyntaxNode::WhileStatement {
                block_id: BLOCK,
                condition_id: None,
            },
        ];

        for node in nodes_with_body {
            assert_eq!(
                node.block_id(),
                Some(BLOCK),
                "{} must expose its body",
                node.label_type()
            );
        }
    }

    /// A variant without a body must not borrow one from a neighbouring arm.
    #[test]
    fn a_variant_without_a_body_reports_no_block_id() {
        assert_eq!(SyntaxNode::Break.block_id(), None);
        assert_eq!(
            SyntaxNode::FinallyClause { block_id: None }.block_id(),
            None
        );
    }
}