Introduce internal/api package with Generate entry point

The new package mirrors esbuild's Build API: a single api.Generate(ctx,
api.GenerateOptions{}) call returns a GenerateResult containing the
generated files and any errors. Most of cmd/generate.go's logic moves
here as unexported helpers; the only exported names are Generate,
GenerateOptions, and GenerateResult.

cmd.Generate is now a thin wrapper that translates the CLI's Options
struct into api.GenerateOptions. The endtoend tests call api.Generate
directly for TestExamples, TestReplay (generate command), and the
benchmarks.

https://claude.ai/code/session_01RCzB2JR5Y5ScFDUmwcxGVZ

Author: claude

internal/api/api.go

@@ -0,0 +1,11 @@
+// Package api is intended to be the future public API for sqlc.
+//
+// The shape of this package is inspired by esbuild's Build API
+// (https://pkg.go.dev/github.com/evanw/esbuild/pkg/api#hdr-Build_API): a small
+// surface area of options structs and result structs that lets callers drive
+// sqlc programmatically without going through the CLI.
+//
+// Today the package lives under internal/ while the API stabilises. Once the
+// surface settles it is expected to graduate to pkg/api so it can be imported
+// by external Go programs.
+package api

internal/api/codegen.go

@@ -0,0 +1,108 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"runtime/trace"
+
+	"google.golang.org/grpc"
+
+	"github.com/sqlc-dev/sqlc/internal/codegen/golang"
+	genjson "github.com/sqlc-dev/sqlc/internal/codegen/json"
+	"github.com/sqlc-dev/sqlc/internal/compiler"
+	"github.com/sqlc-dev/sqlc/internal/config"
+	"github.com/sqlc-dev/sqlc/internal/config/convert"
+	"github.com/sqlc-dev/sqlc/internal/ext"
+	"github.com/sqlc-dev/sqlc/internal/ext/process"
+	"github.com/sqlc-dev/sqlc/internal/ext/wasm"
+	"github.com/sqlc-dev/sqlc/internal/plugin"
+)
+
+func findPlugin(conf config.Config, name string) (*config.Plugin, error) {
+	for _, plug := range conf.Plugins {
+		if plug.Name == name {
+			return &plug, nil
+		}
+	}
+	return nil, fmt.Errorf("plugin not found")
+}
+
+func codegen(ctx context.Context, combo config.CombinedSettings, sql outputPair, result *compiler.Result) (string, *plugin.GenerateResponse, error) {
+	defer trace.StartRegion(ctx, "codegen").End()
+	req := codeGenRequest(result, combo)
+	var handler grpc.ClientConnInterface
+	var out string
+	switch {
+	case sql.Plugin != nil:
+		out = sql.Plugin.Out
+		plug, err := findPlugin(combo.Global, sql.Plugin.Plugin)
+		if err != nil {
+			return "", nil, fmt.Errorf("plugin not found: %s", err)
+		}
+
+		switch {
+		case plug.Process != nil:
+			handler = &process.Runner{
+				Cmd:    plug.Process.Cmd,
+				Env:    plug.Env,
+				Format: plug.Process.Format,
+			}
+		case plug.WASM != nil:
+			handler = &wasm.Runner{
+				URL:    plug.WASM.URL,
+				SHA256: plug.WASM.SHA256,
+				Env:    plug.Env,
+			}
+		default:
+			return "", nil, fmt.Errorf("unsupported plugin type")
+		}
+
+		opts, err := convert.YAMLtoJSON(sql.Plugin.Options)
+		if err != nil {
+			return "", nil, fmt.Errorf("invalid plugin options: %w", err)
+		}
+		req.PluginOptions = opts
+
+		global, found := combo.Global.Options[plug.Name]
+		if found {
+			opts, err := convert.YAMLtoJSON(global)
+			if err != nil {
+				return "", nil, fmt.Errorf("invalid global options: %w", err)
+			}
+			req.GlobalOptions = opts
+		}
+
+	case sql.Gen.Go != nil:
+		out = combo.Go.Out
+		handler = ext.HandleFunc(golang.Generate)
+		opts, err := json.Marshal(sql.Gen.Go)
+		if err != nil {
+			return "", nil, fmt.Errorf("opts marshal failed: %w", err)
+		}
+		req.PluginOptions = opts
+
+		if combo.Global.Overrides.Go != nil {
+			opts, err := json.Marshal(combo.Global.Overrides.Go)
+			if err != nil {
+				return "", nil, fmt.Errorf("opts marshal failed: %w", err)
+			}
+			req.GlobalOptions = opts
+		}
+
+	case sql.Gen.JSON != nil:
+		out = combo.JSON.Out
+		handler = ext.HandleFunc(genjson.Generate)
+		opts, err := json.Marshal(sql.Gen.JSON)
+		if err != nil {
+			return "", nil, fmt.Errorf("opts marshal failed: %w", err)
+		}
+		req.PluginOptions = opts
+
+	default:
+		return "", nil, fmt.Errorf("missing language backend")
+	}
+	client := plugin.NewCodegenServiceClient(handler)
+	resp, err := client.Generate(ctx, req)
+	return out, resp, err
+}

