source

Documentation

Overview

Package source holds the neutral leaf value types shared across the GOWDK compiler packages: source spans, route params, inline scripts, and backend binding metadata. These types carry no behavior and depend on nothing else in the module, so every layer (parser, AST, IR, manifest, generated output) can reference them without creating import cycles or coupling to the manifest page/component model.

Historically these lived in internal/manifest, which forced packages that only needed a SourceSpan to depend on the whole manifest model (and made internal/gwdkir depend on manifest). They were extracted here so the manifest model and the IR can both reference shared leaf types from a neutral home. manifest re-exports them as aliases for backward compatibility.

Index

• Constants
• func BackendInputFieldIntegerBitSize(goType string) int
• func BackendInputFieldSignedInteger(goType string) bool
• func BackendInputFieldTypeSupported(goType string) bool
• func BackendInputFieldUnsignedInteger(goType string) bool
• func BackendRouteMethod(value string) string
• func BackendRoutePath(value string) string
• func ErrorPagePath(value string) (string, error)
• func ExportedIdentifier(value string, fallback string) string
• func InlineScriptName(index int) string
• func IsRouteParamName(value string) bool
• func IsRouteParamType(value string) bool
• func OffsetOf(src []byte, pos SourcePosition) int
• func ParseRouteDeclaration(route string, lineNumber int, rawLine string) (string, []RouteParam, []NamedSpan, error)
• func ParseRoutePattern(route string) (RoutePattern, []RouteIssue)
• func RouteContainsQueryOutsideParams(route string) bool
• func SupportedBackendInputFieldTypes() []string
• func ValidateBackendRoutePath(value string) error
• func ValidateBackendRoutePattern(value string) error
• type BackendBinding
• type BackendBindingStatus
• type BackendInputField
• type BackendInputFieldKind
• type BackendInputFieldTypeInfo
  • func LookupBackendInputFieldType(name string) (BackendInputFieldTypeInfo, bool)
  • func MustBackendInputFieldType(name string) BackendInputFieldTypeInfo
• type BackendSignatureKind
• type InlineScript
• type NamedSpan
• type RelatedSpan
• type RouteIssue
• type RouteParam
  • func RouteParamsFromPath(route string) []RouteParam
• type RouteParamSegmentInfo
  • func ParseRouteParamSegment(segment string) (RouteParamSegmentInfo, bool)
• type RoutePattern
• type SSRLoadReplacement
• type SSRReplacement
• type SourcePosition
  • func PositionAt(src []byte, offset int) SourcePosition
• type SourceSpan

Constants

const (
	BackendInputTypeString      = "string"
	BackendInputTypeBool        = "bool"
	BackendInputTypeInt         = "int"
	BackendInputTypeInt8        = "int8"
	BackendInputTypeInt16       = "int16"
	BackendInputTypeInt32       = "int32"
	BackendInputTypeInt64       = "int64"
	BackendInputTypeRune        = "rune"
	BackendInputTypeUint        = "uint"
	BackendInputTypeUint8       = "uint8"
	BackendInputTypeUint16      = "uint16"
	BackendInputTypeUint32      = "uint32"
	BackendInputTypeUint64      = "uint64"
	BackendInputTypeByte        = "byte"
	BackendInputTypeStringSlice = "[]string"
)

const RestRoutePatternPlaceholder = "{**}"

RestRoutePatternPlaceholder is the normalized route pattern segment for a trailing rest parameter such as {path...}.

Functions

func BackendInputFieldIntegerBitSize

func BackendInputFieldIntegerBitSize(goType string) int

BackendInputFieldIntegerBitSize returns the explicit bit size passed to form integer decoders. Zero means the platform-sized int or uint type.

func BackendInputFieldSignedInteger

func BackendInputFieldSignedInteger(goType string) bool

BackendInputFieldSignedInteger reports whether goType uses the signed integer form decoder.

func BackendInputFieldTypeSupported

func BackendInputFieldTypeSupported(goType string) bool

BackendInputFieldTypeSupported reports whether goType is a form-decoder type supported by compiler validation and generated action decoders.

func BackendInputFieldUnsignedInteger

func BackendInputFieldUnsignedInteger(goType string) bool

BackendInputFieldUnsignedInteger reports whether goType uses the unsigned integer form decoder.

func BackendRouteMethod

func BackendRouteMethod(value string) string

BackendRouteMethod returns the normalized HTTP method spelling used by generated backend route metadata.

func BackendRoutePath

func BackendRoutePath(value string) string

BackendRoutePath returns the normalized path key used by generated backend routers after ValidateBackendRoutePath has accepted the source value.

