lsp

Documentation

Overview

Package lsp is the Aontu Language Server library. It is deliberately split into two layers:

• the analysis library (this file): Diagnostics turns Aontu source text into LSP diagnostics, and Handler implements the transport-agnostic LSP message dispatch (document sync -> publishDiagnostics). Neither touches stdin/stdout, so both are unit-testable and embeddable in any host.
• the server (../cmd/aontu-lsp): a thin stdio JSON-RPC loop that frames bytes and feeds decoded messages to a Handler.

The TypeScript port mirrors this split in ts/src/lsp.ts (library) and ts/src/lsp-server.ts (server).

Index

• Constants
• type CompletionItem
  • func Completions() []CompletionItem
• type Diagnostic
  • func Diagnostics(src string) []Diagnostic
  • func DiagnosticsTrust(src string, vars map[string]aontu.Val, trust *aontu.TrustOptions) []Diagnostic
  • func DiagnosticsVars(src string, vars map[string]aontu.Val) []Diagnostic
• type Handler
  • func NewHandler() *Handler
  • func (h *Handler) Doc(uri string) (string, bool)
  • func (h *Handler) ExitCode() int
  • func (h *Handler) Handle(m Message) []Out
  • func (h *Handler) ShouldExit() bool
• type HoverResult
  • func Hover(src string, line, character int, provenance bool) *HoverResult
  • func HoverTrust(src string, line, character int, provenance bool, trust *aontu.TrustOptions) *HoverResult
• type MarkupContent
• type Message
• type Out
• type Position
• type Range
• type RespError

Constants

const (
	SeverityError       = 1
	SeverityWarning     = 2
	SeverityInformation = 3
	SeverityHint        = 4
)

Severity values (a subset of the LSP DiagnosticSeverity enum).

const (
	CompletionFunction = 3
	CompletionKeyword  = 14
)

LSP CompletionItemKind subset.

const Version = aontu.VERSION

Version is reported to the client in the initialize response. It is the ENGINE's version, not a number of the server's own: a separately maintained one drifts, and had -- the server answered 0.1.0 against a module at 0.1.10, so a client could not tell which engine it was talking to (status-2026-08-21.md section 10).

Types

type CompletionItem

type CompletionItem struct {
	Label  string `json:"label"`
	Kind   int    `json:"kind,omitempty"`
	Detail string `json:"detail,omitempty"`
}

CompletionItem is a single LSP completion suggestion.

func Completions

func Completions() []CompletionItem

Completions returns context-free suggestions: the built-in functions, scalar-kind keywords and literals. Clients filter by the typed prefix.

type Diagnostic

type Diagnostic struct {
	Range    Range  `json:"range"`
	Severity int    `json:"severity"`
	Code     string `json:"code,omitempty"`
	Source   string `json:"source"`
	Message  string `json:"message"`
	// LSP DiagnosticTag values; 1 is Unnecessary, 2 is Deprecated —
	// the native tag editors strike through (G3 phase 4).
	Tags []int `json:"tags,omitempty"`
}

Diagnostic is a single LSP diagnostic.

func Diagnostics

func Diagnostics(src string) []Diagnostic

Diagnostics analyses Aontu source and returns LSP diagnostics for every problem found. A valid document — including a non-concrete schema such as `a:string` — yields an empty (non-nil) slice. Variables, if any, are resolved from vars (may be nil).

func DiagnosticsTrust

func DiagnosticsTrust(src string, vars map[string]aontu.Val, trust *aontu.TrustOptions) []Diagnostic

DiagnosticsTrust is DiagnosticsVars under a trust profile (G5, docs/trust.md). The LSP is the highest-exposure surface — merely OPENING a hostile .aon file in an editor performs its reads — so the Handler confines evaluation to the workspace root and threads the profile through here. Nil means today's unconfined behaviour, which single-file sessions rely on.

func DiagnosticsVars

func DiagnosticsVars(src string, vars map[string]aontu.Val) []Diagnostic

DiagnosticsVars is Diagnostics with $name variables resolved from vars.

type Handler

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

Handler implements the Aontu LSP message flow without any transport: it consumes decoded Messages and returns the Outs to send back. It tracks open document text and recomputes diagnostics on open/change/close. A single Handler is not safe for concurrent use; drive it from one goroutine (as the stdio server does).

func NewHandler

func NewHandler() *Handler

NewHandler returns a ready Handler with no open documents.

func (*Handler) Doc

func (h *Handler) Doc(uri string) (string, bool)

Doc returns the current text of an open document and whether it is open.

func (*Handler) ExitCode

func (h *Handler) ExitCode() int

ExitCode is the process exit code per the LSP spec: 0 if `shutdown` preceded `exit`, otherwise 1.

func (*Handler) Handle

func (h *Handler) Handle(m Message) []Out

Handle processes one incoming message and returns zero or more messages to send. Notifications produce only notifications (e.g. publishDiagnostics); requests produce exactly one response.

func (*Handler) ShouldExit

func (h *Handler) ShouldExit() bool

ShouldExit reports whether an `exit` notification has been received and the server loop should stop.

type HoverResult

type HoverResult struct {
	Contents MarkupContent `json:"contents"`
	Range    *Range        `json:"range,omitempty"`
}

HoverResult is the LSP hover response.

func Hover

func Hover(src string, line, character int, provenance bool) *HoverResult

Hover resolves the value at a cursor position and describes it, or returns nil when the position is not over a concrete value. Because it reads the *unified* tree, a value shows its resolved canon and kind.

func HoverTrust

func HoverTrust(
	src string, line, character int, provenance bool,
	trust *aontu.TrustOptions,
) *HoverResult

HoverTrust is Hover under a trust profile (G5, docs/trust.md), following the DiagnosticsTrust precedent above.

HOVER RUNS UNDER THE SAME CAPABILITY AS DIAGNOSTICS. It used to evaluate through a bare engine -- the full system resolver -- BESIDE confined diagnostics in the same server, so a workspace-confined session still resolved an escaping include the moment a cursor rested on it (use-cases/REVIEW.md finding G). One document, two postures, is not a confinement.

type MarkupContent

type MarkupContent struct {
	Kind  string `json:"kind"` // "markdown" | "plaintext"
	Value string `json:"value"`
}

MarkupContent is LSP markdown/plaintext content.

type Message

type Message struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitempty"`
	Method  string          `json:"method,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Message is an incoming JSON-RPC message (request or notification). ID is kept raw because JSON-RPC ids may be either a number or a string; notifications omit it.

type Out

type Out struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitempty"`
	Method  string          `json:"method,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *RespError      `json:"error,omitempty"`
}

Out is an outgoing JSON-RPC message. Result uses json.RawMessage so a success response can carry an explicit `null` (omitempty drops only a genuinely absent result, e.g. on notifications and error responses).

type Position

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

Position is a zero-based line / UTF-16 character offset, as defined by the LSP specification.

type Range

type Range struct {
	Start Position `json:"start"`
	End   Position `json:"end"`
}

Range is an inclusive-start, exclusive-end span of source text.

type RespError

type RespError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

RespError is a JSON-RPC error object.