epub2md/Prompt_Kontrolle.md

# Qualitätskontrolle für `epub2md.py`

Du bist ein sehr sorgfältiger Senior-Python-Engineer mit Schwerpunkt auf Testautomatisierung, EPUB-Interna, XML/XHTML, Markdown, Dokumentkonvertierung und Software-Qualität.

Im aktuellen Projektverzeichnis befindet sich ein bereits von Claude Code implementiertes Python-Programm zur Konvertierung von DRM-freien EPUB-Dateien nach kapitelweise gespeichertem Markdown. Das Programm heißt voraussichtlich:

```text
epub2md.py
```

Möglicherweise existiert zusätzlich ein Python-Paket, beispielsweise:

```text
epub2md/
```

Außerdem können folgende Verzeichnisse und Dateien vorhanden sein:

```text
Beispiele/
tests/
README.md
requirements.txt
pyproject.toml
setup.py
```

Deine Aufgabe ist nicht, das Programm neu zu entwerfen oder pauschal umzuschreiben. Führe stattdessen eine gründliche, nachvollziehbare Qualitätskontrolle durch und belege jede Feststellung durch tatsächliche Codeanalyse, Testausführung oder konkrete erzeugte Ausgaben.

## Oberstes Ziel

Stelle fest, ob das vorhandene Programm tatsächlich zuverlässig EPUB-Dateien in eine strukturierte, kapitelweise gespeicherte Markdown-Ausgabe konvertiert und dabei insbesondere die folgenden Inhalte korrekt oder zumindest verlustarm verarbeitet:

- Kapitelstruktur und Spine-Reihenfolge
- EPUB-2- und EPUB-3-Metadaten
- Überschriften, Fließtext, Hervorhebungen und Listen
- Tabellen
- Programmcode und Einrückungen
- Bilder, SVGs und andere Medien
- MathML, TeX/LaTeX, SVG- und Bildformeln
- Fußnoten, Endnoten und Rückverweise
- interne EPUB-Links und Anker
- Glossare
- Quellen, Bibliografien und Literaturverzeichnisse
- Sachregister und Personenregister
- YAML-Metadaten
- Inhaltsverzeichnis, Manifest und Konvertierungsbericht
- Fehlerbehandlung, sichere ZIP-Verarbeitung und Offline-Betrieb

Die Prüfung muss praxisnah sein. Prüfe nicht nur, ob Funktionen existieren oder Tests grün sind, sondern ob die erzeugten Markdown-Dateien tatsächlich brauchbar und untereinander korrekt verlinkt sind.

## Verbindliche Arbeitsweise

Halte dich exakt an diese Regeln:

1. Lies zuerst die komplette Projektstruktur ein.
2. Lies die vorhandene Dokumentation, insbesondere `README.md`.
3. Ermittle den tatsächlichen Einstiegspunkt und die tatsächlich unterstützten CLI-Optionen über:

   ```bash
   python3 epub2md.py --help
   ```

   Falls das Programm als Python-Modul ausgeführt werden muss, ermittle den richtigen Aufruf aus der Projektstruktur und Dokumentation.

4. Verlasse dich nicht auf Behauptungen im README oder auf bereits vorhandene Tests.
5. Führe vorhandene Tests tatsächlich aus.
6. Erstelle bei Lücken eigene Testfälle oder temporäre Minimal-EPUB-Dateien.
7. Teste echte EPUB-Dateien aus `Beispiele/`, falls dort Dateien vorhanden sind.
8. Verwende für jeden Testlauf ein neues, leeres Ausgabeverzeichnis.
9. Verwende niemals `--force` gegen ein echtes wichtiges Verzeichnis. Nutze ausschließlich Testausgabeordner, zum Beispiel:

   ```text
   .qa-output/
   .qa-fixtures/
   .qa-reports/
   ```

10. Nimm keine Änderungen am Produktivcode vor, bevor du:
    - den Fehler nachvollziehbar reproduziert hast,
    - den erwarteten Sollzustand beschrieben hast,
    - eine möglichst kleine Korrektur geplant hast.

11. Wenn du Produktivcode änderst:
    - ändere nur das Notwendige,
    - schreibe oder ergänze zuerst einen Test, der den Fehler reproduziert,
    - führe danach den neuen Test und die vollständige Testsuite aus,
    - führe mindestens einen erneuten CLI-Integrationstest aus,
    - dokumentiere exakt, welche Dateien geändert wurden und warum.

