# kompat-testkorpus Specification

## Purpose
Der Kompatibilitäts-Testkorpus hält das Sollverhalten des Dialekts als
ausführbare Spezifikation fest: Referenzprogramme mit byte-genau
dokumentierter Ausgabe, gegen die Frontend und (ab Phase 2) Laufzeit
geprüft werden.

## Requirements

### Requirement: Korpusdateien mit byte-genauer Sollausgabe
Jedes Korpusprogramm `tests/compat/<name>.bas` SHALL eine `<name>.out`
mit dem exakten Sollzustand des Bildschirms besitzen (UTF-8,
LF-Zeilenenden). Die Sollausgabe SHALL den Zellenpuffer als Textbild
abbilden, getrimmt bis zur letzten belegten Zeile und Spalte; nachgestellte
Leerzeichen innerhalb einer Zeile sind signifikant — `PRINT` gibt Zahlen
mit führendem Vorzeichen-/Leerzeichen und nachgestelltem Leerzeichen aus.
Verwendet ein Programm `COLOR`, SHALL die Sollausgabe zusätzlich eine
Attributebene gleicher Abmessung enthalten; ohne `COLOR` MUST sie
entfallen. `.gitattributes` MUST die `.out`-Dateien vor
Zeilenenden-Konvertierung schützen.

#### Scenario: Zahlformatierung in der Sollausgabe
- **WHEN** ein Korpusprogramm `PRINT 1; 2; 3` enthält
- **THEN** lautet die Sollzeile ` 1  2  3 ` (mit nachgestelltem Leerzeichen)

#### Scenario: Getrimmter Snapshot
- **WHEN** ein Korpusprogramm nur zwei Zeilen ausgibt
- **THEN** umfasst die Sollausgabe genau diese zwei Zeilen und keine leeren Folgezeilen

#### Scenario: Attributebene nur bei COLOR
- **WHEN** ein Korpusprogramm ohne `COLOR` läuft
- **THEN** enthält seine `.out` keine Attributebene

### Requirement: Frontend-Meilenstein über den Korpus
Ein automatischer Test SHALL alle `tests/compat/*.bas` durch das
Sprach-Frontend führen und fehlschlagen, sobald eine Datei Diagnosen
liefert. (Ab Phase 2 kommt der Laufzeitvergleich `tbc run` ↔ `.out`
hinzu.)

#### Scenario: Korpus bleibt kompilierbar
- **WHEN** die Frontend-Testsuite läuft
- **THEN** parsen alle Korpusdateien diagnose-frei und der Test nennt andernfalls Datei und Diagnose

### Requirement: Laufzeitvergleich über den Korpus
Ein automatischer Test SHALL jede Korpusdatei `tests/compat/*.bas`
kompilieren, über die VM mit einem Host ohne Terminal ausführen und den
resultierenden Bildschirmzustand gegen die zugehörige `.out`-Datei
vergleichen — getrimmt, mit signifikanten Leerzeichen innerhalb der
Zeilen und, sofern vorhanden, einschließlich der Attributebene. Bei
Abweichung MUST der Test Datei, erste abweichende Zeile sowie Soll und
Ist nennen; weicht nur die Attributebene ab, MUST er Zeile, Spalte, Soll-
und Ist-Attribut nennen.

#### Scenario: Korpus läuft mit korrekter Ausgabe
- **WHEN** die Laufzeit-Testsuite läuft
- **THEN** stimmt der Bildschirmzustand jeder Korpusdatei mit ihrer `.out` überein

#### Scenario: Abweichung wird benannt
- **WHEN** ein Korpusprogramm eine abweichende Ausgabe erzeugt
- **THEN** schlägt der Test fehl und nennt Datei, Zeilennummer, Soll- und Ist-Zeile

#### Scenario: Abweichendes Farbattribut
- **WHEN** ein Korpusprogramm dasselbe Textbild, aber ein abweichendes Attribut erzeugt
- **THEN** schlägt der Test fehl und nennt Zeile, Spalte, Soll- und Ist-Attribut

