use std::collections::BTreeSet;
#[allow(dead_code)]
mod support;
use support::Sandbox;
const DOCUMENTS_THAT_COVER_EVERY_COMMAND: [(&str, &str); 6] = [
("docs/HOW_TO_USE.md", include_str!("../docs/HOW_TO_USE.md")),
(
"docs/HOW_TO_USE.pt-BR.md",
include_str!("../docs/HOW_TO_USE.pt-BR.md"),
),
("docs/COMMANDS.md", include_str!("../docs/COMMANDS.md")),
(
"docs/COMMANDS.pt-BR.md",
include_str!("../docs/COMMANDS.pt-BR.md"),
),
(
"skills/mariadb-cli-en/SKILL.md",
include_str!("../skills/mariadb-cli-en/SKILL.md"),
),
(
"skills/mariadb-cli-pt/SKILL.md",
include_str!("../skills/mariadb-cli-pt/SKILL.md"),
),
];
const MANIFEST: &str = include_str!("../Cargo.toml");
const README: &str = include_str!("../README.md");
fn gaps() -> Option<String> {
std::fs::read_to_string(std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("gaps.md")).ok()
}
const README_PT: &str = include_str!("../README.pt-BR.md");
const SHORT_MAP: &str = include_str!("../llms.txt");
const FULL_MAP: &str = include_str!("../llms-full.txt");
const SHORT_MAP_PT: &str = include_str!("../llms.pt-BR.txt");
const FULL_MAP_PT: &str = include_str!("../llms-full.pt-BR.txt");
const MAPS: [(&str, &str); 4] = [
("llms.txt", SHORT_MAP),
("llms-full.txt", FULL_MAP),
("llms.pt-BR.txt", SHORT_MAP_PT),
("llms-full.pt-BR.txt", FULL_MAP_PT),
];
#[test]
fn the_documentation_page_is_built_for_a_named_target() {
let section = section_of(MANIFEST, "[package.metadata.docs.rs]")
.expect("the manifest declares how its documentation is built");
assert!(
section.contains("targets = ["),
"the documentation section names no target, so the page is built for \
whatever the registry defaults to that week: {section}"
);
assert!(
section.contains("features = ["),
"the page must describe the same build the install produces"
);
}
#[test]
fn every_feature_the_readme_names_exists_in_the_manifest() {
let declared = declared_features();
let offered = features_named_in(README);
let invented: Vec<&String> = offered.difference(&declared).collect();
assert!(
invented.is_empty(),
"the readme tells a reader to install with {invented:?}, which the \
manifest does not declare; the manifest offers {declared:?}"
);
}
#[test]
fn the_readme_answers_the_two_questions_asked_before_installing() {
let headings = headings_of(README);
assert!(
headings.iter().any(|heading| heading == "## MSRV"),
"no minimum toolchain section; the readme has {headings:?}"
);
assert!(
headings.iter().any(|heading| heading == "## License"),
"no licence section under that name; the readme has {headings:?}"
);
}
#[test]
fn the_stated_minimum_toolchain_is_the_one_the_manifest_enforces() {
let enforced = value_of(MANIFEST, "rust-version")
.expect("the manifest declares a minimum toolchain, so cargo can refuse by name");
assert!(
README.contains(&enforced),
"the readme does not carry the minimum toolchain `{enforced}` that the \
manifest enforces, so the two can drift without anything noticing"
);
}
#[test]
fn the_maps_for_a_reading_agent_exist_and_point_somewhere_real() {
for (name, map) in MAPS {
assert!(
map.starts_with("# mariadb-cli"),
"{name} does not open by naming the product"
);
assert!(
!map.contains("docs_prd/"),
"{name} names the requirements directory, which is working material \
and travels neither in the archive nor in the repository, so the \
reader is sent to a file that is not there"
);
assert!(
map.contains("docs/COMMANDS"),
"{name} does not point at the command reference, which is the \
published document that answers what the product does"
);
}
for (readme, short, full) in [
("README.md", "llms.txt", "llms-full.txt"),
("README.pt-BR.md", "llms.pt-BR.txt", "llms-full.pt-BR.txt"),
] {
let text = if readme == "README.md" {
README
} else {
README_PT
};
assert!(
text.contains(short) && text.contains(full),
"{readme} does not mention its maps, so nothing leads to them"
);
}
}
#[test]
fn every_served_command_is_named_by_the_documents_that_promise_all_of_them() {
let sandbox = Sandbox::new();
let served: Vec<String> = sandbox
.run(&["meta", "commands"])
.rows()
.iter()
.filter_map(|row| {
let name = row["name"].as_str()?;
(row["state"].as_str() == Some("served")).then(|| name.to_owned())
})
.collect();
assert!(
served.len() >= 60,
"the binary answered with {} served commands, which is too few for this \
proof to be measuring the surface at all",
served.len()
);
for (name, text) in DOCUMENTS_THAT_COVER_EVERY_COMMAND {
let absent: Vec<&String> = served
.iter()
.filter(|command| !text.contains(command.as_str()))
.collect();
assert!(
absent.is_empty(),
"{name} promises to describe every command and names none of these, \
so a reader looking one up finds nothing: {absent:?}"
);
}
}
#[test]
fn every_served_command_is_shown_being_run_by_both_skills() {
let sandbox = Sandbox::new();
let served: Vec<String> = sandbox
.run(&["meta", "commands"])
.rows()
.iter()
.filter_map(|row| {
let name = row["name"].as_str()?;
(row["state"].as_str() == Some("served")).then(|| name.to_owned())
})
.collect();
assert!(
served.len() >= 60,
"the binary answered with {} served commands, which is too few for this \
proof to be measuring the surface at all",
served.len()
);
for (name, text) in [
(
"skills/mariadb-cli-en/SKILL.md",
include_str!("../skills/mariadb-cli-en/SKILL.md"),
),
(
"skills/mariadb-cli-pt/SKILL.md",
include_str!("../skills/mariadb-cli-pt/SKILL.md"),
),
] {
let unshown: Vec<&String> = served
.iter()
.filter(|command| {
!text.contains(&format!("`mariadb-cli {command} "))
&& !text.contains(&format!("`mariadb-cli {command}`"))
})
.collect();
assert!(
unshown.is_empty(),
"{name} names these commands without ever showing one being run, \
which teaches the reader the word and not the call: {unshown:#?}"
);
}
}
#[test]
fn every_published_schema_is_named_by_the_index_that_lists_them() {
let index_en = include_str!("../docs/schemas/README.md");
let index_pt = include_str!("../docs/schemas/README.pt-BR.md");
let files: Vec<String> = std::fs::read_dir("docs/schemas")
.expect("the schema directory is part of the published package")
.filter_map(|entry| {
let name = entry.ok()?.file_name().to_string_lossy().into_owned();
name.ends_with(".schema.json").then_some(name)
})
.collect();
assert!(
files.len() >= 60,
"found {} schema files, which is too few for this proof to be measuring anything",
files.len()
);
for (name, index) in [("README.md", index_en), ("README.pt-BR.md", index_pt)] {
let absent: Vec<&String> = files.iter().filter(|file| !index.contains(*file)).collect();
assert!(
absent.is_empty(),
"docs/schemas/{name} claims to list every schema and names none of these, \
so run `cargo xtask gen-schemas`: {absent:#?}"
);
}
}
#[test]
fn every_destination_the_maps_name_is_published_and_not_merely_linked() {
let allowlist = section_of(MANIFEST, "include = [").expect("the manifest ships an allowlist");
let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
for (name, map) in MAPS {
let targets = link_targets(map);
assert!(
targets.len() >= 3,
"{name} yielded {} link targets, so this proof is checking almost \
nothing; either the map lost its links or the reader stopped \
finding them",
targets.len()
);
for target in targets {
assert!(
root.join(&target).exists(),
"{name} leads to `{target}`, which is not in the repository"
);
assert!(
published_by(allowlist, &target),
"{name} leads to `{target}` and the allowlist does not publish \
it, so whoever downloads the crate opens a link to nothing"
);
}
}
}
fn published_by(allowlist: &str, target: &str) -> bool {
if allowlist.contains(target) {
return true;
}
let Some((directory, rest)) = target.split_once('/') else {
return false;
};
let Some(extension) = rest.rsplit_once('.').map(|(_, tail)| tail) else {
return false;
};
allowlist.contains(&format!("{directory}/**/*.{extension}"))
}
fn link_targets(text: &str) -> Vec<String> {
let mut found = Vec::new();
for (offset, _) in text.match_indices("](") {
let rest = &text[offset + 2..];
let Some(end) = rest.find(')') else { continue };
let target = &rest[..end];
if target.starts_with("http") || target.starts_with('#') {
continue;
}
found.push(target.to_owned());
}
found
}
#[test]
fn the_published_archive_carries_what_the_readme_points_at() {
let allowlist = section_of(MANIFEST, "include = [").expect("the manifest ships an allowlist");
for named in [
"/README.md",
"/README.pt-BR.md",
"/llms.txt",
"/llms-full.txt",
"/llms.pt-BR.txt",
"/llms-full.pt-BR.txt",
] {
assert!(
allowlist.contains(named),
"the readme leads a reader to `{named}` and the archive does not \
carry it"
);
}
}
#[test]
fn the_missing_links_to_the_code_are_a_decision_and_not_an_oversight() {
let links = ["repository", "homepage", "documentation"];
let published: Vec<&str> = links
.into_iter()
.filter(|key| value_of(MANIFEST, key).is_some())
.collect();
let Some(gaps) = gaps() else {
eprintln!(
"SKIPPED: the_missing_links_to_the_code_are_a_decision_and_not_an_oversight \
needs gaps.md, which is local working material and does not travel in \
the archive. This proof did NOT pass; it did not run."
);
return;
};
if published.len() == links.len() {
assert!(
!gaps.contains("## G-006"),
"the manifest publishes all three links and the gaps file still \
carries G-006, which describes their absence"
);
return;
}
assert!(
gaps.contains("## G-006"),
"the manifest publishes only {published:?} of {links:?} and no gap \
explains the rest, so the omission reads as forgetting"
);
}
fn declared_features() -> BTreeSet<String> {
let Some(section) = section_of(MANIFEST, "[features]") else {
return BTreeSet::new();
};
section
.lines()
.filter_map(|line| {
let (name, _) = line.split_once('=')?;
let name = name.trim();
(!name.is_empty() && !name.starts_with('#')).then(|| name.to_owned())
})
.collect()
}
fn features_named_in(text: &str) -> BTreeSet<String> {
let mut named = BTreeSet::new();
let mut rest = text;
while let Some(at) = rest.find("--features") {
let after = &rest[at + "--features".len()..];
if let Some(word) = after
.split_whitespace()
.next()
.map(|word| word.trim_matches(|character: char| !character.is_alphanumeric()))
{
if !word.is_empty() {
named.insert(word.to_owned());
}
}
rest = after;
}
named
}
fn value_of(manifest: &str, key: &str) -> Option<String> {
manifest.lines().find_map(|line| {
let (name, value) = line.split_once('=')?;
(name.trim() == key).then(|| value.trim().trim_matches('"').to_owned())
})
}
fn section_of<'a>(text: &'a str, opening: &str) -> Option<&'a str> {
let at = text.find(opening)?;
let rest = &text[at..];
let end = rest
.match_indices("\n[")
.map(|(offset, _)| offset)
.find(|offset| *offset > 0)
.unwrap_or(rest.len());
Some(&rest[..end])
}
fn headings_of(text: &str) -> Vec<String> {
text.lines()
.filter(|line| line.starts_with("## "))
.map(str::trim_end)
.map(str::to_owned)
.collect()
}