lsp

Documentation

Overview

Package lsp bridges CalcMark's spec/impl/format layers to the Language Server Protocol. Dependencies flow inward: lsp → spec, lsp → impl, lsp → format. No package should ever import lsp.

Index

• func SemanticTokensLegend() protocol.SemanticTokensLegend
• func ToLSPPosition(pos ast.Position) protocol.Position
• func ToLSPRange(r *ast.Range) protocol.Range
• type CursorContext
  • func ClassifyCursor(region FrontmatterRegion, position protocol.Position) CursorContext
• type CursorPosition
• type DocumentRenderedParams
• type DocumentSnapshot
• type FrontmatterRegion
  • func DetectRegion(source string) (FrontmatterRegion, bool)
• type LexiconResult
• type Server
  • func NewServer() *Server
  • func (s *Server) RunStdio() error
  • func (s *Server) ServeWebSocket(conn *websocket.Conn)

Functions

func SemanticTokensLegend

func SemanticTokensLegend() protocol.SemanticTokensLegend

SemanticTokensLegend returns the legend to register during initialize.

func ToLSPPosition

func ToLSPPosition(pos ast.Position) protocol.Position

ToLSPPosition converts a CalcMark 1-indexed position to a 0-indexed LSP position.

func ToLSPRange

func ToLSPRange(r *ast.Range) protocol.Range

ToLSPRange converts a CalcMark Range to an LSP Range.

Types

type CursorContext

type CursorContext struct {
	InRegion bool
	Position CursorPosition
	Key      string // name of the key the cursor relates to ("" when unknown)
}

CursorContext is the result of classifying a cursor against a region.

func ClassifyCursor

func ClassifyCursor(region FrontmatterRegion, position protocol.Position) CursorContext

ClassifyCursor determines where the cursor at position sits relative to the region: outside, on a fence, on a key, or in a value (including indented continuations of the most recent top-level key).

Edge case: if the cursor sits exactly on the `:` separator column, it is classified as "key" — the user has not yet stepped into the value.

Complexity: O(EndLine) worst case when scanning back for a parent key; for well-formed frontmatter this is bounded by the region size.

type CursorPosition

type CursorPosition string

CursorPosition classifies where in the frontmatter region a cursor sits. String-typed for diagnostic readability per D1 (pragmatism).

const (
	CursorOutside CursorPosition = "outside"
	CursorFence   CursorPosition = "fence"
	CursorKey     CursorPosition = "key"
	CursorValue   CursorPosition = "value"
)

type DocumentRenderedParams

type DocumentRenderedParams struct {
	URI  string `json:"uri"`
	HTML string `json:"html"`
}

DocumentRenderedParams is the payload for the calcmark/documentRendered notification.

type DocumentSnapshot

type DocumentSnapshot struct {
	Source      string
	Document    *specDoc.Document
	Evaluator   *implDoc.Evaluator
	Diagnostics []specDoc.Diagnostic
	HTML        string
}

DocumentSnapshot holds the immutable evaluation results for a document. Request handlers read from the latest snapshot without locks.

type FrontmatterRegion

type FrontmatterRegion struct {
	StartLine int            // line of opening `---`
	EndLine   int            // line of closing `---`
	KeyLines  map[int]string // line index → top-level key name
	// contains filtered or unexported fields
}

FrontmatterRegion describes the YAML frontmatter region delimited by `---` fences at the top of a CalcMark source. Lines are 0-based to match LSP.

func DetectRegion

func DetectRegion(source string) (FrontmatterRegion, bool)

DetectRegion finds the YAML frontmatter region in source. It is mid-edit robust: it does NOT parse YAML — it only locates the fences and extracts top-level key names from `key:` patterns. Returns ok=false when the source does not begin with a `---\n` fence or when no closing fence is present.

Complexity: O(n) over the bytes up to (and including) the closing fence.

type LexiconResult

type LexiconResult struct {
	// Function names from the registry — both canonical (e.g. `grow`)
	// and synonyms (e.g. `average` for `avg`). Includes only function
	// suggestions reachable from FunctionSpecs / Registry, not lexer
	// pseudo-functions.
	Functions []string `json:"functions"`
	// Conversion-relevant keywords surfaced by the lexer's
	// ReservedKeywords map, plus contextual keywords used in NL forms
	// (`by`, `compounded`, `to`). Excludes control-flow words that
	// have no calcmark expression semantics yet (`if`, `else`, ...).
	ConversionKeywords []string `json:"conversionKeywords"`
	// Unit categories valid for `scale.unit_categories` and
	// `convert_to.unit_categories` in frontmatter. Mirrors
	// `units.Categories()` exactly — the canonical set the server-side
	// validator accepts. The TS frontmatter form pulls this list to
	// populate its category chip-list, so adding a category in
	// `spec/units` automatically lights it up in the UI without a
	// client-side mirror needing to follow.
	UnitCategories []string `json:"unitCategories"`
}

LexiconResult is the wire shape returned by `calcmark/lexicon`.

The client uses these sets to color-code syntax in the calc-source preview — function names (`grow`, `throughput`, `accumulate`) and conversion keywords (`as`, `in`, `napkin`, `precise`) get a tertiary accent so the language vocabulary reads distinctly from user data.

The sets are static per LSP version (the function registry and keyword list do not change at runtime), so the client can fetch once after `initialize` and cache for the session.

type Server

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

Server is the CalcMark LSP server.

func NewServer

func NewServer() *Server

NewServer creates a new CalcMark LSP server.

func (*Server) RunStdio

func (s *Server) RunStdio() error

RunStdio starts the LSP server over stdio.

func (*Server) ServeWebSocket

func (s *Server) ServeWebSocket(conn *websocket.Conn)

ServeWebSocket serves the LSP protocol over an existing WebSocket connection. This blocks until the connection is closed. Intended for embedding the LSP inside an HTTP server that handles the WebSocket upgrade externally.