AST Rust API (#1477)

This PR defines an AST API as a façade over the last IR language
currently available (`ir2_flat_contracts`) that allows opaque access to
the IR nodes and the semantic information computed in the frontend
passes.

- From the `SemanticAnalysis` object that is obtainable from the
`CompilationUnit` it's possible to retrieve the root of the AST of each
file in the unit `get_file_ast_root()`, which returns `ast::SourceUnit`.
- Navigation from the `SourceUnit` down through the intermediate AST
nodes, down to the terminal nodes.
- Non-terminal nodes are wrapped in objects which contain a reference to
the IR node and the `SemanticAnalysis`.
- Terminal nodes are not wrapped by default except for `Identifier`
nodes, which allow attempting to resolve to a `Definition` object.
- A `Visitor` trait can be implemented and used via `accept_source_unit`
(and related functions) to traverse the wrapped AST.
- Non-terminal nodes define methods to access the child nodes.
- Certain non-terminal nodes also define other methods to access other
semantic information (eg. `SourceUnit` defines `contracts()` to retrieve
the list of contracts defined in the file)

Author: ggiraldez

Cargo.lock

@@ -27,7 +27,7 @@ categories = [
 [features]
 default = []
 __private_ariadne_errors = ["dep:ariadne"]
-__private_backend_api = ["dep:indexmap"]
+__private_backend_api = ["dep:indexmap", "dep:paste"]
 __private_wasm_apis = []
 __private_testing_utils = ["metaslang_bindings/__private_testing_utils"]
 
@@ -36,6 +36,7 @@ ariadne = { workspace = true, optional = true }
 indexmap = { workspace = true, optional = true }
 metaslang_bindings = { workspace = true }
 metaslang_cst = { workspace = true }
+paste = { workspace = true, optional = true }
 semver = { workspace = true }
 serde = { workspace = true }
 strum = { workspace = true }

crates/solidity/outputs/cargo/crate/Cargo.toml

@@ -8,6 +8,7 @@ use crate::cst::{NodeId, TerminalNode};
 //////////////////////////////////////////////////////////////////////////////
 // Definitions
 
+// __SLANG_DEFINITION_TYPES__ keep in sync with AST type
 #[derive(Debug)]
 pub enum Definition {
     Constant(ConstantDefinition),

crates/solidity/outputs/cargo/crate/src/backend/binder/definitions.rs

@@ -109,6 +109,8 @@ pub struct Binder {
     /// Linearisations, as a vector of definitions, indexed by the
     /// contract/interface definition's `NodeId`
     linearisations: HashMap<NodeId, Vec<NodeId>>,
+    /// Reverse mapping from definition `NodeId` to the set of references that bind to it
+    definitions_to_references: HashMap<NodeId, Vec<NodeId>>,
 }
 
 /// This controls visibility filtering and how to use the linearisation when
@@ -141,6 +143,7 @@ impl Binder {
             references: HashMap::new(),
             node_typing: HashMap::new(),
             linearisations: HashMap::new(),
+            definitions_to_references: HashMap::new(),
         }
     }
 
@@ -262,6 +265,31 @@ impl Binder {
         &self.references
     }
 
+    pub(crate) fn update_definitions_to_references_index(&mut self) {
+        // Build reverse mapping from definitions to references
+        let mut definitions: HashMap<NodeId, Vec<NodeId>> = HashMap::new();
+        for (reference_id, reference) in &self.references {
+            match &reference.resolution {
+                Resolution::Definition(node_id) => {
+                    if let Some(references) = definitions.get_mut(node_id) {
+                        references.push(*reference_id);
+                    } else {
+                        definitions.insert(*node_id, vec![*reference_id]);
+                    }
+                }
+                Resolution::Ambiguous(_) | Resolution::BuiltIn(_) | Resolution::Unresolved => {}
+            }
+        }
+        self.definitions_to_references = definitions;
+    }
+
+    pub fn get_references_by_definition_id(&self, node_id: NodeId) -> Vec<NodeId> {
+        self.definitions_to_references
+            .get(&node_id)
+            .cloned()
+            .unwrap_or_default()
+    }
+
     pub(crate) fn insert_using_directive_in_scope(
         &mut self,
         directive: UsingDirective,

crates/solidity/outputs/cargo/crate/src/backend/binder/mod.rs

@@ -0,0 +1,11 @@
+#[path = "nodes.generated.rs"]
+mod nodes;
+pub use nodes::*;
+
+mod node_extensions;
+pub use node_extensions::*;
+
+use super::ir2_flat_contracts as input;
+
+#[path = "visitor.generated.rs"]
+pub mod visitor;

crates/solidity/outputs/cargo/crate/src/backend/ir/ast/mod.rs

@@ -0,0 +1,51 @@
+use std::rc::Rc;
+
+use super::super::{ContractDefinition, ContractDefinitionStruct, Definition, InterfaceDefinition};
+
+pub enum ContractBase {
+    Contract(ContractDefinition),
+    Interface(InterfaceDefinition),
+}
+
+impl ContractBase {
+    fn from_definition(definition: &Definition) -> Option<Self> {
+        match definition {
+            Definition::Contract(contract) => Some(Self::Contract(Rc::clone(contract))),
+            Definition::Interface(interface) => Some(Self::Interface(Rc::clone(interface))),
+            _ => None,
+        }
+    }
+}
+
+impl ContractDefinitionStruct {
+    pub fn direct_bases(&self) -> Vec<ContractBase> {
+        self.inheritance_types()
+            .iter()
+            .filter_map(|inheritance_type| {
+                let base = inheritance_type.type_name().resolve_to_definition()?;
+                ContractBase::from_definition(&base)
+            })
+            .collect()
+    }
+
+    pub fn linearised_bases(&self) -> Vec<ContractBase> {
+        let Some(base_node_ids) = self
+            .semantic
+            .binder()
+            .get_linearised_bases(self.ir_node.node_id)
+        else {
+            // TODO(validation): once we have validation implemented, this
+            // branch should not be reachable, or we should generate an error
+            // while building the `SemanticAnalysis`.
+            return Vec::new();
+        };
+        base_node_ids
+            .iter()
+            .map(|node_id| {
+                let base_definition = Rc::new(Definition::create(*node_id, &self.semantic));
+                ContractBase::from_definition(&base_definition)
+                    .expect("Linearised base is either a contract or interface")
+            })
+            .collect()
+    }
+}

crates/solidity/outputs/cargo/crate/src/backend/ir/ast/node_extensions/contracts.rs

@@ -0,0 +1,207 @@
+use std::rc::Rc;
+
+use paste::paste;
+
+use super::super::nodes::{
+    ConstantDefinition, ConstantDefinitionStruct, ContractDefinition, ContractDefinitionStruct,
+    EnumDefinition, EnumDefinitionStruct, ErrorDefinition, ErrorDefinitionStruct, EventDefinition,
+    EventDefinitionStruct, FunctionDefinition, FunctionDefinitionStruct,
+    ImportDeconstructionSymbol, ImportDeconstructionSymbolStruct, InterfaceDefinition,
+    InterfaceDefinitionStruct, LibraryDefinition, LibraryDefinitionStruct, Parameter,
+    ParameterStruct, PathImport, PathImportStruct, StateVariableDefinition,
+    StateVariableDefinitionStruct, StructDefinition, StructDefinitionStruct, StructMember,
+    StructMemberStruct, UserDefinedValueTypeDefinition, UserDefinedValueTypeDefinitionStruct,
+    VariableDeclarationStatement, VariableDeclarationStatementStruct, YulFunctionDefinition,
+    YulFunctionDefinitionStruct, YulLabel, YulLabelStruct,
+};
+use super::{create_identifier, create_yul_identifier, Identifier, Reference, YulIdentifier};
+use crate::backend::ir::ast::{
+    create_constant_definition, create_contract_definition, create_enum_definition,
+    create_error_definition, create_event_definition, create_function_definition,
+    create_import_deconstruction_symbol, create_interface_definition, create_library_definition,
+    create_parameter, create_path_import, create_state_variable_definition,
+    create_struct_definition, create_struct_member, create_user_defined_value_type_definition,
+    create_variable_declaration_statement, create_yul_function_definition, create_yul_label,
+};
+use crate::backend::{binder, SemanticAnalysis};
+use crate::cst::NodeId;
+
+// __SLANG_DEFINITION_TYPES__ keep in sync with binder
+pub enum Definition {
+    Constant(ConstantDefinition),
+    Contract(ContractDefinition),
+    Enum(EnumDefinition),
+    EnumMember(Identifier),
+    Error(ErrorDefinition),
+    Event(EventDefinition),
+    Function(FunctionDefinition),
+    Import(PathImport),
+    ImportedSymbol(ImportDeconstructionSymbol),
+    Interface(InterfaceDefinition),
+    Library(LibraryDefinition),
+    Modifier(FunctionDefinition),
+    Parameter(Parameter),
+    StateVariable(StateVariableDefinition),
+    Struct(StructDefinition),
+    StructMember(StructMember),
+    TypeParameter(Parameter),
+    UserDefinedValueType(UserDefinedValueTypeDefinition),
+    Variable(VariableDeclarationStatement),
+    YulFunction(YulFunctionDefinition),
+    YulLabel(YulLabel),
+    YulParameter(YulIdentifier),
+    YulVariable(YulIdentifier),
+}
+
+impl Definition {
+    pub(crate) fn create(definition_id: NodeId, semantic: &Rc<SemanticAnalysis>) -> Self {
+        let definition = semantic
+            .binder()
+            .find_definition_by_id(definition_id)
+            .expect("definition_id references a definition node");
+
+        match definition {
+            binder::Definition::Constant(constant_definition) => Self::Constant(
+                create_constant_definition(&constant_definition.ir_node, semantic),
+            ),
+            binder::Definition::Contract(contract_definition) => Self::Contract(
+                create_contract_definition(&contract_definition.ir_node, semantic),
+            ),
+            binder::Definition::Enum(enum_definition) => {
+                Self::Enum(create_enum_definition(&enum_definition.ir_node, semantic))
+            }
+            binder::Definition::EnumMember(enum_member_definition) => {
+                Self::EnumMember(create_identifier(&enum_member_definition.ir_node, semantic))
+            }
+            binder::Definition::Error(error_definition) => {
+                Self::Error(create_error_definition(&error_definition.ir_node, semantic))
+            }
+            binder::Definition::Event(event_definition) => {
+                Self::Event(create_event_definition(&event_definition.ir_node, semantic))
+            }
+            binder::Definition::Function(function_definition) => Self::Function(
+                create_function_definition(&function_definition.ir_node, semantic),
+            ),
+            binder::Definition::Import(import_definition) => {
+                Self::Import(create_path_import(&import_definition.ir_node, semantic))
+            }
+            binder::Definition::ImportedSymbol(imported_symbol_definition) => Self::ImportedSymbol(
+                create_import_deconstruction_symbol(&imported_symbol_definition.ir_node, semantic),
+            ),
+            binder::Definition::Interface(interface_definition) => Self::Interface(
+                create_interface_definition(&interface_definition.ir_node, semantic),
+            ),
+            binder::Definition::Library(library_definition) => Self::Library(
+                create_library_definition(&library_definition.ir_node, semantic),
+            ),
+            binder::Definition::Modifier(modifier_definition) => Self::Modifier(
+                create_function_definition(&modifier_definition.ir_node, semantic),
+            ),
+            binder::Definition::Parameter(parameter_definition) => {
+                Self::Parameter(create_parameter(&parameter_definition.ir_node, semantic))
+            }
+            binder::Definition::StateVariable(state_variable_definition) => Self::StateVariable(
+                create_state_variable_definition(&state_variable_definition.ir_node, semantic),
+            ),
+            binder::Definition::Struct(struct_definition) => Self::Struct(
+                create_struct_definition(&struct_definition.ir_node, semantic),
+            ),
+            binder::Definition::StructMember(struct_member_definition) => Self::StructMember(
+                create_struct_member(&struct_member_definition.ir_node, semantic),
+            ),
+            binder::Definition::TypeParameter(type_parameter_definition) => Self::TypeParameter(
+                create_parameter(&type_parameter_definition.ir_node, semantic),
+            ),
+            binder::Definition::UserDefinedValueType(user_defined_value_type_definition) => {
+                Self::UserDefinedValueType(create_user_defined_value_type_definition(
+                    &user_defined_value_type_definition.ir_node,
+                    semantic,
+                ))
+            }
+            binder::Definition::Variable(variable_definition) => Self::Variable(
+                create_variable_declaration_statement(&variable_definition.ir_node, semantic),
+            ),
+            binder::Definition::YulFunction(yul_function_definition) => Self::YulFunction(
+                create_yul_function_definition(&yul_function_definition.ir_node, semantic),
+            ),
+            binder::Definition::YulLabel(yul_label_definition) => {
+                Self::YulLabel(create_yul_label(&yul_label_definition.ir_node, semantic))
+            }
+            binder::Definition::YulParameter(yul_parameter_definition) => Self::YulParameter(
+                create_yul_identifier(&yul_parameter_definition.ir_node, semantic),
+            ),
+            binder::Definition::YulVariable(yul_variable_definition) => Self::YulVariable(
+                create_yul_identifier(&yul_variable_definition.ir_node, semantic),
+            ),
+        }
+    }
+
+    pub fn references(&self) -> Vec<Reference> {
+        match self {
+            Definition::Constant(constant_definition) => constant_definition.references(),
+            Definition::Contract(contract_definition) => contract_definition.references(),
+            Definition::Enum(enum_definition) => enum_definition.references(),
+            Definition::EnumMember(identifier) => identifier.references(),
+            Definition::Error(error_definition) => error_definition.references(),
+            Definition::Event(event_definition) => event_definition.references(),
+            Definition::Function(function_definition) => function_definition.references(),
+            Definition::Import(path_import) => path_import.references(),
+            Definition::ImportedSymbol(import_deconstruction_symbol) => {
+                import_deconstruction_symbol.references()
+            }
+            Definition::Interface(interface_definition) => interface_definition.references(),
+            Definition::Library(library_definition) => library_definition.references(),
+            Definition::Modifier(function_definition) => function_definition.references(),
+            Definition::Parameter(parameter) => parameter.references(),
+            Definition::StateVariable(state_variable_definition) => {
+                state_variable_definition.references()
+            }
+            Definition::Struct(struct_definition) => struct_definition.references(),
+            Definition::StructMember(struct_member) => struct_member.references(),
+            Definition::TypeParameter(parameter) => parameter.references(),
+            Definition::UserDefinedValueType(user_defined_value_type_definition) => {
+                user_defined_value_type_definition.references()
+            }
+            Definition::Variable(variable_declaration_statement) => {
+                variable_declaration_statement.references()
+            }
+            Definition::YulFunction(yul_function_definition) => {
+                yul_function_definition.references()
+            }
+            Definition::YulLabel(yul_label) => yul_label.references(),
+            Definition::YulParameter(identifier) => identifier.references(),
+            Definition::YulVariable(identifier) => identifier.references(),
+        }
+    }
+}
+
+macro_rules! define_references_method {
+    ($type:ident) => {
+        paste! {
+            impl [<$type Struct>] {
+                pub fn references(&self) -> Vec<Reference> {
+                    self.semantic.references_binding_to(self.ir_node.node_id)
+                }
+            }
+        }
+    };
+}
+
+define_references_method!(ConstantDefinition);
+define_references_method!(ContractDefinition);
+define_references_method!(EnumDefinition);
+define_references_method!(ErrorDefinition);
+define_references_method!(EventDefinition);
+define_references_method!(FunctionDefinition);
+define_references_method!(ImportDeconstructionSymbol);
+define_references_method!(InterfaceDefinition);
+define_references_method!(LibraryDefinition);
+define_references_method!(Parameter);
+define_references_method!(PathImport);
+define_references_method!(StateVariableDefinition);
+define_references_method!(StructDefinition);
+define_references_method!(StructMember);
+define_references_method!(UserDefinedValueTypeDefinition);
+define_references_method!(VariableDeclarationStatement);
+define_references_method!(YulLabel);
+define_references_method!(YulFunctionDefinition);