compiler

type ASTContextValidateFunc ¶ added in v0.48.0

type ASTContextValidateFunc func(ctx context.Context, ast Expr, meta map[string]any) error

ASTContextValidateFunc validates a parsed tree using the execution context and source compile metadata. It runs during compilation, before lowering.

type ASTValidateFunc ¶ added in v0.28.0

type ASTValidateFunc func(ast Expr, meta map[string]any) error

ASTValidateFunc validates the parsed tree using the source's compile metadata. It runs during compilation, before the AST is lowered into runtime actions.

type ActionGraph ¶ added in v0.23.0

type ActionGraph struct {
	Entry string            `json:"entry,omitempty"`
	Exit  string            `json:"exit,omitempty"`
	Nodes []ActionGraphNode `json:"nodes,omitempty"`
	Edges []ActionGraphEdge `json:"edges,omitempty"`
}

func BuildActionGraph(resolver CapabilityResolver, expr Expr) (*ActionGraph, error)

type ActionGraphDescription ¶ added in v0.23.0

type ActionGraphDescription struct {
	Kind        string
	Name        string
	Form        ActionGraphForm
	ChildLabels []string
}

type ActionGraphEdge ¶ added in v0.23.0

type ActionGraphEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
	Kind string `json:"kind"`
}

type ActionGraphForm ¶ added in v0.23.0

type ActionGraphForm uint8

const (
	ActionGraphOpaque ActionGraphForm = iota
	ActionGraphParallel
	ActionGraphChoice
	ActionGraphCatch
)

type ActionGraphNode ¶ added in v0.23.0

type ActionGraphNode struct {
	ID        string   `json:"id"`
	Kind      string   `json:"kind"`
	Name      string   `json:"name,omitempty"`
	File      string   `json:"file,omitempty"`
	Line      int      `json:"line,omitempty"`
	Column    int      `json:"column,omitempty"`
	Modifiers []string `json:"modifiers,omitempty"`
}

type ActionGraphProvider ¶ added in v0.23.0

type ActionGraphProvider interface {
	DescribeActionGraph() ActionGraphDescription
}

type ArgFieldSpec ¶ added in v0.23.0

type ArgFieldSpec struct {
	Name string
	Kind ArgKind
	// Optional suppresses the default required-field check for capability
	// references. It has no effect on ArgAny, ArgString, ArgInt, or ArgBool.
	Optional bool
}

ArgFieldSpec declares the compiler-level kind of one argument of a capability. Bundles publish their specs via Bundle.ArgSchemas.

type ArgKind ¶ added in v0.23.0

type ArgKind uint8

ArgKind describes the compiler-level type of one capability argument.

const (
	// ArgAny is untyped; no compile-time validation applies.
	ArgAny ArgKind = iota
	// ArgString is a plain string; the value is passed through.
	ArgString
	// ArgInt is an integer literal.
	ArgInt
	// ArgBool is a boolean literal.
	ArgBool
	// ArgCapabilityRef is a statically resolved reference to an action.
	// The parser must present a bare identifier; quoted strings are
	// rejected, and the value is translated through TranslateKeyword
	// and verified against the resolver at compile time.
	ArgCapabilityRef
	// ArgCapabilityRefList is a list of ArgCapabilityRef.
	ArgCapabilityRefList
)

type AssertExpr ¶ added in v0.8.0

type AssertExpr struct {
	Condition string
	Message   string
	Pos       Position
}

AssertExpr: assert(condition, message).

func (*AssertExpr) Analyze(CapabilityResolver) error

func (a *AssertExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (a *AssertExpr) Children() []Expr

func (*AssertExpr) Node()

type Associativity ¶ added in v0.23.0

type Associativity uint8

const (
	Left Associativity = iota
	Right
)

type Atom ¶ added in v0.23.0

type Atom struct {
	Name              string
	Params            map[string]string
	ParamValues       map[string]any // native symbol values; takes precedence over Params
	Modifiers         []string
	ModifierValues    []ModifierValue  // parallel to Modifiers for quoted or native values
	ModifierSources   []ModifierSource // parallel to Modifiers; same length
	Args              map[string]*Value
	HasArgumentObject bool // true when the atom used @{...}, including an empty object
	// NamedPipelineArgs marks `pipeline.NAME @{...}` as a complete request object.
	// The pipeline extension sets this; values are resolved against state at runtime.
	NamedPipelineArgs bool
	Prompt            string
	Targets           []string
	Excludes          []string
	// ConfigInject marks an atom written as `op @config`. For stream
	// sources and operators, fields matching @config.<json_name> values
	// are injected into their parameters at build time.
	ConfigInject bool
	Pos          Position // source position of the atom, for compile-time diagnostics
}

Atom is a single runtime action call.

func (*Atom) Analyze(CapabilityResolver) error

func (a *Atom) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (*Atom) Children() []Expr

func (*Atom) Node()

type AtomAdviseFunc ¶ added in v0.23.0

type AtomAdviseFunc func(atom *Atom, builder *action.Builder[any, any]) error

type AtomSpec ¶ added in v0.23.0

type AtomSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Tags        []string        `json:"tags,omitempty"`
	Scope       string          `json:"scope,omitempty"`
	ReqFields   []FieldSpec     `json:"req_fields,omitempty"`
	ResFields   []FieldSpec     `json:"res_fields,omitempty"`
	Example     json.RawMessage `json:"example,omitempty"`
}

type BlockEntry ¶ added in v0.52.0

type BlockEntry struct {
	Text string
	Span SourceSpan
}

BlockEntry is one top-level comma-separated block entry and its source span.

type BlockRead ¶ added in v0.52.0

