driver

type Driver interface {
	// Parse reads the input string and constructs an AST representation of it.
	//
	// Language can be specified by providing ParseOptions. If the language is not set,
	// it will be set during the Parse call if implementation supports language detection.
	//
	// Depending on the mode, AST may be transformed to different UAST variants.
	// ErrModeNotSupported is returned for unsupported transformation modes.
	//
	// Syntax errors are indicated by returning ErrSyntax.
	// In this case a non-empty UAST may be returned, if driver supports partial parsing.
	//
	// Native driver failures are indicated by ErrDriverFailure and UAST transformation are indicated by ErrTransformFailure.
	// All other errors indicate a protocol or server failure.
	Parse(ctx context.Context, src string, opts *ParseOptions) (nodes.Node, error)
}

type DriverModule interface {
	Module
	Driver
	Manifest() (manifest.Manifest, error)
}

type ErrMulti = derrors.ErrMulti

type Mode int

type Module interface {
	Start() error
	Close() error
}

type Native interface {
	Module
	// Parse reads the input string and constructs an AST representation of it.
	// All errors are considered ErrSyntax, unless they are wrapped into ErrDriverFailure.
	Parse(ctx context.Context, src string) (nodes.Node, error)
}

type ParseOptions struct {
	Mode     Mode
	Language string
	Filename string
}

type Transforms struct {
	// Namespace for native AST nodes of this language. Only enabled in Semantic mode.
	//
	// Namespace will be set at the end of the pipeline, thus all transforms can
	// use type names without the driver namespace.
	Namespace string

	// Preprocess stage normalizes native AST for both Annotated and Semantic stages.
	//
	// It usually:
	//  * changes type key to uast.KeyType
	//  * restructures positional information
	//  * fixes any issues with native AST structure
	Preprocess []transformer.Transformer

	// PreprocessCode stage runs code-assisted transformations after the Preprocess stage.
	// It can be used to fix node tokens or positional information based on the source.
	PreprocessCode []transformer.CodeTransformer

	// Normalize stage converts a known native AST structures to a canonicalized
	// high-level AST representation (UAST). It is executed after PreprocessCode
	// and before the Annotations stage.
	Normalize []transformer.Transformer

	// Annotations stage applies UAST role annotations and is executed after
	// Semantic stage, or after PreprocessCode if Semantic is disabled.
	//
	// It also changes token key to uast.KeyToken. It should not be done in the
	// Preprocess stage, because Semantic annotations are easier on clean native AST.
	Annotations []transformer.Transformer

	// Code stage is applied directly after annotations and provides a way
	// to extract more information from source files, fix positional info, etc.
	//
	// TODO(dennwc): deprecate and examine drivers; documentation was incorrect
	//               it was described that the stage runs after Native, but it
	//               was always running after all annotation stages
	//
	// Deprecated: see PreprocessCode
	Code []transformer.CodeTransformer
}