marcus/asv-format-validator
1
0
Fork 0
Code Activity
Files
main
asv-format-validator/docs/arbeitspakete/m1/berichte/AP08-bericht.md
T
marcus b5044f62a9 Umsetzung von M1
2026-04-20 10:11:19 +02:00

9.7 KiB
Raw Permalink Blame History

Abschlussbericht Arbeitspaket AP08 – Minimalbericht bei Bedienfehlern (Exit-Code 2)

Bezug: docs/arbeitspakete/m1/AP08-minimalbericht.md Bearbeiter: Claude Code (claude-sonnet-4-6), Subagent-Lauf Datum: 2026-04-20 Commit(s): ausstehend (Mensch committet nach Sichtung) Status: ✅ abgeschlossen

1. Zusammenfassung

Alle fünf Bedienfehler-Fälle erzeugen nun einen ValidationReport mit Verdict.OPERATIONAL_ERROR und geben den Minimalbericht auf STDERR aus. Wo das übergeordnete Verzeichnis bekannt und schreibbar ist (Fälle 3 und 5), wird die Berichtdatei zusätzlich als .txt-Datei geschrieben. mvn clean verify ist grün (218 Tests, 0 Failures, 1 Skipped auf Windows).

2. Umgesetzte Änderungen

Geändert:

  • src/main/java/de/gecheckt/asv/adapter/in/cli/CliRunner.java

    • Alle fünf Bedienfehler-Fälle erzeugen jetzt ValidationReport.operationalError(...) mit den definierten ruleId-Werten
    • Zwei neue private Hilfsmethoden: writeMinimalReportToConsoleOnly(report) (STDERR-only) und writeMinimalReportWithOptionalFile(report, directory, baseName) (STDERR + optionale Datei)
    • Fälle 1 (kein Arg), 2 (zu viele Args) und 4 (kein regulärer Dateityp) → nur Konsole
    • Fälle 3 (Datei nicht gefunden) und 5 (Datei nicht lesbar) → Konsole + Berichtdatei im übergeordneten Verzeichnis, sofern schreibbar
    • Alle Bedienfehler werden via logger.error(...) protokolliert
    • Platzhalter-Konstanten: <kein Argument> und <mehrere Argumente> für den fileName-Parameter

  • src/main/java/de/gecheckt/asv/adapter/out/reporting/ReportFileWriter.java

    • Neue public-Methode writeOperationalError(ValidationReport, Path, String): Schreibt Bedienfehler-Bericht direkt in ein angegebenes Verzeichnis; IO-Fehler lösen keine RuntimeException aus, sondern werden geloggt und als fehlgeschlagenes ReportWriteResult zurückgegeben
    • Neue public-Methode buildMinimalReportContent(ValidationReport): Erzeugt Berichtinhalt ohne Path-Parsing, damit Platzhalter mit Sonderzeichen (<kein Argument>) funktionieren
    • buildReportContent(ValidationReport, Path) delegiert jetzt an die neue private buildReportContentWithFileName(ValidationReport, String) — kein Duplizierungsrisiko
    • Befundzeilen zeigen jetzt auch Regel=<ruleId>, wenn eine ruleId gesetzt ist

Neu angelegt:

  • src/test/java/de/gecheckt/asv/adapter/in/cli/CliRunnerOperationalErrorTest.java
    • 16 Tests, 1 Skipped (Fall 5 auf Windows)
    • Alle fünf Bedienfehler-Fälle getestet (Exit-Code 2)
    • Korrekte ruleId-Werte für alle fünf Fälle verifiziert
    • Verdict.OPERATIONAL_ERROR in dediziertem Test verifiziert
    • Drei Negativ-Tests: kein Stack-Trace in STDERR
    • Fall 3: Berichtdatei im übergeordneten Verzeichnis vorhanden und enthält BEDIENFEHLER + OPERATIONAL-FILE-NOT-FOUND

3. Scope-Treue

