feat(AST): Define complete set of AST nodes

Signed-off-by: erick-alcachofa <erick@artichoke.dev>

Introduces the comprehensive header file for the Abstract Syntax Tree,
providing the foundational structures for the parser and subsequent
compiler stages.

This initial version defines all node types required to represent the
language's grammar, including:
- Top-level program structure and module declarations.
- All statement types, including control flow, loops, and deferrals.
- A semantic expression tree designed for a Pratt parser (Unary, Binary,
  Function Calls, etc.).
- A robust, recursive type system for handling complex type signatures.

The design employs modern C++ for safety and clarity:
- `std::unique_ptr` establishes clear ownership of child nodes.
- `std::variant` provides type-safe polymorphism for Statement,
  Expression, and Declaration nodes.
- `std::optional` is used to accurately model optional grammar rules.
- `SourceLocation` is included in every node to support detailed error
  reporting.

lib/include/artichoke/Parser/AST/Node.hpp

@@ -0,0 +1,580 @@
+#pragma once
+
+#include <vector>
+#include <memory>
+#include <variant>
+#include <optional>
+
+namespace arti::lang::ast {
+
+  struct SourceLocation {
+    std::size_t line;
+    std::size_t column;
+  };
+
+  namespace node {
+    template <typename T>
+    using Ptr = std::unique_ptr<T>;
+
+    template <typename T>
+    using Opt = std::optional<T>;
+
+    enum class Mutability {
+      Mutable,
+      Constant,
+    };
+
+    enum class TypeQualifier {
+      Pointer,
+      Slice,
+      Mutable,
+      Optional,
+    };
+
+    enum class UnaryOperator {
+      Not,
+      Minus,
+      BitNot,
+      Ampersand,
+      Star,
+    };
+
+    enum class BinaryOperator {
+      Equal,
+      NotEqual,
+      GreaterThan,
+      LessThan,
+      GreaterEqual,
+      LessEqual,
+    };
+
+    enum class CompoundAssignType {
+      Addition,
+      Substraction,
+      Multiplication,
+      Division,
+      Modulo,
+      BitAnd,
+      BitOr,
+      LeftShift,
+      RightShift,
+      BoolAnd,
+      BoolOr,
+    };
+
+    /* -------- Nodes Forward Declarations -------- */
+    struct Module;
+    struct Struct;
+    struct Enum;
+    struct Function;
+    struct ImportStatement;
+    struct AliasStatement;
+    struct GenericParam;
+    struct FunctionParam;
+    struct StructMember;
+    struct EnumMember;
+    struct CodeBlock;
+    struct VariableDeclaration;
+    struct IfStatement;
+    struct ElseStatement;
+    struct DeferStatement;
+    struct ErrDeferStatement;
+    struct ReturnStatement;
+    struct BreakStatement;
+    struct ContinueStatement;
+    struct MatchStatement;
+    struct SwitchStatement;
+    struct CForStatement;
+    struct RangeForStatement;
+    struct WhileStatement;
+    struct DoWhileStatement;
+    struct InfLoopStatement;
+    struct ExpressionStatement;
+    struct MatchCase;
+    struct SwitchCase;
+    struct Type;
+    struct SimpleTypeExpression;
+    struct GenericTypeExpression;
+    struct AccessTypeExpression;
+    struct NamespacedIdentifier;
+
+    struct UnaryExpression;
+    struct BinaryExpression;
+
+    struct AssignExpression;
+    struct CompoundAssignExpression;
+    struct FunctionCallExpression;
+    struct SliceAccessExpression;
+    struct SliceRangeExpression;
+    struct MemberAccessExpression;
+    struct ScopeAccessExpression;
+    struct PointerAccessExpression;
+    struct ReflectionExpression;
+    struct SliceCreationExpression;
+    struct SliceLengthExpression;
+    struct SlicePtrExpression;
+    struct IdentifierExpression;
+
+    struct StructNamedInit;
+    struct StructNamedFieldsInit;
+    struct StructExpressionsInit;
+
+    struct CharLiteral;
+    struct NullLiteral;
+    struct StringLiteral;
+    struct FloatLiteral;
+    struct IntegerLiteral;
+    struct BooleanLiteral;
+    struct StructLiteral;
+
+    /* -------- Nodes Definitions -------- */
+
+    /* Top Level & Declarations */
+
+    using Declaration = std::variant<
+      Ptr<Struct>,
+      Ptr<Enum>,
+      Ptr<Function>>;
+
+    using TopLevelDeclaration = std::variant<
+      Ptr<Module>,
+      Ptr<Struct>,
+      Ptr<Enum>,
+      Ptr<Function>,
+      Ptr<ImportStatement>,
+      Ptr<AliasStatement>>;
+
+    struct Module {
+      SourceLocation location;
+      bool isExported;
+      Ptr<NamespacedIdentifier> name;
+      std::vector<Ptr<Module>> childModules;
+      std::vector<Declaration> declarations;
+      std::vector<Ptr<AliasStatement>> aliasedElements;
+    };
+
+    struct ImportStatement {
+      SourceLocation location;
+      bool importAll;
+      Ptr<NamespacedIdentifier> target;
+    };
+
+    struct AliasStatement {
+      SourceLocation location;
+      std::string name;
+      Ptr<NamespacedIdentifier> aliased;
+    };
+
+    struct Function {
+      SourceLocation location;
+      bool isExported;
+      std::string name;
+      Ptr<Type> returnType;
+      Ptr<CodeBlock> body;
+      std::vector<Ptr<GenericParam>> generics;
+      std::vector<Ptr<FunctionParam>> params;
+    };
+
+    struct Struct {
+      SourceLocation location;
+      bool isExported;
+      std::string name;
+      std::vector<Ptr<GenericParam>> generics;
+      std::vector<Ptr<StructMember>> members;
+    };
+
+    struct Enum {
+      SourceLocation location;
+      bool isExported;
+      std::string name;
+      std::vector<Ptr<GenericParam>> generics;
+      std::vector<Ptr<EnumMember>> members;
+    };
+
+    struct GenericParam {
+      SourceLocation location;
+      std::string name;
+    };
+
+    struct FunctionParam {
+      SourceLocation location;
+      bool isThis;
+      std::string name;
+      Ptr<Type> type;
+    };
+
+    struct StructMember {
+      SourceLocation location;
+      std::string name;
+      Ptr<Type> type;
+    };
+
+    struct EnumMember {
+      SourceLocation location;
+      std::string name;
+      Ptr<Type> type;
+    };
+
+    /* Expression node types */
+
+    using Expression = std::variant<
+      Ptr<CharLiteral>,
+      Ptr<NullLiteral>,
+      Ptr<StringLiteral>,
+      Ptr<FloatLiteral>,
+      Ptr<IntegerLiteral>,
+      Ptr<BooleanLiteral>,
+      Ptr<StructLiteral>,
+      Ptr<IdentifierExpression>,
+      Ptr<UnaryExpression>,
+      Ptr<BinaryExpression>,
+      Ptr<AssignExpression>,
+      Ptr<CompoundAssignExpression>,
+      Ptr<FunctionCallExpression>,
+      Ptr<SliceAccessExpression>,
+      Ptr<SliceRangeExpression>,
+      Ptr<MemberAccessExpression>,
+      Ptr<ScopeAccessExpression>,
+      Ptr<PointerAccessExpression>,
+      Ptr<ReflectionExpression>,
+      Ptr<SliceCreationExpression>,
+      Ptr<SliceLengthExpression>,
+      Ptr<SlicePtrExpression>>;
+
+    using StructLiteralFields = std::variant<
+      Ptr<StructNamedFieldsInit>,
+      Ptr<StructExpressionsInit>>;
+
+    struct CharLiteral {
+      SourceLocation location;
+      uint8_t value;
+    };
+
+    struct NullLiteral {
+      SourceLocation location;
+    };
+
+    struct StringLiteral {
+      SourceLocation location;
+      std::string value;
+    };
+
+    struct FloatLiteral {
+      SourceLocation location;
+      double value;
+    };
+
+    struct IntegerLiteral {
+      SourceLocation location;
+      uint64_t value;
+    };
+
+    struct BooleanLiteral {
+      SourceLocation location;
+      bool value;
+    };
+
+    struct StructLiteral {
+      SourceLocation location;
+      Ptr<Type> type;
+      StructLiteralFields fields;
+    };
+
+    struct StructNamedInit {
+      SourceLocation location;
+      std::string name;
+      Ptr<Expression> initializer;
+    };
+
+    struct StructNamedFieldsInit {
+      std::vector<StructNamedInit> fields;
+    };
+
+    struct StructExpressionsInit { 
+      std::vector<SourceLocation> locations;
+      std::vector<Ptr<Expression>> initializers;
+    };
+
+    struct IdentifierExpression {
+      SourceLocation location;
+      std::string name;
+    };
+
+    struct UnaryExpression {
+      SourceLocation location;
+      UnaryOperator operatorT;
+      Ptr<Expression> right;
+    };
+
+    struct BinaryExpression {
+      SourceLocation location;
+      BinaryOperator operatorT;
+      Ptr<Expression> leftHs;
+      Ptr<Expression> rightHs;
+    };
+
+    struct AssignExpression {
+      SourceLocation location;
+      Ptr<Expression> leftHs;
+      Ptr<Expression> rightHs;
+    };
+
+    struct CompoundAssignExpression {
+      SourceLocation location;
+      CompoundAssignType type;
+      Ptr<Expression> leftHs;
+      Ptr<Expression> rightHs;
+    };
+
+    struct FunctionCallExpression {
+      SourceLocation location;
+      Ptr<Expression> callee;
+      std::vector<Ptr<Expression>> arguments;
+    };
+
+    struct SliceAccessExpression {
+      SourceLocation location;
+      Ptr<Expression> slice;
+      Ptr<Expression> index;
+    };
+
+    struct SliceRangeExpression {
+      SourceLocation location;
+      Ptr<Expression> slice;
+      Ptr<Expression> start;
+      Ptr<Expression> end;
+    };
+
+    struct MemberAccessExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+      std::string memberName;
+    };
+
+    struct ScopeAccessExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+      std::string memberName;
+      std::vector<Ptr<Type>> genericParams;
+    };
+
+    struct PointerAccessExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+      std::string memberName;
+    };
+
+    struct ReflectionExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+      Opt<std::string> attribute;
+    };
+
+    struct SliceCreationExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+      Ptr<Expression> length;
+    };
+
+    struct SliceLengthExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+    };
+
+    struct SlicePtrExpression {
+      SourceLocation location;
+      Ptr<Expression> object;
+    };
+
+    /* Statements */
+
+    using Statement = std::variant<
+      Ptr<VariableDeclaration>,
+      Ptr<IfStatement>,
+      Ptr<DeferStatement>,
+      Ptr<ErrDeferStatement>,
+      Ptr<ReturnStatement>,
+      Ptr<BreakStatement>,
+      Ptr<ContinueStatement>,
+      Ptr<AliasStatement>,
+      Ptr<MatchStatement>,
+      Ptr<SwitchStatement>,
+      Ptr<CForStatement>,
+      Ptr<RangeForStatement>,
+      Ptr<WhileStatement>,
+      Ptr<DoWhileStatement>,
+      Ptr<InfLoopStatement>,
+      Ptr<ExpressionStatement>>;
+
+    using ElseBranch = std::variant<
+      Ptr<ElseStatement>,
+      Ptr<IfStatement>>;
+
+    using Deferable = std::variant<
+      Ptr<Expression>,
+      Ptr<CodeBlock>>;
+
+    using PreLoopStatement = std::variant<
+      Ptr<VariableDeclaration>,
+      Ptr<Expression>>;
+
+    using TypeExpression = std::variant<
+      Ptr<SimpleTypeExpression>,
+      Ptr<GenericTypeExpression>,
+      Ptr<AccessTypeExpression>>;
+
+
+    struct CodeBlock {
+      SourceLocation location;
+      std::vector<Statement> statements;
+    };
+
+    struct VariableDeclaration {
+      SourceLocation location;
+      Mutability mutability;
+      std::string name;
+      Ptr<Type> type;
+      Ptr<Expression> initializer;
+    };
+
+    struct IfStatement {
+      SourceLocation location;
+      Opt<std::string> unwrappedVar;
+      Ptr<Expression> condition;
+      Ptr<CodeBlock> body;
+      Opt<ElseBranch> elseBranch;
+    };
+
+    struct ElseStatement {
+      SourceLocation location;
+      Opt<std::string> unwrappedVar;
+      Ptr<CodeBlock> body;
+    };
+
+    struct DeferStatement {
+      SourceLocation location;
+      Deferable body;
+    };
+
+    struct ErrDeferStatement {
+      SourceLocation location;
+      Deferable body;
+    };
+
+    struct ReturnStatement {
+      SourceLocation location;
+      Ptr<Expression> value;
+    };
+
+    struct BreakStatement {
+      SourceLocation location;
+      Opt<std::string> label;
+    };
+
+    struct ContinueStatement {
+      SourceLocation location;
+      Opt<std::string> label;
+    };
+
+    struct MatchStatement {
+      SourceLocation location;
+      Ptr<Expression> value;
+      std::vector<Ptr<MatchCase>> cases;
+      Ptr<CodeBlock> defaultCase;
+    };
+
+    struct SwitchStatement {
+      SourceLocation location;
+      Ptr<Expression> value;
+      std::vector<Ptr<SwitchCase>> cases;
+      Ptr<CodeBlock> defaultCase;
+    };
+
+    struct MatchCase {
+      SourceLocation location;
+      std::string identifier;
+      Ptr<Type> matchType;
+      Ptr<CodeBlock> body;
+    };
+
+    struct SwitchCase {
+      SourceLocation location;
+      Ptr<Expression> matchExpr;
+      Ptr<CodeBlock> body;
+    };
+
+    struct CForStatement {
+      SourceLocation location;
+      Ptr<PreLoopStatement> preLoop;
+      Ptr<Expression> condition;
+      Ptr<Expression> postLoop;
+      Ptr<CodeBlock> body;
+    };
+
+    struct RangeForStatement {
+      SourceLocation location;
+      Mutability varMutability;
+      std::string varName;
+      Ptr<Expression> range;
+      Ptr<CodeBlock> body;
+    };
+
+    struct WhileStatement {
+      SourceLocation location;
+      Opt<std::string> unwrappedVar;
+      Ptr<Expression> condition;
+      Ptr<CodeBlock> body;
+      Opt<ElseBranch> elseBranch;
+    };
+
+    struct DoWhileStatement {
+      SourceLocation location;
+      Ptr<CodeBlock> body;
+      Ptr<Expression> condition;
+    };
+
+    struct InfLoopStatement {
+      SourceLocation location;
+      Ptr<CodeBlock> body;
+    };
+
+    struct ExpressionStatement {
+      SourceLocation location;
+      Ptr<Expression> expression;
+    };
+
+    struct SimpleTypeExpression {
+      SourceLocation location;
+      Ptr<NamespacedIdentifier> name;
+    };
+
+    struct GenericTypeExpression { 
+      SourceLocation location;
+      TypeExpression baseType;
+      std::vector<Ptr<Type>> genericArgs;
+    };
+
+    struct AccessTypeExpression {
+      SourceLocation location;
+      TypeExpression baseType;
+      std::string memberName;
+    };
+
+    struct Type {
+      SourceLocation location;
+      std::vector<TypeQualifier> qualifiers;
+      TypeExpression expression;
+    };
+
+    struct NamespacedIdentifier {
+      SourceLocation location;
+      std::vector<std::string> identifierParts;
+    };
+
+  } // namespace node
+
+  struct AST {
+    std::vector<node::TopLevelDeclaration> declarations;
+  };
+
+} // namespace arti::lang::ast