mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! The shape rules this project states about its own source.
//!
//! # Why this file exists
//!
//! The project holds a ceiling of 500 lines per file, and nothing enforced it.
//! It drifted: one proof file reached 1439 lines of code, nearly three times
//! the ceiling, and was found by an audit rather than by a build. A rule that
//! only a reader can break is a rule that gets broken by whoever is not reading
//! it that day.
//!
//! # What is measured
//!
//! A line counts when it is neither blank nor a comment written on its own
//! line. That is this test's own definition, stated here rather than borrowed,
//! because a test that quietly means something different from what it says is
//! the failure this whole suite exists to avoid.
//!
//! Measured against `tokei` across all 150 sources when this was written, the
//! two agree exactly on most files and this one runs up to eight lines higher
//! on the rest, never lower. Being the stricter of the two is the right way
//! round for a ceiling: it refuses slightly early and never slightly late.

/// The most lines of code one file may carry.
const CEILING: usize = 500;

/// Every file the ceiling applies to, with the lines each one carries.
fn measured() -> Vec<(String, usize)> {
    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
    let mut found = Vec::new();
    for start in ["src", "tests"] {
        gather(&root.join(start), root, &mut found);
    }
    found
}

/// Reads every Rust source under one directory and measures it.
fn gather(directory: &std::path::Path, root: &std::path::Path, found: &mut Vec<(String, usize)>) {
    let entries = std::fs::read_dir(directory).expect("a readable directory");
    for entry in entries {
        let path = entry.expect("a readable entry").path();
        if path.is_dir() {
            gather(&path, root, found);
            continue;
        }
        if path.extension().is_none_or(|kind| kind != "rs") {
            continue;
        }
        let text = std::fs::read_to_string(&path).expect("a readable source");
        let carried = text
            .lines()
            .map(str::trim_start)
            .filter(|line| !line.is_empty() && !line.starts_with("//"))
            .count();
        let name = path
            .strip_prefix(root)
            .unwrap_or(&path)
            .to_string_lossy()
            .into_owned();
        found.push((name, carried));
    }
}

/// No file carries more than the ceiling the project states.
///
/// Every file over it is named with its size, rather than the first one found,
/// because a run that reports one file at a time turns a single split into as
/// many runs as there are oversized files.
#[test]
fn no_file_carries_more_than_the_stated_ceiling() {
    let mut over: Vec<(String, usize)> = measured()
        .into_iter()
        .filter(|(_, carried)| *carried > CEILING)
        .collect();
    over.sort_by_key(|(_, carried)| std::cmp::Reverse(*carried));

    assert!(
        over.is_empty(),
        "the ceiling is {CEILING} lines and these carry more, largest first: {over:?}"
    );
}

/// The measurement reaches the sources it claims to reach.
///
/// Without this, a wrong root or a changed layout would leave the test above
/// measuring an empty list and passing, which is the cheapest way for a guard
/// to stop guarding while still reporting success.
#[test]
fn the_measurement_actually_reaches_the_source() {
    let found = measured();
    assert!(
        found.len() > 100,
        "expected the whole source tree, found {} files",
        found.len()
    );
    assert!(
        found.iter().any(|(name, _)| name.contains("lib.rs")),
        "the library root is expected among the measured files"
    );
    assert!(
        found.iter().all(|(_, carried)| *carried > 0),
        "a source measured as empty means the reader, not the source, is wrong"
    );
}