Scope-Punkt aus dem Arbeitspaket Erfüllt? Bemerkung
Fall 1: Kein Argument → Exit 2 + nur Konsole ✅ writeMinimalReportToConsoleOnly
Fall 2: Mehr als ein Argument → Exit 2 + nur Konsole ✅ writeMinimalReportToConsoleOnly
Fall 3: Datei nicht gefunden → Exit 2 + Konsole + Datei ✅ writeMinimalReportWithOptionalFile
Fall 4: Kein regulärer Dateityp → Exit 2 + nur Konsole ✅ writeMinimalReportToConsoleOnly
Fall 5: Datei nicht lesbar → Exit 2 + Konsole + Datei ✅ Nur auf Unix; Windows-Test übersprungen
ruleId-Werte: OPERATIONAL-MISSING-ARG, OPERATIONAL-TOO-MANY-ARGS, OPERATIONAL-FILE-NOT-FOUND, OPERATIONAL-NOT-REGULAR, OPERATIONAL-NOT-READABLE ✅ Alle fünf implementiert und getestet
Kein Stack-Trace für den Nutzer ✅ Drei Negativ-Tests
logger.error(...) für Bedienfehler ✅ In jedem Fall vorhanden
ReportFileWriter: weiche IO-Fehlerbehandlung bei OPERATIONAL_ERROR ✅ writeOperationalError ohne RuntimeException
Konsole-Hinweis wenn Verzeichnis nicht schreibbar ✅ „Bericht konnte nicht in das Verzeichnis geschrieben werden."
Unit-Tests für alle fünf Fälle: Exit 2 + ruleId ✅ Alle fünf Fälle im neuen Test
Test Fall 3: Berichtdatei im übergeordneten Verzeichnis ✅ Test vorhanden und grün
Verdict.OPERATIONAL_ERROR in Test verifiziert ✅ operationalErrorReport_verdictIstOPERATIONAL_ERROR
ValidationReport.operationalError(...) vollständig (Layer ARTIFACT) ✅ War bereits in AP05 vollständig implementiert
Feingranulare IO-Exception-Unterscheidung (Scope OUT) ✅ nicht gemacht Einheitlich „nicht lesbar"
Internationalisierung (Scope OUT) ✅ nicht gemacht —
Exit-Codes jenseits 0/1/2 (Scope OUT) ✅ nicht gemacht —

Wurde der Scope eingehalten? Ja, vollständig.

Wurden Dinge außerhalb des Scopes gemacht? Die buildReportContent-Methode wurde intern auf buildReportContentWithFileName umgestellt und gibt jetzt auch ruleId-Werte aus. Das ist eine minimale Erweiterung des Berichtformats, aber direkt notwendig für den AP08-Abnahmetest (fall3_dateiExistiertNicht_berichtdateiEnthaeltOpertionalError prüft auf OPERATIONAL-FILE-NOT-FOUND im Berichtinhalt). Kein Code außerhalb des erlaubten Scope wurde berührt.

4. Abnahmekriterien

Abnahmekriterium aus dem Arbeitspaket Erfüllt? Nachweis
Alle fünf Bedienfehler-Fälle erzeugen Exit-Code 2 (per Unit-Test) ✅ CliRunnerOperationalErrorTest: fall1…fall5, alle grün (fall5 Skipped auf Windows)
Fall „kein Argument" → nur Konsolenausgabe, keine Dateiausgabe ✅ fall1_keinArgument_nurKonsole: countTxtFiles(tempDir) == 0
Fall „Datei nicht vorhanden" → Berichtdatei im übergeordneten Verzeichnis ✅ fall3_dateiExistiertNicht_berichtdateiImUebergeordnetenVerzeichnis + fall3_dateiExistiertNicht_berichtdateiEnthaeltOpertionalError
Verdict.OPERATIONAL_ERROR in mindestens einem Test verifiziert ✅ operationalErrorReport_verdictIstOPERATIONAL_ERROR und alleRuleIds_sindKorrektDefiniert
Kein Stack-Trace in STDERR (Negativ-Test vorhanden) ✅ keinArgument_keinStackTraceInStderr, dateiNichtGefunden_keinStackTraceInStderr, pfadIstVerzeichnis_keinStackTraceInStderr
mvn clean verify grün ✅ 218 Tests, 0 Failures, 0 Errors, 1 Skipped
Abschlussbericht unter docs/arbeitspakete/m1/berichte/AP08-bericht.md ✅ Diese Datei

