Co to znamená
Případy užití v .ai/repo/use-cases/ a aplikace v .ai/repo/applications/ popisují, k čemu Majordomus slouží. Každý příkaz, kterým případ užití prochází, každé pravidlo, o které se opírá, i každý slib, který dává, je odkaz na něco jiného v repozitáři — a každý z těchto odkazů se kontroluje. Stejně tak vztah mezi oběma soubory: případ užití, který pojmenuje aplikaci, jež jej nepojmenuje zpět, je chyba, ne asymetrie, které si někdo časem všimne.
Princip
mj_validate_catalogue v lib/doctor.sh zploští oba registry vlastním čtečem YAML nástroje a každý odkaz rozliší proti tomu, co jej definuje: příkazy proti docs/CLI.md, doktríny proti rozlišené sadě pravidel přes mj_doc_index, tvrzení proti docs/CLAIMS.yaml. Křížové odkazy mezi oběma katalogy kontrolují v obou směrech mj_cat_has a mj_cat_back. Aplikace, která nedeklaruje does_not_fit_when, je rovnou odmítnuta.
Doktrína majordomus.catalogue-integrity je blokující a vynucují ji doctor a watch, takže totéž pravidlo odpovídá na „je katalog v pořádku“ i „rozešel se“ bez druhé implementace. scripts/generate-site-data opakuje rozlišení při sestavení stránek a odmítne vydat výstup, pokud cokoli visí — rozbitý odkaz se na publikovaný web nedostane.
Jak to vidět
majordomus doctor
# OK catalogue 6 use case(s), 4 application(s) — every command, doctrine, claim and cross-reference resolves, both directionsZměňte id doktríny v případu užití pod .ai/repo/use-cases/ na neexistující a doctor pojmenuje případ užití, chybějící id a příkaz, který vypíše skutečná; majordomus usecase validate vypíše tytéž řádky.
Co nepokrývá
Rozlišení není přesnost. Případ užití, jehož kroky jsou ve špatném pořadí nebo jehož situace popisuje problém, který nikdo nemá, projde všemi zdejšími kontrolami — každý odkaz existuje. Vynucuje se, že katalog nemůže popisovat jiný nástroj než tento; zda je popsané k něčemu, je úsudek, který žádný validátor neučiní.
Proč existuje
Dokumentace k nástroji se rozchází rychleji než nástroj a rozchází se tiše, protože ji nic nespouští. Každé selhání, na kterém tomuto projektu záleží, má stejný tvar — něco je deklarováno, nic nekontroluje, že deklarace stále odpovídá skutečnosti — a próza je největší plocha, kde se to obvykle toleruje. Chápat případ užití jako sadu odkazů, ne jako text, ho činí ověřitelným, a to je jediný důvod psát ho jako data.