İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

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 --catalog dizinleri, ardından workspace.catalog_dirs, ardından varsa çalışma alanı kökündeki catalog dizini.

  • workspace.releases altı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 --catalog dizinleri 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-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)

    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 json ile belge ayrıca passes içerir: her geçişin releases, catalogDirs, findings ve summary alanları; üst düzeydeki findings ve summary ise 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 ile node_modules, vendor ve dist dışında herhangi bir yerde bulunan ve kind değeri Release olan 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ği PATCH / MINOR / MAJOR olarak sınıflandırır; önerilen metadata.version artışı değişikliğin gerektirdiğinden küçükse durur. Yayın akışında, aggrega push öncesinde kullanın. --pre-publish yalnı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:

KuralVarlık kipinde raporladığı türler
Ek açıklama önekiHer 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çimiComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary ve ArtifactLibrary.
Kategori dizinle eşleşirComponent.
Gizli bilgi slotu sensitive bildirirComponent ve Feature.
Metrik kimlik bilgisi ek açıklaması provides ile eşleşirComponent.
Component tarafından bildirilen ProvidesRecipe.
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şirHiç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ışında feature.aggrega.ai/) platforma aittir ve diğer anahtarlarda reddedilir. Varsayılan olarak açıktır; allow_aggrega_ai_prefix ile 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_names ile devre dışı bırakılır.
  • Dinamik başvurular — SchemaLibrary girdileri $dynamicAnchor / $dynamicRef kullanamaz (platformun derleme zamanındaki $ref genişletmesi bunları çözümleyemez). Varsayılan olarak açıktır; allow_dynamic_refs ile devre dışı bırakılır.
  • Id geçersiz kılmaları — SchemaLibrary girdileri kendi $id değerlerini bildiremez (kanonik $id değerini platform türetir). Varsayılan olarak açıktır; allow_id_overrides ile devre dışı bırakılır.
  • Kategori dizinle eşleşir — bir Component’in component.aggrega.ai/category etiketi, 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_mismatches ile devre dışı bırakılır.
  • Doğrudan x-aggrega-* uzantıları — bir Component veya Feature şemasında x-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_extensions ile devre dışı bırakılır.
  • Provides’ın Component tarafından bildirilmesi — bir Recipe’nin spec.provides alanı her girdi için bir anahtar yayımlar ve Recipe’nin uyguladığı Component, spec.schema alanının provides sütununda türün hangi anahtarları sunduğunu bildirir. Bir inject from: 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_provides ile devre dışı bırakılır.
  • Plugin varsayılan sınırları — bir Plugin’in spec.runtime alanı, ana bilgisayarın plugin’i yükleyip çalıştırırken uyguladığı iki üst sınır olan maxMemoryPages ve timeoutMs değ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ü secret olarak sabitleyebilir ve ayrıca onu dolduran her şeyin gizli malzeme işlediğini kaydetmek için sensitive: true bildirebilir. 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.featuresSchema altı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çin spec.usesSchema.<socket>.featuresSchema altı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 --release altı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’inin spec.featuresSchema içinde bildirdiği api_key yuvasıdır; çağıranınki ise bağlantı üzerindeki credential yuvasıdır ve Aggregate’te ya da Release’in bağladığı bir bağlantıda uses.<socket>.<alias>.features.credential konumuna yazılır. Hedefi api_key bildiren 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’te values içinde ya da Release’te infra iç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_key yuvası 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’i component.aggrega.ai/hosting: managed olarak etiketlenmiş bir hedef de, api_key yuvası 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 ve api_key bildirdiğ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, external veya mixed olarak etiketlenmiş ya da hiçbir barındırma etiketi taşımayan bir hedef değerlendirilir. scrape_target soketindeki 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’inin observability.aggrega.ai/metrics-credential ek açıklamasında belirttiğini okur: none altında toplama hiç değerlendirilmez; separate-token altında kimlik bilgisi hiçbir zaman hedefin api_key’i ile karşılaştırılmaz, dolayısıyla üç bulgudan hiçbiri onun için raporlanmaz; target-key altı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 bir api_key eki 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 olmadan api_key adlı 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_mismatches ile 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-credential ek 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ı, yani api_key yuvasının tuttuğu anahtarı alırlar; separate-token, kendilerine ait bir belirteç alırlar. spec.schema içindeki provides sütununda bildirilen metrics_credential_required provides 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: none olarak açıklanıp anahtarı bildiren bir Component ile target-key veya separate-token olarak 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ış bir provides sü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: true

Bunun 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, items ve valuesType altında iç içe geçmiş her bildirim de aynı kurala tabidir. Bildirimin default değ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. parameters altında bildirim olmayan bir girdi bütünüyle alıkonulur.
  • Bir Aggregate’in aggregates altında listelenen her modül, o modüle aktarılan değerleri tutan parameters bloğunu kaybeder.
  • Bir Release, değerleri satır içinde yazsa da $import ile içe aktarsa da parameters bloğunu kaybeder.
  • spec altında bir parameters bloğ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 ./catalog

Yazım sırasında bir varlığı yerel olarak lint edin:

aggrega lint core/datastore/postgres/component.yaml

Yeni bir sürümü yayımlamadan önce yayım kapısını çalıştırın:

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

Tek bir çalıştırma için bir kuralı gevşetin:

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

Ayrı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-publish ondan ö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-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.

Bayraklar

BayrakVarsayılanAçıklama
--allow-aggrega-ai-prefixfalseallow_aggrega_ai_prefix=true değerini zorla
--allow-category-mismatchesfalseallow_category_mismatches=true değerini zorla
--allow-connection-credential-mismatchesfalseallow_connection_credential_mismatches=true değerini zorla
--allow-direct-x-aggrega-extensionsfalseallow_direct_x_aggrega_extensions=true değerini zorla
--allow-dynamic-refsfalseBu çağrı için allow_dynamic_refs=true değerini zorla
--allow-id-overridesfalseBu çağrı için allow_id_overrides=true değerini zorla
--allow-nonstandard-namesfalseallow_nonstandard_names=true değerini zorla
--allow-undeclared-recipe-providesfalseallow_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-prefixfalseallow_aggrega_ai_prefix=false değerini zorla
--no-allow-category-mismatchesfalseallow_category_mismatches=false değerini zorla
--no-allow-connection-credential-mismatchesfalseallow_connection_credential_mismatches=false değerini zorla
--no-allow-direct-x-aggrega-extensionsfalseallow_direct_x_aggrega_extensions=false değerini zorla
--no-allow-dynamic-refsfalseBu çağrı için allow_dynamic_refs=false değerini zorla
--no-allow-id-overridesfalseBu çağrı için allow_id_overrides=false değerini zorla
--no-allow-nonstandard-namesfalseallow_nonstandard_names=false değerini zorla
--no-allow-undeclared-recipe-providesfalseallow_undeclared_recipe_provides=false değerini zorla
--output, -otextÇı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-publishfalseKayı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