Phase 5 vollständig planen und native Exporte abgrenzen

openspec/changes/phase-5-06-debugger-und-direktfenster/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-06

openspec/changes/phase-5-06-debugger-und-direktfenster/design.md

@@ -0,0 +1,31 @@
+## Context
+
+Die VM hat `add_module_breakpoint(module, line)`, `set_step`, Quellortabfragen und `inspect` für aktuelle Locals/Globals, Arrayelemente und UDT-Felder. Die Breakpoint-Identität enthält noch keine Datei; Calls-Ansicht, Ausdrucks-Compiler im pausierten Frame, Step Over, Watchpoints, History und Set Next Statement fehlen. Fehlerhandler werden intern durch `handle_error` gewählt und Frames gegebenenfalls abgewickelt. Die fortsetzbare Sitzung kommt aus 04.
+
+## Goals / Non-Goals
+
+**Goals:** Debugger als opt-in-Steuerung derselben VM; sichtbare Quellorte und beobachtete Werte gehören immer zur pausierten Kompilatrevision.
+
+**Non-Goals:** Zweiter BASIC-Interpreter, Rückgängigmachen von Datei-/Timer-/Netzwerknebenwirkungen, ungeprüftes Setzen des rohen Programmzählers oder persistentes Debugger-Bytecodeformat.
+
+## Decisions
+
+1. IDE-Breakpoints verwenden Dokument-/Modulidentität und eine durch Textedits mitgeführte Marke. Beim Compile werden sie an vorhandene Source-/Stmt-Grenzen des konkreten Kompilats gebunden, einschließlich Datei-ID. Die bestehende Modul-/Zeilen-API bleibt für bisherige Einbetter erhalten; die IDE benutzt die präzisere API. Eine Zeile mit mehreren Statements hält beim Eintritt in die Zeile, ein Step kann jede einzelne Anweisung zeigen. Nicht ausführbare Zeilen werden sichtbar ungebunden und nicht still auf eine fremde Datei verschoben.
+2. Fortsetzen überspringt nur die gerade gemeldete Halteprüfung am aktuellen Stmt und nicht einen späteren erneuten Besuch. Step Over verfolgt konkrete Frameidentität und Tiefe, nicht nur Prozedurname oder Zeilennummer. Run to Cursor besitzt einen temporären Halt mit begrenzter Lebensdauer. Events, rekursive Frames, GOSUB und Fehlerhandler behalten ihre bestehenden Eintritts-/Rückkehrregeln; Breakpoints haben Vorrang vor einem Step-Over-Ende.
+3. Eine lesbare Frame-/Symbolansicht liefert Calls und Watch-Kontext. Ausgewählter Inspektionsrahmen und aktiver Ausführungsrahmen sind getrennt. Ausdrücke werden mit Frontend/Sema/Codegen in einen kurzlebigen Debug-Kontext übersetzt, der tatsächliche Slots referenziert. Es wird keine eigene Arithmetik oder Typkonvertierung implementiert. Watches erlauben Literale, Operatoren, erreichbare Variablen, Arrays/UDTs und nachweislich reine Intrinsics; Benutzerprozeduren und zustandsverändernde Funktionen sind dort mit Diagnose ausgeschlossen. Das ist eine ausdrücklich dokumentierte Schutzregel für automatische Beobachtung; solche Aufrufe sind im Direktfenster möglich.
+4. **Watchpoint-Vorgabe:** Halt bei wahrer boolescher Bedingung an der nächsten Statement-Grenze. Nach Continue wird die aktuelle Prüfung einmal übersprungen; eine weiterhin wahre Bedingung kann an der nächsten Grenze wieder halten. Watchpoints werden nur bei aktiven Einträgen ausgewertet; fehlerhafte Einträge zeigen einen Fehler und werden bis zur Korrektur nicht als „wahr“ behandelt. Keine dauerhafte Mehrarbeit im CLI-Standardpfad.
+5. Immediate übersetzt erlaubte Anweisungen über denselben Frontend-/VM-Pfad in einen temporären Debug-Aufrufrahmen. Bestehende Symbole referenzieren die pausierte Sitzung einschließlich BYREF. Normale Seiteneffekte sind ausdrücklich wirksam. Der ursprüngliche Fortsetzungspunkt und die Debug-Kommandogrenze werden gesichert; Syntax-/Sema-Fehler verändern nichts. Runtime-Fehler und ERROR verwenden den bestehenden Fehlerpfad, ohne den Debug-Eintritt mit einer normalen Programmzeile zu verwechseln. Ein erfolgreich abgearbeitetes Kommando kehrt zur Pause zurück; END/SYSTEM/RUN innerhalb eines aufgerufenen Programmpfads werden an die Sitzung aus 04 weitergegeben. Interrupt/Warten benutzt deren fortsetzbare Operationen.
+6. Trace aktualisiert Quellmarkierung, History führt einen begrenzten Ring aus Quellorten. Projektvorgabe: 1.024 Einträge, älteste fallen heraus. Die Tasten navigieren nur diesen Trace, nicht VM-Zustände. Aktuell und historisch werden deutlich getrennt; alle Werte gehören weiterhin zum aktuellen Halt. Die Referenz beschreibt keine Rückabwicklung von Nebenwirkungen, deshalb wird kein Zeitreise-System gebaut.
+7. Break on Errors ergänzt einen Halt nach Auswahl/Unwinding des zuständigen Handlers, vor dessen erster Anweisung. Fehlerort, ERR/ERL und das vorgesehene RESUME-Ziel werden gesichert. Continue verarbeitet nicht denselben Fehler erneut. Für unbehandelte Fehler bleibt der entsprechende End-/Fehlerzustand unterscheidbar. Tests vergleichen die gesamte Handler-/RESUME-Folge mit deaktivierter Option.
+8. Set Next Statement benutzt eine Tabelle zulässiger Statement-Einstiege und Kontrollkontexte aus Codegen/VM. Nur derselbe aktive Frame und kompatible Schleifen-/GOSUB-/Fehlerkontexte sind erlaubt; Eintritt in einen fremden Block oder Handler ist kein roher PC-Sprung. Die Prüfung erfolgt vollständig vor Mutation. Erfolgreicher Sprung hält den Zustand und führt übersprungenen Code nicht aus.
+
+## Risks / Trade-offs
+
+- Gleiche Zeile in mehreren Includes → Binding mit tatsächlicher Datei-ID, expliziter Regressionstest im selben Modul.
+- Nebenwirkungen durch Watches → wiederverwendeter Expression-Compiler mit ausdrücklicher Reinheitsgrenze, Zustandsvergleich vor/nach mehrfacher Auswertung.
+- Debug-Aufruf und normaler Stack geraten durcheinander → separate Eintrittsmarke, Tests für BYREF, Rekursion, ERROR, Handler, Unterbrechen und RUN.
+- Set Next Statement springt in inkonsistente Strukturen → konservativ begründete Ablehnung; keine stillschweigende Reparatur des Programms.
+
+## Migration Plan
+
+Neue Debuggerfunktionen bleiben opt-in. Bestehende Breakpoint- und Run-APIs weiterprüfen; TBC-Quelldaten werden wiederverwendet. Ein Compile-Neustart bindet Breakpoints neu, löscht Frames, History und Watchwerte und behält nur die vom Benutzer definierten Watchausdrücke.

