Documentation
¶
Overview ¶
Package analyzer implements the ghtmx semantic analysis passes over the shared AST (constitution A2/A4): hx-* attribute validation against the pinned htmx surface, and — in later milestones — binding resolution, fragment classification, and the event registry.
Analysis is accumulative, never fail-fast: all diagnostics for a run are collected so the CLI and LSP report a complete set.
Index ¶
- func EventNameFromAttr(attrName string) (wire string, ok bool)
- func EventNamesFromTrigger(value string) []string
- func ResolveBindings(file *parser.TemplateFile, env BindingEnv, sink *diag.Sink)
- func ValidateAttributes(file *parser.TemplateFile, surface *htmxsurface.Surface, sink *diag.Sink)
- func ValidateFragments(file *parser.TemplateFile, sink *diag.Sink)
- func ValidateImports(file *parser.TemplateFile, sink *diag.Sink)
- func WireName(name string) string
- type BindingEnv
- type DependencyFacts
- type EventInfo
- type FragmentInfo
- type SetAnalysis
- func (s *SetAnalysis) Check(table *routes.Table, sink *diag.Sink)
- func (s *SetAnalysis) Collect(file *parser.TemplateFile, pkgPath string)
- func (s *SetAnalysis) CollectFile(file *parser.TemplateFile)
- func (s *SetAnalysis) CollectFragments(file *parser.TemplateFile, pkgPath string)
- func (s *SetAnalysis) Events() []EventInfo
- func (s *SetAnalysis) FileDependencyFacts() map[string]DependencyFacts
- func (s *SetAnalysis) Fragments() map[string]map[string]FragmentInfo
- func (s *SetAnalysis) MarkBindingFile(file string)
- func (s *SetAnalysis) MarkBound(r routes.Route)
- func (s *SetAnalysis) MarkGoFragmentRefs(refs map[string]bool)
- func (s *SetAnalysis) RemoveFile(file string)
- func (s *SetAnalysis) SetSurface(surface *htmxsurface.Surface)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EventNameFromAttr ¶
EventNameFromAttr extracts the event a constant hx-on attribute listens to, if it is in the compiler-owned namespace. Exported so the LSP layer resolves references under exactly the rules diagnostics enforce.
func EventNamesFromTrigger ¶
EventNamesFromTrigger extracts the compiler-owned event names of a constant hx-trigger value. Filter brackets are stripped verbatim first; each comma-separated spec's first token is its event name. Exported so the LSP layer resolves references under exactly the rules diagnostics enforce.
func ResolveBindings ¶
func ResolveBindings(file *parser.TemplateFile, env BindingEnv, sink *diag.Sink)
ResolveBindings resolves route-aware hx-* verb bindings against the route table (FR-020, FR-022, FR-040) and lowers each resolved symbol binding into a constant attribute carrying the handler's registered path, so the generator folds it into the surrounding static markup with zero runtime cost.
Diagnostics: GHTMX-E0101 unknown handler (naming the symbol), GHTMX-E0102 verb mismatch (stating expected and actual verbs), GHTMX-E0103 direct binding to a parameterised route (directing to the generated constructor).
Expressions that are not symbol references — constructor calls on the generated package, and arbitrary expressions — are left untouched here: constructor emission and the carve-out reporter are separate passes.
func ValidateAttributes ¶
func ValidateAttributes(file *parser.TemplateFile, surface *htmxsurface.Surface, sink *diag.Sink)
ValidateAttributes checks every hx-* attribute in the template file against the surface for the configured htmx version (FR-024, FR-041, FR-044): unknown names (GHTMX-E0201, with did-you-mean suggestions), invalid constant values for constrained attributes (GHTMX-E0202), contradictory combinations on one element (GHTMX-E0203), names valid in the htmx family but not at the configured version — introduced later, or removed or renamed earlier, with the replacement named (GHTMX-E0501) — and, for families with explicit attribute inheritance, inheritable attributes that never reach the descendants issuing the requests (GHTMX-W0202).
Only constant names and values are validated: an expression attribute key, a dynamic value, or spread attributes are exempt from analysis entirely, mirroring the FR-042 conservatism.
func ValidateFragments ¶
func ValidateFragments(file *parser.TemplateFile, sink *diag.Sink)
ValidateFragments checks fragment declarations within one file: names must be unique in their scope (FR-030, GHTMX-E0301). Package-wide uniqueness — required for the generated entry points — is enforced when fragment code generation runs over the whole package.
func ValidateImports ¶ added in v0.1.11
func ValidateImports(file *parser.TemplateFile, sink *diag.Sink)
ValidateImports reports GHTMX-E0308 for template imports that collide with the imports every generated file declares (generator.RuntimeImports): the unaliased root-package import, and any import aliased to one of the names the generated import block claims. Without the check, the collision surfaces as a Go redeclaration error inside a *_ghtmx.go file the author did not write, at a line they cannot edit.
Header nodes are not scanned: they hold only pre-package comments and whitespace, where an import cannot legally appear.
func WireName ¶
WireName converts a declared event name to its kebab-case HX-Trigger wire name: UserCreated becomes user-created, UserID becomes user-id, HTMLLoaded becomes html-loaded. Attribute names are lowercased by HTML, so only a lower-case wire name can be listened to with hx-on. Trailing letters after an acronym split unhelpfully (UserIDs becomes user-i-ds) — prefer names without embedded plural acronyms.
Types ¶
type BindingEnv ¶
type BindingEnv struct {
// Table is the discovered route table.
Table *routes.Table
// Surface supplies the verb for each hx-* attribute.
Surface *htmxsurface.Surface
// PkgPath is the import path of the Go package containing the template
// file; bare handler identifiers resolve against it.
PkgPath string
// GeneratedPkgName is the central generated package's name
// (ghtmxgen by default): constructor calls on it are typed route
// constructors.
GeneratedPkgName string
// Constructors maps generated constructor names to their routes,
// produced by central.Naming over the same table.
Constructors map[string]central.Constructor
// SetAnalysis, when set, receives bound-route marks for the
// unreachable-route check (FR-043).
SetAnalysis *SetAnalysis
}
BindingEnv is the context binding resolution needs beyond the AST.
type DependencyFacts ¶
type DependencyFacts struct {
// Decls are the templates and fragments the file declares.
Decls []string
// Refs are the file's resolved template and fragment references.
Refs []string
// BindsRoutes reports whether generated output embeds route state.
BindsRoutes bool
// EventDecls and EventRefs are wire names declared and referenced.
EventDecls []string
EventRefs []string
}
DependencyFacts is the per-file summary the dependency graph consumes (FR-061). Names are package-path-qualified ("pkg.Name").
type EventInfo ¶
type EventInfo struct {
Name string // Go-side name, e.g. "UserCreated"
WireName string // HX-Trigger name, e.g. "user-created"
Params string // declared payload parameter list, e.g. "(id string)"
Pos diag.Position
}
EventInfo describes one declared event in the compiled set.
type FragmentInfo ¶
type FragmentInfo struct {
Name string
PkgPath string
ParamCount int
Variadic bool
Pos diag.Position
TopLevel bool
}
FragmentInfo describes one declared fragment in the compiled set.
func (FragmentInfo) Exported ¶
func (f FragmentInfo) Exported() bool
Exported reports whether the fragment is visible outside its package.
type SetAnalysis ¶
type SetAnalysis struct {
// contains filtered or unexported fields
}
SetAnalysis accumulates whole-compiled-set facts that no single file can decide alone: literal emitted IDs, literal ID-selector targets (FR-042), and which routes templates actually bind (FR-043). It is safe for concurrent per-file collection; re-collecting a file replaces its contribution, so watch-mode re-analysis stays correct.
func NewSetAnalysis ¶
func NewSetAnalysis() *SetAnalysis
NewSetAnalysis returns an empty whole-set collector.
func (*SetAnalysis) Check ¶
func (s *SetAnalysis) Check(table *routes.Table, sink *diag.Sink)
Check emits the whole-set diagnostics: GHTMX-W0201 for a fully-literal ID-selector target matching no literal ID emitted anywhere in the compiled set (warning by default, error under strict mode via the sink's severity overrides), and GHTMX-W0104 for a route never bound from any template.
func (*SetAnalysis) Collect ¶
func (s *SetAnalysis) Collect(file *parser.TemplateFile, pkgPath string)
Collect records the file's facts and fragment data in one step, so a concurrent snapshot never sees one map updated and the other not.
func (*SetAnalysis) CollectFile ¶
func (s *SetAnalysis) CollectFile(file *parser.TemplateFile)
CollectFile records the file's literal emitted IDs and literal ID-only target selectors. Selectors and IDs containing any interpolated expression are never collected: the check is deliberately conservative.
func (*SetAnalysis) CollectFragments ¶
func (s *SetAnalysis) CollectFragments(file *parser.TemplateFile, pkgPath string)
CollectFragments records the file's fragment declarations and its candidate fragment references for whole-set resolution (FR-032). pkgPath is the import path of the package containing the file.
func (*SetAnalysis) Events ¶
func (s *SetAnalysis) Events() []EventInfo
Events returns the declared events sorted by wire name, for event code generation. On duplicates the first declaration in sorted file order wins, mirroring the diagnostic.
func (*SetAnalysis) FileDependencyFacts ¶
func (s *SetAnalysis) FileDependencyFacts() map[string]DependencyFacts
FileDependencyFacts snapshots every collected file's dependency facts.
func (*SetAnalysis) Fragments ¶
func (s *SetAnalysis) Fragments() map[string]map[string]FragmentInfo
Fragments returns the whole-set fragment registry keyed by package path then name. Used by fragment code generation and reference resolution.
func (*SetAnalysis) MarkBindingFile ¶
func (s *SetAnalysis) MarkBindingFile(file string)
MarkBindingFile records that the file holds at least one route binding: its generated output embeds route state, so a route change invalidates it (FR-061). The file must already be collected.
func (*SetAnalysis) MarkBound ¶
func (s *SetAnalysis) MarkBound(r routes.Route)
MarkBound records that a route was bound from a template.
func (*SetAnalysis) MarkGoFragmentRefs ¶
func (s *SetAnalysis) MarkGoFragmentRefs(refs map[string]bool)
MarkGoFragmentRefs replaces the set of fragment base names rendered from hand-written Go source through their generated <name>Fragment entry points (FR-034's handler-explicit path). The set comes from route discovery's syntax-only package load and refreshes with every rediscovery, so watch mode stays current.
func (*SetAnalysis) RemoveFile ¶
func (s *SetAnalysis) RemoveFile(file string)
RemoveFile drops a deleted file's contribution to the whole-set state, so the dependency graph and checks stop seeing it (FR-061).
func (*SetAnalysis) SetSurface ¶ added in v0.1.23
func (s *SetAnalysis) SetSurface(surface *htmxsurface.Surface)
SetSurface pins the htmx surface the collector resolves attribute names against; nil keeps the syntactic collection. Call it before the first Collect/CollectFile: facts collected earlier are not recomputed.