TerminalBasic/openspec/specs/sprach-frontend/spec.md

# sprach-frontend Specification

## Purpose
Das Sprach-Frontend übersetzt Terminal-Basic-Quelltext (VBDOS-kompatibler
Dialekt) in einen typgeprüften AST: Lexer, fehlertoleranter Parser und
semantische Analyse mit Diagnostik nach den Meldungstexten des Vorbilds.

## Requirements

### Requirement: Lexikalische Analyse nach Sprachreferenz
Der Lexer SHALL Quelltext gemäß docs/sprachreferenz.md §1 zerlegen:
Typ-Suffixe (`% & ! # $ @`) an Bezeichnern und Literalen, case-insensitive
Keywords (Bibliotheksnamen bleiben Bezeichner), `'`/`REM`-Kommentare,
`:`-Anweisungstrenner, Zeilenfortsetzung mit `_`, Hex- (`&H`) und
Oktal-Literale (`&O`), `""`-Escape in Strings sowie die Metabefehle
`'$INCLUDE`, `'$STATIC`, `'$DYNAMIC`.

#### Scenario: Suffix trennt Bibliotheksfunktion von Keyword
- **WHEN** der Lexer `STRING$` und `STRING` liest
- **THEN** wird `STRING$` als Bezeichner (Builtin) und `STRING` als Typ-Keyword erkannt

#### Scenario: Zeilenfortsetzung
- **WHEN** eine Zeile nach Leerraum mit `_` endet
- **THEN** wird die Folgezeile ohne Zeilenende-Token angeschlossen