openspec/changes/phase-5-06-debugger-und-direktfenster/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+Die VM bietet Modul-/Zeilenbreakpoints und einfache Inspektion, aber keine vollständige IDE-Debugger-Sitzung. Besonders Includes, Prozedurschritte, Direktfenster und behandelte Fehler brauchen explizite Verträge, damit Debuggen dieselbe TBVM-Semantik behält.
+
+## What Changes
+
+- Dateigenaue Breakpoints, Run to Cursor, Einzelschritt, Prozedurschritt, Next Statement und Calls-Fenster.
+- Ausdruckswatches, Instant Watch, Watchpoints und Direktfenster im pausierten VM-Kontext.
+- Trace, navigierbare Ausführungshistorie, Break on Errors und validiertes Set Next Statement.
+- Opt-in-Debugger-Erweiterungen der bestehenden VM mit unverändertem Standardverhalten des CLI-Runners.
+
+## Capabilities
+
+### New Capabilities
+
+- `ide-debugger`: Dateigenaue Breakpoints, Run to Cursor, Einzelschritt, Prozedurschritt, Next Statement und Calls-Fenster.
+
+### Modified Capabilities
+
+Keine bestehenden Anforderungen werden ersetzt; die neue IDE-Fähigkeit ergänzt die vorhandenen Laufzeit- und Dateiformatverträge.
+
+## Impact
+
+tb-vm/interp.rs, Debug-Quellorte und Frontend/Codegen für Ausdrücke und Direktfenster; tb-ide-Debugfenster. Keine zweite Auswertungsmaschine, kein Zeitreise-Debugger.
+
+**Abhängigkeiten:** [phase-5-03-editor-und-inkrementelle-uebersetzung](../phase-5-03-editor-und-inkrementelle-uebersetzung/proposal.md), [phase-5-04-ausfuehrung-und-output](../phase-5-04-ausfuehrung-und-output/proposal.md).
+
+**Gesamtplanung:** [Phase-5-Übersicht](../phase-5-01-projekt-und-dokumentmodell/phase-5-uebersicht.md). Die Nummern geben eine gültige Umsetzungsreihenfolge an; OpenSpec erzwingt Change-Abhängigkeiten nicht automatisch.

