routetree

type Action struct {
	// Name is the exported Go function name.
	Name string
	// RelDir is the declaring package's directory relative to the route root,
	// using slashes. The route root package itself has an empty RelDir.
	RelDir string
	// Package and ImportPath name the declaring Go package. ImportPath is empty
	// unless Config.ImportBase was set.
	Package    string
	ImportPath string
	// File and Line locate the declaration, for diagnostics.
	File string
	Line int
	// Hash is the first ActionHashLength hexadecimal characters of the digest of
	// the declaring directory and the name.
	Hash string
	// Path is the endpoint path, such as /_action/9f3c2ab1e4d7/Rename.
	Path string
}

type Analysis struct {
	Route     Route
	Component ComponentSignature
	// Page describes the Go entry point. It is never nil; a route with no
	// page.go still reports RungTemplateOnly.
	Page *PageFunc
	// Inputs is what [Emitter.Decoder] binds for this route. Which declaration
	// supplies it depends on the rung; see [Analyze].
	Inputs []Value
}

type ComponentSignature struct {
	Name string
	// Inputs are the ordinary parameters, in declaration order.
	Inputs []Value
	// Slots are the html parameters, which a wrapper fills rather than a
	// caller passing data.
	Slots []Value
}

type ComposerArg struct {
	// Field is the layout parameter struct field.
	Field string
	// From is the route parameter struct field it reads.
	From string
}

type ComposerLayout struct {
	// Selector is the qualifier for symbols of this layout's package, such as
	// "users." It is empty when the layout lives in the page's own package.
	Selector string
	// Binder is the generated wrapper constructor, such as BindLayout.
	Binder string
	// ParamsType is the generated parameter struct, such as LayoutParams.
	ParamsType string
	// Args maps each declared layout input to the route field feeding it.
	Args []ComposerArg
}

type ComposerModel struct {
	Header     string
	Package    string
	Pattern    string
	Imports    []Import
	ParamsType string
	RenderFunc string
	// Component is the page component name, which also prefixes its generated
	// parameter struct.
	Component string
	Layouts   []ComposerLayout
	Symbols   Symbols
}

type Config struct {
	// Root is the route root directory. Empty uses DefaultRootDir relative to
	// the working directory.
	Root string
	// ImportBase is the Go import path of the route root directory. Setting it
	// lets discovery compute an ImportPath for every route and layout, which is
	// what a generated registry needs to import them. It cannot be derived,
	// because the route root's position inside its module is not visible from
	// the directory alone.
	ImportBase string
	// PageFile, LayoutFile, DocumentFile, and LogicFile override the reserved
	// names. Empty values use the defaults.
	PageFile     string
	LayoutFile   string
	DocumentFile string
	LogicFile    string
}

type DecoderField struct {
	// Go is the generated struct field name.
	Go string
	// Key is the path wildcard or query key it reads.
	Key string
	// Type is the declared Go type.
	Type string
	// IsQuery reads from the query string rather than the path.
	IsQuery bool
	// Required rejects an empty value. A catch-all is not required, because an
	// empty remainder is a legal match.
	Required bool
	// Parse is the call that converts raw into v, empty for a string.
	Parse string
	// Convert narrows the parse result, empty when the types already agree.
	Convert string
	// ErrCode and ErrMessage describe the failure of Parse.
	ErrCode    string
	ErrMessage string
	// MissingMessage describes an absent required path value.
	MissingMessage string
}

type DecoderModel struct {
	Header      string
	Package     string
	Pattern     string
	Imports     []Import
	ParamsType  string
	DecodeFunc  string
	Fields      []DecoderField
	HasQuery    bool
	MissingCode string
	Symbols     Symbols
}

type Emitter struct {
	// Symbols are the identities the templates call.
	Symbols Symbols
	// ParamsType, DecodeFunc, and RenderFunc name the generated declarations, so
	// a framework can publish its own vocabulary without replacing a template.
	ParamsType   string
	DecodeFunc   string
	RenderFunc   string
	RegisterFunc string
	MuxFunc      string
	TableVar     string
	// ActionPrefix is the reserved path every server function endpoint hangs
	// below. Empty uses [DefaultActionPrefix]. A framework mounting under a
	// sub-path or owning its own URL namespace sets it, which is why it is not
	// the fixed value the endpoint hash is.
	ActionPrefix string
	// ActionTableVar names the generated list of endpoints. Every server
	// function is reachable whether or not a template references it, so the
	// list is what makes that surface inspectable.
	ActionTableVar string
	// ActionAttr is the attribute a lowered server-action writes in compiled
	// templates. Empty uses the htmlbind default.
	ActionAttr string
	// contains filtered or unexported fields
}

type Error struct {
	// Path is the offending file or directory.
	Path string
	// Message states what is wrong and, where possible, what to do instead.
	Message string
}

