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
	Destination ArtifactDestination
	// OutputBase is the suggested output base name, without directory,
	// extension, or generated-file suffix.
	OutputBase string
	// Extension is the output file extension without a dot.
	Extension string
	// PackageName is meaningful for a go_package destination only.
	PackageName string
	Content     []byte
	// PublicPath is the URL a public asset is referenced by. It is empty for a
	// go_package destination.
	PublicPath string
}

type ArtifactDestination string

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 DynamoOp = dynamobind.Op

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

type DynamoPredicate = dynamobind.Predicate

type DynamoQueryDecl = dynamobind.QueryDecl

type DynamoQueryOptions struct {
	// ParameterAPI gives each function a leading dynamobind.Handle parameter.
	ParameterAPI bool
	// HandleResolver names a framework function answering a dynamobind.Handle
	// for one Context. ParameterAPI takes precedence over it.
	HandleResolver *SymbolPattern
}

type DynamoQueryParam = dynamobind.QueryParam

type DynamoQueryPlan struct {
	Decl DynamoQueryDecl
	// Item is the type the query decodes into.
	Item DynamoItemPlan
	// Expression is the KeyConditionExpression, written with aliases.
	Expression string
	// Names maps each alias to the attribute it stands for.
	Names map[string]string
	// Values pairs each ":v" placeholder with the parameter and attribute that
	// fill it, in emission order.
	Values []DynamoQueryValue
}

type DynamoQueryValue struct {
	Placeholder string
	Param       DynamoQueryParam
	Attribute   DynamoFieldPlan
}

type DynamoResultShape = dynamobind.ResultShape

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 FirestoreBound = firestorebind.Bound

type FirestoreCondition = firestorebind.Condition

type FirestoreDirection = firestorebind.Direction

type FirestoreEntityPlan struct {
	Name       string
	Kind       string
	SourcePath string
	Fields     []FirestoreFieldPlan
	Usage      FirestoreUsage
}

type FirestoreFieldPlan struct {
	Name     string
	Property string
	// Role is "", "name", "id", "parent", "version" or "ttl". A field with a
	// role other than "", "version" and "ttl" carries identity rather than a
	// property; a ttl field is an ordinary property that a policy also reads.
	Role      string
	OmitEmpty bool
	NoIndex   bool
	// Stored reports whether the field also becomes a property. It is false for
	// an identity field unless the tag gave it a real property name.
	Stored bool
	Type   FirestoreType
}

type FirestoreIndexProperty = firestorebind.IndexProperty

type FirestoreJunction = firestorebind.Junction

type FirestoreKind string

type FirestoreOp = firestorebind.Op

type FirestoreOrder = firestorebind.Order

type FirestorePackagePlan struct {
	Package     string
	PackagePath string
	Entities    []FirestoreEntityPlan
}

type FirestorePredicate = firestorebind.Predicate

type FirestoreProjection = firestorebind.Projection

type FirestoreQueryDecl = firestorebind.QueryDecl

type FirestoreQueryFilter struct {
	Predicate FirestorePredicate
	Field     FirestoreFieldPlan
	Param     FirestoreQueryParam
}

type FirestoreQueryOptions struct {
	// ParameterAPI gives each function a leading firestorebind.Handle parameter.
	ParameterAPI bool
	// HandleResolver names a framework function answering a firestorebind.Handle
	// for one Context. ParameterAPI takes precedence over it.
	HandleResolver *SymbolPattern
}

type FirestoreQueryOrder struct {
	Order FirestoreOrder
	Field FirestoreFieldPlan
}

type FirestoreQueryParam = firestorebind.QueryParam

