hypersteeldb 0.5.4

//! Guards on the things a reader sees before they see any code: the crates.io sidebar, the docs.rs landing
//! page, and the first code block in the README. All three drifted in the 0.1–0.2 series without any test
//! noticing, which is exactly the kind of rot that only a user reports.

const CARGO_TOML: &str = include_str!("../Cargo.toml");
const README: &str = include_str!("../README.md");
const LIB_RS: &str = include_str!("../src/lib.rs");

fn field(name: &str) -> Option<String> {
    CARGO_TOML
        .lines()
        .take_while(|l| !l.starts_with("[lib]"))
        .find(|l| l.trim_start().starts_with(&format!("{name} = ")))
        .and_then(|l| l.split('"').nth(1))
        .map(str::to_string)
}

/// `0.2.3` -> `0.2`, the form a dependency line should carry.
fn minor_series() -> String {
    let v = env!("CARGO_PKG_VERSION");
    let mut parts = v.split('.');
    format!("{}.{}", parts.next().unwrap_or("0"), parts.next().unwrap_or("0"))
}

#[test]
fn the_documentation_link_points_at_this_crate() {
    // It pointed at `https://docs.rs/steeldb`, which is an unrelated crate published by someone else in 2023.
    // Anyone clicking "Documentation" on our crates.io page landed on a stranger's database.
    let doc = field("documentation").expect("a documentation link");
    let pkg = env!("CARGO_PKG_NAME");
    assert!(
        doc.ends_with(pkg) || doc.contains(&format!("/{pkg}/")),
        "documentation is {doc:?} but the package is {pkg:?} — docs.rs keys by PACKAGE name, not lib name"
    );
}

#[test]
fn we_do_not_claim_a_repository_we_do_not_have() {
    // `repository` means source. The only public location is a Hugging Face Space holding index.html, the
    // compiled wasm and sample data — no Rust at all — so declaring it as the repository sends anyone looking
    // for the source somewhere it is not. Better to declare nothing than to declare somewhere wrong.
    if let Some(repo) = field("repository") {
        assert!(
            !repo.contains("/spaces/"),
            "repository points at a Space ({repo}), which carries no source"
        );
    }
}

#[test]
fn the_readme_installs_the_current_version() {
    // The README said `hypersteeldb = "0.1"` through four releases.
    let want = format!("hypersteeldb = \"{}\"", minor_series());
    assert!(
        README.contains(&want),
        "README should install {want:?}; found {:?}",
        README
            .lines()
            .find(|l| l.contains("hypersteeldb = "))
            .unwrap_or("no dependency line at all")
    );
}

#[test]
fn the_crate_docs_install_the_current_version() {
    // Same line again in the rustdoc landing page, which is what docs.rs shows first.
    let want = format!("hypersteeldb = \"{}\"", minor_series());
    assert!(
        LIB_RS.contains(&want),
        "src/lib.rs should install {want:?}; found {:?}",
        LIB_RS
            .lines()
            .find(|l| l.contains("hypersteeldb = "))
            .unwrap_or("no dependency line at all")
    );
}

#[test]
fn the_readme_has_no_repository_relative_images() {
    // crates.io does not serve repository files, so a relative image can only ever render as a broken icon.
    // The header image was `assets/registeel.jpg` — and `assets/` is excluded from the package besides.
    for (i, line) in README.lines().enumerate() {
        if let Some(rest) = line.split("src=\"").nth(1) {
            let src = rest.split('"').next().unwrap_or("");
            assert!(
                src.starts_with("http"),
                "README line {} uses a relative image {src:?}; crates.io cannot resolve it",
                i + 1
            );
        }
        if let Some(rest) = line.split("](").nth(1) {
            let target = rest.split(')').next().unwrap_or("");
            if line.trim_start().starts_with("![") {
                assert!(
                    target.starts_with("http"),
                    "README line {} uses a relative image {target:?}",
                    i + 1
                );
            }
        }
    }
}

#[test]
fn readme_code_blocks_fit_the_crates_io_column() {
    // The rendered column is far narrower than a terminal. Lines of 84 to 96 characters were being cut off
    // mid-sentence, including the comment that explains what a refusal tells you.
    const LIMIT: usize = 74;
    let mut in_fence = false;
    for (i, line) in README.lines().enumerate() {
        if line.trim_start().starts_with("```") {
            in_fence = !in_fence;
            continue;
        }
        if in_fence {
            let n = line.chars().count();
            assert!(n <= LIMIT, "README line {} is {n} chars, over {LIMIT}: {line}", i + 1);
        }
    }
    assert!(!in_fence, "a code fence is left open");
}

#[test]
fn the_package_declares_what_it_is_for() {
    for f in ["description", "license", "readme", "homepage"] {
        assert!(field(f).is_some(), "Cargo.toml is missing {f}");
    }
    let desc = field("description").unwrap();
    assert!(desc.len() > 40, "description is too thin to be useful: {desc:?}");
}

#[test]
fn the_readme_does_not_invent_numbers_in_the_observations_section() {
    // The reframed opening quotes belief intervals and relation tags. A first draft of it carried a plausible
    // but FABRICATED conflict figure and an interval copied from a different corpus — after a whole session
    // spent insisting the README quote measured output. This pins the ones that survived to the example that
    // produces them, so the pairing is checked rather than trusted.
    //
    // `cargo run --example observations` prints exactly these.
    for measured in [
        "rel/supplies/+/acme-corp",
        "rel/permitted/-/defence-ministry",
        "state/asserted   [0.75, 1.00]   ignorance 0.25",
        "state/negated    [0.00, 0.75]   ignorance 0.75",
    ] {
        assert!(README.contains(measured), "README lost the measured line {measured:?}");
    }
    // and must not carry the invented ones
    for invented in ["conflict K = 0.71", "[0.00, 0.88]"] {
        assert!(!README.contains(invented), "README carries a fabricated figure: {invented}");
    }
}