Zdůvodnění
Příkaz je nejmenší věc, kterou tento spustitelný soubor nabízí člověku, a právě u něj jsou důkazy nejlevnější k napsání a nejčastěji psané jinde. Crate už drží své testy vedle kódu, který si je zaslouží — webový modul drží vlastní bezpečnost cest, vlastní řazení, vlastní zamítnutí — a měřitelně je to část crate, kterou lze nejsnáze bezpečně měnit. Výjimkou jsou moduly schopností, tedy samotné příkazy: deklarují povrch, kterého se uživatel dotýká, většina z nich o něm nic netvrdí a jejich důkazy žijí v sadách, které je jmenují z dálky.
Problémem je vzdálenost, ne množství. Test v sadě pokrývá příkaz tak, jak vypadal, když na tu sadu někdo naposledy myslel; test v souboru čte každý, kdo mění deklaraci, na téže obrazovce, a jako první zčervená. Příklad v dokumentaci je silnější ještě víc, protože jej cargo test --doc spouští: dokumentace, která se vykonává, nemůže sklouznout k popisu příkazu, který se tak už nechová, což je způsob selhání, který má próza a testy ne.
Granularita je to, co umožňuje obojí. Jedna schopnost na deklaraci, jeden modul na předmět znamená, že test pojmenovává jedno chování a čtenář, který ho hledá, otevře jeden soubor. Většina toho je už vynucena a toto pravidlo to neopakuje: registr odmítne schopnost deklarovanou mimo jmenný prostor jejího modulu a odmítne duplicitní identitu — capability-modules, dokázáno případem 91. Opakovat kontrolu, která už existuje, by znamenalo druhý registr, jehož odstraňováním toto repozitář tráví čas. Co registr vidět nemůže, je modul složený do aplikace, který nedeklaruje žádný příkaz, a to je jediné zjištění granularity, které toto pravidlo přidává.
Hranice pokrytí je součástí téhož argumentu a existuje pro ni důvod z tohoto repozitáře, ne z principu. Větev, která přidala model, statický souborový server a povrch příkazů, vyšla na 89,40 % proti hranici 90. Hranice nic nenašla — odmítla se pohnout, a toto odmítnutí poslalo autora hledat. Našlo se v kódu napsaném před hodinou a považovaném za pokrytý: slovník, jehož Display a serializace se mohly rozejít, prázdný selektor, který mohl znamenat „žádné“ místo „každé“, statický povrch připojený v kořeni, povrch bez indexu. Cíl místo hranice by dovolil zaokrouhlit 89,40 nahoru na prakticky devadesát a čtyři netestované větve by se dostaly do souboru, jehož celým úkolem je rozhodnout, který povrch na požadavek odpoví.
Poslední část je kompozice. Příkaz je dosažitelný proto, že ho root skládá ze svého modulu, ne proto, že mu to někde v seznamu řekli — stejná vlastnost, kterou project.interfaces-are-projections vyžaduje od každého jiného povrchu. Modul, který nikdo neskládá, je příkaz, který existuje a nikomu se neposkytuje, a modul dosažitelný ručně vedenou registrací je řádek, na který někdo zapomene.
Požadované chování
Každý modul, který kořenové skládání skládá, žije ve vlastním souboru, deklaruje tam své schopnosti a nese v témže souboru alespoň jedno tvrzení, které běží: #[test] v souboru, nebo příklad v dokumentaci, který cargo test --doc spouští. Obě formy pravidlo splňují a volba patří tomu, kdo píše — vyžadovat konkrétní formu kupuje formální test vedle skutečného příkladu, což je obřad, ne důkaz.
Tvrzení musí být o deklaraci: že příkaz je tím, čím se prohlašuje. Modul, který jen zapojuje už otestovaný subsystém, není vyňat, protože právě zapojení nekontroluje nic jiného — vlastní sady modelu testují model, ne jeho projekci, a schopnost, která při refaktoru potichu ztratí expozici, nerozbije žádný test ležící vedle modelu. Pokud je deklarace tak tenká, že by žádné tvrzení o ní nic neznamenalo, je to důvod pochybovat o modulu, ne o pravidle.
Modul, který se deklaruje, skládá kořen a skládání je jediná cesta, kterou se k příkazu dostane. Přidání příkazu do existujícího modulu nepřidá řádek nikde jinde; přidání modulu přidá přesně jeden, ve skládání.
Crate je držen na deklarované hranici pokrytí, která žije v souboru, ne ve zvyku, a kontrola pokrytí ji čte. Hranice je číslo a je to rohatka: commitnutá dolní mez, která smí růst a nikdy klesnout. Toto pravidlo čte scripts/rust-coverage-threshold a odmítne hranici pod mezí zapsanou jednou, jako FLOOR_BOUND, v scripts/ci/rust-command-check; mez je pokrytí crate naměřené v okamžiku jejího nastavení a zvyšuje se spolu se souborem, kdykoli se pokrytí zlepší. Snížení kterékoli z nich je viditelná úprava blokující kontroly, ne tichá změna, po které všechny ostatní kontroly stále procházejí. Pokrytí je hranice, ne cíl: říká, které změny nesmějí přistát, ne kolik testování stačí.
Práh byl kdysi pevných devadesát a jako kontrola selhal. Každý zaznamenaný job coverage změřil crate mezi 83,10 a 83,34 procenta řádků s testovacím kódem mimo jmenovatele a žádný běh nikdy devadesáti nedosáhl, takže job coverage byl červený při každém pushi a jeho verdikt neříkal nic o žádné změně. Práh, který žádný běh nesplní, nekontroluje nic; změřená hodnota, držená tak, aby nemohla klesnout, odmítne každou regresi. To, co ratchet na agregátu nedělá — odmítnout nový nepokrytý kód, zatímco starý dluh drží číslo na místě — drží kontrola změněného kódu, project.new-code-is-covered, která pokrývá každý řádek, funkci a region, který změna přidá nebo se jich dotkne, ať agregát říká cokoli.
Chování při selhání
scripts/ci/rust-command-check čte složený seznam modulů ze samotného compose_modules! a hlásí pro každý modul chybějící soubor, modul bez deklarované schopnosti a absenci jakékoli běžící aserce; napříč stromem modul deklarovaný pomocí module!, který kořen nikde nesestavuje; a jednou práh pokrytí, který je nedeklarovaný, není jedno celé číslo nebo je pod svou mezí rohatky FLOOR_BOUND. Spouští jej kontrola rust-command v .ai/repo/ci/gates.yaml.
Kontrola spouští --strict: každý složený modul musí pravidlo splňovat a ten, který ne, selže při buildu. Neexistuje baseline ani seznam výjimek, protože už není co vyjímat — každý modul, který aplikace skládá, nyní v souboru, který jej deklaruje, potvrzuje, že poskytuje identitu a projekce, které si nárokuje.
Takhle to nezačalo. Pravidlo přistálo s rohatkou: moduly, které je nesplňovaly, byly zaznamenány v základním stavu zapisovaném jen příkazem --write-baseline a kontrola selhala jen pro modul, který v tom seznamu chyběl, takže dluh mohl klesat a nemohl růst. Tento mechanismus v kontrole stále je a je správným způsobem, jak zavést pravidlo proti existujícímu stromu — blokující pravidlo bez migrační cesty je pravidlo, které se vrací zpět. Prostě ho tu už nepotřebujeme a soubor základního stavu byl odstraněn, ne ponechán prázdný, protože 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 scripts/generate-site-data odmítne funkci mj_validate_*, kterou nedeklaruje žádná dodávaná doktrína — právem, protože web dokumentuje doktríny produktu a toto pravidlo je vlastní tomuto repozitáři. Projektové pravidlo, které potřebuje kontrolu, dostane kontrolu, ne doktrínu.
Tam, kde není Rust crate, se doktrína přeskočí a řekne to: vrstva se instaluje do repozitářů, které executable nenesou, a doktrína, která se nedá použít, není porušení.
Ověření
bash test/run.sh 88_rust_command_tested, který sestaví fixture obsahující složený modul s testem, jeden jen s příkladem v dokumentaci, jeden s ničím z toho a jeden deklarovaný, ale nikým nesložený, a ověří, že kontrola hlásí přesně poslední dva — aby bylo prokázáno, že obě formy tvrzení pravidlo splňují, a ne jen prohlášeno. Ověřuje také, že složený modul, který nedeklaruje žádný příkaz, je hlášen, že práh, který není jedno celé číslo nebo leží o jedna pod mezí, kterou kontrola deklaruje, je hlášen a shodí kontrolu, zatímco práh na mezi nebo nad ní ne, že modul, který už je na baseline, kontrolu neshodí, zatímco modul, který na ní není, ano, a že repozitář bez cratu se přeskočí, ne selže.
scripts/ci/rust-command-check na tomto repozitáři hlásí moduly, které stále dluží aserci, a končí nulou, dokud jsou to ty, které baseline zaznamenává.