driver

package
v0.0.35 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: MIT Imports: 59 Imported by: 0

Documentation

Overview

Package driver runs the compiler pipeline: load sources, parse, check, generate Go, and build with the Go toolchain.

Index

Constants

View Source 
const DelveVersion = "v1.27.2"

DelveVersion pins the optional debugger independently of compiler releases.

View Source 
const ModFile = "bork.mod"

ModFile is the file at a module's root that names the module, and the packages allowed to contain unsafe go: 

module example.com/shop
unsafe "example.com/shop/ffi"

Variables

This section is empty.

Functions

func Build 

func Build(path, out string, options ...BuildOptions) error

Build compiles the package at path into an executable at out.

func BuildDebug added in v0.0.14 

func BuildDebug(path, out string) error

BuildDebug retains generated source next to out, and disables optimization and inlining so Delve can inspect source variables and step through bork statements.

func Check 

func Check(path string) ([]*syntax.File, *check.Info, error)

Check parses and type-checks the package at path, and the packages it imports. The files start with the prelude, then the package's own.

func CheckWarnings 

func CheckWarnings(path string) ([]diag.Diagnostic, error)

CheckWarnings returns the owned warning diagnostics used by the CLI, without exposing mutable checked state. Check remains available to AST consumers.

func DebugDAP added in v0.0.14 

func DebugDAP(ctx context.Context, explicit, listen string, stdout, stderr io.Writer) error

DebugDAP delegates DAP to Delve on a loopback TCP listener. The adapter prints its actual listener address, including the selected port when listen ends in :0.

func DefaultOutput 

func DefaultOutput(path string) string

DefaultOutput is the executable name `bork build` uses when none is given: the file name without .bork, or the directory's name.

func Deps 

func Deps(path, action string, packages []string) error

Deps manages dependency manifests in the nearest bork module. Go runs in a temporary module so failed resolution cannot rewrite the user's manifests.

func DepsWithOutput 

func DepsWithOutput(path, action string, packages []string, out io.Writer) error

DepsWithOutput reports newly selected library releases with unsafe grants.

func Describe 

func Describe(position, where string) (*describe.Result, error)

Describe compiles the selected file's package, then answers compiler queries at file:line:column. where is an optional clause, with the value implicit.

func Doc added in v0.0.13 

func Doc(path string, opts DocOptions) ([]byte, error)

Doc returns a complete document only after every requested package checks.

func EditorOrganizeImports added in v0.0.12 

func EditorOrganizeImports(path, source string, diagnostics []diag.Diagnostic) (string, error)

EditorOrganizeImports sorts parsed imports and removes only imports identified as unused by the current compiler diagnostics. It never infers usage from text.

func Emit 

func Emit(path string) ([]byte, error)

Emit compiles the package at path to Go source. A program must have a main function.

func EmitTests 

func EmitTests(path string, opts TestOptions) ([]byte, error)

EmitTests is Emit for the test program (see Test).

func EnableCLICache 

func EnableCLICache()

EnableCLICache activates owned complete-result reuse for the command-line process. Library callers keep the ordinary AST pipeline unless explicitly enabled. Unsupported platforms use their ordinary compiler path.

func FindDelve added in v0.0.14 

func FindDelve(explicit string) (string, error)

FindDelve honors an explicit executable, then the pinned installation, then PATH.

func Install 

func Install(path string) error

Install builds into BORKBIN, replacing an existing executable only on success.

func LexicalSemanticTokens added in v0.0.16 

func LexicalSemanticTokens(path, source string) []check.SemanticToken

LexicalSemanticTokens classifies current source through the compiler lexer when no matching successful snapshot is available.

func Lint added in v0.0.3 

func Lint(path string) ([]diag.Diagnostic, error)

Lint checks a package and returns advisory compiler-backed diagnostics.

func Run 

func Run(path string, args []string) (int, error)

Run builds the package at path into a reusable executable and runs it with the given arguments. It returns the program's exit code.

func RunCLI added in v0.0.26 

func RunCLI(path string, args []string, options ...BuildOptions) (int, error)

RunCLI replaces the CLI process with the built program on supported Unix platforms. Temporary fallback builds and other platforms wait as Run does.

func RunScript 

func RunScript(path string, args []string) (int, error)

RunScript executes a single file with an implicit main, even without a shebang.

func RunScriptCLI added in v0.0.26 

func RunScriptCLI(path string, args []string, options ...BuildOptions) (int, error)

RunScriptCLI uses the same process replacement as bork run.

func SetupDelve added in v0.0.14 

func SetupDelve(ctx context.Context, output io.Writer) error

SetupDelve installs the pinned debugger using Go, and prints its executable path.

func SnapshotDir 

func SnapshotDir(path string) string

