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

AP08 – Minimalbericht bei Bedienfehlern (Exit-Code 2)

Ziel

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

Voraussetzungen

• AP06 (CLI), AP07 (Ausgabeartefakte)

Scope IN

Bedienfehler-Fälle

Alle diese Fälle müssen in Exit-Code 2 mit Minimalbericht resultieren:

1. Kein Argument übergeben → Minimalbericht auf Konsole (Eingabeverzeichnis unbekannt, also keine Dateiausgabe möglich)
2. Mehr als ein Argument → Minimalbericht auf Konsole
3. Eingabedatei existiert nicht → Minimalbericht auf Konsole und falls möglich in das übergeordnete Verzeichnis (dort wo die Datei hätte liegen sollen), sonst nur Konsole
4. Eingabepfad ist kein regulärer Dateityp (z.B. Verzeichnis) → Minimalbericht auf Konsole, keine Dateiausgabe
5. Eingabedatei ist nicht lesbar (Permissions) → Minimalbericht auf Konsole, Dateiausgabe wird versucht wenn Zielverzeichnis schreibbar ist, sonst nur Konsole

Minimalbericht-Inhalt

Der Minimalbericht ist ein ValidationReport (aus AP05) mit:

• fileName = übergebener Pfad (oder Platzhalter <kein Argument> bzw. <mehrere Argumente>)
• timestamp = jetzt
• genau ein Finding:
  • kind = SPEC
  • severity = ERROR
  • layer = ARTIFACT
  • ruleId = "OPERATIONAL-<fallkennung>" (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
• wichtig: das Verdict dieses Reports ist nicht INVALID, sondern OPERATIONAL_ERROR. Die Verdict-Ableitungslogik muss in AP05 bereits den Fall „nur OPERATIONAL-Findings" erkennen können — falls das in AP05 noch nicht vorgesehen wurde, muss ValidationReport hier minimal erweitert werden.
• Alternative, sauberere Modellierung: ein zusätzlicher Konstruktor oder Factory-Methode ValidationReport.operationalError(String fileName, String ruleId, String message), der den Verdict-Status explizit auf OPERATIONAL_ERROR setzt.

Dateiausgabe bei Exit-Code 2

• wenn das Zielverzeichnis ermittelbar und schreibbar ist: Berichtdatei wird gemäß AP07-Logik erzeugt
• wenn nicht: nur Konsolenausgabe, keine Fehlermeldung („Bericht konnte nicht geschrieben werden"), weil das den Benutzer doppelt verunsichert
• eine kurze Hinweiszeile auf der Konsole ist okay: „Bericht konnte nicht in das Verzeichnis geschrieben werden, siehe Konsolenausgabe oben."

Logging

• der Minimalbericht wird zusätzlich geloggt (logger.error(...)) — damit in der Log-Datei (sofern erzeugt) dokumentiert ist, was schiefging
• bei Fall 1 und 2 (keine Dateipfadinformation) ist die Log-Datei nicht sinnvoll zu platzieren → Fallback auf log4j2.xml-Default aus AP04

Scope OUT

• Unterscheidung zwischen verschiedenen IO-Exceptions im Detail (FileSystemException, AccessDeniedException, …) — ein einheitlicher Fall „nicht lesbar" reicht
• Internationalisierung
• Exit-Codes jenseits von 0/1/2
• Behandlung von OutOfMemoryError, StackOverflowError etc.

Schritte

1. Branch m1/ap08-minimalbericht
2. Factory-Methode ValidationReport.operationalError(...) in AP05-Modell ergänzen (falls noch nicht vorhanden)
3. CliRunner um die fünf Bedienfehler-Fälle erweitern; pro Fall wird der passende Minimalbericht erzeugt
4. ReportFileWriter: im OPERATIONAL-Fall weichere IO-Fehlerbehandlung (keine RuntimeException, stattdessen Konsolenhinweis)
5. Unit-Tests für alle fünf Fälle
6. End-to-End-Test: java -jar ... /pfad/zu/nichtvorhandener/datei.auf erzeugt auf Konsole einen Minimalbericht und Exit-Code 2
7. mvn clean verify grün
8. Commit M1-AP08: Minimalbericht bei Exit-Code 2
9. Abschlussbericht schreiben

Abnahmekriterien

• alle fünf Bedienfehler-Fälle erzeugen einen Minimalbericht (per Unit-Test belegt)
• Exit-Code in allen fünf Fällen ist 2
• Im Fall „Eingabedatei existiert nicht" wird der Minimalbericht in das übergeordnete Verzeichnis geschrieben, sofern dieses schreibbar ist
• Im Fall „kein Argument" wird der Minimalbericht nur auf Konsole ausgegeben (keine Dateiausgabe)
• Verdict.OPERATIONAL_ERROR ist in mindestens einem Test verifiziert
• mvn clean verify ist grün
• Abschlussbericht liegt vor

Rest-Risiken und offene Punkte

• Im Fall „Eingabedatei existiert nicht, Zielverzeichnis aber schon" ist der Bericht-Basisname der angegebene Dateiname (obwohl die Datei nicht existiert). Das ist okay — der Benutzer findet den Bericht dort, wo er die Datei erwartet hätte.
• Die Unterscheidung zwischen OPERATIONAL_ERROR und INVALID im Verdict ist wichtig für spätere Reporting-Logik. Falls sich herausstellt, dass OPERATIONAL_ERROR als separater Verdict-Wert zu Komplikationen führt, kann alternativ ein Boolean-Flag isOperational auf dem Report verwendet werden. Entscheidung im Bericht dokumentieren.

Bericht

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