feat: Document AST node structure across compiler stages

Add a new Markdown document detailing the AST node structure as it evolves through the compiler's different stages. This includes a diagram illustrating the data flow and relationships between the generic `Node<K, T>` structure and its specialized forms (`UntypedNode`, `BoundNode`, `TypedNode`, `AnalyzedNode`). The document explains the `kind` and `ty` payloads for each stage and their significance. Also removes a deleted file related to a previous optimization plan and adds new files for future optimization plans.
2026-02-27 08:58:38 +01:00
parent e104e7f59b
commit 83324a1892
5 changed files with 249 additions and 55 deletions
@@ -0,0 +1,118 @@
+# 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`)