openspec/changes/phase-5-06-debugger-und-direktfenster/specs/ide-debugger/spec.md

@@ -0,0 +1,70 @@
+## Purpose
+
+Stellt quellgenaues Debuggen innerhalb derselben TBVM bereit, einschließlich Ausführungssteuerung, Variablenbeobachtung, Direktfenster und nachvollziehbarer Fehlerhalte.
+
+## ADDED Requirements
+
+### Requirement: Dateigenaue Breakpoints
+F9 und Toggle Breakpoint SHALL Haltepunkte nach Modul, physischer Quelldatei und Zeile setzen und entfernen. Nur ausführbare Anweisungsgrenzen SHALL binden; nicht bindbare Marken SHALL sichtbar als inaktiv gelten. Clear All SHALL alle entfernen. Continue SHALL die angehaltene Anweisung genau einmal ausführen, bevor derselbe Halt erneut ausgelöst werden kann.
+
+#### Scenario: Zwei Includes mit gleicher Zeile
+- **WHEN** ein Modul zwei Includes mit ausführbarer Zeile 2 verwendet und nur die zweite Datei einen Haltepunkt besitzt
+- **THEN** hält ausschließlich die Anweisung der zweiten Datei an, mit richtigem Quellort und unverändertem Zustand vor ihrer Ausführung
+
+#### Scenario: Einfügen oberhalb einer Marke
+- **WHEN** oberhalb eines Breakpoints Zeilen eingefügt und danach neu übersetzt wird
+- **THEN** wird die Marke mit dem Dokumentedit verschoben und an der neuen Revision neu gebunden oder sichtbar deaktiviert; sie trifft keine fremde Anweisung
+
+### Requirement: Schrittsteuerung und Calls
+F8 SHALL eine BASIC-Anweisung einschließlich Betreten eines Aufrufs ausführen. F10 SHALL den aktuellen Aufruf bis zur nächsten Anweisung desselben Aufrufrahmens ausführen; Breakpoints und Fehlerhalte SHALL dabei Vorrang behalten. F7 SHALL temporär bis zum Cursor laufen, ohne vorhandene Breakpoints zu verlieren. Calls SHALL die Aufrufkette mit Prozedur und Quellort zeigen; Next Statement SHALL zur tatsächlichen Ausführungsstelle navigieren.
+
+#### Scenario: Rekursion und Prozedurschritt
+- **WHEN** F10 an einem rekursiven Aufruf verwendet wird
+- **THEN** endet der Schritt im ursprünglichen Aufrufrahmen hinter dem Aufruf und nicht in einem gleichnamigen rekursiven Rahmen
+
+#### Scenario: Temporäres Laufziel
+- **WHEN** Run to Cursor zuvor durch einen anderen Breakpoint unterbrochen oder das Programm beendet wird
+- **THEN** bleiben dauerhafte Breakpoints erhalten und ein beendeter oder abgebrochener Cursorlauf hinterlässt keinen ungewollten temporären Haltepunkt
+
+### Requirement: Watches und Watchpoints
+Add Watch, Instant Watch/Shift+F9, Watchpoint, Delete Watch und Delete All Watch SHALL typisierte BASIC-Ausdrücke im ausgewählten erreichbaren Aufrufrahmen einschließlich Modulqualifizierung, Arrayelementen und UDT-Feldern anbieten. Automatische Beobachtung SHALL den Programmzustand unverändert lassen; nicht nebenwirkungsfrei auswertbare Ausdrücke SHALL mit Grund abgewiesen werden. Watchpoints SHALL bei wahrer Bedingung an einer Anweisungsgrenze halten. Auswertungsfehler SHALL den jeweiligen Eintrag markieren und die Sitzung erhalten.
+
+#### Scenario: Beobachtung im lokalen Kontext
+- **WHEN** eine rekursive Prozedur pausiert und ein anderer erreichbarer Rahmen in Calls gewählt wird
+- **THEN** zeigen dessen Watches die Werte dieses Rahmens einschließlich lokaler Arrays und qualifizierter Globals, ohne den Ausführungsrahmen zu wechseln
+
+#### Scenario: Watchpoint wird wahr
+- **WHEN** eine Zuweisung eine zuvor falsche Watchpoint-Bedingung wahr macht
+- **THEN** hält die Ausführung an der nächsten sicheren Anweisungsgrenze mit aktualisierten Werten
+
+### Requirement: Direktfenster im pausierten Kontext
+Window→Immediate SHALL ein bedarfsweise sichtbares Direktfenster öffnen. Im Break-Modus SHALL es PRINT, Zuweisungen, Prozeduraufrufe und ERROR n über dieselben Sprach-, Typ- und Laufzeitregeln wie Projektcode ausführen. Änderungen an erreichbaren Variablen SHALL danach im Programm sichtbar sein. Ungültige Eingaben SHALL eine Diagnose liefern, ohne den angehaltenen Fortsetzungspunkt zu verlieren. Während eines laufenden Kommandos SHALL Unterbrechen möglich bleiben.
+
+#### Scenario: Wert ändern und fortsetzen
+- **WHEN** im lokalen Break-Kontext eine Zuweisung und ein BYREF-Prozeduraufruf eingegeben werden und anschließend F5 folgt
+- **THEN** verwendet das Programm die geänderten Werte und setzt am vorherigen Programmpunkt fort; temporärer Direktcode bleibt kein Teil des gespeicherten Projekts
+
+#### Scenario: Fehler im Direktfenster
+- **WHEN** ERROR n oder ein fehlerhaftes Direktkommando ausgeführt wird
+- **THEN** wird der Fehler nach den geltenden Laufzeitregeln angezeigt beziehungsweise behandelt, die IDE bleibt bedienbar und der Zustand der pausierten Sitzung ist eindeutig erkennbar
+
+### Requirement: Trace und Ausführungshistorie
+Trace On SHALL die aktuelle Quellstelle während des Laufs sichtbar verfolgen. History On SHALL ausgeführte Quellstellen in einem begrenzten Verlauf halten; Shift+F8/Shift+F10 SHALL darin rückwärts/vorwärts navigieren. Historische Auswahl SHALL sich von der aktuellen Ausführungsstelle unterscheiden und MUST NOT Variablen, Uhr, Dateien oder andere Nebenwirkungen zurückspulen. Ein Neustart SHALL den Verlauf zurücksetzen.
+
+#### Scenario: Historie betrachten
+- **WHEN** nach drei Zuweisungen zweimal rückwärts in History navigiert wird
+- **THEN** zeigt die IDE frühere Quellorte als Historie, während Variablenwerte und nächster realer Ausführungspunkt unverändert bleiben
+
+### Requirement: Break on Errors
+Bei aktivem Break on Errors SHALL die IDE auch vor der ersten Anweisung eines ausgewählten Fehlerhandlers anhalten und Fehlernummer, verursachenden Quellort und Handlerziel zeigen. Continue SHALL die bestehende Fehlerbehandlung genau einmal fortführen; ohne Debuggeroption SHALL das bisherige Verhalten unverändert bleiben. Unbehandelte Fehler SHALL als solche unterscheidbar bleiben.
+
+#### Scenario: Behandelter Fehler
+- **WHEN** ein Laufzeitfehler einen ON-ERROR-Handler auswählt und Break on Errors aktiv ist
+- **THEN** hält die IDE vor dem Handlercode; nach Continue stimmen ERR, ERL, Unwinding und RESUME-Verhalten mit dem Lauf ohne Debuggerhalt überein
+
+### Requirement: Sicheres Set Next Statement
+Set Next Statement SHALL im Break-Modus den nächsten Ausführungspunkt auf eine ausführbare Stelle desselben aktiven Prozedurrahmens setzen können, sofern Kontroll-, Schleifen-, GOSUB- und Fehlerzustand kompatibel bleiben. Ein unzulässiger Wechsel SHALL begründet und vollständig ohne Zustandsänderung abgewiesen werden. Erfolgreiches Setzen SHALL keine übersprungenen Anweisungen ausführen.
+
+#### Scenario: Gültiger und ungültiger Sprung
+- **WHEN** zunächst eine gleichrangige Folgeanweisung und danach eine Stelle in einer anderen Prozedur als nächstes Statement gewählt wird
+- **THEN** ist die erste Wahl wirksam und die zweite abgewiesen, ohne den ersten gültigen Fortsetzungspunkt zu verändern

