macrame-db 0.15.0

//! Appendix D names numbers, and this is what keeps them true (0.13.38, W11.5,
//! [D-211](../../docs/architecture/s13-decision-register.md#d-211)).
//!
//! # Why the contract needs a gate and Appendix A does not
//!
//! [Appendix A](../../docs/architecture/appendices.md) is *shape* — signatures,
//! held by `doc_sync_tests` and by the checked-in surface itself. Appendix D is
//! **quantities**: 1,313 items, schema v11, snapshot container v3, MSRV 1.88,
//! eight doctrines. A quantity in a normative document is the thing that rots
//! first and says nothing when it does, because it is still a plausible number
//! long after it stops being the right one. [D-207](../../docs/architecture/s13-decision-register.md#d-207)
//! found the same count wrong in four places with four different answers; the
//! fix there was an assertion, and this is that fix applied to the document that
//! tells a downstream caller what a major version means.
//!
//! # What it cannot check
//!
//! Whether the *promises* are kept. No test can read "no item is removed" and
//! verify it against a future release — that is `check_public_api.py`'s job
//! against the baseline, and `public_path_tests`'s against the shape. This gate
//! checks the narrower thing: that when Appendix D states a fact about this
//! build, it is a fact about this build.

use std::collections::BTreeSet;

const APPENDIX_D: &str = include_str!("../docs/architecture/appendices.md");
const BASELINE: &str = include_str!("../docs/architecture/public-api.txt");
const MANIFEST: &str = include_str!("../Cargo.toml");
const SNAPSHOT_RS: &str = include_str!("../src/temporal/snapshot.rs");
const FOUNDATIONS: &str = include_str!("../docs/architecture/s0-s3-foundations.md");

/// Appendix D's text, so a number that happens to appear in Appendix A or C
/// cannot satisfy an assertion about the contract.
fn contract() -> &'static str {
    let start = APPENDIX_D
        .find("## Appendix D — The stability contract (normative)")
        .expect("Appendix D is in docs/architecture/appendices.md");
    &APPENDIX_D[start..]
}

/// The value of a `const NAME: TYPE = VALUE;` in a source file.
fn const_value(src: &str, name: &str) -> String {
    let at = src
        .find(&format!("{name}: "))
        .unwrap_or_else(|| panic!("{name} is declared"));
    let rest = &src[at..];
    let eq = rest.find('=').expect("the constant has an initialiser");
    rest[eq + 1..]
        .split(';')
        .next()
        .expect("the initialiser is terminated")
        .trim()
        .to_string()
}

#[test]
fn the_contract_names_the_surface_the_baseline_holds() {
    let items = BASELINE
        .lines()
        .map(str::trim_end)
        .filter(|l| !l.is_empty() && (!l.starts_with('#') || l.starts_with("#[")))
        .count();

    // Written the way the document writes it, thousands separator included.
    let stated = format!("**{},{:03} items**", items / 1000, items % 1000);
    assert!(
        contract().contains(&stated),
        "Appendix D does not say {stated}, and `public-api.txt` holds {items} \
         items. That figure is what a caller reads to know how large the thing \
         being frozen is; it is regenerated by \
         `python scripts/check_public_api.py --bless` and has to be carried \
         here in the same commit (D-211)."
    );
}

#[test]
fn the_contract_names_the_schema_and_container_versions_the_code_has() {
    let schema = macrame::schema::SCHEMA_VERSION;
    assert!(
        contract().contains(&format!("**v{schema}** today")),
        "Appendix D does not say `**v{schema}** today` for the schema version, \
         and `SCHEMA_VERSION` is {schema}. A migration rung is a minor version \
         and this is the sentence that says so (D-211)."
    );

    // Private to `snapshot.rs` by design — the format version is not API — so
    // it is read the way `doc_sync_tests` reads other private facts.
    let container = const_value(SNAPSHOT_RS, "SNAP_FORMAT_VERSION");
    assert!(
        contract().contains(&format!("**v{container}** today")),
        "Appendix D does not say `**v{container}** today` for the snapshot \
         container, and `SNAP_FORMAT_VERSION` is {container}. D-043 makes an \
         unknown version a refusal rather than a parse, which is only a safe \
         promise while the document knows which version that is (D-211)."
    );
}

#[test]
fn the_contract_names_the_msrv_the_manifest_declares() {
    let msrv = MANIFEST
        .lines()
        .map(str::trim)
        .find_map(|l| l.strip_prefix("rust-version = \""))
        .and_then(|r| r.split('"').next())
        .expect("the manifest declares an MSRV");

    assert!(
        contract().contains(&format!("**{msrv}** today")),
        "Appendix D does not say `**{msrv}** today` for the MSRV, and \
         `Cargo.toml` declares {msrv}. The floor is not this crate's to choose \
         — it comes through libsql-ffi's build dependency — which is exactly \
         why the document has to be told when it moves (D-211)."
    );
}

#[test]
fn the_contract_names_the_doctrines_that_exist() {
    let doctrines: BTreeSet<&str> = FOUNDATIONS
        .match_indices("<a id=\"doctrine-")
        .map(|(i, _)| {
            let rest = &FOUNDATIONS[i + 16..];
            &rest[..rest.find('"').expect("the anchor is closed")]
        })
        .collect();

    let n = doctrines.len();
    let stated = match n {
        8 => "The eight doctrines",
        _ => "",
    };
    assert!(
        !stated.is_empty() && contract().contains(stated),
        "§0 defines {n} doctrines ({doctrines:?}) and Appendix D says \
         \"the eight\". A doctrine is the one thing here that is not a version \
         boundary at all, so the count is not a detail (D-211)."
    );
}

#[test]
fn the_documents_are_shaped_the_way_these_tests_assume() {
    // A `contract()` that returned an empty string would pass every `contains`
    // above only if they also failed; this is the floor that says it did not.
    assert!(
        contract().len() > 2_000,
        "Appendix D parsed to {} bytes; the heading changed and these tests are \
         measuring nothing",
        contract().len()
    );
    assert!(contract().contains("### D.1 — What 1.0 freezes"));
    assert!(contract().contains("### D.2 — What 1.0 does not freeze"));
    assert_eq!(const_value(SNAPSHOT_RS, "SNAP_FORMAT_VERSION"), "4");
}