template

type Annotation int

type Choose struct {
	Param   string
	Cases   []ChooseCase // declaration order, excluding default
	Default *ChooseCase  // nil = required parameter
	Slot    Slot
	Span    diagnostics.Span // '@choose' through '@end'
}

type ChooseCase struct {
	Name string // "" for @default
	Body string // edge-trimmed verbatim; may be empty only for default
	Span diagnostics.Span
}

type FilterTree struct {
	Param      string
	Required   bool // @filter-tree!: nil tree is an error, Unscoped explicit
	Predicates []Predicate
	// Slot is SlotWhereConjunct or SlotHavingConjunct — the two
	// positions where the empty tree's TRUE rendering is one whole
	// conjunct (enforced by the scanner's anchor checks and R1
	// membership on the empty rendering).
	Slot Slot
	Span diagnostics.Span
}

type GuardAtom struct {
	Param string
	Op    string
	Value string // Go-side literal (unquoted string, number, true/false)
	Kind  ValueKind
	// RawValue is the literal as written in SQL (e.g. `'a'`, `false`),
	// preserved for `sqletch fmt`.
	RawValue string
}

type GuardedItem struct {
	Name   string
	Guards []GuardAtom
	Span   diagnostics.Span
}

type IfPresent struct {
	Guards   []GuardAtom
	Sep      Sep
	Body     string // verbatim (edge-trimmed), separator lifted
	Slot     Slot
	Span     diagnostics.Span // '@if-present' through '@endif'
	BodySpan diagnostics.Span
}

type InExpr struct {
	Param string
	Span  diagnostics.Span
}

type Item interface {
	// Raw is the full byte range this item occupies in the file
	// (constructs include their @… markers). Item ranges of a query
	// are contiguous: concatenated they reproduce the source section.
	Raw() diagnostics.Span
}

type Occurrence struct {
	Span         diagnostics.Span
	Guards       []GuardAtom // guard set of the enclosing fragment; nil in skeleton
	InChooseCase bool        // inside a @choose case body (empty guard set, R3)
	InFilterTree bool        // inside a @predicate body (constructor arg)
	InIn         bool        // the parameter of an @in(:param) list occurrence
}

type OrderBy struct {
	Param   string
	Keys    []OrderKey
	Default *ChooseCase // whole ORDER BY clause; may be empty
	Span    diagnostics.Span
}

type OrderKey struct {
	Name string
	Body string // one sort expression
	Span diagnostics.Span
}

type Param struct {
	Name        string
	Occurrences []Occurrence
	// GuardBit is set iff the param is used as a presence-guard atom;
	// -1 otherwise.
	GuardBit int
	// Optional is filled by the R9 classification (rules.CheckLexical):
	// true iff every bind appearance lies in fragments guarded by this
	// parameter — a pointer field in the generated params struct.
	Optional bool
	// Policy names the policy that wove this parameter in; empty for a
	// parameter the query author wrote. Codegen uses it to tell a value
	// the caller asked for from one the tool injected on their behalf.
	// The latter is a required argument of the generated method rather
	// than a params-struct field, so omitting it cannot compile.
	Policy string
}

type PolicyOptOut struct {
	Policy string
	Reason string
	Span   diagnostics.Span
}

type Predicate struct {
	Name   string
	Body   string   // one boolean expression
	Params []string // distinct :params in first-occurrence order
	Span   diagnostics.Span
}

type QueryFile struct {
	Path    string
	Queries []*QueryTemplate
}

type QueryTemplate struct {
	Name       string
	Annotation Annotation
	HeaderSpan diagnostics.Span
	Items      []Item
	// Params in first-appearance order (deterministic output).
	ParamOrder []string
	Params     map[string]*Param
	// GuardAtoms in bit order: GuardAtoms[i] has bit i.
	GuardAtoms []GuardAtom
	// InsertColGuards / InsertValGuards collect the guarded INSERT
	// column items and, per VALUES row, the guarded value items — the
	// R7 pairing input. Guarded items are restricted to the tail of
	// their clause (checked at scan time), so sequence equality plus
	// the maximal Describe implies positional alignment in every shape.
	InsertColGuards []GuardedItem
	InsertValGuards [][]GuardedItem
	// TypeHints holds `-- @param name: sqltype` directives: explicit
	// parameter types that override (Tier 1) or supply (Tier 2) the
	// oracle's answer. Values are raw SQL type names resolved by the
	// dialect.
	TypeHints map[string]TypeHint
	// ColumnHints holds `-- @column name: sqltype` directives: result
	// column types for dialects whose oracle cannot type expression
	// columns (SQLite decltype is NULL for any expression). Keyed by
	// the result column's output name.
	ColumnHints map[string]TypeHint
	// WhereKwEnd, TailStart, and StmtEnd are template-source offsets
	// recorded for the policy weaver (design 14 §4.2): WhereKwEnd is
	// the offset just past the statement's top-level WHERE keyword (-1
	// when absent); TailStart is where a synthesized WHERE clause would
	// go when the statement has none — the start of the first
	// GROUP BY/HAVING/ORDER BY/tail/RETURNING clause (or `@order-by`
	// construct), -1 when the statement has no such clause; StmtEnd is
	// the end of the last statement token (excluding any terminating
	// semicolon), the fallback insertion point.
	WhereKwEnd int
	TailStart  int
	StmtEnd    int
	// PolicyOptOuts are the query's `-- @policy-optout: name (reason)`
	// annotations in declaration order (a slice so diagnostics never
	// depend on map iteration order).
	PolicyOptOuts []PolicyOptOut
}

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

type Sep int

type Skeleton struct {
	Text string // verbatim bytes, params still :name
	Span diagnostics.Span
	// Synth marks text that exists in no template file (a policy-woven
	// conjunct): Span is zero-width at the insertion offset, and the
	// renderer maps the emission as synthesized text anchored there
	// instead of attributing it to the template bytes that follow.
	Synth bool
}

type Slot int

type TypeHint struct {
	SQLType string
	Span    diagnostics.Span
}

type ValueKind int