asv-format-validator/docs/arbeitspakete/m1/AP08-minimalbericht.md

model

model
sonnet

AP08 – Minimalbericht bei Bedienfehlern (Exit-Code 2)

Meilenstein: M1 Vorgänger: AP06, AP07 ✅ erforderlich Nachfolger: AP10, AP11 Grundlage: docs/specs/technik-und-architektur.md v5, §§ „Gültigkeitsentscheidung und Exit-Codes", „Laufzeit- und Betriebsmodell"

Ziel

Auch bei Bedien- oder Zugriffsfehlern (Exit-Code 2) entsteht ein Minimalbericht, der den Fehler nachvollziehbar beschreibt. technik-und-architektur.md verlangt das ausdrücklich: „Auch bei Exit-Code 2 soll, soweit technisch möglich, ein Minimalbericht erzeugt werden."

Voraussetzungen

• AP06 (CLI), AP07 (Ausgabeartefakte)

Scope IN

Bedienfehler-Fälle (alle müssen Exit-Code 2 + Minimalbericht ergeben)

1. Kein Argument → nur Konsolenausgabe (Eingabeverzeichnis unbekannt)
2. Mehr als ein Argument → nur Konsolenausgabe
3. Eingabedatei existiert nicht → Konsolenausgabe + Berichtdatei im übergeordneten Verzeichnis, sofern dieses schreibbar ist
4. Eingabepfad ist kein regulärer Dateityp (z.B. Verzeichnis) → nur Konsolenausgabe
5. Eingabedatei ist nicht lesbar (Berechtigungen) → Konsolenausgabe + Berichtdatei sofern Zielverzeichnis schreibbar

Minimalbericht-Inhalt

Ein ValidationReport (AP05) via ValidationReport.operationalError(...) mit:

• fileName = übergebener Pfad (oder <kein Argument> / <mehrere Argumente>)
• timestamp = jetzt
• Genau ein Finding:
  • kind = SPEC → Verdict wird OPERATIONAL_ERROR
  • severity = ERROR
  • layer = ARTIFACT
  • ruleId = z.B. OPERATIONAL-MISSING-ARG, OPERATIONAL-FILE-NOT-FOUND, OPERATIONAL-NOT-READABLE, OPERATIONAL-NOT-REGULAR, OPERATIONAL-TOO-MANY-ARGS
  • germanMessage = kurzer verständlicher deutscher Text

Wichtige Regeln

• Kein Stack-Trace für den Nutzer — technische Details gehören ins Log, nicht in den Bericht
• Wenn Zielverzeichnis nicht schreibbar: nur Konsolenausgabe, kein Fehler-auf-Fehler
• Eine kurze Hinweiszeile auf Konsole ist okay: „Bericht konnte nicht in das Verzeichnis geschrieben werden."
• Der Bedienfehler wird zusätzlich geloggt (logger.error(...))

Tests

• Unit-Test für alle fünf Fälle: Exit-Code 2 + korrekter ruleId-Wert
• Negativ-Test: kein Stack-Trace in der Ausgabe
• Test: Fall 3 (Datei nicht vorhanden) → Berichtdatei im übergeordneten Verzeichnis, wenn schreibbar

Scope OUT

• Unterscheidung feingranularer IO-Exceptions (AccessDeniedException, FileSystemException etc.) — ein einheitlicher Fall „nicht lesbar" reicht
• Internationalisierung
• Exit-Codes jenseits von 0/1/2

Schritte

1. ValidationReport.operationalError(...) prüfen — falls noch nicht vollständig in AP05 implementiert, hier ergänzen
2. CliRunner um alle fünf Bedienfehler-Fälle erweitern
3. ReportFileWriter: im OPERATIONAL_ERROR-Fall weichere IO-Fehlerbehandlung (kein RuntimeException, stattdessen Konsolenhinweis)
4. Unit-Tests für alle fünf Fälle
5. mvn clean verify grün bekommen
6. Abschlussbericht schreiben

Abnahmekriterien

• Alle fünf Bedienfehler-Fälle erzeugen Exit-Code 2 (per Unit-Test belegt)
• Fall „kein Argument" → nur Konsolenausgabe, keine Dateiausgabe
• Fall „Datei nicht vorhanden" → Berichtdatei im übergeordneten Verzeichnis, sofern schreibbar
• Verdict.OPERATIONAL_ERROR ist in mindestens einem Test verifiziert
• Kein Stack-Trace in STDERR (Negativ-Test vorhanden)
• mvn clean verify grün
• Abschlussbericht unter docs/arbeitspakete/m1/berichte/AP08-bericht.md

Rest-Risiken und offene Punkte

• Im Fall „Datei nicht vorhanden, Zielverzeichnis aber existiert" ist der Basisname der angegebene Dateiname — der Nutzer findet den Bericht dort, wo er die Datei erwartet hätte.
• Falls Verdict.OPERATIONAL_ERROR als separater Wert zu Komplikationen führt: Boolean-Flag isOperational auf dem Report ist zulässiger Ausweg — Entscheidung im Bericht dokumentieren.

Bericht

docs/arbeitspakete/m1/berichte/AP08-bericht.md nach docs/arbeitspakete/m1/templates/ap-bericht.md.