Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega lint

aggrega lint sprawdza konwencje publikacji — nazewnictwo, zgodność katalogów kategorii, prefiksy adnotacji, dyscyplinę tworzenia schematów oraz wielkość podbicia wersji. Ma trzy tryby, wybierane argumentem, które stosują tę samą dyscyplinę konwencji w trzech zakresach: cały katalog (bez argumentu), domknięcie zależności pojedynczej encji Release (--release) oraz jedna encja w pliku (ścieżka encji, z opcjonalną bramką publikacji --pre-publish). Każdy zakres odpowiada na to samo pytanie — „czy ta treść przestrzega dyscypliny publikacji katalogu?” — dla innego wycinka katalogu.

Konwencje to coś innego niż poprawność. aggrega lint nigdy nie sprawdza, czy treść jest poprawnie sformułowana ani czy dałaby się skompilować — do tego służy aggrega validate, które odzwierciedla te same trzy zakresy dla schematu, filarów, rozwiązywania odwołań, extends, możliwości rodzajów wejścia i renderowania. Selektor gniazda lub slotu, którego gramatyka selektorów nie potrafi odczytać, jest błędem poprawności, więc lint nic o nim nie zgłasza: validate go odrzuca, w całym katalogu lub w pojedynczej encji Component lub Feature — zob. zadeklarowane selektory. Oba polecenia się uzupełniają: validate mówi, czy treść jest poprawna; lint mówi, czy nadaje się do publikacji zgodnie z konwencjami katalogu.

aggrega lint jest opcjonalne. Sam kompilator pozostaje bez własnego zdania w kwestii dyscypliny katalogu; te reguły znajdują się w osobnej wtyczce, którą uruchamia się z własnego wyboru. Obszar roboczy, w którym nigdy nie uruchamia się aggrega lint, nadal się buduje i publikuje.

Ścieżkę encji można podać jako argument pozycyjny lub za pomocą --entity <path>. --release wyklucza się z argumentem encji — wybierają one różne zakresy; podanie obu powoduje zatrzymanie.

Konwencje w całym katalogu (bez argumentu)

aggrega lint bez argumentu uruchamia strukturalne reguły dyscypliny publikowania dla każdej encji katalogu znalezionej w skonfigurowanych katalogach. Wyniki mają charakter doradczy — są zgłaszane z ważnością warn i nigdy nie zatrzymują działania z powodu samego wyniku dotyczącego konwencji. Służy do przeglądania katalogu pod kątem odstępstw w nazewnictwie, katalogach kategorii i prefiksach adnotacji. Encja Aggregate, Manifest, Release lub Workload znaleziona w tych katalogach jest pomijana, a nie sprawdzana: przebieg zlicza każdy taki rodzaj w wierszu not checked: po swoim podsumowaniu i odsyła do trybu encji, który sprawdza dokument dowolnego rodzaju.

Plik YAML w katalogu katalogu encji 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. Dokument Aggrega, którego nie można odczytać, którego YAML nie daje się sparsować lub którego kind, metadata albo spec nie ma kształtu koperty encji — na przykład metadata zapisane jako lista — zatrzymuje przebieg z E0175 po odczytaniu katalogów, wymieniając każdy taki plik wraz z przyczyną podaną przez odczyt lub parser; nic nie jest lintowane i nie jest wypisywany wiersz conventions checked. 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 ten sam przebieg 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. --release zatrzymuje się w ten sam sposób na takim dokumencie w swoich katalogach katalogu encji.

To, które katalogi są odczytywane, zależy od struktury obszaru roboczego:

  • Obszar roboczy, którego konfiguracja nie określa własnych katalogów dla encji Release, jest sprawdzany jednokrotnie, w obrębie swojego stosu wyszukiwania: najpierw katalogi --catalog, następnie workspace.catalog_dirs, a potem katalog catalog w katalogu głównym obszaru roboczego, jeśli istnieje.

  • Obszar roboczy, który wymienia 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 pojedynczy przebieg po nich wszystkich odczytałby wszystkie warianty naraz — encja jednego wariantu przesłaniałaby encję innego. Dlatego jest on sprawdzany raz dla każdej encji Release w obszarze roboczym, w obrębie katalogów, które ta encja Release odczytuje, przy czym katalogi --catalog są 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ępują wyniki tego przebiegu i jego własne podsumowanie:

    Release release-compose.yaml reads catalog-compose
    conventions checked: 7 entities, 0 advisory finding(s)
    Release release-helm-synth.yaml reads catalog-helm-synth
    conventions checked: 8 entities, 0 advisory finding(s)

    Releases odczytujące dokładnie te same katalogi współdzielą jeden przebieg, który wymienia każdą z nich, dzięki czemu wynik jest w nim zgłaszany jednokrotnie. Encja Release, która nie odczytuje żadnego katalogu — jej wpis zawiera catalog_dirs: [] — jest zgłaszana jako niemająca nic do sprawdzenia, a pozostałe przebiegi działają normalnie. Z -o json dokument zawiera też passes: dla każdego przebiegu jego releases, catalogDirs, findings i summary, natomiast findings i summary najwyższego poziomu obejmują wszystkie przebiegi łącznie. Releases obszaru roboczego to jego dokumenty Release — pliki YAML, których kind ma wartość Release, znajdujące się w dowolnym miejscu pod katalogiem głównym obszaru roboczego, poza katalogami ukrytymi oraz node_modules, vendor i dist.

