majordomus rules

Efektivní sada pravidel: každé aktivní pravidlo vendorované pod sekcí pravidel repozitáře plus každé aktivní pravidlo, které repozitář napsal, vyřešené jako graf závislostí. Jen pro čtení v každém podpříkazu kromě vendor update.

Pravidlo je soubor Markdown s YAML front matter. Jeho identitou je id a version z front matter, nikdy název souboru. docs/DOCTRINE.md popisuje formát, blok x-majordomus, který váže pravidlo na validátor, a co je dnes autoritativní.

$ majordomus rules list
majordomus.scope-integrity                 v1  blocking  vendor:majordomus enforced by check,finish,watch
majordomus.sessions-are-workers            v1  advisory  vendor:majordomus no validator; see the rule
project.english-only                       v1  blocking  project          proven by scripts/ci/english-only-check
project.clean-room                         v1  blocking  project          review-enforced: the rule is about the provenance of what was written, which no program in this tree can read

• list [--json] vypíše účinnou sadu v pořadí řešení: identita, třída, původ (vendor:<name> nebo project) a způsob vynucování. Tři režimy, které popisuje DOCTRINE.md: enforced by <commands> pro pravidlo, které spouští dispatcher, proven by <paths> pro pravidlo, které drží kontrola nebo případ, a review-enforced: <reason> pro pravidlo, které nese reviewed_because vysvětlující, proč ho žádný program nevyjádří. Pravidlo bez bloku x-majordomus říká no validator; see the rule, místo aby se skrylo: je normativní pro každého, kdo ho čte, a nic ho strojově nekontroluje.

  Tento příkaz odpovídá na to, co pravidla jsou. Co každé z nich prokazuje — zda případ, který jmenuje, ve stromu stále je, zda jej některý runner řídí, zda jej kdy někdo spustil a zda je ten běh starší než to, čeho se týká — je jiná otázka a odpovídá na ni spustitelný soubor: majordomus-cli rules report, rules show <id>, rules proves <test>.

• show <id> vypíše jedno pravidlo, front matter a tělo, s cestou relativní k repozitáři, z níž bylo přečteno, jako prvním řádkem. Id mimo efektivní sadu skončí kódem 12.

• vendor status porovná vendorovaný základ s balíčkem, který dodává běžící spustitelný soubor. Vypíše obě revize, pak integritu manifestu vendorované kopie a nakonec, zda jsou oba balíčky stejné.

• vendor diff je prověřitelný rozdíl mezi oběma, jako unified diff obou adresářů. Skončí s kódem 0, ať se liší, nebo ne; vendor status nese výstupní kód.

• vendor update [--force] nahradí vendorovaný základ balíčkem spustitelného souboru. Zápis je atomický: nový balíček se připraví vedle cíle a prohodí se. Nikdy se nedotkne rules/project/.

Řešení selhává uzavřeně. Chybějící závislost, závislost na zastaralém pravidlu, cyklus, jedno id@version nárokované dvěma soubory, projektové pravidlo ve jmenném prostoru dodavatele, poškozený nebo neúplný front matter, neznámý klíč front matteru nebo blok x-majordomus, který nejmenuje žádný validátor, žádný vynucující příkaz nebo žádný test — každé z toho zastaví list, show i každý příkaz, který čte danou sadu, s kódem 10 a důvodem. Nic se neaplikuje částečně. Pořadí je deterministické: dva běhy se shodnou a každá závislost je uvedena před pravidlem, které na ní závisí.

Vendorovaná kopie repozitáře je autoritativní. Novější spustitelný soubor hlásí novější základ přes vendor status a vendor diff; nikdy žádný neaplikuje. update, doctor a check nechávají vendorovaný adresář na pokoji. Základ se mění, jen když se o to požádá vendor update.

Ruční úprava pod vendor/ je zjištěna. Manifest balíku uvádí každý soubor pravidel s jeho hashem. Soubor, jehož hash už nesedí, uvedený soubor, který chybí, nebo soubor vedle manifestu, který v něm není uveden, hlásí vendor status a odmítá vendor update, dokud --force.

test/cases/67_rule_dag.sh dokazuje každé odmítnutí mutací a dokazuje, že balíček novější distribuce se neuplatní, dokud o to nikdo nepožádá, že vendor update ponechá rules/project/ bajt po bajtu, jaké bylo, a že rozřešené pořadí je napříč běhy stejné.