### Requirement: Korpusabdeckung der Phase-2-Semantik
Der Korpus SHALL um Referenzprogramme mit dokumentierter Sollausgabe für
die Zahlenkonvertierungs-Matrix (Rundung, Ganzzahldivision, logische
Operatoren, Überlauf-Randfälle über Fehlerbehandlung), die
Fehlerbehandlung (`ON ERROR`, `RESUME`-Varianten, `ERR`/`ERL`) sowie
Prozeduraufrufe mit BYREF-/BYVAL-Wirkung erweitert werden.

#### Scenario: Konvertierungsmatrix als Korpustest
- **WHEN** die Laufzeit-Testsuite läuft
- **THEN** existiert ein Korpusprogramm, das die Matrix-Randfälle ausgibt, und seine Ausgabe entspricht der dokumentierten Sollausgabe

### Requirement: Korpusabdeckung der Phase-3-Semantik
Der Korpus SHALL um Referenzprogramme mit dokumentierter Sollausgabe für
die Bildschirmsteuerung (`LOCATE`, `COLOR`, `CLS`, `VIEW PRINT`-Scrollen,
`CSRLIN`/`POS`, Zurücklesen per `SCREEN`), die Formatierung
(`PRINT USING` inklusive Feldüberlauf), breite Unicode-Zeichen
(Doppelzellen, Umbruch am rechten Rand), Datum und Zeit sowie die
Datei-E/A in allen drei Zugriffsarten erweitert werden. Dateiprogramme
MUST in einem temporären Arbeitsverzeichnis laufen und dürfen keine
Artefakte im Projektbaum hinterlassen.

#### Scenario: Bildschirmsteuerung als Korpustest
- **WHEN** die Testsuite läuft
- **THEN** existiert ein Korpusprogramm, das mit `LOCATE` und `COLOR` an definierten Positionen ausgibt, und sein Snapshot entspricht der Sollausgabe

#### Scenario: Datei-Korpustest hinterlässt nichts
- **WHEN** ein Datei-E/A-Korpusprogramm gelaufen ist
- **THEN** ist das Arbeitsverzeichnis wieder entfernt und der Projektbaum unverändert

### Requirement: Nachweis der Größenunabhängigkeit
Die Bildschirmgröße des Test-Hosts SHALL je Korpusprogramm explizit
festgelegt und in der Sollausgabe vermerkt sein; ein Vorgabewert MUST NOT
stillschweigend gelten. Mindestens ein Korpusprogramm SHALL bei zwei
verschiedenen Bildschirmgrößen laufen und je Größe eine eigene
Sollausgabe besitzen, um nachzuweisen, dass Löschen, Umbruch, Scrollen
und Cursorgrenzen der jeweiligen Größe folgen. Mindestens ein
Korpusprogramm SHALL eine Größenänderung während der Ausführung
durchlaufen und danach die neuen Grenzen ausnutzen.

#### Scenario: Gleiches Programm bei zwei Größen
- **WHEN** dasselbe Bildschirm-Korpusprogramm bei 80×25 und bei 120×40 läuft
- **THEN** stimmt jede Ausgabe mit der Sollausgabe ihrer Größe überein und die Sollausgaben unterscheiden sich in Umbruch- und Scrollverhalten

#### Scenario: Größenänderung mitten im Programm
- **WHEN** der Test-Host während der Ausführung von 80×25 auf 120×40 wechselt
- **THEN** bleibt der bisherige Inhalt oben links erhalten und die anschließende Ausgabe nutzt die neuen Grenzen

### Requirement: Korpusabdeckung der Ereignis-Traps
Der Testkorpus SHALL die Ereignissteuerung mit Programmen abdecken, die
ohne echte Wartezeit und mit reproduzierbarer Ausgabe laufen: Zeit-Trap,
Tasten-Trap einschließlich der Frage, ob die Taste im Eingabestrom
verbleibt, benutzerdefiniertes Ereignis, die drei Maskierungszustände je
Quelle, der Hauptschalter `EVENT` sowie Rückkehr und Nicht-Wiedereintritt
eines Handlers. Ein Korpusprogramm mit Zeitbezug SHALL seinen
Zeitverlauf im Programmkopf deklarieren; ohne Deklaration MUST der
Harness den Lauf abweisen statt auf die Systemuhr auszuweichen.