12. Erfinde keine Resultate. Wenn ein Test nicht ausgeführt werden kann, erkläre:
    - den konkreten Grund,
    - die Fehlermeldung,
    - die Auswirkung auf die Qualitätseinschätzung.

13. Keine Netzwerkzugriffe, keine Cloud-Dienste, keine Telemetrie und keine DRM-Umgehung.

14. Lösche keine Originaldateien unter `Beispiele/` und bearbeite sie nicht.

15. Verwende keine oberflächlichen Aussagen wie „scheint zu funktionieren“. Jede Aussage muss durch:
    - einen Test,
    - eine Code-Stelle,
    - eine erzeugte Datei,
    - oder einen reproduzierbaren Fehler
    gestützt sein.

## Prüfprotokoll

Lege im Projektverzeichnis ein Verzeichnis für die Qualitätsprüfung an:

```text
.qa/
```

Lege darin mindestens diese Dateien an:

```text
.qa/
├── QA_REPORT.md
├── QA_REPORT.json
├── commands.log
├── test-results.txt
├── findings.md
├── generated-fixtures/
├── output/
└── diff-summary.md
```

Falls die Projektregeln temporäre Dateien an anderer Stelle verlangen, passe die Pfade an. Die Ergebnisse der Qualitätskontrolle müssen aber klar von der normalen Programmausgabe getrennt sein.

Protokolliere alle wichtigen ausgeführten Kommandos inklusive Rückgabecode in:

```text
.qa/commands.log
```

Die Datei darf keine geheimen Daten enthalten. Es sollen in erster Linie lokal reproduzierbare Befehle, Testnamen und relevante Fehlermeldungen enthalten sein.

## Phase 1: Bestandsaufnahme

Führe zunächst eine Bestandsaufnahme durch.

Prüfe:

- Welche Python-Dateien und Module existieren?
- Gibt es eine `requirements.txt`, `pyproject.toml`, `setup.py` oder `tox.ini`?
- Welche Drittbibliotheken sind erforderlich?
- Gibt es Tests?
- Gibt es Beispiel-EPUBs?
- Ist das Programm monolithisch oder modular aufgebaut?
- Welche CLI-Optionen werden tatsächlich angeboten?
- Welche Ausgabestruktur behauptet die Dokumentation?
- Existieren Dokumentation und Implementierung im Einklang?

Erstelle in `.qa/QA_REPORT.md` einen Abschnitt:

```markdown
## Bestandsaufnahme
```

Dokumentiere dort:

- Projektstruktur
- Einstiegspunkt
- Python-Version
- erkannte Abhängigkeiten
- vorhandene Tests
- Anzahl und Namen vorhandener Beispiel-EPUBs
- tatsächlich vorhandene CLI-Optionen
- offensichtliche Diskrepanzen zwischen README und Implementierung

## Phase 2: Installations- und Startprüfung

Prüfe die Installation beziehungsweise Ausführbarkeit unter einer lokalen virtuellen Umgebung, sofern sinnvoll.

Nutze beispielsweise:

```bash
python3 -m venv .qa/venv
. .qa/venv/bin/activate
python -m pip install --upgrade pip
```

Installiere Abhängigkeiten anhand der tatsächlich vorhandenen Projektdateien, zum Beispiel:

```bash
pip install -r requirements.txt
```

oder:

```bash
pip install -e .
```

Führe anschließend aus:

```bash
python3 epub2md.py --help
```

Prüfkriterien:

- Das Programm startet ohne Traceback.
- `--help` funktioniert.
- Die Nutzungsbeschreibung ist verständlich.
- Positionsargumente für Eingabe-EPUB und Ausgabeordner sind dokumentiert.
- Implementierte Optionen sind sichtbar.
- Nicht implementierte, aber dokumentierte Optionen müssen als Dokumentationsfehler markiert werden.
- Nicht dokumentierte, aber implementierte Optionen müssen ebenfalls dokumentiert werden.

Wenn keine isolierte virtuelle Umgebung aufgebaut werden kann, teste mit der vorhandenen Python-Umgebung und dokumentiere dies klar.

## Phase 3: Vorhandene Tests ausführen

Ermittle das verwendete Testframework. Führe mindestens die vollständige Testsuite aus, bevorzugt mit:

```bash
pytest -q
```

Falls keine Tests vorhanden sind, markiere dies als schwerwiegende Qualitätslücke.

Prüfe zusätzlich, ob bei vorhandenem `pytest` eine Coverage-Auswertung möglich ist. Wenn ein Coverage-Tool nicht installiert ist, installiere es nur dann, wenn dies mit dem vorhandenen Abhängigkeitskonzept vereinbar ist.