type FirestoreQueryPlan struct {
	Decl FirestoreQueryDecl
	// Entity is the type the query decodes into, and whose Kind the query runs
	// against.
	Entity FirestoreEntityPlan
	// Filters pairs each predicate with the field it names and the parameter
	// that fills it, in the order the source wrote them.
	Filters []FirestoreQueryFilter
	// Where is the checked filter tree, or nil when there is no where clause.
	// Filters is its leaves; the tree is what the emitter walks when the
	// declaration uses or.
	Where *FirestoreCondition
	// HasOr reports whether the tree needs datastore.Where at all. Without it
	// the emitter keeps to the per-predicate Filter calls it always wrote.
	HasOr bool
	// Orders are the checked sort keys.
	Orders []FirestoreQueryOrder
	// Ancestor is the parameter holding the ancestor key, or "".
	Ancestor string
	// Select and Distinct are the checked property names, resolved to what the
	// tags call them.
	Select   []string
	Distinct []string
	// ProjectsAnArray reports whether any projected property is a slice, which
	// makes the service return one result per element rather than one per
	// entity. The godoc says so; nothing here can prevent it.
	ProjectsAnArray bool
	// Start and End are the parameters holding the cursors.
	Start string
	End   string
}

type FirestoreResultShape = firestorebind.ResultShape

type FirestoreType struct {
	Kind FirestoreKind
	// Go is the type as it must be written inside the generated package.
	Go string
	// Elem is the element of a slice or pointer.
	Elem *FirestoreType
	// Struct is the named struct type of a nested entity, 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.
	Bits int
}

type FirestoreUsage uint8

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
	// DynamoQueryName is the generated DynamoDB query output file.
	DynamoQueryName string
	// FirestoreName is the Firestore entity codec output file.
	FirestoreName string
	// FirestoreQueryName is the generated Firestore query output file.
	FirestoreQueryName string
	// PublicDir and PublicURLBase override where extracted static assets are
	// written and how they are referenced. Empty values retain the generator
	// options; setting one requires setting the other.
	PublicDir     string
	PublicURLBase 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
	// DynamoParameterAPI and FirestoreParameterAPI put the runtime Handle in
	// each generated query's signature for this run. Like the SQL switches they
	// can turn the option on, never off.
	DynamoParameterAPI    bool
	FirestoreParameterAPI bool
}