SnapshotDir is where the tests of the package at path keep their snapshots: a snapshots directory next to its sources.

func Sources 

func Sources(path string) ([]string, error)

Sources lists the .bork files for path: the file itself, or every .bork file directly inside a directory (one directory = one package).

func Test 

func Test(path string, stdout io.Writer, opts TestOptions) (int, error)

Test builds the package's tests in test mode and runs them, with the report going to stdout. It returns the exit code: 0 if every test passed.

func Watch 

func Watch(ctx context.Context, path string, options WatchOptions, report func(WatchResult) error) error

Watch checks once, then checks again only after a tracked input changes or a manual retrigger. Unsupported result-cache paths still compile afresh, but do not execute periodically. Untracked unsafe/foreign inputs need a retrigger.

func WorkspacePackages added in v0.0.21 

func WorkspacePackages(path string, roots []string, overlays map[string]string) ([]string, error)

WorkspacePackages inventories local packages through the compiler source reader, including new buffers. Hidden/vendor directories and nested modules are excluded unless supplied as explicit workspace roots.

Types

type BuildOptions added in v0.0.28 

type BuildOptions struct{ Fast, Rebuild bool }

BuildOptions controls validation of an executable, independently of compiler result reuse. Rebuild always wins over Fast.

type CacheCleanReport 

type CacheCleanReport struct {
	Results, Stages, Temporaries, Dependencies int
	Bytes                                      int64
}

func Clean 

func Clean(ctx context.Context, all bool) (CacheCleanReport, error)

Clean removes compiler-owned artifacts, preserving project outputs, Go's cache and permanent coordination files. Waiting for active clients is cancellable.

type DiagError 

type DiagError struct {
	Diags *diag.List
}

DiagError is returned when the bork program has compile errors.

func (*DiagError) Error 

func (e *DiagError) Error() string

type DocOptions added in v0.0.13 

type DocOptions struct{ All, HTML bool }

type EditorAnalysis 

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

EditorAnalysis is a successful checked snapshot. Its compiler graph remains private, separate from Check/Emit artifacts. Use it serially with its Session.

func (*EditorAnalysis) AllReferences added in v0.0.21 

func (a *EditorAnalysis) AllReferences() []check.SourceReference

func (*EditorAnalysis) Definition 

func (a *EditorAnalysis) Definition(pos diag.Pos) (*diag.Pos, error)

Definition resolves a token identity without evaluating facts.

func (*EditorAnalysis) Describe 

func (a *EditorAnalysis) Describe(pos diag.Pos) (*describe.Result, error)

func (*EditorAnalysis) EditorCallHierarchy added in v0.0.22 

func (a *EditorAnalysis) EditorCallHierarchy(pos diag.Pos) (*EditorNavigationItem, error)

func (*EditorAnalysis) EditorCalls added in v0.0.22 

func (a *EditorAnalysis) EditorCalls() []EditorCallEdge

func (*EditorAnalysis) EditorContextCompletions added in v0.0.4 

func (a *EditorAnalysis) EditorContextCompletions(file, src string, pos, at diag.Pos) ([]EditorCompletion, bool)

EditorContextCompletions uses compiler tokens to recover unfinished editor syntax and queries the last checked graph for its semantic candidates.

func (*EditorAnalysis) EditorExtractFunction added in v0.0.17 

func (a *EditorAnalysis) EditorExtractFunction(start, end diag.Pos) (string, error)

EditorExtractFunction creates a private helper from a complete expression. Callers must recheck the proposed source to verify contracts, lifetimes, contextual types, and return boundaries after moving the expression.

func (*EditorAnalysis) EditorImplementations added in v0.0.22 

func (a *EditorAnalysis) EditorImplementations(pos diag.Pos) []EditorNavigationItem

func (*EditorAnalysis) EditorImportSymbols added in v0.0.4 

func (a *EditorAnalysis) EditorImportSymbols(path string) []EditorCompletion

EditorImportSymbols inventories exported declarations in embedded standard packages, the current module and the already resolved library graph. It parses source without running code.

func (*EditorAnalysis) EditorInlays added in v0.0.20 

func (a *EditorAnalysis) EditorInlays(path string, options check.EditorInlayOptions) ([]check.EditorInlay, error)

func (*EditorAnalysis) EditorMatchArms added in v0.0.4 

func (a *EditorAnalysis) EditorMatchArms(pos diag.Pos) []EditorCompletion

EditorMatchArms describes patterns for the compiler-selected scrutinee type.

func (*EditorAnalysis) EditorMembers added in v0.0.4 

func (a *EditorAnalysis) EditorMembers(pos diag.Pos) []EditorCompletion

EditorMembers exposes checked fields and methods of a selected value.