Beispiel:

```bash
pytest -q --disable-warnings --maxfail=1
```

Falls möglich:

```bash
coverage run -m pytest
coverage report -m
```

Beurteile nicht nur die Zahl erfolgreicher Tests, sondern auch:

- Ob zentrale Funktionen tatsächlich getestet werden.
- Ob Tests nur Hilfsfunktionen statt CLI-Integration testen.
- Ob Fehlerfälle getestet werden.
- Ob Tests echte EPUB-Strukturen oder nur Mock-Objekte nutzen.
- Ob Tests kritische Spezialfälle aus diesem Prüfauftrag abdecken.

## Phase 4: Erzeuge eigene Minimal-EPUB-Testdaten

Falls das Projekt nicht bereits ausreichende, rechtlich unproblematische Testfixtures besitzt, erstelle selbst kleine, synthetische und DRM-freie EPUB-2- und EPUB-3-Dateien unter:

```text
.qa/generated-fixtures/
```

Erzeuge die Test-EPUBs ausschließlich lokal mit Python und ZIP-Dateien. Die EPUBs müssen valide genug sein, um vom Zielprogramm verarbeitet zu werden.

Erzeuge mindestens folgende Fixtures:

```text
01-minimal-epub2.epub
02-minimal-epub3-nav.epub
03-chapters-and-links.epub
04-code-and-tables.epub
05-images-and-svg.epub
06-mathml-and-equations.epub
07-footnotes-and-endnotes.epub
08-glossary-bibliography-index.epub
09-complex-table.epub
10-malicious-paths.epub
11-broken-container.epub
12-encoding-edge-cases.epub
```

### Anforderungen an die Fixtures

#### `01-minimal-epub2.epub`

Muss enthalten:

- `META-INF/container.xml`
- OPF-Paketdatei
- Metadaten mit Titel, Autor, Sprache und Identifier
- mindestens ein XHTML-Kapitel
- Spine-Reihenfolge
- NCX-Datei, falls sinnvoll

#### `02-minimal-epub3-nav.epub`

Muss enthalten:

- EPUB-3-OPF
- `nav.xhtml`
- mindestens zwei Kapitel
- valide Spine-Reihenfolge
- Dokumenttitel und Metadaten

#### `03-chapters-and-links.epub`

Muss enthalten:

- mehrere Kapitel
- mindestens zwei H1-Überschriften in einer XHTML-Datei
- interne Links:
  - zu einem anderen Kapitel
  - zu einem Anker im selben Kapitel
  - zu einem Anker in einem anderen Kapitel
- eine absichtlich nicht auflösbare interne Referenz

Prüfe:

- Kapitelaufteilung anhand von `--chapter-level`
- funktionierende relative Links
- Warnung für nicht auflösbare Links

#### `04-code-and-tables.epub`

Muss enthalten:

- Inline-Code
- Python-Code mit signifikanter Einrückung
- Shell-Code mit `$`, Pipes und Backslashes
- Code mit Backticks
- Code mit `<`, `>` und `&`
- Codeblöcke mit und ohne Sprachklasse
- verschachtelte ungeordnete und geordnete Listen
- einfache Tabelle

Prüfe:

- Code wird nicht HTML-escaped zerstört.
- Python-Einrückungen bleiben erhalten.
- Der Codeblock nutzt genügend Backticks.
- Sprachlabels sind korrekt oder bei Unsicherheit leer.
- Listenstruktur bleibt erhalten.
- Die einfache Tabelle wird als GFM-Tabelle oder zumindest in valider, lesbarer Form ausgegeben.

#### `05-images-and-svg.epub`

Muss enthalten:

- PNG oder JPEG
- SVG
- `figure` mit `figcaption`
- `img` mit `alt` und `title`
- mehrfach referenziertes Bild
- Bild mit Leerzeichen oder Sonderzeichen im Quellpfad

Prüfe:

- Bilder werden nur einmal extrahiert.
- Ausgabedateien bleiben im Ausgabeordner.
- Relative Bildlinks funktionieren aus den Kapiteldateien.
- SVG bleibt SVG und wird nicht ungewollt gerastert.
- Bildunterschriften und Alternativtexte bleiben erhalten.

#### `06-mathml-and-equations.epub`

Muss mindestens folgende MathML-Beispiele enthalten:

```xml
<math>
  <mfrac><mi>a</mi><mi>b</mi></mfrac>
</math>
```

