# AST Node-Struktur über Compiler-Stages

Dieses Dokument beschreibt die Architektur der AST-Knoten (Abstract Syntax Tree) über die verschiedenen Phasen des Compilers hinweg. Die Rust-Implementierung nutzt eine generische `Node<K, T>` Struktur, die in jeder Phase strikt typisiert wird, um Fehlerklassen der ursprünglichen Delphi-Architektur zu vermeiden.

## Architektur & Datenfluss

Der Compiler verarbeitet den AST in mehreren Stufen. Statt die Knoten in-place zu mutieren, erzeugt jede Phase einen neuen, typsicheren und spezialisierten Baum.

```mermaid
classDiagram
    direction TB
    
    class Node~K,T~ {
        +Identity identity
        +K kind
        +T ty
    }
    
    class UntypedKind {
        <<enumeration>>
        Identifier(Symbol)
        Parameter(Symbol)
        Def(Target, Value)
        Assign(Target, Value)
        MacroDecl(...)
        Template(...)
        Splice(...)
        ...
    }
    
    class BoundKind~T~ {
        <<enumeration>>
        Get(Address, Symbol)
        Set(Address, Value)
        Define(Symbol, Address, Kind, Value, Captures)
        GetField(Record, Keyword)
        Destructure(Pattern, Value)
        Lambda(Params, Upvalues, Body)
        ...
    }
    
    class StaticType {
        <<struct>>
        // Type Information
    }
    
    class NodeMetrics {
        <<struct>>
        +Rc~TypedNode~ original
        +Purity purity
        +bool is_recursive
    }

    %% Typedefs und Spezialisierungen
    class UntypedNode {
        <<type alias>>
        Node~UntypedKind, ()~
    }
    
    class BoundNode {
        <<type alias>>
        Node~BoundKind~()~, ()~
    }
    
    class TypedNode {
        <<type alias>>
        Node~BoundKind~StaticType~, StaticType~
    }
    
    class AnalyzedNode {
        <<type alias>>
        Node~BoundKind~NodeMetrics~, NodeMetrics~
    }

    Node <|-- UntypedNode : binds
    UntypedNode *-- UntypedKind : uses
    
    Node <|-- BoundNode : binds
    BoundNode *-- BoundKind : uses
    
    Node <|-- TypedNode : binds
    TypedNode *-- StaticType : uses T
    TypedNode *-- BoundKind : uses K
    
    Node <|-- AnalyzedNode : binds
    AnalyzedNode *-- NodeMetrics : uses T
    AnalyzedNode *-- BoundKind : uses K

    %% Phasen-Übergänge
    UntypedNode ..> BoundNode : Parser & Binder
(Namensauflösung)
    BoundNode ..> TypedNode : TypeChecker
(Typ-Inferenz)
    TypedNode ..> AnalyzedNode : Analyzer
(Purity, Rekursion)
```

## Compiler Stages im Detail

1. **Parser (Untyped AST)**
   * **Typ:** `Node<UntypedKind, ()>` (Alias: Keiner, direkt genutzt)
   * **Beschreibung:** Der vom Parser erstellte Roh-Baum. Bezeichner (`Identifier`, `Def`, `Assign`) sind lediglich Namen (Symbols). Beinhaltet Strukturen für das Macro-System (`MacroDecl`, `Template`, `Splice`).
   * **Payload (`T`):** `()` (Keine Metadaten)

2. **Binder (Bound AST)**
   * **Typ:** `BoundNode<()>` bzw. `Node<BoundKind<()>, ()>`
   * **Beschreibung:** Namensauflösung und Scope-Analyse wurden durchgeführt. Namen wurden in physische Adressen (`Address`: `LocalSlot`, `UpvalueIdx`, `GlobalIdx`) überführt. Neue Knoten wie `Get`, `Set`, `Define` lösen die untypisierten Varianten ab. Closures kennen nun ihre `Upvalues` (gefangene Variablen). Macros wurden vollständig expandiert.
   * **Payload (`T`):** `()`

3. **Type Checker (Typed AST)**
   * **Typ:** `TypedNode` bzw. `Node<BoundKind<StaticType>, StaticType>`
   * **Beschreibung:** Statische Typprüfung. Die Kern-Struktur (`BoundKind`) bleibt erhalten, aber jeder Knoten trägt nun seinen verifizierten statischen Typ (`StaticType`) in der Eigenschaft `ty`.
   * **Payload (`T`):** `StaticType`

4. **Analyzer / Optimizer (Analyzed AST)**
   * **Typ:** `AnalyzedNode` bzw. `Node<BoundKind<NodeMetrics>, NodeMetrics>`
   * **Beschreibung:** Vorbereitung für die Optimierung. Sammelt wichtige Metadaten pro Knoten für den Optimizer.
   * **Payload (`T`):** `NodeMetrics` (enthält Metadaten wie `Purity` (Ist der Knoten seiteneffektfrei?), `is_recursive` sowie eine Referenz auf den originalen `TypedNode`)