type GenerateResult struct {
	BinderPath         string
	ConfigBindPath     string
	DynamoPath         string
	DynamoQueryPath    string
	FirestorePath      string
	FirestoreQueryPath string
	OpenAPIPath        string
	TemplatesPath      string
	// AssetPaths holds the static files extracted from component style and
	// script blocks, then the files reference hook conversions produced, in
	// generation order.
	AssetPaths []string
	// Rewrites reports what the reference hooks did, including what they
	// declined and why. An author cannot see a build-time rewrite by reading
	// the template, so the build is the only place it is visible.
	//
	// It reports rather than interprets: whether a converted file is small
	// enough is the caller's judgment, and a caller measuring sizes owns its
	// own transform and can measure inside it.
	Rewrites []htmlbind.Rewrite
	// ReadSet holds every authored file the run depended on through a hook: the
	// sources each cache key named, plus whatever each transform reported
	// reading beyond them, sorted. A transform that under-reports produces a
	// stale output on the next run, which is the one correctness property this
	// package cannot verify for the caller.
	ReadSet []string
	// DynamicReferences are the attributes a hook was registered for whose
	// value is a template expression, and so could not be rewritten.
	DynamicReferences []htmlbind.DynamicReference
	// DepsPath is the recorded read set, written only when a transform reported
	// reading something. The next run verifies it before trusting its own skip,
	// because a file read by a transform is not otherwise a hashed input.
	DepsPath    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
	// DynamoTemplatePattern is the base-name glob for DynamoDB query
	// declarations. An empty value uses DefaultDynamoTemplatePattern.
	DynamoTemplatePattern string
	// FirestoreTemplatePattern is the base-name glob for Firestore query
	// declarations. An empty value uses DefaultFirestoreTemplatePattern.
	FirestoreTemplatePattern 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
	// DynamoParameterAPI gives every generated DynamoDB query a leading
	// dynamobind.Handle parameter instead of resolving one from the Context.
	// The declared name is unchanged; only the signature moves. False keeps the
	// Context form, which is the default and what every existing run generates.
	DynamoParameterAPI bool
	// DynamoHandleResolver selects a framework function that answers a
	// dynamobind.Handle for one Context, so generated code reads the
	// framework's own Context value instead of the one dynamobind installs.
	// It is how a framework carrying every value it manages in one struct
	// serves generated queries with a single lookup.
	//
	// The signature is func(context.Context) (dynamobind.Handle, error). Nil
	// uses dynamobind's own Context key. DynamoParameterAPI takes precedence:
	// a signature that already carries the Handle resolves nothing.
	DynamoHandleResolver *SymbolPattern
	// FirestoreParameterAPI is DynamoParameterAPI for Firestore queries,
	// giving each a leading firestorebind.Handle parameter.
	FirestoreParameterAPI bool
	// FirestoreHandleResolver is DynamoHandleResolver for Firestore queries.
	// The signature is func(context.Context) (firestorebind.Handle, error).
	FirestoreHandleResolver *SymbolPattern
	// DataAttributePrefix names the data attributes generated HTML uses for
	// partial update boundaries. Empty uses the standard prefix. A project
	// overriding it must use a browser runtime built for the same prefix,
	// because the runtime hardcodes it rather than discovering it.
	DataAttributePrefix string
	// 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

	// PublicDir is the filesystem directory receiving the static files
	// extracted from component style and script blocks. Empty uses
	// DefaultPublicDir.
	PublicDir string
	// PublicURLBase is the URL prefix under which those files are served. It is
	// either an absolute URL path or a full URL, and is used verbatim either
	// way, so a CDN base changes the reference and nothing else. Empty uses
	// DefaultPublicURLBase.
	//
	// Neither option is derived from the other, and setting one explicitly
	// requires setting the other.
	PublicURLBase string

	// ReferenceHooks rewrite the static values of the attributes they are
	// registered for, at generation time, and declare the conversions those
	// rewrites depend on. They are how a build converts a file a template points
	// at, such as an image to a modern format or a TypeScript entry point to
	// JavaScript.
	//
	// A hook converts and returns the bytes, so the rewrite may depend on how
	// the conversion turned out; an encode larger than its source is worth
	// declining, and only the converted bytes can say so.
	ReferenceHooks []htmlbind.ReferenceHook
	// ConversionCacheDir stores the outcome of each conversion, keyed by what
	// the hook's CacheKey declared it depends on. An unchanged asset then costs
	// a digest instead of an encode, and a source that once lost a size
	// comparison is never re-encoded to rediscover it.
	//
	// Empty converts every build, which is correct and slow. It is a plain
	// directory of generated data: deleting it costs time and nothing else.
	ConversionCacheDir string
	// DerivedAssetDir receives the files those conversions produce. It is
	// deliberately not derived from PublicDir: a hook chooses the URL it rewrites
	// to, and only the caller knows which directory is served there.
	//
	// A produced file with no directory configured is a configuration error
	// rather than a silent discard.
	DerivedAssetDir string
	// ConversionWorkers converts what the compile is about to ask for ahead of
	// it, on this many goroutines, instead of one encode at a time inside a
	// sequential compile. It changes wall clock and nothing else: the same
	// bytes, the same produced files, and the same diagnostics in the same
	// order.
	//
	// Zero or one keeps every transform on one goroutine, which is the default
	// because concurrency is a promise about the caller's transform that only
	// the caller can make. Being a pure function of what it reads is necessary
	// and not sufficient: a transform holding a shared scratch buffer is pure by
	// that definition and unsafe by this one. Set this only once Transform is
	// safe for concurrent use.
	//
	// A warm cache converts nothing and starts nothing whatever this says.
	//
	// It is excluded from the hashed options deliberately. Every other field
	// here can change what is generated, and this one cannot: it says how many
	// goroutines do the same work. Hashing it would stamp the machine that ran
	// the build into the output, so a four-core laptop and a sixteen-core runner
	// would disagree on bytes that are identical in every way that matters, and
	// `--check` would fail on the difference between two correct builds.
	ConversionWorkers int `json:"-"`

	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
}