Skip to content

vox-graph-reader API Reference (generated)

Crate: vox-graph-reader · Version: 0.6.0 · Target: Library (lib.rs)

Read-only BFS traversal, path-finding, and cross-manifest comparison for Vox Graph graph.json exports

Read-only graph reader for Graphify graph.json (NetworkX JSON export format).

{ "nodes": [{"id": "x", "label": "...", "community": "c1"}],
"links": [{"source": "x", "target": "y"}] }

Edges may appear under "links" or "edges" — both are supported. Edges are indexed three ways: a symmetric adjacency (undirected, default Direction::Both), a forward index (source→target = caller→callee, Direction::Out), and a reverse index (callee→caller, Direction::In). Traversal selects the index via [Direction].

FeatureDefault / Enables
defaulttree-sitter-grammars
tree-sitter-grammarsdep:tree-sitter, dep:tree-sitter-rust, dep:tree-sitter-typescript, dep:tree-sitter-python
ModuleDescription
ast—
ast_vox—
bfs—
cache—
cluster—
compare—
coverage—
crate_model—
edge_weights—
gc—
history—
lens—
lod—
manifest—
overlay—
reachability—
rebuild—
rebuild_causes—
registry—
snapshot—
what_if—
StructDescription
TraversalHitA single result from BFS traversal.
GraphifyReaderRead-only graph reader. Builds an in-memory adjacency index from a Graphify JSON value. Construction is O(N + E). Queries are O(N + E) worst case for full BFS.
EnumDescription
GraphifyReaderErrorError type for [GraphifyReader] construction.
FunctionDescription
from_valueConstruct from a parsed serde_json::Value. Returns [GraphifyReaderError::MissingNodes] if the "nodes" key is absent or not an array.
from_refConstruct by borrowing a parsed serde_json::Value. Identical to [Self::from_value] but leaves the input intact, so a caller that must retain the raw Value (for example to serve a lexical search) does not have to clone it. The graph is ~126 MB in this repo, so that clone is the difference between ~650 MB and ~1.15 GB of peak commit.
node_countTotal number of nodes in the graph.
edge_countTotal number of undirected edges (each edge counted once). Assumption: The source graph.json contains no duplicate directed edges. If the same {source, target} pair appears more than once in the links array, this count will be inflated (each duplicate pair adds 2 to the adjacency sum). Graphify’s own export format does not produce duplicates, so this is safe in practice.
bfs_from_seedsBFS from one or more seed node IDs up to max_depth hops. direction selects callees ([Direction::Out]), callers ([Direction::In]), or the legacy undirected neighborhood ([Direction::Both]).
shortest_pathShortest path between two node IDs (BFS). Returns None if unreachable.
god_nodesNodes sorted by degree (highest first), capped at top_n. Returns (node_id, degree) pairs.
community_membersAll node IDs belonging to community_id (matched on the "community" node field).
graph_digestBLAKE3 hex digest of graph bytes. The single source of truth for graph_json_sha256 (rebuild) and lexical_ingest_sha256 (ingest) so lexical_lag comparisons are valid.
Dependency Topology, diagram 16 nodes, 5 edges: vox-cli → vox-graph-reader; vox-cli-ci → vox-graph-reader; vox-cli-research → vox-graph-reader; vox-cli-review → vox-graph-reader; vox-orchestrator-mcp → vox-graph-readervox-graph-readervox-clivox-cli-civox-cli-researchvox-cli-reviewvox-orchestrator-mcp
Diagram source
graph {
direction: right
node vox_graph_reader: "vox-graph-reader"
node vox_cli: "vox-cli"
vox_cli -> vox_graph_reader
node vox_cli_ci: "vox-cli-ci"
vox_cli_ci -> vox_graph_reader
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_graph_reader
node vox_cli_review: "vox-cli-review"
vox_cli_review -> vox_graph_reader
node vox_orchestrator_mcp: "vox-orchestrator-mcp"
vox_orchestrator_mcp -> vox_graph_reader
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-cli-ciDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-cli-reviewDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
KindSymbolSignatureSourceDescription
enumGraphifyReaderErrorpub enum GraphifyReaderErrorcrates/vox-graph-reader/src/lib.rs#L45-L48Error type for [GraphifyReader] construction.
structTraversalHitpub struct TraversalHitcrates/vox-graph-reader/src/lib.rs#L64-L73A single result from BFS traversal.
structGraphifyReaderpub struct GraphifyReadercrates/vox-graph-reader/src/lib.rs#L79-L88Read-only graph reader. Builds an in-memory adjacency index from a Graphify JSON value. Construction is O(N + E). Queries are O(N + E) worst case for full BFS.
fnfrom_valuepub fn from_value(value: serde_json::Value) -> Result<Self, GraphifyReaderError>crates/vox-graph-reader/src/lib.rs#L94-L96Construct from a parsed serde_json::Value. Returns [GraphifyReaderError::MissingNodes] if the "nodes" key is absent or not an array.
fnfrom_refpub fn from_ref(value: &serde_json::Value) -> Result<Self, GraphifyReaderError>crates/vox-graph-reader/src/lib.rs#L104-L189Construct by borrowing a parsed serde_json::Value. Identical to [Self::from_value] but leaves the input intact, so a caller that must retain the raw Value (for example to serve a lexical search) does not have to clone it. The graph is ~126 MB in this repo, so that clone is the difference between ~650 MB and ~1.15 GB of peak commit.
fnnode_countpub fn node_count(&self) -> usizecrates/vox-graph-reader/src/lib.rs#L192-L194Total number of nodes in the graph.
fnedge_countpub fn edge_count(&self) -> usizecrates/vox-graph-reader/src/lib.rs#L202-L204Total number of undirected edges (each edge counted once). Assumption: The source graph.json contains no duplicate directed edges. If the same {source, target} pair appears more than once in the links array, this count will be inflated (each duplicate pair adds 2 to the adjacency sum). Graphify’s own export format does not produce duplicates, so this is safe in practice.
fnbfs_from_seedspub fn bfs_from_seeds(crates/vox-graph-reader/src/lib.rs#L210BFS from one or more seed node IDs up to max_depth hops. direction selects callees ([Direction::Out]), callers ([Direction::In]), or the legacy undirected neighborhood ([Direction::Both]).
fnshortest_pathpub fn shortest_path(&self, from: &str, to: &str, direction: Direction) -> Option<Vec<String>>crates/vox-graph-reader/src/lib.rs#L226-L233Shortest path between two node IDs (BFS). Returns None if unreachable.
fngod_nodespub fn god_nodes(&self, top_n: usize) -> Vec<(String, usize)>crates/vox-graph-reader/src/lib.rs#L238-L247Nodes sorted by degree (highest first), capped at top_n. Returns (node_id, degree) pairs.
fncommunity_memberspub fn community_members(&self, community_id: &str) -> Vec<String>crates/vox-graph-reader/src/lib.rs#L250-L259All node IDs belonging to community_id (matched on the "community" node field).
fngraph_digestpub fn graph_digest(bytes: &[u8]) -> Stringcrates/vox-graph-reader/src/lib.rs#L264-L266BLAKE3 hex digest of graph bytes. The single source of truth for graph_json_sha256 (rebuild) and lexical_ingest_sha256 (ingest) so lexical_lag comparisons are valid.
structast::ExtractedNodepub struct ExtractedNodecrates/vox-graph-reader/src/ast.rs#L10-L14—
structast::ExtractedEdgepub struct ExtractedEdgecrates/vox-graph-reader/src/ast.rs#L17-L24—
structast::ExtractedGraphpub struct ExtractedGraphcrates/vox-graph-reader/src/ast.rs#L35-L38—
fnast::extract_astpub fn extract_ast(path: &Path, content: &str) -> ExtractedGraphcrates/vox-graph-reader/src/ast.rs#L265-L267Back-compat wrapper: bare ids. Used by ast_tests (which assert on label, unaffected).
fnast::extract_ast_in_modulepub fn extract_ast_in_module(path: &Path, content: &str, module_id: &str) -> ExtractedGraphcrates/vox-graph-reader/src/ast.rs#L271-L273Per-file AST. Definition ids and edge sources are qualified with module_id; edge targets are left bare for global resolution in rebuild.
fnast::extract_ast_in_module_with_wrapperspub fn extract_ast_in_module_with_wrappers(crates/vox-graph-reader/src/ast.rs#L278Like extract_ast_in_module, but with a voxTransport.<method> → target map so wrapper calls become declared boundary edges. invoke/callTool boundary crossings are detected from their arg0 string literal regardless of the map.
fnast_vox::extract_vox_ast_in_modulepub fn extract_vox_ast_in_module(content: &str, module_id: &str) -> ExtractedGraphcrates/vox-graph-reader/src/ast_vox.rs#L177Extract .vox declarations and call/composition/import/implements edges.
enumbfs::Directionpub enum Directioncrates/vox-graph-reader/src/bfs.rs#L9-L16Which adjacency to traverse. Both is the legacy undirected behavior.
structcache::CacheManagerpub struct CacheManagercrates/vox-graph-reader/src/cache.rs#L5-L7—
fncache::newpub fn new(cache_dir: PathBuf) -> Selfcrates/vox-graph-reader/src/cache.rs#L10-L13—
fncache::get_cached_hashpub fn get_cached_hash(&self, file_path: &Path) -> Option<String>crates/vox-graph-reader/src/cache.rs#L20-L33—
fncache::write_cachepub fn write_cache(&self, file_path: &Path, hash: &str, graph: &ExtractedGraph)crates/vox-graph-reader/src/cache.rs#L35-L44—
fncache::load_cachepub fn load_cache(&self, file_path: &Path) -> Option<ExtractedGraph>crates/vox-graph-reader/src/cache.rs#L46-L58—
structcluster::ClusterNodepub struct ClusterNodecrates/vox-graph-reader/src/cluster.rs#L5-L8—
structcluster::ClusterEdgepub struct ClusterEdgecrates/vox-graph-reader/src/cluster.rs#L11-L14—
fncluster::cluster_nodespub fn cluster_nodes(nodes: &[ClusterNode], edges: &[ClusterEdge]) -> HashMap<String, String>crates/vox-graph-reader/src/cluster.rs#L16-L62—
structcompare::ManifestSummarypub struct ManifestSummarycrates/vox-graph-reader/src/compare.rs#L5-L9A lightweight summary derived from a Graphify corpus manifest.
structcompare::ManifestDiffpub struct ManifestDiffcrates/vox-graph-reader/src/compare.rs#L13-L20The delta between two manifest summaries (old → new).
fncompare::diff_manifestspub fn diff_manifests(old: &ManifestSummary, new: &ManifestSummary) -> ManifestDiffcrates/vox-graph-reader/src/compare.rs#L23-L29Compute the signed delta from old to new.
enumcoverage::CoverageStatuspub enum CoverageStatuscrates/vox-graph-reader/src/coverage.rs#L20-L31Coverage status for a single backend node.
structcoverage::CoverageEntrypub struct CoverageEntrycrates/vox-graph-reader/src/coverage.rs#L35-L39One coverage entry per node of the requested kind.
structcoverage::CoverageReportpub struct CoverageReportcrates/vox-graph-reader/src/coverage.rs#L43-L45Result of [compute_coverage].
fncoverage::compute_coveragepub fn compute_coverage(graph: &Value, kind: &str) -> CoverageReportcrates/vox-graph-reader/src/coverage.rs#L102-L144Classify every node whose "kind" equals kind. For each such node: collect caller edges whose target is the node id; if the node carries "missing": true → [CoverageStatus::DeadEnd]; else if any caller targets it → [CoverageStatus::Surfaced]; else [CoverageStatus::OrphanBackend].
structcrate_model::CrateMetricspub struct CrateMetricscrates/vox-graph-reader/src/crate_model.rs#L14-L19Per-crate model metrics.
fncrate_model::crate_metricspub fn crate_metrics(crates/vox-graph-reader/src/crate_model.rs#L24Compute per-crate metrics from adj (crate -> its deps) and self_s (crate -> compile seconds). self_s may be empty or partial; blast_s degrades to 0 while dependents stays meaningful. Cycle-safe: uses a visited set in the reverse-BFS.
fncrate_model::build_crate_mappub fn build_crate_map(crate_graph: &Value, audit: &Value) -> Valuecrates/vox-graph-reader/src/crate_model.rs#L79-L187Build a deterministic graphify-shaped crate map from crate-graph.v1.json ({crates:{name:[deps]}}) and the crate_audit.json array (crate, compile_s [string or number], loc, layer). Node attrs: compile_s, loc, layer, fan_in, dependents, blast_s, community. When audit is empty ([]), times degrade to 0 and dependents still ranks crates by impact.
structcrate_model::CrateSummarypub struct CrateSummarycrates/vox-graph-reader/src/crate_model.rs#L191-L202Summary record for a single crate in contracts/ci/crate-build-map.v1.json.
fncrate_model::build_crate_summarypub fn build_crate_summary(crate_graph: &Value, compile_times: &HashMap<String, f64>) -> Valuecrates/vox-graph-reader/src/crate_model.rs#L213-L266Build the small, committed crate-build SSOT (contracts/ci/crate-build-map.v1.json). crate_graph is the {crates:{name:[deps]}} shape from crate-graph.v1.json. compile_times maps crate name -> self compile seconds (audit native precision; may be partial/empty). Output embeds compile_s (the periodically-refreshed INPUT) plus the DERIVED dependents/blast_s/fan_in, so the parity gate can recompute the derived fields from crate_graph + the embedded compile_s and detect drift. Deterministic: crates sorted alphabetically; blast_s rounded to whole seconds; compile_s kept at input precision.
fnedge_weights::weigh_edgespub fn weigh_edges(crates/vox-graph-reader/src/edge_weights.rs#L42For every declared dep edge in adj, count distinct target-crate symbols referenced from the source crate via resolved corpus edges. Rows are emitted for ALL adjacency edges (including zero-weight), sorted by (target_blast_s desc, symbols_used asc) — best cut candidates first.
fngc::value_scorepub fn value_score(usage: u64, recency_days: f64, churn: u64, cost_secs: f64) -> f64crates/vox-graph-reader/src/gc.rs#L7-L13Higher = more worth maintaining. usage = recent query/search hits; recency_days = days since last use; churn = node/community delta magnitude since last rebuild; cost_secs = last build wall-time. Bounded, monotone in usage and recency.
enumgc::Retentionpub enum Retentioncrates/vox-graph-reader/src/gc.rs#L16-L20—
fngc::retention_decisionpub fn retention_decision(score: f64, maintain_above: f64, discard_below: f64) -> Retentioncrates/vox-graph-reader/src/gc.rs#L23-L31score >= maintain_above → keep fresh; score < discard_below → GC; else let TTL expire.
fngc::pick_lenspub fn pick_lens(node_count: usize, threshold: usize) -> &'static strcrates/vox-graph-reader/src/gc.rs#L34-L40Data-size escape hatch: above threshold nodes, prefer the coarse modules lens (Plan B).