### Requirement: Literal-Typisierung
Der Lexer SHALL numerische Literale typisieren: Ganzzahlen INTEGER → LONG
→ Gleitkomma nach Wertebereich; `E`-Exponent → SINGLE, `D`-Exponent →
DOUBLE; Suffixe erzwingen den Typ (Überlauf → Diagnose „Overflow");
Dezimalpunkt-Literale bis 7 signifikante Stellen → SINGLE, darüber →
DOUBLE (Projektentscheidung 2026-09-02); `@`-Literale als
Currency-Festkomma ×10 000.

#### Scenario: Schwelle SINGLE/DOUBLE
- **WHEN** die Literale `1.5` und `3.14159265` gelext werden
- **THEN** ist `1.5` SINGLE und `3.14159265` DOUBLE

### Requirement: Vollständige Anweisungs-Grammatik
Der Parser SHALL den Anweisungssatz des Dialekts in einen AST überführen,
darunter: Zuweisung inkl. `MID$`-Anweisung, `PRINT`/`LPRINT` (mit
`USING`/`#`-Datei, `?`-Kurzform), `INPUT`/`LINE INPUT`, `IF` (Block und
einzeilig, `THEN zeilennummer`), `SELECT CASE` (Werte, `TO`-Bereiche,
`IS`-Vergleiche, `CASE ELSE`), `FOR`/`DO`/`WHILE`-Schleifen mit `EXIT`,
`GOTO`/`GOSUB`/`RETURN`/`ON … GOTO|GOSUB`, `ON [LOCAL] ERROR`/`RESUME`,
`DIM`/`REDIM`/`ERASE`/`CONST`/`DEFtype`/`OPTION`/`TYPE…END TYPE`/
`DECLARE`/`SUB`/`FUNCTION`/`CALL`, `COMMON`/`SHARED`/`STATIC`,
`DATA`/`READ`/`RESTORE`, `DEF FN` (einzeilig und Blockform),
`VIEW PRINT`, `NAME … AS`, Ereignissteuerung (`TIMER/KEY(n)/UEVENT
ON|OFF|STOP`) sowie die komplette Datei-E/A-Grammatik (`OPEN` in beiden
Syntaxen inkl. `ISAM`-/`ACCESS`-/`LOCK`-Klauseln, `CLOSE`, `FIELD`,
`GET`/`PUT`, `LSET`/`RSET`, `WRITE`, `SEEK`, `LOCK`/`UNLOCK`).
Zeilennummern und Labels am Zeilenanfang SHALL als Sprungziele erfasst
werden.

#### Scenario: Blockstrukturen über mehrere Zeilen
- **WHEN** ein `SELECT CASE` mit `CASE 1: PRINT "eins"` und `CASE ELSE` geparst wird
- **THEN** entsteht ein Select-Knoten mit zwei Armen und Inline-Anweisungen im ersten Arm

#### Scenario: Fehlertoleranz je Anweisung
- **WHEN** eine Anweisung einen Syntaxfehler enthält
- **THEN** wird eine Diagnose mit Position gesammelt, bis zum Anweisungsende synchronisiert und die Folgeanweisung normal geparst

### Requirement: Semantische Prüfung
Die Semantik SHALL prüfen: Typkompatibilität (numerisch ↔ numerisch,
String ↔ String; sonst „Type mismatch"), implizite Deklaration bei
Erstverwendung (Suffix-getrennte Variablen), `DEFtype`-Buchstabenbereiche,
`OPTION EXPLICIT` („Variable not defined"), Arrays (implizit, `DIM`,
`REDIM`; doppelte explizite Deklaration → „Duplicate definition"),
UDT-Feldzugriffe (`kunde.name` mit Feldtyp; unbekanntes Feld → „Element
not defined"), `SHARED`-Import von Modulvariablen in Prozeduren,
Konstantenfaltung für `CONST` (nicht konstant → „Invalid constant"),
Sprungziele („Label not defined") sowie Prozedur- und Builtin-Signaturen
(Anzahl → „Argument-count mismatch", Typen).

#### Scenario: Typkonflikt
- **WHEN** `a$ = 1` geprüft wird
- **THEN** wird „Type mismatch" mit Quelltextposition gemeldet

#### Scenario: UDT-Feldtyp
- **WHEN** ein `TYPE` mit Feld `Name AS STRING * 30` deklariert ist und `k.Name = 5` geprüft wird
- **THEN** wird „Type mismatch" gemeldet

### Requirement: Compile-Zeit-Abweisung deklarierter Non-Features
Die Semantik MUST jede Verwendung der in docs/sprachreferenz.md
(„Abweichungen") deklarierten Non-Features — Hardware-Nähe (`PEEK`,
`POKE`, `INP`, `OUT`, `WAIT`, `BLOAD`/`BSAVE`, `VARPTR`-Familie, `CALL
ABSOLUTE`/`INTERRUPT`, `IOCTL`), `CHAIN`, Grafik-Anweisungen, `SOUND`/
`PLAY` und die Event-Geräte `COM`/`PEN`/`PLAY`/`STRIG` — zur Compile-Zeit
mit der Meldung „Feature unavailable" abweisen. Dokumentierte Features
außerhalb dieser Liste MUST NOT abgewiesen werden (Guiding Principle).

#### Scenario: Hardware-Zugriff
- **WHEN** `POKE 100, 1` oder `x = PEEK(100)` kompiliert wird
- **THEN** erscheint die Compile-Diagnose „Feature unavailable"

### Requirement: Diagnostik mit Vorbild-Meldungen
Diagnosen SHALL exakte 1-basierte Quelltextpositionen (Zeile, Spalte)
tragen; die Meldungstexte SHALL dem Katalog des Vorbilds folgen, wo eine
Entsprechung existiert (z. B. „Type mismatch", „Duplicate definition",
„Label not defined", „Subprogram not defined", „Overflow").

Bei Projekten und Includes SHALL jede Diagnose den ursprünglichen Dateinamen mit dessen physischer Zeile und Spalte tragen.

#### Scenario: Position in der Diagnose
- **WHEN** in Zeile 3 ein Typkonflikt auftritt
- **THEN** nennt die Diagnose Zeile 3 und die Spalte des Ausdrucks

#### Scenario: Include-Diagnose
- **WHEN** ein eingebundenes Include einen Typfehler enthält
- **THEN** nennt die Diagnose die Include-Datei und ihre eigene Quellposition

### Requirement: Typisiertes HIR als Sema-Ausgabe
Die semantische Analyse SHALL neben den Diagnosen einen typisierten,
abgesenkten Zwischenbaum (HIR) liefern, der die Codegen-Eingabe bildet:
Namen sind zu Slot-/Tabellenindizes aufgelöst, jeder Ausdrucksknoten
trägt seinen Ergebnistyp, `CONST`-Werte sind gefaltet, `DEFtype`-Regeln
angewandt und implizite Konvertierungen als explizite
Konvertierungsknoten materialisiert. Bei Diagnosen mit Fehlercharakter
darf kein HIR für das betroffene Konstrukt garantiert werden; ein
diagnose-freies Modul MUST ein vollständiges HIR ergeben.

#### Scenario: Konvertierung wird materialisiert
- **WHEN** `d# = i% + 1.5#` semantisch analysiert wird
- **THEN** enthält das HIR einen expliziten Konvertierungsknoten INTEGER→DOUBLE unter dem Additionsknoten und die Zuweisung trägt den Zieltyp DOUBLE

#### Scenario: Diagnose-freies Modul liefert HIR
- **WHEN** ein Korpusmodul ohne Diagnosen analysiert wird
- **THEN** liefert das Frontend ein HIR, aus dem der Codegen ohne erneute Namens- oder Typauflösung Bytecode erzeugen kann

### Requirement: Jedes dokumentierte Element besitzt eine Signatur
Die Semantik SHALL für jedes im Sprachinventar geführte Element eine
Signatur besitzen (Argumentanzahl und -typen) — auch für Elemente, deren
Laufzeitverhalten noch aussteht. Ein im Inventar geführtes Element MUST
NOT als unbekannter Bezeichner oder mit einem generischen Syntaxfehler
abgewiesen werden; die Diagnose bzw. der Laufzeitfehler MUST es
namentlich nennen (Guiding Principle). Das gilt insbesondere für die
Gruppen, die bisher gar keine Signatur haben: die finanzmathematischen
Funktionen, die Record-Konvertierungsfunktionen (`MK…$`/`CV…`), die
Dateisystem-Funktionen `CURDIR$`, `DIR$`, `CHDRIVE`, sowie `LPOS`,
`STACK`, `SYSTEM`, `ERDEV`/`ERDEV$` und `SetFormatCC`.

Die TerminalBasic-Erweiterung TIMEZONEKNOWN SHALL als parameterlose INTEGER-Funktion eine Signatur besitzen und im Inventar mit ihrer tatsächlichen Umsetzung geführt sein.

#### Scenario: Element ohne Laufzeitverhalten wird namentlich abgewiesen
- **WHEN** ein Modul eine im Inventar als `offen` geführte Funktion verwendet
- **THEN** nennt die Ablehnung deren Namen und nicht „unbekannter Bezeichner"

#### Scenario: Argumentprüfung ohne Laufzeitverhalten
- **WHEN** ein Modul `MKL$()` ohne Argument enthält
- **THEN** meldet die Semantik eine Argumentanzahl-Diagnose, die `MKL$` nennt

#### Scenario: Signatur der Zonenzustandsabfrage
- **WHEN** PRINT TIMEZONEKNOWN übersetzt wird
- **THEN** entsteht eine INTEGER-Funktionsabfrage; TIMEZONEKNOWN(1) wird mit benannter Argumentanzahl-Diagnose abgewiesen

### Requirement: Modulweites ON ERROR ist aus Prozeduren ansprechbar
`ON ERROR GOTO label` ohne `LOCAL` SHALL einen modulweiten Fehlerhandler
setzen, dessen Sprungziel auch dann aufgelöst wird, wenn die Anweisung in
einer Prozedur steht und das Label auf Modulebene liegt. Nur
`ON LOCAL ERROR GOTO label` SHALL prozedurlokale Handler-Auflösung
verlangen. Ein modulweites `ON ERROR` in einer Prozedur MUST NOT wie
`ON LOCAL ERROR` behandelt werden, und ein auf Modulebene vorhandenes
Label MUST NOT als „Label not defined" gemeldet werden.

#### Scenario: Handler auf Modulebene aus einer Prozedur
- **WHEN** ein Modul das Label `Fehler:` auf Modulebene führt und eine `SUB` die Anweisung `ON ERROR GOTO Fehler` enthält
- **THEN** wird das Label aufgelöst und es entsteht keine Diagnose

#### Scenario: ON LOCAL ERROR bleibt prozedurlokal
- **WHEN** eine `SUB` die Anweisung `ON LOCAL ERROR GOTO Fehler` enthält und `Fehler:` nur auf Modulebene existiert
- **THEN** wird „Label not defined" gemeldet

### Requirement: DATA-Elemente behalten ihren Rohtext
Unquotierte Elemente einer `DATA`-Anweisung SHALL exakt so erhalten
bleiben, wie sie im Quelltext stehen — insbesondere in ihrer Groß- und
Kleinschreibung. Die Normalisierung von Bezeichnern MUST NOT auf
`DATA`-Elemente wirken. Führender und nachgestellter Leerraum eines
unquotierten Elements SHALL entfernt werden, innenliegender erhalten
bleiben.

#### Scenario: Gemischte Schreibweise bleibt erhalten
- **WHEN** ein Modul `DATA Hallo Welt` enthält und `READ s$` ausgeführt wird
- **THEN** enthält `s$` den Text `Hallo Welt` mit unveränderter Groß- und Kleinschreibung

#### Scenario: Leerraum an den Rändern
- **WHEN** ein Modul `DATA   ab cd  ` enthält und gelesen wird
- **THEN** lautet der Wert `ab cd`

### Requirement: ISAM-Anweisungen und -Funktionen in Grammatik und Signaturprüfung
Der Parser SHALL die ISAM-Anweisungen und -Funktionen des Vorbilds als
eigene Konstrukte erkennen, und die Semantik SHALL für jede eine Signatur
führen (Argumentanzahl und -typen). Der maßgebliche Umfang ergibt sich
aus dem Sprachinventar; er umfasst mindestens `CREATEINDEX`,
`DELETEINDEX`, `SETINDEX`, `GETINDEX$`, `INSERT`, `RETRIEVE`, `UPDATE`,
`DELETE`, `DELETETABLE`, `MOVEFIRST`, `MOVELAST`, `MOVENEXT`,
`MOVEPREVIOUS`, `SEEKEQ`, `SEEKGT`, `SEEKGE`, `BEGINTRANS`,
`COMMITTRANS`, `ROLLBACK`, `ROLLBACK ALL`, `SAVEPOINT`, `SETMEM` und
`BOF`. Eine fehlerhafte Verwendung MUST eine Diagnose erzeugen, die
das Element namentlich nennt; ein ISAM-Element MUST NOT als unbekannter
Bezeichner oder mit einem generischen Syntaxfehler abgewiesen werden
(Guiding Principle).

#### Scenario: ISAM-Anweisung wird als solche erkannt
- **WHEN** ein Modul `SETINDEX #1, "NachName"` enthält
- **THEN** entsteht keine Diagnose „unbekannter Bezeichner" und die Anweisung wird als ISAM-Anweisung erfasst

#### Scenario: Falsche Argumentanzahl wird namentlich gemeldet
- **WHEN** ein Modul `SEEKGT #1` ohne Schlüsselwert enthält
- **THEN** nennt die Diagnose `SEEKGT` und die erwartete Argumentanzahl

#### Scenario: Typprüfung des Satzarguments
- **WHEN** `RETRIEVE #1, x$` mit einem String statt einer Variablen des Tabellentyps geprüft wird
- **THEN** wird „Type mismatch" mit Quelltextposition gemeldet

### Requirement: Ereignis-Traps in Grammatik und Signaturprüfung
Der Parser SHALL die Trap-Anweisungen des Vorbilds als eigene Konstrukte
erkennen: `ON TIMER(n) GOSUB ziel`, `ON KEY(n) GOSUB ziel`,
`ON UEVENT GOSUB ziel` und `ON SIGNAL(n) GOSUB ziel`. Diese Formen MUST
NOT als berechnetes `ON ausdruck GOSUB liste` behandelt werden. Die
Steueranweisungen `TIMER`, `KEY(n)`, `UEVENT` und `SIGNAL(n)` mit `ON`,
`OFF` oder `STOP` SHALL erkannt und nur für diese Quellen zugelassen
werden; `EVENT` SHALL nur `ON` und `OFF` zulassen, weil das Vorbild
keinen dritten Zustand kennt. `COM`, `PEN`, `PLAY` und `STRIG` MUST als
Non-Feature namentlich abgewiesen werden. `SetUEvent` SHALL eine
Signatur besitzen. Die Wertebereiche SHALL geprüft werden: `ON KEY(n%)`
mit `n%` aus 0, 1–25 oder 30–31, `ON TIMER(n&)` mit `n&` aus 1–86 400
und `ON SIGNAL(n%)` mit `n%` aus 1–2. Eine fehlerhafte Verwendung MUST
eine Diagnose erzeugen, die das Element namentlich nennt.

#### Scenario: ON TIMER ist kein berechnetes GOSUB
- **WHEN** ein Modul `ON TIMER(5) GOSUB Marke` enthält
- **THEN** wird die Anweisung als Zeit-Trap erfasst und nicht als `ON ausdruck GOSUB` mit einer einelementigen Zielliste

#### Scenario: Ungültige Kennung wird namentlich gemeldet
- **WHEN** ein Modul `ON KEY(99) GOSUB Marke` enthält
- **THEN** nennt die Diagnose `ON KEY` und den zulässigen Wertebereich

#### Scenario: EVENT kennt kein STOP
- **WHEN** ein Modul `EVENT STOP` enthält
- **THEN** nennt die Diagnose `EVENT` und die zulässigen Formen `ON` und `OFF`

#### Scenario: Zeitintervall außerhalb des Bereichs
- **WHEN** ein Modul `ON TIMER(90000) GOSUB Marke` enthält
- **THEN** nennt die Diagnose `ON TIMER` und den Bereich 1 bis 86400

#### Scenario: Non-Feature-Quelle wird abgewiesen
- **WHEN** ein Modul `ON PEN GOSUB Marke` enthält
- **THEN** meldet die Übersetzung „Feature unavailable" an der Fundstelle der Anweisung — wie bei jedem anderen Non-Feature — und nicht einen generischen Syntaxfehler

#### Scenario: SetUEvent besitzt eine Signatur
- **WHEN** ein Modul `CALL SetUEvent` enthält
- **THEN** entsteht keine Diagnose „Subprogram not defined"

### Requirement: Trap-Ziele sind Sprungziele des Moduls
Das Ziel eines Ereignis-Traps SHALL wie ein `GOSUB`-Ziel aufgelöst
werden. Ein unbekanntes Ziel MUST zur Übersetzungszeit gemeldet werden
und nennt dabei das Label.

#### Scenario: Unbekanntes Trap-Ziel
- **WHEN** ein Modul `ON TIMER(1) GOSUB Fehlt` ohne Label `Fehlt` enthält
- **THEN** meldet die Übersetzung ein undefiniertes Sprungziel und nennt `Fehlt`

### Requirement: Objektzugriffe in Grammatik und Semantik
Der Parser SHALL Punktpfade auf Formulare und Steuerelemente
(`objekt.eigenschaft`), den Container-Operator
`form!steuerelement[.eigenschaft]`, `IF TYPEOF ausdruck IS klasse`, den
Metabefehl `$FORM` und die Datentypen `FORM` und `CONTROL` als
Parametertypen erkennen. Die Semantik SHALL Eigenschaften gegen die
Klasse des Objekts prüfen und ihren Typ bestimmen. Ein Punktpfad, dessen
Basis weder ein benutzerdefinierter Typ noch ein bekanntes Objekt ist,
MUST eine Diagnose erzeugen, die Basis und Eigenschaft namentlich nennt;
er MUST NOT zu einer impliziten Variablen mit Punkt im Namen werden.

Gleichnamige Steuerelemente unterschiedlicher Formulare SHALL im jeweiligen Formularnamensraum aufgelöst werden; die explizite Containerangabe SHALL vor der lokalen Namenssuche wirken.

#### Scenario: Unbekanntes Objekt wird benannt
- **WHEN** ein Modul `Text9.Text = "a"` ohne Steuerelement `Text9` enthält
- **THEN** nennt die Diagnose `Text9` als unbekanntes Objekt statt „Type mismatch" zu melden

#### Scenario: Unbekannte Eigenschaft wird benannt
- **WHEN** ein Modul `Text1.Farbe = 3` enthält
- **THEN** nennt die Diagnose `Farbe` als unbekannte Eigenschaft von `TextBox`

#### Scenario: Eigenschaftstyp wird geprüft
- **WHEN** ein Modul `Text1.Text = 5` enthält
- **THEN** meldet die Semantik einen Typkonflikt mit Nennung der Eigenschaft

#### Scenario: TYPEOF
- **WHEN** ein Modul `IF TYPEOF Ziel IS CommandButton THEN` enthält
- **THEN** wird es übersetzt und die Klasse gegen die bekannten Steuerelementklassen geprüft

#### Scenario: Gleichnamige Controls verschiedener Formulare
- **WHEN** Form1 und Form2 jeweils Text1 enthalten und Form2!Text1.Text gelesen wird
- **THEN** wird Text1 in Form2 aufgelöst und das Programm übersetzt diagnosefrei

### Requirement: Bang-Operator neben dem SINGLE-Suffix
Der Lexer SHALL `!` als Container-Operator erkennen, wenn ihm ein
Bezeichner folgt, und andernfalls als Typsuffix für SINGLE. Beide Formen
MUST im selben Modul nebeneinander verwendbar sein.

#### Scenario: Beide Bedeutungen im selben Modul
- **WHEN** ein Modul `Wert! = 1.5` und `Form1!Text1.Text = "a"` enthält
- **THEN** wird die erste Zeile als SINGLE-Variable und die zweite als Containerzugriff übersetzt

### Requirement: Ereignisprozeduren mit festen Signaturen
Die Semantik SHALL eine `SUB`, deren Name der Form `Objekt_Ereignis`
entspricht und deren Objekt bekannt ist, als Ereignisprozedur erkennen
und ihre Parameterliste gegen die Signatur der Forms-Referenz prüfen.
Eine abweichende Parameterliste MUST namentlich gemeldet werden. Eine
`SUB` mit Unterstrich im Namen ohne bekanntes Objekt MUST weiterhin eine
gewöhnliche Prozedur sein.

#### Scenario: Falsche Signatur
- **WHEN** ein Modul `SUB Form_MouseDown (X AS SINGLE)` enthält
- **THEN** nennt die Diagnose die erwartete Parameterliste der Ereignisprozedur

#### Scenario: Gewöhnliche SUB mit Unterstrich
- **WHEN** ein Modul `SUB Zins_Berechnen (n AS INTEGER)` ohne Objekt `Zins` enthält
- **THEN** wird sie als gewöhnliche Prozedur übersetzt