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).

Constants

ENV_KEYWORD_DOC

#2134: the contextual env word’s one-line doc, shown when hovering it.

RESERVED_PRINCIPALS

#706, #2135: the reserved call-site principals of a test case — each with what the system driver sends for it. Not declarations: by <name> names one of these, never an actor.

RUN_ID_DOC

#2138: the doc run.id shows on hover and in completion.

Functions

describe_advance_at

#2137 (ADR 0156): hover for the contextual advance keyword of an advance Clock by <Duration> statement. None anywhere else, so an ordinary identifier named advance keeps its own hover.

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_env_at

#2134: hover for a suite’s or case’s env { … } clause — on the env word, its doc (ENV_KEYWORD_DOC); on an entry’s name, the entry and where it applies: “variable given to every participant (suite)”, or “(case, overrides suite)” for a case entry its suite also gives. env is lexed as an identifier, so neither the keyword fallback nor the declaration rungs reach it. None when the cursor is on neither.

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_reserved_principal_at

#2135: hover for a reserved principal (Nobody, Forged, Stale) in a call-site by clause: what the driver sends. None when the cursor is not on one of those names right after by.

describe_run_id_at

#2138 (ADR 0156): hover for run.id in a case body — on either the run or the id. None anywhere else, and where the case binds its own run, so an ordinary value keeps its own hover.

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 (no expr_types entry for it — on a broken buffer ADR 0094’s partial types usually still carry one; when they don’t, this degrades to the keyword doc).

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.

describe_system_job_address_at

#2136 (ADR 0156): hover for the schedule / message address name in a system-tier case (sweeper.schedule(…), deliveries.message(m)), which runs the handler through the participant Worker’s own scheduled / queue entry point rather than in process. None anywhere else, including the same address at unit or integration, and a .schedule / .message whose receiver is not a cron / queue service of the suite’s target (a record field named message, say). The target’s declaration is looked up in source and others (the project’s other files).

describe_unit

#1885: hover Markdown for the unit name — a fenced <kind> <name> line, followed by its module doc when one of its files carries one.

describe_unit_at

#1885: the module-doc hover for the unit name under offset in text (see unit_name_at), resolved against text itself, then others (the project’s other files), then the embedded first-party sources (so consumes bynk.cloudflare still names its unit). None when the cursor is not on a unit name, or no source declares it.

describe_variant_key

#1888: the hover for a sum variant named by a qualified key, "Shape.Circle", declared in source; None when no sum there has it.

describe_variant_named

#1888: the hover for a sum variant named bare, as a pattern or a constructor names it (Circle(r)), when exactly one sum in source declares a variant of that name; None otherwise, so an ambiguous name answers nothing rather than the wrong variant.

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.

firstparty_notes

Standard-library S3 (#1963): what hover adds about a first-party item’s stability: that it is experimental (no compatibility promise, and an [unstable] allow to use), and that an enum is extensible (a match on it needs a wildcard). Empty for a stable, closed item.

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.

is_test_run_receiver

#2138: whether the run identifier starting at run_start in source is the test run’s run — inside a suite’s case body, with no binder of its own in scope there. #2175: the scope is the checker’s: a let earlier in any enclosing block, a lambda parameter, a match arm’s pattern, or an is <pattern> test’s bindings all shadow it. #2181: an is test binds where the checker says it does (bynk_check::narrowing): in an if’s then block when the condition holds, in its else block when it fails (if !(v is Some(run)) { … } else { run.id }), and on the right of && and implies (v is Some(run) && run.id == "x").

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_name_at

#1885: the qualified unit name under offset, when the cursor sits on the file’s own unit-header name or on a uses/consumes (or a suite’s) target path — the positions where hover shows a unit’s module doc.

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.