```xml
<math>
  <msup><mi>x</mi><mn>2</mn></msup>
</math>
```

```xml
<math>
  <msub><mi>a</mi><mi>i</mi></msub>
</math>
```

```xml
<math>
  <msubsup>
    <mi>x</mi><mi>i</mi><mn>2</mn>
  </msubsup>
</math>
```

Zusätzlich:

- Inline-Formel
- Blockformel mit Gleichungsnummer
- nicht vollständig unterstütztes MathML-Element
- SVG-Formel
- Bildformel mit Alternativtext
- TeX/LaTeX in einem Attribut oder Textbereich, falls das Programm dies behauptet zu unterstützen

Prüfe für `--math auto`, `--math tex`, `--math mathml` und `--math image`:

- Keine Formel verschwindet.
- Bei einfacher MathML-zu-TeX-Konvertierung sind Bruch, Hochstellung und Index semantisch erkennbar.
- Bei komplexem oder unbekanntem MathML bleibt eine maschinenlesbare oder visuell verwendbare Repräsentation erhalten.
- Es wird kein offensichtlich falsches TeX erzeugt.
- Gleichungsnummern bleiben sichtbar.
- SVG- und Bildformeln bleiben als Medienreferenz erhalten.
- Warnungen für nicht semantisch extrahierte Formeln erscheinen im Report.

#### `07-footnotes-and-endnotes.epub`

Muss enthalten:

- eine Fußnotenreferenz mit `epub:type="noteref"` oder `role="doc-noteref"`
- Fußnotentext mit mehreren Absätzen
- Fußnote mit Link und Hervorhebung
- Fußnote mit Formel oder Code, wenn möglich
- mehrfach referenzierte Fußnote
- Endnotenabschnitt
- Rücklink zur Textstelle

Prüfe für:

```bash
--footnotes end-of-chapter
--footnotes end-of-book
--footnotes inline
--footnotes keep-links
```

Prüfkriterien:

- Fußnotentext verschwindet nicht.
- Fußnoten erscheinen nicht doppelt als Fließtext und als Fußnote.
- Referenzen und Definitionen sind konsistent.
- Inhalte innerhalb von Fußnoten bleiben erhalten.
- Der gewählte Modus entspricht der tatsächlichen Ausgabe.
- Nicht auflösbare Fußnotenverweise erzeugen Warnungen.

#### `08-glossary-bibliography-index.epub`

Muss enthalten:

- Glossar als Definitionsliste oder klar semantisch markierter Abschnitt
- Quellen- oder Bibliografieabschnitt
- URLs, DOI, ISBN und bibliografische Angaben
- Sachregister
- Personenregister
- alphabetische Gruppen
- mindestens einen internen Registerlink

Prüfe:

- Diese Bereiche werden nicht als normale, unbenannte Kapitel vermischt, falls das Programm eine Spezialbehandlung behauptet.
- Glossarbegriffe und Definitionen bleiben erhalten.
- Literaturangaben bleiben vollständig.
- URLs bleiben Links.
- Registereinträge und sichtbare Seiten-/Kapitelreferenzen bleiben erhalten.
- Interne Registerlinks werden, soweit möglich, korrekt umgesetzt oder als Warnung dokumentiert.

#### `09-complex-table.epub`

Muss enthalten:

- `colspan`
- `rowspan`
- mehrzeilige Tabellenzellen
- Textformatierung in Tabellenzellen

Prüfe:

- Keine Zellinhalte gehen verloren.
- Falls keine GFM-Tabelle sinnvoll ist, bleibt die Tabelle als valides HTML im Markdown erhalten.
- Eine Warnung wird erzeugt, wenn das Werkzeug dies verspricht.

#### `10-malicious-paths.epub`

Muss ZIP-Einträge mit unsicheren Pfaden enthalten, beispielsweise:

```text
../../outside.txt
../escape.xhtml
/absolute/path.txt
```

Prüfe:

- Das Programm schreibt nichts außerhalb des Ausgabeordners.
- Der Fehler wird sicher abgefangen.
- Es kommt nicht zu Path Traversal.
- Die Fehlermeldung ist verständlich.
- Der Rückgabecode entspricht dokumentierten Fehlercodes oder wird als Abweichung dokumentiert.

#### `11-broken-container.epub`

Muss mindestens einen absichtlich defekten Container-, OPF- oder Spine-Verweis enthalten.

Prüfe:

