Documentation
¶
Overview ¶
Package compiler provides a compiler for GoSPA Single File Components (.gospa).
Index ¶
- Variables
- func ExtractTypes(script string) ([]Prop, []State)
- func GenerateGoStruct(name string, props []Prop) string
- func GenerateTSInterface(name string, props []Prop, states []State) string
- func ValidateSafeGoScript(script string) error
- func ValidateSafeScript(script string) error
- func ValidateSafeTSScript(script string) error
- type CompileOptions
- type ComponentType
- type GospaCompiler
- type Prop
- type RuntimeTier
- type State
Constants ¶
This section is empty.
Variables ¶
var ( // PropsRegex matches GoSPA $props() declarations. PropsRegex = regexp.MustCompile(`(?m)var\s+\{\s*(.*?)\s*\}\s*=\s*\$props\(\)`) // StateRegex matches GoSPA $state() declarations. StateRegex = regexp.MustCompile(`(?m)(?:var|const)\s+([a-zA-Z0-9_]+)\s*=\s*\$state\((.*?)\)`) // DerivedRegex matches GoSPA $derived() declarations. DerivedRegex = regexp.MustCompile(`\$derived\((.*?)\)`) // EffectRegex matches GoSPA $effect() declarations. EffectRegex = regexp.MustCompile(`(?s)\$effect\(func\(\)\s*\{(.*?)\}\)`) // CSSDotRegex matches CSS class selectors. CSSDotRegex = regexp.MustCompile(`\.([a-zA-Z][a-zA-Z0-9-_]*)`) // ReactiveLabelRegex matches GoSPA $: reactive labels. ReactiveLabelRegex = regexp.MustCompile(`\$:\s*([a-zA-Z0-9_]+)\s*=\s*([^;\n]+)`) // CSSElementRegex matches CSS element selectors. CSSElementRegex = regexp.MustCompile(`(?m)^([a-z0-9]+)\s*\{`) )
var DangerousCallPatterns = []*regexp.Regexp{ regexp.MustCompile(`exec\.Command`), regexp.MustCompile(`os\.OpenFile`), regexp.MustCompile(`os\.Create`), regexp.MustCompile(`os\.Remove`), regexp.MustCompile(`os\.Rename`), regexp.MustCompile(`os\.Mkdir`), regexp.MustCompile(`os\.MkdirAll`), regexp.MustCompile(`os\.WriteFile`), regexp.MustCompile(`os\.RemoveAll`), regexp.MustCompile(`os\.Symlink`), regexp.MustCompile(`os\.Setenv`), regexp.MustCompile(`os\.Getenv`), regexp.MustCompile(`system\s*\(`), regexp.MustCompile(`syscall\.Exec`), regexp.MustCompile(`syscall\.ForkExec`), regexp.MustCompile(`unix\.Exec`), regexp.MustCompile(`unix\.ForkExec`), }
DangerousCallPatterns are regex patterns for unsafe function calls that should be rejected in SafeMode.
var DangerousImportNames = []string{
"os/exec", "exec",
"os",
"unsafe",
"syscall",
"plugin",
"runtime/debug",
"runtime/pprof",
"reflect",
"C",
}
DangerousImportNames are packages whose presence indicates a trust boundary violation when compiling SFCs from untrusted sources.
var DangerousTSPatterns = []*regexp.Regexp{ regexp.MustCompile(`(?m)\bimport\s+[^\n]*\bfrom\s*['\"](?:child_process|fs|fs/promises|os|net|tls|dgram|worker_threads|vm)['\"]`), regexp.MustCompile(`(?m)\brequire\s*\(\s*['\"](?:child_process|fs|fs/promises|os|net|tls|dgram|worker_threads|vm)['\"]\s*\)`), regexp.MustCompile(`(?m)\b(?:child_process\.)?(?:exec|execSync|spawn|spawnSync|fork)\s*\(`), regexp.MustCompile(`(?m)\b(?:fs|fs/promises)\s*\.\s*(?:writeFile|writeFileSync|rm|rmSync|unlink|unlinkSync|rename|renameSync|mkdir|mkdirSync)\s*\(`), regexp.MustCompile(`(?m)\b(?:process\.)?env\s*\[`), regexp.MustCompile(`(?m)\b(?:process\.)?env\s*\.`), }
DangerousTSPatterns are patterns that should be blocked when validating TypeScript snippets in SafeMode.
Functions ¶
func ExtractTypes ¶ added in v0.1.32
ExtractTypes parses the script content to find props and state.
func GenerateGoStruct ¶ added in v0.1.32
GenerateGoStruct generates a Go struct for the component props.
func GenerateTSInterface ¶ added in v0.1.32
GenerateTSInterface generates a TypeScript interface for the component state.
func ValidateSafeGoScript ¶ added in v0.1.37
ValidateSafeGoScript validates that script content does not contain dangerous patterns. Returns nil if the script is safe, or an error describing the dangerous pattern found.
func ValidateSafeScript ¶ added in v0.1.32
ValidateSafeScript is retained as a compatibility wrapper for callers/tests that validate Go snippets.
func ValidateSafeTSScript ¶ added in v0.1.37
ValidateSafeTSScript validates TypeScript snippets in SafeMode without attempting to parse them as Go.
Types ¶
type CompileOptions ¶
type CompileOptions struct {
Type ComponentType
IslandID string
Name string
PkgName string
Hydrate bool
HydrateMode string // immediate, visible, idle, interaction
ServerOnly bool
// RuntimeTier overrides the detected runtime complexity.
RuntimeTier RuntimeTier
// SafeMode enables stricter validation of script content.
// When true, the compiler checks that Go scripts parse as valid Go and
// rejects dangerous patterns such as exec.Command, os/exec, unsafe, or
// syscall imports. Use this when compiling .gospa from sources you do
// not fully trust (e.g., CMS-generated SFCs).
SafeMode bool
}
CompileOptions configures the compilation of a .gospa component.
type ComponentType ¶
type ComponentType string
ComponentType represents the type of a compiled component.
const ( ComponentTypeIsland ComponentType = "island" ComponentTypePage ComponentType = "page" ComponentTypeLayout ComponentType = "layout" ComponentTypeStatic ComponentType = "static" ComponentTypeServer ComponentType = "server" )
Component type constants.
type GospaCompiler ¶
type GospaCompiler struct{}
GospaCompiler handles the compilation of .gospa files.
func (*GospaCompiler) Compile ¶
func (c *GospaCompiler) Compile(opts CompileOptions, input string) (templ, ts string, err error)
Compile compiles a .gospa component into Templ and TypeScript. If opts.SafeMode is true, the script content is validated against a set of dangerous patterns before compilation proceeds.
func (*GospaCompiler) CompileLegacy ¶
func (c *GospaCompiler) CompileLegacy(goName, islandID, input, pkgName string) (templ, ts string, err error)
CompileLegacy preserves the old island-only API.
type RuntimeTier ¶ added in v0.1.36
type RuntimeTier string
RuntimeTier represents the complexity of the client runtime needed.
const ( // RuntimeTierMicro provides basic reactivity only. RuntimeTierMicro RuntimeTier = "micro" // RuntimeTierCore provides DOM bindings and event handling. RuntimeTierCore RuntimeTier = "core" // RuntimeTierFull provides all features including dynamic modules. RuntimeTierFull RuntimeTier = "full" )
RuntimeTier constants define the different levels of client-side runtime functionality.