parser

type Parser ¶

type Parser interface {
	// Parse produces a Tree from source bytes. If oldTree is non-nil,
	// implementations SHOULD perform an incremental reparse using it as a
	// starting point. Implementations MUST enforce the size ceiling
	// (returning ErrSourceTooLarge) before doing any backend-specific
	// parsing work.
	Parse(source []byte, oldTree *Tree) (*Tree, error)

	// Close releases any resources (C memory, WASM instances) held by the
	// parser. Safe to call once; implementations should make repeat calls
	// a no-op rather than double-free.
	Close() error
}

Parser is the narrow, backend-swappable seam between arbitrary source bytes and a syntax tree (D-05b). Both the CGo tree-sitter backend (internal/parser/cgo) and any future wazero-WASM backend implement this exact shape so callers (storage, extractors) never depend on a specific backend's types.

Security contract (Security Domain V5 / threat T-01-03): implementations MUST reject source input larger than their configured ceiling (see MaxSourceBytes) by returning ErrSourceTooLarge, and MUST perform that check BEFORE handing the bytes to the underlying C or WASM parser. This bounds the pathological-input denial-of-service surface (e.g. a single multi-megabyte minified line) at the seam, before any backend-specific parsing cost is paid.

Crash-isolation contract (threat T-01-01, accepted for Phase 1): a C-level segfault inside a tree-sitter grammar's external scanner (for example Python's INDENT/DEDENT scanner) runs in-process with no memory isolation from the Go host. This is NOT a Go panic and is NOT recoverable via Go's recover() — callers and implementations MUST NOT design any crash-isolation logic around recover() for this path. The CGo backend's crash-isolation behavior under adversarial input is measured (not eliminated) by the Plan 01-07 spike; a subprocess isolation boundary remains a Phase 2+ option if that risk proves unacceptable in practice.

Resource contract: implementations allocate C or WASM-backed memory for parsers/trees. Callers MUST call Close() exactly once when done with a Parser to free those resources; Close() must be safe to call even if no Parse call was made. Callers MUST ALSO call Close() on every *Tree returned by Parse exactly once when done with it — including a superseded oldTree once an incremental reparse produces its replacement — to free the tree's own native memory, which is distinct from and not released by Parser.Close().

type Tree ¶

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

Tree is a backend-neutral syntax tree handle. Call sites never touch a backend-specific tree type directly (e.g. *tree_sitter.Tree) — every backend wraps its native tree behind this opaque type so storage and future extractors can be written against a single shape regardless of which Parser implementation produced the tree.

func NewTree(inner any, closeFn func()) *Tree

func (t *Tree) Close() error

func (t *Tree) Inner() any