fix: keep a block comment leading a later statement on its own line

[MildlyMeticulous]

A block comment before a statement that follows another is formatted inline on the first pass but moved onto its own line on the second, so formatting isn't idempotent:

format('SELECT 1; /* c */ COMMIT;');
// => "SELECT\n  1;\n\n/* c */ COMMIT;"
// reformatted => "SELECT\n  1;\n\n/* c */\nCOMMIT;"

Same shape as #952, one level up. That fix made a block comment standalone when layout.isAtStartOfLine(), but formatAst gives each statement its own Layout, so for a leading comment the layout is still empty and isAtStartOfLine() falls through to return false. Statements are joined with newlines, so every statement after the first does start on a line — the second pass sees that newline as the comment's precedingWhitespace and flips the decision.

Layout now takes whether its statement is preceded by others, and an empty layout reports isAtStartOfLine() accordingly. The first statement is unaffected, so a leading comment on the whole query still formats inline as before.

Found by fuzzing format(format(x)) === format(x) with comments injected at every token boundary: 14,427 variants over 14 dialects, 10 failures before, 0 after. It reproduces in 11 of 21 dialects and for any keyword-only statement — COMMIT, ROLLBACK, BEGIN, END, GO, USE, VACUUM, ANALYZE, SAVEPOINT. Statements with clauses are stable because the following keyword forces the newline anyway.

5,861 tests pass; tsc, eslint and prettier clean.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: bd34be73-cb71-49aa-a22b-499c9c50c3cc

📥 Commits

Reviewing files that changed from the base of the PR and between aa8efae and 67ee978.

📒 Files selected for processing (3)

• src/formatter/Formatter.ts
• src/formatter/Layout.ts
• test/features/comments.ts

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Improved formatting for block comments between statements by placing them on their own line.
  • Ensured formatted output remains consistent when formatting is applied repeatedly.

• Tests

  • Added coverage for comment placement and formatting consistency after statement delimiters.

Walkthrough

The formatter now tracks whether each statement follows another statement, passes that state into Layout, and uses it when determining line starts. A regression test verifies standalone block-comment placement and formatting idempotency.

Changes

Statement layout formatting

Layer / File(s)	Summary
Track statement line-start state src/formatter/Layout.ts	Layout stores whether its statement starts on a new line, and isAtStartOfLine() uses that state for indentation-only layouts.
Propagate statement position and validate comments src/formatter/Formatter.ts, test/features/comments.ts	Statement indexes are passed into Layout, with a regression test covering block-comment placement and idempotent formatting.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• sql-formatter-org/sql-formatter#952: Changes related Layout.isAtStartOfLine() semantics for standalone block-comment formatting.

Suggested reviewers: nene, sarathfrancis90

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main fix: keeping block comments before later statements on their own line.
Description check	✅ Passed	The description is directly about the same idempotency bug and the formatting fix in this changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nene]

Thanks for the PR. Sorry for the lack of attention. I'm currently pretty busy. Maybe I'll get to reviewing this on Sunday or next week.

[nene]

We don't really need to perform statement-counting to achieve this fix.

And we're lacking tests.

See the comment that outlines a simpler way to fix this problem.

[nene]

Looks like the same fix can be achieved by just replacing this with:

return true;

But we're lacking on tests that would demonstrate a need for something more complex than that.

Layout case

This is definitely OK fix inside the Layout class, which gets constructed to format every separate SQL statement. And each statement will start from a new line, including the first one.

We might want to add a test that checks what happens when formatting a block-comment before a first SQL statement, like:

  it('keeps first block comment on its own line', () => {
    const sql = '/* c1 */ SELECT 1;';
    const result = dedent`
      /* c1 */
      SELECT
        1;
    `;
    expect(format(sql)).toBe(result);
  });

InlineLayout case

It's not so OK with the InlineLayout class, because that one is used to format expressions inside parenthesis, which never form a new line. But currently our tests don't cover this scenario well. We're missing a test like this:

  it('preserves inline block-comment', () => {
    const sql = 'SELECT (/* c */ 1 + 2);';
    const result = dedent`
      SELECT
        (/* c */ 1 + 2);
    `;
    expect(format(sql)).toBe(result);
  });

To make that test pass, we should just override the isAtStartOfLine()method in InlineLayout with one that always returns false.