blockworx/script/

debugger.rs

//! The script debugger: author a script as text, one step per line, and
//! execute it like code under a debugger — step forward, step backward,
//! reset — against the real editing tools.
//!
//! The core invariant: the state at position `p` is *the initial document
//! with the step lines `0..p` replayed as one continuous script*, exactly
//! the way the tutorial player and the golden tests replay a level. Every
//! position change re-derives the state by prefix replay (milliseconds at
//! tutorial scale), so stepping, rewinding, and editing share one code path
//! and can never disagree with what a shipped level would do. The emitted
//! level's `solution` is the full replay's end state — such a level passes
//! the golden-replay test by construction.
//!
//! Execution halts at the first invalid line: a skipped step would make
//! every later line replay against the wrong state.

use crate::document_ng::Document;
use crate::schema::model as schema;

use super::headless::Headless;
use super::parse::{Line, ParseError, parse_line};
use super::step::{Script, Step};

/// One line of the script buffer, as last parsed.
pub struct LineEntry {
    pub source: String,
    pub kind: LineKind,
}

pub enum LineKind {
    /// Empty, whitespace, or a comment — traversed silently.
    Blank,
    /// A `step key=… en=…` narration marker — starts a group, executes as a
    /// no-op.
    Marker {
        key: String,
        narration: String,
    },
    Step(Step),
    /// Doesn't parse; execution refuses to pass it.
    Invalid(ParseError),
}

/// What a transport action did.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StepOutcome {
    Advanced,
    /// Parked at `line`: it is invalid (or failed to resolve at runtime) and
    /// execution refuses to pass it.
    Halted(usize),
    AtEnd,
    AtStart,
}

pub struct Debugger {
    /// The captured starting document, in document KDL — replays parse it
    /// exactly like a level file's `initial`.
    initial_kdl: String,
    lines: Vec<LineEntry>,
    /// Lines `0..position` are applied; `position` is the next line to run.
    position: usize,
    harness: Headless,
    /// A step line whose doc-anchored target named a missing object — a
    /// *runtime* halt (the line parses fine), reported against its line.
    runtime_halt: Option<(usize, String)>,
}

const NAME: &str = "script-debugger";

impl Debugger {
    /// A debugger over `doc` as the starting state ("Init" in the window).
    pub fn new(doc: &Document) -> Self {
        let initial_kdl = schema::Document::from(doc).to_kdl();
        let harness = Headless::new(Some(&initial_kdl), NAME);
        Self {
            initial_kdl,
            lines: Vec::new(),
            position: 0,
            harness,
            runtime_halt: None,
        }
    }

    /// Re-capture the starting document ("Init" again): the script text
    /// stays, the position rewinds to the top of the new baseline.
    pub fn init(&mut self, doc: &Document) {
        self.initial_kdl = schema::Document::from(doc).to_kdl();
        // Replaying zero lines can't fail.
        let _ = self.replay(0);
    }

    /// Replace the script text (the editor's buffer, verbatim). The position
    /// clamps to the first changed line — everything at or past an edit no
    /// longer describes the state that was replayed through it.
    pub fn set_text(&mut self, text: &str) {
        let new_lines: Vec<LineEntry> = text
            .split('\n')
            .map(|source| LineEntry {
                kind: match parse_line(source) {
                    Ok(Line::Blank) => LineKind::Blank,
                    Ok(Line::Marker { key, narration }) => LineKind::Marker { key, narration },
                    Ok(Line::Step(step)) => LineKind::Step(step),
                    Err(e) => LineKind::Invalid(e),
                },
                source: source.to_owned(),
            })
            .collect();
        let first_change = self
            .lines
            .iter()
            .zip(&new_lines)
            .position(|(old, new)| old.source != new.source)
            .unwrap_or_else(|| self.lines.len().min(new_lines.len()));
        self.lines = new_lines;
        if first_change < self.position {
            // A failure parks the position at the failing line, which is all
            // an edit-triggered rewind needs.
            let _ = self.replay(first_change);
        }
    }

    pub fn text(&self) -> String {
        let sources: Vec<&str> = self.lines.iter().map(|l| l.source.as_str()).collect();
        sources.join("\n")
    }

    pub fn lines(&self) -> &[LineEntry] {
        &self.lines
    }

    /// The next line to execute — where the editor's marker sits.
    pub fn position(&self) -> usize {
        self.position
    }

    /// The line execution is parked on for a *runtime* failure, with the
    /// message (parse failures live on the lines themselves).
    pub fn runtime_halt(&self) -> Option<&(usize, String)> {
        self.runtime_halt.as_ref()
    }

