Co to znamená
Příkaz nativní příkazové řádky v Rustu nemůže existovat potichu. Cokoli vypisuje --help, vypisuje i reference pod /docs/cli/, stejnými slovy, protože obojí jsou projekce jedné deklarace v apps/majordomus-cli/src/cli.rs. Příkaz, který běží sám — na rozdíl od rodiče, který jen seskupuje příkazy pod sebou — musí nést aspoň jeden příklad a ten není próza: je to vektor argumentů s názvem, popisem, tím, co muselo proběhnout před ním, a typovaným tvrzením o tom, co jeho spuštění musí vytvořit. Příkazová řádka, kterou čtenář vidí na stránce, se skládá z tohoto vektoru, takže neexistuje druhý zápis, který by zastaral.
Příklady se poté spouštějí. apps/majordomus-cli/tests/cli_docs.rs vezme stejná metadata, jaká stránka vykresluje, a provede je proti zkompilovanému binárnímu souboru v jednorázovém repozitáři, jeden na příklad — včetně dvou dlouho běžících příkazů, které se spustí, otestují a zastaví. Kde se příklad záměrně neprovádí, říká to a říká proč, vlastními slovy, na vlastní stránce. „Zdokumentováno“ a „otestováno“ je tedy tentýž objekt, ne dvě věci, které se náhodou shodují.
Princip
cli::tree() prochází sestavený clap Command a ke každému uzlu připojí konstantu EXAMPLES deklarovanou vedle argumentů příkazu; výsledek, CommandDoc, nese cestu, trasu, řádek použití, každý argument s výchozí hodnotou a přijatými hodnotami a každý příklad. cli::validate_docs hlásí v jednom průchodu každý příkaz bez shrnutí, kořen bez dlouhého popisu, každý argument bez nápovědy, každý příkaz, který běží samostatně a nenese příklad, každé duplicitní id příkladu, každý příklad připojený ke špatnému příkazu a každý příklad, na který kanonický parser neodpovídá tak, jak příklad říká — každé porušení pojmenuje příkaz, soubor k úpravě a porušené pravidlo. majordomus capabilities validate jej spouští a končí kódem 10, čímž se dostane do scripts/rust-check a do jobu rust v CI bez vlastní kontroly.
Testy jsou dvě úrovně nad týmiž daty. Úroveň A parsuje každý dokumentovaný vektor argumentů a každý vektor, o kterém příklad říká, že musí běžet první, pomocí Cli::try_parse_from: přejmenovaný příznak, odstraněná hodnota enumu nebo chybějící povinný argument činí příklad okamžitě zastaralým. Úroveň B spouští každý příklad proti sestavenému programu v čerstvém fixture repozitáři — ověřuje exit kód, výstup, dokument JSON nebo JSON pointer, který očekávání pojmenovává; majordomus serve --port 0 se spustí, adresa, kterou vypíše, se přečte v termínu, jeho dokumentovaná trasa se stáhne přes skutečný socket a zastaví se uzavřením stdin; s majordomus mcp --standalone se mluví skutečným požadavkem initialize. Obojí drží stráž, která potomka zabije, ať sonda našla cokoli, takže žádný test nemůže zanechat server.
Dále po proudu se tentýž strom stává docs/generated/cli.md, cli z docs/generated/registry.json, cli a cli_pages z site/data/registry/registry.json a jednou stránkou na příkaz pod /docs/cli/. Trasa každého příkazu se odvozuje jednou, v Rustu, takže nic jiného nesluguje cestu příkazu; scripts/site-check porovnává trasy, které sestavení vytvořilo, s trasami, které program deklaruje, jako množiny a v obou směrech, a test/cases/98_cli_reference.sh dokazuje projekci úpravou stromu a sledováním, jak stránky přibývají a mizí.
Jak to vidět
majordomus capabilities validate | grep '^OK cli'
cargo test --manifest-path apps/majordomus-cli/Cargo.toml --test cli_docs
just test-shell 98_cli_reference
scripts/site-build && scripts/site-check | grep '^OK cli'Co nepokrývá
Týká se nativního příkazového řádku, toho z Rust spustitelného souboru. Životní cyklus úloh shellového nástroje je jiný program s vlastním katalogem (share/commands.yaml), vlastním vyprávěním (docs/CLI.md) a vlastními stránkami; ani jedno se z druhého negeneruje. Kontrakt vyžaduje příklad, ne dobrý: zda příklad něco učí, stále posuzuje recenzent. Jeden příklad se záměrně neprovádí — zaznamenání baseline měření nahrazuje přijaté důkazy repozitáře a vyžaduje plný měřicí běh — a nese tento důvod všude, kde se objeví, takže stránka nikdy netvrdí důkaz, který nemá.
Proč existuje
Dokumentace, kterou nikdo nespouští, tiše chátrá, a příkaz dodaný s jednořádkovým shrnutím je příkaz, který čtenář nemůže použít. Obě selhání mají stejný tvar jako drift, kterému má project.no-claim-without-test zabránit, a dostávají stejnou odpověď: dát dokumentaci tam, kde je deklarace, udělat z příkladu to, co test spouští, a nechat CI odmítnout zbytek. Zamýšleným výsledkem je, že přidat nedokumentovaný příkaz je těžší než přidat dokumentovaný.