func ErrorPagePath

func ErrorPagePath(value string) (string, error)

ErrorPagePath returns a clean generated-output-relative error page path.

func ExportedIdentifier

func ExportedIdentifier(value string, fallback string) string

ExportedIdentifier returns a PascalCase Go identifier fragment derived from value. Underscores are preserved because they are valid Go identifier characters and can distinguish otherwise identical generated names. fallback is returned when value contains no identifier characters.

func InlineScriptName

func InlineScriptName(index int) string

InlineScriptName returns the deterministic generated filename for the zero-based inline browser script declaration index in one source owner.

func IsRouteParamName

func IsRouteParamName(value string) bool

IsRouteParamName reports whether value is a valid route param identifier.

func IsRouteParamType

func IsRouteParamType(value string) bool

IsRouteParamType reports whether value is a supported route param type.

func OffsetOf

func OffsetOf(src []byte, pos SourcePosition) int

OffsetOf returns the 0-based byte offset into src for a 1-based line/column position (column counted in runes). An unset position (non-positive line or column) maps to 0, and a position past the end of src is clamped to len(src). It is the inverse of PositionAt for in-bounds, rune-aligned positions.

func ParseRouteDeclaration

func ParseRouteDeclaration(route string, lineNumber int, rawLine string) (string, []RouteParam, []NamedSpan, error)

ParseRouteDeclaration extracts typed params from a source route declaration and returns the normalized path used by downstream metadata.

func ParseRoutePattern

func ParseRoutePattern(route string) (RoutePattern, []RouteIssue)

ParseRoutePattern validates and normalizes a declared route. Dynamic segment names normalize to "{}"; a trailing rest segment normalizes to "{**}".

func RouteContainsQueryOutsideParams

func RouteContainsQueryOutsideParams(route string) bool

RouteContainsQueryOutsideParams reports whether route contains a "?" outside a {param} segment.

func SupportedBackendInputFieldTypes

func SupportedBackendInputFieldTypes() []string

func ValidateBackendRoutePath

func ValidateBackendRoutePath(value string) error

ValidateBackendRoutePath rejects paths that would be unsafe or ambiguous when registered as generated backend routes.

func ValidateBackendRoutePattern

func ValidateBackendRoutePattern(value string) error

ValidateBackendRoutePattern rejects unsafe generated route patterns while allowing whole-segment route params such as /patients/{id:int}.

Types

type BackendBinding

type BackendBinding struct {
	Kind         string
	PageID       string
	Source       string
	Span         SourceSpan
	BlockName    string
	Method       string
	Route        string
	ImportPath   string
	PackageName  string
	FunctionName string
	Signature    BackendSignatureKind
	InputType    string
	InputPointer bool
	InputFields  []BackendInputField
	Status       BackendBindingStatus
	Message      string
	// UnexportedCandidate is set when a handler is missing but a same-named
	// unexported Go function exists in the inspected package, so tooling can
	// explain that the function is present but not exported.
	UnexportedCandidate bool
	// Ambiguous is set when the same handler name is declared in more than one
	// Go source (sibling same-package code and an inline go {} block), so tooling
	// reports the conflict instead of silently preferring one.
	Ambiguous bool
}

BackendBinding describes the Go handler selected for a backend block (a page load, act, api, or fragment block, or a standalone Go endpoint).

type BackendBindingStatus

type BackendBindingStatus string

BackendBindingStatus describes whether a .gwdk backend block has a matching same-package Go handler.

const (
	BackendBindingBound                BackendBindingStatus = "bound"
	BackendBindingMissing              BackendBindingStatus = "missing"
	BackendBindingUnsupportedSignature BackendBindingStatus = "unsupported_signature"
)

type BackendInputField

type BackendInputField struct {
	FieldName string
	FormName  string
	Type      string // canonical value from LookupBackendInputFieldType
}

BackendInputField describes one form field decoded into a Go action input struct from compile-time Go AST metadata.

type BackendInputFieldKind

type BackendInputFieldKind string

const (
	BackendInputFieldKindString      BackendInputFieldKind = "string"
	BackendInputFieldKindBool        BackendInputFieldKind = "bool"
	BackendInputFieldKindSignedInt   BackendInputFieldKind = "signed_int"
	BackendInputFieldKindUnsignedInt BackendInputFieldKind = "unsigned_int"
	BackendInputFieldKindStringSlice BackendInputFieldKind = "string_slice"
)

type BackendInputFieldTypeInfo

type BackendInputFieldTypeInfo struct {
	Name    string
	Kind    BackendInputFieldKind
	BitSize int
}

