gopls

Documentation

Overview

Package gopls manages the pinned semantic-intelligence sidecar over LSP.

Index

• Constants
• func OffsetForPosition(contents []byte, position Position) (int, error)
• type Capabilities
• type Client
  • func Start(ctx context.Context, config Config) (*Client, error)
  • func (c *Client) Capabilities() Capabilities
  • func (c *Client) Close(ctx context.Context) error
  • func (c *Client) Notify(method string, params any) error
  • func (c *Client) Request(ctx context.Context, method string, params, result any) error
  • func (c *Client) Terminated() bool
• type Config
• type Installation
  • func Locate(ctx context.Context, hostExecutable, override string) (Installation, error)
• type Manager
  • func NewManager(lifecycle context.Context, config Config) (*Manager, error)
  • func (m *Manager) Capabilities() (Capabilities, error)
  • func (m *Manager) Close(ctx context.Context) error
  • func (m *Manager) Notify(method string, params any) error
  • func (m *Manager) Request(ctx context.Context, method string, params, result any, idempotent bool) error
  • func (m *Manager) Restart(ctx context.Context) error
• type Position
  • func PositionForOffset(contents []byte, offset int) (Position, error)

Constants

const SupportedVersion = "v0.21.0"

SupportedVersion is the only gopls version covered by the current LSP contract suite and release bundle.

Functions

func OffsetForPosition

func OffsetForPosition(contents []byte, position Position) (int, error)

OffsetForPosition converts an LSP UTF-16 position into a UTF-8 byte boundary.

Types

type Capabilities

type Capabilities struct {
	WorkspaceSymbol bool `json:"workspace_symbol"`
	Hover           bool `json:"hover"`
	Definition      bool `json:"definition"`
	TypeDefinition  bool `json:"type_definition"`
	References      bool `json:"references"`
	Implementation  bool `json:"implementation"`
	DocumentSymbol  bool `json:"document_symbol"`
	CallHierarchy   bool `json:"call_hierarchy"`
	Diagnostics     bool `json:"diagnostics"`
	Rename          bool `json:"rename"`
	Formatting      bool `json:"formatting"`
	CodeAction      bool `json:"code_action"`
}

Capabilities is the normalized subset of negotiated gopls features used by agentic-go. It records the initialize response rather than assuming support.

type Client

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

Client owns one long-lived stdio LSP process.

func Start

func Start(ctx context.Context, config Config) (*Client, error)

Start launches and initializes one gopls LSP session.

func (*Client) Capabilities

func (c *Client) Capabilities() Capabilities

Capabilities returns the immutable negotiated capability manifest.

func (*Client) Close

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

Close performs the LSP shutdown sequence once.

func (*Client) Notify

func (c *Client) Notify(method string, params any) error

Notify sends one JSON-RPC notification.

func (*Client) Request

func (c *Client) Request(ctx context.Context, method string, params, result any) error

Request sends one cancellable JSON-RPC request.

func (*Client) Terminated

func (c *Client) Terminated() bool

Terminated reports whether the sidecar session can no longer serve requests.

type Config

type Config struct {
	Command           string
	Workspace         string
	ClientVersion     string
	Args              []string
	MaxFrame          int
	InitializeTimeout time.Duration
}

Config describes one managed gopls process.

type Installation

type Installation struct {
	Path    string `json:"path"`
	Version string `json:"version"`
	Bundled bool   `json:"bundled"`
}

Installation describes the effective semantic sidecar.

func Locate

func Locate(ctx context.Context, hostExecutable, override string) (Installation, error)

Locate resolves and probes the pinned companion. An explicit override is authoritative; otherwise the sibling release binary wins over PATH.

type Manager

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

Manager owns the replaceable gopls session for one workspace. It retries at most one idempotent read after a terminal sidecar failure. Mutation is never replayed because the server may have applied an edit before disconnecting.

func NewManager

func NewManager(lifecycle context.Context, config Config) (*Manager, error)

NewManager starts the initial long-lived sidecar session.

func (*Manager) Capabilities

func (m *Manager) Capabilities() (Capabilities, error)

Capabilities returns the currently negotiated sidecar capabilities.

func (*Manager) Close

func (m *Manager) Close(ctx context.Context) error

Close shuts down the current session and prevents replacement.

func (*Manager) Notify

func (m *Manager) Notify(method string, params any) error

Notify sends an event to the current session without replay.

func (*Manager) Request

func (m *Manager) Request(ctx context.Context, method string, params, result any, idempotent bool) error

Request delegates one LSP operation. A terminal failure may be retried once only when the caller marks the operation idempotent.

func (*Manager) Restart

func (m *Manager) Restart(ctx context.Context) error

Restart replaces the session after configuration or repository identity changes. It never replays an operation across the boundary.

type Position

type Position struct {
	Line      int `json:"line"`
	Character int `json:"character"`
}

Position is a zero-based LSP position whose Character is measured in UTF-16 code units, not bytes or Unicode code points.

func PositionForOffset

func PositionForOffset(contents []byte, offset int) (Position, error)

PositionForOffset converts a UTF-8 byte boundary into an LSP position.