- Verständliche Fehlermeldung.
- Kein unkontrollierter Python-Traceback im Normalmodus, sofern das Programm benutzerfreundliche Fehlerbehandlung beansprucht.
- Passender Rückgabecode.
- Kein teilweise irreführender Erfolgsreport.

#### `12-encoding-edge-cases.epub`

Muss enthalten:

- deutsche Umlaute
- französische Akzente
- griechische Buchstaben
- mathematische Unicode-Symbole
- typografische Anführungszeichen
- Gedankenstriche
- nicht-ASCII-Dateinamen oder IDs, soweit EPUB-kompatibel

Prüfe:

- UTF-8-Ausgabe ist korrekt.
- keine vermeidbaren Ersatzzeichen `<EFBFBD>`
- keine ungerechtfertigte Transliteration im Text
- Slug-Verhalten entspricht `--slug-language`

## Phase 5: CLI- und Ausgabestruktur prüfen

Prüfe alle tatsächlich vorhandenen Optionen. Falls die ursprüngliche Spezifikation Optionen vorsieht, die Implementierung aber andere Optionen anbietet, bewerte ausschließlich die reale Implementierung und dokumentiere die Abweichung.

Prüfe mindestens:

```bash
python3 epub2md.py --help
python3 epub2md.py INPUT.epub OUTPUT_DIR
python3 epub2md.py INPUT.epub OUTPUT_DIR --dry-run
python3 epub2md.py INPUT.epub OUTPUT_DIR --verbose
```

Wenn implementiert, prüfe zusätzlich:

```bash
--format gfm
--format commonmark
--extract-media
--no-extract-media
--copy-original
--chapter-level 1
--chapter-level 2
--toc
--no-toc
--frontmatter
--no-frontmatter
--footnotes end-of-chapter
--footnotes end-of-book
--footnotes inline
--footnotes keep-links
--math auto
--math tex
--math mathml
--math image
--images relative
--images flat
--images original-path
--slug-language de
--slug-language en
--slug-language none
--keep-html
--strict
--force
--report DATEI.json
```

Für jede tatsächlich implementierte Option prüfe:

- Wird die Option akzeptiert?
- Ändert sie die Ausgabe wirklich in erwarteter Weise?
- Ist der Effekt dokumentiert?
- Entsteht bei ungültigen Werten eine verständliche Fehlermeldung?
- Gibt es einen sinnvollen Exit-Code?

Prüfe die Ausgabestruktur:

- Wird ein README oder Index erzeugt, falls behauptet?
- Werden Kapiteldateien erzeugt?
- Sind sie stabil nummeriert?
- Sind Slugs sinnvoll und konfliktfrei?
- Werden Medien in einem klaren Unterverzeichnis gespeichert?
- Werden Metadaten separat gespeichert, falls behauptet?
- Wird ein maschinenlesbarer Report erzeugt, falls behauptet?
- Werden Diagnoseinformationen erzeugt, falls Warnungen auftreten?
- Existieren keine Referenzen auf nicht existierende lokale Dateien, soweit die Konvertierung dies kontrollieren kann?

## Phase 6: Inhaltliche Ausgabevalidierung

Validiere nicht nur Dateiexistenz, sondern auch den Inhalt.

### Markdown-Validierung

Prüfe stichprobenartig und automatisiert:

- Gibt es unbalancierte Code-Fences?
- Gibt es leere oder abgeschnittene Markdown-Dateien?
- Gibt es kaputte relative Bildlinks?
- Gibt es kaputte interne Markdown-Links?
- Gibt es doppelte Kapitelinhalte?
- Gibt es unerwartete HTML-Entity-Reste wie `&lt;` im Code?
- Gibt es Python-Code, dessen Einrückung verloren ging?
- Gibt es offensichtlich entstellte Tabellen?
- Gibt es Fußnotenreferenzen ohne Definition oder Definitionen ohne Referenz?
- Gibt es offensichtliche Datenverluste bei Formeln?
- Enthält die Ausgabe ungewollte Navigationsfragmente wie „Next“, „Previous“, „Table of Contents“, falls diese aus dem EPUB-Reader-Layout stammen?
- Wurden Bilder oder Formeln fälschlich als Textmüll ausgegeben?
- Wurden Medienreferenzen auf existierende Dateien umgesetzt?

Verwende bei Bedarf kleine Prüfskripte unter `.qa/`, aber passe nicht die Produktivlogik an, nur um Tests zu täuschen.

### Relative Links

Schreibe einen Validator, der alle lokalen Markdown-Links und Bildlinks findet und prüft:

