16. Scénář je sekce těla, ne pole hlavičky
Zpřesňuje ADR 8 (případy užití jsou spustitelné kanonické objekty), které zavedlo scénář a umístilo ho do front matteru.
Kontext
ADR 8 učinilo scénář případu užití kanonickými daty a uložilo ho jako mapování scenario: ve YAML front matteru dokumentu. Funguje to — každý scénář běží — ale největší a nejméně deklarativní věc v souboru to umisťuje do poloviny souboru vyhrazené té nejmenší a nejvíce deklarativní.
Front matter je strojová strana dokumentu: čím objekt je a jak je klasifikován. Každý další klíč případu užití je jedním z toho — id, titul, kategorie, seznam příkazů, které jmenuje. scenario není nic z toho. Je to program: příprava, uspořádaný seznam volání a aserce na návratový kód a výstup každého z nich. V tomto repozitáři ten nejdelší přesahuje čtyřicet řádků, takže čtenář, který otevřel soubor případu užití, narazil na čtyřicet řádků spustitelného YAML dřív než na první větu prózy a vyprávění, které dokument existuje vyprávět — # Situation, # Outcome — bylo odsunuto pod okraj.
Povolený seznam ukazoval stejné zkreslení z druhé strany. Jedenáct z dvaceti řádků share/allow/use-case.txt byly vzory ^scenario\.steps\.[0-9]+\....$: kontrakt front matter byl většinou o něčem jiném než o front matter.
Nic o scénáři nemusí být v hlavičce. Není to identita, nic podle toho neklasifikuje a žádný výpis podle toho netřídí. Jediné, co čtenáři i nástroj potřebují, je, aby se spolehlivě našel a přesně parsoval, a pevný název sekce to zajistí stejně dobře jako pevný klíč.
Rozhodnutí
Scénář se přesouvá z front matter do sekce těla pojmenované # Scenario, která nese právě jeden oplocený blok yaml, umístěný mezi # Situation a # Outcome.
Front matter ponechává jen identitu a klasifikaci. Header.scenario z share/schemas/majordomus/use-case/use-case.v1.proto zmizelo a Body získává povinnou neprázdnou sekci Scenario, takže majordomus generate promítne sekci do share/sections/use-case.txt a zahodí každý řádek scenario.* z share/allow/use-case.txt.
Zprávy Scenario, Step, Expect a FileContains zůstávají v protu. Dosahuje se na ně z těla, ne z Header, a zůstávají jediným napsaným popisem toho, co ohraničený blok obsahuje.
Blok je YAML, nikoli próza nebo tabulka, protože scénář se stále provádí. Je to surový text v pojmenované sekci, což čtenář chce, a parsovatelný dokument, což runner potřebuje; prozaická nebo tabulková podoba by čitelnost koupila pravidly uvozování a zakázkovým parserem.
lib/usecase.sh skládá parsovaný blok zpět pod prefix scenario. téhož plochého jmenného prostoru, který vytváří front matter, takže každý čtenář pod loaderem — usecase list, validate, run, coverage, impact, generátor webu — zůstává nezměněn. Kontrola allow-listu tyto složené klíče před měřením zahodí, protože pocházejí z těla, kde místo toho platí seznam sekcí.
Důsledky
Soubor případu užití se nyní čte v pořadí, v jakém se věci dějí: situace, důkaz, výsledek. Smlouva o front matter je opět o front matter.
majordomus usecase validate vyžaduje # Scenario vedle # Situation a # Outcome a usecase scaffold zapisuje sekci místo klíče. Případ užití napsaný podle starého tvaru se naparsuje, ztratí svůj scénář a je hlášen jako aktivní případ užití cílící na záruku bez spustitelných důkazů — pojmenované selhání, ne ticho.
Generátor se nenaučil nic nového: změna je vyjádřitelná ve slovníku voleb, který share/schemas/majordomus/options.proto už měl. Sekce, jejíž obsah má deklarovaný tvar, je stále popsána jen komentářem a zprávou vedle ní; pokud ohraničené sekce poroste více druhů, stojí za to tuto vazbu v sadě voleb explicitně udělat.
Scénář už není viditelný pro konzumenta, který čte jen front matter. Nástroj nic takového neudělal — indexer v Rustu na něj nikdy neodkazoval — ale externí čtenář, který parsoval jen YAML hlavičku, by nyní musel číst tělo.