Die drei Zustände SHALL für KEY und UEVENT ebenso ausdrücklich im Korpus vorkommen wie für TIMER, einschließlich der Lesbarkeit einer unter KEY STOP gemerkten Taste.

#### Scenario: Zeit-Trap im Korpus
- **WHEN** ein Korpusprogramm mit deklariertem Zeitverlauf und `ON TIMER` ausgeführt wird
- **THEN** entspricht der Bildschirminhalt byte-genau der Sollausgabe und der Lauf benötigt keine messbare Wartezeit

#### Scenario: Fehlende Zeitdeklaration
- **WHEN** ein Korpusprogramm zeitgesteuerte Traps nutzt, aber keinen Zeitverlauf deklariert
- **THEN** schlägt der Harness mit einer Meldung fehl, die die fehlende Deklaration nennt

#### Scenario: KEY STOP im Korpus
- **WHEN** der Korpus einen F1-Druck unter KEY STOP und ein späteres ON ausführt
- **THEN** prüft seine Sollausgabe sowohl die normal lesbare Taste als auch genau eine spätere Handlerausführung

### Requirement: Korpusabdeckung der Formularprogramme
Der Testkorpus SHALL Formularprogramme mit byte-genauer
Bildschirm-Sollausgabe führen. Ihre Ereignisfolge (Tasten, Maus, Zeit)
SHALL im Programmkopf deklariert und vom Harness eingespeist werden,
sodass ein Lauf ohne Terminal und ohne Wartezeit auskommt und zweimal
dasselbe Ergebnis liefert. Abgedeckt SHALL sein: Fokus- und
Tabreihenfolge, Access-Key, Klick über die Maus, Menüauswahl, ein
Listen-Steuerelement, ein Timer und ein modaler Dialog.

Der Access-Key-Nachweis SHALL mindestens ein gewöhnliches Control betreffen und MUST NOT allein durch einen Menü-Access-Key ersetzt werden. Rückwärtstab und die beobachtbare Reihenfolge LostFocus vor GotFocus SHALL enthalten sein.

#### Scenario: Formularprogramm im Korpus
- **WHEN** ein Formular-Korpusprogramm mit deklarierter Ereignisfolge ausgeführt wird
- **THEN** entspricht der Bildschirminhalt byte-genau der Sollausgabe

#### Scenario: Wiederholbarkeit
- **WHEN** dasselbe Programm zweimal ausgeführt wird
- **THEN** ist die Ausgabe beide Male identisch

#### Scenario: Control-Access-Key und Rückwärtstab
- **WHEN** ein Formular-Korpus Alt+O für eine OK-Schaltfläche und anschließend Rückwärtstab deklariert
- **THEN** weist die Sollausgabe den Click und den Fokuswechsel in korrekter Reihenfolge nach

### Requirement: Kompatibilitätsnachweis an Fremdprogrammen
Die Formularprogramme aus dem öffentlichen Bestand des Vorbilds SHALL
sich ohne Diagnosen oder Non-Features übersetzen lassen und bedienbar
sein. Jeder entdeckte fehlende Sprach-, Projekt-, Formular- oder
Laufzeitpfad MUST implementiert und als Befund festgehalten werden.

Der Nachweis SHALL den verwendeten öffentlichen Bestand mit Revision und Programmeinstiegen benennen sowie reproduzierbare Eingabesequenzen und sichtbare Zustandsänderungen führen. Ein bloß erfolgreiches Starten MUST NOT als Bediennachweis gelten.

#### Scenario: Fremdprogramm übersetzt
- **WHEN** ein Formularprogramm des öffentlichen Bestands übersetzt wird
- **THEN** entstehen keine Diagnosen und das Programm ist bedienbar

#### Scenario: Bediennachweis ist wiederholbar
- **WHEN** ein dokumentiertes Fremdprogramm erneut mit seiner Prüfsequenz ausgeführt wird
- **THEN** werden dieselben relevanten Formularzustände beziehungsweise Abschlussereignisse erreicht
