aggrega validate
aggrega validate sprawdza poprawność — schemat, strukturę filarów, rozwiązywanie odwołań między dokumentami, łańcuchy extends, obsługę rodzaju wejścia przez provider oraz (w przypadku encji renderującej) to, czy faktycznie się renderuje. Polecenie ma trzy tryby, wybierane argumentem, które stosują tę samą dyscyplinę poprawności w trzech zakresach: całego katalogu (bez argumentu), domknięcia zależności jednej encji Release (--release) oraz jednego pliku encji (ścieżka encji). Każdy zakres odpowiada na to samo pytanie — „czy ta treść jest poprawna?” — dla innego wycinka katalogu.
Poprawność to coś innego niż konwencje. aggrega validate sprawdza, czy treść jest dobrze sformułowana i dałaby się skompilować; aggrega lint sprawdza, czy treść przestrzega dyscypliny publikowania przyjętej w katalogu (nazewnictwa, zgodności katalogów z kategoriami, wielkości podbicia wersji i pozostałych). Oba polecenia odzwierciedlają nawzajem swoje trzy zakresy, dzięki czemu każdy z tych wymiarów można sprawdzić z potrzebną szczegółowością.
aggrega validate niczego nie zapisuje na dysku i nie odczytuje stanu środowiska uruchomieniowego. Wykonuje to samo rozwiązywanie i tę samą walidację co kompilacja, zatrzymując się przed renderowaniem (lub, w przypadku pojedynczej encji, izolując je).
Ścieżkę encji można podać jako argument pozycyjny. Flaga --release podana obok ścieżki encji nie wybiera zakresu encji Release: encja nadal jest sprawdzana samodzielnie, w kategoriach tej encji Release — zob. Sprawdzanie encji w kategoriach encji Release.
Poprawność całego katalogu (bez argumentu)
aggrega validate bez argumentu wczytuje każdą encję katalogu z skonfigurowanych katalogów i sprawdza ją od początku do końca. Zanim cokolwiek wczyta, odczytuje każdy plik YAML w tych katalogach, a dokument Aggrega wśród nich, którego nie da się wczytać, zatrzymuje uruchomienie, jak opisano poniżej. Następnie:
- Struktura filaru schematu — blok
spec.schema:każdej encji Component i Feature jest rozwijany i walidowany (ta sama kontrola filaru schematu, którą stosuje kompilacja), łącznie z rozwinięciem formy kompaktowej. - Rozwiązywanie odwołań między dokumentami — odwołania
$refi$importdo wpisów SchemaLibrary są rozwiązywane, a SchemaLibrary, której nie da się rozwiązać lub która jest w inny sposób nieprawidłowa, zostaje odrzucona. - Łańcuchy
extends— każda encja deklarującaextendsjest rozwiązywana względem swojego rodzica, a scalony kształt rodzic+potomek jest sprawdzany. Rodzic, którego nie zawierają katalogi encji, jest odczytywany tam, gdzie odczytuje go kompilacja: z pamięci podręcznej artefaktów, zgodnie z przypięciem, które zapisuje dla niego plik blokady encji Release — pliki blokady encji Releases, dla których wykonywany jest przebieg, albo każdej encji Release w obszarze roboczym, gdy jest on walidowany w jednym przebiegu. Dzięki temu baza opublikowana w rejestrze przechodzi walidację, gdy tylkoaggrega pullją pobierze i przypnie, a rodzic, którego nie zawiera żadne z nich, zatrzymuje uruchomienie, wskazującaggrega pull --release <release>. Nic nie jest pobierane. - Zadeklarowane selektory — każdy selektor etykiet, który dokument Component lub Feature deklaruje przy gnieździe zależności w
spec.usesSchemaalbo przy slocie załącznika wspec.featuresSchema— w tym, w encji Component, sloty deklarowane przez gniazdo — jest odczytywany zgodnie z gramatyką selektorów, niezależnie od tego, czy cokolwiek podłącza gniazdo lub wypełnia slot. Zob. zadeklarowane selektory. - Kolizje lokalizacji OCI — dwie różne tożsamości katalogowe, które publikowałyby do tej samej lokalizacji w rejestrze, są głośno odrzucane, dzięki czemu kompilacja nigdy po cichu nie nadpisuje opublikowanych bajtów jednej encji bajtami innej.
- Provider input-kind capability — encja Recipe lub FeatureRecipe, która deklaruje blok
workload:powiązany z dostawcą niepotrafiącym przeprowadzić syntezy, jest oznaczana jako błąd, ponieważ nigdy nie da się jej zbudować.
Jest to ogólnokatalogowy odpowiednik walidacji kompilacji wykonywanej dla każdej encji Release — miejsce, w którym ma wyjść na jaw uszkodzona encja katalogu, zanim dotrze do niej jakakolwiek encja Release. Polecenie zatrzymuje się głośno na dokumencie Aggrega, którego nie da się wczytać, oraz przy każdym naruszeniu filaru schematu, nierozwiązywalnej lub nieprawidłowej bibliotece, niepowodzeniu rozwiązywania extends, zadeklarowanym selektorze odrzucanym przez gramatykę, kolizji lokalizacji lub błędzie zdolności w zakresie rodzaju wejścia. Ustalenia dotyczące nakładania się filarów schematu i zawężania przy rozszerzaniu, a także każde słowo kluczowe x-aggrega-*, które encja Component lub Feature zapisuje wprost w treści swojego schematu, są doradczymi wierszami notice:, które nigdy nie zmieniają kodu wyjścia.
Dokument Aggrega, którego nie da się wczytać, zatrzymuje uruchomienie. Plik YAML w katalogu katalogowym jest dokumentem Aggrega, gdy jeden z jego wierszy zaczyna się bez wcięcia od apiVersion: i wartości zaczynającej się od aggrega.ai/, w cudzysłowie lub bez. Taki plik, którego nie da się odczytać, którego YAML nie daje się sparsować albo którego kind lub metadata nie ma kształtu koperty encji — na przykład metadata zapisane jako lista — zatrzymuje uruchomienie z E0175 po odczytaniu katalogów, z wymienieniem każdego takiego pliku i przyczyny podanej przez odczyt lub parser; nic nie jest sprawdzane i nie jest wypisywany wiersz catalog validation passed. Dokument, który daje się wczytać i deklaruje kind, którego nie zawiera żaden katalog — na przykład błędnie zapisany Componnent albo brak jakiegokolwiek kind — zatrzymuje to samo uruchomienie z E0371 i jest wymieniany obok nich wraz z rodzajem, który deklaruje; dokumenty Manifest i Release oraz dokument Workload, który encja Recipe importuje z własnego katalogu, są pomijane. Każdy inny YAML — szablony chartu Helm, których nie da się sparsować przed wyrenderowaniem, wartości chartu, definicje przepływów pracy — jest pomijany.
To, które katalogi są odczytywane, zależy od struktury obszaru roboczego:
-
Obszar roboczy, którego konfiguracja nie podaje własnych katalogów dla encji Release, jest walidowany raz, na podstawie swojego stosu wyszukiwania: najpierw katalogi
--catalog, potemworkspace.catalog_dirs, a następnie katalogcatalogw katalogu głównym obszaru roboczego, jeśli istnieje. -
Obszar roboczy, który wymienia encje Releases w
workspace.releases, może przechowywać katalog w kilku wariantach obok siebie, z których każdy jest odczytywany przez własną encję Release, a wczytanie ich wszystkich naraz umieściłoby każdy wariant w jednym katalogu, przy czym encja jednego wariantu przesłaniałaby encję innego. Dlatego jest on walidowany raz dla każdej encji Release w obszarze roboczym, na podstawie katalogów, które ta encja Release odczytuje, przy czym katalogi--catalogsą pierwsze w każdym przebiegu; encja Release, której konfiguracja nie wymienia, odczytuje listę obszaru roboczego. Każdy przebieg jest raportowany pod wierszem podającym jego encję Release i odczytane katalogi, po którym następuje wynik tego przebiegu:Release release-compose.yaml reads catalog-composecatalog validation passed (schema-pillar + library + extends + oci-location)Release release-helm-synth.yaml reads catalog-helm-synthcatalog validation passed (schema-pillar + library + extends + oci-location)Encje Releases, które odczytują dokładnie te same katalogi, współdzielą jeden przebieg, który wymienia każdą z nich. Encja Release, która nie odczytuje żadnego katalogu — jej wpis zawiera
catalog_dirs: []— jest raportowana jako niemająca nic do sprawdzenia, a pozostałe przebiegi działają normalnie. Każdy przebieg jest raportowany niezależnie od tego, co wykrył wcześniejszy, ponieważ uszkodzona encja w jednym wariancie nic nie mówi o innym, a polecenie kończy się niepowodzeniem, gdy którykolwiek przebieg się nie powiedzie, wymieniając encje Releases, których katalogi nie przeszły walidacji. Encje Releases w obszarze roboczym to jego dokumenty Release — pliki YAML, którychkindtoRelease, znajdujące się w dowolnym miejscu pod katalogiem głównym obszaru roboczego, poza katalogami ukrytymi oraznode_modules,vendoridist.
Uruchomienie, w którym w żadnym przebiegu nie ma nic do odczytania, jest odrzucane, zamiast być raportowane jako czysty katalog: należy umieścić encje w catalog/, przekazać --catalog lub ustawić workspace.catalog_dirs — albo, w obszarze roboczym wymieniającym encje Releases, własne catalog_dirs encji Release w workspace.releases. Polecenie nigdy niejawnie nie przegląda bieżącego katalogu roboczego, więc nigdy nie wciąga niepowiązanych drzew.
Narzędzie validate polecenia aggrega mcp, poproszone o cały katalog, waliduje te same przebiegi; w obszarze roboczym wymieniającym encje Releases jego odpowiedź zawiera każdy z nich w passes — encje Releases, odczytane katalogi i własny werdykt tego przebiegu — obok werdyktu dla nich wszystkich.
Biblioteka przechowywana tylko w pamięci podręcznej artefaktów
Pamięć podręczna artefaktów przechowuje to, co umieściło w niej pobieranie, a encja SchemaLibrary z pamięci podręcznej liczy się jako treść katalogu tylko wtedy, gdy wpis w pliku blokady encji Release poświadcza jej skrót — zob. Czym jest pamięć podręczna, a czym nie jest. Gdy $ref: nie rozwiązuje się do niczego, a pamięć podręczna zawiera bibliotekę, której nie przypina żaden wpis pliku blokady i której nie dostarcza żaden katalog encji odczytywany przez sprawdzenie, po raporcie następuje wiersz remediation: wymieniający każdą taką bibliotekę i działanie skuteczne dla zakresu, który zawiódł:
- Bez argumentu oraz ze ścieżką encji, niezależnie od tego, czy podano
--release, validate odczytuje biblioteki wyłącznie z katalogów encji, nigdy przez wpis pliku blokady, więc zarejestrowany wpis nie zmieniłby jego werdyktu. Wiersz to stwierdza i wskazuje na utworzenie biblioteki w katalogu encji albo naaggrega pull --release <release>, a następnieaggrega validate --release <release>, które sprawdza encję Release względem bibliotek przypiętych w jej pliku blokady. - Z samym
--releasevalidate odczytuje plik blokady encji Release, więc wiersz wskazujeaggrega pull --release <release>, które rozwiązuje bibliotekę i rejestruje jej wpis, albo utworzenie biblioteki w katalogu encji.
Ten wiersz nie zmienia ani werdyktu, ani kodu wyjścia.
Zadeklarowane selektory
Encja Component lub Feature ogranicza za pomocą selektorów etykiet, co można podłączyć do jej gniazd zależności i co może wypełnić jej sloty załączników — selector: każdego wpisu spec.usesSchema i każdego wpisu spec.featuresSchema, a w encji Component także selector: każdego slotu, który gniazdo deklaruje we własnym featuresSchema. Kompilacja odczytuje selektor tylko tam, gdzie coś do niego dociera: krawędź poprowadzona przez gniazdo, załącznik wypełniający slot. Dlatego zakres całego katalogu i zakres pojedynczej encji odczytują każdy selektor deklarowany przez dokument Component lub Feature, niezależnie od tego, czy cokolwiek podłącza gniazdo lub wypełnia slot, a selektor odrzucany przez gramatykę — lista wartości bez nawiasu zamykającego, podwójny przecinek, klucz zawierający = lub ! — powoduje niepowodzenie kontroli. Gramatyka jest opisana w sekcji gramatyka ciągów znaków.
Odmowa jest tą samą, którą zgłasza kompilacja, gdy dociera do tego samego selektora, z tym samym kodem i tymi samymi słowami: E0007 dla selektora gniazda i E0008 dla selektora slotu, ze wskazaniem selektora, deklarującego go gniazda lub slotu oraz powodu, dla którego gramatyka nie mogła go odczytać. Jest rejestrowana jako błąd katalogu w pliku encji:
selector violation (
"<selector>", declared on socket"<socket>", which could not be evaluated:"<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (naruszenie selektora: selektora zadeklarowanego przy gnieździe nie dało się ocenić. Należy poprawić selektor w deklaracji gniazda w usesSchema typu komponentu.)
Każdy dokument jest odczytywany tak, jak napisał go autor, więc selektor zadeklarowany przez encję bazową jest zgłaszany raz, we własnym pliku bazy, a nie raz dla każdej rozszerzającej ją encji. appliesTo i appliesToAnyOf encji Feature nie są tu odczytywane: odczytuje się je wszędzie tam, gdzie oceniany jest załącznik tej encji Feature.
Zakres całego katalogu zgłasza każdy odrzucony selektor w osobnym wierszu selector: i kończy się niepowodzeniem, podając ich liczbę; zakres pojedynczej encji zgłasza je jako niepowodzenie swojego poziomu kształtu — z --release obok ścieżki encji lub bez niej, ponieważ ta postać jest zakresem pojedynczej encji uruchomionym w kategoriach encji Release (zob. sprawdzanie encji w kategoriach encji Release). Samo --release, które waliduje domknięcie zależności encji Release, oraz kompilacja odczytują selektor tylko tam, gdzie dociera do niego krawędź lub wypełnienie, i tam się na nim zatrzymują.
Poprawność w zakresie encji Release (--release)
aggrega validate --release <release-path> waliduje dokładnie te encje, do których docierają rozwiązane zależności pojedynczej encji Release, a nie cały katalog ani jedną encję. Domknięcie jest obliczane przez ten sam mechanizm, którego używa kompilacja, więc sprawdzane encje to dokładnie te, które rozwiązałaby kompilacja tej encji Release. Na tym domknięciu polecenie:
- rozwiązuje łańcuchy
extendsw zakresie domknięcia, kończąc się błędem przy błędzie rozwiązywania; - waliduje filary schematu każdej rozwiązanej encji (w zakresie domknięcia), kończąc się błędem przy błędzie filaru schematu;
- uruchamia tę samą kontrolę zgodności wartości przed renderowaniem, którą uruchamia kompilacja — rozwiązuje parametry encji Release w autorskich wartościach (tak że wartość
{{ .parameters.* }}jest sprawdzana po rozwiązaniu, a nie jako szablon) i waliduje wynik względem złożonych schematów domknięcia, w tym zgodność ze złożonym schematem rodzica i potomka dla encji używającejextends. Wartość naruszająca swój schemat powoduje błąd z niezerowym kodem wyjścia; - ocenia każdą asercję Recipe i FeatureRecipe względem wartości, do których rozwiązuje się encja Release, tak jak kompilacja ocenia je przed renderowaniem: encja Recipe każdego komponentu jest wiązana tak, jak mapuje ją encja Manifest, jej
localsiprovidessą rozwiązywane, a pierwsza asercja, która nie przejdzie — taka, która wywołujefail, albo taka, której szablon zatrzymuje się na kluczu, którego nie znajduje — powoduje niepowodzenie walidacji z warunkiem i zdaniem, z jakimi zatrzymuje się kompilacja. Szablonlocalslubprovides, którego nie da się obliczyć, również powoduje niepowodzenie walidacji, tak jak powoduje niepowodzenie kompilacji. Provider, przez którego renderuje każda encja Recipe, jest pytany o nazwę, jaką nadaje zasobom tego komponentu, tak jak pyta go kompilacja, ponieważprovidesencji Recipe może tę nazwę odczytywać; nic nie jest renderowane. Te asercje są oceniane tylko wtedy, gdy nic z powyższego jeszcze nie zawiodło, więc encja Release zgłasza najwcześniejszy błąd, na którym zatrzymałaby się kompilacja; - zgłasza wyniki dotyczące nakładania się filarów schematu i zawężania przy rozszerzaniu jako informacyjne wiersze
notice:, które nigdy nie zmieniają kodu wyjścia; - pokazuje każde słowo kluczowe
x-aggrega-*, które odczytywana encja zapisuje wprost w treści swojego schematu, jako wierszwarning:, raz na encję, tak jak pokazuje je kompilacja — to również nigdy nie zmienia kodu wyjścia.
Dzięki temu --release jest prawdziwą kontrolą przed kompilacją: wychwytuje to, co odrzuciłaby kompilacja, zanim do niej dojdzie — walidację zależności kompilacji bez renderowania. Nie wykonuje renderowania i nie wywołuje pobierania z sieci: domknięcie jest rozwiązywane z lokalnego katalogu (oraz z przypięć w pliku blokady encji Release, jeśli istnieje); zestaw zależności przypiętych do rejestru, który wymaga pliku blokady, zgłasza rzetelny błąd nierozwiązywalnego odwołania zamiast pobierać. Zawężanie jest zgłaszane jako porada, nigdy egzekwowane.
Plik blokady, który nie odpowiada już temu, do czego rozwiązuje się Release, powoduje odmowę walidacji z zatrzymaniem wypisywanym przez aggrega build. Gdy obok encji Release znajduje się plik blokady, --release porównuje go z tym, do czego rozwiązuje się Release, za pomocą porównania rozbieżności, które kompilacja wykonuje przed renderowaniem, gdy tylko zależności encji Release zostaną rozwiązane i zanim zostanie wykonana którakolwiek z powyższych kontroli. Plik blokady, od którego odbiegła przypięta encja, biblioteka, plugin lub sam plik Release, zatrzymuje walidację odmową E0130 kompilacji — każdy rozbieżny wpis, a następnie aggrega pull --release <release>, które ją usuwa — i niezerowym kodem wyjścia, więc walidacja nigdy nie przepuszcza pliku blokady odrzucanego przez kompilację jako rozbieżny. Bez argumentu oraz ze ścieżką encji validate nie podlega plikowi blokady: kontrola całego katalogu odczytuje przypięcia z pliku blokady tylko po to, by znaleźć rodzica extends, a kontrola pojedynczej encji nie odczytuje pliku blokady.
Ponieważ polecenie uruchamia te same kontrole co kompilacja, uruchamia też te same dołączone wtyczki bramkujące — podlega więc temu samemu rejestrowi zaufanych tożsamości wtyczek co kompilacja. Obszar roboczy dołączający wtyczkę, która zwraca werdykt akceptacji lub odrzucenia, ma rejestr zaufania wtyczek obok swojej encji Release, a --release porównuje z nim konfigurację, zanim którakolwiek z tych wtyczek zostanie uruchomiona: zarejestrowana bramka, której konfiguracja już nie dołącza, zatrzymuje walidację, a wtyczka rozwiązana z pamięci podręcznej wypełnianej przez aggrega pull, której artefakt nie jest zarejestrowanym, jest odrzucana zamiast uruchamiana. Obszar roboczy, który niczego nie zarejestrował, nie ma rejestru, co niczego w tym porównaniu nie zmienia. --release wymienia też każde wycofanie zarejestrowane dla tego, od czego zależy encja Release, na standardowym wyjściu błędów jako wiersz deprecation: w brzmieniu, które wypisuje aggrega build: zarówno znacznik, który plik blokady rejestruje dla przypiętego odwołania, jak i znacznik, który rejestr zaufania rejestruje dla wtyczki dołączonej w roli werdyktu. Wycofanie nie zmienia ani werdyktu, ani kodu wyjścia, a rejestr zaufania, który istnieje, ale nie można go odczytać, zatrzymuje walidację, zamiast zostać uznany za rejestr, który niczego nie odnotowuje.
Wtyczka odczytana z pamięci podręcznej podlega też podpisowi zapisanemu w jej wpisie, tak jak w kompilacji, w chwili jej ładowania. Jeśli wpis zapisuje zweryfikowany podpis, materiał podpisu wskazany przez ten fakt w pamięci podręcznej jest sprawdzany ponownie, a wtyczka, której materiału brakuje lub jest inny, zostaje odrzucona — podobnie jak wtyczka, której materiał wykonano dla innej wtyczki niż odczytana, co wygląda jak signature skopiowany z innego wpisu, niezależnie od wymogu podpisu. Jeśli konfiguracja zaufania obszaru roboczego wymaga podpisu, wtyczka odczytana z pamięci podręcznej, której wpis nie zapisuje żadnego — lub dla której rejestr nie ma wpisu, także po usunięciu rejestru — również jest odrzucana, przy tych samych ustawieniach, przy których aggrega pull odrzuciłoby ją jako niepodpisaną, więc skip_signature_verification i rejestr advisory pozwalają ją uruchomić. Odrzucenie powoduje niepowodzenie walidacji i jest zgłaszane wśród jej diagnostyk, ze wskazaniem wtyczki i aggrega pull --release <release> — polecenia, które weryfikuje jej podpis w rejestrze, zapisuje go i umieszcza w pamięci podręcznej wskazany pakiet, nadpisując kopię, która nie zgadza się już ze swoim skrótem; wtyczka dostarczana z jednego z katalogów katalogu encji lub z kopii wbudowanej w plik binarny kompilatora nigdy nie podlega temu wymogowi. Dwa pozostałe zakresy nie podlegają niczemu z powyższych: nie odczytują dołączeń wtyczek obszaru roboczego, więc żadna taka wtyczka w nich nie działa.
To samo dotyczy wtyczek, które zmieniają graf, zamiast go oceniać. Dołączenie label-transform lub annotation-transform kształtuje renderowany wynik, więc plik blokady przypina zarówno jego tożsamość, jak i odczytywane przez nie pliki źródłowe — a --release uruchamia te dołączenia tak jak kompilacja: odtworzone z pliku blokady, sprawdzając każde względem zapisanego skrótu i odczytując treść źródłową zawartą w pliku blokady, a nie plik na dysku. Warto znać dwie konsekwencje, zanim się na nie natrafi:
- Dołączenie wtyczki transformującej w
.aggrega-config.yamlnie zmienia działania--releaseaż do wykonania pobrania. To ta sama reguła, której przestrzega kompilacja, z tego samego powodu: zestaw dołączeń jest wejściem determinującym bajty, więc jest przyjmowany przy pobraniu, a nie w chwili edycji. - Wtyczka w pamięci podręcznej, której bajty nie zgadzają się już ze skrótem zapisanym w pliku blokady, jest odrzucana, dokładnie tak jak podczas kompilacji.
Jeśli encja Release nie ma pliku blokady, --release nadal waliduje — ostrzega, że nie mógł sprawdzić tożsamości wtyczki, i wskazuje, co uruchomić, zamiast odmawiać. Zobacz ostrzeżenia.
Zwracanie skompilowanego grafu
--ir-graph zapisuje graf rozwiązany przez tę walidację na standardowe wyjście w formacie JSON, przed wierszem werdyktu. Działa addytywnie: uruchamiane są te same kontrole, zapisywane te same diagnostyki, a kod wyjścia jest taki sam jak bez tej flagi. Zwracany graf to ten, na którym przeprowadzono walidację, więc nie może opisywać innego rozwiązania niż to, którego dotyczy werdykt.
Flaga dotyczy wyłącznie tego zakresu — zakresy całego katalogu i pojedynczej encji sterują syntetyzowaną uprzężą, a nie encją Release, i nie rozwiązują grafu — a żądanie jej gdzie indziej jest odrzucane, a nie po cichu ignorowane. Jeśli przebieg zatrzyma się przed rozwiązaniem grafu, na standardowe wyjście nic nie jest zapisywane, a własne diagnostyki polecenia mówią, co go zatrzymało.
Warto zwrócić uwagę na sąsiednią flagę. --response-format określa, ile własnego raportu tego polecenia jest zapisywane (detailed lub concise); --ir-graph żąda drugiego dokumentu obok tego raportu. Jedna dotyczy objętości, druga przedmiotu, i żadna nie zmienia werdyktu.
Wartości, które autor zadeklarował jako wrażliwe, są ukrywane w grafie — w tym values i infra połączenia, gdy gniazdo konsumującego komponentu deklaruje liść jako wrażliwy — w ustrukturyzowanej formie opisanej w aggrega inspect. --unredacted obok --ir-graph drukuje je zamiast tego, na warunkach określonych przez aggrega inspect --unredacted: dotyczy grafu i niczego innego, co zapisuje to polecenie, a wszystko, do czego trafi wynik, zawiera wtedy te wartości jawnym tekstem. Podana bez --ir-graph jest odrzucana, ponieważ nie byłoby czego ujawniać.
Poprawność pojedynczej encji (ścieżka encji)
aggrega validate <entity-path> sprawdza jeden plik encji katalogu. Stosuje warstwowy zestaw kontroli i zatrzymuje się na pierwszym blokującym błędzie, tak aby naruszenie schematu ujawniło się wyraźnie, zanim rozpocznie się jakakolwiek praca na katalogu:
- Symbole zastępcze (każdy rodzaj) — wartość wymagana przez rodzaj, którą plik pozostawia jako pusty ciąg znaków. Wszystkie są zgłaszane naraz, przed pozostałymi kontrolami, każdy z informacją, czego wymaga; zob. symbole zastępcze wciąż do uzupełnienia.
- Koperta schematu (każdy rodzaj) — dokładnie ta sama kontrola JSON Schema dla pojedynczej encji, którą moduł ładujący katalog wykonuje na każdej granicy parsowania.
- Kształt (każdy rodzaj) — walidacja strukturalna właściwa dla rodzaju. W przypadku encji Component lub Feature obejmuje odczytanie każdego selektora etykiet, który plik deklaruje przy gnieździe zależności lub slocie załącznika, zgodnie z gramatyką selektorów; zob. zadeklarowane selektory.
- Struktura filarów (Component i Feature) — kontrola filarów
spec.schema:, korzystająca z encji SchemaLibraries katalogu do rozwijania$refmiędzy dokumentami.
Component lub Feature kończy na tym: koperta schematu, kształt i struktura filarów. Pojedyncza encja Component nie ma utworzonych values ani infra do renderowania w izolacji, więc nie ma czego renderować — jej poprawność w pełni obejmują warstwy schematu i filarów. Każde słowo kluczowe x-aggrega-*, które treść jej schematu zapisuje wprost, jest zgłaszane wśród uwag doradczych na standardowym wyjściu błędów jako wiersz warning:, wskazujący słowo kluczowe, jego położenie i deklaratywną tabelę, którą należy zapisać zamiast niego; nigdy nie zmienia to werdyktu ani kodu wyjścia.
Recipe dodatkowo renderuje się w izolacji. To jeden z aspektów poprawności pojedynczej encji, a nie jej główny element: po przejściu warstw schematu i kształtu validate rozwiązuje z katalogu encję Component wskazaną w implements encji Recipe, syntetyzuje minimalne encje Aggregate, Manifest i Release wokół pojedynczej instancji tej encji Component powiązanej z testowaną encją Recipe i uruchamia na niej rzeczywisty potok kompilacji — najpierw rozwiązywanie i strażniki (z pominięciem renderowania), a następnie rzeczywiste renderowanie izolowanego wyniku. Każda wymagana wartość i każde wymagane pole infra bez wartości domyślnej są wypełniane symbolem zastępczym zadeklarowanego typu — wartości w syntetyzowanej encji Aggregate, infra w syntetyzowanej encji Release — a każda inna wartość i pole infra przyjmują wartość domyślną ze schematu za pośrednictwem resolvera; encja Release kieruje instancję do syntetyzowanej domyślnej granicy i nie deklaruje values: ani zasobów obliczeniowych, których nie zadeklarowała encja Aggregate. Symbol zastępczy to wartość akceptowana przez własne zadeklarowane ograniczenia pola: stała lub pierwsza wartość wymieniona w enum, liczba w dozwolonym zakresie, ciąg znaków o wymaganej długości i w wymaganym format, wersja semantyczna tam, gdzie wymaga jej pattern, tyle elementów listy, ile jest wymaganych, oraz każda właściwość wymagana przez obiekt. Żaden inny pattern, warunek validate: lub when:, złożenie schematów ani ograniczenie dotyczące elementów listy nie są brane pod uwagę, więc pole, które na nich polega, może nadal odrzucić swój symbol zastępczy; validate zgłasza wtedy to odrzucenie słowami samego schematu. Wyrenderowane artefakty są wypisywane, aby autor zobaczył izolowany wynik przed włączeniem encji do pełnej encji Aggregate. Ponieważ środowisko dla pojedynczej encji wypełnia tylko te wymagane pola, nie tworzy żadnego połączenia i nie dołącza żadnej encji Feature, encja Recipe, której szablony odczytują wartość dostarczaną wyłącznie przez połączenie lub dołączoną encję Feature, nie może zostać wyrenderowana w izolacji; validate zgłasza takie renderowanie jako niepodjęte, a nie nieudane. Asercja wywołująca fail jest zgłaszana jako ostrzeżenie, a nie jako niepowodzenie kontroli — zob. nieudana asercja jest ostrzeżeniem. Renderowanie, które zatrzymuje się z jakiegokolwiek innego powodu, nie zostało ukończone, a validate zgłasza je wraz z diagnostyką renderowania aż do zdania wskazującego, co je zatrzymało.
Encja Recipe, której source: musi zostać pobrane, nie jest w ogóle renderowana, a w przypadku encji Recipe, której renderowanie zatrzymuje się przy odczycie wartości dostarczanej wyłącznie przez połączenie lub dołączoną encję Feature, to renderowanie zostaje odłożone na bok — zob. czego nie sprawdza poprawność pojedynczej encji poniżej.
FeatureRecipe przechodzi kontrolę schematu i kształtu; jej renderowanie jest pomijane, ponieważ FeatureRecipe renderuje się tylko po dołączeniu do komponentu hosta, a syntetyzowanie hosta przechodzącego strażniki dla dowolnej encji Feature nie jest podejmowane.
Sprawdzanie encji w kontekście encji Release
Obszar roboczy może nadać każdej encji Release własne katalogi — zob. Nadawanie encji Release własnych katalogów — i w ten sposób utrzymywać obok siebie po jednym wariancie katalogu na każdą encję Release. Ścieżka encji podana samodzielnie jest sprawdzana względem własnych katalogów obszaru roboczego, gdzie odwołanie do jednego z tych wariantów — encji Component implementowanej przez Recipe, encji SchemaLibrary, do której odwołuje się filar — nie zostaje znalezione. Po podaniu --release obok ścieżki encji te same kontrole są wykonywane w kontekście tej encji Release: odwołania encji są rozwiązywane przez katalogi, które konfiguracja obszaru roboczego przypisuje tej encji Release, z dołączonymi na początku ewentualnymi --catalog, czyli przez katalogi odczytywane przez build tej encji Release.
Przykład MariaDB + Adminer utrzymuje cztery takie warianty. Encja Component jego wariantu synth pobiera ustawienia przechowywania z encji SchemaLibrary, którą zawierają tylko warianty synth i chart, więc przechodzi walidację w kontekście encji Release, która jest z nią budowana:
$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/component/mariadb.yamlKind: ComponentSchema: validPillars: validi kończy się niepowodzeniem, wskazując bibliotekę, której nie udało się rozwiązać, w kontekście encji Release, której katalogi jej nie zawierają — --release release-compose.yaml lub brak --release w obszarze roboczym, który nie wymienia własnych katalogów.
Encja Recipe jest sprawdzana w ten sam sposób. Recipe wariantu synth implementuje core/datastore/mariadb, którego nie zawierają własne katalogi obszaru roboczego, więc podana samodzielnie kończy się błędem render: implements target "core/datastore/mariadb" not found in catalog. Po podaniu encji Release, która jest z nią budowana, rozwiązuje encję Component tej encji Release i renderuje się w izolacji:
$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Resolution: validRender: 3 artifact(s)a następnie wypisywane są trzy wyrenderowane artefakty. Każdy wariant tego przykładu deklaruje core/datastore/mariadb, więc encja Recipe przechodzi walidację w kontekście każdej z czterech encji Releases; w kontekście encji Release, której katalogi nie zawierają takiej encji Component, kończy się niepowodzeniem ze wskazaniem celu, tak jak bez --release. Wiersze Attachments: wyjaśniono w sekcji wymagany slot dołączenia lub wymóg obecności.
Nadal jest to zakres pojedynczej encji. Kontrole, raport i kod wyjścia są takie, jak opisuje ta sekcja — encja Component lub Feature z selektorem gniazda lub slotu odrzucanym przez gramatykę kończy się tu niepowodzeniem dokładnie tak jak bez --release, zob. zadeklarowane selektory — i żadne domknięcie nie jest walidowane: --release wskazuje encję Release, przez której katalogi odczytywane są odwołania encji, a nie domknięcie do sprawdzenia, dlatego --ir-graph jest odrzucana obok ścieżki encji. Opcja --release wskazująca nieistniejący plik lub katalog jest odrzucana, zanim cokolwiek zostanie sprawdzone.
Katalog wymieniony w konfiguracji obszaru roboczego, który nie jest katalogiem — bo na przykład nic w tym miejscu nie istnieje — dla tej encji Release lub dla obszaru roboczego, gdy nie podano --release, jest odrzucany, zanim cokolwiek zostanie sprawdzone, tak jak odrzuca go każde polecenie, które go odczytuje (Skąd odczytywane są encje lokalne): odrzucenie wskazuje wpis, plik konfiguracyjny i wiersz, które go wymieniają, oraz ustawienie, i nie jest wydawany żaden werdykt. Kontrola encji w edytorze za pośrednictwem aggrega serve podaje to samo odrzucenie jako jedyny wpis dla pliku encji, na poziomie błędu, a narzędzie validate w aggrega mcp odrzuca z nim wywołanie.
Wciąż brakujące symbole zastępcze
Wartość wymagana przez rodzaj, którą plik pozostawia jako pusty ciąg znaków, jest symbolem zastępczym, a validate zgłasza ją przed wszystkim innym. Dokument przygotowany przez aggrega scaffold zawiera taki symbol wszędzie tam, gdzie jego rodzaj potrzebuje wartości, którą może podać tylko autor, więc w tym miejscu można się dowiedzieć, które z nich pozostały. Oto przygotowana encja FeatureRecipe z wypełnioną jedynie wersją:
Entity: my-feature-recipe.yamlKind: FeatureRecipe2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates: 7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it. 8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).Wszystkie symbole zastępcze w pliku są wymieniane naraz, w kolejności w dokumencie, wraz z wierszem, kolumną i informacją, czego wymagają. To, czego wymagają, jest odczytywane ze schematu samego rodzaju: wartości, które przyjmuje, jeśli schemat je wymienia, wersja semantyczna, taka jak 1.0.0, jeśli schemat jej wymaga, a w pozostałych przypadkach pierwsze zdanie opisu pola zawartego w schemacie.
To, które wartości się liczą, również jest odczytywane ze schematu. Wartość się liczy, gdy rodzaj wymaga jej na najwyższym poziomie dokumentu lub wewnątrz obiektu, którego rodzaj także wymaga, a plik ustawia ją na pusty ciąg znaków. Klucz całkowicie pominięty w pliku jest zgłaszany przez sprawdzenie schematu jako brakująca właściwość. Pole opcjonalne pozostawione puste nie jest symbolem zastępczym, podobnie jak pole wymagane tylko wewnątrz listy lub mapy, którą autor zdecydował się zapisać. Jeśli schemat sam wymienia pusty ciąg znaków wśród wartości przyjmowanych przez pole, pusta wartość jest wartością, a nie symbolem zastępczym.
Wartość jest wymagana nawet tam, gdzie schemat przyjąłby ją pustą. Schemat dopuszcza pusty ciąg znaków dla pól capability i implements encji Recipe lub FeatureRecipe, ale pusta wartość nie wskazuje żadnego dostawcy ani typu, więc validate zgłasza obie jako symbole zastępcze, jak każde inne. Jeśli sprawdzenie schematu również odrzuca ten sam plik — pusta wersja, etykieta typu bez wartości — raport zawiera kod tego sprawdzenia, E0215, jak pokazuje przykład na stronie aggrega scaffold; jeśli sprawdzenie schematu go akceptuje, jak powyżej, raport nie zawiera kodu. Wynik w tym samym pliku, który nie dotyczy pustej wartości, jest nadal zgłaszany, słowami samego sprawdzenia schematu, przed listą.
Ta interpretacja należy do walidacji pojedynczej encji, z --release obok ścieżki encji lub bez niego. Uruchomienie dla całego katalogu, napotykając ten sam dokument, zgłasza to, co zgłasza sprawdzenie schematu, więc encja FeatureRecipe z pustym implements w katalogu przechodzi je; zakres Release i aggrega build również nie stosują tej interpretacji.
Rodzaj, którego ten zakres nie przyjmuje
Walidacja pojedynczej encji przyjmuje Component, Feature, Recipe, FeatureRecipe, Workload i Plugin. Plik każdego innego rodzaju jest odrzucany, a odmowa wymienia przyjmowane rodzaje oraz, w przypadku rodzaju encji, zakres, który sprawdza dokument tego rodzaju:
kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys itZakres całego katalogu to uruchomienie bez argumentu, a zakres Release to --release bez ścieżki encji:
| Rodzaj | Sprawdzane przez |
|---|---|
| Aggregate | uruchomienie dla całego katalogu, gdy znajduje się w katalogu; --release dla encji Release, która go wdraża |
| Manifest | --release dla encji Release, która go wskazuje |
| Release | --release <release-path> |
| SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | uruchomienie dla całego katalogu, gdy znajduje się w katalogu |
Uruchomienie dla całego katalogu odczytuje tylko to, co znajduje się w skonfigurowanych katalogach, więc encja Aggregate przechowywana w katalogu głównym obszaru roboczego obok swojej encji Release jest sprawdzana przez --release dla tej encji Release.
Niespełniona asercja jest ostrzeżeniem
Asercja wywołująca fail — zadeklarowana przez encję Recipe lub przez encję Component wskazaną w jej implements — jest zgłaszana jako ostrzeżenie, a sprawdzenie nie kończy się z jej powodu niepowodzeniem. Syntetyzowana encja Release zawiera symbole zastępcze i wartości domyślne schematu zamiast wartości ustawianych przez rzeczywistą encję Release, więc asercja dotycząca takiej wartości, obrazu czy obecności warunku wstępnego nie jest tu spełniona niezależnie od tego, czy encja Recipe jest poprawna, a validate nie potrafi odróżnić asercji czekającej na encję Release od asercji błędnej. Werdykt w sprawie asercji pozostawia się budowaniu, które zawsze ma encję Release.
Ostrzeżenie jest zapisywane na standardowe wyjście błędów, rozpoczyna się od warning: i następuje po ewentualnych uwagach informacyjnych. Zawiera pełny komunikat asercji — encję, instancję, nazwę asercji i zdanie napisane przez jej autora — zamknięty jeszcze jednym zdaniem:
A Release must satisfy this assertion before a build of it can pass.Raport na standardowym wyjściu informuje, gdzie uruchomienie się zatrzymało, a polecenie kończy się kodem 0. Własna asercja encji Recipe zatrzymuje renderowanie, więc raport zawiera Render: stopped on a failed assertion, reported as a warning po Resolution: valid. Asercja encji Component jest obliczana przed renderowaniem czegokolwiek, więc raport zawiera Resolution: stopped on a failed assertion, reported as a warning, a po nim Render: not attempted (the run stopped on that assertion). W obu przypadkach nic nie zostaje wyrenderowane, więc żaden artefakt nie jest wypisywany.
Ostrzeżeniem jest tylko asercja wywołująca fail. Asercja, która zatrzymuje się na odczytywanym, lecz nieodnalezionym kluczu, albo która nie daje się sparsować, jest błędem w tekście samej asercji, a nie niespełnioną asercją, i jest oceniana jak każde inne zatrzymanie. Każdy inny błąd pozostaje werdyktem sprawdzenia.
aggrega build dla encji Release, która nie spełnia asercji, zatrzymuje się na niej z błędem, wskazując asercję i podając zdanie jej autora, jak zawsze, a aggrega validate --release dla tej encji Release kończy się na niej niepowodzeniem z tym samym błędem. Sprawdzenie encji w edytorze przez aggrega serve daje to samo ostrzeżenie, oznaczone na kluczu samej asercji, jeśli deklaruje ją encja Recipe, a narzędzie validate w aggrega mcp odpowiada valid: true z ostrzeżeniem wśród notices.
Czego nie sprawdza poprawność pojedynczej encji
Cztery sprawdzenia rzeczywistego budowania są poza zasięgiem budowania pojedynczej encji, a validate rezygnuje z każdego z nich, zamiast zgłaszać wynik, za którym nie może ręczyć.
Źródło, które trzeba pobrać
Walidacja jednej encji nie odczytuje pliku blokady, nie odczytuje ani nie zapisuje pamięci podręcznej i nie wykonuje żadnych żądań sieciowych. Encja Recipe, której source: wskazuje coś pobieranego przez transport — repozytorium chartów OCI lub HTTPS, repozytorium Git — nie ma zatem kodu infrastruktury, z którego można renderować: chart ani moduł nie istnieje w żadnym miejscu osiągalnym dla uruchomienia, a w sprawdzanym pliku nie ma błędu. Validate to stwierdza, wypisuje jako wynik odrębny od renderowania i kończy się kodem 0:
Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validResolution: validRender: not attempted (this Recipe's source is fetched) Validating one entity on its own reads no lockfile, reads and writes no cache, and makes no network request, so the chart or module this Recipe names is never retrieved and there is nothing to render from. To render it, build a Release that deploys a component this Recipe implements.Wszystko powyżej tego wiersza zostało sprawdzone i jest zgłaszane jako poprawne. Znaczenie kodu wyjścia dla takiej encji Recipe jest zatem węższe niż dla wyrenderowanej — schemat, kształt i rozwiązywanie są poprawne; renderowanie nie zostało potwierdzone — a raport określa, z którym z tych dwóch przypadków ma się do czynienia.
Źródło, które obszar roboczy już zawiera, nie jest pomijane. Względne source: ./module nie wymaga pobierania, więc jego renderowanie jest podejmowane jak każde inne, a niepowodzenie w nim jest rzeczywistym wynikiem, zgłaszanym jako Render: not completed in isolation z niezerowym kodem wyjścia. Powyższy wiersz pojawia się tylko dla źródła, które trzeba pobrać.
Aby rzeczywiście wyrenderować encję Recipe z pobieranym źródłem, należy uruchomić aggrega build dla encji Release wdrażającej komponent implementowany przez tę encję Recipe: budowanie rozwiązuje źródło przez plik blokady encji Release i lokalną pamięć podręczną, które dostarczają bajtów niemożliwych do uzyskania przez validate.
Wymagane gniazdo uses
Druga dotyczy tego, czy gniazda uses z required: true encji Component wskazanej w implements są obsadzone.
Wymagane gniazdo obsadza się, podłączając krawędź do innego komponentu — z własnego bloku uses encji Aggregate albo z encji Release, która podłącza gniazdo zadeklarowane przez Component. Syntetyczna uprząż zawiera jedną instancję, więc nie ma w niej drugiego komponentu, na który mogłaby wskazywać taka krawędź, i żadne zredagowanie syntetycznych dokumentów nie może go wytworzyć: wymyślenie partnera oznaczałoby wymyślenie zasobów obliczeniowych, których uprząż nigdy nie zadeklarowała. Dlatego validate wymienia gniazda, których nie sprawdził, i kontynuuje rozwiązywanie oraz renderowanie:
Sockets: required uses sockets not checked (backend, cache, registry) Validating a Recipe on its own places its Component in a build of one, so no other component exists for a required socket to be wired to. Whether each of these sockets is populated is checked when the Component is deployed in an Aggregate.Ten wiersz pojawia się tylko wtedy, gdy Component deklaruje co najmniej jedno wymagane gniazdo, i wymienia tylko wymagane — gniazdo opcjonalne nigdy nie jest wymieniane, ponieważ pozostawienie go niepodłączonego nie jest ustaleniem w żadnym zakresie. Encja Recipe, której Component nie deklaruje żadnego wymaganego gniazda, nie wytwarza takiego wiersza, a jej raport pozostaje bez zmian.
Sama reguła nie jest ani złagodzona, ani powielona; jest sprawdzana w zakresie, który może na nią odpowiedzieć. aggrega build stosuje ją w pełni łącznie do powierzchni krawędzi encji Aggregate i encji Release i zatrzymuje się na wymaganym gnieździe, którego nic nie podłącza. Zatem encja Recipe, która przechodzi walidację pojedynczej encji, nadal musi spełnić regułę wymaganych gniazd, gdy jej Component zostanie wdrożony, a raport to stwierdza, zamiast pozostawiać niewypowiedzianą różnicę między tym, co sprawdził validate, a tym, co sprawdzi kompilacja.
Wymagany slot dołączenia lub nakaz obecności
Trzecia dotyczy tego, czy sloty dołączeń z required: true encji Component wskazanej w implements — nazwane punkty wiązania deklarowane przez jej featuresSchema — są wypełnione oraz czy istnieje dołączenie każdego typu Feature, którego wymagają jej nakazy obecności.
Wymagany slot wypełnia się, dołączając Feature pod tą nazwą, w encji Aggregate lub w encji Release, na komponencie lub w zakresie powyżej niego — tam, gdzie Component jest wdrażany, a nie w encji Recipe. Syntetyczna uprząż nie dołącza żadnego Feature, więc nic, co buduje, nie może wypełnić takiego slotu. Dlatego validate wymienia sloty, których nie sprawdził, i kontynuuje rozwiązywanie oraz renderowanie, dokładnie tak jak w przypadku wymaganych gniazd:
Attachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Ten wiersz pojawia się tylko wtedy, gdy Component deklaruje co najmniej jeden wymagany slot, i wymienia tylko wymagane; encja Recipe, której Component nie deklaruje żadnego, nie wytwarza takiego wiersza. Pomijane jest tylko samo wymaganie: ograniczenie etykiety slotu i dozwolone mechanizmy dostarczania pozostają takie, jak zadeklarowano. Szablon, którego nie da się sparsować, nadal powoduje niepowodzenie uruchomienia, podobnie jak własny błąd encji Recipe, taki jak Workload, którego provider nie potrafi zsyntetyzować — chyba że Recipe odczytuje także wartość, którą dostarcza tylko połączenie lub dołączony Feature, jak opisuje następna sekcja.
Nakaz obecności — adnotacja features.aggrega.ai/requiredType.<label> na encji Component, wymagająca, aby jakieś dołączenie miało wskazany w niej typ Feature — jest pomijany z tego samego powodu: uprząż niczego nie dołącza, więc nic, co buduje, nie może mieć tego typu. Validate wymienia każdy niesprawdzony nakaz z jego etykietą i wymaganym typem, po czym kontynuuje rozwiązywanie oraz renderowanie. example/compute/service z biblioteki standardowej deklaruje jeden taki nakaz, więc jego Recipe zgłasza, przed dwoma wyrenderowanymi artefaktami:
$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalogEntity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: presence mandates not checked (monitoring: core/prometheus-exporter) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to carry a type the Component requires. Whether an attachment of each of these types is present is checked when a Release that deploys the Component is built.Resolution: validRender: 2 artifact(s)Nakaz, którego deklaracji nie da się ocenić — prefiks adnotacji bez etykiety po nim albo wartość, która nie jest typem Feature — nie jest pomijany: jest to własny błąd encji Component, którego żadne dołączenie nie naprawi, i validate kończy na nim uruchomienie niepowodzeniem, tak jak kompilacja.
Każda reguła jest sprawdzana tam, gdzie można na nią odpowiedzieć. aggrega pull, aggrega build i aggrega validate --release oceniają obie na rzeczywistych dołączeniach encji Release i każde z nich zatrzymuje się na wymaganym slocie, którego nic nie wypełnia, oraz na nakazanym typie, którego nie ma żadne dołączenie.
Wartość, którą dostarcza tylko połączenie lub dołączony Feature
Czwarta dotyczy tego, czy encja Recipe renderuje się, gdy jej połączenia i dołączone Features dostarczą to, co odczytują jej szablony.
Szablony encji Recipe odczytują to, co połączenie dostarcza pod .context.inject i .context.uses, oraz to, co dołączony Feature dostarcza pod .features. Syntetyczna uprząż nie podłącza żadnego połączenia i nie dołącza żadnego Feature, więc każdy taki odczyt nic nie znajduje: odczyt pod .context.inject.env trafia na pusty kanał dostarczania, a range po .context.uses nie trafia na żadne połączenie. Validate najpierw renderuje Recipe, a render, który się zakończy, jest zgłaszany jak zwykle. Gdy render się zatrzyma, a szablony Recipe — łącznie z importowanymi przez nie plikami i wpisami bibliotek — odczytują cokolwiek spod tych trzech, validate zgłasza render jako niepodjęty, wymienia wartości, które Recipe tam odczytuje, wypisuje zdanie, na którym render się zatrzymał, i kończy z kodem 0. Wariant z chartem przykładu MariaDB + Adminer odczytuje dane uwierzytelniające bazy danych z kanału dostarczania, który wypełniają jego dwa dołączone sekrety:
$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yamlEntity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Resolution: validRender: not attempted (this Recipe reads values a build of one cannot supply) Validating a Recipe on its own places its Component in a build that wires no connection and attaches no Feature, so nothing supplies what its templates read under .context.inject, .context.uses or .features. Its render stopped, and whether on one of those values or on a fault of its own is not judged here. To render it, build a Release that deploys a component this Recipe implements. Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORDOdczyt, który nic nie znajduje i niczego nie zatrzymuje, nie jest pomijany: range po .context.uses, który nic nie renderuje, w renderze, który się kończy, jest zgłaszany jako taki render, jakim był.
O wyniku decyduje to, co Recipe odczytuje, a nie to, na czym render się zatrzymał, a ma to konsekwencję, którą warto znać, zanim się na nią trafi: własny błąd encji Recipe, która także odczytuje taką wartość — na przykład błędnie zapisany klucz — jest zgłaszany jako niepodjęty wraz z resztą, a nie jako niepowodzenie. Wiersz The render stopped: zawiera własne zdanie renderu, dzięki czemu widać, który to przypadek, a kompilacja encji Release wdrażającej ten Component ocenia render w pełni.
Dwa błędy nadal powodują niepowodzenie uruchomienia niezależnie od tego, co Recipe odczytuje, ponieważ żadne połączenie ani Feature ich nie zmienia: szablon, którego nie da się sparsować, oraz odwołanie odrzucone przez render — korzeń, którego kontekst renderu nie definiuje, lub błędnie wpisany klucz pod korzeniem o stałym kształcie, taki jak .context.instance_idd. Asercja zadeklarowana przez Recipe, która wywołuje fail, nie jest ani pomijana, ani niepowodzeniem, niezależnie od tego, co Recipe odczytuje: jest zgłaszana jako ostrzeżenie, jak zawsze nieudana asercja. Encja Recipe, której szablony nie odczytują niczego z tych trzech, ma render oceniany w całości, a render, który się zatrzyma, kończy się niepowodzeniem ze zdaniem wskazującym przyczynę.
Narzędzie validate polecenia aggrega mcp wydaje ten sam werdykt dla tej samej encji Recipe: render pominięty w ten sposób zwraca wynik prawidłowy bez niczego w diagnostyce, a powyższe wiersze znajdują się w tekście, który narzędzie zwraca obok niej.
Ładowanie katalogu w trybie pojedynczej encji jest tolerancyjne: niezwiązana uszkodzona encja w innym miejscu katalogu jest pomijana zamiast przerywać sprawdzanie, więc nigdy nie blokuje walidacji celu w izolacji.
Pominięty plik nadal wyjaśnia encję Component, której brakuje z jego powodu. Gdy cel implements encji Recipe nie zostaje znaleziony, a dokładnie jeden pominięty plik deklaruje tę encję Component, raport zaczyna się od odmowy dotyczącej samego tego pliku — jego ścieżki, naruszanego przez niego ograniczenia i krótkiego kodu warunku w nagłówku — po której następuje note: informująca, że plik został pominięty podczas ładowania, więc katalog nie zawiera niczego pod deklarowaną przez niego tożsamością, a następnie błąd implements target … not found in catalog jako powód, dla którego plik był potrzebny. Gdy żaden pominięty plik nie deklaruje tej encji Component albo deklaruje ją więcej niż jeden, na pierwszym miejscu jest błąd nieznalezienia, a każdy pominięty plik jest wymieniony pod nim w sekcji note: catalog files skipped at load. Taki opis pominiętego pliku podaje aggrega build, a także sprawdzanie encji w edytorze przez aggrega serve i narzędzie validate z aggrega mcp. Katalog, z którego niczego nie pominięto, raportuje dokładnie tak, jak raportowałby w innym przypadku.
Jak validate ma się do lint i build
Te trzy polecenia odpowiadają na trzy różne pytania:
aggrega validate— czy to jest poprawne? Schemat, filary, odwołania,extends, obsługa rodzaju wejścia i izolowane renderowanie. Nie odczytuje żadnego stanu środowiska uruchomieniowego i nie emituje żadnych artefaktów.aggrega lint— czy to jest zgodne z konwencjami publikowania katalogu? Nazewnictwo, zgodność z katalogami kategorii, prefiksy adnotacji, wielkość podbicia wersji i pozostała część opcjonalnej dyscypliny publikowania. Lint odzwierciedla trzy zakresy validate, ale nigdy nie sprawdza poprawności.aggrega build— kompilacja kompletnego wdrożenia. Build wymaga pełnego domknięcia Aggregate + Manifest + Release i emituje artefakty natywne dla dostawcy. W ramach kompilacji waliduje własne domknięcie zależności, a następnie renderuje.aggrega validate --releaseto sama ta walidacja zależności, bez renderowania; walidacja pojedynczej encji izoluje renderowanie pojedynczej encji Recipe bez pełnej encji Aggregate.
Przykłady
Walidacja całego katalogu:
aggrega validate --catalog ./catalogWalidacja dokładnie tego, od czego zależy jedna encja Release, przed jej zbudowaniem:
aggrega validate --release releases/production.yamlWalidacja jednej encji oraz — w przypadku encji Recipe — podgląd jej wyrenderowanego w izolacji wyniku:
aggrega validate core/datastore/postgres/recipes/helm.yamlWalidacja jednej encji w kontekście encji Release, której konfiguracja obszaru roboczego nadaje własne katalogi z katalogiem encji:
aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yamlZobacz także
- ./aggrega-lint.md — odpowiednik dotyczący konwencji, działający w tych samych trzech zakresach.
- ./aggrega-build.md — kompiluje kompletną parę Aggregate + Release do artefaktów; w ramach kompilacji waliduje jej domknięcie zależności.
- ./aggrega-inspect.md — odpytuje graf IR po rozwiązaniu, bez przechodzenia do renderowania.
- ../errors/warnings.md — ustalenia doradcze, które validate wyświetla jako wiersze
notice:.
Składnia
aggrega validate [entity-path] [flags]Opis
Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillarstructure, cross-document library resolution, extends chains, and providerinput-kind capabilities, over every catalog entity. Where the workspaceconfiguration gives its Releases catalog directories of their own underworkspace.releases, it checks the catalog once for each Release, over thedirectories that Release reads, and reports each pass under a line namingits Releases and those directories; Releases reading the same directoriesshare one pass.
With --release, validate checks the entities a Release's dependency closurereaches: closure-scoped pillars, extends, and pre-render authored-valueconformance — the same correctness a build applies, scoped to that Release.It then evaluates the Recipe and FeatureRecipe assertions against the valuesthat Release resolves to, as a build does before it renders, and reports afailing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it acceptsas a single-entity target are Component, Feature, Recipe, FeatureRecipe,Workload and Plugin. A value the kind requires that the file leaves empty isreported first, as a placeholder still owed: every one is named at once, withwhat it takes, read from the kind's own schema. That reading is this scope'salone; a whole-catalog run, a Release's closure and a build do not apply it.Each kind then has its schema checked, then the checks its own kind carries:pillar structure for a Component or Feature; shape for a Workload,FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compileagainst a minimal generated harness, so its resolution, its guards and arender of its output are all exercised. Where that Recipe's source is onethat has to be fetched, the render is reported as not attempted instead:validating one entity on its own reads no lockfile, reads and writes no cacheand makes no network request, so the chart or module it names is neverretrieved and there is nothing to render from. A render that stops while theRecipe's templates read what only a connection or an attached Featuresupplies — anything under .context.inject, .context.uses or .features — isreported as not attempted too: the generated harness wires no connection andattaches no Feature, so that render cannot be judged there, and a fault ofthe Recipe's own beside such a read is set aside with it. A template thatdoes not parse and a reference the render refuses still fail. An assertionthat calls fail, the Recipe's own or one its Component declares, is printedas a warning closed by a sentence saying a Release must satisfy it before abuild can pass, and does not fail the check: the generated harness sets noneof a real Release's values, so it cannot tell an assertion waiting on one fromone that is broken, and a build still halts on it. Any other kind is refused heretoday, and the refusal names the scope that checks it instead: a whole-catalogrun reaches an Aggregate and the library kinds when they sit in a catalogdirectory, and --release reaches a Release, the Manifest it names and theAggregate it deploys.
With an entity path and --release together, the entity is checked in thatRelease's terms: its references — the Component a Recipe implements, alibrary a pillar refers to — resolve through the catalog directories theworkspace configuration gives that Release rather than the workspace's own,so a workspace keeping one catalog variant per Release checks an entityagainst the variant that Release builds with. The checks are the entitypath's; no closure is validated.
The command writes nothing to disk.Flagi
| Flaga | Domyślnie | Opis |
|---|---|---|
--catalog | [] | Katalog z katalogiem encji; można podać wielokrotnie. Każde —catalog <dir> jest dodawane na początek stosu wyszukiwania katalogów (wygrywa pierwsze dopasowanie): catalog_dirs obszaru roboczego lub — dla encji Release, której konfiguracja obszaru roboczego nadaje własne katalogi w workspace.releases — katalogi tej encji Release; stos kończy się katalogiem o nazwie catalog w katalogu głównym obszaru roboczego, jeśli taki istnieje. Lista catalog_dirs zapisana jako pusta oznacza, że żaden lokalny katalog nie jest odczytywany. |
--ir-graph | false | Dodatkowo zapisuje na stdout, w formacie JSON, graf IR obliczony w tym przebiegu, oprócz wszystkiego, co to polecenie już generuje. Wartości, które autor zadeklarował jako wrażliwe, są w nim ukrywane; aby je wypisać, należy przekazać —unredacted. Dotyczy zakresu —release, jedynego zakresu, który rozwiązuje encję Release do grafu. Wybiera DOKUMENT, podczas gdy —response-format określa, jak dużą część własnego raportu tego polecenia zapisać; żadna z tych flag nie wpływa na werdykt ani na kod wyjścia |
--no-unsupported-field-warnings | false | Wycisza klasę ostrzeżeń o nieobsługiwanych polach: komunikaty, które cel zgłasza dla czegoś, co zostało napisane przez autora, a czego nie może uwzględnić — pola encji Workload, którego nie potrafi wyrazić (jak cel o niższej wierności, np. compose), lub adnotacji aggrega.ai/, na którą nie reaguje dla rodzaju wejścia danego węzła. Pozostałe ostrzeżenia renderowania są nadal wyświetlane. Działa tylko na wyświetlanie; nie zmienia wyrenderowanego wyniku. Dotyczy zakresu encji, jedynego zakresu, który renderuje |
--plugin | — | Ścieżka do surowego pliku .wasm do walidacji względem jego samoopisu describe() — kontrola autorska przed publikacją. Samodzielnie wymaga —type; z argumentem w postaci encji Plugin sprawdza krzyżowo plik binarny względem zadeklarowanego w encji typu, deklaracji możliwości, odwzorowania poleceń i rejestru funkcji hosta. |
--release | — | Ścieżka do pliku YAML encji Release. Samodzielnie waliduje rozwiązane domknięcie zależności tej encji; z argumentem encji sprawdza tę encję w kategoriach encji Release, rozwiązując jej odwołania przez katalogi, które konfiguracja obszaru roboczego nadaje tej encji Release. Ścieżka względna jest rozwiązywana względem katalogu, w którym uruchamiane jest polecenie, a nie względem katalogu głównego obszaru roboczego. Jeśli ten katalog nie należy do żadnego obszaru roboczego i nie wskazano katalogu głównego, ścieżka bezwzględna odnajduje obszar roboczy na podstawie własnego folderu encji Release |
--response-format | detailed | Ilość danych wyjściowych dla zakresu —release, czyli domknięcia encji Release bez argumentu encji: detailed (domyślnie) zgłasza każdą diagnostykę oraz wiersze doradcze; concise zgłasza liczbę diagnostyk i tylko pierwszą diagnostykę. Werdykt i kod wyjścia są w obu przypadkach identyczne. |
--type | — | Typ wtyczki dla kontroli —plugin obejmującej tylko plik binarny, weryfikowany względem typu zgłaszanego przez sam plik binarny. Ma znaczenie tylko z —plugin; gdy typ dostarcza encja Plugin, należy go pominąć (niezgodna wartość przerywa działanie). |
--unredacted | false | Wypisuje wartości, które autor zadeklarował jako wrażliwe, zamiast je ukrywać. Wszystko, do czego trafiają dane wyjściowe — terminal, potok, plik, nagranie ekranu — zawiera wtedy te wartości jawnym tekstem. Dotyczy grafu zapisywanego przez —ir-graph i niczego więcej, dlatego wymaga —ir-graph |