496 lines
17 KiB
Rust
496 lines
17 KiB
Rust
//! The knowledge graph and the algorithm flow graphs.
|
||
//!
|
||
//! Two kinds of graph are served:
|
||
//!
|
||
//! - The concept graph, authored in `content/graph/concepts.json`. Its nodes
|
||
//! are concepts and its edges are the relationships between them, such as
|
||
//! `uses`, `refines`, or `contrasts`. A node carries the identifier of the
|
||
//! document that explains it, so the frontend can open the document when a
|
||
//! node is clicked.
|
||
//! - Flow graphs, authored one per file in `content/flows/`. A flow graph
|
||
//! describes the steps of an algorithm, such as the SGP4 propagation
|
||
//! sequence, as nodes with shapes and labelled edges with branches.
|
||
//!
|
||
//! Both are plain JSON with the same shape, so one renderer on the frontend
|
||
//! handles either. The layout is computed on the frontend from the node
|
||
//! kinds; the backend only supplies the structure, which keeps the authored
|
||
//! data independent of any particular rendering.
|
||
|
||
use crate::docs::ApiCatalog;
|
||
use crate::json::{self, Value};
|
||
|
||
/// The kind of a graph node.
|
||
///
|
||
/// The kind selects how a node is drawn. The set is intentionally small so
|
||
/// that a new graph can be authored without touching the renderer.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||
pub enum NodeKind {
|
||
/// A concept in the knowledge graph.
|
||
Concept,
|
||
/// A crate of the `apsis-rs` workspace.
|
||
Crate,
|
||
/// A layer of the `apsis-rs` workspace.
|
||
Layer,
|
||
/// A step of an algorithm.
|
||
Step,
|
||
/// A decision in an algorithm, with more than one outgoing edge.
|
||
Decision,
|
||
/// A terminal step, such as a returned value or an error.
|
||
Terminal,
|
||
/// A data item, such as an element set or an epoch.
|
||
Data,
|
||
}
|
||
|
||
impl NodeKind {
|
||
/// Parses a kind name, defaulting to [`NodeKind::Concept`].
|
||
pub fn parse(name: &str) -> Self {
|
||
match name {
|
||
"crate" => Self::Crate,
|
||
"layer" => Self::Layer,
|
||
"step" => Self::Step,
|
||
"decision" => Self::Decision,
|
||
"terminal" => Self::Terminal,
|
||
"data" => Self::Data,
|
||
_ => Self::Concept,
|
||
}
|
||
}
|
||
|
||
/// Returns the kind name as it is written in the data.
|
||
pub const fn name(self) -> &'static str {
|
||
match self {
|
||
Self::Concept => "concept",
|
||
Self::Crate => "crate",
|
||
Self::Layer => "layer",
|
||
Self::Step => "step",
|
||
Self::Decision => "decision",
|
||
Self::Terminal => "terminal",
|
||
Self::Data => "data",
|
||
}
|
||
}
|
||
}
|
||
|
||
/// A node of a graph.
|
||
#[derive(Debug, Clone)]
|
||
pub struct Node {
|
||
/// Identifier, unique within the graph.
|
||
pub id: String,
|
||
/// Display label in English.
|
||
pub label: String,
|
||
/// Display label in Chinese, or `None` when the label is a name that is
|
||
/// written the same way in both languages.
|
||
pub label_zh: Option<String>,
|
||
/// Kind, selecting how the node is drawn.
|
||
pub kind: NodeKind,
|
||
/// Chapter or group the node belongs to, used for colouring.
|
||
pub group: String,
|
||
/// One sentence description in English.
|
||
pub summary: String,
|
||
/// One sentence description in Chinese, when one is authored.
|
||
pub summary_zh: Option<String>,
|
||
/// Identifier of the document that explains the node, when one exists.
|
||
pub document: Option<String>,
|
||
/// Identifier of the interface item, when the node names one.
|
||
pub api: Option<String>,
|
||
}
|
||
|
||
/// An edge of a graph.
|
||
#[derive(Debug, Clone)]
|
||
pub struct Edge {
|
||
/// Source node identifier.
|
||
pub source: String,
|
||
/// Target node identifier.
|
||
pub target: String,
|
||
/// Relationship name, such as `uses`.
|
||
pub kind: String,
|
||
/// Optional label drawn on the edge, in English.
|
||
pub label: Option<String>,
|
||
/// The same label in Chinese, when one is authored.
|
||
pub label_zh: Option<String>,
|
||
}
|
||
|
||
/// A graph, either the concept graph or one flow graph.
|
||
#[derive(Debug, Clone)]
|
||
pub struct Graph {
|
||
/// Identifier of the graph.
|
||
pub id: String,
|
||
/// Display title in English.
|
||
pub title: String,
|
||
/// Display title in Chinese, when one is authored.
|
||
pub title_zh: Option<String>,
|
||
/// One sentence description in English.
|
||
pub summary: String,
|
||
/// One sentence description in Chinese, when one is authored.
|
||
pub summary_zh: Option<String>,
|
||
/// Nodes.
|
||
pub nodes: Vec<Node>,
|
||
/// Edges.
|
||
pub edges: Vec<Edge>,
|
||
}
|
||
|
||
impl Graph {
|
||
/// Returns a node by identifier.
|
||
///
|
||
/// Used to resolve the endpoints of an edge, which is what the check
|
||
/// for a dangling edge does.
|
||
#[allow(dead_code)]
|
||
pub fn node(&self, id: &str) -> Option<&Node> {
|
||
self.nodes.iter().find(|node| node.id == id)
|
||
}
|
||
|
||
/// Returns the edges that leave a node.
|
||
#[allow(dead_code)]
|
||
pub fn outgoing(&self, id: &str) -> impl Iterator<Item = &Edge> {
|
||
self.edges.iter().filter(move |edge| edge.source == id)
|
||
}
|
||
|
||
/// Returns the identifiers of every edge endpoint that is not a node.
|
||
///
|
||
/// The authored graph data is checked with this at startup, so a broken
|
||
/// edge is reported rather than drawn to nowhere.
|
||
#[allow(dead_code)]
|
||
pub fn dangling_edges(&self) -> Vec<(String, String)> {
|
||
self.edges
|
||
.iter()
|
||
.filter(|edge| self.node(&edge.source).is_none() || self.node(&edge.target).is_none())
|
||
.map(|edge| (edge.source.clone(), edge.target.clone()))
|
||
.collect()
|
||
}
|
||
|
||
/// Returns the distinct groups in the order they first appear.
|
||
pub fn groups(&self) -> Vec<String> {
|
||
let mut groups = Vec::new();
|
||
for node in &self.nodes {
|
||
if !groups.iter().any(|group| group == &node.group) {
|
||
groups.push(node.group.clone());
|
||
}
|
||
}
|
||
groups
|
||
}
|
||
}
|
||
|
||
/// The concept graph together with the algorithm flow graphs.
|
||
#[derive(Debug)]
|
||
pub struct GraphSet {
|
||
/// The concept knowledge graph.
|
||
pub concepts: Graph,
|
||
/// The flow graphs, in title order.
|
||
pub flows: Vec<Graph>,
|
||
}
|
||
|
||
impl GraphSet {
|
||
/// Returns a flow graph by identifier.
|
||
pub fn flow(&self, id: &str) -> Option<&Graph> {
|
||
self.flows.iter().find(|graph| graph.id == id)
|
||
}
|
||
}
|
||
|
||
/// Loads the concept graph and every flow graph from the embedded content.
|
||
pub fn load_graph() -> GraphSet {
|
||
let concepts = crate::docs::content::get("graph/concepts.json")
|
||
.and_then(parse_graph)
|
||
.unwrap_or_else(|| Graph {
|
||
id: "concepts".to_string(),
|
||
title: "Concepts".to_string(),
|
||
title_zh: Some("概念图谱".to_string()),
|
||
summary: String::new(),
|
||
summary_zh: None,
|
||
nodes: Vec::new(),
|
||
edges: Vec::new(),
|
||
});
|
||
|
||
let mut flows: Vec<Graph> = crate::docs::content::list("flows/", ".json")
|
||
.into_iter()
|
||
.filter_map(|(_, text)| parse_graph(text))
|
||
.collect();
|
||
flows.sort_by(|left, right| left.title.cmp(&right.title));
|
||
|
||
GraphSet { concepts, flows }
|
||
}
|
||
|
||
/// Parses a graph from its JSON representation.
|
||
///
|
||
/// Returns `None` when the identifier is missing, because a graph without an
|
||
/// identifier cannot be addressed.
|
||
pub fn parse_graph(text: &str) -> Option<Graph> {
|
||
let value = json::parse(text).ok()?;
|
||
let id = value.get("id")?.as_str()?.to_string();
|
||
let title = value
|
||
.get("title")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or(&id)
|
||
.to_string();
|
||
let summary = value
|
||
.get("summary")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or_default()
|
||
.to_string();
|
||
let title_zh = text_field(&value, "title_zh");
|
||
let summary_zh = text_field(&value, "summary_zh");
|
||
|
||
let nodes = value
|
||
.get("nodes")
|
||
.map(Value::as_array)
|
||
.unwrap_or_default()
|
||
.iter()
|
||
.filter_map(|node| {
|
||
Some(Node {
|
||
id: node.get("id")?.as_str()?.to_string(),
|
||
label: node
|
||
.get("label")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or_else(|| node.get("id").and_then(Value::as_str).unwrap_or(""))
|
||
.to_string(),
|
||
label_zh: text_field(node, "label_zh"),
|
||
kind: NodeKind::parse(
|
||
node.get("kind")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or("concept"),
|
||
),
|
||
group: node
|
||
.get("group")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or("general")
|
||
.to_string(),
|
||
summary: node
|
||
.get("summary")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or_default()
|
||
.to_string(),
|
||
summary_zh: text_field(node, "summary_zh"),
|
||
document: node
|
||
.get("document")
|
||
.and_then(Value::as_str)
|
||
.map(str::to_string),
|
||
api: node.get("api").and_then(Value::as_str).map(str::to_string),
|
||
})
|
||
})
|
||
.collect();
|
||
|
||
let edges = value
|
||
.get("edges")
|
||
.map(Value::as_array)
|
||
.unwrap_or_default()
|
||
.iter()
|
||
.filter_map(|edge| {
|
||
Some(Edge {
|
||
source: edge.get("source")?.as_str()?.to_string(),
|
||
target: edge.get("target")?.as_str()?.to_string(),
|
||
kind: edge
|
||
.get("kind")
|
||
.and_then(Value::as_str)
|
||
.unwrap_or("relates")
|
||
.to_string(),
|
||
label: edge
|
||
.get("label")
|
||
.or_else(|| edge.get("label_en"))
|
||
.and_then(Value::as_str)
|
||
.map(str::to_string),
|
||
label_zh: edge
|
||
.get("label_zh")
|
||
.and_then(Value::as_str)
|
||
.map(str::to_string),
|
||
})
|
||
})
|
||
.collect();
|
||
|
||
Some(Graph {
|
||
id,
|
||
title,
|
||
title_zh,
|
||
summary,
|
||
summary_zh,
|
||
nodes,
|
||
edges,
|
||
})
|
||
}
|
||
|
||
/// Returns a member of a JSON object as an owned string, when it is a
|
||
/// non-empty string.
|
||
fn text_field(value: &Value, key: &str) -> Option<String> {
|
||
value
|
||
.get(key)
|
||
.and_then(Value::as_str)
|
||
.filter(|text| !text.is_empty())
|
||
.map(str::to_string)
|
||
}
|
||
|
||
/// Builds the crate structure graph from the interface catalog.
|
||
///
|
||
/// The nodes are the crates, grouped by layer, and the edges follow the
|
||
/// layer order that `apsis-rs` enforces:
|
||
/// `foundation -> physics -> orbit -> rf -> network -> ops -> sim`. A layer
|
||
/// edge is drawn from each layer to the next one that the enabled feature
|
||
/// set contains, which is what the dependency rule means in practice.
|
||
pub fn crate_structure(catalog: &ApiCatalog) -> Graph {
|
||
let layers = [
|
||
"foundation",
|
||
"physics",
|
||
"orbit",
|
||
"rf",
|
||
"network",
|
||
"ops",
|
||
"sim",
|
||
];
|
||
let mut nodes = Vec::new();
|
||
let mut edges = Vec::new();
|
||
let mut present: Vec<&str> = Vec::new();
|
||
|
||
for krate in &catalog.crates {
|
||
// A crate that belongs to no layer has no place in a diagram of the
|
||
// layer structure: the workspace facade re-exports every layer and
|
||
// would sit under a layer it is not part of. It stays on the index,
|
||
// where it is a crate like any other.
|
||
if krate.layer.is_empty() {
|
||
continue;
|
||
}
|
||
nodes.push(Node {
|
||
id: krate.name.clone(),
|
||
label: krate.name.clone(),
|
||
label_zh: None,
|
||
kind: NodeKind::Crate,
|
||
group: krate.layer.clone(),
|
||
summary: crate_summary_zh(&krate.name)
|
||
.unwrap_or_else(|| krate.summary.lines().next().unwrap_or_default().to_string()),
|
||
summary_zh: None,
|
||
document: None,
|
||
api: None,
|
||
});
|
||
edges.push(Edge {
|
||
source: krate.name.clone(),
|
||
target: krate.layer.clone(),
|
||
kind: "belongs-to".to_string(),
|
||
label: None,
|
||
label_zh: None,
|
||
});
|
||
if !present.contains(&krate.layer.as_str()) {
|
||
present.push(match layers.iter().find(|layer| **layer == krate.layer) {
|
||
Some(layer) => layer,
|
||
None => "foundation",
|
||
});
|
||
}
|
||
}
|
||
|
||
// One node per layer that the catalog contains, so the graph describes
|
||
// this build rather than the whole workspace.
|
||
for layer in layers {
|
||
if !present.contains(&layer) {
|
||
continue;
|
||
}
|
||
nodes.push(Node {
|
||
id: layer.to_string(),
|
||
label: layer.to_string(),
|
||
label_zh: None,
|
||
kind: NodeKind::Layer,
|
||
group: layer.to_string(),
|
||
summary: format!(
|
||
"The {layer} layer. A layer may use the layers to its left and no layer to its right."
|
||
),
|
||
summary_zh: Some(format!(
|
||
"{layer} 层。每一层可以依赖其左侧的层，不能依赖其右侧的层。"
|
||
)),
|
||
document: Some("architecture-apsis-rs".to_string()),
|
||
api: None,
|
||
});
|
||
}
|
||
|
||
// The dependency rule, drawn between the layers that are present.
|
||
for window in layers.windows(2) {
|
||
let (lower, upper) = (window[0], window[1]);
|
||
if present.contains(&lower) && present.contains(&upper) {
|
||
edges.push(Edge {
|
||
source: lower.to_string(),
|
||
target: upper.to_string(),
|
||
kind: "depends".to_string(),
|
||
label: Some(format!("{lower} enables {upper}")),
|
||
label_zh: Some(format!("{lower} 启用 {upper}")),
|
||
});
|
||
}
|
||
}
|
||
|
||
Graph {
|
||
id: "crates".to_string(),
|
||
title: "apsis-rs crate structure".to_string(),
|
||
title_zh: Some("apsis-rs crate 结构".to_string()),
|
||
summary: "Workspace crates grouped by layer; edges follow the one way dependency rule."
|
||
.to_string(),
|
||
summary_zh: Some("按层分组的 workspace crate；边表示单向依赖规则。".to_string()),
|
||
nodes,
|
||
edges,
|
||
}
|
||
}
|
||
|
||
/// Returns the Chinese summary of a crate, when one is authored.
|
||
///
|
||
/// The crate name is the key, so the table stays beside the graph rather
|
||
/// than in a separate translation file.
|
||
fn crate_summary_zh(name: &str) -> Option<String> {
|
||
let text = match name {
|
||
"apsis-core" => "共享基础类型：通用错误、常量与单位标记 trait。",
|
||
"apsis-units" => "物理量强类型 newtype：长度、时间、频率、角度、温度。",
|
||
"apsis-math" => "无依赖线性代数：三维矢量、三阶矩阵、四元数。",
|
||
"apsis-macros" => "支撑 workspace 的宏。",
|
||
"apsis-time" => "时间尺度、历元与日历转换。",
|
||
"apsis-leap" => "用于 UTC 转换的内嵌闰秒表。",
|
||
"apsis-coord" => "在类型中携带参考系的位置表示。",
|
||
"apsis-geodesy" => "参考椭球与大地坐标计算。",
|
||
"apsis-frames" => "参考系定义与地固系旋转。",
|
||
"apsis-tle" => "两行元素集解析。",
|
||
"apsis-sgp4" => "SGP4 与 SDP4 解析轨道传播器。",
|
||
"apsis-kepler" => "开普勒轨道元素与二体问题。",
|
||
"apsis-ephemeris" => "星历采样与插值。",
|
||
"apsis-maneuver" => "脉冲与有限推力轨道机动模型。",
|
||
"apsis-orbit" => "轨道层统一入口：元素、传播与机动。",
|
||
_ => return None,
|
||
};
|
||
Some(text.to_string())
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
const SAMPLE: &str = r#"{
|
||
"id": "concepts",
|
||
"title": "Concepts",
|
||
"summary": "The concept map.",
|
||
"nodes": [
|
||
{"id": "sgp4", "label": "SGP4", "kind": "concept", "group": "propagation", "summary": "Analytical model.", "document": "sgp4"},
|
||
{"id": "tle", "label": "TLE", "kind": "data", "group": "propagation", "summary": "Element set.", "document": "tle"}
|
||
],
|
||
"edges": [
|
||
{"source": "sgp4", "target": "tle", "kind": "consumes", "label": "reads"}
|
||
]
|
||
}"#;
|
||
|
||
#[test]
|
||
fn parses_a_graph() {
|
||
let graph = parse_graph(SAMPLE).unwrap();
|
||
assert_eq!(graph.id, "concepts");
|
||
assert_eq!(graph.nodes.len(), 2);
|
||
assert_eq!(graph.edges.len(), 1);
|
||
assert_eq!(graph.node("sgp4").unwrap().kind, NodeKind::Concept);
|
||
assert_eq!(graph.node("tle").unwrap().kind, NodeKind::Data);
|
||
assert_eq!(graph.outgoing("sgp4").count(), 1);
|
||
assert!(graph.dangling_edges().is_empty());
|
||
assert_eq!(graph.groups(), vec!["propagation"]);
|
||
}
|
||
|
||
#[test]
|
||
fn reports_dangling_edges() {
|
||
let text = r#"{"id":"x","nodes":[],"edges":[{"source":"a","target":"b","kind":"k"}]}"#;
|
||
let graph = parse_graph(text).unwrap();
|
||
assert_eq!(graph.dangling_edges().len(), 1);
|
||
}
|
||
|
||
#[test]
|
||
fn crate_structure_follows_the_layer_order() {
|
||
let catalog = crate::docs::load_api_catalog();
|
||
let graph = crate_structure(&catalog);
|
||
assert!(!graph.nodes.is_empty());
|
||
assert!(graph.dangling_edges().is_empty());
|
||
for edge in &graph.edges {
|
||
assert_ne!(edge.source, edge.target);
|
||
}
|
||
}
|
||
}
|