parser

type ByteRange struct {
	// Start is the inclusive starting byte offset.
	Start int
	// End is the exclusive ending byte offset.
	End int
}

type InputEdit struct {
	// StartByte is the byte offset where the edit begins.
	StartByte int
	// OldEndByte is the byte offset where the replaced region ended.
	OldEndByte int
	// NewEndByte is the byte offset where the replacement region ends.
	NewEndByte int
	// StartPoint is the point for StartByte.
	StartPoint Point
	// OldEndPoint is the point for OldEndByte.
	OldEndPoint Point
	// NewEndPoint is the point for NewEndByte.
	NewEndPoint Point
}

type Lang int

type Node struct {
	// Kind is the grammar node type (e.g. "function_declaration").
	Kind string
	// StartByte is the inclusive starting byte offset of the node.
	StartByte int
	// EndByte is the exclusive ending byte offset of the node.
	EndByte int
	// StartPoint is the row/column position of StartByte.
	StartPoint Point
	// EndPoint is the row/column position of EndByte.
	EndPoint Point
	// Named reports whether the node is a named node (vs. an anonymous token).
	Named bool
	// Missing reports whether the node is a MISSING node — a zero-width node the
	// parser inserts to recover from a syntax error (e.g. an absent closing
	// brace). A MISSING node has a normal Kind, so this flag is the only way to
	// distinguish it from a genuine token; parse-health diagnostics surface it
	// alongside ERROR-kind nodes (SPEC §10.5).
	Missing bool
	// Children are the node's direct child nodes in source order.
	Children []*Node
}

type ParserPort interface {
	// Parse parses src under lang into a fresh Tree.
	Parse(ctx context.Context, lang Lang, src []byte) (*Tree, error)
	// ParseIncremental reparses src under lang, reusing old after applying edit.
	ParseIncremental(ctx context.Context, lang Lang, src []byte, old *Tree, edit InputEdit) (*Tree, error)
	// ChangedRanges reports the byte ranges that differ between old and new.
	ChangedRanges(old, new *Tree) []ByteRange
}

type Point struct {
	// Row is the zero-based line number.
	Row int
	// Col is the zero-based byte offset within the row.
	Col int
}

type Tree struct {
	// Root is the root node of the tree.
	Root *Node
	// Source is the byte slice the tree was parsed from.
	Source []byte
	// Native is an opaque, adapter-owned engine handle; nil for engine-free
	// trees (e.g. test fakes). Consumers never inspect it.
	Native any
}