debug-formatter

Debug a SQL formatter bug using red-green testing and pipeline tracing.

Instructions

1. Reproduce (RED)

Add a failing test to syntaqlite/tests/fmt_comments.rs (comment bugs) or the relevant tests/fmt_diff_tests/*.py file. Always eprintln! the actual output:

#[test]
fn descriptive_name() {
    let input = "...";
    let out = fmt(input);
    eprintln!("=== actual ===\n{out}=== end ===");
    assert_eq!(out, "...\n");
}

Run it and confirm RED:

cargo test -p syntaqlite --features fmt,sqlite --test fmt_comments TEST_NAME -- --nocapture

2. Trace the pipeline

Work through these layers to find the root cause:

3. Common bug patterns

• Blank line between comments: Two consecutive drains both produce hardline + comment + hardline; back-to-back hardlines = blank line. Fix via continuation flag on drain_keyword_interior.
• Comment on wrong side of keyword: flush_drain for interior comments runs before keyword text is emitted. Check flush vs keyword append ordering in the Keyword match arm.
• Comment lost: has_non_comment_text guard stops drain_before when a keyword sits between the comment and target offset. Multi-word interiors need skip_text_check: true.
• Pending dropped: flush_drain with leading != NIL zeroes pending. If pending held a LINE from the clause template, that break is lost.

4. Fix and verify (GREEN)

cargo test -p syntaqlite --features fmt,sqlite --test fmt_comments TEST_NAME -- --nocapture
cargo test -p syntaqlite --features fmt,sqlite
cargo build -p syntaqlite-cli && tools/run-integration-tests

All 7 integration suites must pass (including ~650 idempotency checks).