internal/api/config.go

@@ -0,0 +1,93 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/sqlc-dev/sqlc/internal/config"
+)
+
+const errMessageNoVersion = `The configuration file must have a version number.
+Set the version to 1 or 2 at the top of sqlc.json:
+
+{
+  "version": "1"
+  ...
+}
+`
+
+const errMessageUnknownVersion = `The configuration file has an invalid version number.
+The supported version can only be "1" or "2".
+`
+
+const errMessageNoPackages = `No packages are configured`
+
+func readConfig(stderr io.Writer, dir, filename string) (string, *config.Config, error) {
+	configPath := ""
+	if filename != "" {
+		configPath = filepath.Join(dir, filename)
+	} else {
+		var yamlMissing, jsonMissing, ymlMissing bool
+		yamlPath := filepath.Join(dir, "sqlc.yaml")
+		ymlPath := filepath.Join(dir, "sqlc.yml")
+		jsonPath := filepath.Join(dir, "sqlc.json")
+
+		if _, err := os.Stat(yamlPath); os.IsNotExist(err) {
+			yamlMissing = true
+		}
+		if _, err := os.Stat(jsonPath); os.IsNotExist(err) {
+			jsonMissing = true
+		}
+
+		if _, err := os.Stat(ymlPath); os.IsNotExist(err) {
+			ymlMissing = true
+		}
+
+		if yamlMissing && ymlMissing && jsonMissing {
+			fmt.Fprintln(stderr, "error parsing configuration files. sqlc.(yaml|yml) or sqlc.json: file does not exist")
+			return "", nil, errors.New("config file missing")
+		}
+
+		if (!yamlMissing || !ymlMissing) && !jsonMissing {
+			fmt.Fprintln(stderr, "error: both sqlc.json and sqlc.(yaml|yml) files present")
+			return "", nil, errors.New("sqlc.json and sqlc.(yaml|yml) present")
+		}
+
+		if jsonMissing {
+			if yamlMissing {
+				configPath = ymlPath
+			} else {
+				configPath = yamlPath
+			}
+		} else {
+			configPath = jsonPath
+		}
+	}
+
+	base := filepath.Base(configPath)
+	file, err := os.Open(configPath)
+	if err != nil {
+		fmt.Fprintf(stderr, "error parsing %s: file does not exist\n", base)
+		return "", nil, err
+	}
+	defer file.Close()
+
+	conf, err := config.ParseConfig(file)
+	if err != nil {
+		switch err {
+		case config.ErrMissingVersion:
+			fmt.Fprint(stderr, errMessageNoVersion)
+		case config.ErrUnknownVersion:
+			fmt.Fprint(stderr, errMessageUnknownVersion)
+		case config.ErrNoPackages:
+			fmt.Fprint(stderr, errMessageNoPackages)
+		}
+		fmt.Fprintf(stderr, "error parsing %s: %s\n", base, err)
+		return "", nil, err
+	}
+
+	return configPath, &conf, nil
+}

internal/api/generate.go

