Zdůvodnění
Příkazový řádek je povrch, se kterým se většina lidí setká první, a jeho dokumentace hnije specifickým způsobem: struktura zůstává zhruba správná, protože --help je generováno, zatímco příklady — část, kterou čtenář skutečně kopíruje — tiše přestávají fungovat. Příklady jsou polovina, kterou žádný překladač nekontroluje, a proto je to polovina, která se musí spouštět. project.rust-canonical-declaration už říká, že operace spustitelného souboru existuje v jedné deklaraci; toto pravidlo říká totéž o dokumentaci příkazového řádku a přidává část, kterou ta deklarace sama dát nemůže: důkaz, že to, co stránka ukazuje, stále běží.
Požadované chování
Deklarace clap v apps/majordomus-cli/src/cli.rs je struktura: každý příkaz, argument, výchozí hodnota a přijatá hodnota. Typovaná metadata vedle ní ve stejném souboru (cli::EXAMPLES) jsou příklady: id, titulek, popis, vektor argumentů, co se musí nejdřív připravit a co musí běh ukázat. Příkazový řádek, který čtenář kopíruje, se vykresluje z vektoru argumentů a nikdy se nepíše podruhé.
Každý příkaz, který může člověk spustit, nese alespoň jeden příklad. Zda lze příkaz spustit, se čte z clap, nikdy ze seznamu: příkaz bez čehokoli pod sebou nebo takový, jehož podpříkaz je volitelný. Příkaz, který jen seskupuje jiné příkazy, žádný nenese.
cli::validate je kontrakt na jednom místě, hlásící každé porušení jednoho běhu: příkaz bez shrnutí, argument bez nápovědy, výčtová hodnota, která nic neříká, duplicitní id příkladu, příklad, který parser nepřijme, příklad u příkazu, který nespouští, sada příkladů pro neexistující příkaz a spustitelný příkaz bez příkladu. Každé porušení jmenuje příkaz, soubor k úpravě a pravidlo, které porušilo.
Každá projekce se odvozuje z toho jednoho stromu a regeneruje se se změnou, která ho posunula: docs/generated/cli.md, docs/generated/cli.json, cli z site/data/registry/registry.json, site/data/generated/cli.json a jedna trasa na příkaz pod /docs/cli/. Trasa příkazu se počítá jednou, ve spustitelném souboru, a nese se v datech; žádný konzument si nevyrábí vlastní. Nikde jinde se neudržuje seznam příkazů, voleb, příkladů ani tras — ne v šabloně, ne v navigaci, ne v dokumentu, ne v testu.
Nástroj shell bin/majordomus je jiný program. share/commands.yaml a docs/CLI.md jsou jeho a ani jeden není kanonický pro spustitelný soubor v Rustu; oba povrchy příkazů jsou dokumentovány odděleně a jejich routy se nepřekrývají.
Chování při selhání
majordomus capabilities validate vypíše porušení a skončí kódem 10; apps/majordomus-cli/tests/cli_docs.rs shodí sadu testů crate kvůli stejnému kontraktu a tests/cli_examples.rs selže, když dokumentovaný příklad přestane jít zpracovat, přestane běžet, přestane odpovídat tím, na co je dokumentován, nebo po sobě zanechá proces. majordomus generate --check a scripts/derive-check selžou na jakékoli zastaralé projekci. scripts/site-check selže na příkazu bez cesty, cestě bez příkazu, stránce, která nevykresluje své argumenty nebo kotvy příkladů, chybějícím odkazu nahoru nebo dolů a cestě příkazu zapsané ručně do šablony, generátoru nebo navigace. scripts/site-probe selže, když deklarovaná cesta neodpovídá nebo když stránka příkazu neukazuje, co její data říkají, že ukazuje. Recenzent odmítne příkaz přidaný bez příkladu a úpravu generované reference CLI.
Ověření
apps/majordomus-cli/tests/cli_docs.rs a apps/majordomus-cli/tests/cli_examples.rs; majordomus capabilities validate; just derive a just derive-check; scripts/site-check a scripts/site-probe nad sestaveným webem.