gointel

Documentation

Overview

Package gointel is the agent's in-process Go code intelligence: a warm, type-checked view of the Go module under the workspace root, exposed as read-only tools (go_describe, go_definition, go_references, go_implementations, go_symbols, go_diagnostics). Queries resolve against an immutable per-module Snapshot.

Index

• Constants
• Variables
• func DefaultVetPasses() []string
• func NewTools(ix Index) taskengine.ToolsRepo
• func VetPasses() []string
• type Config
• type DefinitionResult
• type DescribeResult
• type Diagnostic
• type DiagnosticsResult
• type ImplEntry
• type ImplementationsResult
• type Index
  • func NewIndex(cfg Config) Index
• type Member
• type RefFile
• type RefLine
• type ReferencesResult
• type Request
• type Snapshot
  • func (s *Snapshot) Packages() []string
• type Symbol
• type SymbolsResult
• type ToolchainView
  • func (v ToolchainView) String() string

Constants

const (
	// ScopeChanged reports on the packages whose files this index has observed change — via Invalidate or the mtime sweep — since the process started.
	ScopeChanged = "changed"
	// ScopePackage reports on one package, named by import path, package name, or a workspace-relative file.
	ScopePackage = "package"
	// ScopeAll reports on every package of the module.
	ScopeAll = "all"
)

Diagnostic scopes.

const (
	ToolDescribe        = "go_describe"
	ToolDefinition      = "go_definition"
	ToolReferences      = "go_references"
	ToolImplementations = "go_implementations"
	ToolSymbols         = "go_symbols"
	ToolDiagnostics     = "go_diagnostics"
)

Tool names the gointel provider exposes; each is a pure read of an in-memory type-checked snapshot at allow tier.

const ToolsProviderName = "native-go"

ToolsProviderName is the tools-provider key this package registers under; the native- prefix is a namespace, not a gate: it keeps a declared MCP source from minting the same key, while an allowlist addresses the toolset by that exact name ("*" admits it, "!native-go" removes it). Policy addresses it as `tools_policies.native-go`; every tool it exposes is a pure read at allow tier.

Variables

var (
	// ErrNoModule means no go.mod was found at or above the query directory, within the allowed directory.
	ErrNoModule = errors.New("gointel: no Go module")
	// ErrOutsideAllowedDir means the module root that owns the query directory lies outside the allowed directory.
	ErrOutsideAllowedDir = errors.New("gointel: module root outside allowed directory")
	// ErrNoGoToolchain means the `go` binary is not on PATH.
	ErrNoGoToolchain = errors.New("gointel: no go toolchain")
	// ErrLoad means the module could not be loaded at all (driver failure).
	ErrLoad = errors.New("gointel: module load failed")
	// ErrNotFound means a named symbol resolved to nothing in this module.
	ErrNotFound = errors.New("gointel: symbol not found")
	// ErrAmbiguous means a name matched more than one declaration; the error text lists the qualified candidates.
	ErrAmbiguous = errors.New("gointel: ambiguous symbol")
	// ErrShutdown means the index has been shut down and answers nothing further, rather than silently rebuilding a snapshot no reaper will drop.
	ErrShutdown = errors.New("gointel: index shut down")
)

Sentinel errors, for errors.Is by callers that need to branch.

Functions

func DefaultVetPasses

func DefaultVetPasses() []string

DefaultVetPasses returns the names of the passes a diagnostics call runs when none are requested.

func NewTools

func NewTools(ix Index) taskengine.ToolsRepo

NewTools returns the gointel ToolsRepo; register it under ToolsProviderName in the engine's local tools map.

func VetPasses

func VetPasses() []string

VetPasses returns the names of every curated analysis pass, defaults first.

Types

type Config

