debug-formatter

name	debug-formatter
description	Debug a SQL formatter bug. Use when the user reports incorrect formatting, such as wrong whitespace, misplaced comments, or blank lines.
user_invocable	true

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:

Layer	File	What to check
Grammar	syntaqlite-buildtools/parser-nodes/*.synq	fmt { } block; clause("KW", field) expands to IF_SET → LINE → KEYWORD → NEST(LINE, CHILD)
Bytecode compiler	syntaqlite-buildtools/src/dialect_codegen/fmt_compiler.rs	How Fmt::Clause, Fmt::Keyword compile to opcodes
Interpreter	syntaqlite/src/fmt/interpret.rs	Main loop in interpret_node; state = running (committed doc) + pending (deferred line breaks)
Comment drain	syntaqlite/src/fmt/comment.rs	drain_before(offset) respects has_non_comment_text guard; drain_keyword_interior() skips it for multi-word keywords
flush_drain	interpret.rs	Integrates DrainResult { trailing, leading } into running/pending; when leading != NIL, pending is dropped
Doc renderer	syntaqlite/src/fmt/doc.rs	Wadler-style; hardline always breaks, line breaks if group broken

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).