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.

InboundEntry

Represents InboundEntry.

InboundRow

One inbound-table row: file and line of the referencing site, then heuristic (whether the edge was guessed) and source (the trimmed referencing line). An empty source is omitted from --json.

InboundTables

The three inbound tables, one per kind (inherits/uses-type/uses-member).

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.

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 four outbound tables: three by kind 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, the lines at which it references the symbol, the ref_count, and whether the reference was guessed (heuristic).

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.

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.

TestsResult

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

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.

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

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.

resolve_impact_seed

Resolve an impact-walk seed argument to a file’s defs or a single symbol.

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.