Zdůvodnění
project.interfaces-are-projections už říká, že schopnost se definuje jednou a každé rozhraní z ní vychází, a sady crate to už dokazují v obou směrech pro MCP, HTTP a OpenAPI: deklarovaná projekce existuje a žádná projekce nenese položku, kterou registr nedrží. Na těchto třech transportech už nemůže nic selhat, protože žádný z nich nemá co deklarovat sám.
Příkazová řádka ano. Je to jediná projekce, která nese příkazy nad rámec schopností — spouští servery, zapisuje generované soubory, vykresluje hodnoty pro člověka — a je tedy jediným místem, kde operace může skončit mimo API, aniž by to kdokoli zvolil. Změřeno v den, kdy toto pravidlo přistálo, měla příkazová řádka třiapadesát spustitelných příkazů; sedmnáct bylo vázáno na schopnost a šestatřicet nebylo vázáno na nic. Při čtení jednoho po druhém byla většina v pořádku a několik ne, a obě skupiny nešlo rozlišit jinak než čtením jednoho po druhém, což je stav, který toto pravidlo ukončuje.
Náprava není vtěsnat každý příkaz do trasy HTTP. Kdyby se majordomus serve stalo endpointem, žádali bychom server, aby se stal jiným serverem; kdyby majordomus generate zapisovalo soubory přes API jen pro čtení, porušilo by první slib executable. Náprava je, že absence je výrok, který někdo učinil a stroj kontroluje, a ne mezera.
Slovník je důležitější než mechanismus. Existují čtyři strukturální důvody, proč příkaz v tomto spustitelném souboru patří jen příkazové řádce — stane se procesem, zapisuje do repozitáře, odpovídá o checkoutu volajícího, nebo je jiným jménem příkazu, který už je zaúčtován — a pátý pro vykresluje schopnost, což vůbec není absence: operace je v API a příkaz je její terminálové vykreslení, takže klasifikace jmenuje schopnost a kontrola odmítne tvrzení, pokud tato schopnost neexistuje a neodpovídá přes HTTP. Záměrně neexistuje důvod znamenající „zatím nepromítnuto“. Čtení, které patří do API a chybí v něm, je vada, a slovník, který ji umí zdvořile vyjádřit, je slovník, který ji vyrobí.
Požadované chování
Každý spustitelný příkaz cli::tree() — list nebo rodič, který něco dělá, když po něm nenásleduje podpříkaz, obojí čtené z vlastní deklarace clap a nikdy ze seznamu — je buď svázán se schopností přes její CliExposure, nebo nese záznam v cli::LOCAL s jedním z pěti typovaných důvodů a jednou větou právě o tomto příkazu.
Příkaz, který jen seskupuje jiné, není pro tento účel příkaz: nic nespouští, takže pro něj není operace, kterou by byl nebo která by mu chyběla, a příkaz, který získá povinný podpříkaz, přestane být spustitelný toutéž úpravou, která to způsobí.
cli::LOCAL žije vedle deklarace clap, ke které patří, ze stejného důvodu jako cli::EXAMPLES: kdo přidává příkaz, dívá se na ten soubor, a tvrzení uložené kdekoli jinde zastará při refaktoringu, který s ním nikdo nespojí.
Každá schopnost, která deklaruje trasu HTTP, je popsána generovaným dokumentem OpenAPI a každá operace, kterou dokument popisuje, je deklarována schopností.
Chování při selhání
majordomus quality report hlásí, s kódy OPERATION_CLI_UNCLASSIFIED pro příkaz, který není ani jedno, OPERATION_CLASSIFICATION_STALE pro položku jmenující příkaz, schopnost nebo cíl aliasu, které neexistují, OPERATION_CLASSIFICATION_CONFLICT pro příkaz, který je zároveň vázán i klasifikován, OPERATION_MISSING_OPENAPI pro deklarovanou routu, kterou dokument nepopisuje, a OPERATION_PROJECTION_ORPHAN pro operaci, kterou dokument popisuje a žádná schopnost nedeklaruje. Příkaz končí s 10, kdykoli cokoli platí, a kontrola rust-quality v .ai/repo/ci/gates.yaml jej spouští.
Tři způsoby, jak to pokazit, jsou tři nálezy a žádný z nich nelze způsobit zapomenutím: přidání příkazu vyvolá první, odebrání druhý a povýšení klasifikovaného příkazu na schopnost bez odstranění jeho záznamu třetí.
Ověření
cargo test --manifest-path apps/majordomus-cli/Cargo.toml quality::parity, který spouští inspekci proti skutečnému registru a skutečnému stromu příkazů a ověřuje, že žádná položka cli::LOCAL není zastaralá, že čistá skupina se nepovažuje za příkaz a že dokument OpenAPI, kterému chybí deklarovaná routa, je hlášen jednou za routu.
apps/majordomus-cli/tests/quality.rs, který ověřuje vlastnost, pro niž toto pravidlo existuje: každý spustitelný příkaz je zohledněn právě jednou a obě evidence se nepřekrývají.