Module graph 

Graphs, canonically: a node and edge model in Rust, derived from the registry and the index, and projected to whatever a reader wants. Nothing here knows about Cytoscape, Mermaid or Graphviz; a rendering library is a consumer of Graph, never its shape.

Every graph is derived. None is authored: a node exists because a capability, an object or a projection exists, and an edge exists because one of them names another. A derivation that would need a file listing its own nodes belongs somewhere else.

use majordomus_cli::graph::{Builder, Node};

fn thing(id: &str) -> Node {
    Node { id: id.into(), kind: "thing".into(), label: id.to_uppercase(), summary: None,
           route: None, source: None, status: None, external: false, facts: Default::default() }
}

let mut builder = Builder::new("demo", "Demo", "Two things and the edge between them.", "example")
    .node_kind("thing", "one of the things")
    .edge_kind("names", "the source names the target");
builder.node(thing("a"));
builder.node(thing("b"));
builder.edge("a", "b", "names");
// an edge to something the derivation never added is dropped rather than dangling
builder.edge("a", "never-added", "names");

let graph = builder.finish();
assert_eq!(graph.nodes.len(), 2);
assert_eq!(graph.edges.len(), 1, "the dangling edge is gone");
assert!(graph.nodes.windows(2).all(|w| w[0].id <= w[1].id), "sorted, so two runs agree");

Determinism is a contract: the same tree and the same executable produce the same bytes. Nodes and edges are sorted by their identities, never by discovery order, and no derivation reads a clock.

Structs

Builder

A graph under construction. Adding an edge whose ends are not both present is refused by Builder::finish, not silently dropped: an edge to nothing is a derivation bug.

Edge

One directed edge. Both ends are node ids of the same graph; a derivation that cannot resolve an end adds an external node rather than a dangling edge.

Graph

A derived graph: what it is, where it came from, what its vocabularies mean, and the nodes and edges themselves.

GraphInfo

One graph the executable can derive: what it is, without deriving it.

GraphMetadata

What a reader needs to know about the graph as a whole before drawing it.

Node

One node. id is unique within the graph; kind is what the graph’s node_kinds declares it to be; route is where the Cockpit shows the thing itself, when it shows it anywhere.

NodeState

One node’s runtime state: what a process observed, never what a file declared.

ObservedGraph

The second projection of a graph: the definitions a static build publishes, and beside them what a process observes about them now.

RuntimeState

What is true of a node in a running process, and of nothing on a published page.

Unresolved

One reference that names something this repository does not hold.

Enums

Fact

One fact a node carries from its object’s front matter, in the shapes a node can hold.

Constants

COMPOSED

The id of the composed graph: the one derivation that joins every registry, and the one a generated artifact carries. Named here because the generator asks for it by id.

MAX_NODES

The most nodes a derivation emits. A graph past this is unreadable in a browser and unhelpful in a terminal; the derivation stops, says so in the metadata, and the page that shows it says so too.

Functions

capability_page

The Cockpit route of a capability.

composed_complete

The composed graph whole, every object of the index in it: what the generated docs/generated/graph.json carries and what the development-context compiler selects from. MAX_NODES bounds a graph a person is shown; a reader of the graph as data — the site’s entity pages and catalogue counts, a context selection — would take a prefix for the repository and miss whatever sorted past it.

derive

Derive one graph by id; None when no such graph exists.

derive_whole

derive(), for a graph committed as data: Err when no such graph exists or when it stopped at MAX_NODES (whole).

ids

The ids of every graph, in the order they are listed.

is_acyclic

Does the edge set form a directed acyclic graph? Kahn’s algorithm over the node set.

list

Every graph, described but not derived. Deriving all of them to list them would read the whole index for a menu.

routes

Where the Cockpit shows an object of the index, and where it shows a capability: the one place a route is built from an identity, so a page that moves moves once.

unresolved_relations

Every reference the layer declares that resolves to nothing this repository holds.

whole

A graph that is to be committed as data, refused if it is a prefix: a graph past MAX_NODES is shown to a person truncated, but a projection written to the repository that silently stopped at the bound would drop whatever sorted past it from every reader.