Add Architektur & Struktur

Architektur-%26-Struktur.md

@@ -0,0 +1,64 @@
+# 🏗️ Architektur & Struktur
+
+Diese Seite richtet sich an Entwickler (und an das zukünftige Ich), die den Quellcode der **BMC TPL Code All around** Extension verstehen, erweitern oder debuggen möchten. 
+
+Die Erweiterung nutzt die native Visual Studio Code Extension API und verzichtet bewusst auf einen schweren, externen Language Server, um maximale Performance und einfache Wartbarkeit zu garantieren.
+
+---
+
+## 📂 Projektstruktur (Ziel-Architektur)
+
+Um den Code wartbar zu halten und nicht alles in wenige, riesige Dateien zu packen, folgt das Projekt dieser logischen Modul-Struktur:
+
+\`\`\`text
+src/
+├── core/
+│   └── TplLinter.ts           # Kernlogik des Syntax-Scanners und State-Trackings
+├── providers/
+│   ├── TplCompletionProvider.ts  # Autovervollständigung & Snippets
+│   ├── TplHoverProvider.ts       # Tooltips und DocString-Parsing
+│   ├── TplDocumentFormatter.ts   # Auto-Formatierung & Visual Alignment
+│   └── TplCodeActionProvider.ts  # Quick Fixes (Glühbirne)
+├── data/
+│   └── TplBuiltIns.ts         # Statische BMC-Dokumentationen und Snippet-Strukturen
+├── utils/
+│   ├── DocStringExtractor.ts  # Hilfsfunktionen zum Parsen von Multiline-Kommentaren
+│   └── RegexHelpers.ts        # Zentrale Reguläre Ausdrücke für das Projekt
+└── extension.ts               # Entry-Point der Extension (Registrierung der Module)
+\`\`\`
+
+---
+
+## ⚙️ Die Kernkomponenten
+
+Wie arbeiten die Teile zusammen? Hier ist der Workflow der wichtigsten Module:
+
+### 1. Entry Point (`extension.ts`)
+Dies ist der Dreh- und Angelpunkt. Die `activate`-Funktion wird von VS Code aufgerufen, sobald eine `.tpl` Datei geöffnet wird. Sie erledigt zwei Dinge:
+1. **Event-Listener binden:** Lauscht auf das Öffnen von Dokumenten (`onDidOpenTextDocument`), Änderungen am Code (`onDidChangeTextDocument`) und Anpassungen an den Einstellungen (`onDidChangeConfiguration`).
+2. **Provider registrieren:** Meldet dem VS Code-Editor, welche Klassen für Hover, Autocomplete und Formatierung zuständig sind.
+
+### 2. Der Linter / Scanner (`core/TplLinter.ts`)
+Das Herzstück der Code-Analyse. Es handelt sich um einen zeilenbasierten, zustandsbehafteten (stateful) Scanner.
+* **State Tracking:** Der Linter merkt sich Variablen über Zeilengrenzen hinweg (z.B. `inConditionBlock`, `parenStack`), um zu wissen, ob ein `=` als Vergleich oder fehlerhafte Zuweisung gewertet werden muss.
+* **Diagnostics:** Findet der Scanner einen Fehler, erzeugt er eine `vscode.Diagnostic` (die roten oder gelben Kringel im Editor) und übergibt sie an die `DiagnosticCollection`.
+
+### 3. Autovervollständigung (`providers/TplCompletionProvider.ts`)
+Dieser Provider feuert bei jedem Tastendruck oder via `Ctrl + Space`.
+* **Regelwerk:** Er analysiert den Text *vor* dem Cursor (`linePrefix`).
+* **Kontext:** Endet die Zeile auf einen Punkt (z.B. `discovery.`), wird das dynamische `TplBuiltIns` Objekt durchsucht und die passenden Parameter-Überladungen als Snippets generiert.
+* **Dynamik:** Zieht sich für das `tpl_skeleton`-Snippet live die VS Code Workspace-Konfigurationen (Author, Publisher etc.).
+
+### 4. Tooltips (`providers/TplHoverProvider.ts`)
+Reagiert, wenn die Maus über einem Wort stehen bleibt.
+* Er greift das Wort (inkl. Namespace-Punkten) unter dem Cursor ab.
+* Entweder schlägt er den Namen in den statischen BMC-Daten (`data/TplBuiltIns.ts`) nach und rendert die Markdown-Beschreibung.
+* Oder er durchsucht das aktuelle/importierte Dokument nach der Definition und extrahiert den zugehörigen `"""`-DocString aus dem Code.
+
+---
+
+## 🔄 Lifecycle-Management
+
+Das Plugin ist ressourcenschonend konzipiert:
+* Der Linter analysiert den Code **on-the-fly** im Arbeitsspeicher, ohne Dateien auf die Festplatte schreiben zu müssen.
+* Einstellungen (Settings) werden beim Tippen live geladen. Ein Neustart des Editors ist bei Konfigurationsänderungen nicht notwendig.