type Config struct {
	// AllowedDir is the workspace root that every query directory and module root must lie within.
	AllowedDir string
	// CwdResolver supplies the workspace root per call context when AllowedDir is empty.
	CwdResolver func(context.Context) string
	// MaxRoots bounds how many module-root snapshots are cached (default 2).
	MaxRoots int
	// IdleTimeout drops a snapshot untouched for this long (default 15m; <=0 disables reaping).
	IdleTimeout time.Duration
}

Config configures an Index; zero values fall back to the documented defaults.

type DefinitionResult

type DefinitionResult struct {
	Symbol    string `json:"symbol"`
	Kind      string `json:"kind"`
	Location  string `json:"location"`
	Line      string `json:"line,omitempty"`
	Module    string `json:"module,omitempty"`
	Toolchain string `json:"toolchain"`
}

DefinitionResult is where a symbol is declared.

type DescribeResult

type DescribeResult struct {
	Symbol     string   `json:"symbol"`
	Kind       string   `json:"kind"`
	Type       string   `json:"type,omitempty"`
	Signature  string   `json:"signature,omitempty"`
	Doc        string   `json:"doc,omitempty"`
	Location   string   `json:"location"`
	Underlying string   `json:"underlying,omitempty"`
	Fields     []Member `json:"fields,omitempty"`
	Methods    []Member `json:"methods,omitempty"`
	Note       string   `json:"note,omitempty"`
	Toolchain  string   `json:"toolchain"`
}

DescribeResult is hover-grade truth about a symbol.

type Diagnostic

type Diagnostic struct {
	Location string `json:"location"`
	// Severity is "type-error" (the load's own parse/type errors) or "vet" (a curated analysis pass).
	Severity string `json:"severity"`
	// Category is the analyzer name, or "type" for a load error.
	Category string `json:"category"`
	Message  string `json:"message"`
	Line     string `json:"line,omitempty"`
}

Diagnostic is one finding.

type DiagnosticsResult

type DiagnosticsResult struct {
	Scope string `json:"scope"`
	// Passes names the analysis passes that actually ran, so a clean result cannot be mistaken for "everything was checked".
	Passes      []string     `json:"passes"`
	Packages    []string     `json:"packages"`
	TypeErrors  int          `json:"type_errors"`
	VetFindings int          `json:"vet_findings"`
	Total       int          `json:"total"`
	Shown       int          `json:"shown"`
	Diagnostics []Diagnostic `json:"diagnostics"`
	Note        string       `json:"note,omitempty"`
	// Toolchain names the build context these findings were produced under.
	Toolchain string `json:"toolchain"`
}

DiagnosticsResult is a scoped diagnostics sweep.

type ImplEntry

type ImplEntry struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	Receiver string `json:"receiver,omitempty"`
	Location string `json:"location"`
}

ImplEntry is one end of an implements relation.

type ImplementationsResult

type ImplementationsResult struct {
	Symbol string `json:"symbol"`
	Kind   string `json:"kind"`
	// Implementers is populated when Symbol is an interface.
	Implementers []ImplEntry `json:"implementers,omitempty"`
	// Interfaces is populated when Symbol is a concrete type: the module interfaces it satisfies.
	Interfaces []ImplEntry `json:"interfaces,omitempty"`
	Note       string      `json:"note,omitempty"`
	Toolchain  string      `json:"toolchain"`
}

ImplementationsResult answers in both directions.

type Index

type Index interface {
	// Describe returns kind, type, signature, doc and — for named types — fields and methods.
	Describe(ctx context.Context, req Request) (*DescribeResult, error)
	// Definition returns the declaration site and the declaring source line.
	Definition(ctx context.Context, req Request) (*DefinitionResult, error)
	// References returns uses of the symbol across this module, grouped by file.
	References(ctx context.Context, req Request) (*ReferencesResult, error)
	// Implementations answers in both directions: implementers of an interface, or the module interfaces a concrete type satisfies.
	Implementations(ctx context.Context, req Request) (*ImplementationsResult, error)
	// Symbols outlines a package or a file.
	Symbols(ctx context.Context, req Request) (*SymbolsResult, error)
	// Diagnostics returns type/parse errors plus a curated vet pass set.
	Diagnostics(ctx context.Context, req Request) (*DiagnosticsResult, error)

	// Invalidate marks the snapshots owning these paths dirty so the next query rebuilds; it never blocks or rebuilds inline.
	Invalidate(paths ...string)

	// Shutdown drops every snapshot and stops the reaper, joining its goroutine.
	Shutdown()
}

