Address PR review: printer package, no line width, docs

- Extract the doc renderer into internal/sql/ast/printer; TrackedBuffer
  embeds printer.Buffer and keeps the AST-facing layer (node dispatch,
  comment emission) in the ast package, since every node's Format method
  names TrackedBuffer and moving it would create an import cycle.
- Drop the 80-column line width: like gofmt, fmt no longer rewraps lines
  on its own. AttachComments records which printer-modeled boundaries the
  author broke at, and boundary() keeps those breaks; one-line statements
  stay on one line.
- Fold the comment-free path into the attachment path: formatStmt always
  goes through formatWithComments, retiring formatRaw/verifyFormatted.
- Cobra: Short is now "Format SQL queries"; Long drops the
  comments-never-deleted sentence and the engine-support paragraph.
- Docs: rewrite howto/fmt.md for the no-width model with a regenerated
  example; update cli.md; regenerate the sqlite endtoend golden.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018MTvpHqNMadH12pTtsgUq2

Author: claude

docs/howto/fmt.md

@@ -5,32 +5,18 @@ canonical format. Each query is parsed with the engine's parser and printed
 back from the syntax tree, so formatting never depends on how the query was
 written — only on what it means.
 
-A statement that fits within 80 columns is printed on a single line. A longer
-statement breaks at clause boundaries (`FROM`, `WHERE`, `ORDER BY`, ...), and
-any part that still does not fit — a column list, an `AND`/`OR` chain, a
-parenthesized subquery — breaks again, indented one level deeper. This is the
-same layout model used by Prettier and by ruff's Python formatter: the printer
-lays each group of the statement out flat when it fits and breaks it when it
-does not.
-
-Comments are never deleted. The comments above each query are kept, including
-the [`-- name:`](../reference/query-annotations.md) annotation and multi-line
-`/* */` blocks, and a comment on the same line as a statement's closing
-semicolon stays attached to it.
+Like `gofmt`, the formatter does not impose a maximum line width. A statement
+written on a single line stays on a single line, and a statement the author
+broke across lines keeps its breaks: the printer notices which clause
+boundaries (`FROM`, `WHERE`, `ORDER BY`, ...) and list boundaries the author
+broke at and preserves them, normalizing indentation and spacing around them.
 
 Comments inside a statement are formatted along with it: each comment is
 anchored to the code around it by source position and printed back there —
 a comment trailing a select-list item stays with that item, a comment above
-a clause stays above its keyword — and a statement carrying comments keeps
-its multi-line shape. Any statement that cannot be proven to survive
-formatting unchanged is left exactly as written.
-
-Formatting currently supports the `sqlite` engine, whose parser surfaces the
-comments its lexer sees; other engines' query files are left untouched and
-gain support as their parsers are updated. Files that cannot be parsed
-without the compiler's preprocessing (for example, files using
-`sqlc.slice()` on engines whose parser rejects it) are also skipped; a
-skipped file is reported on standard error and left unchanged.
+a clause stays above its keyword — and a comment that runs to the end of its
+line breaks the statement open around it. Any statement that cannot be
+proven to survive formatting unchanged is left exactly as written.
 
 ## Usage
 
@@ -60,7 +46,10 @@ running `sqlc fmt` rewrites it to:
 
 ```sql
 -- name: GetAuthor :one
-SELECT id, name, bio FROM authors WHERE id = ? LIMIT 1;
+SELECT id, name, bio
+FROM authors
+WHERE id = ?
+LIMIT 1;
 
 -- name: SearchAuthors :many
 SELECT
@@ -69,10 +58,11 @@ SELECT
   bio,
   created_at
 FROM authors
-WHERE name LIKE ?
-  AND bio IS NOT NULL
-  AND id > ?
-  AND created_at > ?
-  AND name <> ?
+WHERE name LIKE ? AND bio IS NOT NULL AND id > ? AND created_at > ? AND name <> ?
 ORDER BY name;
 ```
+
+`GetAuthor` keeps the line breaks its author wrote; had it been written on
+one line, it would stay on one line. In `SearchAuthors`, the line comment
+cannot share a line with the code after it, so the statement breaks open
+around it, while the `WHERE` chain — written on one line — stays on one.

docs/reference/cli.md

