Co to znamená
Správce změní kanonický soubor — deklaraci v Rustu, dokument, tvrzení, sémantiku příkazu — a spustí just derive. Každá commitnutá projekce tohoto souboru se přegeneruje v pořadí, v jakém na sobě projekce závisejí, a diff je změna viděná z každého rozhraní. just derive-check prokáže, že commitnutý strom je to, co jeho zdroje produkují, nic nezapisuje a jmenuje každý zastaralý artefakt v jedné zprávě; CI a workflow Pages spouštějí stejný skript. Nikdo si nemusí pamatovat, který generátor spustit po které úpravě; ví to graf.
Princip
scripts/derive je graf vypsaný jednou, ve třech stupních. Stupeň A, majordomus generate: projekce závislé jen na kódu — docs/generated/{openapi.json,registry.json,capabilities.md,cli.md,modules/*.md}, share/allow/*.txt, bootstrapy providerů. Stupeň B, scripts/generate-site-data: data a obsah webu a odvozené dokumenty (docs/SITE_CLAIMS.md, docs/PLAN_STATUS.md), z kanonických souborů a z manifestu registru a dokumentu OpenAPI ze stupně A. Stupeň C, znovu majordomus generate: datová sada registru webu a matice měření výkonu, které čtou index vrstvy, a dokumenty, které zapsal stupeň B, jsou objekty tohoto indexu. Žádný stupeň nečte svůj vlastní výstup a výstupy stupně C nečte nic než sestavení webu, takže graf nemá cyklus a druhý běh na čistém stromu nezmění nic.
scripts/derive-check spustí majordomus generate --check a scripts/generate-site-data --check, obojí před ukončením, a skončí kódem 10, když některý našel zastaralý soubor. První pokrývá každou projekci registru, schémata, politiku a index; druhý pokrývá data webu podle otisku vstupů, který zahrnuje manifest registru a dokument OpenAPI, takže schopnost upravenou v Rustu zachytí první a manifest přegenerovaný bez webu druhý.
Commit, z něhož byla stránka sestavena, je fakt buildu, ne odvozeného souboru: scripts/site-build zapisuje site/data/build.json a site/static/build.json (servírováno na /build.json) s commitem, informací, zda byl strom špinavý, hashem vstupu webu a otisky registru a indexu; ani jeden se necommituje. source.json commit nesl dřív, což dělalo generátor webu neidempotentním na čistém stromě a vyjímalo jeden soubor z pravidla, kterému podléhá každý jiný odvozený soubor.
Jak to vidět
git status --short # clean
just derive # three stages, ~30 s
git status --short # still clean: nothing to regenerate
just derive-check # every derived artifact is current
sed -i '' 's/Search objects/Find objects/' apps/majordomus-cli/src/capability/builtin/objects.rs
just derive-check # exit 10: docs/generated/... (differs), site/data/registry/registry.json (differs)
just derive && just derive-check # in sync again, with the change in every projection
git checkout apps/majordomus-cli docs siteCo nepokrývá
Generátory vlastní své výstupy a své kontroly; skripty orchestrují a nepřidávají nic vlastního. Odvozený soubor, který generátor neporovnává (dnes žádný takový není), by se neporovnával ani zde. Soubory jen pro build (site/content/**, site/public/**, build.json) se přestavují scripts/site-build a dokazuje je scripts/site-check, ne tato kontrola.
Proč existuje
Dva generátory vyrostly vedle sebe, každý s vlastním vstupním bodem a vlastní kontrolou, a pořadí mezi nimi byl komentář v justfile, který přestal platit, jakmile web začal spotřebovávat projekce spustitelného souboru. test/cases/51_derived_artifacts_committed.sh dokazuje, že commitnuté odvozené soubory odpovídají svým zdrojům a že žádný z nich neobsahuje commit, do něhož přistává — včetně source.json, protože výjimka zanikla — a tam, kde je cargo k dispozici, že scripts/derive-check v tomto checkoutu projde.