- Das Ziel ist entweder:
  - eine externe URL,
  - ein existierender relativer Pfad,
  - ein gültiger Anker im selben Dokument,
  - oder ein gültiges Dokument plus Anker.
- Fehlende Ziele werden im QA-Bericht aufgelistet.
- Der Validator muss Anker berücksichtigen, sofern praktikabel.
- Dokumentiere bei Ankerprüfung Grenzen der Heuristik.

### YAML-Frontmatter

Falls Frontmatter ausgegeben wird:

- Prüfe, ob es syntaktisch valides YAML ist.
- Prüfe, ob Titel, Kapitelnummer und Quelldatei plausibel sind.
- Prüfe, ob Sonderzeichen korrekt kodiert sind.
- Prüfe, ob die Metadaten nicht unzulässig erfunden wurden.

### JSON-Validierung

Falls `manifest.json`, `conversion-report.json` oder andere JSON-Dateien ausgegeben werden:

- Parse sie mit Python.
- Prüfe, ob die referenzierten Kapitel- und Mediendateien existieren.
- Prüfe, ob Zahlenwerte plausibel sind.
- Prüfe, ob gemeldete Warnungen mit beobachteten Problemen übereinstimmen.
- Prüfe, ob ein Programm bei Warnungen nicht fälschlich „verlustfrei“ oder „vollständig erfolgreich“ behauptet.

## Phase 7: Prüfung mit realen EPUB-Beispielen

Falls unter `Beispiele/` EPUB-Dateien vorhanden sind:

1. Liste alle EPUB-Dateien auf.
2. Bestimme anhand von Metadaten, Dateinamen und kurzer Strukturinspektion, welche davon wahrscheinlich:
   - Roman
   - Bildband
   - Programmierbuch
   - Mathematikbuch
   - Fachbuch
   sind.
3. Konvertiere jede EPUB-Datei in ein eigenes Unterverzeichnis unter:

   ```text
   .qa/output/examples/
   ```

4. Verwende standardmäßig konservative Optionen, zum Beispiel:

   ```bash
   python3 epub2md.py \
     "Beispiele/DATEI.epub" \
     ".qa/output/examples/NAME" \
     --format gfm \
     --extract-media \
     --toc \
     --frontmatter \
     --footnotes end-of-chapter \
     --math auto \
     --images relative \
     --slug-language de \
     --report ".qa/output/examples/NAME/report.json" \
     --verbose
   ```

5. Prüfe für jedes reale Buch stichprobenartig mindestens:
   - erste Kapiteldatei
   - ein Kapitel aus der Mitte
   - ein Kapitel mit besonderem Inhalt, falls vorhanden
   - letzte Kapiteldatei
   - README/Index
   - Medienverzeichnis
   - Konvertierungsbericht
6. Lies nur die für die technische Prüfung erforderlichen Auszüge. Gib im QA-Bericht keine längeren urheberrechtlich geschützten Textpassagen wieder.
7. Dokumentiere pro Buch:
   - Anzahl erzeugter Kapitel
   - Anzahl Medien
   - Anzahl Warnungen
   - erkannte Formeln
   - erkannte Codeblöcke
   - erkannte Fußnoten
   - erkannte Spezialabschnitte
   - konkrete Probleme und Dateipfade
   - Bewertung der Brauchbarkeit für:
     - Markdown-Lektüre
     - Pandoc-Weiterverarbeitung
     - RAG-Import
     - technische Bücher mit Code
     - Mathematik mit Formeln

## Phase 8: Sicherheits- und Robustheitsprüfung

Prüfe insbesondere:

### ZIP-Sicherheit

- Path Traversal wird sicher verhindert.
- Keine Datei wird außerhalb des Ausgabeordners geschrieben.
- Große oder ungewöhnliche Archive führen nicht zu unkontrollierten Ausnahmen, soweit ohne absichtliche Ressourcenerschöpfung testbar.
- ZIP-Einträge werden nicht blind extrahiert.

### XML-Sicherheit

- XML-Verarbeitung erlaubt keine externen Entitäten.
- Externe Ressourcen werden nicht aus dem Netzwerk geladen.
- Kein XXE-Risiko, soweit anhand der verwendeten Parserkonfiguration prüfbar.

### Dateisystemverhalten

- Existierender Ausgabeordner wird nicht stillschweigend überschrieben.
- Falls `--force` existiert, überschreibt es nur den angegebenen Ausgabeordner.
- `--dry-run` erzeugt keine fachlichen Ausgabedateien.
- Fehler führen nicht zu verwirrenden, halbvollständigen Ergebnissen ohne Warnung.
- Temporäre Verzeichnisse werden nach Möglichkeit bereinigt.

