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
	// WriterType is the writer the generated composer takes.
	WriterType string
	// RequestParam is the request parameter name, empty when the composer
	// declares none.
	RequestParam 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, which is a pointer when the input is
	// optional.
	Type string
	// Base is Type with the optional pointer removed, so it is the scalar the
	// parse call and the diagnostics name.
	Base string
	// Optional binds a pointer, left nil when the key is absent or its value is
	// empty. It is set for a query parameter only.
	Optional bool
	// 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
	// RenderWriterType is the writer the generated composer takes. Empty uses
	// [DefaultRenderWriterType], which is what keeps a rung 3 handler free to
	// render into a buffer. It must be qualified by io, by Symbols.HTTPAlias, or
	// by Symbols.RuntimeAlias, because those are the packages the composer
	// imports.
	RenderWriterType string
	// RenderRequestParam adds a request parameter to the generated composer under
	// this name, so a "render" block override has the request in scope there as
	// well as in the registry handler. Empty declares none.
	//
	// It is off by default because the composer's contract is a writer: a handler
	// rendering into a buffer to choose its status has no response to hand over.
	RenderRequestParam string
	// GeneratedHeader is the first line of every emitted file. Empty uses
	// [GeneratedHeader], and a framework branding its own output replaces it.
	//
	// A run that changes it must also name the new prefix to the discovery pass,
	// which recognizes this module's own header and nothing else. An
	// unrecognized generated registry is analyzed as if a user had written it,
	// and its page registrations become documented API routes. Keeping the
	// default line and adding a brand line below it needs no such registration.
	GeneratedHeader 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
	// ActionResolver supplies the endpoint URL of a server action this tree does
	// not declare, so a framework can address a handler from its own route table.
	// A handler exported by the template's own route package always wins, which is
	// what keeps a resolver from silently retargeting a discovered action.
	ActionResolver func(name string) (url string, ok bool)
}

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 Package struct {
	// RelDir is the directory relative to the route root, using slashes. The
	// route root package itself has an empty RelDir.
	RelDir string
	// Dir is the absolute directory.
	Dir string
	// Name is the Go package name.
	Name string
	// ImportPath is the Go import path. It is empty unless Config.ImportBase was
	// set.
	ImportPath string
}

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. Params excludes a
	// leading context.Context and Results excludes the trailing error.
	Params  []Value
	Results []Value
	// TakesContext records that the declaration opened with a context.Context.
	//
	// It is trimmed out of Params rather than counted in them, so "Params are
	// the URL inputs, in route order" stays true and neither the route-order
	// check nor the generated decoder has to carry an offset. A context is not
	// a URL input: it arrives from the request rather than from the address,
	// which is why it cannot be spelled as one.
	TakesContext bool
}

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 RenderCall struct {
	// Writer is the writer identifier, always present.
	Writer string
	// Request is the request identifier, empty where none is in scope. The
	// registry handler always has one; the composer has one only when
	// [Emitter.RenderRequestParam] declared it.
	Request string
	// Wrappers is the layout chain slice identifier, empty when the page has no
	// ancestor layout and renders on its own.
	Wrappers string
	// Leaf is the expression building the page fragment, such as Page(params).
	Leaf string
	// Options is the render option slice identifier, empty where none is in
	// scope.
	Options string
	// Symbols are the identities generated code calls.
	Symbols Symbols
}

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
	// MuxImport and MuxAlias name the package providing the router the registry
	// installs on. They are separate from the pair above because the same alias
	// would otherwise supply both the router and Request: a framework wanting
	// only its own router would drag the request package along with it and be
	// left replacing the whole registry template.
	MuxImport string
	MuxAlias  string
	// MuxType is the router type the generated registration function takes, and
	// MuxConstructor the call that builds one. Both are written verbatim, so a
	// framework whose router is an interface writes no pointer. An empty
	// MuxConstructor omits the constructor function, which is what a router
	// needing arguments generated code cannot supply wants.
	//
	// Generated code registers through HandleFunc alone, so a one-method
	// interface is enough to satisfy either.
	MuxType        string
	MuxConstructor 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, naming the error value
	// a decoder builds. WriteError is the selector a generated handler writes a
	// failure through, taking (w, r, err).
	BadRequest string
	Problem    string
	WriteError 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
	// ImportBase is the Go import path of Root, copied from the Config so a
	// caller reading the tree back needs no second source for it. It is empty
	// unless Config.ImportBase was set.
	ImportBase 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
}