ast: tagged, snake_case JSON output for parse and analyze

[kyleconroy]

Reworks the JSON that sqlc parse and sqlc analyze --ast print, in three commits. Replaces #4591, which got the same tagging from a hand-written reflective encoder; this version gets it from stock encoding/json with no custom marshaller in the tree walk.

Tag every node with its type

ast.Node is an interface, so the JSON encoding carried no record of which node a given object was. Nodes with no fields of their own — A_Star, Null, TODO — all encoded as {}, and an empty List was indistinguishable from them. On INSERT ... RETURNING *, the star and four untranslated clauses printed as the same empty object.

Every node struct now declares a zero-sized marker as its first field:

type SelectStmt struct {
	Tag NodeTag[SelectStmt] `json:"tag"`
	...
}

encoding/json calls MarshalJSON on the field, and the generic type parameter carries the node's identity to it at compile time — no encoder walks the tree, plain json.Marshal of any node is tagged. The zero value is valid, so the engines' struct literals are untouched, and the field is zero-sized, so nodes cost the same memory.

The marker's UnmarshalJSON accepts only the containing node's name, so a document decoded into the wrong node type is an error (node tagged "RangeVar" decoded into SortBy) instead of a silently misfielded tree.

tag as the key avoids every collision: encoding/json matches field names case-insensitively on decode, so kind would capture A_Expr.Kind, type the eight nodes with a Type field, and node would silently capture SortBy.Node. Because the tag is a real field rather than a key injected beside the fields, nothing can shadow it.

Omit absent fields

25% of the keys in typical output were null and another 9% were empty containers. Pointer, slice, interface and map fields now carry ,omitempty; scalars deliberately don't, because zero is a value the parser can find: stmt_location is 0 for the first statement in a file, and LIMIT 0 parses to an ival of 0.

This also drops empty (not just nil) lists, a small normalization: the dolphin converter builds Items as an empty slice where the postgresql one leaves it nil, so the same SQL printed different JSON per engine.

snake_case field names

Every node field gets an explicit json tag with the snake_case form of its name: stmt_location, from_clause, relname. The keys read as JSON rather than Go leaking through, match the names libpg_query uses for the same fields in its own JSON output, and match analyze's existing columns/params keys. Field renames become a compile-time-visible decision about the JSON rather than a silent output change.

Sample, for INSERT ... RETURNING *:

"returning_list": {
  "tag": "List",
  "items": [
    {
      "tag": "ResTarget",
      "val": {
        "tag": "ColumnRef",
        "fields": { "tag": "List", "items": [ { "tag": "A_Star" } ] },
        "location": 93
      },
      "location": 93
    }
  ]
}

Notes

• The codemod touched all 255 node structs (the set with pointer-receiver Pos()), correctly excluding the 76 non-struct Node implementers (enum types with Pos methods) and the fmt/comment structs. 702 reference-typed fields carry omitempty; 528 scalar fields carry a name-only tag; no two fields in any struct collapse to the same snake key.
• docs/howto/parse.md already notes the JSON shape is beta; it gains sections on node tags, absent fields, and the naming convention. TODO tags are documented as "parsed but not represented in the AST", not "absent from the query".
• Validation against ast: tag node types and omit absent fields in JSON output #4591: the first two commits were diffed golden-by-golden against the reflective encoder's output — byte-identical except the mysql empty-list normalization called out above.

Testing

Covered end to end: go test --tags=examples -timeout 20m ./... passes with PostgreSQL and MySQL running, plus go vet and gofmt. Eight goldens regenerated (seven parse_basic, analyze_ast/postgresql); the other 26 parse/analyze cases regenerate byte-identical, confirming nothing outside AST output moved.