Struct CodeModel 

pub struct CodeModel { /* private fields */ }

A source file read at the code level.

Implementations

impl CodeModel

pub fn build(source: String, lang: Lang, decls: Vec<Decl>) -> Self

Derive the arbor from a producer’s Decl stream — the seam. decls must be pre-order: a parent precedes its children.

pub fn parse(text: &str, ext: &str) -> Result<Self, CodeError>

Read text as ext’s language at the code level: the backend parse (cached when the thread’s AST cache is enabled — see quarb_tree_sitter::set_cache) lowers through the grammar’s table.

pub fn open(path: &Path) -> Result<Self, CodeError>

Read a file at the code level, language by extension.

pub fn locator(&self, node: NodeId) -> String

A human-readable locator: name-or-construct segments, a [n] index only among same-label siblings — /lexer/lex/is_name_char, /main/for/call[3].

pub fn source(&self) -> &str

The parsed source text.

pub fn lang(&self) -> Lang

The grammar this model was lowered from.

pub fn ident(&self, node: NodeId) -> Option<&str>

The declared (or adopted) identifier — None on anonymous constructs and the file root. Distinguishes a function named switch from the construct: the identifier is a stored fact, not a name-string comparison.

pub fn construct(&self, node: NodeId) -> &str

The vocabulary word ("" on the file root).

pub fn span(&self, node: NodeId) -> (usize, usize)

Byte range into the source.

pub fn line_span(&self, node: NodeId) -> (usize, usize)

1-based start/end lines.

Trait Implementations

impl AstAdapter for CodeModel

fn name(&self, node: NodeId) -> Option<String>

The declared identifier, else the construct word; the file root stays unnamed.

fn property(&self, node: NodeId, name: &str) -> Option<Value>

The uniform property set: ::signature, ::doc, ::callee — the identifier is NOT a property (it is the name; :::name answers it). Aliased annotation keys fall through to metadata via AstAdapter::aliased_metadata.

fn default_value(&self, node: NodeId) -> Option<Value>

A node’s source text.

fn links(&self, node: NodeId) -> Vec<(String, NodeId)>

->definition: a call’s edges to the declarations its callee resolves to (same file, by identifier).

fn backlinks(&self, node: NodeId) -> Vec<(String, NodeId)>

<-definition: find-references — every call site whose callee resolves here.

fn root(&self) -> NodeId

The root node — the initial navigation context.

fn children(&self, node: NodeId) -> Vec<NodeId>

The tree children of node, in document order.

fn parent(&self, node: NodeId) -> Option<NodeId>

The parent of node, or None for the root.

fn traits(&self, node: NodeId) -> Vec<String>

The traits of node — its adapter-defined classifications, used by <trait> navigation filters (e.g. a filesystem adapter’s <dir>, <code>, <image>).

fn metadata(&self, node: NodeId, key: &str) -> Option<Value>

Adapter-defined metadata — ::::key (a filesystem adapter’s size, modified, permissions, …). None if absent.

fn aliased_metadata(&self, _node: NodeId) -> &'static [&'static str]