openspec/changes/phase-5-06-debugger-und-direktfenster/tasks.md

@@ -0,0 +1,27 @@
+## 1. Quellgenaue Halte und Schritte
+
+- [ ] 1.1 Eine dateigenaue Breakpoint-Bindung ergänzen und bestehende Modul-/Zeilen-API erhalten; Tests mit zwei Includes derselben physischen Zeile im selben Modul halten nur im gewählten Include.
+- [ ] 1.2 Editierbare Breakpoint-Marken mit Neubindung an Kompilatrevisionen integrieren; Tests für Einfügen/Löschen und nicht ausführbare Zeilen belegen richtige Verschiebung oder sichtbare Deaktivierung.
+- [ ] 1.3 Continue-/Single-Step-Verhalten und F9/Clear All im IDE-Dispatcher anbinden; Tests belegen Ausführung einer angehaltenen Anweisung genau einmal und erneuten Halt bei späterem Schleifendurchlauf.
+- [ ] 1.4 Step Over mit Frameidentität sowie Run to Cursor mit temporärem Halt implementieren; Tests prüfen Rekursion, GOSUB, Eventhandler, vorrangige Breakpoints und Aufräumen des Cursorziels.
+- [ ] 1.5 Calls-Fenster und Next Statement mit getrenntem Inspektions-/Ausführungsrahmen anbinden; ein Rekursionstest navigiert in ältere Frames, ohne den aktiven PC zu verändern.
+
+## 2. Ausdrücke und Direktfenster
+
+- [ ] 2.1 Bestehenden Frontend-/Codegen-Pfad für temporäre Debug-Ausdrücke mit Slotbindung im gewählten Frame zugänglich machen; Tests vergleichen Zahlenkonvertierung, Modulqualifizierung, Arrays und UDT-Felder mit normalem BASIC-Code.
+- [ ] 2.2 Add/Instant/Delete/Delete All Watch und das read-only Debug Window integrieren; Tests zeigen Fehler pro Eintrag und nachweislich unveränderten Zustand nach wiederholter Beobachtung.
+- [ ] 2.3 Reinheitsprüfung für automatische Ausdrücke und bedingte Watchpoints implementieren; Tests lehnen zustandsverändernde Aufrufe ab und halten nach einer falsch→wahr-Änderung an der nächsten Grenze.
+- [ ] 2.4 Immediate Window mit temporärem Debug-Eintritt für PRINT und Zuweisungen implementieren; Tests belegen sichtbare Werteänderung und erhaltenen ursprünglichen Fortsetzungspunkt.
+- [ ] 2.5 Prozeduraufrufe einschließlich BYREF, ERROR und Runtimefehler im Direktfenster integrieren; Tests prüfen Handler/RESUME, Unterbrechen, wartende Aufrufe sowie END/RUN-Übergänge ohne verlorenen oder doppelten Frame.
+
+## 3. Historie, Fehler und Ausführungsziel
+
+- [ ] 3.1 Trace, begrenzte History und Shift+F8/Shift+F10 mit eindeutiger historischer Markierung implementieren; Tests belegen Ringgrenze, Navigation und unveränderte aktuelle Variablen/Dateieffekte.
+- [ ] 3.2 Break on Errors zwischen Handlerwahl und erster Handleranweisung einführen; Differentialtests mit deaktivierter Option belegen identische ERR/ERL-, Unwinding- und RESUME-Folge nach Continue.
+- [ ] 3.3 Zulässige Ziele für Set Next Statement aus Statement-/Kontrollkontexten ableiten und vor Mutation prüfen; Tests erlauben gleichrangige Ziele und lehnen fremde Frames, Schleifen-/GOSUB-/Fehlerkontexte ohne Teiländerung ab.
+- [ ] 3.4 Debuggerzustand an Neustart und Quellrevisionen binden; Tests belegen neu gebundene Breakpoints, erhaltene Watchdefinitionen und verworfene Frames/History/Werte.
+
+## 4. Abnahme und Bedienung
+
+- [ ] 4.1 Die vollständigen Debugger-Menüs und F7/F8/F9/F10/Shift+F9 über App-Ereignisse prüfen; dieselben Szenarien müssen auch mit Include- und Formularereigniscode korrekt anhalten.
+- [ ] 4.2 Debuggerverträge und die expliziten Grenzen für Watches, History und Set Next Statement dokumentieren; verification.md weist alle Szenarien sowie bestandene VM-/Fehlerhandler-/CLI-Regressionen und Format-/Clippy-Prüfung nach.