Module query 

Graph queries and their result models.

Structs

AmbiguousRow

One ambiguous-table row: the referencing file/line, the origin and raw text of the reference, and how many candidates it matched.

AmbiguousTables

The inbound and outbound ambiguous-reference tables.

BrakedFile

A hub file the walk refused to widen THROUGH, and how many distinct other files reference it. Kept in its own vec (separate from BrakedIface) so that type, its tests and its JSON bytes are untouched when the file brake never fires. Sorted widest-first then by path, the same total order, for the same reason.

BrakedIface

An interface the walk refused to widen through, and how many distinct constructors inject it. Sorted widest-first then by name, a total order that depends on nothing about the walk’s own iteration.

DefSite

Represents DefSite.

GraphIndex

The built query index over a Graph. by_id/by_file/by_simple_name/ by_lower_name store graph.defs indices rather than cloned Defs, so a def is never copied into every bucket it is reachable from.

ImpactModel

The resolved impact result for one seed.

ImpactRow

One row of an impact model: a file in the blast radius and its metrics.

ImpactWalkResult

The result of an impact walk.

ImportRow

One imports-table row: file/line, the imported target namespace, and source. An imports edge is never a guess, so unlike OutboundRow this carries no heuristic field.

ImportedRow

One row of imported-edge reach: a file this graph never resolved an edge to, named only because a foreign, producer-asserted record points at (or out of) a file the native walk already reached.

ImportedSection

The imported half of an impact answer: capped and counted apart from the native rows, so a large import can never evict one of them.

InboundEntry

Represents InboundEntry.

InboundRow

One inbound-table row: file and line of the referencing site, then heuristic (whether the edge was guessed), tier (which guess tier said so) and source (the trimmed referencing line). An empty source is omitted from --json. occurrence_index distinguishes two rows that would otherwise be equal on every other field (see the occurrence module); it is None on every row outside such a collision.

InboundTables

The five inbound tables, one per kind.

IndexOptions

What the caller wants left OUT of the index it is asking for.

KindLines

One representative referencing line PER EDGE KIND that reached this file, the lowest line per kind. 0 means “this kind never contributed”, which keeps a row a kind never touched free of that key in --json. direct_amb is the ambiguous half of the direct kind, kept apart only so build_impact_model can apply the resolved-over-ambiguous tie-break instead of letting an ambiguous line win by being numerically smaller.

MemberCandidate

One row of an ambiguous member seed: the declaring type, the member name, and the FIRST site that type declares it at.

MemberRefEntry

One enum member that carries at least one inbound reference.

MemberRefs

How many of an ENUM’s inbound member edges land on one of its members, split by member.

OutboundEntry

Represents OutboundEntry.

OutboundRow

One outbound-table row: file/line of the referencing site, to_file/to of the target, then heuristic and source (same omit-when-empty rule as InboundRow). source is read at the site actually making the reference – for an outbound edge that is a line in the def’s own file, not the target’s.

OutboundTables

The six outbound tables: three by kind, implements/overrides, plus imports.

ReadModel

The resolved read result for one symbol: everything refs answers,

ReadSpan