### Fehlercodes

Prüfe Rückgabecodes für:

- fehlende Eingabedatei
- ungültige Option
- kaputte ZIP-Datei
- kaputter EPUB-Container
- kaputte OPF-/Spine-Struktur
- Schreibfehler im Ziel, soweit sicher simulierbar
- unerwartete Ausnahme, falls reproduzierbar

Vergleiche mit der Dokumentation. Abweichungen sind als Fehler oder Dokumentationsmangel zu erfassen.

## Phase 9: Codequalität und Wartbarkeit

Führe eine gezielte Codeanalyse durch.

Prüfe:

- Sind Funktionen und Klassen klar abgegrenzt?
- Gibt es überlange, schwer testbare Funktionen?
- Werden Dataclasses oder strukturierte Modelle verwendet?
- Ist die HTML-zu-Markdown-Konvertierung rekursiv und nachvollziehbar?
- Sind Sonderfälle lokal gekapselt?
- Gibt es unnötige globale Zustände?
- Werden Dateipfade sicher behandelt?
- Werden Textkodierungen konsistent als UTF-8 behandelt?
- Gibt es Bare-`except:` oder verschluckte Fehler?
- Werden Warnungen zentral gesammelt?
- Sind Logs und Fehlermeldungen hilfreich?
- Ist die Konvertierung deterministisch?
- Funktioniert die Ausgabe bei wiederholtem Lauf reproduzierbar?
- Werden nicht unterstützte Inhalte sichtbar dokumentiert, statt still zu verschwinden?
- Gibt es Tests für tatsächlich komplexe Inhalte oder nur triviale Happy Paths?

Nutze bei Bedarf Werkzeuge wie:

```bash
python -m compileall .
```

und, falls im Projekt verfügbar oder angemessen:

```bash
ruff check .
```

```bash
mypy .
```

Führe zusätzliche Linter oder Typprüfungen nur aus, wenn sie ohne unvertretbare Umbauten nutzbar sind. Ein fehlender Linter ist nicht automatisch ein Fehler; fehlende Tests für Kernfunktionalität hingegen sind relevant.

## Fehlerklassifikation

Klassifiziere jedes Problem eindeutig:

```text
Kritisch
    Sicherheitsproblem, Datenverlust, Absturz bei normalen Eingaben,
    Überschreiben außerhalb des Zielordners, fehlerhafte Spine-Reihenfolge,
    verlorene Kapitel, zerstörter Programmcode, verschwindende Formeln oder Fußnoten.

Hoch
    Nicht funktionierende zentrale Option, falsche interne Links,
    unbrauchbare Bildpfade, fehlerhafte Kapitelaufteilung,
    ungültige Markdown-Ausgabe, nicht verarbeitete EPUB-3-Navigation,
    falsche oder fehlende Metadaten trotz Vorhandensein in EPUB.

Mittel
    Begrenzte Spezialfälle, schlechte Warnungen, unvollständige Reports,
    nicht optimal erhaltene Tabellen, fehlende Sprachkennung in Code,
    Dokumentationsabweichungen.

Niedrig
    Kosmetik, uneinheitliche Dateinamen, unpräzise Hilfetexte,
    kleinere README-Mängel ohne Auswirkung auf Konvertierungsqualität.
```

Bewerte immer die reale Auswirkung. Eine bekannte und klar dokumentierte Einschränkung ist weniger gravierend als stiller Datenverlust.

## Reparaturregeln

Führe Reparaturen nur durch, wenn:

- ein konkreter Fehler reproduziert wurde,
- der Fehler in den Projektumfang fällt,
- eine kleine, sichere Korrektur möglich ist,
- du zuvor oder gleichzeitig einen Regressionstest ergänzt.

Bei jeder Reparatur:

1. Erstelle einen fehlschlagenden Test oder dokumentiere einen reproduzierbaren CLI-Test.
2. Implementiere die kleinste mögliche Korrektur.
3. Führe den spezifischen Regressionstest aus.
4. Führe die vollständige Testsuite aus.
5. Führe mindestens einen realistischen EPUB-Integrationstest aus.
6. Aktualisiere README oder Hilfetext, wenn Verhalten oder Einschränkung relevant ist.
7. Dokumentiere Änderung, Ursache, Test und Ergebnis in `.qa/diff-summary.md`.

