goldeneye: move the shape of an engine's answer into its own package

The JSON sqlc analyze prints — a query, its columns, its parameters and
their types — lived in endtoend beside the case finder. It is its own
thing, so it moves to the analysis package, and the Analyzed prefix goes
with it: analysis.Query, analysis.Column, analysis.Param.

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

Author: claude

internal/goldeneye/README.md

@@ -96,8 +96,8 @@ the hand-written files alone, and the checks do not look at them.
   `internal/core/seed`, and the helpers that write a generated set of files
   into an engine directory or diff it against what is committed.
 - `endtoend/` — finds the analyze cases, splits their query files, and
-  holds the shape of an engine's answer, which it compares with a case's
-  committed output.
+  compares an engine's answer with a case's committed output.
+- `analysis/` — the shape of that answer: the JSON `sqlc analyze` prints.
 - `postgresql/`, `duckdb/`, `clickhouse/`, `sqlite/` — one package per
   engine, each exposing `Locate`, `Version` and `Generate`, `Analyze` where
   the engine has an analysis check, and tests that run the checks.

internal/goldeneye/endtoend/output.go internal/goldeneye/analysis/analysis.gointernal/goldeneye/endtoend/output.go renamed to internal/goldeneye/analysis/analysis.go

@@ -1,34 +1,33 @@
-package endtoend
+// Package analysis is the shape of an engine's answer about a query: the
+// JSON `sqlc analyze` prints, so that a case's committed stdout.json can be
+// compared with what the database itself reports, byte for byte.
+package analysis
 
 import (
 	"bytes"
 	"encoding/json"
 )
 
