Module symbols 

Symbol lookups for hover and go-to-definition.

Single-file lookups walk the parsed AST. Cross-file lookups (v1.1; LSP spec §3.4 cross-file requirement) iterate the project’s .bynk sources to find a declaration in any unit the user might be referencing — used when the open file lacks the symbol the user clicked on (typically because the name was imported via uses or made available via consumes).

Structs

CrossFileSymbol

A cross-file declaration lookup result: the path of the file containing the declaration, the declaration’s source span, and the full source text of that file (returned because callers need it to convert the span to an LSP range and to build hover content).

DocLinkCandidate

#848: one intra-doc-link candidate scanned from doc-comment text — a [Name] shortcut, a [`Name`] code-span-wrapped shortcut, or a [text][Name] full reference. span is the byte range (into the text the scanner was given) of the whole construct to rewrite when name resolves; display is the link text to keep (Name for a shortcut, the code span including backticks for the code-span form, text for a full reference).

Functions

describe_agent_state_at

v0.137.0 (ADR 0161): hover for the key/store contextual keywords and the agent state fields they introduce. Both are lexed as Idents (not reserved KEYWORDS), and the fields they declare are neither let/param locals nor top-level declarations — so neither the keyword fallback nor the describe_symbol/locals paths in the hover handler reach them. This closes that gap: for the cursor on the key/store keyword or on the field name it declares, render the field’s signature (type, and a store field’s @indexed/@bounded/… annotations) followed by the contextual-keyword doc.

describe_firstparty_symbol

Describe a symbol declared in the embedded first-party sources — the bynk and bynk.cloudflare adapters and the bynk.list/bynk.map/bynk.string stdlib. Hover and completion-doc resolution otherwise walk only the project’s files (walk_bynk_files), so stdlib/surface symbols had no surfaced signature or doc; this is the fallback after the project scan. Any --- doc block on a first-party declaration rides along (via describe_fn/describe_type/…), once the sources carry one.

describe_handler_annotation_at

v0.140 (ADR 0163): hover for a handler-position annotation (@cache). Handler annotations are not symbols and declare no local, so they miss both the describe_symbol and locals paths — this closes the gap. For the cursor anywhere within a handler’s @cache( … ) annotation, render the formatted annotation followed by a prose description of @cache and its fields. None when the cursor is not inside a handler annotation.

describe_keyword_at

v0.121 (ADR 0156): the reserved-keyword doc for the token at offset in source, if the cursor sits on one — matched by source text against bynk_syntax::keywords::KEYWORDS, independent of the token’s TokenKind (unlike the identifier-only lexical hover fallback above). This is hover’s floor for the mechanical coverage test: every lowercase-initial keyword gets at least this, even where describe_symbol has no richer path for it (e.g. the testing-track clause keywords — requires/ensures/suite/…).

describe_self_at

v0.122 (editor-currency slice 1): a hover summary for self under the cursor — self: <Type>. self is a reserved keyword (never an Ident, so it does not flow through locals_nav), but a self use is a typed expression, so its type is in expr_types at the token’s span. For a method the type is the receiver’s name; for an agent handler the checker gives self a synthetic record type __<Agent>Self (to resolve self.<key>), which is un-synthesised here to <Agent>. None when the cursor is not on the self keyword or its type is unknown (a broken buffer — expr_types is clean-file-only, so this degrades to the keyword doc, never a wrong type).

describe_store_op_at

#611: hover for a store field’s operation — the <op> of a <field>.<op>(…) call on an agent’s store field (items.put(id, item)). Store operations are checked but never indexed and are not value-receiver methods, so qualified_callee_at (name-receivers only) never reaches them and they resolved nowhere. Renders the operation’s signature from the enumerable bynk_check::store_ops registry — generic in the kind’s key/value/element type — over the field’s declared kind, which grounds it.

describe_symbol

Build a Markdown summary of a named declaration suitable for an LSP hover response. Returns None if no declaration matches.

describe_symbol_cross_file

Markdown hover content for name from any project file other than current_path, plus the path of the file that contributed it. See find_declaration_cross_file’s doc for the content-ownership-track shape of files. Returns None if the name is not declared anywhere in the project.

doc_link_spans

#848: the (candidate name, absolute source span) of every intra-doc-link candidate inside every DocBlock token in source — the clickable ranges for doc-comment document links, mirroring unit_reference_spans’s role for uses/consumes targets. Spans are computed against the raw, unstripped doc-block body (bynk_syntax::lexer::doc_block_body_range), not the common-indent-stripped doc_block_content text — that stripping is not offset-preserving, so a span-based caller must avoid it. Only tokenizes (not a full parse), so links still surface even when the rest of the file has a parse error elsewhere, as long as tokenization succeeds.

find_declaration_cross_file

Find name’s declaration in any project file other than current_path. Content-ownership track (#1086) slice 1: files is a pre-read (path, content) map (the caller’s overlay-then-disk sweep) rather than bare paths this function used to read from disk itself. Returns the first hit, in path-sorted order (see sorted_paths); None if the name is not found anywhere in the project.

find_declaration_span

Return the source span of the declaration named name in the given source text. Returns None if no declaration matches.

handler_annotation_token_spans

v0.140 (ADR 0163): the spans to classify as decorator semantic tokens — each handler annotation’s @name (the @ through the name) and its argument labels (maxAge:, scope:). Parsed from source; empty when it carries no handler annotations. Feeds the semantic-tokens producer, which is otherwise a parse-free index read, so the parse lives here beside the hover parse.

own_declaration_name

#302: the source’s own declared qualified name and its span — the rewrite target when the file backing this unit is renamed. None for a suite (its SourceUnit::name() is its target’s name, not one of its own; nothing else addresses a suite by name) or on a parse bail.

qualified_callee_at

v0.123 (editor-currency slice 2, DECISION B): if the identifier at ident_span is the member of an Upper.member name-receiver access (Clock.now, Email.of), return the full Recv.member callee for crate::signature_help::resolve_label to resolve to its signature — the same resolution completion and signature help perform, no new index. None for a bare identifier or a lowercase (value-receiver) method, which resolve_label does not handle.

scan_doc_link_candidates

#848: every intra-doc-link candidate in text, in order. [text](url), an author-defined [label]: url reference, fenced-code-block content, and non-identifier bracket content ([note]) are excluded — see scan_bracket_candidate and doc_link_prepass (private below).

store_field_kind_at

#596: the storage-kind vocabulary a bare receiver is eligible for at completion’s <recv>. position — recv_end is the offset just past the receiver identifier (where its dot sat before completion::value_receiver_rewrite dropped it, so source here is that rewritten buffer). Mirrors describe_store_op_at’s by-provenance receiver check (not shadowed by a local, inside the declaring agent’s state scope), but starts from the receiver’s own end offset rather than walking back from an operation token, since completion fires before any member name is typed — and the rewrite’s postcondition already guarantees a bare, non-dot-qualified name reaches here, so unlike describe_store_op_at there is no further is_dot_preceded check to make.

type_ref_str

unit_reference_spans

Slice 6b: the (unit name, name span) of every uses/consumes target in the source — the clickable ranges for document links. The link’s target file is resolved by the handler through the unit→source map (ADR 0095); this only finds the spans, so it works on the live buffer regardless of the map.