Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
//! **The README's graph states figures, so the figures are re-derived.**
//!
//! `docs/assets/knowledge-graph.svg` is drawn from a real certified run over
//! `benchmark/reference/ies-core.ttl` and prints the counts in its legend:
//! how many triples were asserted, how many the fixpoint derived, and the
//! rules that derived them. It is the first picture on the README.
//!
//! Nothing about an SVG stops those drifting from the engine. So this runs the
//! reasoner over the same ontology and compares. The picture is regenerated by
//! `docs/assets/knowledge-graph.py` from a certificate directory, and this is
//! what makes forgetting to regenerate it a failure rather than a slow lie.
//!
//! The drawn EDGE counts are deliberately not re-derived here. They are a
//! projection of the certificate onto `rdfs:subClassOf`, which the generator
//! computes and this test would have to reimplement to check, and a second
//! implementation of the same projection agreeing with the first says very
//! little. The asserted and derived totals are the load-bearing numbers and
//! they come straight from the engine.
use open_ontologies::graph::GraphStore;
use open_ontologies::reason::{InferenceTarget, Reasoner};
use std::path::PathBuf;
use std::sync::Arc;
fn repo() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
}
fn svg() -> String {
std::fs::read_to_string(repo().join("docs").join("assets").join("knowledge-graph.svg"))
.expect("read knowledge-graph.svg")
}
/// The integer the legend writes between `prefix` and `suffix`.
///
/// Anchored on both sides on purpose. Searching for a bare word finds the
/// first one in the file, and the first "derived" is in the `aria-label`,
/// which describes the picture in prose and carries no number. A loose anchor
/// made this test fail against a correct SVG.
fn drawn(prefix: &str, suffix: &str) -> u64 {
let s = svg();
let at = s
.find(prefix)
.unwrap_or_else(|| panic!("the legend no longer says {prefix:?}"));
let rest = &s[at + prefix.len()..];
let digits: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect();
assert!(!digits.is_empty(), "no number after {prefix:?}");
let after = &rest[digits.len()..];
assert!(
after.starts_with(suffix),
"expected {suffix:?} after the number following {prefix:?}, found {:?}",
&after[..suffix.len().min(after.len())]
);
digits.parse().expect("digits parse")
}
#[test]
fn the_graph_states_the_counts_a_real_run_produces() {
let ttl = std::fs::read_to_string(repo().join("benchmark").join("reference").join("ies-core.ttl"))
.expect("read ies-core.ttl");
let graph = Arc::new(GraphStore::new());
graph.load_turtle(&ttl, None).expect("ies-core.ttl must parse");
let dir = std::env::temp_dir().join(format!("oo-kg-asset-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("scratch dir");
let json = Reasoner::run_full(
&graph,
"rdfs",
false,
InferenceTarget::DefaultGraph,
Some(dir.as_path()),
)
.expect("reason over ies-core.ttl");
let r: serde_json::Value = serde_json::from_str(&json).expect("report is JSON");
let cert = &r["certificate"];
let asserted = cert["asserted"].as_u64().expect("certificate records asserted");
let derived = cert["derivations"].as_u64().expect("certificate records derivations");
assert_eq!(
drawn("out of ", " asserted triples"),
asserted,
"the graph says {} asserted triples and the engine produced {asserted}. Regenerate it: \
python3 docs/assets/knowledge-graph.py <dir>/asserted.tsv <dir>/derivations.tsv \
docs/assets/knowledge-graph.svg",
drawn("out of ", " asserted triples")
);
assert_eq!(
drawn("asserted triples and ", " derived"),
derived,
"the graph says {} derived and the engine produced {derived}. Regenerate it the same way.",
drawn("asserted triples and ", " derived")
);
// And the rules named in the legend are rules the run actually used.
let by_rule = cert["by_rule"].as_object().expect("certificate records by_rule");
let text = svg();
for (rule, count) in by_rule {
let claim = format!("{rule} x{count}");
assert!(
text.contains(&claim),
"the run used {claim} and the legend does not say so. A legend naming some of the \
rules is worse than one naming none, because a reader cannot tell which"
);
}
let _ = std::fs::remove_dir_all(&dir);
}
// ── The picture has to MOVE, and its first frame has to be the picture ──
//
// This file used to check only the counts, so it stayed green for as long as
// the asset was a still image. The README calls it a graph of what was asserted,
// what was derived and what was refused, and those are three things that happen
// in an order; a still frame shows them side by side as though they were one
// kind of fact. The counts were right and the argument was missing.
/// Every animation element and the element it animates.
///
/// `<animateMotion>` counts. The particles travelling along the certified and
/// rejected links are the Studio view's signature motion, they are animations
/// by every meaning of the word, and a gate that ignored them would report the
/// asset as barely animated while 265 things moved on it.
fn animation_elements(s: &str) -> Vec<(String, String)> {
let mut out = animate_blocks(s);
out.extend(motion_blocks(s));
out
}
fn motion_blocks(s: &str) -> Vec<(String, String)> {
let mut out = vec![];
for (i, _) in s.match_indices("<animateMotion ") {
let tag_end = s[i..].find('>').map(|e| i + e + 1).unwrap_or(s.len());
out.push((String::new(), s[i..tag_end].to_string()));
}
out
}
fn animate_blocks(s: &str) -> Vec<(String, String)> {
// (the parent element's opening tag, the <animate ...> tag)
let mut out = vec![];
for (i, _) in s.match_indices("<animate ") {
let tag_end = s[i..].find('>').map(|e| i + e + 1).unwrap_or(s.len());
let animate = s[i..tag_end].to_string();
// The enclosing element is the nearest preceding opening tag that is
// not itself an <animate>. An element may carry several, and the second
// one's parent is the element, not its sibling.
let mut cut = i;
let parent = loop {
let before = &s[..cut];
let Some(open) = before.rfind('<') else { break None };
if before[open..].starts_with("<animate") {
cut = open;
continue;
}
let open_end = before[open..].find('>').map(|e| open + e + 1).unwrap_or(cut);
break Some(before[open..open_end].to_string());
};
let Some(parent) = parent else { continue };
out.push((parent, animate));
}
out
}
fn attr(tag: &str, name: &str) -> Option<String> {
let pat = format!("{name}=\"");
let i = tag.find(&pat)? + pat.len();
let j = tag[i..].find('"')? + i;
Some(tag[i..j].to_string())
}
#[test]
fn the_graph_is_animated_and_the_animation_loops() {
let s = svg();
let blocks = animation_elements(&s);
assert!(
blocks.len() >= 10,
"the asset carries {} animations; it is meant to play four beats and a still \
picture cannot make the argument the README makes with it",
blocks.len()
);
for (_, a) in &blocks {
assert_eq!(
attr(a, "repeatCount").as_deref(),
Some("indefinite"),
"an animation that runs once is a slideshow a reader arrives after: {a}"
);
}
}
/// The one that matters, and the one that caught a real bug.
///
/// The first version of this asset animated the graph INTO existence, from
/// opacity 0. It played correctly in a browser and rendered as an empty
/// rectangle under macOS Quick Look, because a still renderer samples the
/// timeline at t=0 and t=0 was blank. Thumbnails, link previews and PDF exports
/// all sample rather than play. So every animated attribute must already hold
/// its t=0 value statically, and every t=0 value must be a visible one.
#[test]
fn sampling_the_first_frame_gives_the_whole_picture() {
let s = svg();
for (parent, a) in animate_blocks(&s) {
let Some(name) = attr(&a, "attributeName") else { continue };
let Some(values) = attr(&a, "values") else { continue };
let first = values.split(';').next().unwrap_or("").trim().to_string();
match attr(&parent, &name) {
Some(statik) => assert_eq!(
statik, first,
"<{name}> starts at {first} but the element carries {statik}, so a renderer \
that samples t=0 draws something the animation never shows.\n parent: \
{parent}\n animate: {a}"
),
// Absent means the SVG default applies. Every property animated here
// defaults to 0, so the static frame agrees only if the animation
// also starts at 0.
None => assert_eq!(
first, "0",
"<{name}> is not set on the element, so it defaults to 0, but the animation \
starts at {first}.\n parent: {parent}"
),
}
if name == "opacity" {
let v: f64 = first.parse().unwrap_or(1.0);
// Two things are allowed to be invisible in the still frame, and
// both are things a still frame SHOULD NOT show: a beat caption for
// a beat that is not running, and a transient sweep, which at rest
// would just be a stray ring drawn over the graph. Everything that
// carries content has to be there.
let is_caption = parent.starts_with("<text");
let is_sweep = parent.contains("fill=\"none\"");
assert!(
v > 0.0 || is_caption || is_sweep,
"a layer at opacity 0 in the first frame is invisible to every thumbnailer, \
and only a caption or an unfilled sweep may start hidden.\n parent: {parent}"
);
}
}
}
#[test]
fn the_six_steps_are_captioned_in_order() {
let s = svg();
// Six. The provers got a step of their own (a reader was told the
// first-order family exists and never shown it do anything), and the
// unasked question got one too: the page showed yes and no, and the third
// answer, that the question is not in the file's language, was the one
// ies-core's 43 skos:Concept terms actually need.
let beats = [
"a person asserts",
"the engine derives",
// The count in this caption is the legend's CERTIFIED number, asserted
// below rather than written here, so the caption cannot drift from it.
"Lean checks the one certificate covering all",
"four provers read the clauses",
"a line is forged, and the same checker refuses",
"a question the file cannot be asked is returned unasked",
];
let mut at = 0usize;
for b in beats {
let Some(i) = s[at..].find(b) else {
panic!("the asset is missing the caption {b:?}; the motion is then decoration");
};
at += i + b.len();
}
// The arity in beat 3 is the legend's own number. A caption that said a
// different count from the legend under it would be the figure arguing
// with itself.
let (_, certified, _) = legend_counts();
assert!(
s.contains(&format!("covering all {certified}, and accepts")),
"beat 3 states a certificate count that is not the legend's CERTIFIED {certified}"
);
// Every step is numbered on the rail, and the numbers are visible at rest
// so a still frame shows the sequence rather than one lonely word.
for n in 1..=beats.len() {
assert!(
s.contains(&format!(">{n}</text>")),
"the step rail is missing the number {n}; a reader cannot see where in the \
sequence the running step sits"
);
}
}
// ── The README's caption must match the asset it captions ──────────────
//
// It did not. The caption read "4 rejected" while the legend rendered
// `REJECTED 1`, and the two had disagreed since the asset was redrawn. Nobody
// noticed because nothing compared them: the counts test above checks the SVG
// against a real run, and the README against nothing at all.
//
// A number on the front page is a claim, and a claim with no gate decays
// silently. This is that gate.
fn readme() -> String {
std::fs::read_to_string(
std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("README.md"),
)
.expect("README.md")
}
/// The legend counts, read out of the asset rather than out of the generator,
/// because what ships is the file.
fn legend_counts() -> (u64, u64, u64) {
let s = svg();
let one = |label: &str| -> u64 {
let i = s
.find(&format!(">{label}<"))
.unwrap_or_else(|| panic!("the asset has no {label} row"));
let tail = &s[i..(i + 400).min(s.len())];
let key = "text-anchor=\"end\">";
let j = tail
.find(key)
.unwrap_or_else(|| panic!("no count beside {label}"))
+ key.len();
let k = tail[j..].find('<').expect("unterminated count") + j;
tail[j..k].parse().unwrap_or_else(|_| panic!("{label} count is not a number"))
};
(one("ASSERTED"), one("CERTIFIED"), one("REJECTED"))
}
#[test]
fn the_readme_caption_states_the_counts_the_asset_renders() {
let (a, c, r) = legend_counts();
let expected = format!("{a} asserted, {c} certified, {r} rejected");
let readme = readme();
assert!(
readme.contains(&expected),
"the README caption and the asset's own legend disagree. The asset renders \
{expected:?}, and the README does not say that. Regenerate the asset and update \
the caption together, or the front page states a number the picture under it \
contradicts."
);
}
/// The headline number of the semantic plan, which is the first beat.
///
/// Derived from a run: a base of 900 individuals of one property, plus one
/// `rdfs:domain` triple. Every shape number stays at zero and the conservativity
/// check reports 901 new consequences. The figures below are asserted against a
/// live run rather than trusted, because a headline nobody re-measures is the
/// first thing to go stale.
#[test]
fn the_front_page_plan_figures_come_from_a_run() {
use open_ontologies::conservativity::{ConservativityOptions, ExtensionMode};
use open_ontologies::graph::GraphStore;
use open_ontologies::plan::Planner;
use open_ontologies::state::StateDb;
use std::sync::Arc;
const N: usize = 900;
let mut base = String::from(
"@prefix ex: <http://ex.org/> .\n\
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n\
@prefix owl: <http://www.w3.org/2002/07/owl#> .\n\
ex:Person a owl:Class .\n\
ex:hasParent a owl:ObjectProperty .\n",
);
for i in 0..N {
base.push_str(&format!("ex:p{i} ex:hasParent ex:q{i} .\n"));
}
let dir = std::env::temp_dir().join(format!("oo-readme-plan-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
let graph = Arc::new(GraphStore::new());
graph.load_turtle(&base, None).unwrap();
let planner = Planner::new(StateDb::open(&dir.join("state.db")).unwrap(), graph);
let proposal = format!("{base}ex:hasParent rdfs:domain ex:Person .\n");
let out = planner
.plan_checked(
&proposal,
Some(ConservativityOptions {
mode: ExtensionMode::Replacement,
profile: "owl-rl".to_string(),
out: dir.join("cert"),
scan_rows: 100_000,
max_rows: 1_000_000,
}),
)
.unwrap();
let v: serde_json::Value = serde_json::from_str(&out).unwrap();
let _ = std::fs::remove_dir_all(&dir);
let readme = readme();
// The field names are the plan's own: `added_classes`, not `added.classes`.
// The first version of this read `added.classes`, got `None`, and reported
// zero through an `unwrap_or(0)` — a missing field and a measured zero
// looking identical, which is the measurement error this whole file exists
// to prevent.
let n_added = v["added_classes"].as_array().expect("added_classes").len();
let n_removed = v["removed_classes"].as_array().expect("removed_classes").len();
assert_eq!(n_added, 0, "the one-triple change added a class: {:?}", v["added_classes"]);
assert_eq!(n_removed, 0, "it removed one: {:?}", v["removed_classes"]);
assert_eq!(v["blast_radius"]["triples_affected"], serde_json::json!(0));
assert_eq!(v["risk_score"], serde_json::json!("low"));
assert_eq!(
v["conservativity"]["conservativity_verdict"],
serde_json::json!("not_conservative_under_rule_table")
);
let consequences = v["conservativity"]["new_consequences_total"]
.as_u64()
.expect("a count of new consequences");
assert!(
readme.contains(&format!("{consequences} consequences that were not there before")),
"the run reports {consequences} new consequences and the README headline does not \
say so. The front page number is the claim; this run is the measurement."
);
assert!(
readme.contains(&format!("new consequences {consequences}")),
"the plan block on the front page does not state {consequences}"
);
}
/// A tag-balance check, because the asset is generated by string concatenation
/// and nothing here parsed it. A dash-marching animation was once emitted as
/// `</line/>`: browsers drew it anyway, every other guard passed, and the file
/// was not XML. `<img src=...svg>` is the delivery path and a stricter renderer
/// is entitled to refuse it outright.
fn tags(s: &str) -> Vec<(bool, String, bool)> {
let b = s.as_bytes();
let mut out = Vec::new();
let mut i = 0usize;
while i < b.len() {
if b[i] != b'<' {
i += 1;
continue;
}
let mut j = i + 1;
let mut quoted = false;
while j < b.len() && (quoted || b[j] != b'>') {
if b[j] == b'"' {
quoted = !quoted;
}
j += 1;
}
let body = &s[i + 1..j.min(s.len())];
if !body.starts_with('?') && !body.starts_with('!') {
let closing = body.starts_with('/');
let selfclose = body.ends_with('/');
let name: String = body
.trim_start_matches('/')
.chars()
.take_while(|c| c.is_alphanumeric() || *c == ':' || *c == '-')
.collect();
out.push((closing, name, selfclose));
}
i = j + 1;
}
out
}
fn imbalance(s: &str) -> Option<String> {
let mut stack: Vec<String> = Vec::new();
for (closing, name, selfclose) in tags(s) {
if closing {
match stack.pop() {
Some(open) if open == name => {}
Some(open) => return Some(format!("</{name}> closes <{open}>")),
None => return Some(format!("</{name}> with nothing open")),
}
} else if !selfclose {
stack.push(name);
}
}
stack.pop().map(|n| format!("<{n}> never closed"))
}
#[test]
fn the_asset_is_well_formed_markup() {
// The guard must be able to fail, or it is decoration. These are the three
// ways this generator has actually gone wrong or could: a stray slash on a
// closing tag, a tag closed by the wrong name, and one never closed.
assert!(imbalance("<svg><line/></line/></svg>").is_some());
assert!(imbalance("<svg><g><line/></svg></g>").is_some());
assert!(imbalance("<svg><g><line/></svg>").is_some());
assert!(imbalance("<svg><g><line/><text>x</text></g></svg>").is_none());
let s = svg();
assert_eq!(
imbalance(&s),
None,
"docs/assets/knowledge-graph.svg does not have balanced tags"
);
}
/// The ontology heading must say which predicate it drew, and must not claim
/// the FILE is in pieces.
///
/// It read "WHAT THE FILE CONTAINS - 139 CLASSES IN 6 DISJOINT PIECES". The
/// file holds 1,083 triples over 22 predicates and this figure draws exactly
/// one of them, `rdfs:subClassOf`. On that predicate ies-core falls into six
/// pieces; on the file's own other relations three of them join up and it
/// falls into four. The six are the top branches of one class hierarchy.
/// Reporting a consequence of the drawing as a property of the data is the
/// mistake this figure exists to argue against, so it is worth a guard rather
/// than a careful author.
#[test]
fn the_ontology_heading_names_the_predicate_it_drew() {
let s = svg();
// The asset calls itself the Studio 3D view, so the Studio has to lay the
// graph out this way. It did not: `Graph3D.tsx` was a plain ForceGraph3D,
// one force run over everything, and the figure's placed pipeline and
// per-component packing existed only in the drawing. The claim was made
// true by changing the component, and this keeps it true.
if s.contains("the Studio 3D view") {
let studio = std::fs::read_to_string(repo().join("studio/src/components/Graph3D.tsx"))
.expect("studio/src/components/Graph3D.tsx");
for needed in ["PIPELINE", "componentCentres", "fx:", "comp"] {
assert!(
studio.contains(needed),
"the asset calls itself the Studio 3D view but Graph3D.tsx has no \
{needed:?}. Either the Studio lays the graph out the way this \
figure draws it, or the figure must stop saying it is the Studio."
);
}
}
// Retracted wording, and anything else that claims the FILE is split.
for gone in ["WHAT THE FILE CONTAINS", "DISJOINT PIECES", "DISJOINT"] {
assert!(
!s.contains(gone),
"{gone:?} is back in the asset. The drawing is one predicate out of \
twenty-two, so it cannot speak for the file."
);
}
// And it has to declare its scope by naming the predicate.
assert!(
s.contains("subClassOf"),
"the ontology heading must name the predicate it drew, or a reader has \
no way to know the picture is a subclass skeleton rather than the file"
);
// The class count has to agree with the node count the subtitle states.
// Every node in the figure is either a class of the ontology or one of the
// ten things in the pipeline, so the difference is fixed and a stale
// literal on either side breaks it.
let nodes = drawn("Studio 3D view: ", " nodes and");
let classes: u64 = s
.split(" TERMS OF")
.next()
.and_then(|before| {
before
.rsplit(|c: char| !c.is_ascii_digit())
.find(|t| !t.is_empty())
.and_then(|t| t.parse().ok())
})
.expect("the heading states a term count");
// `E` is left out of the list: the name is one letter and appears inside
// half the words in the file, so asserting on it would pass for the wrong
// reason. It is still counted, because the count below counts it.
let pipeline = ["ies-core.ttl", "certificate", "problem.tsv", "Lean 4",
"Isabelle/HOL", "Vampire", "Z3", "Mace4", "oo-resolution"];
for name in pipeline {
assert!(s.contains(name), "the pipeline no longer names {name:?}");
}
let in_pipeline = (pipeline.len() + 1) as u64;
assert_eq!(
nodes - classes,
in_pipeline,
"the subtitle says {nodes} nodes and the heading says {classes} classes, \
but the pipeline holds {in_pipeline}. Every node is a class or one of \
the pipeline's, so one of these numbers is stale."
);
}
/// Which judge earned `certificate` is READ from the prover run, not typed.
///
/// `docs/assets/kgcert/prove.json` is `onto_fol_prove`'s result on the figure's
/// own ontology. If it says `refutation_certified` on a `cnf` problem, the
/// asset must show Vampire with a `certificate` badge, an edge to `oo-resolution`,
/// and a legend whose `opinion` row does NOT name Vampire; if it does not, the
/// asset must show the older, weaker picture. Either way the asset agrees with
/// the run, and a hand edit to one side fails here.
#[test]
fn the_judges_badges_come_from_the_prover_run() {
let s = svg();
let run: serde_json::Value = serde_json::from_str(
&std::fs::read_to_string(repo().join("docs/assets/kgcert/prove.json")).expect("prove.json"),
).expect("json");
let certified = run["verdict"] == "refutation_certified" && run["problem_form"] == "cnf";
assert!(s.contains("oo-resolution"), "the checker of Fo certificates must be drawn");
if certified {
assert!(s.contains("Vampire's refutation is checked"), "beat 4 must say the refutation was checked");
assert!(s.contains(run["theorem"].as_str().unwrap()), "the legend names the theorem the run named");
assert!(!s.contains("Vampire, E, Z3 and Mace4 read a different file"), "the opinion row may not name Vampire");
assert!(s.contains("E, Z3 and Mace4 read the clauses too"), "{}", "the opinion row lists the three that only opine");
} else {
assert!(s.contains("Vampire, E, Z3 and Mace4 read a different file"));
assert!(!s.contains("Vampire's refutation is checked"));
}
// And the committed certificate is the one the run produced: same step count.
let cert = std::fs::read_to_string(repo().join("docs/assets/kgcert/goal_00000.fo.cert")).expect("cert");
let steps = cert.lines().filter(|l| l.starts_with("r\t") || l.starts_with("f\t")).count() as u64;
assert_eq!(steps, run["certificate_steps"].as_u64().unwrap(), "prove.json and the .fo.cert disagree on step count");
}
/// The sixth beat is read from a run, like the fourth. `docs/assets/kgcert/mu.json`
/// is one goal `onto_fol_prove` returned with the verdict `mu`, and the asset
/// must name that goal's subject, say what the file calls it, and count it
/// in the legend. A beat about an unasked question that no run returned
/// would be the page inventing a verdict.
#[test]
fn the_unasked_beat_comes_from_the_mu_run() {
let s = svg();
let mu: serde_json::Value = serde_json::from_str(
&std::fs::read_to_string(repo().join("docs/assets/kgcert/mu.json")).expect("mu.json"),
)
.expect("mu.json is JSON");
assert_eq!(mu["report"]["verdict"], "mu", "the committed run is not an unasked question");
let subject = mu["goal"][0].as_str().expect("goal subject");
let local = subject.trim_matches(|c| c == '<' || c == '>').rsplit('/').next().unwrap();
let kind = mu["report"]["kind"].as_str().unwrap_or("");
assert!(
s.contains(&format!("returned unasked · {local} is")),
"the badge does not name {local}, the subject the run returned unasked"
);
// What the file calls the term comes from the run's own sentence.
let why = mu["report"]["why"].as_str().unwrap_or("");
if kind == "individual" && why.contains("skos/core#Concept") {
assert!(s.contains(&format!("{local} is a Concept, never a class")), "{why}");
}
assert!(s.contains(">UNASKED</text>"), "the legend has no UNASKED row");
assert!(s.contains("無"), "the glyph is the beat; without it the line just dims");
// And the question is never drawn as refuted: the two words stay apart.
assert!(!s.contains("unasked, refused") && !s.contains("refuted · Accent"));
}
/// Two pieces of writing may not sit in the same place.
///
/// Every label and badge on the drawing is a rounded `#020617` rectangle with
/// text over it, placed by a routine that tries a handful of candidate
/// positions and takes the first clear one. One of them did not: the
/// "disagreement · stops the line" badge took a single computed point, and
/// that point landed on the `problem.tsv` label. Both are visible in the same
/// instant, so the drawing showed two sentences through each other, and no
/// test could see it because every number on the page was still correct.
///
/// The rule here is stronger than it has to be: NO two label boxes overlap,
/// even two that are never lit at once. A badge that shares its pixels with
/// another is a badge whose position was not chosen, and the cost of the
/// stricter rule is a few pixels of layout freedom.
#[test]
fn no_two_labels_sit_on_top_of_each_other() {
let s = svg();
let mut boxes: Vec<(f64, f64, f64, f64)> = Vec::new();
let mut at = 0usize;
while let Some(i) = s[at..].find("<rect x=\"") {
let start = at + i;
let Some(end) = s[start..].find("/>") else { break };
let tag = &s[start..start + end + 2];
at = start + end + 2;
// Label chips and badges only: the legend panel and the colour swatches
// are neither rounded nor this colour.
if !tag.contains("fill=\"#020617\"") || !tag.contains("rx=\"") {
continue;
}
let num = |k: &str| -> Option<f64> {
let i = tag.find(&format!("{k}=\""))? + k.len() + 2;
tag[i..].split('"').next()?.parse().ok()
};
if let (Some(x), Some(y), Some(w), Some(h)) =
(num("x"), num("y"), num("width"), num("height"))
{
boxes.push((x, y, x + w, y + h));
}
}
assert!(
boxes.len() > 20,
"only {} label boxes were found, so this test is not looking at the labels and \
cannot fail",
boxes.len()
);
let mut clashes = Vec::new();
for (i, a) in boxes.iter().enumerate() {
for b in &boxes[i + 1..] {
let ix = a.2.min(b.2) - a.0.max(b.0);
let iy = a.3.min(b.3) - a.1.max(b.1);
if ix > 0.5 && iy > 0.5 {
clashes.push(format!(
" {:?} and {:?} share {ix:.0}x{iy:.0} pixels",
a, b
));
}
}
}
assert!(
clashes.is_empty(),
"{} pair(s) of labels overlap, so the drawing prints two sentences through each \
other:\n{}\n\nEvery badge is placed by trying candidate positions against \
`placed`; one that overlaps is one that was placed blind.",
clashes.len(),
clashes.join("\n")
);
}
// ── The hand-drawn animation on the front page ──────────────────────────
//
// The README shows `knowledge-graph.webp`, drawn in the paper style by
// `docs/assets/hand-drawn/hero.js` from `knowledge-graph.scene.json`, and links
// the SVG for anyone who wants the exact figure. A raster carries no number a
// test can read, so the chain is checked one link at a time: the first test
// ties the SVG to a live run, this one ties the scene to the SVG, and the WebP
// carries the digest of the scene that drew it. Regenerating one without the
// others fails here.
/// One published variant of the animation: the SVG it was drawn beside, its
/// scene, its WebP, and the README that shows it.
struct Variant {
svg: &'static str,
scene: &'static str,
webp: &'static str,
readme: &'static str,
}
const VARIANTS: [Variant; 2] = [
Variant {
svg: "knowledge-graph.svg",
scene: "knowledge-graph.scene.json",
webp: "knowledge-graph.webp",
readme: "README.md",
},
Variant {
svg: "knowledge-graph.zh-CN.svg",
scene: "knowledge-graph.zh-CN.scene.json",
webp: "knowledge-graph.zh-CN.webp",
readme: "README.zh-CN.md",
},
];
fn asset(name: &str) -> Vec<u8> {
std::fs::read(repo().join("docs/assets").join(name))
.unwrap_or_else(|_| panic!("docs/assets/{name}"))
}
/// Every variant is checked the same way. The legend counts are compared with
/// the ENGLISH SVG's for both languages: the labels are translated, the numbers
/// are not, and both scenes come from the same run.
#[test]
fn the_hand_drawn_animation_is_drawn_from_the_svgs_own_scene() {
let (a, c, r) = legend_counts();
for v in &VARIANTS {
let bytes = asset(v.scene);
let scene: serde_json::Value = serde_json::from_slice(&bytes)
.unwrap_or_else(|_| panic!("{} is not JSON", v.scene));
let text = String::from_utf8(asset(v.svg)).expect("the SVG is UTF-8");
let rows = scene["legend"]["rows"].as_array().expect("legend rows");
for (key, want) in [("asserted", a), ("certified", c), ("rejected", r)] {
let row = rows
.iter()
.find(|x| x["key"] == key)
.unwrap_or_else(|| panic!("{} has no {key} row", v.scene));
assert_eq!(
row["count"].as_u64(),
Some(want),
"{} says {} for {key} and the SVG legend says {want}. Both come from one \
run of knowledge-graph.py; regenerate them together.",
v.scene,
row["count"]
);
}
// The sub-heading carries the run's totals, and it is the SVG's own sentence.
let sub = scene["sub"].as_str().expect("sub-heading");
assert!(
text.contains(sub),
"the sub-heading of {} is not the one in {}. They were drawn from different runs.",
v.scene,
v.svg
);
let nodes = scene["nodes"].as_array().expect("nodes").len().to_string();
let edges = scene["edges"].as_array().expect("edges");
let n_edges = edges.len().to_string();
assert!(
sub.contains(&nodes) && sub.contains(&n_edges),
"{} draws {nodes} nodes and {n_edges} edges and its sub-heading says otherwise",
v.scene
);
let forged = edges.iter().filter(|e| e[2] == "rejected").count() as u64;
assert_eq!(forged, r, "{} forges {forged} lines and the legend says {r}", v.scene);
// The WebP is animated and was drawn from THIS scene.
let webp = asset(v.webp);
assert!(
webp.len() > 12 && &webp[0..4] == b"RIFF" && &webp[8..12] == b"WEBP",
"{} is not a WebP file",
v.webp
);
assert!(
webp.windows(4).any(|w| w == b"ANIM"),
"{} is a still. The front page argues in six steps, in order.",
v.webp
);
use sha2::{Digest, Sha256};
let stamp = format!("scene-sha256={:x}", Sha256::digest(&bytes));
assert!(
webp.windows(stamp.len()).any(|w| w == stamp.as_bytes()),
"{} was not drawn from the scene in the repository. Re-render it: node \
docs/assets/hand-drawn/render.js {} {}",
v.webp,
v.scene,
v.webp
);
// The front page shows the animation and links the exact figure.
let md = std::fs::read_to_string(repo().join(v.readme)).expect("README");
assert!(
md.contains(&format!("docs/assets/{}", v.webp)),
"{} no longer shows {}",
v.readme,
v.webp
);
assert!(
md.contains(&format!("href=\"docs/assets/{}\"", v.svg)),
"{} shows the drawing and no longer links the exact figure {} it was drawn from",
v.readme,
v.svg
);
}
}