Crate pedant_graph

Expand description

Deterministic, language-tagged code topology built from one snapshot-bound symbol-resolution result.

The graph separates three relations a consumer would otherwise have to reconstruct itself: logical containment, source association, and certainty-carrying reference and dependency edges. It consumes already validated in-memory facts and widens nothing: it loads no project, reads no file, parses no source, invokes no build tool, and evaluates no policy.

The snapshot must be the one the resolution was validated against, and a successful build serializes to the compact version-1 JSON described below through serde_json::to_string.

pedant_graph::build_rust_graph(snapshot, resolution)

§A second language behind a feature

The default build projects Rust. Selecting the go feature adds the Go adapter beside it: build_go_graph and build_go_graph_with_limits — named here rather than linked, because the default build has no such item — take a Go snapshot and the resolution validated against it and answer the same CodeGraph the Rust builders answer, through the same checked assembler. The feature forwards to pedant-core/go-resolution and nothing else, so a build without it links no Go grammar through this crate, and the optional graph cache below stays Rust-only either way.

§The version-1 shape

One object with six keys, in this order:

schema_version: the integer CodeGraph::SCHEMA_VERSION.
tier: "syntactic" or "semantic", taken from the supplied report.
nodes: id, language, name, kind, location. kind is tagged by category; location is null or tagged by kind as file or span.
containment: parent and child, sorted by child then parent.
references: id, source, language, kind, text, span, gaps, edges, in mint order.
edges: id, source, target, kind, certainty, origin, in mint order. origin is tagged by kind as reference or dependency.

Every identity is an integer equal to the record’s position in its own slice, and every graph-owned enum is one lower-snake-case string. No key states a coordinate, a size, a color, or any other layout choice.

§Bounded queries over a built graph

A caller states which edges to admit and what the answer may cost, then asks. Nothing about the graph changes.

let analysis = GraphAnalysis::new(
    graph,
    GraphEdgeSelection::code_relations(),
    GraphAnalysisLimits::new(100_000, 400_000, 8, 50_000_000),
)?;
analysis.neighbors(node, 2, GraphDirection::Incoming)

The same view answers the derived questions. Cohesion, modularity, affinity, and boundary-crossing cycles are evidence about the partition the graph declares; layout metadata is that evidence beside the degrees and weights a ranker or a renderer would otherwise measure itself.

let analysis = GraphAnalysis::new(
    graph,
    GraphEdgeSelection::code_relations(),
    GraphAnalysisLimits::new(100_000, 400_000, 8, 50_000_000),
)?;
let evidence = analysis.divergence();
for module in evidence.cohesion() {
    let _ = (module.root(), module.internal_edges(), module.score());
}
analysis.layout_assist()

§Optional bounded reuse

A caller that inspects successive repository states may keep a cache of the work it already admitted. The cache builds nothing of its own: it takes the same snapshot and validated resolution the direct builder takes, returns the same graph, and states how many values it may retain. Zero disables a category without disabling the computation behind it.

let mut cache = GraphCache::new(GraphCacheLimits::new(4_096, 8, 4, 256));
let held = cache.build_rust_graph(snapshot, resolution, GraphLimits::default())?;
let analysis = held.analyze(
    GraphEdgeSelection::code_relations(),
    GraphAnalysisLimits::new(100_000, 400_000, 8, 50_000_000),
)?;
let _ = (analysis.divergence(), cache.stats().exact_graph_hits());

The returned handles are the caller’s: a graph, an analysis, and every product they answer with stay valid and immutable after eviction, after clear, and after the cache itself is dropped. Nothing about the version-1 object above changes, and no cache value is serialized.

Structs§

BetweennessCentrality: How much of the selected topology’s shortest routing passes through one node.
BoundaryCrossingComponent: One cycle whose members are declared in more than one partition.
CachedCodeGraph: One immutable graph, shared with the cache that produced it.
CachedGraphAnalysis: One shared analysis over one cached graph.
CodeGraph: One deterministic, language-tagged code topology.
ComponentIdKind: Marker distinguishing component identities from the graph’s own identities.
CondensationEdge: Every selected edge between one ordered pair of components.
CondensationGraph: One selected topology with every component contracted to a single node.
ContainmentEdge: One logical-ownership edge between a parent node and the node it owns.
DeclaredModulePartition: Which container owns each node, and which nodes each container owns.
DegreeCentrality: How many selected edges arrive at and leave one node.
DependencyEvidence: What one build-unit dependency edge retained from its declaration.
EdgeIdKind: Marker distinguishing edge identities from the other identity kinds.
GraphAnalysis: One borrowed graph, the selection applied to it, and the indexes that selection produced.
GraphAnalysisLimits: How much work one analysis of one graph may cost.
GraphCache: A caller-owned cache of graphs built from complete resolution claims.
GraphCacheLimits: The retention ceilings one cache is bounded by.
GraphCacheStats: A copied reading of one cache’s cumulative activity.
GraphComponent: One set of nodes that all reach each other.
GraphComponents: Every component of one selected topology, and which one each node belongs to.
GraphDivergence: What one selected topology says about the partition its graph declares.
GraphEdge: One directed relation between two graph nodes.
GraphEdgeSelection: The edge kinds and certainties one analysis admits.
GraphId: One dense u32 position whose marker fixes the collection it addresses.
GraphLimits: How many nodes, reference records, and edges one build may produce.
GraphNeighbor: One reached node and how many selected steps away it is.
GraphNode: One structural entity of a code graph.
GraphPath: One directed route over selected outgoing edges.
GraphReference: One naming site, its copied evidence, and the edges its candidates produced.
GraphSubgraph: One selection into the raw graph, never a second graph.
LayoutAssistMetadata: Every admitted node and every selected edge, described once.
LayoutEdgeMetadata: One selected edge, restated with both of its ends and its own evidence.
LayoutNodeMetadata: What one node is, is inside, and measures as.
MisplacementCandidate: One symbol’s selected edges into one partition other than its own.
ModuleCohesion: How much of one partition’s outgoing traffic stays inside it.
NodeIdKind: Marker distinguishing node identities from the other identity kinds.
ReferenceIdKind: Marker distinguishing reference identities from the other identity kinds.

Enums§

GraphAnalysisError: A refusal taken while building or querying one analysis.
GraphBuildError: A refusal taken while projecting one resolution into a graph.
GraphCertainty: How much an edge is known.
GraphCollection: Which graph collection a ceiling addresses.
GraphDependencyKind: Which dependency table declared a build-unit edge.
GraphDirection: Which way a neighborhood or subgraph walk follows a selected edge.
GraphEdgeKind: What relation an edge states.
GraphEdgeOrigin: Why an edge exists. No edge exists without one of these.
GraphNodeKind: What kind of entity a node is.
GraphNodeLocation: Where a node’s bytes sit, when it has any.
GraphReferenceKind: What a naming site denotes at the graph layer.

Functions§

build_rust_graph: Project one snapshot-bound Rust resolution under the default ceilings.
build_rust_graph_with_limits: Project one snapshot-bound Rust resolution under caller-chosen ceilings.

Type Aliases§

GraphComponentId: A component’s dense identity within one GraphComponents.
GraphEdgeId: An edge’s dense identity within one crate::CodeGraph.
GraphNodeId: A node’s dense identity within one crate::CodeGraph.
GraphReferenceId: A reference record’s dense identity within one crate::CodeGraph.