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)

	// Version returns a version of the driver or the server, depending where is this interface is implemented.
	Version(ctx context.Context) (Version, error)

	// Languages returns a list of manifests for languages supported by this driver or the server.
	Languages(ctx context.Context) ([]manifest.Manifest, error)
}

type DriverModule interface {
	Module
	Driver
}

type ErrMissingDriver struct {
	Language string
}

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
}

type Version struct {
	Version string    // the version label for the driver, e.g., 'v1.2.3-tag' or 'undefined'
	Build   time.Time // the timestamp when the driver was built
}