Zdůvodnění
Kompilátor už odmítá exportovanou položku bez dokumentace: #![warn(missing_docs)] v lib.rs a -D warnings v kontrole činí její absenci selháním buildu. To nezachytí nic o tom, zda je dokumentace hodna čtení, a nezachytí vůbec nic o příkladech, kde žije to zajímavé selhání.
Próza o chování se rozchází s realitou. Rozchází se tiše, rozchází se ve směru toho, co kód dělal dřív, a žádná kontrola v tomto repozitáři to nemohla vidět — protože próza se nespouští. Příklad se spouští: cargo test --doc ho zkompiluje proti skutečným signaturám a provede proti skutečnému chování, takže zastaralý příklad je červený build, a ne odstavec, který uvede v omyl dalšího čtenáře. To je celý argument pro toto pravidlo a je to stejný argument, který project.rust-command-tested-in-file už uplatňuje pro příkazy. Toto pravidlo ho zobecňuje z modulů příkazů na celý povrch.
Druhá polovina je hranice. Modul je koncepční jednotka — něco vlastní, má invarianty, má sousedy — a modul, který neříká, co vlastní, je adresář s .rs na konci. Když toto pravidlo poprvé změřilo crate, každý exportovaný modul měl hlavičku a méně než jeden z deseti v ní měl příklad a čtvrtina neměla vedle sebe žádný test ani žádný test, který by je pojmenovával. To jsou moduly, kde změna nerozbije nic viditelného, což je přesně tam, kde se změny pokazí. Aktuální čísla zde nejsou napsána: počítá je majordomus quality report --summary.
Třetí část je to, co pravidlo nevyžaduje, a je to záměrné. Pole, varianta, konstanta, static a alias typu jsou pojmenované a typované; příklad jednoho z nich je příkladem čehokoli, co ho čte, a pravidlo, které by jej vyžadovalo, by bylo splněno s assert!(true) uvnitř bloku kódu — ceremoniálem, který toto pravidlo existuje, aby odmítlo. Totéž platí pro accessor, jehož tělo vrací to, co příjemce již drží. Politika proto klasifikuje každou položku podle jejího druhu a tvaru, odvodí, co po ní smí chtít, a vypíše, co nežádala, s důvodem. Neexistuje soubor výjimek, protože soubor výjimek je místo, kam lze přidat řádek.
Toto pravidlo nenahrazuje project.rust-command-tested-in-file a obě mají jiný předmět. To pravidlo se týká modulů, které aplikace skládá — každého z nich, ať je jeho viditelnost jakákoli — a žádá jedno tvrzení vedle deklarace v kterékoli z přijatých forem. Toto se týká toho, co crate exportuje komukoli, a žádá příklad i test. Modul schopnosti, který je pub(crate), drží první pravidlo a druhé ne, což je správně: pořád je to příkaz a není to API.
Přísné pravidlo o exportovaném povrchu je také pravidlem o tom, jak velký ten povrch je. Tento crate je publish = false: jeho spotřebiteli jsou jeho vlastní binárka, testy, měření výkonu a příklady v dokumentaci a nic jiného. Položka, kterou žádný spotřebitel nepotřebuje, stojí podle tohoto pravidla doc komentář a příklad a správnou odpovědí na tuto cenu je obvykle pub(crate). To je zamýšlený tlak, ne jeho vedlejší efekt.
Požadované chování
Každá položka, kterou crate exportuje — dosažitelná z kořene crate přes moduly pub nebo vynesená ze soukromého pub use — nese dokumentaci. Kde položka nese chování (modul, typ, trait, funkce, metoda, exportované makro), ta dokumentace říká něco, co signatura ne, a obsahuje aspoň jeden oplocený blok, který toolchain kompiluje: žádné ignore, žádný oplocený rámeček prózy, který by ho zastupoval.
Příklad se počítá, když je zkompilován, když jmenuje položku, kterou dokumentuje, a když ověřuje něco, co by mohlo být nepravdivé. assert!(true), assert_eq!(1, 1) a aritmetická identita nejsou tvrzení o položce; unwrap, expect a ? jsou, protože selhání kteréhokoli shodí doctest. no_run se počítá a ignore ne: rozdíl je v tom, zda jej toolchain zkompiloval.
Každý exportovaný modul nese hlavičku //!, která vysvětluje hranici, místo aby ji jen pojmenovala, alespoň jeden spustitelný příklad svého životního cyklu a behaviorální pokrytí: test #[cfg(test)] vedle deklarace nebo test pod tests/, který modul jmenuje. Platí obě formy, z důvodu, který uvádí project.rust-command-tested-in-file — vyžadovat konkrétní z nich by koupilo formální test vedle skutečného příkladu.
To, co politika od položky nežádá, se odvozuje z druhu a tvaru té položky a hlásí se jako výjimka s důvodem. Nic výjimku nedeklaruje a neexistuje soubor, do kterého by se zapsala.
Chování při selhání
majordomus quality report změří crate a odpoví typovaným reportem: počty a jeden nález na porušení, nesoucí stabilní kód, pravidlo, soubor a řádek, symbol, proč na tom záleží a co udělat. Kódy jsou RUST_PUBLIC_MISSING_DOCS, RUST_PUBLIC_THIN_DOCS, RUST_PUBLIC_MISSING_EXAMPLE, RUST_EXAMPLE_NOT_EXECUTABLE, RUST_EXAMPLE_PLACEHOLDER, RUST_EXAMPLE_DOES_NOT_NAME_SUBJECT, RUST_MODULE_MISSING_DOCS, RUST_MODULE_MISSING_EXAMPLE a RUST_MODULE_MISSING_BEHAVIOURAL_TEST. Příkaz končí s 10, když stojí kterýkoli z nich, což je kód, který používá každá další nesplněná smlouva v tomto executable, a JSON i lidské vykreslení jsou dvě čtení jedné hodnoty, takže se nemohou neshodnout na výsledku.
Měření je schopnost, takže se odpovídá stejně na příkazové řádce, přes HTTP, přes MCP i v Cockpitu. Kontrola rust-quality v .ai/repo/ci/gates.yaml jej spouští a scripts/rust-check jej spouští ve stejném pořadí jako člověk.
Vynucování je rohatka, zatímco dluh klesá. .ai/repo/rust-quality-baseline.txt zaznamenává nálezy, které platily, když toto pravidlo přistálo; kontrola selže na nález, který v něm není, takže dluh může klesat a nemůže růst. To je mechanismus, který popisuje a použil project.rust-command-tested-in-file, ze stejného důvodu: blokující pravidlo bez migrační cesty je pravidlo, které se vrátí zpět. Baseline zapisuje jen --write-baseline, což je záměrný akt, a pravidlo není hotové, dokud soubor není prázdný a odstraněný — prázdný seznam výjimek zve k tomu, aby do něj někdo přidal řádek.
Validátor nežije v lib/. Ta knihovna patří dodávanému nástroji a projektové pravidlo, které potřebuje kontrolu, dostane kontrolu, ne doktrínu — argumentuje tak project.rust-command-tested-in-file a toto pravidlo ho následuje. Kde není žádný Rust crate, kontrola se přeskočí a řekne to.
Ověření
cargo test --manifest-path apps/majordomus-cli/Cargo.toml quality, který měří fixture crates postavené k tomuto účelu: zdokumentovaný, s příklady a otestovaný crate nemá žádné nálezy a jeden crate na každý způsob selhání vyprodukuje přesně svůj vlastní kód a nic jiného — žádný příklad, ignorovaný příklad, zástupný příklad, příklad o něčem jiném, modul bez testu. Vlastní negativní fixtures validátoru ho drží, aby se nestal ceremoniálním.
apps/majordomus-cli/tests/quality.rs, který spouští měření nad tímto cratem přes sestavený registr a skutečný strom příkazů a vynucuje ratchet: žádné zjištění mimo základní stav.
test/cases/96_rust_public_api_quality.sh, který sestaví executable, změří přes něj fixture repozitář a ověří exit kód i JSON čistého i selhávajícího stromu.