generator

type Artifact struct {
	// SourcePath is the real on-disk path of the owning source. It is empty for
	// package-wide artifacts.
	SourcePath string
	Kind       ArtifactKind
	// OutputBase is the suggested output base name, without directory,
	// extension, or generated-file suffix.
	OutputBase  string
	PackageName string
	GoSource    []byte
}

type ArtifactKind string

type CallOperation string

type CallPattern struct {
	Target        CallTarget
	Operation     CallOperation
	TypeRoles     map[string]TypeSource
	ArgumentRoles map[string]ValueSource
}

type CallPatternOption func(*CallPattern)

type CallRegistry struct {
	// contains filtered or unexported fields
}

type CallTarget struct {
	Function *SymbolPattern
	Method   *MethodPattern
}

type CheckRules struct {
	Required bool
	Min      *float64
	Max      *float64
	MinLen   *int
	MaxLen   *int
	Len      *int
	Pattern  string
	Email    bool
	UUID     bool
	Date     bool
	Time     bool
	DateTime bool
}

type Command struct {
	Name    string
	Summary string
	Run     func(context.Context, []string, CommandIO) int
}

type CommandIO struct {
	Stdin            io.Reader
	Stdout           io.Writer
	Stderr           io.Writer
	WorkingDirectory string
	Environment      []string
}

type CommandSet struct {
	// contains filtered or unexported fields
}

type ConfigBindBinding struct {
	TypeName   string
	Prefix     string
	SubCommand bool
	Name       string
	Help       string
	// SourcePath is the Go file containing the discovered call.
	SourcePath string
}

type ConfigBindSpec struct {
	SourcePath string
	Spec       cbcg.Spec
}

type DefaultRule struct {
	Value string
	Set   bool
}

type DiscoverySymbol struct {
	PackagePath         string
	Name                string
	ReceiverPackagePath string
	ReceiverType        string
	Usage               Usage
	TypeArgument        int
	ArgumentType        *int
}

type Document map[string]any

type DynamoFieldPlan struct {
	Name      string
	Attribute string
	OmitEmpty bool
	// Key is "", "partition" or "sort".
	Key  string
	Type DynamoType
}

type DynamoItemPlan struct {
	Name       string
	SourcePath string
	Doc        string
	Fields     []DynamoFieldPlan
	Usage      DynamoUsage
}

type DynamoKind string

type DynamoPackagePlan struct {
	Package     string
	PackagePath string
	Items       []DynamoItemPlan
}

type DynamoType struct {
	Kind DynamoKind
	// Go is the type as it must be written inside the generated package.
	Go string
	// Elem is the element of a slice, map or pointer.
	Elem *DynamoType
	// MapKey is the key type of a map attribute, written as the generated
	// package must spell it. DynamoDB map keys are strings, so it is always a
	// string-kinded type.
	MapKey string
	// Struct is the named struct type of a nested item, always declared in the
	// same package as its parent.
	Struct string
	// Bits is the width a number is parsed at: 8, 16, 32 or 64, and 0 for int
	// and uint, which strconv reads as the platform width. Parsing at the
	// field's own width turns a value it cannot hold into an error instead of a
	// silent wrap.
	Bits int
}

type DynamoUsage uint8

type EnumRule struct {
	Values []string
	Set    bool
}

type Feature string

type FieldPlan struct {
	Name     string      // Go field name
	Wire     string      // wire / tag name ("*" for payload rest)
	Source   FieldSource // input|query|payload|path|header|cookie|method
	Kind     string      // string|int|int64|bool|float64|file|rest_*|struct|slice|map
	JSON     string      // json name for encode/document keys
	Check    CheckRules  // from check:"" tag; empty if absent
	Enum     EnumRule    // from enum:"" tag; unset if absent
	Default  DefaultRule // from default:"" tag; unset if absent
	TypeName string      // KindStruct name, or element struct name for slice/map of struct
	ElemKind string      // for slice/map: string|int|int64|bool|float64|struct
	DB       string      // SQL result column (db tag or snake_case field name)
	GroupKey bool        // groupkey tag presence
	Doc      string      // godoc of the field (doc or line comment)
}

type FieldSource string