func (*EditorAnalysis) EditorNamedCallable added in v0.0.4 

func (a *EditorAnalysis) EditorNamedCallable(path, name string) *check.CallableDescription

func (*EditorAnalysis) EditorNamedMembers added in v0.0.4 

func (a *EditorAnalysis) EditorNamedMembers(pos diag.Pos, name string) []EditorCompletion

EditorNamedMembers resolves a visible binding in the checked snapshot when an unfinished edit has moved the receiver away from its former source position.

func (*EditorAnalysis) EditorPackageSymbols added in v0.0.4 

func (a *EditorAnalysis) EditorPackageSymbols(path, alias string) []EditorCompletion

EditorPackageSymbols lists exports of a package already imported by the file.

func (*EditorAnalysis) EditorSymbols added in v0.0.4 

func (a *EditorAnalysis) EditorSymbols(pos diag.Pos) []EditorCompletion

EditorSymbols lists package, prelude and lexically visible local symbols.

func (*EditorAnalysis) EditorSymbolsInBuffer added in v0.0.4 

func (a *EditorAnalysis) EditorSymbolsInBuffer(path, src string, pos diag.Pos) []EditorCompletion

EditorSymbolsInBuffer maps an unfinished edit back to the checked snapshot.

func (*EditorAnalysis) EditorTypeDefinitions added in v0.0.22 

func (a *EditorAnalysis) EditorTypeDefinitions(pos diag.Pos) []EditorNavigationItem

func (*EditorAnalysis) EditorTypeFields added in v0.0.4 

func (a *EditorAnalysis) EditorTypeFields(path, head string) []EditorCompletion

EditorTypeFields resolves a literal or destructuring head using the parser and checker, including import aliases and generic substitutions.

func (*EditorAnalysis) ReferenceAt added in v0.0.21 

func (a *EditorAnalysis) ReferenceAt(pos diag.Pos) *check.SourceReference

ReferenceAt resolves a source token through the checker-owned identity index.

func (*EditorAnalysis) References added in v0.0.21 

func (a *EditorAnalysis) References(def diag.Pos) []check.SourceReference

func (*EditorAnalysis) SemanticTokens added in v0.0.16 

func (a *EditorAnalysis) SemanticTokens(path string) []check.SemanticToken

SemanticTokens returns owned classifications from this checked snapshot. The per-file index is retained for repeat requests; no facts are evaluated.

func (*EditorAnalysis) SignatureHelp added in v0.0.18 

func (a *EditorAnalysis) SignatureHelp(path, current string, at diag.Pos) *EditorSignatureHelp

func (*EditorAnalysis) Sources 

func (a *EditorAnalysis) Sources() map[string]string

Sources returns owned source text for disk packages in the checked graph.

func (*EditorAnalysis) Symbols added in v0.0.21 

func (a *EditorAnalysis) Symbols() []check.Symbol

func (*EditorAnalysis) Warnings 

func (a *EditorAnalysis) Warnings() []diag.Diagnostic

type EditorCallEdge added in v0.0.22 

type EditorCallEdge struct {
	Caller, Callee EditorNavigationItem
	Start, End     diag.Pos
	Reference      diag.Pos
}

type EditorCompletion added in v0.0.4 

type EditorCompletion struct {
	Name, Detail, Kind, Text string

	Rank       int
	ImportPath string
	// contains filtered or unexported fields
}

EditorCompletion contains compiler-owned symbol metadata, independent of LSP.

type EditorNavigationItem added in v0.0.22 

type EditorNavigationItem struct {
	Name, Kind, Detail                       string
	Start, End, SelectionStart, SelectionEnd diag.Pos
}

type EditorSignatureHelp added in v0.0.18 

type EditorSignatureHelp struct {
	*check.EditorSignature
	Documentation   string
	ActiveParameter *int
}

EditorSignatureHelp recovers the current call with compiler tokens, then uses checked identities or normal compiler lookup. It does not recheck a package.

type EditorWorkspace added in v0.0.21 

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

EditorWorkspace owns current checked snapshots of local workspace packages. Dependencies remain readable for navigation, but never editable.

func AnalyzeNavigationWorkspace added in v0.0.22 

func AnalyzeNavigationWorkspace(path string, roots []string, overlays map[string]string, sessions map[string]*Session) (*EditorWorkspace, error)

AnalyzeNavigationWorkspace includes each explicit editor root, including independent standalone directories. Empty roots contribute no packages.

func AnalyzeWorkspace added in v0.0.21 

func AnalyzeWorkspace(path string, roots []string, overlays map[string]string) (*EditorWorkspace, error)

AnalyzeWorkspace checks closed importers as well as open buffers. An invalid local package prevents edits: returning a partial reference set is unsafe.

func AnalyzeWorkspaceWithSessions added in v0.0.21 

