Dieser Post setzt den achten Teil fort. bausteinsicht validate und bausteinsicht lint prüfen das Modell auf der Kommandozeile. Noch besser: Fehler direkt im Editor sehen — beim Tippen, ohne den Terminal zu verlassen. Das ermöglicht das Language Server Protocol.

Was ist LSP?

Das Language Server Protocol (LSP) ist ein offener Standard von Microsoft. Ein Language Server läuft im Hintergrund und analysiert Quellcode (oder Konfigurationsdateien) — der Editor fragt ihn ab und zeigt die Ergebnisse an:

  • Rote Unterstreichungen bei Fehlern

  • Autovervollständigung für bekannte Werte

  • Hover-Informationen

  • CodeLens (kleine Infos über Zeilen)

Weil LSP ein Standard ist, funktioniert bausteinsicht-lsp mit jedem LSP-fähigen Editor: VS Code, Neovim, Emacs, Zed, IntelliJ.

bausteinsicht-lsp installieren

bausteinsicht-lsp ist ein separates Binary — es läuft als Hintergrundprozess, den der Editor startet:

# Via Go Install
go install github.com/docToolchain/Bausteinsicht/cmd/bausteinsicht-lsp@latest

# Via Release-Binary (Linux amd64)
curl -Lo bausteinsicht-lsp \
  https://github.com/docToolchain/Bausteinsicht/releases/latest/download/bausteinsicht-lsp_linux_amd64
chmod +x bausteinsicht-lsp && sudo mv bausteinsicht-lsp /usr/local/bin/

VS Code Einrichtung

Option A: VS Code Extension (empfohlen)

Die offizielle Bausteinsicht VS Code Extension installiert und konfiguriert den LSP automatisch:

  1. Extensions-Panel öffnen (Ctrl+Shift+X)

  2. Nach „Bausteinsicht" suchen

  3. Extension installieren

Die Extension aktiviert sich automatisch sobald eine *.jsonc-Datei geöffnet wird, die architecture im Dateinamen enthält.

Option B: Manuelle Konfiguration

Für andere Editoren oder manuelle Kontrolle: bausteinsicht-lsp über die LSP-Konfiguration des Editors registrieren.

VS Code settings.json:

{
  "languageServerExample.maxNumberOfProblems": 100,
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Oder via vscode-languageclient in einer Extension:

{
  "command": "bausteinsicht-lsp",
  "args": ["--stdio"],
  "filenamePattern": "*architecture*.jsonc"
}

Was der LSP bietet

Inline-Validierung

Der LSP ruft bausteinsicht validate --format json im Hintergrund auf und zeigt Fehler direkt als rote Unterstreichung im Editor:

"frontend": {
    "kind": "container",
    "children": { ... }  ← ⚠ Error: kind 'container' has container:false in specification
}

Fehlermeldungen erscheinen beim Hover über der markierten Stelle — ohne Terminal öffnen.

Severity-Stufen: * Error (rot): Strukturfehler, die validate blockieren * Warning (gelb): Warnungen aus lint (Constraint-Verstöße) * Info (blau): Hinweise (z.B. Element nicht in einer View sichtbar) * Hint (grau): Stil-Empfehlungen

CodeLens: Inline-Metadaten

Über jeder Element-Definition zeigt der LSP eine CodeLens-Zeile mit Metadaten:

"api": {
    "kind": "container",
    "title": "REST API",
    "status": "deployed"
}

Die CodeLens zeigt: * Element-Typ (kind) * Lifecycle-Status (status, wenn gesetzt) * Anzahl der Views, in denen das Element erscheint

Ein Klick auf die CodeLens öffnet das draw.io-Diagramm an der entsprechenden Stelle.

Validierung beim Speichern

Jedes Mal wenn architecture.jsonc gespeichert wird, laufen validate und lint automatisch im Hintergrund. Verstöße erscheinen sofort im Problems-Panel von VS Code — kein manuelles bausteinsicht lint nötig.

JSON Schema: Die schlanke Alternative

Ohne LSP-Setup funktioniert Autovervollständigung auch über JSON Schema. VS Code unterstützt das nativ.

Den $schema-Eintrag in architecture.jsonc setzen (→ Teil 3):

{
  "$schema": "https://raw.githubusercontent.com/docToolchain/Bausteinsicht/main/schemas/bausteinsicht.schema.json",
  ...
}

Das gibt sofort:

  • Autovervollständigung für alle bekannten Felder (kind, title, technology, etc.)

  • Typ-Validierung (z.B. container muss ein Boolean sein)

  • Hover-Dokumentation für alle Felder

JSON Schema prüft nur die Struktur, nicht die inhaltliche Konsistenz (z.B. ob ein kind-Wert in specification.elements definiert ist). Dafür ist der LSP zuständig.

Lokales Schema (ohne Internetverbindung)

# Schema herunterladen
curl -Lo schemas/bausteinsicht.schema.json \
  https://raw.githubusercontent.com/docToolchain/Bausteinsicht/main/schemas/bausteinsicht.schema.json

# In architecture.jsonc referenzieren
# "$schema": "./schemas/bausteinsicht.schema.json"

LSP vs. JSON Schema: Wann was?

FeatureJSON Schemabausteinsicht-lsp

Felddokumentation beim Hover

✅

✅

Autovervollständigung (bekannte Felder)

✅

✅

Typ-Validierung

✅

✅

Constraint-Prüfung (lint)

✗

✅

Modell-Konsistenz (validate)

✗

✅

CodeLens (kind/status/views)

✗

✅

Setup-Aufwand

Minimal (1 Zeile)

Gering (Binary installieren)

Funktioniert offline

✗ (Remote-URL) / ✅ (lokal)

✅

Für die meisten Projekte reicht JSON Schema. bausteinsicht-lsp lohnt sich wenn man regelmäßig mit dem Modell arbeitet und Constraint-Feedback sofort im Editor haben möchte.

Beispiel-Modell

Das Beispiel für diesen Teil (Elemente mit status-Feld für LSP-CodeLens) liegt unter teil_9.jsonc.

So sieht das Ergebnis in draw.io aus (bausteinsicht sync):

Das draw.io-File dafür findest du hier: teil_9.drawio

Generierte PNG-Dateien via bausteinsicht export --image-format png:

containers
context

Generierte PlantUML-Diagramme via bausteinsicht export-diagram:

Diagram
Diagram

Was als nächstes kommt

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org