type GenerateRequest struct {
	Dir           string
	Out           string
	Name          string
	OpenAPI       bool
	OpenAPIName   string
	TemplatesName string
	// HTMLTemplatePattern and SQLTemplatePattern override template discovery
	// globs. Empty values retain the generator options.
	HTMLTemplatePattern string
	SQLTemplatePattern  string
	// SQLDialect overrides the generator option for this run. An empty value
	// retains it.
	SQLDialect     string
	ConfigBindName string
	// DynamoName is the DynamoDB item codec output file.
	DynamoName  string
	Check       bool
	GenerateAll bool
	// Force regenerates even when the generated files record the current input
	// hash. Use it after a change the hash does not cover, such as an edit in
	// another package of the module.
	Force         bool
	SQLContextAPI bool
	// SQLContextOnlyAPI enables the context-only SQL API for this run. It can
	// turn the option on, never off.
	SQLContextOnlyAPI bool
}

type GenerateResult struct {
	BinderPath     string
	ConfigBindPath string
	DynamoPath     string
	OpenAPIPath    string
	TemplatesPath  string
	Diagnostics    []parser.Diagnostic
	// Cached reports that the paths were left untouched because the generated
	// files already record the current input hash.
	Cached bool
}

type Generator struct{ Options Options }

type MethodPattern struct {
	PackagePath         string
	Name                string
	ReceiverPackagePath string
	ReceiverType        string
}

type Options struct {
	ServeMuxes      PatternSet[TypePattern]
	RouteMethods    PatternSet[MethodPattern]
	RouteFunctions  PatternSet[SymbolPattern]
	RuntimePackages PatternSet[string]
	Calls           PatternSet[CallPattern]
	FileTypes       PatternSet[TypePattern]
	// HTMLTemplatePattern and SQLTemplatePattern are filepath.Match patterns
	// applied to file base names. Empty values use the standard patterns.
	HTMLTemplatePattern string
	SQLTemplatePattern  string
	// SQLDialect names the target database for SQL templates: "postgresql",
	// "mysql", or "sqlite". A run that discovers a SQL template must set it.
	// There is no default, because an assumed dialect emits placeholders the
	// target engine rejects, and nothing about the templates reveals the
	// mistake.
	SQLDialect string
	// SQLContextAPI adds Context-resolved wrappers for exported SQL templates.
	SQLContextAPI bool
	// SQLContextOnlyAPI publishes only the Context-resolved SQL surface under
	// the name declared in the template. The executor-taking function becomes
	// unexported and no <Component>Context wrapper is generated. It implies
	// SQLContextAPI.
	SQLContextOnlyAPI bool
	// SQLExecutorResolver selects a framework-specific Context resolver and
	// implies SQLContextAPI. Nil uses sqlbind.SQLExecutorFromContext.
	SQLExecutorResolver *SymbolPattern
	// GeneratedHeaders names header prefixes, beside this module's own, whose
	// files every discovery pass must skip. A framework generating with tinybind
	// and branding its output writes a header nothing here recognizes on its own,
	// and an unrecognized generated registry is analyzed as if a user had written
	// it: its page registrations become routes, and an HTML page enters an OpenAPI
	// document. Each entry still requires the conventional "DO NOT EDIT." ending.
	GeneratedHeaders []string
	// PreserveTemplateWhitespace keeps the authoring indentation and newlines of
	// HTML templates in generated static output instead of collapsing each run
	// to one space. The default collapses, which renders identically and drops
	// every indentation byte from the generated source and the binary.
	PreserveTemplateWhitespace bool

	DisableFeatures []Feature
	GenerateAll     bool
}

type PackagePlan struct {
	Package     string
	PackagePath string
	Types       []TypePlan
	// Discovered lists type names referenced by configured generic call sites.
	Discovered []string
}

type PatternSet[T any] struct {
	Set      []T
	Disabled bool
}

type SymbolPattern struct{ PackagePath, Name string }

type TypePattern struct{ PackagePath, Name string }

type TypePlan struct {
	Name string
	// SourcePath is the Go file that declares the type. It is the owning source
	// of every artifact generated for this type.
	SourcePath string
	Fields     []FieldPlan
	// Doc is the godoc of the type declaration.
	Doc string
	// Usage records which generated entry points are referenced by source code.
	// Zero means the type is unused and emits no mapping paths.
	Usage Usage
	// DirectUsage excludes usage inherited from containing structs.
	DirectUsage Usage
}

type TypeSource struct {
	GenericArgument *int
	ArgumentType    *int
}

type Usage uint32

type ValueSource struct {
	Argument   *int
	Constant   any
	IsConstant bool
}