@@ -10,7 +10,7 @@ Available Commands:
   completion  Generate the autocompletion script for the specified shell
   createdb    Create an ephemeral database
   diff        Compare the generated files to the existing files
-  fmt         Format query files
+  fmt         Format SQL queries
   generate    Generate source code from SQL
   help        Help about any command
   init        Create an empty sqlc.yaml settings file

internal/cmd/fmt.go

@@ -20,11 +20,11 @@ import (
 	"github.com/sqlc-dev/sqlc/internal/sql/sqlpath"
 )
 
-// fmtLineWidth is the line width formatted queries are wrapped to. A
-// statement whose flat form fits stays on one line; a longer one breaks at
-// clause boundaries, and any list or parenthesized region that still does
-// not fit breaks again one indentation level deeper.
-const fmtLineWidth = 80
+// noLineLimit renders without a maximum line width: like gofmt, fmt never
+// rewraps a line on its own. Breaks come from the author's own line breaks
+// at the boundaries the printer models, and from comments, which cannot
+// share a line with the code after them.
+const noLineLimit = 1 << 30
 
 // queryFormatter is what the fmt command needs from an engine: a parser
 // that surfaces the comments its lexer already scans (so statements and
@@ -51,18 +51,13 @@ func newQueryFormatter(engine config.Engine) queryFormatter {
 func newFmtCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "fmt",
-		Short: "Format query files",
+		Short: "Format SQL queries",
 		Long: `Format the SQL query files referenced by the configuration file.
 
 Each query is parsed with the engine's parser and printed back in a canonical
-form, with its comments kept where they were written. Comments are never
-deleted, and a statement that cannot be proven to survive formatting
-unchanged is left exactly as written. Files are rewritten in place; pass
---diff to print the changes to stdout instead.
-
-Formatting currently supports the sqlite engine; other engines' query files
-are left untouched and gain support as their parsers are updated to surface
-comments.`,
+form, with its comments kept where they were written. A statement that cannot
+be proven to survive formatting unchanged is left exactly as written. Files
+are rewritten in place; pass --diff to print the changes to stdout instead.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			defer trace.StartRegion(cmd.Context(), "fmt").End()
 			stderr := cmd.ErrOrStderr()
@@ -383,23 +378,10 @@ func isCommentLine(line string) bool {
 // original text when formatting cannot be proven to preserve the query.
 func formatStmt(f queryFormatter, raw *ast.RawStmt, orig string, interior []ast.Comment, src string) string {
 	fallback := strings.TrimSuffix(strings.TrimSpace(orig), ";") + ";"
-	if len(interior) > 0 {
-		// The reprinter path: interior comments are woven back in by
-		// position. Any failure to prove the result faithful keeps the
-		// statement as written.
-		if out, ok := formatWithComments(f, raw, interior, src); ok {
-			return out
-		}
-		return fallback
-	}
-	out := formatRaw(raw, f)
-	if strings.TrimSpace(strings.TrimSuffix(out, ";")) == "" {
-		return fallback
-	}
-	if !verifyFormatted(f, out) {
-		return fallback
+	if out, ok := formatWithComments(f, raw, interior, src); ok {
+		return out
 	}
-	return out
+	return fallback
 }
 
 // formatWithComments pretty-prints a statement with its interior comments
@@ -435,7 +417,7 @@ func prettyCommented(raw *ast.RawStmt, f queryFormatter, comments []ast.Comment,
 		}
 	}()
 	ct := ast.AttachComments(raw, f, comments, src)
-	out = ast.PrettyWithComments(raw, f, fmtLineWidth, ct)
+	out = ast.PrettyWithComments(raw, f, noLineLimit, ct)
 	if !ct.Exhausted() {
 		return ""
 	}
@@ -462,26 +444,3 @@ func sameComments(a, b []ast.Comment) bool {
 	}
 	return true
 }
-
-// formatRaw pretty-prints a statement's AST, turning a formatter panic into
-// an empty string so the caller falls back to the original text.
-func formatRaw(raw *ast.RawStmt, f queryFormatter) (out string) {
-	defer func() {
-		if r := recover(); r != nil {
-			out = ""
-		}
-	}()
-	return ast.Pretty(raw, f, fmtLineWidth)
-}
-
-// verifyFormatted reports whether the formatted SQL provably still means
-// the same thing: it must parse back as a single statement that formats to
-// itself. The comparison ignores case because some parsers normalize
-// keyword and identifier case.
-func verifyFormatted(f queryFormatter, formatted string) bool {
-	file, err := f.ParseFile(strings.NewReader(formatted))
-	if err != nil || len(file.Stmts) != 1 || file.Stmts[0].Raw == nil {
-		return false
-	}
-	return strings.EqualFold(formatRaw(file.Stmts[0].Raw, f), formatted)
-}

internal/endtoend/testdata/fmt/sqlite/stdout.txt

@@ -1,32 +1,32 @@
 --- a/query.sql
 +++ b/query.sql
-@@ -1,16 +1,15 @@
+@@ -1,12 +1,15 @@
  -- name: GetAuthor :one
++SELECT id, name, bio
++FROM authors
++WHERE id = ?
++LIMIT 1;
 -select  id,name , bio from   authors
 -where id =  ? limit 1;
-+SELECT id, name, bio FROM authors WHERE id = ? LIMIT 1;
 
  -- name: PickyQuery :many
--SELECT id, -- the primary key
--       name,
--       -- computed downstream
--       bio
 +SELECT
 +  id, -- the primary key
 +  name,
 +  -- computed downstream
 +  bio
+-SELECT id, -- the primary key
+-       name,
+-       -- computed downstream
+-       bio
  FROM authors
  -- soft-deleted rows are filtered
--WHERE bio IS NOT NULL
--  AND id > ?;
-+WHERE bio IS NOT NULL AND id > ?;
- 
- -- name: InlineBlock :many
+ WHERE bio IS NOT NULL
+@@ -16,5 +19,6 @@
  SELECT /* inline note */ id, name FROM authors ORDER BY name;
-@@ -17,4 +16,3 @@
 
  -- name: ListAuthors :many
++SELECT id, name, bio
++FROM authors
 -SELECT id, name, bio FROM authors
--ORDER BY name;
-+SELECT id, name, bio FROM authors ORDER BY name;
+ ORDER BY name;

internal/sql/ast/CLAUDE.md

@@ -7,7 +7,7 @@ This package defines the Abstract Syntax Tree (AST) nodes used by sqlc to repres
 ### Node Interface
 All AST nodes implement the `Node` interface with:
 - `Pos() int` - returns the source position
-- `Format(buf *TrackedBuffer)` - formats the node back to SQL
+- `Format(buf *TrackedBuffer, d format.Dialect)` - formats the node back to SQL
 
 ### TrackedBuffer
 The `TrackedBuffer` type (`print.go`) handles SQL formatting with dialect-specific behavior:
@@ -18,25 +18,38 @@ The `TrackedBuffer` type (`print.go`) handles SQL formatting with dialect-specif
 - `TypeName(ns, name string)` - formats type names (dialect-specific)
 
 ### Pretty printing
+The doc renderer lives in `ast/printer` (`printer.Buffer`), which knows
+nothing about AST nodes; `TrackedBuffer` embeds it and adds the
+AST-facing layer (`astFormat`, comment emission, anchors).
 `TrackedBuffer` records a Wadler-style document (the model behind Prettier
 and ruff): Format methods emit text plus layout tokens, and the renderer
 decides which break opportunities become newlines.
 
-- `line()` - a space when the group fits on one line, a newline otherwise
-- `softline()` - nothing when the group fits, a newline otherwise
-- `group()` / `endGroup()` - a region laid out flat when its width fits
-- `indent()` / `endIndent()` - one level deeper (2 spaces) after breaks
-- `joinComma(list)` - joins items with `,` + `line()`
+- `Line()` - a space when the group fits on one line, a newline otherwise
+- `Softline()` - nothing when the group fits, a newline otherwise
+- `Group()` / `EndGroup()` - a region laid out flat when its width fits
+- `Indent()` / `EndIndent()` - one level deeper (2 spaces) after breaks
+- `Breaker()` - forces every enclosing group to break (measures as
+  infinitely wide)
+- `joinComma(list)` - joins items with `,` + `Line()`
 - `condition(node)` - clause-level AND/OR chain without outer parentheses,
   one branch per line when broken
 
 `ast.Format(n, d)` renders on a single line (all breaks collapse);
 `ast.Pretty(n, d, width)` breaks lines to fit `width` columns. Statement
-Format methods open a group and put `line()` before each clause keyword
+Format methods open a group and put `Line()` before each clause keyword
 (`FROM`, `WHERE`, ...), so a statement that fits stays on one line and a
 long one breaks at clause boundaries. When adding a Format method, write
 tokens so the flat rendering is correct SQL; layout tokens are optional.
 
+The fmt command does not pass a real width: like gofmt it never rewraps
+on its own, so it prints with an effectively infinite width and defers
+to the author's line breaks instead. `AttachComments` records, for each
+emission-point marker, whether its neighbouring printed nodes sat on
+different source lines; when they did, `boundary()` emits a `Breaker()`
+there on the real print, so the group the author broke stays broken and
+everything else stays flat.
+
 ### Comments
 `ast.File{Stmts, Comments}` is what a comment-surfacing parser returns
 (SQLite via meyer's ParseFile). `AttachComments(raw, d, comments, src)`

internal/sql/ast/bool_expr.go

@@ -43,26 +43,26 @@ func (n *BoolExpr) Format(buf *TrackedBuffer, d format.Dialect) {
 			op = "OR "
 		}
 		buf.WriteString("(")
-		buf.group()
-		buf.indent()
-		buf.softline()
+		buf.Group()
+		buf.Indent()
+		buf.Softline()
 		if items(n.Args) && op != "" {
 			first := true
 			for _, item := range n.Args.Items {
 				if _, ok := item.(*TODO); ok {
 					continue
 				}
 				if !first {
-					buf.line()
+					buf.Line()
 					buf.WriteString(op)
 				}
 				first = false
 				buf.astFormat(item, d)
 			}
 		}
-		buf.endIndent()
-		buf.softline()
-		buf.endGroup()
+		buf.EndIndent()
+		buf.Softline()
+		buf.EndGroup()
 		buf.WriteString(")")
 	}
 }

