bmc-tpl-code-all-around/README.md

BMC Discovery TPL - VS Code Extension

🌍 *🇺🇸 English * | 🇩🇪 Deutsch 🌍

🇺🇸 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 file for details.

---

🇩🇪 Deutsch

Verwandle deine BMC Discovery TPL-Entwicklung von reaktivem Scripting in proaktives Software Engineering.

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.

✨ Hauptfunktionen

🧠 Kontextsensitive IntelliSense

Die Extension liest nicht nur Text, sie versteht die logische Struktur deiner TPL-Patterns.

• 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).

• Namespace Support: Lokale definitions-Blöcke werden als saubere Namespaces verstanden und projektweit vorgeschlagen.

🌍 Workspace Indexing (Cross-File Support)

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.

• Intelligentes Hovering: Fährt man mit der Maus über importierte Methoden, wird der zugehörige DocString ("""...""") direkt aus der externen Datei als Tooltip geladen.

🛡️ Unbestechlicher Custom Linter

Ein hochgradig robuster Linter, der die Besonderheiten und Edge-Cases von TPL perfekt beherrscht.

• Strikte Ausführungszonen: Warnt sofort, wenn ausführbarer Code außerhalb gültiger Zonen (body, triggers, constants, definitions) platziert wird.

• Multi-Line Conditions: Vollständige Unterstützung für mehrzeilige if ... or ... then Konstrukte, ohne fehlerhafte Semikolon-Warnungen auszulösen.

• Stack-Tracking: Überwacht hierarchisch alle Kontrollstrukturen. Fehlende oder falsche end if;, end for; oder end while; Anweisungen leuchten sofort rot auf.

• 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-Datei.

© Thomas Wehnert (Kuro)