type BlockRead struct {
	Body     []string
	Entries  []BlockEntry
	Next     int
	Span     SourceSpan
	BodySpan SourceSpan
}

BlockRead contains the entries and parser-derived spans for a directive block.

func ReadBlockWithSpans(lines []string, start int) (BlockRead, error)

type BoundarySpec ¶ added in v0.23.0

type BoundarySpec struct {
	Name        string
	Description string
	Consume     func(stream action.AnyStreamAction) *action.Builder[any, any]
}

BoundarySpec is a stream-to-unary adapter. It is the only place in a pipeline where iter.Seq2[T, error] becomes a single value.

func BoundaryByName(name string) (BoundarySpec, bool)

func NamedBoundaries() []BoundarySpec

type BuildContext ¶ added in v0.23.0

type BuildContext struct {
	Resolver   CapabilityResolver
	Modifiers  *ModifierTable
	Advisers   []AtomAdviseFunc
	Introspect bool
}

BuildContext carries every dependency a node needs to lower itself into a runnable action. It is deliberately a small value struct: the AST knows how to Build itself, core just provides the pieces.

type BuildExtension ¶ added in v0.36.0

type BuildExtension struct {
	Always    bool
	Modifiers []string
	Requires  []string
	Replaces  []string
	Sources   func(meta map[string]any) []string
}

BuildExtension describes the source-level dependencies of a bundle for generated Go builds. It is deliberately a token-level linking contract, not an AST-level guarantee that every selected action executes.

type BuildSource ¶ added in v0.36.0

type BuildSource = BuildUsage

BuildSource is the source-oriented spelling used by build planners.

type BuildUsage ¶ added in v0.36.0

type BuildUsage struct {
	File       string
	Raw        string
	Clean      string
	Metadata   map[string]any
	Directives []string
}

BuildUsage is one source contribution considered by the generated-build planner. Raw preserves syntax inside pipeline/macro bodies that preprocessing may remove; Clean includes constants and other substitutions.

type Bundle ¶ added in v0.23.0

type Bundle struct {
	ID          string
	Alias       string // Local @require qualifier replacing library namespaces for this compilation.
	Libraries   []action.Library
	Directives  []Directive
	Modifiers   []Modifier
	Operators   []Operator
	Primaries   []PrimaryExtension
	Materialize Materializer
	// MaterializePhase defaults to MaterializeDeclarations; see materializer-lifecycle.md.
	MaterializePhase MaterializePhase
	OnPreprocess     func(meta map[string]any) PreprocessContributions
	// InheritScope copies extension-owned compile metadata into a child scope
	// before child directives run. Implement it when child preprocessing depends
	// on parent declarations; propagation is opt-in per bundle, and this callback
	// must merge into child metadata rather than replacing other extensions' data.
	// Treat parentMeta as read-only and copy values retained by the child.
	InheritScope  ScopeInheritFunc
	AtomAdvise    func(atom *Atom, builder *action.Builder[any, any]) error
	WrapPipeline  func(meta map[string]any, inner action.AnyAction) (action.AnyAction, error)
	Hooks         []action.AnyHook
	FileResolvers []FileResolverBinding

	ArgSchemas map[string][]ArgFieldSpec

	AcceptedOptions []string
	Symbols         []SymbolNamespace

	SelfTest func() []SelfTestSection
	Fixtures fs.FS
	// SourceModules contains compile-time .nflow sources addressable through
	// @include. Only paths listed in ExportedModules are visible to consumers.
	SourceModules   fs.FS
	ExportedModules []string

	// Shutdowns are invoked by the runner host after the outer invocation
	// completes. Compile and Execute do not close bundle resources.
	Shutdowns []ShutdownFunc

	// Build contributes optional source-level build planning metadata.
	Build BuildExtension
}

Bundle is one extension distribution.

func BundleWithFileResolver(bundle Bundle, provider xfile.Provider, resolver xfile.Resolver) Bundle

func ResolveBuildBundles(bundles []Bundle, selected []string) ([]Bundle, error)

func (b Bundle) AllSelfTests() []SelfTestSection

type BundleFactory ¶ added in v0.23.0

type BundleFactory func(opts map[string]string) Bundle

func Lookup(id string) (BundleFactory, bool)

func LookupBundleForModule(target string) (BundleFactory, bool)

type CapabilityContract ¶ added in v0.23.0

type CapabilityContract struct {
	Name   string
	Input  TypeDescriptor
	Output TypeDescriptor
}

type CapabilityRef ¶ added in v0.23.0

type CapabilityRef struct {
	Raw       string
	Canonical string
}

CapabilityRef is a statically resolved reference to an action, stream, or operator. Raw is the identifier as written in the DSL; Canonical is the name after translating native keywords. Both are held so diagnostics can point at the source form.

func ParseCapabilityRef(raw string) (CapabilityRef, error)

func ParseCapabilityRefList(line string) ([]CapabilityRef, error)

type CapabilityResolver ¶ added in v0.23.0

type CapabilityResolver interface {
	Action(name string) (action.AnyAction, bool)
	Stream(name string) (action.AnyStreamAction, bool)
	Operator(name string) (action.NamedOperator, bool)
	Mount(lib action.Library) error
	MountWithAlias(lib action.Library, alias string) error
}

CapabilityResolver decouples compiler analysis and building from concrete capability registries.

type Catalog ¶ added in v0.23.0

type Catalog struct {
	Atoms      []AtomSpec      `json:"atoms"`
	Sources    []SourceSpec    `json:"sources"`
	Operators  []OperatorSpec  `json:"operators"`
	Modifiers  []ModifierSpec  `json:"modifiers"`
	Directives []DirectiveSpec `json:"directives"`
}

