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 tool reference lists every tool, and the front page lists none of them.**
//!
//! Issue #196: the README sold surface area. A visitor met four abstract nouns
//! and a tool count before meeting a verb, and could not tell what the thing was
//! for. The breadth is real and it keeps its code; it loses its place above the
//! fold and moves to `docs/tool-reference.md`, linked once, low on the page.
//!
//! A reference page that drifts from the code is worse than no reference page,
//! because it is read as authoritative. These tests are the gate: the page is
//! generated from the `#[tool(...)]` attributes and must stay in step with them.
use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
fn repo() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
}
fn read(p: &str) -> String {
std::fs::read_to_string(repo().join(p)).unwrap_or_else(|e| panic!("{p}: {e}"))
}
/// Tool names as the server registers them.
fn registered() -> BTreeSet<String> {
let src = read("src/server.rs");
let mut out = BTreeSet::new();
let needle = "#[tool(name = \"";
let mut i = 0;
while let Some(j) = src[i..].find(needle) {
let start = i + j + needle.len();
let end = start + src[start..].find('"').expect("unterminated tool name");
out.insert(src[start..end].to_string());
i = end;
}
out
}
/// Tool names the reference page lists, from the first column of its table.
fn documented() -> BTreeSet<String> {
read("docs/tool-reference.md")
.lines()
.filter_map(|l| {
let l = l.trim();
let rest = l.strip_prefix("| `")?;
let end = rest.find('`')?;
Some(rest[..end].to_string())
})
.collect()
}
#[test]
fn every_registered_tool_is_in_the_reference() {
let (r, d) = (registered(), documented());
let missing: Vec<_> = r.difference(&d).collect();
assert!(
missing.is_empty(),
"these tools are registered and not listed in docs/tool-reference.md: {missing:?}. \
Regenerate the page rather than deleting this assertion; an unlisted tool is one \
nobody can find."
);
}
#[test]
fn the_reference_invents_no_tools() {
let (r, d) = (registered(), documented());
let extra: Vec<_> = d.difference(&r).collect();
assert!(
extra.is_empty(),
"docs/tool-reference.md lists tools the server does not register: {extra:?}. A \
reference page that names something that does not exist is worse than a missing \
page, because it is read as authoritative."
);
}
/// The count on the page is a claim like any other.
#[test]
fn the_reference_states_the_right_count() {
let n = registered().len();
let page = read("docs/tool-reference.md");
assert!(
page.contains(&format!("{n} tools.")),
"the page does not state {n} tools, which is how many are registered"
);
}
/// The two totals the front page used to print, and must never print again.
///
/// Spelled in parts rather than as one literal each, and the reason is a gate
/// and not taste. `readme_claims_test::no_file_states_a_tool_count_this_build
/// _cannot_justify` scans every tracked `.md` and `.rs` for a number followed
/// by the word tools and fails on any that this build cannot justify. A test
/// file carrying `121` next to that word IS such a claim, so adding one tool to
/// the server used to break this file. The two gates are both right and they
/// are reconciled here: the record of what was retired is kept, and the shape
/// of a claim is not. `concat!` joins them at compile time, so the ban is on the
/// same bytes it always was.
const RETIRED_TOTALS: [&str; 2] = [concat!("121", " tools"), concat!("113", " tools")];
/// The repositioning itself. The front page shows the loop and not the
/// catalogue, and this is what stops the catalogue creeping back.
#[test]
fn the_front_page_sells_the_loop_and_not_the_surface_area() {
let readme = read("README.md");
let fold = &readme[..readme.len().min(9000)];
for banned in [RETIRED_TOTALS[0], RETIRED_TOTALS[1], "Terraforming MCP"] {
assert!(
!readme.contains(banned),
"the README still says {banned:?}. Surface area reads as insecurity, and a \
number where a purpose belongs tells a visitor nothing about what this is for."
);
}
for beat in [
"consequences that were not there before", // beat 1, the semantic plan
"re-verifies months later", // beat 2, the certificate
"exits 1 and names the rule", // beat 3, the refusal
] {
assert!(
fold.contains(beat),
"the fold is missing the beat {beat:?}. The three beats are attention, \
evidence, credibility, in that order, and dropping one leaves an argument \
that does not close."
);
}
assert!(
fold.contains("This is not an ontology editor"),
"the anti-positioning line is gone. It answers the first question a visitor has."
);
assert!(
fold.contains("A text diff is `git diff`"),
"the second anti-positioning line is gone. It pre-empts the first objection, which \
is why this is not just a file in git."
);
assert!(
readme.contains("docs/tool-reference.md"),
"the breadth has to be reachable: the reference page is linked once, low on the page"
);
}
/// `trustworthy`, and the other words the issue retired, must stay gone.
///
/// Checked by ABSENCE across every file that carries outward prose, because a
/// claim lives in more copies than anyone expects and reading the new text
/// finds only the copy you are looking at.
///
/// `docs/tool-reference.md` is exempt from the COUNT strings and only those.
/// The ban exists because a number where a purpose belongs tells a visitor
/// nothing about what this is for; the reference page is the catalogue, its job
/// is to be exhaustive, and a catalogue that will not say how long it is is
/// being coy. It is not exempt from `trustworthy`, which is a faith claim
/// wherever it appears. This exemption is written down rather than achieved by
/// narrowing the walk, so a reader can disagree with it.
#[test]
fn the_retired_words_do_not_come_back() {
let mut hits = vec![];
let mut walk = |p: &Path| {
if p.extension().is_some_and(|e| e == "md")
&& let Ok(t) = std::fs::read_to_string(p)
{
let lower = t.to_lowercase();
let is_catalogue = p.ends_with("tool-reference.md");
for w in [RETIRED_TOTALS[0], RETIRED_TOTALS[1], "terraforming mcp", "trustworthy"] {
let counts_only = w.ends_with(" tools");
if is_catalogue && counts_only {
continue;
}
if lower.contains(w) {
hits.push(format!("{}: {w}", p.display()));
}
}
}
};
walk(&repo().join("README.md"));
walk(&repo().join("README.zh-CN.md"));
let docs = repo().join("docs");
let mut stack = vec![docs];
while let Some(d) = stack.pop() {
let Ok(rd) = std::fs::read_dir(&d) else { continue };
for e in rd.flatten() {
let p = e.path();
if p.is_dir() {
stack.push(p);
} else {
walk(&p);
}
}
}
assert!(
hits.is_empty(),
"retired strings are back: {hits:?}. Verify by absence, not by reading the new text."
);
}