internal/sql/ast/comment.go

@@ -64,6 +64,15 @@ type CommentTable struct {
 	end    []int
 	taken  []bool
 	nTaken int
+	// breaks marks the emission points where the author broke the line:
+	// the printer keeps those breaks, gofmt-style, instead of imposing a
+	// line width.
+	breaks map[Node]bool
+}
+
+// breakAt reports whether the author broke the line at this emission point.
+func (t *CommentTable) breakAt(n Node) bool {
+	return t != nil && t.breaks[n]
 }
 
 // Exhausted reports whether every attached comment was printed.
@@ -169,6 +178,33 @@ func AttachComments(raw *RawStmt, d format.Dialect, comments []Comment, src stri
 		}
 	}
 	table.taken = make([]bool, len(table.recs))
+
+	// Record where the author broke the line: an emission point whose
+	// neighbouring printed nodes sit on different source lines. The printer
+	// keeps these breaks (and only imposes new ones for comments), so the
+	// statement's shape stays the author's.
+	table.breaks = make(map[Node]bool)
+	for i, a := range anchors {
+		if !a.marker {
+			continue
+		}
+		prevPos, nextPos := -1, -1
+		for j := i - 1; j >= 0; j-- {
+			if !anchors[j].marker {
+				prevPos = anchors[j].pos
+				break
+			}
+		}
+		for j := i + 1; j < len(anchors); j++ {
+			if !anchors[j].marker {
+				nextPos = anchors[j].pos
+				break
+			}
+		}
+		if prevPos >= 0 && nextPos >= 0 && lineOf(prevPos) != lineOf(nextPos) {
+			table.breaks[a.node] = true
+		}
+	}
 	return table
 }
 
@@ -197,4 +233,3 @@ func collectAnchors(n Node, d format.Dialect) (out []anchor) {
 	}
 	return out
 }
-

internal/sql/ast/common_table_expr.go

@@ -32,12 +32,12 @@ func (n *CommonTableExpr) Format(buf *TrackedBuffer, d format.Dialect) {
 		buf.WriteString(")")
 	}
 	buf.WriteString(" AS (")
-	buf.group()
-	buf.indent()
-	buf.softline()
+	buf.Group()
+	buf.Indent()
+	buf.Softline()
 	buf.astFormat(n.Ctequery, d)
-	buf.endIndent()
-	buf.softline()
-	buf.endGroup()
+	buf.EndIndent()
+	buf.Softline()
+	buf.EndGroup()
 	buf.WriteString(")")
 }