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
	// NativeForm reports that a template in the declaring package names this
	// handler from a form element, so a browser can submit to it with no runtime
	// loaded. It is what puts a POST on the page's own pattern.
	//
	// An action named only from a bare button sets nothing: such an element has
	// no native submit channel to serve, so registering a POST for it would take
	// a path an application may want and buy nothing. Discovery cannot see this,
	// because it reads Go sources; the template compiler reports it.
	NativeForm bool
	// Published is the identifier client script calls this action through. It is
	// the Go name in initialism-aware lowerCamelCase unless a declaration
	// overrode it, and it is a wire name rather than a second identity: a Go
	// rename moves Name and leaves an overridden Published where it was.
	Published string
	// Typed records that this action was admitted by a declaration rather than
	// by its signature, and Signature is what that signature says.
	//
	// A handler-shaped function is an action by existing, because nothing else
	// has that shape. An arbitrary signature distinguishes nothing, so a
	// declaration is what says this one is an action. The two kinds share an
	// address space, a hash and a table; what differs is that a typed action is
	// reached only by a script, never by a template.
	Typed     bool
	Signature TypedSignature
	// Wrapper is the symbol the registry registers for this action.
	//
	// A raw handler is registered as itself: it is the whole response and
	// nothing is generated around it. A typed one is registered as the
	// generated entry point emitted beside it, which is what lets the declared
	// function be unexported and what makes its signature free.
	Wrapper string
}

type ActionDeclaration struct {
	// Import is the package path declaring the annotation.
	Import string
	// Package is the identifier that path is reached through when the file
	// imports it without an explicit alias.
	//
	// It has to be declared rather than derived, because a path's last element
	// is not always the package name: this module's own path ends in
	// tinybind-go and its package is httpbind. The handler shape check never
	// met that, resolving only net/http, where the two agree.
	Package string
	// Name is the function name within it.
	Name 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
	// HandlerShape is the rung 3 signature [Generate] recognizes. The zero value
	// uses [DefaultHandlerShape].
	//
	// It sits beside Symbols rather than with the analysis entry points because
	// both name the same transport, and a build that emitted one transport while
	// admitting the other's handler shape would fail in generated source rather
	// than in configuration.
	HandlerShape HandlerShape
	// 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
	// ClientHandlerAttr is the attribute an on-prefixed handler lowers into, and
	// ComponentParameterAttr the one a component's emitted parameters are written
	// to. Empty uses the htmlbind defaults. A framework driving its own client
	// runtime points them at that runtime's vocabulary.
	ClientHandlerAttr      string
	ComponentParameterAttr string
	// ActionSelectorField is the hidden field a generated form carries to say
	// which server function a native submit is for. Empty uses
	// [DefaultActionSelectorField]. It is written into the form by the template
	// compiler and read back by the generated page POST, so one setting moves
	// both halves.
	ActionSelectorField 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)
	// ScriptResolver reads the component script blocks of one template and
	// answers what each block exposes and which of the component's parameters to
	// emit onto its root element.
	//
	// It is how a framework that parses JavaScript supplies what this module
	// refuses to read. Configuring one costs a second parse of every template
	// carrying a block, because the blocks have to be reported before the compile
	// that consumes the answers can run; a tree with no resolver parses once, as
	// it always has.
	ScriptResolver func(path string, scripts []htmlbind.ComponentScript) (ScriptAnswers, error)
	// DataAttributePrefix is the boundary attribute prefix compiled into every
	// template in the tree. Empty uses the htmlbind default.
	//
	// A project configuring its runtime with a prefix of its own sets the same
	// value here. Without it a page tree takes the default while a registered
	// template takes the configured one, and two halves of one project disagree
	// about an attribute name they both have to read.
	DataAttributePrefix string
	// PublicURLBase is the URL prefix an extracted asset's reference is computed
	// against. Empty uses the htmlbind default.
	//
	// It has to name where the caller actually serves Result.Assets from, since
	// the URL it produces is written into the generated component and nothing
	// downstream can correct it.
	PublicURLBase string
	// ImplicitBindings are the names an embedder puts in every template's
	// scope, and Messages plus MessageContextBinding are the message symbol
	// table and the binding supplying those symbols' leading argument.
	//
	// They are here because a page tree is a second compile path: a seam filled
	// only where templates are compiled as a package would leave every
	// filesystem route without the feature, which is the shape of
	// .knowledge requirement:route-package-context-externals.
	ImplicitBindings      []htmlbind.ImplicitBinding
	Messages              map[string]htmlbind.MessageSymbol
	MessageContextBinding string
}