The declaration span of a resolved def: the file, its 1-based start and end lines, and the VERBATIM source text of those lines (no trim, no clip

RefsModel

The resolved refs result for one symbol.

SeqMap

Insertion-order-preserving String-keyed map with a mutable get-or-insert-default accessor. Same shape as graph::OrderedMap, kept as a separate small type here because that one exposes no get_mut/entry-style API. Public for the same reason as SeqSet – appears in [ImpactWalkResult::visited].

SeqSet

Insertion-order-preserving set: insert is a no-op when the value is already present (first insertion wins the position). Public because it appears in [ImpactWalkResult]’s public fields.

SymbolRefs

The immediate inbound/outbound edges of one resolved symbol, holding graph.edges indices rather than cloned edges (the same convention GraphIndex uses).

Table

A capped table: total rows before capping, how many were dropped, and the surviving rows.

TestRow

One row of a tests model: a test file, the test-carrying test_defs in it (possibly empty for a Project-vouched row – a harness file in a test project need not declare any attributed method itself), the lines at which it references the symbol, the ref_count, whether the reference was guessed (heuristic), and which vouch (via) put the file in this model at all.

TestsModel

The resolved tests result for one symbol.

VisitedEntry

One visited file’s entry in an impact walk.

Enums

ImpactResult

The outcome of an impact query: resolved, ambiguous, or not found.

MemberSeedResolution

Whether resolving seed as a member’s declaring type, ignoring inbound references entirely (unlike refs.rs’s own edge-verified fallback).

Outcome

One of the four words a query verb’s --json answer names its result with.

ReadResult

The outcome of a read query – the refs outcome set unchanged, so the ambiguity and zero-hit discipline are literally the same code path’s.

RefsResult

The outcome of a refs query: resolved, ambiguous, a bare-member answer, or not found.

Resolution

Represents Resolution.

SeedKind

Represents SeedKind.

SeedResolution

Represents SeedResolution.

TestVia

Which vouch earned a row in a tests model: an attribute-carrying def declared in the file (Attribute), or, absent that, the project model placing the file’s unit inside a project marked test (Project).

TestsResult

The outcome of a tests query: resolved, ambiguous, or not found.

Why

One of the words a hit row’s why field names.

Constants

DEFAULT_CAP

Default per-table row cap for the outbound and ambiguous tables. The three inbound tables share INBOUND_CAP instead.

DEFAULT_DAMPING

Default damping factor for the personalized PageRank pass.

DEFAULT_HOPS

Default number of hops for the impact walk.

DEFAULT_HUB_MAX_INDEGREE

Default hub brake: a file whose in-degree is at or above this stops widening. In-degree here is the number of DISTINCT OTHER FILES that reference a file through a direct (inherits/uses-type/uses-member) or heuristic edge. Derived from a corpus histogram rather than guessed: 824 files carry at least one referrer, every value from 1 to 33 is populated (holding 777 of the 824, 94.3%), and the first empty slot is at 34, above which the tail is sparse and gapped. The comparison is >=, so 34 is the first value that is not an ordinary file. 0 disables the in-degree half of the brake; the name-pattern half (is_infra_file) is a classification, not a threshold, and stays on.

DEFAULT_IFACE_MAX_FANIN

Default fan-in brake: an interface injected into more than this many distinct constructors is treated as infrastructure for widening purposes, whatever it is called. Chosen from the constructor-injection in-degree histogram of a large corpus, where 151 of 155 injected contracts (97.4%) sit at or below 8 and nothing sits between 8 and the four estate-wide ones (9, 11, 12, 21). 0 disables the brake (--iface-max-fanin 0).

DEFAULT_ITERATIONS

Default iteration count for the personalized PageRank pass.

INBOUND_CAP

Default cap shared across all three inbound kinds – one cap total, not one per table.

OUTBOUND_CAP

Default cap for the --out view: one cap shared across all four outbound kinds (inherits/uses-type/uses-member/imports), the mirror of INBOUND_CAP. --all lifts this cap.

SCHEMA_VERSION

The version of the --json answer shape every refs/read/impact/ tests object carries as its first key. Bump it only when an existing key is renamed, removed, or given a different meaning – adding a new key, as schema_version and why themselves were added, never requires a bump. A consumer should ignore any key it does not recognise.

SOURCE_MAX

Maximum length of a displayed source line, in UTF-16 code units. Truncation counts code units (see clip_source) so the cut is stable regardless of any astral characters on the line.

Functions

build_impact_model

Blast radius for a seed, ranked. Never filters beyond the stated cap: rows is the ranked, capped view; dropped/total_affected account for every row the walk found, capped or not.

build_imported_section

Builds the imported section of an impact answer.

build_read_model

read = refs resolution + capped-and-ranked inbound machinery, reused

build_refs_model

Build the refs model for query. out includes the outbound tables; cap/inbound_cap/outbound_cap bound the tables; all_out (--all) lifts the inbound and outbound caps.

build_tests_model

Which TEST files reference this symbol, at which lines, via which test-carrying defs. Nothing here is a new kind of edge: it is the same inbound set refs reports, filtered to the files test_defs_by_file vouches for, which is why a symbol nothing tests answers “none” rather than falling back to a name convention.

def_files

The distinct files a def is declared in, deduped: a partial type’s also_in site can share a file with its primary declaration.

def_sites

Every declaring site of a def, NOT deduped (unlike def_files) – each site is its own row.

file_inbound_counts

The per-file precise inbound-edge count find’s tie-break ranks by.

find_names

Name search: every whitespace-split token of query has to appear, case-insensitively, as a substring of the declared NAME – path and purpose are the manifest search’s haystack, not this one’s. The caller owns the graph (see the module header’s two-phase note). Results come back in index build order; ranking is the caller’s job.

first_decl_line_by_file

Every FILE’s own first declaration line, keyed by path: the minimum line across every graph.names entry that file carries, over the WHOLE index. Unlike find_names, this is never filtered to one query’s matches, because a manifest-pool row needs a line to open regardless of the query. A file the name index carries nothing for (no declared symbol at all – a config file, a doc, an asset) has no entry here; the caller falls back to line 1.

impact_walk

Reverse-edge k-hop walk from a set of seed def ids. Hop N’s frontier is every def declared in a file discovered at hop N-1; a file already visited (or a seed’s own file) is recorded at most once, at its first (minimum) hop. Ambiguous edges whose candidates include a frontier def count toward via-count/top-symbols too. As a byproduct it builds fwd_adj, the file-level subgraph that seeds the PPR ranking pass.

is_infra_file

A file whose PATH says it is infrastructure. Always on: unlike the in-degree threshold, this is a classification of what the file is FOR, and 0 on the threshold does not turn a composition root back into an ordinary file.

load_graph_index

Build the query index, phase two of the two-phase build (see module header). graph is what the caller got back from graph::read_graph(root); root is used here only for the manifest join.

load_graph_index_with

load_graph_index with the caller’s own IndexOptions. Everything is built the same way either way; opts only decides which heuristic edges earn a place in the heuristic adjacency.

looks_like_file_path

Whether arg looks like a file path rather than a symbol query: a bare simple/qualified name with no path separator or file extension is a symbol query; anything else is a file path. Equivalent to /\.[A-Za-z0-9]+$/ by checking the LAST . only (if an earlier dot’s suffix were all-alnum, the last dot’s suffix – which contains that earlier dot – could not be, since . is not [A-Za-z0-9]). Note a fully-qualified symbol id like App.Widgets.IWidget (trailing segment alphanumeric) DOES look like a file path under this heuristic.

name_tier

Collapses suggest::kind_rank into three tiers for find’s default view: tier 1 is a code symbol (kind_rank 0 – a type or top-level declaration – or 1 – a member), tier 2 is a markup or binding name (kind_rank 2), tier 3 is a resource key (kind_rank 3). find matches tier 1 then 2 by default and demotes tier 3 to a one-line trailer (--resources includes it).

personalized_page_rank

Personalized PageRank over the file-level subgraph. Plain power iteration, no dependencies. Ranking only – never removes a node.

qualified_member_owners

Every type declaring a member named name, in name-index order, each with every site it declares it at.

qualified_seed

The synthetic, fully-qualified seed --pick re-resolves against.

resolve_impact_seed

Resolve an impact-walk seed to a file’s defs or a single symbol. The type ladder (resolve_symbol) runs first; a member seed, tried only once it has missed, answers AS its unique declaring type – impact has no member-shaped answer of its own. A dotted member seed looks like a file path under looks_like_file_path, so it is tried on a file-path MISS instead: that branch never resolved a type before, so nothing changes.

resolve_member_seed

Resolve seed (Member, Type.Member, or Namespace.Type.Member) to the def id of the type that uniquely declares it.

resolve_symbol

“Never guess” resolution ladder: exact id, then unique exact name, then unique case-insensitive name; two-or-more candidates at any step is reported as ambiguous, not resolved further.

source_line

The literal line a declaration sits on, ASCII-trimmed by trim_source. Returns "" on an unreadable file or an out-of-range line; the caller then prints file:line with nothing after it rather than a row ending in a dangling separator.

symbol_refs

Immediate (1-hop) inbound/outbound for one resolved symbol. Partial-class defs union outbound over every declaring file. An enum query unions every member’s inbound uses-member edges in, iterating index.graph.defs directly (its array order) rather than the unordered by_id map.

Type Aliases

HeuristicEntry

The value shape of both heuristic_inbound and heuristic_outbound_by_file (inherits/uses-type/uses-member – note no imports: an imports edge names a namespace string, never a def, so no tier can guess one). Structurally identical to InboundEntry, and deliberately the same type.

LineCache

Per-file cache of source lines, so a widely used type does not re-read one consumer file once per hit. The value is None for a file that could not be read.