From bda2c0a069c3e6b277538aed07c1c154ba43d062 Mon Sep 17 00:00:00 2001 From: kuro Date: Thu, 15 Oct 2026 20:02:59 +0000 Subject: [PATCH] =?UTF-8?q?README.md=20geupdated,=20hat=20nun=20auch=20eng?= =?UTF-8?q?lische=20=C3=BCbersetzung?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 157 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 96 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index d6ccfea..a98c41a 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,119 @@ -# BMC TPL Code All-Around +# BMC Discovery TPL - VS Code Extension -**Linter, Auto-Formatter, IntelliSense und Hover-Dokumentationen für die BMC TPL (Template Language).** +🌍 [*🇺🇸 English *](#english) *| [ 🇩🇪 Deutsch](#deutsch)* 🌍 -Diese Visual Studio Code Erweiterung verwandelt deinen Editor in eine vollwertige Entwicklungsumgebung für BMC Discovery TPL-Skripte. Sie nimmt dir Tipparbeit ab, formatiert Code nach strengen Best Practices, verhindert Syntax-Fehler noch vor dem Deployment und versteht projektübergreifende Abhängigkeiten. +## 🇺🇸 English + +**Transform your BMC Discovery TPL development from reactive scripting into proactive software engineering.** + +Writing Topology Pattern Language (TPL) for BMC Discovery used to mean writing code blindly, uploading it, and hoping the appliance wouldn't throw a cryptic error upon activation. This extension changes everything. It acts as a full-fledged Language Server tailored specifically for TPL, catching syntax errors and logic flaws *before* your code ever touches the server. + +### ✨ Key Features + +#### 🧠 Context-Aware IntelliSense + +The extension understands the logical structure of your TPL patterns. + +* **Zone Strictness:** You will only get code suggestions that are valid in your current block. No `if` statements in `metadata`, no `metadata` fields in the `body`. + +* **Smart Completion:** Completing a local method (e.g., `my_tools.doWork`) automatically inserts parentheses and a semicolon, placing your cursor perfectly for parameters (`$0`). + +* **Namespace Support:** Local `definitions` blocks are parsed as clean namespaces. + +#### 🌍 Workspace Indexing (Cross-File Support) + +Break the boundaries of single-file editing. The extension asynchronously indexes your entire workspace. + +* **Cross-File Imports:** Resolves `from Module import Definition` on the fly. External methods are immediately available in your autocomplete list. + +* **Intelligent Hover:** Hovering over imported methods fetches and displays the DocString (`"""..."""`) from the external file. + +#### 🛡️ Unforgiving Custom Linter + +A highly robust linter built to understand TPL's unique quirks and edge cases. + +* **Execution Zone Enforcement:** Instantly warns if executable code or assignments are placed outside valid zones (`body`, `triggers`, `constants`, `definitions`). + +* **Multi-Line Conditions:** Fully supports complex `if ... or ... then` constructs without throwing false semicolon errors. + +* **Stack-Tracking:** Monitors your control structures. Missing or mismatched `end if;`, `end for;`, or `end while;` tags are flagged immediately. + +* **URL/String Immunity:** Slashes (`//`) or semicolons inside strings and URLs will not break the comment or syntax parser. + +#### ✅ Developer Ergonomics & Workflow + +* **Workspace Scanning:** Run the `TPL: Scan Workspace` command to lint your entire project at once. All issues appear in VS Code's native "Problems" tab. + +* **Native TODO Tracking:** Comments containing `TODO:` are automatically indexed as blue "Information" hints in the Problems tab for easy navigation. + +* **Quick Fixes:** Missing mandatory metadata (like `author`, `tree_path`)? Click the lightbulb icon to generate the missing fields perfectly inside the block. + +### 🚀 Roadmap + +* **1-Click Test Deployment:** Integration of the BMC Helix REST API to push and activate patterns directly to a test appliance via VS Code. + +* **CI/CD Pipeline Integration:** A headless CLI version of the linter to block bad code in Git Merge Requests, enabling fully automated production deployments. + +### 📄 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- -## ✨ Features +## 🇩🇪 Deutsch -### 🤖 Intelligenter Linter (Syntax-Scanner) -Der Linter analysiert den Code in Echtzeit, merkt sich Zustände über Zeilenumbrüche hinweg und warnt vor typischen TPL-Fehlern: -* **Strikte Hierarchie-Prüfung:** Überwacht die korrekte Reihenfolge der Blöcke innerhalb von Patterns und Syncmappings (`metadata` -> `overview` -> `constants` -> `triggers` -> `mapping`/`removal` -> `body`). -* **Smarter Zuweisungs-Check:** Findet fehlende Semikolons (toleriert sie aber in `enumeration`-Blöcken oder bei umgebrochenen Code-Zeilen). Warnt streng mit einem Fehler, wenn `=` anstelle von `:=` für Variablenzuweisungen genutzt wird (außerhalb von legitimen `if`/`where` Vergleichen). -* **Block- & Klammer-Tracking:** Erkennt nicht geschlossene Blöcke (wie fehlende `end body;` oder `end pattern;`) und findet ungeschlossene runde `(` oder eckige `[` Klammern. -* **Pflichtfeld-Validierung:** Prüft, ob auf Modul-Ebene zwingend benötigte Metadaten (`origin`, `author`, `products`, `publishers`, `tree_path`) vorhanden sind und ob im `body` ein initiales `log.debug` Statement steht. -* **Versions-Prüfung:** Gleicht die im Modul deklarierte TPL-Version mit der in deinen Settings definierten Version ab und warnt vor veralteten Skripten. +**Verwandle deine BMC Discovery TPL-Entwicklung von reaktivem Scripting in proaktives Software Engineering.** -### ⚙️ Konfigurierbare Plugin-Einstellungen (Settings) -Personalisiere das Plugin direkt über die VS Code Benutzeroberfläche (File > Preferences > Settings > Extensions > BMC TPL Einstellungen): -* **Standard Metadaten:** Hinterlege deine eigenen Werte für `Author`, `Publisher`, `Origin` und den `Tree Path`. Diese werden beim Generieren neuer Module automatisch eingesetzt. -* **TPL Zielversion:** Definiere die TPL-Version (z.B. `23` für 1.23), für die du standardmäßig entwickelst. -* **Live-Reload:** Änderungen an den Einstellungen greifen sofort, ganz ohne Neustart des Editors. +Bisher glich das Schreiben von Topology Pattern Language (TPL) oft einem Blindflug: Code tippen, manuell hochladen und hoffen, dass die Appliance bei der Aktivierung keinen kryptischen Fehler wirft. Diese Extension ändert alles. Sie verhält sich wie ein maßgeschneiderter Language Server für TPL, der Syntax- und Logikfehler abfängt, *bevor* der Code den Server überhaupt berührt. -### 🎨 Auto-Formatter & Visual Alignment (`Shift + Alt + F`) -Schluss mit kaputten Einrückungen! Der Formatter bringt deinen Code in Bestform: -* **VS Code Standard:** Erzwingt strikt 4 Leerzeichen pro Einrückungs-Ebene. -* **Dynamische Block-Einrückung:** Erkennt automatisch startende und endende Blöcke (`if`, `for`, `pattern`, `table` etc.) und passt die Einrückungsebene an. -* **Klammer-Gedächtnis (Visual Alignment):** Die Königsdisziplin! Der Formatter merkt sich die spaltengenaue Position von geöffneten Arrays `[` oder Funktionsaufrufen `(` und richtet alle Folgezeilen makellos an dieser Klammer aus. +### ✨ Hauptfunktionen -### 💡 IntelliSense & Autovervollständigung (Cross-File) -Spart extrem viel Zeit beim Coden durch massives Kontext-Wissen: -* **Volle BMC Standard-Bibliothek:** Nahtlose Integration aller Built-In Funktionen (z.B. `discovery`, `number`, `text`, `model`). Unterstützt Parameter-Überladungen (z.B. `number.toText` wahlweise mit oder ohne Basis) per Tab-Navigation. -* **Workspace-Scanning:** Importierst du ein Modul (z.B. `from company.helpers import my_helper`), durchsucht das Plugin im Hintergrund dein gesamtes Projekt. Tippst du `my_helper.`, werden dir automatisch alle verfügbaren `define`-Methoden vorgeschlagen. -* **Lokale Namespaces:** Erkennt `definitions`-Blöcke in der gleichen Datei und schlägt deren Methoden vor. -* **Variablen-Tracking:** Lernt alle Variablen, die du mit `:=` definiert hast, und schlägt sie dir später vor. +#### 🧠 Kontextsensitive IntelliSense -### 🔍 Hover-Dokumentation (Tooltips) -Wenn du mit der Maus über einem Methodennamen, einem Pattern oder einer Tabelle stehen bleibst: -* **Offizielle BMC Doku:** Volle Integration der originalen, mehrzeiligen BMC Dokumentationen für alle eingebauten Funktionen (kein Browser mehr nötig!). -* **DocString Extraction:** Liest eigene Multi-Line-Kommentare (`"""` oder `'''`) aus, die unter `define` oder `pattern` Deklarationen stehen, und rendert sie als saubere Markdown-Tooltips (auch projektübergreifend!). +Die Extension liest nicht nur Text, sie versteht die logische Struktur deiner TPL-Patterns. -### ⚡ Quick Fixes (Code Actions / Glühbirne) -Bietet sofortige Reparaturoptionen mit einem Klick: -* **"Fehlende Modul-Metadaten einfügen":** Generiert sofort alle 5 Pflichtfelder im Modul-Metadata-Block. -* **"Log-Statement einfügen":** Baut das fehlende `log.debug("Start pattern...");` direkt am Anfang des `body`-Blocks ein. -* **"Tabs zu Spaces":** Ersetzt sofort alle illegalen Tabs (`\t`) in einer Zeile durch jeweils 4 korrekte Leerzeichen. +* **Strikte Zonen:** Vorschläge gibt es nur dort, wo sie erlaubt sind. Keine `if`-Schleifen im `metadata`-Block, keine Metadaten-Felder im `body`. ---- +* **Smart Completion:** Bei der Autovervollständigung von Methoden (z.B. `my_tools.doWork`) werden Klammern und Semikolon automatisch generiert und der Cursor optimal platziert (`$0`). -## 🚀 Snippets (Code-Vorlagen) +* **Namespace Support:** Lokale `definitions`-Blöcke werden als saubere Namespaces verstanden und projektweit vorgeschlagen. -Einfach das Keyword tippen und `Enter` drücken, um komplette, perfekt eingerückte Blöcke zu generieren: +#### 🌍 Workspace Indexing (Cross-File Support) -| Keyword | Beschreibung | -| :--- | :--- | -| `tpl_skeleton` | **God-Snippet**: Generiert ein komplett frisches TPL Modul. Nutzt automatisch deine hinterlegten Settings für Metadaten und Version. | -| `pattern` / `syncmapping` | Baut einen leeren Pattern/Syncmapping-Block inklusive DocString und End-Tag. | -| `define` | Generiert eine Methodendefinition (`define name(params) ... end define;`). | -| `metadata`, `overview`, `body`... | Baut den jeweiligen Block auf und platziert den Cursor in der Mitte. | -| `table` | Erstellt eine Tabelle inklusive des `default -> "unknown";` Fallbacks. | -| `if`, `elif`, `else` | Baut bedingte Abfragen inkl. `then` und `end if;` und platziert den Cursor sauber bei der Bedingung. | -| `for`, `while` | Baut Standard-Schleifen inkl. `do` und End-Tag und lässt dich direkt iterieren. | +Die Extension durchbricht die Grenzen einzelner Dateien und scannt asynchron das gesamte Projekt. ---- +* **Cross-File Imports:** Versteht `from Modul import Definition`. Methoden aus anderen Dateien stehen sofort in der Autovervollständigung bereit. -## 🛠️ Installation & Nutzung +* **Intelligentes Hovering:** Fährt man mit der Maus über importierte Methoden, wird der zugehörige DocString (`"""..."""`) direkt aus der externen Datei als Tooltip geladen. -1. Das Plugin aktivieren. (Von den Releases das neueste herunterladen und einfach die `.vsix` Datei in die Add-ons von Visual Studio Code ziehen). -2. In einem Projekt mit TPL Dateien eine davon öffnen und die Analyse durchlaufen lassen. -3. Der Linter startet automatisch bei jedem Tastendruck. -4. **Formatieren:** Rechtsklick -> *Dokument formatieren* (oder `Shift + Alt + F`). -5. **Autovervollständigung:** Triggert automatisch beim Tippen, speziell nach einem Punkt (`.`) bei Modul-Aufrufen. -6. **Quick Fixes:** Auf die gelbe/rote Glühbirne am Zeilenanfang klicken oder `Ctrl + .` (Windows/Linux) / `Cmd + .` (Mac) drücken. +#### 🛡️ Unbestechlicher Custom Linter ---- +Ein hochgradig robuster Linter, der die Besonderheiten und Edge-Cases von TPL perfekt beherrscht. -## 📜 Lizenz +* **Strikte Ausführungszonen:** Warnt sofort, wenn ausführbarer Code außerhalb gültiger Zonen (`body`, `triggers`, `constants`, `definitions`) platziert wird. -Dieses Projekt ist unter der **MIT License** lizenziert. +* **Multi-Line Conditions:** Vollständige Unterstützung für mehrzeilige `if ... or ... then` Konstrukte, ohne fehlerhafte Semikolon-Warnungen auszulösen. -Copyright (c) 2026 Thomas Wehnert +* **Stack-Tracking:** Überwacht hierarchisch alle Kontrollstrukturen. Fehlende oder falsche `end if;`, `end for;` oder `end while;` Anweisungen leuchten sofort rot auf. -Jedem, der eine Kopie dieser Software erhält, wird hiermit kostenlos die Erlaubnis erteilt, ohne Einschränkung mit der Software zu handeln, einschließlich und ohne Einschränkung der Rechte zur Nutzung, zum Kopieren, Ändern, Zusammenführen, Veröffentlichen, Verteilen, Unterlizenzieren und/oder Verkaufen von Kopien der Software, sofern der obige Urheberrechtshinweis und dieser Genehmigungshinweis in allen Kopien oder wesentlichen Teilen der Software enthalten sind. Die Software wird "ohne Mängelgewähr" (as is) zur Verfügung gestellt. \ No newline at end of file +* **URL/String Immunität:** Komplexere Strings (inklusive URLs mit `//` oder Semikolons) bringen den Parser nicht mehr aus dem Tritt. + +#### ✅ Entwickler-Ergonomie & Workflow + +* **Workspace Scanning:** Mit dem Befehl `TPL: Gesamten Workspace prüfen` lässt sich das komplette Projekt auf einen Schlag durchleuchten. Alle Fehler landen übersichtlich im VS Code "Probleme"-Tab. + +* **Natives TODO-Tracking:** Kommentare mit `TODO:` werden automatisch erfasst und als blaue Info-Links im Probleme-Tab indiziert. + +* **Quick Fixes:** Fehlen Pflicht-Metadaten (wie `author`, `tree_path`), lassen sich diese per Klick auf das Glühbirnen-Symbol (Code Action) automatisch an der richtigen Stelle generieren. + +### 🚀 Roadmap + +* **1-Klick Test Deployment:** Integration der BMC Helix REST API, um Patterns direkt aus VS Code auf eine Test-Appliance zu pushen. + +* **CI/CD Pipeline Integration:** Eine "Headless"-Version des Linters für GitLab/GitHub, um fehlerhaften Code in Merge Requests zu blockieren und vollautomatisierte Deployments für die Produktion zu ermöglichen. + +### 📄 Lizenz + +Dieses Projekt ist unter der MIT-Lizenz lizenziert – weitere Details finden sich in der [LICENSE](LICENSE)-Datei. + +**© Thomas Wehnert (Kuro)** \ No newline at end of file