type Generated struct {
	// Path is the absolute destination.
	Path string
	// Source is the formatted Go source.
	Source []byte
	// Registry marks the one file registering every route and endpoint.
	//
	// It is flagged because it is the one file whose write has an order. It
	// names the entry point of every typed server action, and those are emitted
	// by the binding phase, which runs after this one because it type-checks
	// each route package and a package does not type-check until the compiled
	// component is in it. Writing the registry first would leave the root
	// package naming a symbol nothing had written yet.
	//
	// Writing it last costs nothing: the binding phase is required to skip it
	// anyway, per rule:generated-source-not-discovered, so writing it earlier
	// only produces a file that phase must ignore.
	Registry bool
}

type HandlerShape struct {
	// Import is the package path the parameter types come from. The check is
	// syntactic, so the qualifier is resolved from the file's own import of this
	// path rather than from type information.
	Import string
	// Types are the parameter types, in order, written without a qualifier and
	// with a leading * where the parameter is a pointer: ResponseWriter and
	// *Request name the net/http pair.
	Types []string
	// GeneratedHeaders names header prefixes, beside this module's own, whose
	// files action discovery must skip. A framework branding its generated
	// output writes a header nothing here recognizes on its own; this module's
	// own prefix is always recognized, so a caller never lists it.
	GeneratedHeaders []string
	// Declaration names the annotation that admits a typed server action, whose
	// signature this shape says nothing about. A zero value uses the annotation
	// this module ships.
	//
	// It sits here because the two admission rules are read together: a
	// function is an action by having this shape or by being declared, and a
	// caller configuring one transport configures both at once.
	Declaration ActionDeclaration
}

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
}

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
	// Symbol is what the registration names: the handler itself for a raw
	// action, the generated entry point for a typed one.
	Symbol string
	// Published is the identifier client script calls the action through, and
	// Typed reports which admission rule let it in.
	Published string
	Typed     bool
}

