Skip to content

Document reference LSP ​

Native and WASM transports use the same core methods. The LSP parses source and formats edits. The host owns candidate lookup and authorization. The LSP does not fetch candidates or keep a candidate cache.

Ranges use LSP UTF-16 line and character positions. The parser supplies the reference spans. Code, comments, literals, editor notes, and other raw source blocks do not produce reference targets. LSP core enables parser locations for both native and WASM builds.

The WASM LSP package exports TypeScript declarations for these methods from @sevenwiki/sevenmark-lsp/protocol. The ts feature of sevenmark_lsp_core generates crates/sevenmark_wasm_lsp/sevenmark_lsp_protocol.d.ts. A core test fails when the checked-in file differs from the Rust types. To update it, run SEVENMARK_UPDATE_TS=1 cargo test -p sevenmark_lsp_core --features ts typescript.

Host admission ​

initialize.initializationOptions.admission accepts optional max_source_bytes, max_ast_bytes, and max_semantic_tokens. Source size uses UTF-8 bytes. Syntax storage is a logical budget. Semantic tokens have a separate collection cap. The generated protocol exports AuthoringAdmissionOptions and AuthoringAdmission. The accepted complete admission appears at initializeResult.capabilities.experimental.sevenmark.admission.

The host supplies its effective limits once when it initializes the producer. Omitted fields use producer defaults. Invalid values return JSON-RPC -32602. The producer does not silently substitute a default for an invalid supplied limit. Parser and formatter WASM *_with_limits entrypoints use the same source and syntax-storage validation. JavaScript numbers must be finite, positive, whole values within the advertised portable bounds before conversion.

Retained editor usage ​

Send sevenmark/resourceUsage with {textDocument:{uri},version} after the existing textDocument/semanticTokens/full request. The server returns AuthoringResourceUsage, or null when the URI or version is no longer open. It reads retained counters without another parse or token traversal. The result contains the accepted admission, UTF-8 source size, logical syntax storage, parser and expression depth peaks, and semantic-token collection usage.

Each budget has limit, used, and saturating remaining. Parser usage is null when source admission refused parsing. Token usage is null until the existing token walk has run. Token status is complete, exhausted, or unavailable; emitted counts output tokens and budget.used is the accepted high-water count across raw, disjoint, and single-line token collection. An exhausted walk can emit no tokens with positive measured usage. This is not zero work. Rejected charges do not increase accepted usage.

The host must bind counters to the current document version, accepted admission, and worker instance. Clear them when source or authority changes.

Completion procedure ​

  1. Call sevenmark/referenceContext with {textDocument:{uri},position}.
  2. Request candidates from the host with the returned query and namespace restriction.
  3. Call sevenmark/referenceCompletions with the context and authorized candidates.
  4. Apply the selected completion's textEdit to the current document version.

The browser must abort old host requests when the document version, cursor, account, or region changes.

Reference context ​

sevenmark/referenceContext returns null outside a supported target. Otherwise, it returns {version,range,query,useKind,namespaceRestriction}.

useKind is wiki_link, include, redirect, category, file, or media_link. namespaceRestriction follows the parsed occurrence:

Source contextRestriction
File media or category membershipfile or category, including UUID targets
Explicit name:<namespace>:... targetThe name's namespace
Wiki-link namespace prefix, such as [[template:Title]] or [[:file:Title]]The parsed name's namespace
Include or redirect with #namespace, followed by a bare nameThe parameter's namespace
Bare general link, include, redirect, or media #link targetnull
General UUID target, including an include with #namespacenull

An explicit name supplies its own namespace even when a wrapper supplies a different default. #namespace sets the default scope of a name. It does not turn an include into a namespace-restricted operation on UUIDs. Includes can still reuse ordinary documents. File media and category membership keep their existing occurrence restrictions.

Null keeps the general picker open to authorized candidates in every namespace. It does not change the Document namespace used to resolve a bare name before a candidate is selected. The same parser handles incomplete and multiline targets, escapes, and valid namespace spellings. It excludes raw source contexts.

An include completion can pass a path such as Parent/Child as the host query. The host searches for the child. A path can exceed the length of a local title. The selected edit replaces the query with the child's UUID address. The include grammar still resolves an unselected bare name as a root title.

Source prefixes are not browser URL routing rules. In particular, {{{#include template:Title}}} is a literal Document title, not a Template selection. Use #namespace="template" Title or name:template:root:Title for that include.

Reference completions ​

sevenmark/referenceCompletions accepts {textDocument:{uri},position,version,range,candidates}. Each candidate has {document_id,namespace,title,display_path?}. The host must supply current readable titles and breadcrumb text.

The result is standard CompletionItem[]. Each textEdit.range replaces the exact reference. Its newText is id:<canonical UUID>. Anchors, display labels, include parameters, and the File media prefix stay outside the edit. A wiki-link namespace prefix is part of the replaced reference; the UUID retains the selected document's identity. A changed version or range returns no edits.

The LSP recomputes the current namespace restriction and rejects candidates from other namespaces. The host must also apply this restriction during candidate lookup. This check does not replace the host's authorization check.

Site follows the same candidate rule: [[site:Title]], name:site:root:Title and #namespace="site" Title restrict candidates to site. A host's language-edition display name is not sent as a namespace or added to parser completions. [[Site:Title]] remains an ordinary Document name.

The LSP accepts at most 100 candidates. Equal titles with different UUIDs remain separate candidates. Duplicate UUIDs are omitted.

The LSP omits optional breadcrumb details over 2000 UTF-8 bytes or with control characters. The candidate keeps its local title label and UUID edit. Clients must accept a candidate without detail. The LSP does not truncate breadcrumbs or reconstruct hierarchy.

Parsed references ​

sevenmark/documentReferences accepts {textDocument:{uri}}. It returns {version,references:[{range,useKind,reference}]}. A closed or unversioned document returns null.

reference uses the shared tagged enum:

json
{ "kind": "id", "document_id": "019a0000-0000-7000-8000-000000000001" }
json
{
  "kind": "named",
  "namespace": "document",
  "parent_document_id": null,
  "title": "Title"
}

A named child scope has a parent UUID instead of null. Decoration consumers must use the returned ranges and reject stale versions. They must not parse source with a second parser. An editor can display authorized titles or paths while the source retains UUID references.

Discussion message input ​

sevenmark/messageReferenceContext accepts the same text-document and UTF-16 position fields as sevenmark/referenceContext. It returns null outside an eligible #N input, or {version, range, prefix}. The range includes # and the decimal prefix. An empty prefix requests recent messages. At a line start, the numeric form is eligible even when Markdown also parses it as a header. Code, literals, comments, TeX, parameters and condition expressions are excluded. Parser closure probes exclude unfinished raw constructs while the user types.

The host supplies currently readable candidates from the selected discussion. Selecting a candidate replaces the range with <^message-uuid>. The host must discard a response after source, selection, account, authority or thread changes. The LSP performs no network or authorization lookup.

Standard built-in completions now provide exact UTF-16 text edits. These edits replace the whole keyword and reuse adjacent closing delimiters. Existing nonempty arguments and bodies remain intact. LSP snippets retain numbered tab stops; clients must translate the snippet syntax their editor requires.