OpenParable
Skip to content
← Back to skills

Debug Formatter

Testing & Quality
debug-formatter

Debug Formatter is an Agent Skill for testing & quality published in the LalitMaganti/syntaqlite repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Debug a SQL formatter bug. Use when the user reports incorrect formatting output — wrong whitespace, misplaced comments, blank lines, etc.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/LalitMaganti/syntaqlite/blob/HEAD/.agents/skills/debug-formatter/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/debug-formatter, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

LayerFileWhat to check
Grammarsyntaqlite-buildtools/parser-nodes/*.synqfmt { } block; clause("KW", field) expands to IF_SET → LINE → KEYWORD → NEST(LINE, CHILD)
Bytecode compilersyntaqlite-buildtools/src/dialect_codegen/fmt_compiler.rsHow Fmt::Clause, Fmt::Keyword compile to opcodes
Interpretersyntaqlite/src/fmt/interpret.rsMain loop in interpret_node; state = running (committed doc) + pending (deferred line breaks)
Comment drainsyntaqlite/src/fmt/comment.rsdrain_before(offset) respects has_non_comment_text guard; drain_keyword_interior() skips it for multi-word keywords
flush_draininterpret.rsIntegrates DrainResult { trailing, leading } into running/pending; when leading != NIL, pending is dropped
Doc renderersyntaqlite/src/fmt/doc.rsWadler-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).