func AnalyzeWorkspaceWithSessions(path string, roots []string, overlays map[string]string, sessions map[string]*Session) (*EditorWorkspace, error)

AnalyzeWorkspaceWithSessions retains checked snapshots for repeated workspace queries while Session validation still checks overlays, disk inputs and tools.

func (*EditorWorkspace) Analyses added in v0.0.21 

func (w *EditorWorkspace) Analyses() []*EditorAnalysis

func (*EditorWorkspace) OwnsSource added in v0.0.22 

func (w *EditorWorkspace) OwnsSource(path string) bool

OwnsSource distinguishes workspace declarations from readable dependency graphs.

func (*EditorWorkspace) References added in v0.0.21 

func (w *EditorWorkspace) References(def diag.Pos) []check.SourceReference

func (*EditorWorkspace) Rename added in v0.0.21 

func (w *EditorWorkspace) Rename(def diag.Pos, name string) ([]diag.TextEdit, error)

Rename constructs and checks edits without writing files. Rechecking every package also verifies that references still bind to the renamed declaration.

func (*EditorWorkspace) RenameWithSessions added in v0.0.21 

func (w *EditorWorkspace) RenameWithSessions(def diag.Pos, name string, sessions map[string]*Session) ([]diag.TextEdit, error)

RenameWithSessions keeps verification caches separate from current-source snapshots. Sessions still validate every dependency, buffer and Go input.

func (*EditorWorkspace) Sources added in v0.0.21 

func (w *EditorWorkspace) Sources() map[string]string

type Session 

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

Session reuses the last successful complete-program result. Check and Emit retain no compiler graph and return independent data. Analyze separately retains an editor query snapshot, used serially by the language server. Go type/export metadata, custom drivers and compile-time evaluation bypass complete-program reuse. Audited pure predicate batches have a separate bounded Session cache.

func NewSession 

func NewSession() *Session

func (*Session) Analyze 

func (s *Session) Analyze(path string, overlays map[string]string) (*EditorAnalysis, error)

Analyze checks a package using absolute-path unsaved source overlays. Returned analyses remain snapshots when later requests fail or change their overlays.

func (*Session) Check 

func (s *Session) Check(path string) ([]diag.Diagnostic, error)

Check returns owned warning diagnostics. Errors retain the one-shot compiler's diagnostic behavior; unsuccessful results are compiled again on each request.

func (*Session) Emit 

func (s *Session) Emit(path string) ([]byte, error)

Emit returns an owned copy of generated Go source. Predicate checking may reuse Session-owned audited boolean batches.

func (*Session) Stats 

func (s *Session) Stats() SessionStats

type SessionStats 

type SessionStats struct {
	Hits, Misses, Bypasses                uint64
	ProofHits, ProofMisses, ProofDeclines uint64
	Reason                                string
}

SessionStats counts requests and explains the most recent hit or miss. Proof counters count native predicate batches, separately from program hits.

type TestOptions 

type TestOptions struct {
	// JSON emits result JSON Lines, keeping program output on stderr.
	JSON bool
	// Filter selects tests by their exact declaration name.
	Filter string
	// FilterSet distinguishes an empty declaration name from no filter.
	FilterSet bool
	// Update writes the snapshots that assertSnapshot finds missing or
	// different, instead of failing.
	Update bool
	// AutoProperties property-tests the functions whose promises are
	// trusted (unsafe go, or trust in their body), calling them on
	// generated arguments. It is opt-in until effects tell which
	// functions are pure: random arguments could make others do IO.
	AutoProperties bool
	// Seed, if not 0, is the seed of every property test, instead of
	// one from its name. Cases, if not 0, is how many cases each runs.
	Seed  int64
	Cases int
	// Hermetic fails, without running it, every test that can reach the
	// network (a function doing net in Go code) with no mock in force.
	Hermetic bool
	// Parallel, if more than 1, is how many tests run at a time. Each
	// runs on goroutines of its own, and the report keeps their order.
	Parallel int
}

TestOptions are the options of bork test.

type WatchOptions 

type WatchOptions struct {
	Interval  time.Duration
	Retrigger <-chan struct{}
}

WatchOptions configures serialized content polling. Retrigger forces a fresh compilation, including inputs outside the compiler's tracked inventory.

type WatchResult 

type WatchResult struct {
	SchemaVersion int               `json:"schema_version"`
	RequestID     uint64            `json:"request_id"`
	Status        string            `json:"status"`
	Diagnostics   []diag.Diagnostic `json:"diagnostics"`
}

WatchResult is a complete diagnostic snapshot. Failed checks are recoverable; every publication owns its diagnostics. Request IDs also count obsolete attempts whose inputs changed during checking and whose results were withheld.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.