    /// Execute the next step line (traversing blanks and markers), halting
    /// at an invalid line.
    pub fn step_forward(&mut self) -> StepOutcome {
        loop {
            match self.lines.get(self.position).map(|l| &l.kind) {
                None => return StepOutcome::AtEnd,
                Some(LineKind::Blank | LineKind::Marker { .. }) => self.position += 1,
                Some(LineKind::Invalid(_)) => return StepOutcome::Halted(self.position),
                Some(LineKind::Step(_)) => {
                    let target = self.position + 1;
                    return match self.replay(target) {
                        Ok(()) => StepOutcome::Advanced,
                        Err(line) => StepOutcome::Halted(line),
                    };
                }
            }
        }
    }

    /// Rewind past the previous step line (to the state just before it).
    pub fn step_back(&mut self) -> StepOutcome {
        let previous = self.lines[..self.position]
            .iter()
            .rposition(|l| matches!(l.kind, LineKind::Step(_)));
        if let Some(line) = previous {
            let _ = self.replay(line);
            StepOutcome::Advanced
        } else {
            let _ = self.replay(0);
            StepOutcome::AtStart
        }
    }

    /// Back to the initial state, position 0.
    pub fn reset(&mut self) {
        let _ = self.replay(0);
    }

    /// The state at the current position, for mirroring into the app editor.
    pub fn document(&self) -> &Document {
        self.harness.document()
    }

    pub fn projected(&self) -> schema::Document {
        self.harness.projected()
    }

    /// Derive the state at `target` from scratch: reset to the initial
    /// document and replay the step lines `0..target` as one continuous
    /// script. On a runtime resolution failure, parks at the failing line
    /// (the frames before it have run — the same state a full replay up to
    /// that line produces) and records the halt.
    fn replay(&mut self, target: usize) -> Result<(), usize> {
        self.runtime_halt = None;
        self.harness.reset(Some(&self.initial_kdl), NAME);
        let step_lines: Vec<usize> = self.lines[..target]
            .iter()
            .enumerate()
            .filter_map(|(i, l)| matches!(l.kind, LineKind::Step(_)).then_some(i))
            .collect();
        let script = Script::new(
            step_lines
                .iter()
                .filter_map(|&i| match self.lines[i].kind {
                    LineKind::Step(step) => Some(step),
                    _ => None,
                })
                .collect(),
        );
        match self.harness.run_script(&script) {
            Ok(()) => {
                self.position = target;
                Ok(())
            }
            Err(e) => {
                // `e.step` indexes the prefix script; map back to its line.
                let line = step_lines.get(e.step).copied().unwrap_or(target);
                self.position = line;
                self.runtime_halt = Some((line, format!("names a missing object: {:?}", e.target)));
                Err(line)
            }
        }
    }

    /// The first invalid line, if any — emission refuses while one exists.
    pub fn first_invalid(&self) -> Option<usize> {
        self.lines
            .iter()
            .position(|l| matches!(l.kind, LineKind::Invalid(_)))
    }

    /// Assemble the complete level file: metadata, the captured initial, the
    /// editor text wrapped into `step {}` groups at the marker lines —
    /// verbatim — and the full replay's end state as the solution.
    pub fn emit_level(&self, meta: &LevelMeta) -> Result<String, String> {
        if let Some(line) = self.first_invalid() {
            return Err(format!("line {} is invalid", line + 1));
        }
        let has_steps = self
            .lines
            .iter()
            .any(|l| matches!(l.kind, LineKind::Step(_)));
        if !has_steps {
            return Err("the script has no steps".into());
        }
        // The solution: a scratch full replay, leaving the current position
        // alone.
        let mut scratch = Headless::new(Some(&self.initial_kdl), NAME);
        let script = Script::new(
            self.lines
                .iter()
                .filter_map(|l| match l.kind {
                    LineKind::Step(step) => Some(step),
                    _ => None,
                })
                .collect(),
        );
        scratch
            .run_script(&script)
            .map_err(|e| format!("step {} names a missing object", e.step))?;
        let solution = scratch.projected();
        Ok(emit(meta, &self.initial_kdl, &solution, &self.lines))
    }
}

/// Metadata for [`Debugger::emit_level`]. `camera` is grid cells
/// `(x, y, w, h)`; `None` derives it from the solution's top (sheet) block.
pub struct LevelMeta {
    pub id: String,
    pub title: String,
    pub instructions: String,
    pub camera: Option<(i32, i32, i32, i32)>,
}