Uruchomienie, w którym żaden przebieg nie ma nic do odczytania, jest odrzucane, a nie raportowane jako czysty katalog: należy umieścić encje w catalog/, przekazać --catalog lub ustawić workspace.catalog_dirs — albo, w obszarze roboczym wymieniającym Releases, własne catalog_dirs encji Release w workspace.releases. Polecenie nigdy nie przegląda niejawnie bieżącego katalogu roboczego.

Dowiązanie w katalogu katalogu encji, które prowadzi poza obszar roboczy — lub poza wskazany katalog leżący poza nim — nie jest odczytywane, a uruchomienie zatrzymuje się w tym miejscu, podając to dowiązanie, zamiast raportować czysty katalog, którego jednego z dokumentów nie udało się odczytać; build w tych samych katalogach zatrzymuje się na tym samym dowiązaniu. Granica obszaru roboczego opisuje tę regułę i sposoby zaradzenia.

Konwencje w obrębie encji Release (--release)

aggrega lint --release <release-path> uruchamia te same reguły strukturalne na plikach encji katalogu, do których sięga rozwiązane domknięcie pojedynczej encji Release, zamiast na całym katalogu lub jednej encji. Oblicza domknięcie za pomocą tego samego mechanizmu, którego używa kompilacja, a następnie sprawdza linterem plik katalogu każdej encji należący do jej autora. Encja przypięta w rejestrze, przechowywana w gnieździe pamięci podręcznej, nie ma lokalnego pliku do sprawdzenia i jest pomijana — reguły publikacji dotyczą plików tworzonych lokalnie. Podobnie jak w trybie całego katalogu wyniki mają charakter doradczy i nigdy nie zatrzymują działania z powodu samego wyniku dotyczącego konwencji.

Jest to również jedyny zakres, w którym dostępna jest cała encja Release, dlatego właśnie tu działają reguły, które ją odczytują — reguła poświadczeń połączenia opisana w sekcji Reguły dyscypliny. Taka reguła działa raz na sprawdzenie, po regułach dla poszczególnych encji, na trzech dokumentach: encji Aggregate wdrażanej przez Release, w postaci zapisanej przez jej autora; encji Release z włączonym łańcuchem extends, tak aby potomna encja Release zawierała to, co dziedziczy; oraz, dla każdego komponentu deklarowanego przez Aggregate, encji Component, której instancją jest ten komponent, w postaci rozwiązanej przez katalog. Nie ma wśród nich żadnej wartości parametru, jak w każdym zakresie: Release trafia do reguły bez bloku parameters, w tym bez wartości dziedziczonych z bazy, a Aggregate bez wartości domyślnych i bez wartości przekazywanych każdemu importowanemu modułowi — zob. Co otrzymuje wtyczka lintera. Jej wyniki są raportowane pod plikiem encji Release.

Jest to odpowiednik dotyczący konwencji dla polecenia aggrega validate --release, które sprawdza poprawność tego samego domknięcia.

Lintery uruchamiane w tym zakresie są weryfikowane względem rejestru zaufanych tożsamości wtyczek znajdującego się obok encji Release, tak jak robi to kompilacja. Zanim którykolwiek z nich zostanie uruchomiony, --release porównuje skonfigurowane dołączenia plugins.linter z rejestrem zaufania wtyczek: zarejestrowana wtyczka, której konfiguracja już nie dołącza — linter lub bramka — zatrzymuje przebieg, a linter odczytany z pamięci podręcznej, którego artefakt nie jest zarejestrowanym artefaktem, jest odrzucany zamiast uruchamiany. Linter odczytany z pamięci podręcznej jest przy ładowaniu weryfikowany także względem zarejestrowanego podpisu: jeśli jego wpis odnotowuje zweryfikowany podpis, materiał podpisu wskazany przez ten fakt w pamięci podręcznej jest sprawdzany ponownie, a przebieg zatrzymuje się z E0144, gdy go brakuje lub się różni, oraz z E0332, gdy został wykonany dla innej wtyczki niż odczytany linter — signature skopiowany z innego wpisu — niezależnie od wymagań dotyczących podpisywania; jeśli konfiguracja zaufania obszaru roboczego wymaga podpisu, wpis bez podpisu — lub brak wpisu dla lintera, w tym usunięty rejestr — zatrzymuje przebieg z E0331, przy tych samych ustawieniach, przy których aggrega pull odrzuciłoby go jako niepodpisany. Każdy z tych trzech błędów wskazuje środek zaradczy, aggrega pull --release <release>, które weryfikuje podpis lintera w jego rejestrze, zapisuje go i umieszcza w pamięci podręcznej wskazany przez niego pakiet, nadpisując kopię w pamięci podręcznej, która nie odpowiada już swojemu skrótowi. Linter udostępniany z kopii wbudowanej w plik binarny kompilatora nigdy nie podlega temu wymaganiu. Są to błędy przebiegu, a nie wyniki dotyczące konwencji, więc zatrzymują działanie tam, gdzie wynik by go nie zatrzymał. Zakresy całego katalogu i pojedynczej encji nie wskazują żadnej encji Release i nie odczytują rejestru, więc linter odczytany przez nie z pamięci podręcznej jest sprawdzany wyłącznie względem manifestu w pamięci podręcznej. Przed tym wszystkim --release wymienia każde wycofanie zarejestrowane dla tego, od czego zależy encja Release, 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 lintera lub bramki — dzięki czemu przebieg informuje o tym nawet wtedy, gdy zatrzymuje go jedna z powyższych odmów. Wycofanie nie zmienia żadnego wyniku ani kodu wyjścia, a rejestr zaufania, który istnieje, ale nie można go odczytać, zatrzymuje przebieg, zamiast zostać uznany za rejestr, który niczego nie odnotowuje.

