Dieser Post setzt den achtzehnten Teil fort. bausteinsicht validate und bausteinsicht lint prüfen ob das Modell korrekt ist. bausteinsicht health geht weiter: es bewertet wie gut das Modell ist — Vollständigkeit, Konformität, Komplexität und mehr.

bausteinsicht health

bausteinsicht health --model architecture.jsonc

Ausgabe:

Architecture Health Report
==========================

Overall Score: 78.5/100 [B]
Summary: Good architecture documentation with room for improvement
Timestamp: 2025-06-11T06:00:00Z

Model Statistics
----------------
Elements:      18
Relationships: 14
Views:          4

Category Scores
---------------
Completeness:    82.0/100 (weight: 40%)
  Details: 15/18 elements have descriptions
Conformance:     95.0/100 (weight: 30%)
  Details: 1 constraint violation
Complexity:      65.0/100 (weight: 20%)
  Details: High relationship density detected
Deprecation:     70.0/100 (weight: 5%)
  Details: 2 deprecated elements still in use
Documentation:   80.0/100 (weight: 5%)
  Details: 3 elements without title

Findings
--------
Completeness (3 findings):
  [MAJOR] Missing descriptions
          shop.legacy, shop.legacy.api, eventbus: description is empty

Complexity (1 finding):
  [MINOR] High coupling
          shop.api has 6 outgoing relationships — consider splitting

Deprecation (1 finding):
  [MAJOR] Deprecated element referenced
          shop.legacy: status=deprecated but still used by shop.frontend

Bewertungskategorien

KategorieGewichtungWas wird bewertet

Completeness

40 %

Anteil der Elemente mit Beschreibung, Title, Technology

Conformance

30 %

Constraint-Verstöße aus bausteinsicht lint

Complexity

20 %

Relationship-Dichte, maximale Tiefe, Zyklen

Deprecation

5 %

Deprecated/Archived-Elemente die noch referenziert werden

Documentation

5 %

Elemente ohne title-Feld

Notenskala

ScoreNote

≥ 97

A+

≥ 93

A

≥ 90

B+

≥ 87

B

≥ 80

C+

≥ 70

C

≥ 60

D

< 60

F

Kurzansicht für Dashboards

bausteinsicht health --model architecture.jsonc --summary
# → Overall Score: 78.5/100 [B]

# Als JSON (für CI-Auswertung)
bausteinsicht health --model architecture.jsonc --summary --format json
{
  "overall": 78.5,
  "grade": "B",
  "summary": "Good architecture documentation with room for improvement",
  "timestamp": "2025-06-11T06:00:00Z"
}

Report in Datei schreiben

bausteinsicht health --model architecture.jsonc \
  --output docs/architecture-health.txt

Vollständige JSON-Ausgabe

bausteinsicht health --model architecture.jsonc --format json

Gibt das vollständige HealthScore-Objekt zurück mit categories, findings, Element-Zählern und ISO8601-Timestamp.

CI-Integration

- name: Architecture health (informational)
  run: |
    bausteinsicht health --model architecture.jsonc --summary
  continue-on-error: true   # health bricht nicht den Build

- name: Architecture health (enforce minimum grade)
  run: |
    GRADE=$(bausteinsicht health --model architecture.jsonc \
      --summary --format json | jq -r '.grade')
    if [[ "$GRADE" == "D" || "$GRADE" == "F" ]]; then
      echo "Architecture health below minimum threshold: $GRADE"
      exit 1
    fi
Im Gegensatz zu bausteinsicht lint blockiert health den Build nicht per Exit-Code — es ist eine Qualitätsmessung, kein Gate. Den Exit-Code kann man selbst über den Grade-Schwellenwert steuern (wie im Beispiel oben).

Unterschied zu validate und lint

BefehlZweckExit-Code bei Problem

validate

Strukturelle Korrektheit (Referenzen, Schema)

1

lint

Constraint-Verletzungen (Architekturregeln)

1

health

Qualitätsbewertung (Score, Note)

0 (immer erfolgreich)

Beispiel-Modell

Das Beispiel für diesen Teil (Modell mit unterschiedlicher Dokumentationsqualität — legacy-Service ohne Description/Status) liegt unter teil_19.jsonc.

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

Das draw.io-File dafür findest du hier: teil_19.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