Index owns the per-module-root snapshot cache, answers every query, and is safe for concurrent use.

func NewIndex

func NewIndex(cfg Config) Index

NewIndex builds an Index and starts its idle reaper.

type Member

type Member struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	Type     string `json:"type"`
	Doc      string `json:"doc,omitempty"`
	Location string `json:"location,omitempty"`
}

Member is one field or method of a named type.

type RefFile

type RefFile struct {
	File  string    `json:"file"`
	Count int       `json:"count"`
	Lines []RefLine `json:"lines"`
}

RefFile groups locations by the file they occur in; Count is the number of distinct lines.

type RefLine

type RefLine struct {
	Line int    `json:"line"`
	Text string `json:"text,omitempty"`
	Uses int    `json:"uses,omitempty"`
}

RefLine is one location that uses a symbol; Uses is set only when the line mentions it more than once.

type ReferencesResult

type ReferencesResult struct {
	Symbol     string    `json:"symbol"`
	Definition string    `json:"definition"`
	Total      int       `json:"total"`
	Uses       int       `json:"uses"`
	Shown      int       `json:"shown"`
	Files      []RefFile `json:"files"`
	Note       string    `json:"note,omitempty"`
	Toolchain  string    `json:"toolchain"`
}

ReferencesResult is every use of a symbol in this module; Total counts distinct file:line locations and Uses counts raw identifier occurrences.

type Request

type Request struct {
	Dir    string
	Symbol string
	Target string
	Scope  string
	Passes []string
	Max    int
}

Request is the per-query argument bundle; each field is meaningful only to the queries that use it.

type Snapshot

type Snapshot struct {
	// Root is the absolute module root.
	Root string
	// Base is the workspace root Root is contained in; every path in a result is rendered relative to it.
	Base string
	// ModulePath is the module path from go.mod, when the driver reported one.
	ModulePath string
	// Fset positions every object in this snapshot.
	Fset *token.FileSet
	// Toolchain is the build context this snapshot was produced under.
	Toolchain ToolchainView
	// BuiltAt and BuildDuration are the load's own telemetry.
	BuiltAt       time.Time
	BuildDuration time.Duration
	// contains filtered or unexported fields
}

Snapshot is one module root, loaded and fully type-checked, immutable after build; queries read it without locking.

func (*Snapshot) Packages

func (s *Snapshot) Packages() []string

Packages returns the module's own package import paths, sorted.

type Symbol

type Symbol struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	Type     string `json:"type,omitempty"`
	Location string `json:"location"`
}

Symbol is one entry in an outline.

type SymbolsResult

type SymbolsResult struct {
	Target    string   `json:"target"`
	Kind      string   `json:"kind"`
	Total     int      `json:"total"`
	Shown     int      `json:"shown"`
	Symbols   []Symbol `json:"symbols"`
	Note      string   `json:"note,omitempty"`
	Toolchain string   `json:"toolchain"`
}

SymbolsResult is a package or file outline.

type ToolchainView

type ToolchainView struct {
	// GoVersion is the `go` binary that read the module graph.
	GoVersion string `json:"go_version"`
	// Checker is the Go release whose go/types produced the type information — this binary's own.
	Checker string `json:"checker"`
	GOOS    string `json:"goos"`
	GOARCH  string `json:"goarch"`
}

ToolchainView names the build context a result was produced under; treat it as a signal, not a verdict.

func (ToolchainView) String

func (v ToolchainView) String() string

String is the one-line form embedded in every result.