Každý odkaz, který moment činí, se rozliší proti věci, kterou pojmenovává, a ten, který se nerozliší, je chyba nesoucí nejbližšího kandidáta

Co to znamená

Okamžik pojmenovává věci: publikum, které ho pozná, provozní oblasti, do kterých spadá, jiné okamžiky, příkazy a schopnosti, které na něj odpovídají, tvrzení, jež říkají, co je zaručeno, pravidla, která ho řídí, a případy užití, které ukazují cestu ven. Každé z těchto jmen se kontroluje proti věci, kterou pojmenovává, a jméno, které se nepřeloží na nic, je chyba — s nabídkou nejbližšího existujícího jména, pokud hodnota vypadá jako překlep.

.ai/repo/why/moments/two-agents-one-bug.md:audiences
unknown audience reference: "ai-nativ-team"
did you mean: ai-native-team

Princip

majordomus why validate rozlišuje každý odkaz proti jeho vlastnímu registru: publikum, oblasti a související okamžiky proti katalogu; příkazy proti registru příkazů; id schopností proti registru spustitelného souboru; tvrzení proti docs/CLAIMS.yaml; pravidla proti efektivní množině pravidel; případy užití proti sekci případů užití vrstvy. Kandidátem je nejbližší podle editační vzdálenosti, v mezích, které se škálují s délkou hodnoty.

Tentýž příkaz hlásí dvě další třídy chyb: soubor, jehož jméno nesouhlasí s id v něm, s uvedením jména, jaké mít má; a dva soubory nárokující jednu identitu, které index vyloučí a katalog je hlásí, místo aby se hlásil jako platný nad objekty, které z něj byly odebrány.

Jak to vidět

majordomus why validate                          # every finding; exit 10 when any is an error
majordomus why validate --format json | jq '.findings[] | {path, field, message, did_you_mean}'
cargo test -p majordomus-cli --test why
bash test/run.sh 98_why_catalogue

apps/majordomus-cli/tests/why.rs zapíše moment jmenující publikum, které neexistuje, a ověří zjištění, jeho pole a nabídnutého kandidáta; totéž udělá pro související moment, který neexistuje, pro soubor, jehož název nesouhlasí s id, a pro dva soubory nárokující jednu identitu. test/cases/98_why_catalogue.sh dokazuje tytéž tři případy z příkazového řádku, s exit kódem.

Co nepokrývá

Kontroluje, že se jméno přeloží, ne že bylo správné ho uvést. Okamžik může pojmenovat tvrzení, které s ním nemá nic společného, a validace projde.

Proč existuje

Moment je většinou odkazy — na publika, oblasti, příkazy, schopnosti, tvrzení, pravidla a případy užití — a každý z nich je jméno, které člověk napsal do souboru Markdown. Nekontrolovaná se tato jména tiše kazí: příkaz se přejmenuje, id tvrzení se změní a moment dál jmenuje to staré. Nic se nerozbije, takže si toho nikdo nevšimne, a katalog se pomalu stává souborem stránek popisujících nástroj, který už neexistuje.

Kandidát nabízený při těsném minutí tam je proto, že chyba je téměř vždy překlep, nikoli špatný nápad, a validátor, který řekne jen „neznámé“, nutí autora znovu číst seznam, který už četl. Dva soubory nárokující jednu identitu se hlásí zde, místo aby se přešly, protože index odstraní oba, a katalog, který by se prohlásil za platný nad objekty, jež z něj byly vyňaty, by vypovídal o něčem jiném než o repozitáři.