Crate lex_extension 

Public surface for Lex extensions.

This crate is the stable contract that handler authors and Rust embedders depend on. It defines:

• The LexHandler trait — the protocol’s source of truth.
• Wire types (LabelCtx, WireNode, WireInline, diagnostics, render output, hover, completions, code actions) — the cross-version stable representation of Lex content and hook payloads.
• Schema types (Schema and friends) — the read-only structs a YAML loader produces.
• The Format enum used by render hooks.

The runtime registry, schema loader, transports (subprocess, WASM), trust gate, and sandboxing live in the internal lex-extension-host crate. Handler authors depend on lex-extension only.

Versioning

There are two version axes, intentionally decoupled:

• WIRE_VERSION identifies the JSON-RPC wire-format contract exchanged at the initialize handshake. Handlers across any transport (subprocess, native, future WASM) speaking the same WIRE_VERSION interoperate. Once stable, breaking changes to the wire format bump this integer.
• The crate’s Cargo version (0.1.x today) tracks the Rust API.

The two axes line up at 1.0: this crate ticks to 1.0.0 when its Rust API stabilises, and at that point a handler built against lex-extension = "1" speaks WIRE_VERSION = 1. Until then the Rust API is per-Cargo unstable: any 0.x → 0.y bump may be source-incompatible.

Where forward-compatibility is implementable today without API churn, it is:

• String-shaped enums (severity, completion kind, code-action kind, ref kind, hover format) deserialise unknown wire values as a documented fallback (Info, Value, Refactor, General, Plaintext). New variants in the wire protocol are non-breaking for handlers — older handlers see the fallback.
• Block AST kinds (WireNode, WireInline) are closed within a WIRE_VERSION. Adding a new kind is a wire-version bump, not a silent extension. The #[non_exhaustive] attribute on those enums keeps the Rust side additive across lex-extension major versions.
• Public structs (Diagnostic, Hover, Completion, etc.) are not #[non_exhaustive] today, by design — pre-1.0, struct-literal construction is the right ergonomics for handler authors. Before tagging 1.0 the public structs will gain #[non_exhaustive] plus constructors, so post-1.0 field additions stay non-breaking.

See comms/specs/proposals/lex-extension-wire.lex for the normative wire-format spec.

Re-exports

pub use handler::HandlerError;

pub use handler::LexHandler;

pub use wire::AnnotationBody;

pub use wire::CodeAction;

pub use wire::CodeActionKind;

pub use wire::Completion;

pub use wire::CompletionKind;

pub use wire::Diagnostic;

pub use wire::DiagnosticSeverity;

pub use wire::Format;

pub use wire::FormatCtx;

pub use wire::HostNodeKind;

pub use wire::Hover;

pub use wire::HoverFormat;

pub use wire::LabelCtx;

pub use wire::LexAnnotationOut;

pub use wire::NodeRef;

pub use wire::Position;

pub use wire::Range;

pub use wire::RefKind;

pub use wire::RelatedDiagnostic;

pub use wire::RenderOut;

pub use wire::TextEdit;

pub use wire::WireFootnote;

pub use wire::WireInline;

pub use wire::WireListItem;

pub use wire::WireNode;

pub use wire::WireRow;

pub use wire::WireTableCell;

pub use schema::BodyKind;

pub use schema::BodyPresence;

pub use schema::BodyShape;

pub use schema::Capabilities;

pub use schema::DiagnosticDecl;

pub use schema::EnumValue;

pub use schema::HandlerSpec;

pub use schema::HandlerTransport;

pub use schema::HookSet;

pub use schema::ParamSpec;

pub use schema::ParamType;

pub use schema::RenderHook;

pub use schema::Schema;

Modules

handler

The LexHandler trait — the protocol’s source of truth.

schema

Schema types — the read-only structs a YAML loader produces.

wire

Wire-format types: the cross-version stable representation of Lex content and hook payloads.

Constants

WIRE_VERSION

The wire-format protocol version exchanged in the initialize handshake.