type RegistryFormAction struct {
	// Selector is the opaque value the form's hidden field carries.
	Selector string
	// Package qualifies the handler symbol, such as "id_." It is empty for a
	// handler in the root package itself.
	Package string
	// Name is the exported Go function name.
	Name 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
	// ActionSelectorField is the hidden field the generated dispatcher reads the
	// selector out of. The template compiler wrote it into the form.
	ActionSelectorField string
}

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
	// PageFields fills the page component parameter struct.
	PageFields []ComposerArg
	// Layouts are the ancestor wrappers, outermost first.
	Layouts []ComposerLayout
	// PostPattern is the pattern the page's own POST route registers under,
	// empty where the route reaches no server function. A form carrying
	// server-action posts here rather than to the handler's own address, because
	// a form declaring no action submits to the document URL and that is what
	// carries the path parameters a handler serving /users/{id} needs.
	PostPattern string
	// FormActions are the server functions a native submit on this page can
	// reach: the ones declared in the route's own package and in every layout
	// wrapping it. One POST registration serves them all and the generated
	// dispatcher branches on the selector.
	FormActions []RegistryFormAction
}

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 Result struct {
	// Files are the emitted Go sources: a compiled component per template, a
	// typed decoder per route, and one registry in the route root.
	Files []Generated
	// Assets are the stylesheets and component scripts the tree's templates
	// extracted, deduplicated across the tree. A file name carries the hash of
	// its own bytes, so two templates producing one name produced identical
	// content and the duplicate is dropped rather than returned twice.
	//
	// Nothing writes them. Each carries Base, Extension, Content, and the URL it
	// was compiled against, which is what a caller needs to put the file where
	// that URL resolves. A page declaring a script block whose asset is dropped
	// leaves a reference to a file that answers 404.
	Assets []htmlbind.Asset
	// Actions is every server function the tree discovered, raw and typed
	// alike, in the order the registry registers them.
	//
	// A caller needs the typed ones: the entry point each is registered under
	// is emitted by the binding phase, which runs after this, so the signature
	// read here has to reach that phase. The raw ones are reported beside them
	// because one table is what every other consumer already reads.
	Actions []Action
}

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 ScriptAnswers struct {
	Handlers   map[string]htmlbind.ClientHandlerSet
	Parameters map[string][]string
}

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
	// CatchAllSuffix is what the router spells inside a catch-all segment where
	// net/http spells "...", so {rest...} becomes {rest} plus this. Empty uses
	// net/http's own marker, which leaves the pattern as discovered.
	//
	// RootPattern is the path the tree root registers under. Empty uses
	// net/http's "/{$}", the exact-match marker that keeps the root from
	// matching every path below it.
	//
	// Both exist because a router that does not read Go 1.22 patterns does not
	// merely fail on these two: it reads "{rest...}" as a parameter named
	// "rest..." and "{$}" as one named "$", so the route is silently installed
	// somewhere else rather than rejected.
	//
	// Neither has an "unsupported" spelling. Unlike the transform's router
	// target, where every field is caller-declared and an unset one is genuinely
	// unknown, these default to a working router, so an unset field cannot be
	// told from a router that reads Go 1.22 syntax and needs no rewrite.
	CatchAllSuffix string
	RootPattern    string
	// RequestType is the type of the request value generated code receives,
	// written verbatim. Empty spells the net/http request from HTTPAlias.
	//
	// It is separate from HTTPAlias because an alias reaches the spelling of a
	// type and not its shape: a transport carrying the request and the response
	// in one value has one parameter where net/http has two, which no renaming
	// of the package can express.
	RequestType string
	// HandlerParams is the parameter list an emitted handler literal declares.
	// Empty spells the net/http pair from HTTPAlias.
	HandlerParams string
	// Writer and Request are the identifiers a generated handler body uses for
	// the response and the request. Empty uses w and r.
	//
	// They are the same identifier on a transport whose one value carries both,
	// which is what collapses a runtime call's leading arguments; see
	// [Symbols.TransportArgs].
	Writer  string
	Request string
	// RequestIsContext records that the request value is itself a
	// context.Context, as fasthttp's RequestCtx is. When false the context is
	// read with a .Context() call, which is the net/http spelling.
	RequestIsContext bool
	// ErrorImport and ErrorAlias name the package providing the constructors
	// below and the request accessors. 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 the transport values followed by the error.
	BadRequest string
	Problem    string
	WriteError string
	// PathValue, QueryValues, and QueryLookup are selectors on ErrorAlias naming
	// the request accessors a generated decoder reads through.
	//
	// The decoder calls these rather than spelling methods on the request value
	// because fasthttp has no path routing of its own: its PathValue reads
	// whatever the router stored, so there is no method on the transport for a
	// method-shaped decoder to call. Routing both transports through the runtime
	// is what lets one decoder template serve either.
	PathValue   string
	QueryValues string
	QueryLookup string
	// ActionSelector and DispatchAction are selectors on ErrorAlias naming the
	// two halves of the page's own POST route: reading which server function a
	// native form submit named, and running it with the post-redirect-get default
	// applied when it writes nothing.
	//
	// They sit here for the same reason the accessors above do. Observing whether
	// a handler wrote a response means wrapping the transport's own writer, which
	// no template can spell portably.
	ActionSelector string
	DispatchAction 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 TypedSignature struct {
	// Params are the declared inputs, in order, after any leading context has
	// been trimmed. Each carries its name and the source text of its type.
	Params []Value
	// TakesContext records that the declaration opened with a context.Context,
	// on the terms the typed page entry point already reads one.
	TakesContext bool
	// Result is the type of the single non-error result, empty when the
	// function returns only an error.
	Result string
}

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
}