fn emit(
    meta: &LevelMeta,
    initial: &str,
    solution: &schema::Document,
    lines: &[LineEntry],
) -> String {
    use std::fmt::Write;
    let mut out = String::new();
    let title = if meta.title.trim().is_empty() {
        meta.id.clone()
    } else {
        meta.title.trim().to_owned()
    };
    let _ = writeln!(
        out,
        "level {} title={} {{",
        kdl_quote(meta.id.trim()),
        kdl_quote(&title)
    );
    let _ = writeln!(
        out,
        "    instructions {}",
        kdl_quote(meta.instructions.trim())
    );
    let (cx, cy, cw, ch) = meta.camera.unwrap_or_else(|| solution_camera(solution));
    let _ = writeln!(out, "    camera x={cx} y={cy} w={cw} h={ch}");
    let _ = writeln!(
        out,
        "    initial {{\n{}\n    }}",
        indent(initial.trim_end(), "        ")
    );
    let _ = writeln!(
        out,
        "    solution {{\n{}\n    }}",
        indent(solution.to_kdl().trim_end(), "        ")
    );
    let mut group_open = false;
    for entry in lines {
        match &entry.kind {
            LineKind::Blank | LineKind::Invalid(_) => {}
            LineKind::Marker { key, narration } => {
                if group_open {
                    let _ = writeln!(out, "    }}");
                }
                let _ = writeln!(
                    out,
                    "    step key={} en={} {{",
                    kdl_quote(key),
                    kdl_quote(narration)
                );
                group_open = true;
            }
            LineKind::Step(_) => {
                if !group_open {
                    // Steps before the first marker: an implicit opening group
                    // the author renames in the file.
                    let _ = writeln!(out, "    step key=\"step-1\" en=\"step-1\" {{");
                    group_open = true;
                }
                let _ = writeln!(out, "        {}", entry.source.trim());
            }
        }
    }
    if group_open {
        let _ = writeln!(out, "    }}");
    }
    out.push_str("}\n");
    out
}

fn kdl_quote(s: &str) -> String {
    let escaped = s
        .replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('\n', "\\n");
    format!("\"{escaped}\"")
}

/// Indent a document snippet to sit inside a `{}` block.
fn indent(kdl: &str, by: &str) -> String {
    kdl.lines()
        .map(|l| {
            if l.is_empty() {
                String::new()
            } else {
                format!("{by}{l}")
            }
        })
        .collect::<Vec<_>>()
        .join("\n")
}