Catalog is a machine-readable dump of the compiler surface: every atom, stream source, operator, modifier, and directive known to the resolver and tables. Consumed by `nflow catalog`, `nflow list`, `nflow show`, and the linter. Regenerated on every build — no manual maintenance.

func BuildCatalog(
	resolver CapabilityResolver,
	mt *ModifierTable,
	dt *DirectiveTable,
	ot *OperatorTable,
) Catalog

type CompileAndRunReq ¶ added in v0.23.0

type CompileAndRunReq struct {
	Source  string
	Payload any
}

type CompileOption ¶ added in v0.23.0

type CompileOption func(*compileConfig)

func BundleConfig(bundles ...Bundle) []CompileOption

func WithASTContextValidators(fns ...ASTContextValidateFunc) CompileOption

func WithASTValidators(fns ...ASTValidateFunc) CompileOption

func WithActionGraph() CompileOption

func WithActionIntrospection() CompileOption

func WithArgSchemas(schemas map[string][]ArgFieldSpec) CompileOption

func WithAtomAdvisors(fns ...AtomAdviseFunc) CompileOption

func WithCLIArgs(args []string) CompileOption

func WithConfigMap(cfg map[string]string) CompileOption

func WithLineModifiers(lookups ...LineLookup) CompileOption

func WithOnPreprocess(fns ...OnPreprocessFunc) CompileOption

func WithPipelineWrappers(fns ...PipelineWrapFunc) CompileOption

func WithScopeInheritors(fns ...ScopeInheritFunc) CompileOption

type CompileReq ¶ added in v0.23.0

type CompileReq struct {
	Source             string
	Name               string
	Line               int
	InheritedPrimaries []PrimaryExtension
	InheritedMeta      map[string]any
	Prepared           *PreparedSource
}

type CompileRes ¶ added in v0.23.0

type CompileRes struct {
	Program     action.AnyAction
	Meta        map[string]any
	AST         Expr
	ActionGraph *ActionGraph `json:"action_graph,omitempty"`
}

type ConditionalExpr ¶

type ConditionalExpr struct {
	Cond Expr
	Then Expr
	Else Expr
	Pos  Position
}

ConditionalExpr: cond ? then : else.

func (c *ConditionalExpr) Analyze(r CapabilityResolver) error

