analyzer

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func EventNameFromAttr

func EventNameFromAttr(attrName string) (wire string, ok bool)

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

func EventNamesFromTrigger(value string) []string

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

func WireName(name string) string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL