engine

type Answer ¶

type Answer[T any] struct {
	// Language is the language of the engine that published the answer. It is
	// empty for an answer that a service merged from the answers of several
	// languages.
	Language source.Language

	Items      []T
	Provenance trust.Provenance
	Status     trust.Status

	// Skipped is [Result.Skipped] of the engine that answered. Services use it
	// to leave the answer out of a merge across languages. Callers read
	// Provenance.
	Skipped bool
}

Answer is a published result: the items an engine returned and the evidence behind them. Services build an Answer with Publish. Engines return a Result and never build an Answer.

Empty Items do not prove absence. trust.Status.Answered reports whether an engine ran, and trust.Provenance.SupportsNegativeClaim reports whether an empty list proves that none exist.

func Publish[T any](r Result[T], e Engine, role Role, want trust.Fidelity) Answer[T]

func Refused[T any](reason string) Answer[T]

func Unsupported[T any](reason string) Answer[T]

type Available ¶

type Available interface {
	Available(ctx context.Context) error
}

Available is implemented by an engine that depends on something outside the process, such as a language server binary. The catalogue does not select an engine whose Available returns an error, and Catalog.Capabilities reports the error. An engine that does not implement Available is always available.

type Bindings ¶

type Bindings uint8

Bindings are the bindings that an answer contains beside the declarations that a file offers to the rest of a program. The zero value contains none of them.

const (
	// BindImports contains what a file brings into scope.
	BindImports Bindings = 1 << iota
	// BindParameters contains the parameters and the type parameters of each
	// signature.
	BindParameters
	// BindLocals contains the declarations inside the body of a callable or
	// the value of a binding, which [sema.Locals] reports.
	BindLocals
	// BindLabels contains the labels of statements.
	BindLabels

	// BindAll contains every binding.
	BindAll = BindImports | BindParameters | BindLocals | BindLabels
)

func (b Bindings) Keeps(kind sema.Kind, local bool) bool

type Capability ¶

type Capability struct {
	Language source.Language
	Engine   string
	// Unavailable is the reason the engine cannot run, or empty.
	Unavailable string
	Role        Role
	Fidelity    trust.Fidelity
	Cost        Cost
	// Available reports whether the engine can run now.
	Available bool
}

Capability is one role that one engine serves for one language.

type Catalog ¶

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

Catalog is the set of registered engines. Add is not safe for concurrent use. Build the catalog before serving requests, after which every other method is safe for concurrent use.

func NewCatalog() *Catalog

func (c *Catalog) Add(e Engine) error

func (c *Catalog) Capabilities(ctx context.Context) []Capability

func (c *Catalog) Close(ctx context.Context) error

func (c *Catalog) For(ctx context.Context, lang source.Language, role Role) []Engine

type Checker ¶

type Checker interface {
	Check(ctx context.Context, files map[source.Path][]byte) (Result[edit.Finding], error)
}

Checker reports the findings for content that is not on disk. The write path calls it on the projected content of a change before it writes, and a dry run calls it without writing.

A Checker judges content in memory. A Verifier judges the workspace on disk. An engine can implement either port without the other.

type Closer ¶

type Closer interface {
	Close(ctx context.Context) error
}

Closer is implemented by an engine that keeps a subprocess or a connection open across calls. Catalog.Close closes it.

type Cost ¶

type Cost uint8

Cost is what producing an answer takes, cheapest first. It is independent of fidelity: the catalogue orders engines by fidelity and breaks ties by cost.

const (
	// CostMemory is a lookup in a structure already in memory.
	CostMemory Cost = iota
	// CostParse is a parse of each file in scope.
	CostParse
	// CostAnalyze is a type check of a package graph.
	CostAnalyze
	// CostSession is expensive once and cheap afterwards, such as a language
	// server that loads the workspace when it starts.
	CostSession
	// CostProcess is a subprocess per call.
	CostProcess
)

func (c Cost) String() string

type Declined ¶

type Declined []string

Declined lists why engines could not answer a request, one reason per engine that declined or language that failed.

func (d Declined) Reason() string

type Engine ¶

type Engine interface {
	// Name identifies the engine in a provenance and a capability report.
	Name() string

	// Language returns the language the engine serves.
	Language() source.Language

	// Fidelity returns the tier the engine declares for a role. The value is
	// fixed for the engine's lifetime. [trust.None] declines the role. The
	// catalogue calls Fidelity only for roles whose port the engine
	// implements.
	Fidelity(Role) trust.Fidelity

	// Cost returns what serving a role takes.
	Cost(Role) Cost
}

Engine is the interface every adapter implements. An adapter also implements the port of each role it serves.

type Formatter ¶

type Formatter interface {
	Format(ctx context.Context, paths []source.Path) (Result[edit.Change], error)
}

Formatter returns the changes that format paths. The changes do not touch any other path.

type Indexer ¶

type Indexer interface {
	Index(ctx context.Context, p source.Path) (Result[sema.Symbol], error)
	Granularity() Invalidation
	Affected(changed source.Path) []source.Path
}

Indexer produces the declarations an index stores for one file.

Granularity returns the widest invalidation a change can cause. It is fixed for the engine's lifetime. Affected returns the paths to index again after a change to one path.

type Invalidation ¶

type Invalidation uint8

Invalidation is the set of files that a change to one file makes stale. The values are ordered from the narrowest to the widest. The zero value is InvalidateFile.

const (
	// InvalidateFile marks only the changed file stale.
	InvalidateFile Invalidation = iota
	// InvalidateUnit marks every file of the changed file's unit stale.
	InvalidateUnit
	// InvalidateWorkspace marks every file stale, so the index rebuilds
	// everything after each change.
	InvalidateWorkspace
)

type Outliner ¶

type Outliner interface {
	Outline(ctx context.Context, req Request) (Result[sema.Symbol], error)
}

Outliner lists the declarations in a scope.

type Planner ¶

type Planner interface {
	Plan(
		ctx context.Context,
		req Request,
		op edit.Operation,
		target edit.Target,
		args edit.Args,
	) (Result[edit.Change], error)
}

Planner computes the changes an operation makes. It does not write them. The write path seals, checks and writes the changes, so atomicity does not depend on the engine.

type Query ¶

type Query struct {
	// Text matches declaration names by fuzzy match and documentation by
	// content.
	Text string

	// Kind restricts matches to one kind. KindUnknown matches every kind.
	Kind sema.Kind

	// Private includes declarations that are not visible outside their
	// unit.
	Private bool

	// Include selects the bindings that the search returns beside the
	// declarations that a file offers to the rest of a program. The engine
	// applies it before Limit.
	Include Bindings

	// Limit caps the number of items. Zero selects the engine's default.
	Limit int
}

Query is a search for declarations.

type Relator ¶

type Relator interface {
	Relate(ctx context.Context, req Request, of sema.ID, kind sema.RelationKind) (Result[sema.Relation], error)
}

Relator returns the relations of one kind from a declaration. The engine returns them in the direction that kind names, whichever direction it stores, and may stop at the Request.Limit of the caller. Request.Declared is the span at which the caller found the declaration.

type Request ¶

type Request struct {
	// Scope is a file or a directory, relative to the workspace root.
	Scope source.Path

	// Language restricts the request to one language. Empty selects the
	// languages that [Languages] returns for Scope.
	Language source.Language

	// Declared is the span of the declaration that [Relator.Relate] starts
	// from, as the outline of the caller reports it, or the zero span. An
	// engine whose own declarations do not match the ID can find the
	// declaration at this span.
	Declared source.Span

	// Limit is the number of relations that the caller keeps from
	// [Relator.Relate], and zero keeps every relation. An engine may return
	// only the first Limit relations by the path and offset of their sites. It
	// then adds a [trust.CaveatTruncated] caveat that counts the relations it
	// found.
	Limit int

	// Preferred is the lowest tier the caller wants. An answer below it is
	// published as [trust.Degraded], not refused.
	Preferred trust.Fidelity

	// Tests includes the files the language treats as tests. The language
	// module defines which paths those are.
	Tests bool
}

Request is the scope of one question. Limit and Declared apply to Relator.Relate alone.

type Resolver ¶

type Resolver interface {
	Resolve(ctx context.Context, req Request, at source.Position) (Result[sema.Symbol], error)
}

Resolver returns the declarations that the name at a position denotes. More than one item means the name is ambiguous.

The position can contain only a line and a column. The engine computes the offset from the file, so Resolve is the one port where source.Position.Offset is not authoritative on input.

type Result ¶

type Result[T any] struct {
	Items []T

	// Caveats are limits on this answer, such as files the engine did not
	// read.
	Caveats []trust.Caveat

	// Completeness is how much of the requested scope the engine examined.
	Completeness trust.Completeness

	// Lowered is a tier below the engine's declared one, for an answer worth
	// less than usual, such as a type check of code that does not compile.
	// Publish uses the lower of the two. The zero value keeps the declared
	// tier.
	Lowered trust.Fidelity

	// Skipped reports that the scope contains no file of the engine's
	// language. Services leave skipped answers out of the evidence they merge
	// across languages. An engine that read files without a match returns an
	// empty result with Skipped false. An engine that cannot find what the
	// request names returns ErrDecline.
	Skipped bool
}

Result is the return value of every engine port. It has no field for the engine's name or tier, and Lowered can only lower the tier the engine declares, so an engine cannot overstate its evidence. Services turn a Result into an Answer with Publish.

type Role ¶

type Role uint8

Role is a question an engine can answer. Each role has its own port interface, and engines declare a fidelity and a cost per role. The zero value is RoleUnset.

const (
	// RoleUnset is no role. It is never valid on a request.
	RoleUnset Role = iota
	// RoleOutline lists the declarations in a scope. See Outliner.
	RoleOutline
	// RoleSearch finds declarations by name. See Searcher.
	RoleSearch
	// RoleResolve finds the declaration a name denotes. See Resolver.
	RoleResolve
	// RoleRelate finds the edges of a declaration. See Relator.
	RoleRelate
	// RolePlan computes the edits of an operation. See Planner.
	RolePlan
	// RoleFormat computes formatting edits. See Formatter.
	RoleFormat
	// RoleCheck reports problems in content that is not on disk. See
	// Checker.
	RoleCheck
	// RoleVerify reports problems in a scope on disk. See Verifier.
	RoleVerify
	// RoleIndex produces the facts an index stores. See Indexer.
	RoleIndex
)

func Roles() []Role

func (r Role) String() string

type Router ¶

type Router interface {
	// LanguageOf returns the language that claims p by its extension.
	LanguageOf(p source.Path) (source.Language, bool)

	// Languages returns every registered language, in a fixed order.
	Languages() []source.Language
}

Router maps paths to languages. The language registry implements it.

type Searcher ¶

type Searcher interface {
	Search(ctx context.Context, req Request, q Query) (Result[sema.Symbol], error)
}

Searcher finds the declarations in a scope that match a query.

type Verifier ¶

type Verifier interface {
	Verify(ctx context.Context, req Request, suites []string) (Result[edit.Finding], error)
}

Verifier reports the findings of the language's toolchain for a scope on disk. Suites names the checks to run in the language's own terms, such as linters or test runners. An empty list runs the language's default. An engine declines a request that names a suite it does not run, with the error of Unrun.

type Waited ¶

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

Waited sums the time that the engines of one call wait for a process outside techne, such as the reply of a language server. Waits that overlap each add their whole time, so the sum can exceed the time of the call. Waited is safe for concurrent use.

func Timing(ctx context.Context) (context.Context, *Waited)

func (w *Waited) Total() time.Duration