Assessor_2.0/docs/TOOL_PROFILES.md

Deklarative Toolprofile

Stand: 2026-07-17
Profilschema: 1

Zweck

Toolprofile bündeln alle werkzeugspezifischen Kenntnisse außerhalb der Formatparser und React-Komponenten. Ein Profil beschreibt Daten; die gemeinsame Profil-Fabrik erzeugt daraus die ausführbare Erkennung, Sheetpriorisierung, Standardansicht und Statusfilterung.

Profilinhalt

Eine ToolProfileDefinition enthält:

• stabile Profil-ID, Anzeigename und semantische Profilversion
• gewichtete Erkennungssignale für Dateiname, Inhalt, Tabellen, Kopfzeilen und Zellwerte
• bevorzugte und nachrangige Tabellennamen
• Synonyme für kanonische Feldrollen
• Status- und Severity-Normalisierung
• Titel-, Severity- und Sortierfelder für die Darstellung
• deklarative Statusfilter
• priorisierte Vergleichsschlüssel
• Kennzeichnung als generischer Fallback

Das Schema steht in src/domain/tool-profile-definition.ts. Die gemeinsame Laufzeitumsetzung liegt in src/profiles/profile-factory.ts.

Vorhandene Profile

Profil	Version	Schwerpunkt
Generic	1.0.0	verlustfreier Fallback für unbekannte Tabellen
Purple Knight	1.0.0	Indicator Results, IOE-Status, Weight und Ergebnisverweise
PingCastle	1.0.0	Healthcheck, Risk Scores und Regelkennungen
CIS-CAT Pro	1.0.0	Assessment Results, Recommendation und Pass/Fail
Maester	1.0.0	flache TestResults-Exporte, MT-IDs und ResultDetail

Die Definitionen liegen jeweils im Verzeichnis des Werkzeugs. profile-definition-catalog.ts stellt sie der Erkennungsengine bereit; profile-catalog.ts stellt die daraus erzeugten Laufzeitprofile für den Import und die Oberfläche bereit.

Verarbeitungsablauf

ToolProfileDefinition
  -> Quellen- und Mappingerkennung
  -> createImportProfile
  -> Profilwahl
  -> Sheetpriorisierung
  -> UI-Defaults und Statusfilter

Die Formatparser kennen keine Profile. Die Erkennungsengine liest Quellsignale, Feldregeln und Tabellenregeln ausschließlich aus dem Definitionskatalog. Die React-Anwendung verwendet lediglich den fertigen Laufzeitkatalog.

Versionierung

Jede fachliche Änderung an Erkennung, Mapping, Normalisierung oder Vergleichsschlüsseln benötigt eine neue Profilversion. Die beim Import verwendete Version wird als profileVersion im ImportedDataset gespeichert. Damit können zukünftige Re-Imports und Mappingmigrationen nachvollziehen, mit welchem Regelstand ein Datensatz verarbeitet wurde.

Neues Profil ergänzen

Ein neues Werkzeug benötigt:

1. eine versionierte Profildefinition,
2. die Registrierung im Definitionskatalog,
3. ein aus der Fabrik erzeugtes Laufzeitprofil,
4. die Registrierung im Laufzeitkatalog,
5. synthetische oder anonymisierte Fixture-Tests.

Formatparser, Erkennungsalgorithmus und React-Komponenten müssen dafür nicht geändert werden.

Darstellung von Textfeldern

Verbindlich für alle Werkzeuge und alle Ansichten: kein Aufrufer formatiert einen Feldwert selbst. Jeder werkzeuggelieferte Fließtext wird über RichTextValue ausgegeben, das die Auswertung an src/shared/markdown.ts delegiert. Ein neues Profil braucht dafür keine eigene Regel.

Behandelt werden:

• HTML-Auszeichnung, auf eine erlaubte Liste beschränkt; aktive Inhalte werden verworfen
• Markdown-Überschriften, geordnete und ungeordnete Aufzählungen, Tabellen, Codeblöcke
• **fett**, *kursiv*, `code`, [Titel](Adresse) — auch ineinander verschachtelt
• nackte Adressen im Fließtext
• Markdown-Tabellen ohne Zeilenumbrüche, wie Maester sie exportiert
• Überschriften, die mitten in einer Zeile stehen

Bewusst nicht behandelt: nummerierte Aufzählungen innerhalb einer Zeile. 1. ist ebenso oft der Anfang einer Kennung wie „1.1.1 (L1)"; eine Trennung dort würde Fachtext zerschneiden.

Zwei Regeln stützen das:

• cellText (statt clean) erhält die Zeilenstruktur eines Zellwerts. clean bleibt für Schlüssel, Kopfzeilen und Vergleiche zuständig — dort ist die Faltung richtig, im Inhalt zerstört sie die Gliederung.
• Schreibt ein Werkzeug seine Ergebnistabelle in ein Textfeld statt in eine eigene Datei, projiziert inlineResultTableSheets sie als Blatt. Sie ist dann über dieselbe Results-Schaltfläche erreichbar wie eine verknüpfte Datei.

Fällt bei einem neuen Werkzeug Auszeichnung auf, die hier fehlt, gehört sie nach src/shared/markdown.ts — nicht in das Profil und nicht in eine Komponente.

Fallback und Sicherheit

Wenn kein Werkzeugprofil ausreichend viele Signale erreicht, gewinnt das generische Profil. Nicht erkannte Felder bleiben als additional erhalten. Profile führen keinen importierten Inhalt aus und erweitern weder Netzwerk- noch Tauri-Berechtigungen.