Graph Data Structures

:::info For engine extenders and JSON shape When using the closed-source engine via arxo-loader or the FFI, you receive a single JSON string; you do not get direct access to these Rust graph types. This page documents the structure of the data the engine produces (and that may appear in the result JSON or in internal/plugin code). For the public API see Rust API and FFI API. The DataStore page describes how plugins access these graphs inside the engine. :::

Graph Data Structures

The engine produces several graph structures. When extending the engine you access them via the DataStore. All graph types are defined in arxo-types (MIT-licensed).

NodeId

File-level nodes are identified by NodeId: an interned file path (Arc<str>). Use it as a key for lookups and as source/target in edges.

use arxo_types::core::types::NodeId;

let id = NodeId::from("src/main.ts");
assert_eq!(id.as_str(), "src/main.ts");

Import Graph

ImportGraph represents module/file dependencies: who imports whom.

Node metadata

Each node is a NodeMetadata:

Field	Type	Description
id	NodeId	File path identifier
path	PathBuf	File path
group	Option<String>	Group label (from grouping)
layer	Option<String>	Architecture layer, if configured
size	usize	Size metric (e.g. lines)
member_ids	Option<Vec<NodeId>>	Member file IDs when grouped
package_name	Option<String>	Package name when in a workspace
package_root	Option<PathBuf>	Package root path

Edge types

Edges carry EdgeData with an EdgeType:

Variant	Description
Import	Normal import
Reexport	Re-export from another module
DynamicImport	Dynamic import (e.g. import())
TypeOnly	Type-only import (e.g. import type)
Require	CommonJS-style require()
BarrelImport	Barrel file re-export
SideEffect	Side-effect-only import

EdgeData also has weight (e.g. for metrics) and optional original_import (raw specifier).

API summary

use arxo_types::data::import_graph::{ImportGraph, NodeMetadata};

// Counts
graph.node_count();
graph.edge_count();

// Lookup by NodeId
graph.get_node(&node_id) -> Option<&NodeMetadata>

// Petgraph access (for iteration, algorithms)
graph.inner()           -> &Graph<NodeMetadata, EdgeData, Directed>
graph.node_indices()    -> Iterator<NodeIndex>
graph.node_weight(idx) -> Option<&NodeMetadata>
graph.neighbors(idx)   -> Neighbors
graph.edges(idx)       -> Edges

Use graph.inner() with petgraph for algorithms (e.g. DFS, SCC). The engine also exposes a precomputed SCC DAG via the DataStore for cycle analysis.

---

Call Graph

CallGraph represents file-to-file call relationships: which file’s code calls into which other file.

Edge types and resolution

Each edge has CallEdgeData:

Field	Type	Description
edge_type	CallEdgeType	Kind of call
is_precise	bool	Resolved to a single target
confidence	f64	0.0–1.0 resolution confidence
resolution_method	ResolutionMethod	How the target was resolved
call_count	usize	Number of call sites
source_file	NodeId	File where the call appears

CallEdgeType:

Variant	Description
DirectCall	Direct function call
MethodCall	Method call on an object
Constructor	Constructor/new call
HigherOrder	Callback passed to another function

ResolutionMethod (examples): LocalDefinition, DirectImport, RustAnalyzer, Inheritance, SamePackage, TypeIndex, GlobalNameMatch, etc. Each has a confidence() (e.g. 1.0 for LocalDefinition, lower for heuristics). You can filter edges by min_confidence in configuration.

API summary

use arxo_types::data::call_graph::{CallGraph, CallEdgeData, CallEdgeType, ResolutionMethod};

graph.node_count();
graph.edge_count();
graph.get_node(&node_id) -> Option<&NodeMetadata>
graph.inner() -> &Graph<..., CallEdgeData, Directed>

The DataStore also exposes call reachability, call dependencies, and call SCC DAG for transitive and cycle analysis.

---

Entity Graph

EntityGraph is a function/class/variable-level call graph: nodes are entities (e.g. functions, classes), not files.

Entity IDs

Entity IDs are strings: "file_id::symbol" (e.g. "src/utils.ts::formatDate"). Use entity_id(file_id, symbol) to build them.

Node metadata

EntityNodeMetadata:

Field	Type	Description
id	EntityId	file_id::symbol
file_id	NodeId	Containing file
symbol	String	Symbol name
kind	EntityKind	Entity kind

EntityKind:

Variant	Description
Function	Function or method
Class	Class
Variable	Variable
Constant	Constant
Module	Module-level (e.g. top-level script)
Unknown	Could not classify

Edge data

EntityEdgeData mirrors call graph edge data: edge_type, is_precise, confidence, resolution_method, call_count, source_file.

API summary

use arxo_types::data::entity_graph::{
    EntityGraph, EntityId, EntityKind, EntityNodeMetadata,
    entity_id,
};

let eid = entity_id(&node_id, "formatDate");
graph.get_entity(&eid) -> Option<&EntityNodeMetadata>
graph.node_count();
graph.edge_count();
graph.inner() -> &Graph<EntityNodeMetadata, EntityEdgeData, Directed>

---

Type Graph

TypeGraph represents type relationships: inheritance, implementations, type aliases.

Type IDs

Type IDs are strings: "file_id::TypeName". Use type_id(file_id, type_name) to build them.

Node metadata

TypeNodeMetadata:

Field	Type	Description
id	TypeId	file_id::TypeName
file_id	NodeId	Declaring file
name	String	Type name
qualified_name	Option<String>	Fully qualified (e.g. Java pkg.Class)
kind	TypeKind	Kind of type
is_abstract	bool	Abstract type

TypeKind:

Variant	Description
Class	Class
Interface	Interface
Trait	Trait (e.g. Rust)
Struct	Struct
Enum	Enum
Record	Record/object type
TypeAlias	Type alias
Unknown	Could not classify

Edge types

TypeEdgeData has TypeEdgeType and weight:

Variant	Description	Typical weight
Extends	Class extends class	1.0
Implements	Class implements interface	0.9
TraitImpl	impl Trait for Type (Rust)	0.85
TypeAlias	type Foo = Bar	0.5
GenericBound	T: Trait, T extends Foo	0.3

API summary

use arxo_types::data::type_graph::{
    TypeGraph, TypeId, TypeKind, TypeNodeMetadata, TypeEdgeType,
    type_id,
};

graph.get_type(&type_id) -> Option<&TypeNodeMetadata>
graph.node_count();
graph.edge_count();
graph.inner() -> &Graph<TypeNodeMetadata, TypeEdgeData, Directed>

---

Serialization

Graphs support serialization for caching and transport. The engine uses to_serializable() / from_serializable() (or equivalent) for bincode cache; the same types are JSON-serializable via serde for the report and FFI output.

Next steps

• DataStore — How to obtain and use these graphs in your code
• Configuration — Grouping and call graph confidence
• Concepts: Graphs — High-level overview of graphs in Arxo