/// The camera fallback: the solution's top (sheet) block, which the document
/// pipeline keeps sized around the content; else a bounding box.
fn solution_camera(solution: &schema::Document) -> (i32, i32, i32, i32) {
    if let Some(top) = solution.blocks.iter().find(|b| b.id == solution.top) {
        let (w, h) = (
            i32::try_from(top.w).unwrap_or(i32::MAX),
            i32::try_from(top.h).unwrap_or(i32::MAX),
        );
        return (top.x, top.y, w, h);
    }
    let xs = || solution.blocks.iter();
    let x0 = xs().map(|b| b.x).min().unwrap_or(0);
    let y0 = xs().map(|b| b.y).min().unwrap_or(0);
    let far = |b: &schema::Block| b.x.saturating_add(i32::try_from(b.w).unwrap_or(i32::MAX));
    let low = |b: &schema::Block| b.y.saturating_add(i32::try_from(b.h).unwrap_or(i32::MAX));
    let x1 = xs().map(far).max().unwrap_or(24);
    let y1 = xs().map(low).max().unwrap_or(20);
    (x0 - 2, y0 - 2, (x1 - x0) + 4, (y1 - y0) + 4)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::widget::drawing::finalize_load;

    const INITIAL: &str = r#"
top "b0"

block "b0" x=0 y=0 w=24 h=20 {
    title "sheet"
}
"#;

    const SCRIPT: &str = r#"step key="pick" en="Pick the New Block tool"
highlight "tool:new-block" secs=0.3
click "tool:new-block"
step key="place" en="Click two corners"
move-to "8,6" secs=0.3
click "8,6"
move-to "16,13" secs=0.3
click "16,13"
type "12,14" text="CPU" secs=0.5"#;

    fn initial_doc() -> Document {
        let mut doc = crate::document_ng::schema_convert::from_kdl(INITIAL, "test").unwrap();
        finalize_load(&mut doc);
        doc
    }

    fn debugger_with_script() -> Debugger {
        let mut debugger = Debugger::new(&initial_doc());
        debugger.set_text(SCRIPT);
        debugger
    }

    fn titles(doc: &schema::Document) -> Vec<String> {
        doc.blocks
            .iter()
            .filter_map(|b| b.title.as_ref().map(|t| t.name.clone()))
            .collect()
    }

    fn run_to_end(debugger: &mut Debugger) {
        while debugger.step_forward() == StepOutcome::Advanced {}
    }

    #[test]
    fn stepping_to_the_end_builds_the_block() {
        let mut debugger = debugger_with_script();
        run_to_end(&mut debugger);
        assert_eq!(debugger.step_forward(), StepOutcome::AtEnd);
        let projected = debugger.projected();
        assert_eq!(projected.blocks.len(), 2);
        assert!(titles(&projected).contains(&"CPU".to_owned()));
    }

    /// Stepping back un-does the last step line; stepping forward again
    /// re-derives the identical state (prefix replay is the single truth).
    #[test]
    fn stepping_back_and_forward_is_deterministic() {
        let mut debugger = debugger_with_script();
        run_to_end(&mut debugger);
        let at_end = debugger.projected();

        assert_eq!(debugger.step_back(), StepOutcome::Advanced);
        assert!(
            !titles(&debugger.projected()).contains(&"CPU".to_owned()),
            "the type line should be un-done"
        );
        assert_eq!(debugger.step_forward(), StepOutcome::Advanced);
        assert_eq!(debugger.projected(), at_end);
    }

    #[test]
    fn reset_returns_to_the_initial_state() {
        let mut debugger = debugger_with_script();
        let initial = debugger.projected();
        run_to_end(&mut debugger);
        assert_ne!(debugger.projected(), initial);
        debugger.reset();
        assert_eq!(debugger.position(), 0);
        assert_eq!(debugger.projected(), initial);
    }

    /// An invalid line is a wall: execution parks on it, repeated stepping
    /// stays parked, and the state is the prefix before it.
    #[test]
    fn execution_halts_at_the_first_invalid_line() {
        let mut debugger = Debugger::new(&initial_doc());
        debugger.set_text("click \"tool:new-block\"\nwiggle \"1,1\"\nmove-to \"8,6\" secs=0.3");
        assert_eq!(debugger.step_forward(), StepOutcome::Advanced);
        let before = debugger.projected();
        assert_eq!(debugger.step_forward(), StepOutcome::Halted(1));
        assert_eq!(debugger.step_forward(), StepOutcome::Halted(1));
        assert_eq!(debugger.position(), 1);
        assert_eq!(debugger.projected(), before);
    }

    /// A line that parses but names a missing object halts at runtime.
    #[test]
    fn a_missing_target_halts_at_runtime() {
        let mut debugger = Debugger::new(&initial_doc());
        debugger.set_text("drag \"block:ghost\" \"4,4\" secs=0.3");
        assert_eq!(debugger.step_forward(), StepOutcome::Halted(0));
        assert!(debugger.runtime_halt().is_some());
    }

    /// Editing a line clamps the position back to it — the state past an
    /// edit no longer describes what was replayed.
    #[test]
    fn editing_an_executed_line_rewinds_to_it() {
        let mut debugger = debugger_with_script();
        run_to_end(&mut debugger);
        let mut text = debugger.text();
        text = text.replace("click \"8,6\"", "click \"9,6\"");
        debugger.set_text(&text);
        assert!(debugger.position() <= 5);
        assert!(!titles(&debugger.projected()).contains(&"CPU".to_owned()));
    }

    /// The emitted level round-trips through the real level parser and — the
    /// by-construction property — replays to exactly its stored solution.
    #[test]
    fn emitted_level_replays_to_its_solution_by_construction() {
        let mut debugger = debugger_with_script();
        run_to_end(&mut debugger);
        let text = debugger
            .emit_level(&LevelMeta {
                id: "authored".into(),
                title: "Authored".into(),
                instructions: "Do the thing.".into(),
                camera: None,
            })
            .unwrap();
        let level = crate::tutorial::level::Level::parse(Box::leak(text.into_boxed_str()))
            .unwrap_or_else(|e| panic!("{e}"));
        assert_eq!(level.steps.len(), 2);
        assert_eq!(level.steps[0].key, "pick");
        assert_eq!(level.steps[1].key, "place");

        let mut harness = Headless::new(level.initial_kdl, &level.id);
        harness.run_script(&level.script).unwrap();
        let mut solution =
            crate::document_ng::schema_convert::from_kdl(level.solution_kdl, &level.id).unwrap();
        finalize_load(&mut solution);
        assert_eq!(harness.projected(), schema::Document::from(&solution));
    }

    #[test]
    fn emission_refuses_invalid_lines_and_empty_scripts() {
        let meta = LevelMeta {
            id: "x".into(),
            title: String::new(),
            instructions: String::new(),
            camera: None,
        };
        let mut debugger = Debugger::new(&initial_doc());
        assert!(debugger.emit_level(&meta).is_err());
        debugger.set_text("wiggle \"1,1\"");
        assert!(debugger.emit_level(&meta).unwrap_err().contains("line 1"));
    }
}