aggrega lint
aggrega lint, yayımlama uzlaşımlarını denetler: adlandırma, kategori-dizin uyumu, açıklama (annotation) önekleri, şema yazma disiplini ve sürüm artışı boyutu. Argümanıyla seçilen üç kipi vardır; bu kipler aynı uzlaşım disiplinini üç kapsamda uygular: tüm katalog (argümansız), tek bir Release’in bağımlılık kapanışı (--release) ve tek bir varlık dosyası (isteğe bağlı bir --pre-publish yayımlama kapısıyla birlikte bir varlık yolu). Her kapsam, kataloğun farklı bir dilimi üzerinde aynı soruyu yanıtlar: “bu içerik kataloğun yayımlama disiplinine uyuyor mu?”
Uzlaşımlar doğruluktan ayrıdır. aggrega lint, içeriğin iyi biçimli olup olmadığını ya da derlenip derlenmeyeceğini hiçbir zaman denetlemez; bu, şema, sütunlar, başvuru çözümleme, extends, girdi türü yeteneği ve render için aynı üç kapsamı yansıtan aggrega validate komutunun işidir. Seçici dilbilgisinin okuyamadığı bir soket ya da slot seçicisi bir doğruluk hatasıdır, bu nedenle lint onun hakkında hiçbir şey raporlamaz: validate onu tüm katalog üzerinde ya da tek bir Component veya Feature üzerinde reddeder — bkz. bildirilen seçiciler. İki komut birbirini tamamlar: validate size içeriğin doğru olup olmadığını söyler; lint ise kataloğun uzlaşımlarına göre yayımlanabilir olup olmadığını söyler.
aggrega lint isteğe bağlıdır. Derleyicinin kendisi katalog disiplini konusunda kendi görüşü olmayan bir yapıda kalır; bu kurallar, çalıştırmayı sizin seçtiğiniz ayrı bir eklentide yer alır. aggrega lint komutunu hiç çalıştırmayan bir çalışma alanı yine de derlenir ve yayımlanır.
Varlık yolu konumsal olarak ya da --entity <path> ile verilebilir. --release, bir varlık argümanıyla birlikte kullanılamaz; ikisi farklı kapsamlar seçer ve her ikisinin birden verilmesi çalışmayı durdurur.
Tüm katalog uzlaşımları (argümansız)
Argümansız çalıştırılan aggrega lint, yapılandırılmış katalog dizinleri altında bulunan her katalog varlığı üzerinde yapısal yayımlama disiplini kurallarını çalıştırır. Bulgular tavsiye niteliğindedir: warn önem düzeyinde raporlanırlar ve yalnızca bir uzlaşım bulgusu nedeniyle asla durdurmazlar. Bir kataloğu adlandırma, kategori dizini ve ek açıklama öneki sapmalarına karşı taramak için kullanın. Bir katalog dizinindeki bir Aggregate, Manifest, Release veya Workload denetlenmek yerine atlanır: geçiş, bu türlerin her birini özetinden sonra bir not checked: satırında sayar ve sizi her türden bir belgeyi denetleyen varlık kipine yönlendirir.
Bir katalog dizini altındaki bir YAML dosyası, satırlarından biri girintisiz olarak apiVersion: ve tırnaklı ya da tırnaksız aggrega.ai/ ile başlayan bir değerle başlıyorsa bir Aggrega belgesidir. Okunamayan, YAML’i ayrıştırılamayan ya da kind, metadata veya spec alanı bir varlık zarfının biçiminde olmayan bir Aggrega belgesi — örneğin liste olarak yazılmış bir metadata — dizinler okunduktan sonra çalıştırmayı E0175 ile durdurur ve bu tür her dosyayı, okumanın veya ayrıştırıcının verdiği nedenle birlikte adlandırır; hiçbir şey denetlenmez ve conventions checked satırı yazdırılmaz. Yüklenen ancak hiçbir kataloğun tutmadığı bir kind bildiren bir belge — örneğin yanlış yazılmış bir Componnent ya da hiç kind olmaması — aynı çalıştırmayı E0371 ile durdurur ve bildirdiği türle birlikte bunların yanında adlandırılır; bir Manifest, bir Release ve bir Recipe’nin kendi dizininden içe aktardığı bir Workload atlanır. Diğer her YAML — işlenene kadar ayrıştırılamayan bir Helm chart’ının şablonları, chart değerleri, iş akışı tanımları — atlanır. --release da katalog dizinleri altındaki böyle bir belgede aynı şekilde durur.
Hangi dizinlerin okunacağı çalışma alanının yapısına bağlıdır:
-
Yapılandırması kendine ait hiçbir Release katalog dizini vermeyen bir çalışma alanı, arama yığını üzerinde bir kez denetlenir: önce
--catalogdizinleri, ardındanworkspace.catalog_dirs, ardından varsa çalışma alanı kökündekicatalogdizini. -
workspace.releasesaltında Releases adlandıran bir çalışma alanı, bir kataloğu her biri kendi Release’i tarafından okunan birkaç varyant hâlinde yan yana tutabilir; tümü üzerinde tek bir geçiş her varyantı aynı anda okur ve bir varyantın varlığı diğerininkini gölgeler. Bu nedenle çalışma alanı, barındırdığı her Release için bir kez, o Release’in okuduğu dizinler üzerinde denetlenir; her geçişte--catalogdizinleri ilk sırada yer alır. Yapılandırmanın adlandırmadığı bir Release, çalışma alanının listesini okur. Her geçiş, Release’ini ve okuduğu dizinleri adlandıran bir satırın altında raporlanır; ardından o geçişin bulguları ve kendi özeti gelir:Release release-compose.yaml reads catalog-composeconventions checked: 7 entities, 0 advisory finding(s)Release release-helm-synth.yaml reads catalog-helm-synthconventions checked: 8 entities, 0 advisory finding(s)Tam olarak aynı dizinleri okuyan Releases, her birini adlandıran tek bir geçişi paylaşır; böylece oradaki bir bulgu bir kez raporlanır. Hiçbir dizin okumayan bir Release (girdisi
catalog_dirs: []yazar), denetlenecek bir şeyi olmadığı şeklinde raporlanır ve diğer geçişler her zamanki gibi çalışır.-o jsonile belge ayrıcapassesiçerir: her geçişinreleases,catalogDirs,findingsvesummaryalanları; üst düzeydekifindingsvesummaryise tüm geçişleri birlikte kapsar. Bir çalışma alanının barındırdığı Releases, onun Release belgeleridir: çalışma alanı kökü altında, gizli dizinler ilenode_modules,vendorvedistdışında herhangi bir yerde bulunan vekinddeğeriReleaseolan YAML dosyaları.
Hiçbir geçişte okunacak bir şey bulunmayan bir çalıştırma, temiz bir katalog olarak raporlanmak yerine reddedilir: varlıkları catalog/ altına koyun, --catalog geçirin veya workspace.catalog_dirs ayarlayın; Releases adlandıran bir çalışma alanında ise workspace.releases altında bir Release’in kendi catalog_dirs alanını ayarlayın. Geçerli çalışma dizinini asla örtük olarak taramaz.
Bir katalog dizininin altında bulunup çalışma alanının dışına (ya da çalışma alanı dışında adlandırdığınız bir dizinin dışına) çıkan bir bağlantı okunmaz ve çalıştırma, belgelerinden birini okuyamadığı bir kataloğu temiz olarak raporlamak yerine bağlantıyı adlandırarak orada durur; aynı dizinler üzerindeki bir derleme de aynı bağlantıda durur. Çalışma alanı sınırı kuralı ve çözümlerini açıklar.
Bir Release genelinde uzlaşımlar (--release)
aggrega lint --release <release-path>, aynı yapısal kuralları tüm katalog ya da tek bir varlık yerine tek bir Release’in çözümlenmiş kapanışının ulaştığı katalog varlık dosyaları üzerinde çalıştırır. Kapanışı bir derlemenin kullandığı mekanizmanın aynısıyla hesaplar, ardından her varlığın yazara ait katalog dosyasını denetler. Bir önbellek yuvasında bulunan, kayıt defterine sabitlenmiş bir varlığın denetlenecek yerel dosyası yoktur ve atlanır; yayımlama kuralları yerel olarak yazılmış dosyalara uygulanır. Tüm katalog kipinde olduğu gibi bulgular tavsiye niteliğindedir ve yalnızca bir uzlaşım bulgusu nedeniyle hiçbir zaman durdurmaz.
Bu aynı zamanda elinde bütün bir Release bulunan tek kapsamdır; dolayısıyla tek bir çalıştırmayı okuyan kurallar, yani Disiplin kuralları altında açıklanan bağlantı kimlik bilgisi kuralı burada çalışır. Böyle bir kural, varlık başına kurallardan sonra, her denetimde bir kez ve üç belge üzerinde çalışır: Release’in dağıttığı Aggregate, yazarının yazdığı haliyle; extends zinciri içine katlanmış Release, böylece bir alt Release miras aldıklarını taşır; ve Aggregate’in bildirdiği her component için o component’in örneği olduğu Component, kataloğun çözümlediği haliyle. Bunların arasında hiçbir parametre değeri yoktur, her kapsamda olduğu gibi: Release, bir tabandan miras aldığı değerler de dahil olmak üzere parameters bloğu olmadan gelir; Aggregate ise varsayılanları ya da içe aktardığı her modüle geçirdiği değerler olmadan gelir; bkz. Bir linter eklentisine verilenler. Bulguları Release dosyası altında raporlanır.
Bu, aynı kapanışı doğruluk açısından denetleyen aggrega validate --release komutunun uzlaşımlar karşılığıdır.
Bu kapsamın çalıştırdığı linter’lar, Release’in yanındaki güvenilir eklenti kimlikleri kaydına tabi tutulur, tıpkı bir derlemenin yaptığı gibi. Herhangi biri çalışmadan önce --release, yapılandırılmış plugins.linter eklerini eklenti güven kaydı ile karşılaştırır: yapılandırmanın artık eklemediği kayıtlı bir eklenti (bir linter ya da bir kapı) geçişi durdurur ve yapıtı kayıtlı olan olmayan, önbellekten okunan bir linter çalıştırılmak yerine reddedilir. Önbellekten okunan bir linter, yüklendiğinde kayıtlı imzasına da tabi tutulur: girdisi doğrulanmış bir imza kaydediyorsa, bu bilginin önbellekte adını verdiği imza malzemesi yeniden denetlenir ve imzalama gereksinimi ne derse desin, malzeme eksik ya da farklıysa geçiş E0144 ile, okunan linter’dan farklı bir eklenti için yapılmışsa (başka bir girdiden kopyalanmış bir signature) E0332 ile durur; çalışma alanının güven yapılandırması bir imza gerektiriyorsa, hiç imza kaydetmeyen bir girdi ya da linter için hiç girdi olmaması (silinmiş bir kayıt dahil), aggrega pull komutunun onu imzasız olarak reddetmesine yol açacak ayarların aynısı altında geçişi E0331 ile durdurur. Üçünün her biri çözüm olarak aggrega pull --release <release> komutunu belirtir; bu komut linter’ın imzasını kayıt defterinde doğrular, kaydeder ve adını verdiği paketi önbelleğe alır, artık özetiyle eşleşmeyen önbellekteki bir kopyayı yeniden yazar. Derleyici ikili dosyasının içindeki kopyadan sunulan bir linter hiçbir zaman bu gereksinime tabi tutulmaz. Bunlar uzlaşım bulguları değil geçişin başarısızlıklarıdır; bu nedenle bir bulgunun durdurmayacağı yerde durdururlar. Tüm katalog ve tek varlık kapsamları hiçbir Release adı vermez ve hiçbir kayıt okumaz; bu nedenle önbellekten okudukları bir linter yalnızca önbellekteki manifestine göre denetlenir. Tüm bunlardan önce --release, Release’in bağlı olduğu şeylere karşı kaydedilmiş her geri çekmeyi bir deprecation: satırı olarak, aggrega build komutunun yazdırdığı sözcüklerle adlandırır; bu, lockfile’ın sabitlenmiş bir başvuruya karşı kaydettiği işareti de, güven kaydının bir linter’a ya da bir kapıya karşı kaydettiği işareti de kapsar; böylece geçiş, yukarıdaki retlerden biri onu durdursa bile bunu bildirir. Bir geri çekme hiçbir bulguyu ve hiçbir çıkış kodunu değiştirmez; mevcut olup okunamayan bir güven kaydı ise hiçbir şey kaydetmeyen bir kayıt sayılmak yerine geçişi durdurur.
Varlık disiplini: yerel ve yayın kapısı
Varlık yolu modu iki önem düzeyinden biriyle çalışır:
- Varsayılan (yerel). Disiplin kurallarını yerel varlık içeriği üzerinde
warnönem düzeyinde çalıştırır. Kayıt defterine erişilmez; sürüm artırma denetimi atlanır. Yazım sırasında kullanın. --pre-publish(yayın kapısı). Varlığın yayımlanmış en son ön sürüm olmayan sürümünü kayıt defterinden getirir, aynı kurallarıhaltönem düzeyinde çalıştırır ve ayrıca değişikliğiPATCH/MINOR/MAJORolarak sınıflandırır; önerilenmetadata.versionartışı değişikliğin gerektirdiğinden küçükse durur. Yayın akışında,aggrega pushöncesinde kullanın.--pre-publishyalnızca tek varlık biçimine uygulanır.
Gereğinden fazla artırmaya her zaman izin verilir; gereğinden az artırma durdurur. Bir varlığın ilk yayını (kayıt defterinde önceki sürüm yoksa) artırma denetimini atlar ve hiçbir doğrulama yapılmadığını belirten bir uyarı gösterir.
Varlık kipinin denetlediği türler
Varlık kipi, adlandırdığınız belgeyi türü ne olursa olsun lint’ten geçirir ve onu tek bir varlığı okuyan her kurala verir. Her kural hangi türleri tanımladığına kendisi karar verir ve tanımlamadığı bir tür verilen kural hiçbir şey raporlamaz. Dolayısıyla bir Aggregate, Manifest, Release veya Workload adlandırmak — tüm katalog geçişinin atladığı ve not checked: satırında listelediği türler — kuralları onun üzerinde de çalıştırır ve yalnızca o türü tanımlayan kurallar raporlayabilir:
| Kural | Varlık kipinde raporladığı türler |
|---|---|
| Ek açıklama öneki | Her tür: belgenin türü ne olursa olsun metadata.annotations alanını okur. |
Doğrudan x-aggrega-* uzantıları | Her tür: belgenin türü ne olursa olsun spec.schema alanını okur. |
| Ad biçimi | Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary ve ArtifactLibrary. |
| Kategori dizinle eşleşir | Component. |
| Gizli bilgi slotu sensitive bildirir | Component ve Feature. |
| Metrik kimlik bilgisi ek açıklaması provides ile eşleşir | Component. |
| Component tarafından bildirilen Provides | Recipe. |
| Dinamik ref’ler, Id geçersiz kılmaları | SchemaLibrary. |
| Plugin varsayılan sınırları | Plugin. |
Sürüm artırma karşılaştırması (--pre-publish) | Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate ve Plugin (derleyiciye yerleşik bir eklenti karşılaştırılmaz); başka herhangi bir türdeki değişiklik MAJOR olarak sınıflandırılır. |
| Bağlantı kimlik bilgisi hedef anahtarla eşleşir | Hiçbiri: bütün bir Release’i okur, bu nedenle yalnızca --release altında çalışır. |
Bir Aggregate, Manifest, Release ve Workload şemalarında ne metadata.annotations ne de spec.schema bildirir; bu nedenle bunlardan birine ait olup türünün şemasıyla eşleşen bir belge, her türü okuyan iki kuraldan hiçbir bulgu almaz. Bu iki kural onun hakkında yalnızca belge yine de bu anahtarlardan birini taşıdığında raporlar; türünün şeması bunu beklenmeyen bir özellik olarak reddeder. Bir Aggregate adlandırmanın kattığı şey, --pre-publish altındaki sürüm artırma karşılaştırmasıdır; bu karşılaştırma onu aşağıdaki ölçüt bölümünün açıkladığı gibi yayımlanmış sürümüyle karşılaştırır.
Sürüm artırma ölçütleri
--pre-publish kipinde değişiklik, önceki yayımlanmış sürümle karşılaştırılır ve sınıflandırılır:
PATCH— yalnızca dokümantasyon veya yorum değişiklikleri.MINOR— kesinlikle yalnızca ekleme niteliğindeki değişiklikler (yeni bir isteğe bağlı alan, yeni bir girdi).MAJOR— kaldırmalar, tür daraltma veya önceden isteğe bağlı olan bir alanın zorunlu hâle gelmesi.
Karşılaştırma varlık türüne göre yapılır: Component, Feature ve SchemaLibrary, şema taşıyan alanları gözetilerek karşılaştırılır; MappingLibrary girdi anahtarı düzeyinde karşılaştırılır (girdi gövdeleri opaktır, bu nedenle değişmiş bir gövde ihtiyatlı biçimde MAJOR olarak ele alınır); Recipe ve FeatureRecipe ise yük taşıyan alanları üzerinden karşılaştırılır. Bir Aggregate; parametre bildirimleri, bileşenleri ve alt sistemleri üzerinden karşılaştırılır; bir parametrenin varsayılan değeri karşılaştırmaya diğer herhangi bir parametre değerinden daha fazla ulaşmaz (bkz. Bir linter eklentisine neler verilir), dolayısıyla yalnızca bir varsayılan değerle sınırlı bir değişiklik — bir varsayılanın eklenmesi, değiştirilmesi veya kaldırılması — karşılaştırmanın parçası değildir; parametre yuvası sözcük dağarcığı dışındaki bir anahtarda yapılan değişiklik de öyle. Yetersiz artırma, gereken artırmayı belirten bir tanılama iletisiyle durdurulur.
Disiplin kuralları
Çoğu kuralın .aggrega-config.yaml içinde lint.publishing_discipline altında çalışma alanı başına bir ayarı ve buna karşılık gelen bir CLI geçersiz kılması vardır; her geçersiz kılmanın bir --no- karşılığı bulunur. Öncelik sırası her kapsamda (katalogun tamamı, bir Release ve tek bir varlık) şöyledir: --no-<flag>, --<flag>’in üzerindedir; o da çalışma alanı yapılandırma değerinin üzerindedir. Her kural varsayılan olarak açıktır ve her varsayılan ya platform mekanizmasına ya da belgelenmiş bir katalog uzlaşımına dayanır; ayarlar, birini gevşetmek için bir nedeni olan çalışma alanının devre dışı bırakma seçenekleridir.
Ayarı olmayan kurallar bunu aşağıdaki girdilerinde belirtir ve gerekçe her durumda aynıdır: bu kurallar varlık hakkında bir olguyu bildirir ve kararı yazara bırakır, dolayısıyla gevşetilecek bir yargı yoktur. Yukarıda açıklanan sürüm artırma ölçütünün de ayarı yoktur; önerilen içeriği yayımlanmış sürümle karşılaştırır ve değişikliğin neyi gerektirdiğini bildirir; bu, bir çalışma alanı tercihi değil, değişikliğin bir özelliğidir.
- Açıklama öneki — ayrılmış ad alanları (
aggrega.ai/ve bir Feature dışındafeature.aggrega.ai/) platforma aittir ve diğer anahtarlarda reddedilir. Varsayılan olarak açıktır;allow_aggrega_ai_prefixile devre dışı bırakılır. - Ad biçimi — her varlık türünün bir ad biçimi uzlaşımı vardır (bulutta yerel türler için segment sayıları; kütüphane türleri için PascalCase). Varsayılan olarak açıktır;
allow_nonstandard_namesile devre dışı bırakılır. - Dinamik başvurular — SchemaLibrary girdileri
$dynamicAnchor/$dynamicRefkullanamaz (platformun derleme zamanındaki$refgenişletmesi bunları çözümleyemez). Varsayılan olarak açıktır;allow_dynamic_refsile devre dışı bırakılır. - Id geçersiz kılmaları — SchemaLibrary girdileri kendi
$iddeğerlerini bildiremez (kanonik$iddeğerini platform türetir). Varsayılan olarak açıktır;allow_id_overridesile devre dışı bırakılır. - Kategori dizinle eşleşir — bir Component’in
component.aggrega.ai/categoryetiketi,core/altındaki ilk dizin segmentiyle eşleşmeli ve kapalı kategori kümesinden (ai-agent,ai-model,ai-tool,ai-pipeline,datastore,gateway,mesh,network,messaging,storage,compute,observability,security,bigdata,devtool) alınmalıdır.core/yolu altındaki varlıklar için varsayılan olarak açıktır;allow_category_mismatchesile devre dışı bırakılır. - Doğrudan
x-aggrega-*uzantıları — bir Component veya Feature şemasındax-aggrega-*anahtarlarını doğrudan yazmak, birinci sınıf yazım yolu lehine önerilmez. Varsayılan olarak açıktır;allow_direct_x_aggrega_extensionsile devre dışı bırakılır. - Provides’ın Component tarafından bildirilmesi — bir Recipe’nin
spec.providesalanı her girdi için bir anahtar yayımlar ve Recipe’nin uyguladığı Component,spec.schemaalanınınprovidessütununda türün hangi anahtarları sunduğunu bildirir. Birinjectfrom:başvurusu bu bildirime göre denetlenir; dolayısıyla Component bildirmeden bir Recipe’nin yayımladığı anahtar üretilir, ancak bir tüketici onu bağladığında reddedilir. Bildirilen sözleşmenin ötesinde yayımlama derleme zamanında kabul edilir; bu nedenle bulgu bir ret değil, tavsiye niteliğindedir. Recipes için varsayılan olarak açıktır;allow_undeclared_recipe_providesile devre dışı bırakılır. - Plugin varsayılan sınırları — bir Plugin’in
spec.runtimealanı, ana bilgisayarın plugin’i yükleyip çalıştırırken uyguladığı iki üst sınır olanmaxMemoryPagesvetimeoutMsdeğerlerini taşır. Hiçbirini sabitlemeyen bir Plugin platform varsayılanlarıyla çalışır; bu güvenli bir sonuçtur ve hata değildir, bu yüzden kural varsayılanların geçerli olduğunu ve sabitlenebilecek açık sınırların bulunduğunu bildirir. Plugin varlıkları için varsayılan olarak açıktır; ayarı yoktur. - Gizli yuva sensitive bildirir — bir ek yuvası, etiket seçicisi aracılığıyla onu dolduran Feature türünü
secretolarak sabitleyebilir ve ayrıca onu dolduran her şeyin gizli malzeme işlediğini kaydetmek içinsensitive: truebildirebilir. Seçici hangi doldurmaların kabul edilebilir olduğunu belirtir; işaretçi ise işlemeyi belirtir. Türü sabitleyip işaretçi bildirmeyen bir yuva, bu işlemenin doğrudan okunmak yerine seçiciden yeniden türetilmesine bırakır. Kural, bir varlığın bildirdiği her yuvayı okur:spec.featuresSchemaaltındaki kendi ek bloğunun yuvalarını ve bir Component üzerinde, her bağımlılık soketinin içinden bağlanan bağlantılar içinspec.usesSchema.<socket>.featuresSchemaaltında bildirdiği yuvaları; bir soketin yuvasına ilişkin bulgu, yuvanın yanı sıra soketi de adlandırır. Components ve Features için varsayılan olarak açıktır; ayarı yoktur. - Bağlantı kimlik bilgisi hedef anahtarla eşleşir (
connection-credential-matches-target-key) — bir anahtarı denetleyen sunucu, doğruladığı anahtarı kendi Component’inin bir yuvasında tutar; çağıran ise anahtarı, sunucuya ulaştığı bağlantı üzerinde sunar. Uçlardan hiçbiri diğerinin eklerini görmez; dolayısıyla ikisi yalnızca yazarları anahtarı her iki uca da yazdığı için tek bir anahtarı tutar — genellikle her iki ekin tek bir parametreyi okumasıyla — ve bir derleme bunları hiçbir zaman karşılaştırmaz. Bu kural karşılaştırır; ayrıca bütün bir Release’i okuyan tek kuraldır, bu yüzden--releasealtında çalışır ve başka hiçbir kapsamda çalışmaz. Her iki ucu, standart kataloğun onlara verdiği adlarla bulur: hedefin anahtarı, Component’ininspec.featuresSchemaiçinde bildirdiğiapi_keyyuvasıdır; çağıranınki ise bağlantı üzerindekicredentialyuvasıdır ve Aggregate’te ya da Release’in bağladığı bir bağlantıdauses.<socket>.<alias>.features.credentialkonumuna yazılır. Hedefiapi_keybildiren ve managed olarak etiketlenmemiş her bağlantı için şunları raporlar: anahtar yuvası doldurulmamış bir hedefe kimlik bilgisi taşıyan bir bağlantı, bağlantıda kimlik bilgisi olmayan dolu bir anahtar yuvası ve gizli değerlerini farklı adlandıran iki uç. Karşılaştırdığı şey, her ucun konum belirleyicisidir — bir ekin yazdığıorigin, Aggregate’tevaluesiçinde ya da Release’teinfraiçinde — yazarın yazdığı haliyle; böylece tek bir parametreyi okuyan iki uç eşit sayılır, iki sabit değer ise metinleriyle karşılaştırılır. Hiçbir şey çözümlenmez ve bir bulgu bileşeni, bağlantıyı, hedefi ve iki yuvayı adlandırır ama konum belirleyicilerden hiçbirini asla alıntılamaz, çünkü oraya yazılan metin gizli değerin kendisi olabilir.api_keyyuvası bildirmeyen bir hedef hiçbir bulguya yol açmaz ve çağıran anahtarı olmayan bir yuva, örneğin bir model sunucusunun kayıt defteri çekme belirteci, hiçbir zaman okunmaz. Component’icomponent.aggrega.ai/hosting: managedolarak etiketlenmiş bir hedef de,api_keyyuvası ne tutarsa tutsun değerlendirilmez: böyle bir Component, satıcısının çalıştırdığı bir hizmeti temsil eder; dolayısıyla Release’in çalıştırdığı hiçbir şey onun üzerinde anahtar denetlemez veapi_keybildirdiğinde — örneğin barındırılan bir model API’sinin anahtarını, satıcının ürününün ona verdiği adla — yuva, çağıranlarının sunduğu bir anahtarı değil, Release’in o satıcıya sunduğu anahtarı tutar.self-hosted,externalveyamixedolarak etiketlenmiş ya da hiçbir barındırma etiketi taşımayan bir hedef değerlendirilir.scrape_targetsoketindeki bir bağlantı — standart kataloğun, bir metrik toplayıcının hedeflerine ulaştığı sokete verdiği ad — bir toplamadır (scrape) ve bir toplamanın kimlik bilgisinin hedefin çağıran anahtarı olup olmaması gerektiği hedefin ürününe bağlıdır: bazıları metriklerini kimlik bilgisi olmadan sunar, bazıları her çağıranın sunduğu anahtarın arkasına koyar, bazıları da kendine ait bir belirteç alır. Bu yüzden bir toplama için kural, hedefin Component’ininobservability.aggrega.ai/metrics-credentialek açıklamasında belirttiğini okur:nonealtında toplama hiç değerlendirilmez;separate-tokenaltında kimlik bilgisi hiçbir zaman hedefinapi_key’i ile karşılaştırılmaz, dolayısıyla üç bulgudan hiçbiri onun için raporlanmaz;target-keyaltında diğer her bağlantı gibi değerlendirilir. Kural yalnızca bu üç değeri okur; bu yüzden ek açıklaması olmayan ya da başka bir değere sahip bir hedefe yapılan toplama diğer her bağlantı gibi değerlendirilir — ve başka bir soketteki her bağlantı, model, araç veya veri deposu bağlantıları dahil, hedefin ek açıklaması ne derse desin aynı şekilde değerlendirilir. Kural, hedefe ve bağlantıya yazılan ekleri okur: hedefe bunun yerine bir alt sistemden veya bir sınırdan ulaşan birapi_keyeki o bağlantıyı değerlendirilmemiş bırakır, bir ek açıklamanın eklediği ek bunların arasında değildir — bu nedenle yalnızca bu yolla doldurulan bir anahtar yuvası doldurulmamış olarak okunur —, eki hiçbir konum belirleyici yazmayan bir uç yalnızca dolu olup olmadığına göre karşılaştırılır ve içe aktarılan bir modülün katkıda bulunduğu bir bileşen okunmaz. Yuva adları, barındırma etiketi, toplama soketinin adı ve metrik ek açıklaması hiçbir şema anahtar sözcüğünün işaretlemediği katalog uzlaşımları olduğundan, yuvaları farklı adlandıran bir katalog hiçbir bulguya yol açmaz, farklı adlandırılmış bir toplama soketi diğer her soket gibi değerlendirilir ve bir satıcının anahtarını managed etiketi olmadanapi_keyadlı bir yuvada tutan bir Component, o anahtarı denetleyen bir hedef olarak okunur; çünkü kuralın bir hedefin Component’inden okuduğu şeylerin tamamı yuvanın adı, etiket ve ek açıklamadır. Varsayılan olarak açıktır;allow_connection_credential_mismatchesile devre dışı bırakılabilir. - Metrik kimlik bilgisi ek açıklaması provides ile eşleşir (
metrics-credential-annotation-matches-provides) — bir Component, metrikleri hakkında iki olgu belirtebilir.observability.aggrega.ai/metrics-credentialek açıklaması, ürünün metriklerinin nasıl kimlik doğruladığını belirtir:none, kimlik bilgisi olmadan sunulurlar;target-key, Component’in her çağırandan istediği anahtarı, yaniapi_keyyuvasının tuttuğu anahtarı alırlar;separate-token, kendilerine ait bir belirteç alırlar.spec.schemaiçindekiprovidessütununda bildirilenmetrics_credential_requiredprovides anahtarı ise Recipes’inin her birinin, bir örneğin metriklerinin kimlik bilgisi gerektirip gerektirmediğini söylemek için yayımladığı şeydir — bu, örneğin nasıl yapılandırıldığına bağlı olabilir, çünkü çağıran anahtarının arkasındaki metrikler yalnızca bir anahtar ekliyken kimlik bilgisi gerektirir; bu yüzden ek açıklama onun yerini tutamaz. İkisi ürün hakkında tek bir olguyu belirtir, bu nedenle bu kural ikisinin uyuşmasını bekler:noneolarak açıklanıp anahtarı bildiren bir Component iletarget-keyveyaseparate-tokenolarak açıklanıp bildirmeyen bir Component ayrı ayrı raporlanır ve bulgu Component’i, ek açıklamanın değerini ve fazla ya da eksik olan anahtarı adlandırır. Ek açıklaması olmayan ya da başka bir değere sahip bir Component hiçbir bulguya yol açmaz. Kural Component’i yazıldığı haliyle okur; bu yüzden başka birini genişleten bir Component — şeması tabanınınki olan — hiçbir bulguya yol açmaz ve tabanı bildirildiği yerde okunur; başvuru olarak yazılmış birprovidessütunu, bir bileşim ya da metin olarak yazılmış kaçışlı bir gövde kuralın sıralayabileceği bir şey değildir, dolayısıyla o Component de hiçbir bulguya yol açmaz. Components için varsayılan olarak açıktır; hiçbir ayarı yoktur.
Yapıt değişmezliği bu kurallardan biri değildir ve hiçbir ayarı yoktur. Yayımlanmış bir name:version kesindir: aggrega push, o etikette zaten yayımlanmış özeti, gönderilmek üzere olan içeriğin üreteceği özetle karşılaştırır ve farklı içerikle üzerine yazmayı reddeder. Bayt bayt aynı içeriği yeniden göndermek hiçbir şey yüklemez ve yalnızca o yayının hâlâ eksik olanlarını ekler — yayın tarihini ve gönderimin imzaladığı durumlarda imzasını. Hiçbir bayrak ve hiçbir çalışma alanı yapılandırma ayarı bunu gevşetmez, çünkü kayıt defteri bir operatörün seçebileceği hiçbir üzerine yazma yolu sunmaz. Değişen içerik yeni bir sürüm altında yayımlanır; o sürüm artışını önceki sürüme karşı doğrulayan --pre-publish’tir.
Kural başına geçersiz kılma bayrakları çağrı başına geçitlerdir ve kasıtlı olarak hiçbir ortam değişkenine sahip değildir — zaten .aggrega-config.yaml içinde lint.publishing_discipline altında yapılandırmayla desteklenirler. Genel AGGREGA_* öncelik modeli environment-variables.md sayfasında açıklanır.
Derleme zamanı ve yayımlama zamanı
x-aggrega-* kullanımını caydıran kural aggrega build sırasında da çalışır ve orada bir uyarı olarak ortaya çıkar; aggrega lint --pre-publish aynı bulguyu bir hataya yükseltir. Yerel derlemeler bu tavsiyeyi taşır; yayımlama kapısı ise onu uygular.
Yazarken, düzenleyicinizde
Düzenleyiciniz bir katalog varlığı hakkında iki farklı soru sorar ve bunlar bu sayfanın açıldığı iki sorudur. Varlık doğru mu — ayrıştırılıyor mu, sütunlar çözümleniyor mu, işleniyor mu? Bu aggrega validate komutudur ve bir düzenleyici oturumu bu soruyu her zaman yanıtlar. Varlık yayımlanabilir mi — ad uzlaşıma uyuyor mu, dosya kategorisinin beklediği dizinde mi duruyor, açıklama önekleri doğru mu? Bu, bu kurallardır ve bir düzenleyici oturumu bu soruyu yalnızca siz istediğinizde yanıtlar.
Siz açmadıkça kapalıdır. Önerileri almak istediğiniz varlıkların bulunduğu çalışma alanının .aggrega-config.yaml dosyasında serve.lint_on_validate ile açın:
serve: lint_on_validate: trueBunun için bir komut satırı bayrağı yoktur ve bu bilinçli bir tercihtir: soru belirli bir çalışma alanının kendi içeriğiyle ilgilidir ve siz dil sunucusunu başlatan değil, o çalışma alanını yazan kişisiniz — dil sunucusunu düzenleyiciniz başlatır.
Açık olduğunda, doğruladığınız her varlık doğruluk bulgularının yanında bu bulguları da taşır; her biri kendisini üreten kuralı adlandırır. Bundan üç şey çıkar ve yazarken kullanılabilir olmasını sağlayan da bunlardır:
- Bulgular öneri niteliğinde kalır. Bir uzlaşımı bozan varlık yine de doğrulanır ve Release’i yine de çözümlenir ve işlenir. Ayarı açmak bir öneri katmanı ekler; düzenleyicinizin çalışmayı reddetmesine asla yol açmaz.
- İkisini birbirinden ayırt edebilirsiniz. Yayımlanan her sorun, kendisini ortaya çıkaran katmanı adlandırır; böylece aynı dosyadaki bir adlandırma sorunu ile bir çözümleme hatası, iki kez bildirilen tek bir sorun olarak değil, iki farklı şey olarak okunur.
- Denetlenen, yazdığınız şeydir. Kurallar diskteki dosyayı değil arabelleği okur; böylece düzelttiğiniz bir ad, siz kaydetmeden önce bildirilmeyi bırakır.
O katmanda yalnızca yerel içerik kipi çalışır: hiçbir kayıt defterine başvurulmaz, hiçbir şey getirilmez, hiçbir şey yazılmaz. --pre-publish karşılaştırmasına onu isteyerek ulaşılır — düzenleyiciniz, terminalde --pre-publish yazmanızla aynı şekilde bunun için bir istek gönderir — ve yukarıdaki ayarı düzenleyerek asla ulaşılmaz. Bir belgeye her dokunduğunuzda çalışan bir denetim, tam da bir kayıt defterine ulaşılmaması gereken yerdir; bu yüzden o kip, kendiliğinden eşlik eden bir şey değil, sizin çağırdığınız bir şey olarak kalır.
Denetimi doğrudan istemek, ayar ne derse desin, yukarıdaki üç kapsamın hepsinde çalışır. Dolayısıyla düzenleme başına katmanı hiç açmamış bir çalışma alanı da düzenleyicisinden kataloğu, bir Release’in kapanışını ya da tek bir varlığı taramasını isteyebilir — ve bu komutun yazdırdığı bulguların aynısını alır. Ayar yalnızca denetimin, onu adıyla istemediğiniz yerlerde de çalışıp çalışmayacağını belirler.
Protokol ayrıntıları iki sayfaya dağılmıştır: isteğin ne anlama geldiği ve ne zaman gönderileceği aggrega serve başvurusunda, parametreleri ve yanıtının biçimi ise alan alan kablo biçimi başvurusunda yer alır.
Linter’ı seçmek
Kurallar, standart bir yayımlama linter’ı Wasm eklentisi olarak gelir. Kurallar derleyicide değil bir eklentide bulunduğundan, bir kuruluş kendi katalog disiplinini uygulamak için derleyiciyi değiştirmeden aggrega lint’i farklı bir eklentiye yönlendirebilir.
Bir çalışma alanı plugins.linter altında birden fazla linter ekleyebilir ve her ekleme çalışır: eklemelerin yazıldığı sırayla, her biri kendi giriş fonksiyonunda, tüm bulguları birlikte raporlanarak. Bir kataloğun ikisi arasında seçim yapmak yerine standart kuralları koruyup kendi kurallarını onların yanına eklemesini sağlayan budur. --plugin bunun istisnasıdır: yapılandırılmış eklemelerin yerine bir dosya sistemi yolundan tam olarak tek bir yapıtı çalıştırır; bir kural geliştirilirken onu kullanışlı kılan da budur.
Bir ekleme, eklentisini uri: ile adlandırır; function: ise o eklentideki bir giriş işlevini adlandırır. Bir function: adlandıran ama uri: adlandırmayan bir girdi, hiçbir eklentide olmayan bir işlevi adlandırır; bu nedenle yapılandırma okunurken E0224 altında, dosyayı ve girdinin listesindeki yerini adlandırarak reddedilir — işlevi dışa aktaran eklentinin uri değerini ekleyin. İkisini de adlandırmayan bir girdi hiçbir şey eklemez ve atlanır; tek girdi o olduğunda standart linter, hiç plugins.linter olmadığında olduğu gibi kendi varsayılan giriş işleviyle çalışır.
Bir linter plugin’ine ne verilir
Hiçbir kapsamda bir linter plugin’ine hiçbir parametre değeri ulaşmaz. Bir parametrenin değeri bizzat bir kimlik bilgisi olabilir — bir gizli bilgi eklentisinin origin alanı, Release’in karşıladığı bir parametreyi okuyan bir şablon olabilir ve bu durumda gizli bilgi o parametrenin değeridir — ve bir çalışma alanının eklediği plugin, o çalışma alanının yazmadığı bir plugin olabilir; bu nedenle her belge, parametre değerleri alıkonularak teslim edilir:
- Bir Aggregate her parametre bildirimini korur ve bu bildirimde yalnızca bir bildirimin yazılabildiği anahtarları tutar — parametre yuvası sözlüğü: türü, açıklaması ve kısıtları — ve
properties,itemsvevaluesTypealtında iç içe geçmiş her bildirim de aynı kurala tabidir. Bildirimindefaultdeğeri her düzeyde, anahtar boşaltılarak değil kaldırılarak alıkonulur; böylece bir plugin, bir bildirimin varsayılan değer verip vermediğini ayırt edemez. Bu sözlüğün dışındaki bir anahtar, içerdiği her şeyle birlikte her düzeyde alıkonulur: derleme böyle bir anahtara hiçbir anlam vermez ve bir anahtarı yanlış yazan bir taslak, onun altında bir gizli bilgi taşıyabilir.parametersaltında bildirim olmayan bir girdi bütünüyle alıkonulur. - Bir Aggregate’in
aggregatesaltında listelenen her modül, o modüle aktarılan değerleri tutanparametersbloğunu kaybeder. - Bir Release, değerleri satır içinde yazsa da
$importile içe aktarsa daparametersbloğunu kaybeder. specaltında birparametersbloğu taşıyan diğer her belge bu bloğu bütünüyle kaybeder; başka hiçbir tür böyle bir blok bildirmez.
Bu; komut satırında adı verilen varlık, --pre-publish seçeneğinin onu karşılaştırdığı yayımlanmış sürüm, tüm katalog ve --release geçişlerinin dolaştığı her varlık ve bir Release’in tamamını okuyan bir kuralın aldığı belgeler için geçerlidir. Bir parametreyi okuyan şablon bir değer değildir ve metnini korur; böylece bir kural, yazılmış bir değerin hangi parametreyi okuduğunu yine de görür.
Örnekler
Uzlaşım sapmalarını bulmak için tüm kataloğu tarayın:
aggrega lint --catalog ./catalogYazım sırasında bir varlığı yerel olarak lint edin:
aggrega lint core/datastore/postgres/component.yamlYeni bir sürümü yayımlamadan önce yayım kapısını çalıştırın:
aggrega lint core/datastore/postgres/component.yaml --pre-publishTek bir çalıştırma için bir kuralı gevşetin:
aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-namesAyrıca bakınız
- ./aggrega-validate.md — aynı üç kapsamda doğruluk denetimi yapan karşılığı.
- ./aggrega-build.md — derlemenin bir parçası olarak doğrular;
x-aggrega-*uyarısınıwarnönem düzeyinde gösterir. - ./aggrega-push.md — bir varlığı kayıt defterinde yayımlar;
aggrega lint --pre-publishondan önce gelen denetim kapısıdır. - ./aggrega-pull.md — bağımlılıkları çözümler ve sabitler.
- ./aggrega-serve.md — bu bulguları düzenleyicinizde bildiren dil sunucusu ve düzenleme başına katmanı açan ayar.
- ../errors/warnings.md — yerel mod lint bulguları dahil, ölümcül olmayan uyarılar.
Kullanım
aggrega lint [entity-path] [flags]Açıklama
aggrega lint checks publishing CONVENTIONS — naming, category-directoryalignment, annotation prefixes, and the rest of the publishing-linterdiscipline. 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 rulesover every catalog entity found under the catalog directories. Where theworkspace configuration gives its Releases catalog directories of their ownunder workspace.releases, it runs them 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 it runs them over the entities thatRelease's closure reaches, and also runs the rules that read a wholeRelease: once, over the Aggregate it deploys, the Release and theComponents the Aggregate's components are instances of, with everyparameter value removed. In both, findings are advisory (warn severity)and never halt.
With an entity path, lint runs the publishing-linter rule set againstthat one entity. In default mode the rules run at warn severity overlocal content without consulting any registry. With --pre-publish theprevious registry version is fetched and the schema-evolutionclassification is compared against the proposed version bump; mismatcheshalt. --pre-publish applies to the single-entity shape only. Per-workspacepolicy flags from .aggrega-config.yaml's lint.publishing_discipline blockcan 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 standardoutput with one structured document: every finding with its severity, the rulethat produced it, its short code (the code printed at the head of its row inthe human report, which aggrega explain expands), its message, and the entityfile it concerns, plus counts by severity. A finding from a rule Aggrega doesnot declare, one a linter of your own adds, carries no short code, as its rowprints none. A finding carries a line and column only when the rule thatproduced it located the issue that precisely; otherwise the file alone locatesit. The message is the rule's own text, carried through unchanged, so thestructured and human renderings never word a finding differently. The exitstatus is the same under either format.Bayraklar
| Bayrak | Varsayılan | Açıklama |
|---|---|---|
--allow-aggrega-ai-prefix | false | allow_aggrega_ai_prefix=true değerini zorla |
--allow-category-mismatches | false | allow_category_mismatches=true değerini zorla |
--allow-connection-credential-mismatches | false | allow_connection_credential_mismatches=true değerini zorla |
--allow-direct-x-aggrega-extensions | false | allow_direct_x_aggrega_extensions=true değerini zorla |
--allow-dynamic-refs | false | Bu çağrı için allow_dynamic_refs=true değerini zorla |
--allow-id-overrides | false | Bu çağrı için allow_id_overrides=true değerini zorla |
--allow-nonstandard-names | false | allow_nonstandard_names=true değerini zorla |
--allow-undeclared-recipe-provides | false | allow_undeclared_recipe_provides=true değerini zorla |
--baseline | — | Yayın öncesi evrim denetimini, yayımlanan sürümün altındaki otomatik seçilen en yüksek sürüm yerine, daha önce yayımlanmış bu belirli sürümle karşılaştır; kayıt defterinde bulunan katı SemVer etiketi olmalıdır (—pre-publish gerektirir) |
--catalog | [] | Katalog dizini; yinelenebilir. Her —catalog <dir>, katalog arama yığınının başına eklenir (ilk eşleşme kazanır): çalışma alanının catalog_dirs değeri ya da çalışma alanı yapılandırmasının workspace.releases altında kendi dizinlerini verdiği bir Release için o Release’in dizinleri; yığın, varsa çalışma alanı kökündeki catalog adlı dizinle biter. Boş yazılmış bir catalog_dirs listesi hiçbir yerel katalog okumaz. Tüm katalog ve —release uzlaşım geçişlerince kullanılır. |
--entity | — | Lint uygulanacak varlık YAML’ının yolu (alternatif olarak konumsal argüman olarak verin) |
--no-allow-aggrega-ai-prefix | false | allow_aggrega_ai_prefix=false değerini zorla |
--no-allow-category-mismatches | false | allow_category_mismatches=false değerini zorla |
--no-allow-connection-credential-mismatches | false | allow_connection_credential_mismatches=false değerini zorla |
--no-allow-direct-x-aggrega-extensions | false | allow_direct_x_aggrega_extensions=false değerini zorla |
--no-allow-dynamic-refs | false | Bu çağrı için allow_dynamic_refs=false değerini zorla |
--no-allow-id-overrides | false | Bu çağrı için allow_id_overrides=false değerini zorla |
--no-allow-nonstandard-names | false | allow_nonstandard_names=false değerini zorla |
--no-allow-undeclared-recipe-provides | false | allow_undeclared_recipe_provides=false değerini zorla |
--output, -o | text | Çıktı biçimi: text|json. |
--plugin | — | Yayın linter’ı .wasm yapıtının dosya sistemi yolu (çalışma alanının plugins.linter eklemeleri yerine bu yapıtı çalıştırır) |
--pre-publish | false | Kayıt defterindeki önceki sürümü getir ve önerilen sürüm artışını şema evrimi sınıflandırmasına göre doğrula |
--release | — | Çözümlenmiş bağımlılık kapanışı üzerinde uzlaşımları denetlemek için bir Release YAML’ının yolu (varlık argümanıyla birlikte kullanılamaz). Göreli yol, çalışma alanı köküne göre değil, komutu çalıştırdığınız dizine göre çözümlenir. Bu dizin hiçbir çalışma alanında değilse ve kök belirtilmemişse, mutlak yol çalışma alanını Release’in kendi klasöründen bulur |