-// An engine's answer is written in the JSON `sqlc analyze` prints, so that
-// a case's committed stdout.json can be compared with it byte for byte.
-
-// AnalyzedQuery is what was found out about one query.
-type AnalyzedQuery struct {
-	Name    string           `json:"name"`
-	Cmd     string           `json:"cmd"`
-	Columns []AnalyzedColumn `json:"columns"`
-	Params  []AnalyzedParam  `json:"params"`
+// Query is what was found out about one query.
+type Query struct {
+	Name    string   `json:"name"`
+	Cmd     string   `json:"cmd"`
+	Columns []Column `json:"columns"`
+	Params  []Param  `json:"params"`
 }
 
-// AnalyzedColumn describes a result column, or the column a parameter
-// stands in for.
-type AnalyzedColumn struct {
+// Column describes a result column, or the column a parameter stands in
+// for.
+type Column struct {
 	Name  string    `json:"name"`
 	Type  *TypeExpr `json:"type,omitempty"`
 	Table string    `json:"table,omitempty"`
 }
 
-// AnalyzedParam is one parameter and what it is compared with or assigned
-// to.
-type AnalyzedParam struct {
-	Number int            `json:"number"`
-	Column AnalyzedColumn `json:"column"`
+// Param is one parameter and what it is compared with or assigned to.
+type Param struct {
+	Number int    `json:"number"`
+	Column Column `json:"column"`
 }
 
 // TypeExpr is a type as a call expression: a lowercased name applied to an
@@ -51,7 +50,7 @@ type TypeArg struct {
 }
 
 // Encode prints the answer the way sqlc analyze does.
-func Encode(queries []AnalyzedQuery) ([]byte, error) {
+func Encode(queries []Query) ([]byte, error) {
 	var buf bytes.Buffer
 	enc := json.NewEncoder(&buf)
 	enc.SetIndent("", "  ")

internal/goldeneye/clickhouse/analyze.go

@@ -8,13 +8,14 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/sqlc-dev/sqlc/internal/goldeneye/analysis"
 	"github.com/sqlc-dev/sqlc/internal/goldeneye/endtoend"
 )
 
 // analyze runs every query against the schema and fixture and records what
 // ClickHouse reports about each.
-func analyze(ctx context.Context, l local, schema, fixture string, queries []endtoend.Query) ([]endtoend.AnalyzedQuery, error) {
-	out := make([]endtoend.AnalyzedQuery, 0, len(queries))
+func analyze(ctx context.Context, l local, schema, fixture string, queries []endtoend.Query) ([]analysis.Query, error) {
+	out := make([]analysis.Query, 0, len(queries))
 	for _, q := range queries {
 		aq, err := analyzeQuery(ctx, l, schema, fixture, q)
 		if err != nil {
@@ -25,7 +26,7 @@ func analyze(ctx context.Context, l local, schema, fixture string, queries []end
 	return out, nil
 }
 
-func analyzeQuery(ctx context.Context, l local, schema, fixture string, q endtoend.Query) (endtoend.AnalyzedQuery, error) {
+func analyzeQuery(ctx context.Context, l local, schema, fixture string, q endtoend.Query) (analysis.Query, error) {
 	sql, phs := bindPlaceholders(q.SQL)
 	explain := returnsRows(sql)
 
@@ -43,33 +44,33 @@ func analyzeQuery(ctx context.Context, l local, schema, fixture string, q endtoe
 
 	results, err := l.run(ctx, script.String())
 	if err != nil {
-		return endtoend.AnalyzedQuery{}, err
+		return analysis.Query{}, err
 	}
 
-	aq := endtoend.AnalyzedQuery{
+	aq := analysis.Query{
 		Name:    q.Name,
 		Cmd:     q.Cmd,
-		Columns: []endtoend.AnalyzedColumn{},
-		Params:  []endtoend.AnalyzedParam{},
+		Columns: []analysis.Column{},
+		Params:  []analysis.Param{},
 	}
 	if !explain {
 		return analyzeExec(ctx, l, script.String(), sql, phs, aq)
 	}
 	if len(results) != 2 {
-		return endtoend.AnalyzedQuery{}, fmt.Errorf("expected the query tree and one result set, got %d results", len(results))
+		return analysis.Query{}, fmt.Errorf("expected the query tree and one result set, got %d results", len(results))
 	}
 
 	var lines []string
 	for _, row := range results[0].Data {
 		var line string
 		if err := json.Unmarshal(row["explain"], &line); err != nil {
-			return endtoend.AnalyzedQuery{}, fmt.Errorf("reading query tree: %w", err)
+			return analysis.Query{}, fmt.Errorf("reading query tree: %w", err)
 		}
 		lines = append(lines, line)
 	}
 	tree, err := parseQueryTree(lines)
 	if err != nil {
-		return endtoend.AnalyzedQuery{}, err
+		return analysis.Query{}, err
 	}
 
 	// Names and types come from the block header of the executed query, the
@@ -85,23 +86,23 @@ func analyzeQuery(ctx context.Context, l local, schema, fixture string, q endtoe
 
 	sentinels := tree.sentinels()
 	for i, ph := range phs {
-		ac := endtoend.AnalyzedColumn{}
+		ac := analysis.Column{}
 		if sentinel := sentinels[i+1]; sentinel != nil {
 			ac = tree.paramColumn(sentinel)
 		}
 		if ph.Name != "" {
 			ac.Name = ph.Name
 		}
-		aq.Params = append(aq.Params, endtoend.AnalyzedParam{Number: ph.Number, Column: ac})
+		aq.Params = append(aq.Params, analysis.Param{Number: ph.Number, Column: ac})
 	}
 	return aq, nil
 }
 
-func column(name, typ string) endtoend.AnalyzedColumn {
+func column(name, typ string) analysis.Column {
 	if typ == "" {
-		return endtoend.AnalyzedColumn{Name: name}
+		return analysis.Column{Name: name}
 	}
-	return endtoend.AnalyzedColumn{Name: name, Type: parseType(typ)}
+	return analysis.Column{Name: name, Type: parseType(typ)}
 }
 
 // returnsRows reports whether a statement produces a result set and so can
@@ -166,7 +167,7 @@ func sentinelOrdinal(c *treeNode) (int, bool) {
 // paramColumn describes what a placeholder is compared with or assigned to:
 // the other operand of the function it is an argument of, preferring a
 // column over an expression, or the projected column it stands for.
-func (t *queryTree) paramColumn(sentinel *treeNode) endtoend.AnalyzedColumn {
+func (t *queryTree) paramColumn(sentinel *treeNode) analysis.Column {
 	list := sentinel.parent
 	if list != nil && list.kind == "LIST" && list.parent != nil {
 		switch owner := list.parent; {
@@ -199,7 +200,7 @@ func (t *queryTree) paramColumn(sentinel *treeNode) endtoend.AnalyzedColumn {
 }
 
 // describe turns a tree expression into a column description.
-func (t *queryTree) describe(n *treeNode) endtoend.AnalyzedColumn {
+func (t *queryTree) describe(n *treeNode) analysis.Column {
 	switch n.kind {
 	case "COLUMN":
 		ac := column(n.attrs["column_name"], n.attrs["result_type"])
@@ -217,28 +218,28 @@ func (t *queryTree) describe(n *treeNode) endtoend.AnalyzedColumn {
 		}
 		return column(name, n.attrs["constant_value_type"])
 	}
-	return endtoend.AnalyzedColumn{}
+	return analysis.Column{}
 }
 
 var insertValuesRe = regexp.MustCompile(`(?is)^insert\s+into\s+(?:table\s+)?([\w.` + "`" + `"]+)\s*(?:\(([^)]*)\))?\s*(?:format\s+)?values\b`)
 
 // analyzeExec runs a statement that returns no rows. The only parameters it
 // can describe are those of an INSERT ... VALUES, which map positionally
 // onto the target columns reported by DESCRIBE TABLE.
-func analyzeExec(ctx context.Context, l local, script, sql string, phs []placeholder, aq endtoend.AnalyzedQuery) (endtoend.AnalyzedQuery, error) {
+func analyzeExec(ctx context.Context, l local, script, sql string, phs []placeholder, aq analysis.Query) (analysis.Query, error) {
 	m := insertValuesRe.FindStringSubmatch(sql)
 	if m != nil {
 		script += "DESCRIBE TABLE " + m[1] + ";\n"
 	}
 	results, err := l.run(ctx, script)
 	if err != nil {
-		return endtoend.AnalyzedQuery{}, err
+		return analysis.Query{}, err
 	}
 
-	var targets []endtoend.AnalyzedColumn
+	var targets []analysis.Column
 	if m != nil && len(results) == 1 {
-		byName := map[string]endtoend.AnalyzedColumn{}
-		var all []endtoend.AnalyzedColumn
+		byName := map[string]analysis.Column{}
+		var all []analysis.Column
 		table := strings.Trim(m[1][strings.LastIndexByte(m[1], '.')+1:], "`\"")
 		for _, row := range results[0].Data {
 			var name, typ string
@@ -258,14 +259,14 @@ func analyzeExec(ctx context.Context, l local, script, sql string, phs []placeho
 		}
 	}
 	for i, ph := range phs {
-		ac := endtoend.AnalyzedColumn{}
+		ac := analysis.Column{}
 		if len(targets) > 0 {
 			ac = targets[i%len(targets)]
 		}
 		if ph.Name != "" {
 			ac.Name = ph.Name
 		}
-		aq.Params = append(aq.Params, endtoend.AnalyzedParam{Number: ph.Number, Column: ac})
+		aq.Params = append(aq.Params, analysis.Param{Number: ph.Number, Column: ac})
 	}
 	return aq, nil
 }

internal/goldeneye/clickhouse/check.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"os"
 
+	"github.com/sqlc-dev/sqlc/internal/goldeneye/analysis"
 	"github.com/sqlc-dev/sqlc/internal/goldeneye/endtoend"
 )
 
@@ -28,7 +29,7 @@ func Analyze(ctx context.Context, binary string, c endtoend.Case) ([]byte, error
 	if err != nil {
 		return nil, err
 	}
-	return endtoend.Encode(out)
+	return analysis.Encode(out)
 }
 
 // Check compares what ClickHouse reports for a case with the output the

internal/goldeneye/clickhouse/types.go

@@ -4,7 +4,7 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/sqlc-dev/sqlc/internal/goldeneye/endtoend"
+	"github.com/sqlc-dev/sqlc/internal/goldeneye/analysis"
 )
 
 // A type is a call expression, the way ClickHouse itself models one: a
@@ -38,7 +38,7 @@ import (
 // is the reader's job; the output only records what was said.
 
 // parseType turns a ClickHouse type string into its expression.
-func parseType(t string) *endtoend.TypeExpr {
+func parseType(t string) *analysis.TypeExpr {
 	name, args := splitType(t)
 	name = strings.ToLower(strings.TrimSpace(name))
 	if name == "nullable" && len(args) == 1 {
@@ -49,7 +49,7 @@ func parseType(t string) *endtoend.TypeExpr {
 	if name == "" {
 		name = "nothing"
 	}
-	expr := &endtoend.TypeExpr{Name: name}
+	expr := &analysis.TypeExpr{Name: name}
 	for _, a := range args {
 		expr.Args = append(expr.Args, parseArg(a))
 	}
@@ -59,7 +59,7 @@ func parseType(t string) *endtoend.TypeExpr {
 // parseArg parses one argument: a quoted string, an integer, a boolean, a
 // labelled argument (`lat Float64` in a Tuple, `'a' = 1` in an Enum), or a
 // type.
-func parseArg(a string) endtoend.TypeArg {
+func parseArg(a string) analysis.TypeArg {
 	a = strings.TrimSpace(a)
 	if strings.HasPrefix(a, "'") {
 		end := skipQuoted(a, 0)
@@ -69,22 +69,22 @@ func parseArg(a string) endtoend.TypeArg {
 			arg.Label = lit
 			return arg
 		}
-		return endtoend.TypeArg{String: &lit}
+		return analysis.TypeArg{String: &lit}
 	}
 	if n, err := strconv.ParseInt(a, 10, 64); err == nil {
-		return endtoend.TypeArg{Int: &n}
+		return analysis.TypeArg{Int: &n}
 	}
 	switch strings.ToLower(a) {
 	case "true", "false":
 		b := strings.EqualFold(a, "true")
-		return endtoend.TypeArg{Bool: &b}
+		return analysis.TypeArg{Bool: &b}
 	}
 	if i := labelEnd(a); i > 0 {
 		arg := parseArg(a[i+1:])
 		arg.Label = a[:i]
 		return arg
 	}
-	return endtoend.TypeArg{Type: parseType(a)}
+	return analysis.TypeArg{Type: parseType(a)}
 }
 
 // labelEnd returns the index of the space separating a label from the type