Nimm keine umfangreichen Refactorings nur aus Stilgründen vor. Priorität haben Zuverlässigkeit, Datenintegrität und nachvollziehbare Fehlerbehebung.

## Abschlussbericht

Erstelle am Ende eine vollständige Datei:

```text
.qa/QA_REPORT.md
```

Nutze exakt diese Gliederung:

```markdown
# QA-Bericht: epub2md

## Kurzfazit

## Projekt- und Laufzeitumgebung

## Bestandsaufnahme

## Tatsächlich getestete CLI-Schnittstelle

## Vorhandene Tests

## Ergänzte QA-Tests und Testfixtures

## Ergebnisse der EPUB-Integrationstests

## Prüfung der Markdown-Ausgabe

## Prüfung von Codeblöcken

## Prüfung von Medien und Bildlinks

## Prüfung von Mathematik und Formeln

## Prüfung von Fußnoten und Endnoten

## Prüfung von Glossar, Quellen und Registern

## Prüfung interner Links und Anker

## Sicherheits- und Robustheitsprüfung

## Gefundene Probleme

## Behobene Probleme

## Verbleibende Einschränkungen

## Testabdeckung und Vertrauensniveau

## Endbewertung

## Reproduzierbare Testkommandos
```

Die Datei `.qa/QA_REPORT.json` muss dieselben Kernergebnisse maschinenlesbar enthalten, mindestens mit folgender Struktur:

```json
{
  "project": {
    "name": "epub2md",
    "entrypoint": "epub2md.py",
    "python_version": "",
    "tested_at": ""
  },
  "summary": {
    "status": "pass|pass-with-limitations|fail",
    "critical_issues": 0,
    "high_issues": 0,
    "medium_issues": 0,
    "low_issues": 0,
    "tests_run": 0,
    "tests_passed": 0,
    "tests_failed": 0
  },
  "cli": {
    "works": false,
    "options_tested": []
  },
  "features": {
    "epub2": "",
    "epub3": "",
    "chapters": "",
    "code_blocks": "",
    "images": "",
    "math": "",
    "footnotes": "",
    "internal_links": "",
    "glossary": "",
    "bibliography": "",
    "indexes": "",
    "reports": "",
    "security": ""
  },
  "findings": [],
  "fixes_applied": [],
  "remaining_limitations": [],
  "reproduction_commands": []
}
```

## Endbewertung

Gib im Abschlussbericht eine klare Gesamtbewertung in genau einer dieser Kategorien:

```text
BESTANDEN
    Alle Kernfunktionen funktionieren in den geprüften Fällen.
    Keine kritischen oder hohen Probleme.
    Verbleibende Einschränkungen sind dokumentiert und verursachen keinen stillen Datenverlust.

BESTANDEN MIT EINSCHRÄNKUNGEN
    Grundfunktion funktioniert, aber es gibt mittlere oder niedrige Probleme,
    oder klar abgegrenzte Einschränkungen, beispielsweise bei komplexem MathML,
    Layouttabellen oder nicht standardkonformen EPUBs.
    Diese Einschränkungen müssen transparent dokumentiert sein.

NICHT BESTANDEN
    Mindestens ein kritisches oder hohes Problem bleibt bestehen,
    insbesondere bei Datenverlust, Sicherheit, Kapitelreihenfolge,
    Codeverlust, Fußnotenverlust, zerstörten Links oder nicht funktionierender CLI.
```

Die Endbewertung darf nicht nur aus grünen Unit-Tests abgeleitet werden. Sie muss besonders die realen CLI-Integrationstests, die synthetischen EPUB-Fixtures und – falls vorhanden – die EPUBs aus `Beispiele/` berücksichtigen.

## Abschlussausgabe im Terminal

Gib am Ende im Terminal eine kurze, präzise Zusammenfassung aus:

```text
QA abgeschlossen.

Gesamtbewertung: BESTANDEN | BESTANDEN MIT EINSCHRÄNKUNGEN | NICHT BESTANDEN
Unit-/Integrationstests: X bestanden, Y fehlgeschlagen
Kritische Probleme: X
Hohe Probleme: X
Behobene Probleme: X
Verbleibende Einschränkungen: X

Vollständiger Bericht:
.qa/QA_REPORT.md

Maschinenlesbarer Bericht:
.qa/QA_REPORT.json
```

Wichtig: Behaupte nur dann „BESTANDEN“, wenn die tatsächliche Konvertierung mit realen und synthetischen EPUBs überprüft wurde, interne Links und Medienpfade kontrolliert wurden und keine kritischen oder hohen Probleme bestehen.