BackendInputFieldTypeInfo describes one Go type accepted for generated backend input decoding and contract input metadata.

func LookupBackendInputFieldType

func LookupBackendInputFieldType(name string) (BackendInputFieldTypeInfo, bool)

LookupBackendInputFieldType returns the canonical metadata for a supported backend input field type.

func MustBackendInputFieldType

func MustBackendInputFieldType(name string) BackendInputFieldTypeInfo

MustBackendInputFieldType returns the metadata for name and panics when a compiler-generated backend input field carries an unsupported type.

type BackendSignatureKind

type BackendSignatureKind string

BackendSignatureKind describes the supported Go handler shape.

const (
	BackendSignatureAction0       BackendSignatureKind = "action0"
	BackendSignatureActionValues  BackendSignatureKind = "action_values"
	BackendSignatureActionForm    BackendSignatureKind = "action_form"
	BackendSignatureActionFormPtr BackendSignatureKind = "action_form_ptr"
	BackendSignatureAPI           BackendSignatureKind = "api"
	BackendSignatureFragment      BackendSignatureKind = "fragment"
	BackendSignatureLoad          BackendSignatureKind = "load"
	BackendSignatureLoadError     BackendSignatureKind = "load_error"
)

type InlineScript

type InlineScript struct {
	Name string
	Body string
	Span SourceSpan
}

InlineScript records browser module code declared directly inside a .gwdk source file. Path-based script declarations should remain preferred.

type NamedSpan

type NamedSpan struct {
	Name string
	Span SourceSpan
}

NamedSpan records the source range for a named declaration or reference.

type RelatedSpan

type RelatedSpan struct {
	Source  string
	Span    SourceSpan
	Message string
}

RelatedSpan is a secondary source location attached to a diagnostic, such as the first declaration that a conflict diagnostic also points at. Source is the owning file label (matching a diagnostic's primary Source) and may be empty for a same-file relation. Message is a short note shown alongside the location (for example "first declared here").

type RouteIssue

type RouteIssue struct {
	Code            string
	Message         string
	Param           string
	ParamOccurrence int
}

RouteIssue describes one route validation problem without binding it to a compiler diagnostic type.

type RouteParam

type RouteParam struct {
	Name string
	Type string
	Span SourceSpan
}

RouteParam describes one dynamic route parameter and its declared scalar type. Empty Type means string for compatibility with legacy {name} syntax.

func RouteParamsFromPath

func RouteParamsFromPath(route string) []RouteParam

RouteParamsFromPath parses dynamic route parameters from a route pattern.

type RouteParamSegmentInfo

type RouteParamSegmentInfo struct {
	Name    string
	Type    string
	Rest    bool
	HasType bool
}

RouteParamSegmentInfo describes a single dynamic route segment.

func ParseRouteParamSegment

func ParseRouteParamSegment(segment string) (RouteParamSegmentInfo, bool)

ParseRouteParamSegment parses {name}, {name:type}, and {name...} segments.

type RoutePattern

type RoutePattern struct {
	Pattern   string
	Params    []string
	RestParam string
}

RoutePattern describes the normalized shape of one route declaration.

type SSRLoadReplacement

type SSRLoadReplacement struct {
	Path        string
	Placeholder string
}

SSRLoadReplacement maps a generated placeholder back to a request-time load field path.

type SSRReplacement

type SSRReplacement struct {
	Param       string
	Placeholder string
}

SSRReplacement maps a generated placeholder back to a request route param.

type SourcePosition

type SourcePosition struct {
	Line   int
	Column int
	Offset int
}

SourcePosition is a 1-based source location in a parsed .gwdk file.

Offset is the 0-based byte offset of the position into the source buffer. It is the exact substrate for AST-backed formatting, precise LSP edits, and exact diagnostic ranges, none of which should re-derive offsets from line/column. Offset is best-effort: some parser spans are still line-derived and leave Offset at its zero value while Line/Column are set. Use PositionAt/OffsetOf to convert against a source buffer when an exact offset is required. Set-ness of a position is determined by Line/Column being positive, not by Offset, because byte offset 0 is a valid first-byte position.

func PositionAt

func PositionAt(src []byte, offset int) SourcePosition

PositionAt returns the 1-based line/column (column counted in runes, matching the parser's rune-column spans) for a 0-based byte offset into src, with Offset set to that byte offset. The offset is clamped to the buffer bounds.

type SourceSpan

type SourceSpan struct {
	Start SourcePosition
	End   SourcePosition
}

SourceSpan is a 1-based source range. End is exclusive.