const (
    ModeNative = Mode(1 << iota)
    ModePreprocessed
    ModeAnnotated
    ModeSemantic
)

const (
    // ManifestLocation is the path of the manifest file in the driver image.
    ManifestLocation = "/opt/driver/etc/" + manifest.Filename
)

const ModeDefault = ModeSemantic

var (
    // ErrDriverFailure is returned when the driver is malfunctioning.
    ErrDriverFailure = derrors.ErrDriverFailure

    // ErrSyntax is returned when driver cannot parse the source file.
    // Can be omitted for native driver implementations.
    ErrSyntax = derrors.ErrSyntax

    // ErrTransformFailure is returned if one of the UAST transformations fails.
    ErrTransformFailure = errors.NewKind("transform failed")

    // ErrModeNotSupported is returned if a UAST transformation mode is not supported by the driver.
    ErrModeNotSupported = errors.NewKind("transform mode not supported")
)

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 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
}