@@ -0,0 +1,174 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+	"sync"
+
+	"github.com/sqlc-dev/sqlc/internal/compiler"
+	"github.com/sqlc-dev/sqlc/internal/config"
+)
+
+// errPluginProcessDisabled is returned when the configuration uses a process
+// plugin but the caller has disabled them via GenerateOptions.DisableProcessPlugins.
+var errPluginProcessDisabled = errors.New("plugin: process-based plugins disabled via SQLCDEBUG=processplugins=0")
+
+// GenerateOptions controls a single Generate invocation.
+type GenerateOptions struct {
+	// Dir is the working directory used to resolve the config file and any
+	// relative schema/query paths within it.
+	Dir string
+
+	// File is the configuration filename to use, relative to Dir. When empty,
+	// Generate looks for sqlc.yaml, sqlc.yml, or sqlc.json in Dir.
+	File string
+
+	// Stderr receives diagnostic output. If nil, output is discarded.
+	Stderr io.Writer
+
+	// DisableProcessPlugins, when true, causes Generate to fail if the
+	// configuration uses a process-based plugin. The sqlc CLI sets this from
+	// SQLCDEBUG=processplugins=0.
+	DisableProcessPlugins bool
+
+	// MutateConfig is called after the configuration is parsed but before it is
+	// validated. It is intended for tests.
+	MutateConfig func(*config.Config)
+}
+
+// GenerateResult is the outcome of a Generate call. Files maps absolute output
+// paths to file contents; callers are responsible for writing them to disk if
+// desired. Errors collects any errors encountered during code generation.
+type GenerateResult struct {
+	// Files maps absolute output paths to generated file contents.
+	Files map[string]string
+
+	// Errors collects any errors encountered. A non-empty Errors slice means
+	// generation did not fully succeed.
+	Errors []error
+}
+
+// Generate parses the sqlc configuration referenced by opts and runs every
+// configured codegen target. The returned GenerateResult always has a non-nil
+// Files map; the map is empty when generation fails before any files are
+// produced.
+func Generate(ctx context.Context, opts GenerateOptions) GenerateResult {
+	stderr := opts.Stderr
+	if stderr == nil {
+		stderr = io.Discard
+	}
+
+	res := GenerateResult{Files: map[string]string{}}
+
+	configPath, conf, err := readConfig(stderr, opts.Dir, opts.File)
+	if err != nil {
+		res.Errors = append(res.Errors, err)
+		return res
+	}
+	if opts.MutateConfig != nil {
+		opts.MutateConfig(conf)
+	}
+
+	base := filepath.Base(configPath)
+	if err := config.Validate(conf); err != nil {
+		fmt.Fprintf(stderr, "error validating %s: %s\n", base, err)
+		res.Errors = append(res.Errors, err)
+		return res
+	}
+
+	if opts.DisableProcessPlugins {
+		if err := validateProcessPluginsDisabled(conf); err != nil {
+			fmt.Fprintf(stderr, "error validating %s: %s\n", base, err)
+			res.Errors = append(res.Errors, err)
+			return res
+		}
+	}
+
+	g := &generator{
+		dir:    opts.Dir,
+		output: map[string]string{},
+	}
+
+	if err := processQuerySets(ctx, g, conf, opts.Dir, stderr); err != nil {
+		res.Errors = append(res.Errors, err)
+		return res
+	}
+
+	res.Files = g.output
+	return res
+}
+
+func validateProcessPluginsDisabled(cfg *config.Config) error {
+	for _, plugin := range cfg.Plugins {
+		if plugin.Process != nil {
+			return errPluginProcessDisabled
+		}
+	}
+	return nil
+}
+
+type generator struct {
+	m      sync.Mutex
+	dir    string
+	output map[string]string
+}
+
+func (g *generator) Pairs(ctx context.Context, conf *config.Config) []outputPair {
+	var pairs []outputPair
+	for _, sql := range conf.SQL {
+		if sql.Gen.Go != nil {
+			pairs = append(pairs, outputPair{
+				SQL: sql,
+				Gen: config.SQLGen{Go: sql.Gen.Go},
+			})
+		}
+		if sql.Gen.JSON != nil {
+			pairs = append(pairs, outputPair{
+				SQL: sql,
+				Gen: config.SQLGen{JSON: sql.Gen.JSON},
+			})
+		}
+		for i := range sql.Codegen {
+			pairs = append(pairs, outputPair{
+				SQL:    sql,
+				Plugin: &sql.Codegen[i],
+			})
+		}
+	}
+	return pairs
+}
+
+func (g *generator) ProcessResult(ctx context.Context, combo config.CombinedSettings, sql outputPair, result *compiler.Result) error {
+	out, resp, err := codegen(ctx, combo, sql, result)
+	if err != nil {
+		return err
+	}
+	files := map[string]string{}
+	for _, file := range resp.Files {
+		files[file.Name] = string(file.Contents)
+	}
+	g.m.Lock()
+
+	// out is specified by the user, not a plugin
+	absout := filepath.Join(g.dir, out)
+
+	for n, source := range files {
+		filename := filepath.Join(g.dir, out, n)
+		// filepath.Join calls filepath.Clean which should remove all "..", but
+		// double check to make sure
+		if strings.Contains(filename, "..") {
+			return fmt.Errorf("invalid file output path: %s", filename)
+		}
+		// The output file must be contained inside the output directory
+		if !strings.HasPrefix(filename, absout) {
+			return fmt.Errorf("invalid file output path: %s", filename)
+		}
+		g.output[filename] = source
+	}
+	g.m.Unlock()
+	return nil
+}