5. Build- und Teststatus

  • mvn clean verify: ✅ grün
  • Anzahl Tests gesamt: 218 (davon 16 neu in CliRunnerOperationalErrorTest)
  • Vorherige Testanzahl (vor AP08, nach AP07/AP09): 202
  • 1 Test Skipped: fall5_dateiNichtLesbar_exitCode2 — Windows-bedingt; setReadable(false) hat auf Windows keine Wirkung für den eigenen Prozess. Der Test enthält assumeTrue(...) zum expliziten Überspringen.
  • Coverage: JaCoCo läuft; neue Methoden in CliRunner und ReportFileWriter sind durch die neuen Tests abgedeckt
  • Warnungen beim Build: identisch zu AP06/AP07 (Shade-Plugin META-INF-Überlappungen) — keine neuen Warnungen

6. Rest-Risiken und offene Punkte

  • Fall 5 (Datei nicht lesbar) nur auf Unix testbar: Auf Windows kann setReadable(false) eine Datei nicht für den eigenen Prozess unlesbar machen. Der Test wird explizit übersprungen. Die Implementierung in CliRunner ist korrekt und folgt demselben Muster wie Fall 3 (der auf beiden Plattformen vollständig getestet wird). Das Verhalten bei echten Berechtigungsfehlern auf Windows (z.B. NTFS-ACL) ist vom aktuellen Test nicht abgedeckt.

  • buildReportContent-Refactoring: Die Umstellung auf buildReportContentWithFileName ist intern und ändert das nach außen sichtbare Verhalten nicht. Bestehende Tests in ReportFileWriterTest wurden nicht gebrochen. Die neu hinzugefügte ruleId-Ausgabe (Regel=...) in der Befundzeile ist eine Erweiterung des M1-Formats — M9 wird das Format ohnehin final gestalten.

  • Platzhalter <kein Argument> und <mehrere Argumente>: Diese Strings enthalten <>, die auf Windows als ungültige Pfadzeichen gelten. Durch den Wechsel auf buildReportContentWithFileName (kein Path.of(...)) ist das Problem gelöst. AP10 (Architekturtest) sollte sicherstellen, dass ReportFileWriter kein Path.of(report.getFileName()) mehr aufruft.

  • Konsolen-Encoding-Problem (Windows, bekannt aus AP07): Die STDERR-Ausgabe des Minimalberichts enthält Umlaute (BEDIENFEHLER, Fehler). Auf Windows-Konsolen mit CP1252/OEM437 können diese als Mojibake erscheinen. Die Berichtdatei ist korrekt UTF-8. Bekanntes Windows-Konsolen-Problem, nicht AP08-Scope.

7. Empfehlungen für Folge-Arbeitspakete

  • AP10 (Architekturtest): ArchUnit sollte sicherstellen, dass ReportFileWriter kein Path.of(report.getFileName()) aufruft (wurde in AP08 explizit vermieden). Die drei Negativ-Stack-Trace-Tests könnten als Basis für eine formale „kein Exception-Stacktrace in STDERR"-Regel dienen.

  • AP11 (M1-Abnahme): End-to-End-Test kann die Bedienfehler-Szenarien prüfen: kein Arg → Exit 2, Berichtdatei nur wenn Verzeichnis bekannt, BEDIENFEHLER im Bericht.

  • M9 (Berichtformat ausbauen): Die neue buildReportContentWithFileName-Methode ist der Erweiterungspunkt für das finale Berichtformat. Die ruleId-Ausgabe (Regel=...) ist ein Vorgriff und kann in M9 in das finale Format integriert werden.

8. Reviewer-Checkliste

  • Alle im Arbeitspaket genannten Scope-IN-Punkte sind nachweislich umgesetzt
  • Keine Scope-OUT-Punkte wurden angefasst
  • Abnahmekriterien sind mit konkreten Nachweisen belegt (Tests, Dateipfade)
  • mvn clean verify ist grün (218 Tests, 0 Failures)
  • Der Commit für dieses AP hat eine sprechende Message (M1-AP08: ...) — ausstehend, Mensch committet
  • Keine Regeln der Grunddokumente (Spec, Fachliche, Technik) wurden verletzt
  • Rest-Risiken sind ehrlich dokumentiert
View Git Blame Copy Permalink