type GenerateOptions struct {
	// Config selects the route root and reserved names.
	Config Config
	// RootPackage is the Go package clause of the route root directory, which is
	// where the registry is emitted. Empty derives it from the directory name.
	RootPackage string
	// Emitter renders the Go source. Nil uses [NewEmitter].
	Emitter *Emitter
	// ComponentSuffix, DecoderOutput, and RegistryOutput override the generated
	// file names.
	ComponentSuffix string
	DecoderOutput   string
	RegistryOutput  string
}

type Generated struct {
	// Path is the absolute destination.
	Path string
	// Source is the formatted Go source.
	Source []byte
}

type Import struct {
	Path  string
	Alias string
	// Group starts a new import group before this line, which is how the
	// standard library and the runtime end up separated.
	Group bool
}

type Layout struct {
	// RelDir is the layout directory relative to the route root, using slashes.
	// The root layout has an empty RelDir.
	RelDir string
	// File is the absolute path of the layout template.
	File string
	// Package is the Go package name of the layout directory.
	Package string
	// ImportPath is the Go import path of the layout directory. It is empty
	// unless Config.ImportBase was set.
	ImportPath string
	// Params are the dynamic segments in scope at this level, outermost first.
	// A layout may only depend on segments at or above its own directory.
	Params []Segment
}

type PageFunc struct {
	Rung Rung
	// File is the page.go path, empty at RungTemplateOnly with no file.
	File string
	// Line is the line of the func Page declaration, zero when absent.
	Line int
	// Params and Results are populated at RungTypedPage only. Results excludes
	// the trailing error.
	Params  []Value
	Results []Value
}

type RegistryAction struct {
	Pattern string
	Path    string
	Hash    string
	Name    string
	RelDir  string
	// Selector qualifies the handler's package, such as "id_." It is empty for
	// a handler in the root package itself.
	Selector string
}

type RegistryModel struct {
	Header         string
	Package        string
	Imports        []Import
	RegisterFunc   string
	MuxFunc        string
	TableVar       string
	ActionTableVar string
	DecodeFunc     string
	Routes         []RegistryRoute
	Actions        []RegistryAction
	Symbols        Symbols
}

type RegistryRoute struct {
	Pattern string
	Path    string
	RelDir  string
	// ParamNames are the dynamic segment names, in route order.
	ParamNames []string
	// Selector qualifies symbols of the route's package, such as "id_." It is
	// empty for a route in the root package itself.
	Selector string
	// Raw registers the route's own handler directly and generates no body.
	Raw bool
	// Call is set when a typed func Page must run before rendering.
	Call bool
	// CallResults is the assignment prefix for that call, such as "u, err :=".
	CallResults string
	// CallArgs is the argument list for that call, read from the decoded route.
	CallArgs string
	// PageFields fills the page component parameter struct.
	PageFields []ComposerArg
	// Layouts are the ancestor wrappers, outermost first.
	Layouts []ComposerLayout
}

type Route struct {
	// RelDir is the page directory relative to the route root, using slashes.
	// The root page has an empty RelDir.
	RelDir string
	// Dir is the absolute page directory.
	Dir string
	// PageFile is the absolute path of the page template.
	PageFile string
	// LogicFile is the absolute path of page.go, or empty when absent.
	LogicFile string
	// Package is the Go package name for the page directory.
	Package string
	// ImportPath is the Go import path of the page directory. It is empty
	// unless Config.ImportBase was set.
	ImportPath string
	// Path is the URL path pattern, such as /users/{id}.
	Path string
	// Segments are every directory from the route root to the page directory.
	Segments []Segment
	// Params are the dynamic and catch-all segments only, in route order.
	Params []Segment
	// Layouts are the ancestor layouts, outermost first.
	Layouts []Layout
}

type Rung uint8

type Segment struct {
	// Dir is the directory name exactly as it appears on disk.
	Dir string
	// Name is the parameter name for a dynamic or catch-all segment, and the
	// literal URL segment for a static one.
	Name string
	Kind SegmentKind
}

type SegmentKind uint8

type Symbols struct {
	// HTTPImport and HTTPAlias name the package providing Request and
	// PathValue. The alias is what generated source writes.
	HTTPImport string
	HTTPAlias  string
	// ErrorImport and ErrorAlias name the package providing the constructors
	// below. An empty ErrorImport suppresses the import, which is what a
	// template that reports errors some other way wants.
	ErrorImport string
	ErrorAlias  string
	// BadRequest and Problem are selectors on ErrorAlias.
	BadRequest string
	Problem    string
	// StrconvImport is the package providing the scalar parsers. It is only
	// imported when a route actually declares a non-string input.
	StrconvImport string
	StrconvAlias  string
	// RuntimeImport and RuntimeAlias name the HTML rendering runtime the
	// composer calls.
	RuntimeImport string
	RuntimeAlias  string
}

type Tree struct {
	// Root is the absolute route root directory.
	Root string
	// DocumentFile is the absolute path of the root document shell, or empty.
	DocumentFile string
	// Routes are the discovered pages, ordered by path.
	Routes []Route
}

type Value struct {
	// Name is the declared identifier. A result is usually unnamed, leaving
	// this empty.
	Name string
	// Type is the source text of the type expression, such as string or
	// []Order.
	Type string
}