func (c *ConditionalExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (c *ConditionalExpr) Children() []Expr

func (*ConditionalExpr) Node()

type ContractProvider ¶ added in v0.23.0

type ContractProvider interface {
	Contract(name string) (CapabilityContract, bool)
}

type DeclarationHeader ¶ added in v0.52.0

type DeclarationHeader struct {
	Name            string
	Modifiers       []string
	QuotedModifiers []bool
	Next            int
	KeywordSpan     SourceSpan
	NameSpan        SourceSpan
	HeaderSpan      SourceSpan
}

func ParseDeclarationHeaderWithSpans(req DirectiveReq, directive string) (DeclarationHeader, error)

type DecoratedExpr ¶ added in v0.23.0

type DecoratedExpr struct {
	Inner          Expr
	Modifiers      []string
	ModifierValues []ModifierValue
	Pos            Position
}

DecoratedExpr wraps any primary with postfix modifiers, so constructs like `{ ... }:timeout=5s` and `loop(...) until(...):retry=3` behave like atoms for policy purposes. Build lowers Inner and applies the modifier chain through the same ModifierTable used for atoms.

func (d *DecoratedExpr) Analyze(r CapabilityResolver) error

func (d *DecoratedExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (d *DecoratedExpr) Children() []Expr

func (*DecoratedExpr) Node()

type Directive ¶ added in v0.23.0

type Directive struct {
	Name        string
	Example     string
	Handler     func(context.Context, DirectiveReq) (DirectiveRes, error)
	OpaqueBlock bool // The directive owns a `{ ... }` body that formatters must preserve verbatim.
}

func (d Directive) Action() *action.BuiltAction[DirectiveReq, DirectiveRes]

type DirectiveReq ¶ added in v0.23.0

type DirectiveReq struct {
	Lines   []string
	Body    []string
	I       int
	Out     map[string]any
	File    string
	BaseDir string
	Table   *DirectiveTable

	// Recurse runs the full preprocess on another .nflow file and
	// returns its cleaned body and file-local compilation state.
	Recurse func(absPath string) (clean string, meta map[string]any, err error)

	// Import parses a module in its own source scope. It never merges Out.
	Import func(target, namespace string) error
	// ImportAt is Import with parser-provided source spans for the import and
	// namespace. Directive handlers should prefer it when source offsets exist.
	ImportAt func(target, namespace string, span, targetSpan, namespaceSpan SourceSpan) error
	// contains filtered or unexported fields
}

func (req DirectiveReq) Declare(kind, name string) error

func (req DirectiveReq) DeclareAt(kind, name string, keyword, nameSpan, span SourceSpan) error

func (req DirectiveReq) DeclareIn(space, kind, name string) error

func (req DirectiveReq) DeclareInAt(space, kind, name string, keyword, nameSpan, span SourceSpan) error

func (req DirectiveReq) EmbedSource(clean string, metadata map[string]any)

func (req DirectiveReq) LineSpan(line int) SourceSpan

func (req DirectiveReq) Offset(line, column int) int

func (req DirectiveReq) RecordBlock(block SourceBlock)

func (req DirectiveReq) RecordDeclaration(declaration SourceDeclaration)

func (req DirectiveReq) RecordReference(reference SourceReference)

type DirectiveRes ¶ added in v0.23.0

type DirectiveRes struct {
	Next int

	// BlankLines lists 0-based line indices whose output must be empty
	// even when the source line has content. Block directives use it
	// to remove their own delimiter lines (e.g. @scope's header and
	// closing brace) without consuming the body, so nested directives
	// inside the body still run through the outer preprocess loop.
	BlankLines []int
}

type DirectiveSpec ¶ added in v0.23.0

type DirectiveSpec struct {
	Name    string `json:"name"`
	Example string `json:"example,omitempty"`
}

type DirectiveTable ¶ added in v0.23.0

type DirectiveTable struct {
	// contains filtered or unexported fields
}

func NewDirectiveTable(ds ...Directive) *DirectiveTable

func (t *DirectiveTable) Actions() []action.AnyAction

func (t *DirectiveTable) All() []Directive

func (t *DirectiveTable) ByName(name string) (*action.BuiltAction[DirectiveReq, DirectiveRes], bool)

type DynamicResolver ¶ added in v0.23.0

type DynamicResolver struct {
	// contains filtered or unexported fields
}

func NewDynamicResolver(baseLibs ...action.Library) (*DynamicResolver, error)

func (r *DynamicResolver) Action(name string) (action.AnyAction, bool)

func (r *DynamicResolver) ActionNames() []string

func (r *DynamicResolver) Actions() []action.AnyAction

func (r *DynamicResolver) Contract(name string) (CapabilityContract, bool)

func (r *DynamicResolver) Mount(lib action.Library) error

func (r *DynamicResolver) MountWithAlias(lib action.Library, alias string) error

func (r *DynamicResolver) Operator(name string) (action.NamedOperator, bool)

func (r *DynamicResolver) Operators() []action.NamedOperator

func (r *DynamicResolver) Stream(name string) (action.AnyStreamAction, bool)

func (r *DynamicResolver) Streams() []action.AnyStreamAction

type Expr ¶

type Expr interface {
	Node()
	Children() []Expr
	Analyze(resolver CapabilityResolver) error
	Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)
}

Expr is the root of the AST. Every node knows how to report its children, how to validate its contract (Analyze), and how to lower itself into a runnable action (Build). Core never switches on concrete AST types.

type FallbackExpr ¶

type FallbackExpr struct {
	L, R Expr
	Pos  Position
}

FallbackExpr: left || right.

func (f *FallbackExpr) Analyze(r CapabilityResolver) error

func (f *FallbackExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (f *FallbackExpr) Children() []Expr

func (*FallbackExpr) Node()

type FieldSpec ¶ added in v0.23.0

type FieldSpec struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Required bool   `json:"required,omitempty"`
	Usage    string `json:"usage,omitempty"`
}

type FileResolverBinding ¶ added in v0.28.0

type FileResolverBinding struct {
	Provider xfile.Provider
	Resolver xfile.Resolver
}

FileResolverBinding routes references from one provider to its resolver.

type KeywordMapping ¶ added in v0.23.0

type KeywordMapping struct {
	Keyword string
	Target  string
}

KeywordMapping pairs a native DSL keyword with the canonical action name it compiles to.

func KeywordMappings() []KeywordMapping

type KeywordPrimary ¶ added in v0.23.0

type KeywordPrimary interface {
	PrimaryExtension
	Keyword() string
}

KeywordPrimary is the keyword-dispatch contract.

type Lexer ¶

type Lexer struct {
	// contains filtered or unexported fields
}

func NewLexer(src string) *Lexer

func (l *Lexer) Next() Token

type LineLookup ¶ added in v0.23.0

type LineLookup struct {
	Source  ModifierSource
	Fn      func(line int) []string
	ValueFn func(line int) []ModifierValue
}

func LineModifiersFromOptions(mt *ModifierTable, opts []CompileOption) []LineLookup

type LiteralExpr ¶ added in v0.26.0

type LiteralExpr struct {
	Val any
	Pos Position
}

func (*LiteralExpr) Analyze(CapabilityResolver) error

func (l *LiteralExpr) Build(_ context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (*LiteralExpr) Children() []Expr

func (*LiteralExpr) Node()

type LoopExpr ¶

type LoopExpr struct {
	Body  Expr
	Until string
	Pos   Position
}

LoopExpr: loop(body) until(condition).

func (l *LoopExpr) Analyze(r CapabilityResolver) error

func (l *LoopExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (l *LoopExpr) Children() []Expr

func (*LoopExpr) Node()

type MapEntry ¶ added in v0.8.0

type MapEntry struct {
	Key   string
	Value *Value
}

type MaterializePhase ¶ added in v0.36.0

type MaterializePhase int

MaterializePhase orders extension materializers within the compile lifecycle. Materializers in the same phase retain bundle registration order.

const (
	// MaterializeDeclarations mounts actions declared in extension metadata.
	// The zero value preserves the behavior of existing extension bundles.
	MaterializeDeclarations MaterializePhase = iota
	// MaterializeCompositions compiles declarations that consume mounted actions.
	MaterializeCompositions
)

type MaterializeReq ¶ added in v0.23.0

type MaterializeReq struct {
	Ctx      context.Context
	Meta     map[string]any
	Resolver CapabilityResolver
	Compile  func(name, source string, modifiers ...string) (action.AnyAction, error)
	// CompileValues carries explicitly typed modifier values without flattening
	// them through the legacy string callback.
	CompileValues func(name, source string, modifiers []ModifierValue) (action.AnyAction, error)
	Alias         string
	// Introspection enables retaining child-action relationships on materialized actions.
	Introspection bool
}

MaterializeReq passes context, metadata, and compiler to the materialization phase.

type Materializer ¶ added in v0.23.0

type Materializer func(req MaterializeReq) error

Materializer converts declarations from meta into executable actions in the resolver.

type MergeablePrimary ¶ added in v0.23.0

type MergeablePrimary interface {
	PrimaryExtension
	MergeWith(older PrimaryExtension) PrimaryExtension
}

MergeablePrimary is implemented by primary extensions that know how to combine themselves with an already-installed primary handling the same token or keyword.

NewPrimaryExtensionTable calls MergeWith instead of panicking when it encounters a duplicate and the newer extension implements this interface. The older extension is passed as the argument; the newer decides how to combine them.

This is what lets a bundle whose primary carries per-compilation state — the macros bundle is the canonical case — be installed more than once during a sub-pipeline compile without triggering the "duplicates fail loudly" panic. A genuine cross-bundle conflict (two unrelated bundles claiming the same token) still panics, because neither implements the interface.

type Modifier ¶ added in v0.23.0

type Modifier struct {
	Name        string
	Owner       ModifierOwner
	ValueKind   ModifierKind
	Unique      bool
	Inheritable bool
	Example     string
	Apply       func(b *action.Builder[any, any], raw string) error
	// ApplyNative consumes a symbol value already parsed according to its
	// explicit @symbols type; it must not parse or stringify the value.
	ApplyNative func(b *action.Builder[any, any], value any) error
	// ApplyTarget receives the original action as well as its dynamic builder.
	// Use it for compile-time annotations that validate against request schema.
	ApplyTarget func(target action.AnyAction, b *action.Builder[any, any], raw string) error
}

Modifier is one `:name` or `:name=value` annotation on an atom.

Name is the identifier without the leading colon. The configured Apply or ApplyTarget callback runs once per occurrence, in source order. The raw string is the DSL text after `=`, or "" for a flag. The parser has already stripped surrounding quotes and expanded adjacent tokens, so no modifier needs to worry about either.

Owner declares which subsystem owns the name. A modifier whose name is reserved by the Kernel or the grammar must be declared by its owner; NewModifierTable panics on a mismatch.

func Duration(name string, apply func(*action.Builder[any, any], time.Duration) *action.Builder[any, any]) Modifier

func Flag(name string, apply func(*action.Builder[any, any]) *action.Builder[any, any]) Modifier

func Float64(name string, apply func(*action.Builder[any, any], float64) *action.Builder[any, any]) Modifier

func Int(name string, apply func(*action.Builder[any, any], int) *action.Builder[any, any]) Modifier

func Int32(name string, apply func(*action.Builder[any, any], int32) *action.Builder[any, any]) Modifier

func Int64(name string, apply func(*action.Builder[any, any], int64) *action.Builder[any, any]) Modifier

func String(name string, apply func(*action.Builder[any, any], string) *action.Builder[any, any]) Modifier

func StringList(name string, apply func(*action.Builder[any, any], []string) *action.Builder[any, any]) Modifier

func WithInheritable(m Modifier) Modifier

func WithOwner(m Modifier, owner ModifierOwner) Modifier

func WithUnique(m Modifier) Modifier

type ModifierKind ¶ added in v0.23.0

type ModifierKind uint8

ModifierKind describes the compiler-level value shape of a modifier. The typed constructors (Duration, Int, Flag, ...) set it automatically, so most code never references it directly.

const (
	// ModifierKindAny accepts any value. It is the zero value, so a
	// modifier built via a raw struct literal (not a typed constructor)
	// performs no value validation.
	ModifierKindAny ModifierKind = iota
	ModifierKindFlag
	ModifierKindString
	ModifierKindStringList
	ModifierKindInt
	ModifierKindInt32
	ModifierKindInt64
	ModifierKindFloat64
	ModifierKindDuration
	ModifierKindJSON
)

func (k ModifierKind) String() string

type ModifierOwner ¶ added in v0.23.0

type ModifierOwner uint8

ModifierOwner identifies which subsystem owns a modifier name.

const (
	// OwnerBundle means the modifier is owned by the bundle that
	// declares it. Any bundle may declare a modifier with this owner.
	OwnerBundle ModifierOwner = iota
	// OwnerKernel means the modifier is a standard Kernel policy
	// modifier. Only the modifiers_core bundle may declare it.
	OwnerKernel
	// OwnerGrammar means the modifier is owned by the nflow grammar.
	// No bundle may declare it.
	OwnerGrammar
)

func RequiredModifierOwner(name string) ModifierOwner

type ModifierSource ¶ added in v0.23.0

type ModifierSource struct {
	Kind  string
	Label string
}

ModifierSource records where a modifier came from. Both fields are free-form strings: core never interprets them. Extensions and the parser populate them; `nflow explain` renders them.

Kind is a short category. Reserved values: "atom" for a modifier written directly on the atom. Extensions add their own ("scope", "profile", "pipeline", …).

Label identifies the specific origin within a kind — a profile name, a pipeline name. Empty when the kind alone is enough.

type ModifierSpec ¶ added in v0.23.0

type ModifierSpec struct {
	Name      string `json:"name"`
	ValueKind string `json:"value_kind"`
	Example   string `json:"example,omitempty"`
}

type ModifierTable ¶ added in v0.23.0

type ModifierTable struct {
	// contains filtered or unexported fields
}

ModifierTable indexes modifiers by name. Construction is eager: a duplicate name, or a reserved name declared by the wrong owner, panics.

func NewModifierTable(modifiers ...Modifier) *ModifierTable

func (t *ModifierTable) Actions() []action.AnyAction

func (t *ModifierTable) All() []Modifier

func (t *ModifierTable) ApplyAll(target action.AnyAction, raws []string) (action.AnyAction, error)

func (t *ModifierTable) ApplyAllValues(target action.AnyAction, values []ModifierValue) (action.AnyAction, error)

func (t *ModifierTable) ByName(name string) (Modifier, bool)

type ModifierValue ¶ added in v0.55.0

type ModifierValue struct {
	Raw    string
	Value  any
	Typed  bool
	Quoted bool
}

ModifierValue preserves the source spelling while optionally carrying a native, explicitly typed symbol value. Raw remains available for diagnostics and explain tooling.

type OnPreprocessFunc ¶ added in v0.23.0

type OnPreprocessFunc func(meta map[string]any) PreprocessContributions

OnPreprocessFunc is the compile-time hook fired between Preprocess and Parse. BundleConfig wires it from Bundle.OnPreprocess.

type Operator ¶ added in v0.23.0

type Operator struct {
	Meta    OperatorMeta
	Handler func(context.Context, OperatorReq) (OperatorRes, error)
}

func (o Operator) Action() *action.BuiltAction[OperatorReq, OperatorRes]

type OperatorMeta ¶ added in v0.23.0

type OperatorMeta struct {
	Name          string
	Token         TokenType
	Precedence    int
	Associativity Associativity
	Description   string
	Example       string
}

type OperatorReq ¶ added in v0.23.0

type OperatorReq struct {
	Left  Expr
	Right Expr
	Meta  *OperatorMeta
}

type OperatorRes ¶ added in v0.23.0

type OperatorRes struct {
	Node Expr
}

type OperatorSpec ¶ added in v0.23.0

type OperatorSpec struct {
	Name        string `json:"name"`
	Token       string `json:"token,omitempty"`
	Description string `json:"description,omitempty"`
	Example     string `json:"example,omitempty"`
}

type OperatorTable ¶ added in v0.23.0

type OperatorTable struct {
	// contains filtered or unexported fields
}

func NewOperatorTable(ops ...Operator) *OperatorTable

func (t *OperatorTable) Actions() []action.AnyAction

func (t *OperatorTable) All() []OperatorMeta

func (t *OperatorTable) ByName(name string) (OperatorMeta, *action.BuiltAction[OperatorReq, OperatorRes], bool)

func (t *OperatorTable) ByToken(tok TokenType) (OperatorMeta, *action.BuiltAction[OperatorReq, OperatorRes], bool)

type ParallelExpr ¶

type ParallelExpr struct {
	Branches []Expr
	Pos      Position
}

ParallelExpr: N branches executed concurrently.

func (p *ParallelExpr) Analyze(r CapabilityResolver) error

func (p *ParallelExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (p *ParallelExpr) Children() []Expr

func (*ParallelExpr) Node()

type Parser ¶

type Parser struct {
	// contains filtered or unexported fields
}

func NewParser(ctx context.Context, ops *OperatorTable, src string) *Parser

func NewParserWithFile(
	ctx context.Context,
	ops *OperatorTable,
	primaries *PrimaryExtensionTable,
	src, file string,
) *Parser

func NewParserWithFileOffset(
	ctx context.Context,
	ops *OperatorTable,
	primaries *PrimaryExtensionTable,
	src, file string,
	lineBase int,
) *Parser

func NewParserWithPrimaries(
	ctx context.Context,
	ops *OperatorTable,
	primaries *PrimaryExtensionTable,
	src string,
) *Parser

func (p *Parser) Advance()

func (p *Parser) Context() context.Context

func (p *Parser) Cur() Token

func (p *Parser) Current() Token

func (p *Parser) Fail(_ int, format string, args ...any) error

func (p *Parser) File() string

func (p *Parser) Next()

func (p *Parser) Parse() (Expr, error)

func (p *Parser) ParseExpr(minPrec int) (Expr, error)

func (p *Parser) Peek(offset int) Token

func (p *Parser) Position() Position

func (p *Parser) Src() string

func (p *Parser) SubParse(src string) (Expr, error)

func (p *Parser) WithLineModifiers(lookups ...LineLookup) *Parser

type PipeExpr ¶ added in v0.23.0

type PipeExpr struct {
	L, R Expr
	Pos  Position
}

PipeExpr: left -> right.

func (p *PipeExpr) Analyze(r CapabilityResolver) error

func (p *PipeExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (p *PipeExpr) Children() []Expr

func (*PipeExpr) Node()

type PipelineWrapFunc ¶ added in v0.23.0

type PipelineWrapFunc func(meta map[string]any, inner action.AnyAction) (action.AnyAction, error)

type Position ¶ added in v0.8.0

type Position struct {
	File string
	Line int
	Col  int
}

func DeclarationPosition(out map[string]any, space, name string) (Position, bool)

func PositionOf(err error) (Position, bool)

func (p Position) String() string

type Positioned ¶ added in v0.23.0

type Positioned interface {
	Position() Position
}

Positioned is implemented by errors that carry a source position. Walk the chain with errors.As to find the first one.

type PostfixExtension ¶ added in v0.23.0

type PostfixExtension interface {
	PrimaryExtension
	PostfixToken() TokenType
	MatchesPostfix(p *Parser) bool
	ParsePostfix(p *Parser, left Expr) (Expr, error)
}

PostfixExtension handles an operator-like form whose left operand has already been parsed. MatchesPostfix must not advance the parser; ParsePostfix is called only after it returns true.

type PreparedSource ¶ added in v0.23.0

type PreparedSource struct {
	// contains filtered or unexported fields
}

PreparedSource is the result of preprocessing one source. Its fields are intentionally opaque so callers can inspect metadata and pass the value to CompileAction without separating the source from its metadata.

func PrepareSource(ctx context.Context, dt *DirectiveTable, source, name string, opts ...CompileOption) (*PreparedSource, error)

func PreparedSourceFromPreprocessed(source, name, clean string, meta map[string]any, opts ...CompileOption) *PreparedSource

func (p *PreparedSource) ActionIntrospectionEnabled() bool

func (p *PreparedSource) CleanSource() string

func (p *PreparedSource) Contributions() PreprocessContributions

func (p *PreparedSource) Metadata() map[string]any

func (p *PreparedSource) SourceIdentity() (name, sha256Hex string)

func (p *PreparedSource) SourceIndex() SourceIndex

func (p *PreparedSource) SourceText() string

type PreprocessContributions ¶ added in v0.23.0

type PreprocessContributions struct {
	Primaries   []PrimaryExtension
	CompileOpts []CompileOption
}

func PreprocessContributionsFromMeta(meta map[string]any, opts ...CompileOption) PreprocessContributions

type PreprocessEvent ¶ added in v0.36.0

type PreprocessEvent struct {
	File       string
	Original   string
	Source     string
	Clean      string
	Metadata   map[string]any
	Directives []string
}

PreprocessEvent describes one successfully preprocessed source fragment. Events are synchronous and ordered children before parents. A diamond can report the same file twice because each include is a distinct evaluation. Observers must not mutate Metadata. Source includes substitutions performed by directives; Original preserves the input, and Clean is the executable body. Directives contains only handlers actually invoked in this fragment, not directive-like text in comments, strings or a captured declaration body.

type PreprocessObserver ¶ added in v0.36.0

type PreprocessObserver func(PreprocessEvent)

PreprocessObserver observes the existing directive lifecycle without replacing source loading, parsing directives or changing their execution.

type PrimaryExtension ¶ added in v0.23.0

type PrimaryExtension interface {
	Name() string
	Parse(p *Parser) (Expr, error)
}

PrimaryExtension is the shared contract for parser extensions. Implementations provide Name and Parse plus token, keyword, or postfix dispatch as needed.

type PrimaryExtensionTable ¶ added in v0.23.0

type PrimaryExtensionTable struct {
	// contains filtered or unexported fields
}

func DefaultPrimaryExtensions() *PrimaryExtensionTable

func NewPrimaryExtensionTable(exts ...PrimaryExtension) *PrimaryExtensionTable

func (t *PrimaryExtensionTable) All() []PrimaryExtension

func (t *PrimaryExtensionTable) ByKeyword(kw string) (PrimaryExtension, bool)

func (t *PrimaryExtensionTable) ByPostfix(tok TokenType) (PostfixExtension, bool)

func (t *PrimaryExtensionTable) ByToken(tt TokenType) (PrimaryExtension, bool)

type ProjectionExpr ¶

type ProjectionExpr struct {
	Raw string
	Pos Position
}

ProjectionExpr: raw content `{ ... }`.

func (*ProjectionExpr) Analyze(CapabilityResolver) error

func (p *ProjectionExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (p *ProjectionExpr) Children() []Expr

func (*ProjectionExpr) Node()

type RunCleanupFunc ¶ added in v0.49.0

type RunCleanupFunc func(context.Context) error

RunCleanupFunc releases a resource registered for one Flow invocation. Cleanup receives a fresh bounded context even if the run was canceled.

type RunReq ¶ added in v0.23.0

type RunReq struct {
	Program action.AnyAction
	Payload any
}

type RunRes ¶ added in v0.23.0

type RunRes struct {
	Output any
}

type RunScope ¶ added in v0.49.0

type RunScope struct {
	// contains filtered or unexported fields
}

RunScope is Flow-specific: xctx.NewScope provides pooled request metadata and a pool-release function, but no derived cancellation, resource registration, cleanup ordering, or bounded cleanup context. RunScope owns resources created during one program invocation. Close cancels the run context first, then invokes active cleanup callbacks in reverse registration order exactly once.

func NewRunScope(parent context.Context) (context.Context, *RunScope)

func RunScopeFromContext(ctx context.Context) (*RunScope, bool)

func (s *RunScope) Close(ctx context.Context) error

func (s *RunScope) Register(cleanup RunCleanupFunc) (release func(), err error)

type ScopeInheritFunc ¶ added in v0.49.0

type ScopeInheritFunc func(parentMeta, childMeta map[string]any) error

ScopeInheritFunc copies extension-owned declarations from a parent compilation scope into a child scope before the child's directives run. The parent metadata is read-only; the callback should copy values it keeps.

type SelfTestFeature ¶ added in v0.23.0

type SelfTestFeature struct {
	Name  string
	DSL   string
	Files map[string]string
	// SyntaxOnly marks fixtures that must be compiled but never executed by
	// the ordinary self-test path. Fixtures opt in with `# @syntax-only`.
	SyntaxOnly         bool
	Skip               string
	Source             string
	ExpectCompileError string
}

type SelfTestSection ¶ added in v0.23.0

type SelfTestSection struct {
	Name     string
	Features []SelfTestFeature
}

type ShutdownFunc ¶ added in v0.23.0

type ShutdownFunc func(context.Context) error

ShutdownFunc releases a resource explicitly owned by a bundle. Implementations must honor ctx so host shutdown remains bounded.

type SourceBlock ¶ added in v0.52.0

type SourceBlock struct {
	Kind       string
	Span       SourceSpan
	HeaderSpan SourceSpan
	BodySpan   SourceSpan
}

SourceBlock describes a directive-owned block in original source coordinates.

type SourceDeclaration ¶ added in v0.52.0

type SourceDeclaration struct {
	Kind        string
	Name        string
	KeywordSpan SourceSpan
	NameSpan    SourceSpan
	Span        SourceSpan
}

SourceDeclaration describes a named declaration parsed by a Flow directive.

type SourceImport ¶ added in v0.36.0

type SourceImport struct {
	Namespace     string
	Position      Position
	Span          SourceSpan
	TargetSpan    SourceSpan
	NamespaceSpan SourceSpan
	Source        *PreparedSource
}

SourceImport is a parsed source module, not a map of declarations merged into its caller. Its declarations and extension contributions stay file-local.

func SourceImports(out map[string]any) []SourceImport

type SourceIndex ¶ added in v0.52.0

type SourceIndex struct {
	Declarations []SourceDeclaration
	References   []SourceReference
	Blocks       []SourceBlock
	Imports      []SourceImport
	Tokens       []SourceToken
}

SourceIndex is the single Flow-owned, source-coordinate view used by editor tooling. Directive handlers contribute declarations, references, blocks and import edges; lexical references and tokens come from the compiler lexer.

func BuildSourceIndex(source string, meta map[string]any) SourceIndex

func IndexSource(ctx context.Context, dt *DirectiveTable, source, name string, opts ...CompileOption) (SourceIndex, error)

func IndexSourceWithMetadata(ctx context.Context, dt *DirectiveTable, source, name string, opts ...CompileOption) (SourceIndex, map[string]any, error)

type SourceLine ¶ added in v0.36.0

type SourceLine struct {
	Origins []Position
}

SourceLine identifies a rendered source line through its embedding ancestry. Origins are ordered outermost to innermost. A source-sensitive extension can therefore distinguish an included file's lines from the caller's line numbers and still apply an enclosing policy at the embedding site.

func SourceLinesFromMeta(meta map[string]any) []SourceLine

type SourceLoader ¶ added in v0.23.0

type SourceLoader interface {
	Load(currentFile, target string) (data []byte, resolvedPath string, err error)
}

SourceLoader resolves a directive-referenced source fragment such as the target of @include. CurrentFile is the path of the file that issued the reference; Target is the raw path from the directive.

The returned resolvedPath is used for cycle detection and error reporting. Its only requirement is stability for the same file across calls within one preprocess run.

type SourceMap ¶ added in v0.36.0

type SourceMap map[string]string

SourceMap is an immutable-during-use snapshot of source files keyed by their cleaned absolute paths. It implements SourceLoader without reading from the filesystem. Callers must not mutate the map while any Load call is in progress.

func (sources SourceMap) Load(currentFile, target string) (data []byte, resolvedPath string, err error)

type SourceReference ¶ added in v0.52.0

type SourceReference struct {
	Kind         string
	Name         string
	Value        string
	Modifier     string
	Span         SourceSpan
	NameSpan     SourceSpan
	ModifierSpan SourceSpan
	HasName      bool
	Valid        bool
}

SourceReference describes a parsed or lexical reference in Flow source. Modifier is set for schema modifier references; Value preserves malformed values so editor diagnostics can point at the same text the compiler parsed.

type SourceSpan ¶ added in v0.52.0

type SourceSpan struct {
	Start int
	End   int
}

SourceSpan is a half-open byte range in the original source file.

type SourceSpec ¶ added in v0.23.0

type SourceSpec struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Tags        []string    `json:"tags,omitempty"`
	ReqFields   []FieldSpec `json:"req_fields,omitempty"`
}

SourceSpec describes a stream source (fs.walk, cov.items, ...). A source has a typed request but no typed item — the item type is a per-item element, not a whole response.

type SourceToken ¶ added in v0.52.0

type SourceToken struct {
	Type TokenType
	Text string
	Span SourceSpan
	// InsideProjection marks tokens within a plain projection primary.
	InsideProjection bool
}

SourceToken is a token emitted by Flow's lexer, with its original byte span.

type SymbolNamespace ¶ added in v0.25.0

type SymbolNamespace struct {
	Name    string
	Symbols map[string]any
}

SymbolNamespace groups compile-time symbolic values that .nflow programs reference as `<namespace>.<name>`. Bundles register namespaces from init so that programs in any repo use them without local declarations. Resolved values bind during build; unresolved bare values remain ordinary literals in data positions, while expression validity depends on the expression's env.

func Namespaces() []SymbolNamespace

type Token ¶

type Token struct {
	Type         TokenType
	Lit          string
	Line         int
	Offset       int
	EndOffset    int
	Unterminated bool
}

type TokenPrimary ¶ added in v0.23.0

type TokenPrimary interface {
	PrimaryExtension
	TokenType() TokenType
}

TokenPrimary is the token-dispatch contract.

type TokenType ¶

type TokenType uint8

const (
	TokEOF TokenType = iota
	TokIdent
	TokString
	TokNumber
	TokArrow
	TokPipe
	TokAmpersand
	TokOrOr
	TokLParen
	TokRParen
	TokLBrace
	TokRBrace
	TokColon
	TokEquals
	TokComma
	TokQuestion
	TokHash
	TokTilde
	TokAtBrace
	TokAtPrompt
)

func (t TokenType) String() string

type TypeDescriptor ¶ added in v0.23.0

type TypeDescriptor struct {
	Type   reflect.Type
	Stream bool
}

type TypedSymbolValue ¶ added in v0.55.0

type TypedSymbolValue struct {
	Type  string
	Value any
}

TypedSymbolValue carries an explicitly annotated @symbols value through compile-time metadata without erasing its declared type. Value remains in its native Go representation.

type Value ¶ added in v0.8.0

type Value struct {
	Kind  ValueKind
	Str   string
	Num   float64
	Bool  bool
	Ref   string
	Map   []MapEntry
	Slice []*Value
	Typed any
}

func (v *Value) IsWholeStateRef() bool

type ValueKind ¶ added in v0.8.0

type ValueKind uint8

const (
	ValueString ValueKind = iota
	ValueBare
	ValueNumber
	ValueBool
	ValueNull
	ValueRef
	ValueMap
	ValueSlice
	ValueTyped
)