Dyscyplina encji: tryb lokalny i bramka publikacji

Tryb ze ścieżką encji działa z jednym z dwóch poziomów ważności:

  • Domyślny (lokalny). Uruchamia reguły dyscypliny na lokalnej treści encji z poziomem ważności warn. Bez dostępu do rejestru; sprawdzenie podbicia wersji jest pomijane. Należy go używać podczas tworzenia encji.
  • --pre-publish (bramka publikacji). Pobiera z rejestru najnowszą opublikowaną wersję encji, która nie jest wersją przedpremierową, uruchamia te same reguły z poziomem ważności halt, a dodatkowo klasyfikuje zmianę jako PATCH / MINOR / MAJOR i zatrzymuje się, jeśli proponowane podbicie metadata.version jest mniejsze, niż wymaga zmiana. Należy go używać w procesie publikacji, przed aggrega push. --pre-publish dotyczy wyłącznie postaci z pojedynczą encją.

Podbicie wersji ponad potrzebę jest zawsze dozwolone; zbyt małe podbicie powoduje zatrzymanie. Pierwsza publikacja encji (brak wcześniejszej wersji w rejestrze) pomija sprawdzenie podbicia i zgłasza ostrzeżenie, że nie przeprowadzono żadnej weryfikacji.

Jakie rodzaje sprawdza tryb encji

Tryb encji poddaje lintowaniu wskazany dokument niezależnie od jego rodzaju i przekazuje go każdej regule, która odczytuje jedną encję. Każda reguła sama decyduje, jakie rodzaje opisuje, a reguła, której przekazano rodzaj, którego nie opisuje, niczego nie zgłasza. Dlatego wskazanie encji Aggregate, Manifest, Release lub Workload — rodzajów, które przebieg po całym katalogu pomija i wymienia w swoim wierszu not checked: — również uruchamia na niej reguły, a zgłaszać mogą tylko reguły opisujące ten rodzaj:

RegułaRodzaje, których dotyczą zgłoszenia w trybie encji
Prefiks adnotacjiDowolny rodzaj: odczytuje metadata.annotations niezależnie od rodzaju dokumentu.
Bezpośrednie rozszerzenia x-aggrega-*Dowolny rodzaj: odczytuje spec.schema niezależnie od rodzaju dokumentu.
Kształt nazwyComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary i ArtifactLibrary.
Kategoria zgodna z katalogiemComponent.
Slot sekretu deklaruje sensitiveComponent i Feature.
Adnotacja poświadczeń metryk zgodna z providesComponent.
Provides zadeklarowane przez encję ComponentRecipe.
Dynamiczne refy, nadpisania IdSchemaLibrary.
Domyślne limity encji PluginPlugin.
Porównanie podbicia wersji (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate i Plugin (pluginu wbudowanego w kompilator się nie porównuje); zmiana dowolnego innego rodzaju jest klasyfikowana jako MAJOR.
Poświadczenie połączenia zgodne z kluczem celuŻaden: odczytuje całą encję Release, więc działa tylko z --release.

Encje Aggregate, Manifest, Release i Workload nie deklarują w swoich schematach ani metadata.annotations, ani spec.schema, więc dokument jednego z tych rodzajów zgodny ze schematem swojego rodzaju nie otrzymuje niczego od dwóch reguł odczytujących dowolny rodzaj; te dwie zgłaszają coś o nim tylko wtedy, gdy mimo to zawiera jeden z tych kluczy, który schemat jego rodzaju odrzuca jako nieoczekiwaną właściwość. Wskazanie encji Aggregate dodaje porównanie podbicia wersji w trybie --pre-publish, które porównuje ją z jej opublikowaną wersją, jak opisują kryteria poniżej.

Rubryka podbijania wersji

W trybie --pre-publish zmiana jest porównywana z poprzednią opublikowaną wersją i klasyfikowana:

  • PATCH — zmiany dotyczące wyłącznie dokumentacji lub komentarzy.
  • MINOR — zmiany ściśle addytywne (nowe pole opcjonalne, nowy wpis).
  • MAJOR — usunięcia, zawężenie typu lub zmiana wcześniej opcjonalnego pola na wymagane.

Porównanie odbywa się osobno dla każdego rodzaju encji: encje Component, Feature i SchemaLibrary są porównywane z uwzględnieniem ich pól niosących schemat; MappingLibrary jest porównywana na poziomie kluczy wpisów (treści wpisów są nieprzezroczyste, więc zmieniona treść jest zachowawczo traktowana jako MAJOR); Recipe i FeatureRecipe są porównywane na podstawie ich pól nośnych. Encja Aggregate jest porównywana na podstawie deklaracji parametrów, komponentów i podsystemów; wartość domyślna parametru trafia do porównania w nie większym stopniu niż jakakolwiek inna wartość parametru (zob. Co otrzymuje wtyczka lintera), więc zmiana ograniczona do wartości domyślnej — jej dodanie, zmiana lub usunięcie — nie jest jego częścią, podobnie jak zmiana klucza spoza słownika slotów parametrów. Zbyt małe podbicie wersji powoduje zatrzymanie z diagnostyką wskazującą wymagane podbicie.

Reguły dyscypliny

Większość reguł ma ustawienie na poziomie przestrzeni roboczej w lint.publishing_discipline w pliku .aggrega-config.yaml oraz odpowiadające mu nadpisanie w CLI, przy czym każde nadpisanie ma odpowiednik z przedrostkiem --no-. Pierwszeństwo ma --no-<flag> przed --<flag>, a ta przed wartością z konfiguracji przestrzeni roboczej, w każdym zakresie: całego katalogu, encji Release i pojedynczej encji. Każda reguła jest domyślnie włączona, a każde ustawienie domyślne wynika albo z mechanizmów platformy, albo z udokumentowanej konwencji katalogu; ustawienia służą do rezygnacji w przestrzeni roboczej, która ma powód, by złagodzić daną regułę.

Reguły bez ustawienia informują o tym w swoim opisie poniżej, a powód jest w każdym przypadku ten sam: zgłaszają fakt dotyczący encji i pozostawiają decyzję autorowi, więc nie ma oceny, którą można by złagodzić. Opisana wyżej rubryka podbijania wersji również nie ma ustawienia — porównuje proponowaną treść z opublikowaną wersją i zgłasza, czego wymaga zmiana, co jest właściwością zmiany, a nie preferencją przestrzeni roboczej.

  • Prefiks adnotacji — zarezerwowane przestrzenie nazw (aggrega.ai/ oraz feature.aggrega.ai/ poza encją Feature) należą do platformy i są odrzucane w innych kluczach. Domyślnie włączona; rezygnacja przez allow_aggrega_ai_prefix.
  • Kształt nazwy — każdy rodzaj encji ma konwencję kształtu nazwy (liczba segmentów dla rodzajów cloud-native; PascalCase dla rodzajów bibliotek). Domyślnie włączona; rezygnacja przez allow_nonstandard_names.
  • Odwołania dynamiczne — wpisy encji SchemaLibrary nie mogą używać $dynamicAnchor / $dynamicRef (wykonywane przez platformę w czasie kompilacji rozwijanie $ref nie potrafi ich rozwiązać). Domyślnie włączona; rezygnacja przez allow_dynamic_refs.
  • Nadpisania identyfikatora — wpisy encji SchemaLibrary nie mogą deklarować własnego $id (platforma wyprowadza kanoniczny $id). Domyślnie włączona; rezygnacja przez allow_id_overrides.
  • Kategoria zgodna z katalogiem — etykieta component.aggrega.ai/category encji Component musi odpowiadać pierwszemu segmentowi katalogu pod core/, pochodzącemu z zamkniętego zbioru kategorii (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Domyślnie włączona dla encji pod ścieżką core/; rezygnacja przez allow_category_mismatches.
  • Bezpośrednie rozszerzenia x-aggrega-* — bezpośrednie wpisywanie kluczy x-aggrega-* w schemacie encji Component lub Feature jest odradzane na rzecz pełnoprawnej ścieżki tworzenia. Domyślnie włączona; rezygnacja przez allow_direct_x_aggrega_extensions.
  • Provides zadeklarowane przez Component — spec.provides encji Recipe publikuje jeden klucz na wpis, a encja Component, którą Recipe implementuje, deklaruje w filarze provides swojego spec.schema, które klucze udostępnia dany typ. To właśnie z tą deklaracją sprawdzane jest odwołanie from: w inject, więc klucz publikowany przez Recipe bez deklaracji w encji Component jest wytwarzany, a następnie odrzucany tam, gdzie konsument go podłącza. Publikowanie poza zadeklarowanym kontraktem jest akceptowane w czasie budowania, dlatego wynik ma charakter doradczy, a nie odrzucenia. Domyślnie włączona dla encji Recipes; rezygnacja przez allow_undeclared_recipe_provides.
  • Domyślne limity encji Plugin — spec.runtime encji Plugin zawiera maxMemoryPages i timeoutMs, dwa limity stosowane przez hosta podczas ładowania i uruchamiania wtyczki. Encja Plugin, która nie ustala żadnego z nich, działa z wartościami domyślnymi platformy, co jest bezpiecznym wynikiem, a nie błędem, więc reguła zgłasza, że obowiązują wartości domyślne i że można ustalić jawne limity. Domyślnie włączona dla encji Plugin; nie ma ustawienia.
  • Slot na sekret deklaruje sensitive — slot załącznika może za pomocą selektora etykiet ustalić rodzaj encji Feature, która go wypełnia, na secret, a niezależnie zadeklarować sensitive: true, aby zapisać, że cokolwiek go wypełnia, obsługuje materiał tajny. Selektor określa, które wypełnienia są dopuszczalne; znacznik określa sposób obsługi. Slot, który ustala rodzaj, ale nie deklaruje znacznika, pozostawia ten sposób obsługi do ponownego wyprowadzenia z selektora zamiast bezpośredniego odczytu. Reguła odczytuje każdy slot deklarowany przez encję: sloty jej własnego bloku załączników w spec.featuresSchema, a w encji Component także sloty deklarowane przez każde gniazdo zależności w spec.usesSchema.<socket>.featuresSchema dla połączeń przez nie poprowadzonych — wynik dotyczący slotu gniazda wskazuje zarówno gniazdo, jak i slot. Domyślnie włączona dla encji Components i Features; nie ma ustawienia.
  • Poświadczenie połączenia zgodne z kluczem celu (connection-credential-matches-target-key) — serwer, który sprawdza klucz, przechowuje weryfikowany klucz w slocie własnej encji Component, a wywołujący przedstawia klucz na połączeniu, przez które dociera do serwera. Żadna ze stron nie widzi załączników drugiej, więc obie przechowują ten sam klucz tylko dlatego, że ich autorzy wpisują go po obu stronach — zwykle tak, że oba załączniki odczytują jeden parametr — a kompilacja nigdy ich nie porównuje. Ta reguła to robi i jest jedyną regułą, która odczytuje cały Release, dlatego działa w ramach --release i w żadnym innym zakresie. Obie strony znajduje po nazwach, które nadaje im standardowy katalog: klucz celu to slot api_key, który jego encja Component deklaruje w spec.featuresSchema, a klucz wywołującego to slot credential na połączeniu, zapisany w uses.<socket>.<alias>.features.credential w encji Aggregate lub na połączeniu, które łączy Release. Dla każdego połączenia, którego cel deklaruje api_key i nie jest oznaczony jako zarządzany, reguła zgłasza połączenie niosące poświadczenie do celu z niewypełnionym slotem klucza, wypełniony slot klucza bez poświadczenia na połączeniu oraz dwie strony, które nazywają swój sekret różnie. Porównuje lokalizator każdej strony — origin, który zapisuje załącznik, w values w encji Aggregate lub w infra w encji Release — w postaci zapisanej przez autora, więc dwie strony odczytujące jeden parametr są równe, a dwa literały porównuje się według tekstu; nic nie jest rozwiązywane, a zgłoszenie podaje komponent, połączenie, cel i oba sloty, ale nigdy nie cytuje żadnego lokalizatora, ponieważ zapisany tam tekst może być samym sekretem. Cel, który nie deklaruje slotu api_key, nie powoduje żadnego zgłoszenia, a slot niebędący kluczem wywołującego, taki jak token pobierania z rejestru serwera modeli, nigdy nie jest odczytywany. Nie ocenia się też celu, którego encja Component ma etykietę component.aggrega.ai/hosting: managed, niezależnie od zawartości jego slotu api_key: taka encja Component reprezentuje usługę prowadzoną przez jej dostawcę, więc nic, co uruchamia Release, nie sprawdza na niej klucza, a jeśli deklaruje ona api_key — na przykład klucz do hostowanego API modelu, pod nazwą nadaną przez produkt dostawcy — slot przechowuje klucz, który Release przedstawia temu dostawcy, nigdy klucz przedstawiany przez jej wywołujących. Cel z etykietą self-hosted, external lub mixed albo bez etykiety hostingu jest oceniany. Połączenie na gnieździe scrape_target — nazwie, którą standardowy katalog nadaje gniazdu, przez które scraper metryk dociera do swoich celów — jest scrapingiem, a to, czy poświadczenie scrapingu powinno być kluczem wywołującego celu, zależy od produktu celu: niektóre udostępniają metryki bez poświadczenia, niektóre zabezpieczają je kluczem przedstawianym przez każdego wywołującego, a niektóre przyjmują własny token. Dlatego w przypadku scrapingu reguła odczytuje to, co encja Component celu deklaruje w adnotacji observability.aggrega.ai/metrics-credential: przy none scraping w ogóle nie jest oceniany; przy separate-token jego poświadczenie nigdy nie jest porównywane z api_key celu, więc żadne z trzech zgłoszeń nie jest dla niego raportowane; przy target-key jest oceniany jak każde inne połączenie. Reguła odczytuje tylko te trzy wartości, więc scraping do celu bez adnotacji lub z dowolną inną wartością jest oceniany jak każde inne połączenie — a każde połączenie na innym gnieździe, w tym połączenie z modelem, narzędziem lub magazynem danych, jest oceniane tak samo, niezależnie od adnotacji celu. Reguła odczytuje załączniki zapisane na celu i na połączeniu: załącznik api_key docierający do celu z podsystemu lub granicy pozostawia to połączenie nieocenione, załącznik dodany przez adnotację nie należy do nich, więc slot klucza wypełniony tylko w ten sposób jest odczytywany jako niewypełniony, strona, której załącznik nie zapisuje lokalizatora, jest porównywana tylko pod kątem tego, czy jest wypełniona, a komponent dostarczony przez zaimportowany moduł nie jest odczytywany. Ponieważ nazwy slotów, etykieta hostingu, nazwa gniazda scrapingu i adnotacja metryk są konwencjami katalogu, których nie oznacza żadne słowo kluczowe schematu, katalog nazywający sloty inaczej nie powoduje żadnych zgłoszeń, gniazdo scrapingu nazwane inaczej jest oceniane jak każde inne gniazdo, a encja Component, która przechowuje klucz dostawcy w slocie o nazwie api_key bez etykiety zarządzania, jest odczytywana jako cel sprawdzający ten klucz, ponieważ nazwa slotu, etykieta i adnotacja to wszystko, co reguła odczytuje z encji Component celu. Domyślnie włączona; wyłączenie przez allow_connection_credential_mismatches.
  • Adnotacja poświadczenia metryk zgodna z provides (metrics-credential-annotation-matches-provides) — encja Component może podawać dwa fakty o swoich metrykach. Jej adnotacja observability.aggrega.ai/metrics-credential określa, jak uwierzytelniają się metryki produktu: none — są udostępniane bez poświadczenia; target-key — przyjmują klucz, którego Component wymaga od każdego wywołującego, ten przechowywany w jej slocie api_key; separate-token — przyjmują własny token. Klucz provides metrics_credential_required, zadeklarowany w filarze provides jej spec.schema, jest tym, co publikuje każda z jej encji Recipes, aby określić, czy metryki jednej instancji wymagają poświadczenia — co może zależeć od konfiguracji instancji, ponieważ metryki zabezpieczone kluczem wywołującego wymagają go tylko wtedy, gdy klucz jest dołączony, więc adnotacja nie może go zastąpić. Oba wyrażają jeden fakt o produkcie, dlatego ta reguła wymaga ich zgodności: zgłaszana jest zarówno encja Component z adnotacją none, która deklaruje ten klucz, jak i encja z adnotacją target-key lub separate-token, która go nie deklaruje, a zgłoszenie podaje encję Component, wartość adnotacji oraz nadmiarowy lub brakujący klucz. Encja Component bez adnotacji lub z dowolną inną wartością nie powoduje żadnego zgłoszenia. Reguła odczytuje encję Component w postaci zapisanej, więc encja Component rozszerzająca inną — której schemat jest schematem jej bazy — nie powoduje zgłoszenia, a jej baza jest odczytywana tam, gdzie została zadeklarowana; filar provides zapisany jako referencja, kompozycja lub treść ujęta jako tekst nie jest czymś, co reguła może wyliczyć, więc taka encja Component również nie powoduje zgłoszenia. Domyślnie włączona dla encji Components; nie ma ustawienia.

Niezmienność artefaktów nie należy do tych reguł i nie ma ustawienia. Opublikowana para name:version jest ostateczna: aggrega push porównuje digest już opublikowany pod tym tagiem z digestem, który dałaby treść przeznaczona do wypchnięcia, i odmawia nadpisania go inną treścią. Ponowne wypchnięcie treści identycznej co do bajtu niczego nie przesyła i dołącza tylko to, czego tej publikacji jeszcze brakuje — datę publikacji oraz podpis, jeśli wypchnięcie podpisuje. Żadna flaga ani żadne ustawienie konfiguracji przestrzeni roboczej tego nie łagodzi, ponieważ rejestr nie udostępnia ścieżki nadpisania, którą operator mógłby włączyć. Zmieniona treść jest publikowana w nowej wersji; to --pre-publish weryfikuje tę zmianę wersji względem poprzedniego wydania.

Flagi nadpisujące poszczególne reguły są bramkami dla pojedynczego wywołania i celowo nie mają zmiennej środowiskowej — mają już oparcie w konfiguracji w .aggrega-config.yaml pod lint.publishing_discipline. Ogólny model pierwszeństwa AGGREGA_* opisano w environment-variables.md.

Czas budowania i czas publikacji

Reguła zniechęcająca do x-aggrega-* działa również podczas aggrega build, gdzie zgłasza ostrzeżenie; aggrega lint --pre-publish podnosi to samo zgłoszenie do rangi błędu. Lokalne kompilacje przekazują je jako zalecenie; bramka publikacji je egzekwuje.

Podczas pisania, w edytorze

Edytor zadaje o encji katalogu dwa różne pytania i są to te same dwa, od których zaczyna się ta strona. Czy encja jest poprawna — czy się parsuje, czy filary się rozwiązują, czy się renderuje? To jest aggrega validate, a sesja edytora zawsze na to odpowiada. Czy encja nadaje się do publikacji — czy nazwa jest zgodna z konwencją, czy plik leży w katalogu, którego oczekuje jego kategoria, czy prefiksy adnotacji są właściwe? To są te reguły, a sesja edytora odpowiada na to tylko na żądanie.

Jest to wyłączone, dopóki się tego nie włączy. Włącza się to ustawieniem serve.lint_on_validate w pliku .aggrega-config.yaml tego obszaru roboczego, o którego encjach mają być podawane wskazówki:

serve:
lint_on_validate: true

Nie ma do tego flagi wiersza poleceń i jest to celowe: pytanie dotyczy własnej treści konkretnego obszaru roboczego, a osoba pisząca ten obszar roboczy nie jest tą, która uruchamia serwer języka — robi to edytor.

Po włączeniu każda walidowana encja niesie także te ustalenia, każde z nazwą reguły, która je wygenerowała, obok ustaleń dotyczących poprawności. Wynikają z tego trzy rzeczy i to one sprawiają, że można z tego korzystać podczas pisania:

  • Ustalenia pozostają doradcze. Encja łamiąca konwencję nadal przechodzi walidację, a jej encja Release nadal się rozwiązuje i renderuje. Włączenie ustawienia dodaje warstwę wskazówek; nigdy nie sprawia, że edytor odmawia pracy.
  • Oba rodzaje można odróżnić. Każdy publikowany problem wskazuje warstwę, która go zgłosiła, więc problem z nazwą i błąd rozwiązywania w tym samym pliku są odczytywane jako dwie różne rzeczy, a nie jako jeden problem zgłoszony dwukrotnie.
  • Sprawdzane jest to, co zostało wpisane. Reguły czytają bufor, a nie plik na dysku, więc poprawiona nazwa przestaje być zgłaszana jeszcze przed zapisaniem.

W tej warstwie działa tylko tryb treści lokalnej: żaden rejestr nie jest odpytywany, nic nie jest pobierane, nic nie jest zapisywane. Do porównania --pre-publish dochodzi się, prosząc o nie — edytor wysyła o nie żądanie, tak samo jak wpisuje się --pre-publish w terminalu — a nigdy przez zmianę powyższego ustawienia. Sprawdzenie uruchamiane przy każdym dotknięciu dokumentu to właśnie miejsce, w którym rejestr nie może być odpytywany, dlatego ten tryb pozostaje czymś wywoływanym jawnie, a nie czymś, co działa przy okazji.

Jawne żądanie sprawdzenia działa niezależnie od ustawienia, we wszystkich trzech powyższych zakresach. Obszar roboczy, który nigdy nie włączył warstwy działającej przy każdej edycji, nadal może więc poprosić edytor o przejrzenie katalogu, domknięcia encji Release lub jednej encji — i otrzymać te same ustalenia, które wypisuje to polecenie. Ustawienie decyduje jedynie o tym, czy sprawdzenie działa także tam, gdzie nie zażądano go wprost.

Szczegóły protokołu są rozłożone na dwie strony: co oznacza żądanie i kiedy je wysyłać, opisuje dokumentacja polecenia aggrega serve, a jego parametry i kształt odpowiedzi, pole po polu, opisuje dokumentacja formatu komunikacji.

Wybór lintera

Reguły są dostarczane jako standardowa wtyczka Wasm lintera publikacji. Ponieważ reguły znajdują się we wtyczce, a nie w kompilatorze, przedsiębiorstwo może wskazać aggrega lint inną wtyczkę, aby egzekwować własną dyscyplinę katalogu bez zmieniania kompilatora.

Przestrzeń robocza może dołączyć więcej niż jeden linter w plugins.linter i uruchamiane jest każde dołączenie: w kolejności, w jakiej dołączenia są zapisane, każde w swojej funkcji wejściowej, a wszystkie ich wyniki są zgłaszane razem. Dzięki temu katalog może zachować standardowe reguły i dodać obok nich własne, zamiast wybierać między jednymi a drugimi. Wyjątkiem jest --plugin — uruchamia dokładnie jeden artefakt ze ścieżki w systemie plików zamiast skonfigurowanych dołączeń, co czyni go przydatnym podczas tworzenia reguły.

Dołączenie wskazuje swoją wtyczkę za pomocą uri:, a function: wskazuje funkcję wejściową tej wtyczki. Wpis, który podaje function:, a nie podaje uri:, wskazuje funkcję, która nie należy do żadnej wtyczki, więc konfiguracja jest odrzucana już przy odczycie, z kodem E0224, ze wskazaniem pliku i miejsca wpisu na liście — należy dodać uri wtyczki, która eksportuje tę funkcję. Wpis niepodający żadnego z nich niczego nie dołącza i jest pomijany; gdy jest jedynym wpisem, standardowy linter działa ze swoją domyślną funkcją wejściową, tak jak wtedy, gdy plugins.linter w ogóle nie ma.

Co otrzymuje wtyczka lintera

Żadna wartość parametru nie trafia do wtyczki lintera, w żadnym zakresie. Wartość parametru może sama być poświadczeniem — origin załącznika sekretu może być szablonem odczytującym parametr, który spełnia encja Release, a sekretem jest wtedy wartość tego parametru — a wtyczka dołączona przez przestrzeń roboczą może nie być jej autorstwa, dlatego każdy dokument jest przekazywany z wstrzymanymi wartościami parametrów:

  • Encja Aggregate zachowuje każdą deklarację parametru, zawierającą tylko klucze, którymi zapisuje się deklarację — słownik slotów parametrów: jej typ, opis i ograniczenia — i ta sama zasada obowiązuje każdą deklarację zagnieżdżoną pod jej properties, items i valuesType. Klucz default deklaracji jest wstrzymywany na każdym poziomie przez usunięcie klucza, a nie opróżnienie go, więc wtyczka nie może stwierdzić, czy deklaracja go podaje. Klucz spoza tego słownika jest wstrzymywany wraz z całą zawartością, na każdym poziomie: kompilacja nie nadaje takiemu kluczowi żadnego znaczenia, a szkic z błędnie zapisanym kluczem może zawierać pod nim sekret. Wpis pod parameters, który nie jest deklaracją, jest wstrzymywany w całości.
  • Każdy moduł wymieniony pod aggregates encji Aggregate traci swój blok parameters, który zawiera wartości przekazywane do tego modułu.
  • Encja Release traci swój blok parameters, niezależnie od tego, czy zapisuje wartości bezpośrednio, czy importuje je za pomocą $import.
  • Każdy inny dokument, który zawiera blok parameters pod spec, traci go w całości; żaden inny rodzaj go nie deklaruje.

Dotyczy to encji wskazanej w wierszu poleceń, opublikowanej wersji, z którą porównuje ją --pre-publish, każdej encji przechodzonej w przebiegach dla całego katalogu i --release oraz dokumentów, które otrzymuje reguła odczytująca całą encję Release. Szablon odczytujący parametr nie jest wartością i zachowuje swój tekst, więc reguła nadal widzi, który parametr odczytuje zapisana przez autora wartość.

Przykłady

Przeszukanie całego katalogu pod kątem odstępstw od konwencji:

aggrega lint --catalog ./catalog

Lokalne lintowanie encji w trakcie jej tworzenia:

aggrega lint core/datastore/postgres/component.yaml

Uruchomienie bramki publikacji przed opublikowaniem nowej wersji:

aggrega lint core/datastore/postgres/component.yaml --pre-publish

Złagodzenie jednej reguły na czas pojedynczego uruchomienia:

aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names

Zobacz także

  • ./aggrega-validate.md — odpowiednik sprawdzający poprawność w tych samych trzech zakresach.
  • ./aggrega-build.md — waliduje w ramach kompilacji; zgłasza ostrzeżenie dotyczące x-aggrega-* z poziomem ważności warn.
  • ./aggrega-push.md — publikuje encję w rejestrze; aggrega lint --pre-publish to bramka, która poprzedza publikację.
  • ./aggrega-pull.md — rozwiązuje i przypina zależności.
  • ./aggrega-serve.md — serwer języka, który zgłasza te wyniki w edytorze, oraz ustawienie włączające warstwę sprawdzania przy każdej edycji.
  • ../errors/warnings.md — ostrzeżenia niekrytyczne, w tym wyniki lintowania w trybie lokalnym.

Składnia

aggrega lint [entity-path] [flags]

Opis

aggrega lint checks publishing CONVENTIONS — naming, category-directory
alignment, annotation prefixes, and the rest of the publishing-linter
discipline. It does not check correctness (schema, pillars, resolution,
render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity
aggrega lint --release <path> conventions across a Release's dependency closure
aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rules
over every catalog entity found under the catalog directories. Where the
workspace configuration gives its Releases catalog directories of their own
under workspace.releases, it runs them once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass. With --release it runs them over the entities that
Release's closure reaches, and also runs the rules that read a whole
Release: once, over the Aggregate it deploys, the Release and the
Components the Aggregate's components are instances of, with every
parameter value removed. In both, findings are advisory (warn severity)
and never halt.
With an entity path, lint runs the publishing-linter rule set against
that one entity. In default mode the rules run at warn severity over
local content without consulting any registry. With --pre-publish the
previous registry version is fetched and the schema-evolution
classification is compared against the proposed version bump; mismatches
halt. --pre-publish applies to the single-entity shape only. Per-workspace
policy flags from .aggrega-config.yaml's lint.publishing_discipline block
can be overridden per invocation via the --allow-*/--no-allow-* flag pairs,
in all three shapes.
All three shapes accept -o json, which replaces the human report on standard
output with one structured document: every finding with its severity, the rule
that produced it, its short code (the code printed at the head of its row in
the human report, which aggrega explain expands), its message, and the entity
file it concerns, plus counts by severity. A finding from a rule Aggrega does
not declare, one a linter of your own adds, carries no short code, as its row
prints none. A finding carries a line and column only when the rule that
produced it located the issue that precisely; otherwise the file alone locates
it. The message is the rule's own text, carried through unchanged, so the
structured and human renderings never word a finding differently. The exit
status is the same under either format.

Flagi

FlagaDomyślnieOpis
--allow-aggrega-ai-prefixfalseWymusza allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseWymusza allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseWymusza allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseWymusza allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseWymusza allow_dynamic_refs=true dla tego wywołania
--allow-id-overridesfalseWymusza allow_id_overrides=true dla tego wywołania
--allow-nonstandard-namesfalseWymusza allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseWymusza allow_undeclared_recipe_provides=true
--baseline—Porównuje sprawdzenie ewolucji przed publikacją z tą konkretną, już opublikowaną wersją zamiast z automatycznie wybraną najwyższą wersją niższą od publikowanej; musi to być tag zgodny ze ścisłym SemVer obecny w rejestrze (wymaga —pre-publish)
--catalog[]Katalog; można powtarzać. 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 nie wczytuje żadnego lokalnego katalogu. Używane przez przebiegi konwencji dla całego katalogu i dla —release.
--entity—Ścieżka do pliku YAML encji do lintowania (alternatywnie można ją przekazać jako argument pozycyjny)
--no-allow-aggrega-ai-prefixfalseWymusza allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseWymusza allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseWymusza allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseWymusza allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseWymusza allow_dynamic_refs=false dla tego wywołania
--no-allow-id-overridesfalseWymusza allow_id_overrides=false dla tego wywołania
--no-allow-nonstandard-namesfalseWymusza allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseWymusza allow_undeclared_recipe_provides=false
--output, -otextFormat wyjścia: text|json.
--plugin—Ścieżka w systemie plików do artefaktu .wasm lintera publikacji (uruchamia ten artefakt zamiast podłączeń plugins.linter obszaru roboczego)
--pre-publishfalsePobiera poprzednią wersję z rejestru i weryfikuje proponowaną zmianę wersji względem klasyfikacji ewolucji schematu
--release—Ścieżka do pliku YAML encji Release, aby sprawdzić konwencje w jej rozwiązanym domknięciu zależności (wyklucza się z argumentem encji). Ś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 folderu samej encji Release