Metadata keys this adapter also answers at :: (ruling #29), for the given node — per node, because a composite adapter (a multi-mount, a graft) answers for whichever document owns it. Only an adapter whose property surface is closed — fixed by the adapter, never grown by document content — may declare aliases: a git commit cannot sprout a short field, where a JSON object can sprout anything. Data always wins: the engine consults property first and falls through only when it answers None for that node, so an alias can never shadow a document. Core metadata (:::) is never aliased — name, id and index exist on every node, and aliasing them would change what ::name means wherever a document happens to lack that field.

fn children_named(&self, node: NodeId, name: &str) -> Vec<NodeId>

The children of node whose edge name is exactly name — the engine’s fast path for name-matcher child hops. The default filters children; an adapter whose containers cannot be enumerated (permission-scoped or unbounded remote trees) overrides this with a direct, name-addressed lookup. Must be observationally identical to the default wherever enumeration works. The adapter owns the name test: it may deliberately alias — resolve a name to a node whose edge name differs (git revision syntax landing on a hash-named commit) — and the engine will not re-filter. Container-scoped resolution like that stays child-axis only; per-node spelling aliases belong in answers_to, which this default consults.

fn answers_to(&self, node: NodeId, name: &str) -> bool

Whether node answers to name as a literal spelling (ruling #30). The default is canonical equality. An adapter may declare per-node aliases — a social feed spelling a handle @alice while the stripped alice is the hop name — and the engine consults this wherever a literal name is matched, on every axis, so one override keeps /@alice and //@alice in agreement. :::name stays canonical (locators and reflection print it; an alias is a way in, never a way out), and name patterns (~(...), *) test the canonical name only.

fn resolve( &self, _node: NodeId, _property: &str, _hint: Option<&str>, ) -> Option<NodeId>

Resolve a cross-reference: ::property~>hint maps node’s property (a value that references another node) to its target, with an optional adapter-specific relation hint. A JSON adapter resolves a $ref JSON Pointer; None if unresolvable.

fn external_ref( &self, _node: NodeId, _property: &str, _hint: Option<&str>, ) -> Option<String>

The external reference node’s property holds, if any: an adapter-defined identifier of a document outside this arbor — for html, the anchor’s absolute URL, a relative href joined against the document’s own URL. A #fragment part is the crossref within the target document and rides along (URI semantics). Consulted by ::property--> when in-document resolution misses: a mounted document with that identifier answers (the fragment’s element, else its root), an unmounted one lands among the run’s unresolved external references for the host’s acquisition loop. The engine itself never fetches.

fn resolve_fragment(&self, _node: NodeId, _fragment: &str) -> Option<NodeId>

The element fragment names inside the document node belongs to — html’s id lookup. The landing rung of a fragment-carrying external reference, once its document is mounted.

fn ref_property(&self, _node: NodeId) -> Option<String>

The property carrying node’s own reference, for the bare arrow (//a-->): an html anchor’s href, an iframe’s src. None for a node that references nothing.

fn ref_label(&self, _node: NodeId, _property: &str) -> Option<String>

The relation name a resolution edge from node via property carries — html’s rel attribute. None falls back to the property name as the edge label.

fn link_property( &self, _source: NodeId, _label: &str, _target: NodeId, _name: &str, ) -> Option<Value>

A property of the crosslink source --label--> target — the $-::prop read. Adapters whose edges carry data (a property graph’s relationship properties) override this; None if the edge is bare or unknown. Where parallel edges share source, label, and target, the adapter answers for one of them, consistently.

fn quantifier_bound(&self) -> usize

The quantifier bound N_max: the depth to which open-ended path quantifiers (+, *, {m,}) expand, and the ceiling of any explicit {m,n} (the effective upper bound is min(n, N_max)). An adapter whose natural structures run deep may raise it; the CLI overrides it per run (qua --quantifier-bound).

fn allow_shell(&self) -> bool

Whether the sh(...) pipeline stage may run external commands. False by default — query text stays inert data — and enabled per run by the CLI (qua --allow-shell) through the AllowShell wrapper.

fn invocation_instant(&self) -> Option<(i64, u32)>

The invocation instant now() denotes (spec: The Temporal Fragment, Determinism): one UTC timeline point bound by the runner BEFORE evaluation begins — evaluation itself never reads a clock. None by default (a library run is fully deterministic; now() reads as null); the CLI binds it at startup — pinnable with qua --now — through the WithNow wrapper.

fn provenance(&self, _node: NodeId) -> Provenance

The data provenance of node — the :::source / :::instant / :::dpid / :::provenance core-metadata keys. Empty by default: an adapter answers only the components its substrate genuinely records (never the invocation clock); wrapper adapters fill missing components from what they know — the mount its target, a graft its outer leaf, a model its derivation — and forward the rest inward, so resolution is nearest-ancestor per component.

fn unit_scale(&self, expr: &str) -> Option<(f64, String)>

The scale of a unit expression — (factor, canonical SI-base expansion) — for the unital reading’s criterion text (spec: The Quantital Fragment). The default answers from the engine’s frozen built-in table; a unit-aware adapter (kaiv) overrides it to include the mounted document’s own custom units, so [::range < '50kellicam'] resolves through the document’s .!units imports.