Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

aggrega lint

aggrega lint memeriksa konvensi publikasi — penamaan, keselarasan kategori dengan direktori, prefiks anotasi, disiplin penulisan skema, dan besarnya kenaikan versi. Perintah ini memiliki tiga mode, dipilih berdasarkan argumennya, yang menerapkan disiplin konvensi yang sama pada tiga cakupan: seluruh katalog (tanpa argumen), closure dependensi satu Release (--release), dan file satu entitas (path entitas, dengan gerbang publikasi --pre-publish opsional). Setiap cakupan menjawab pertanyaan yang sama — “apakah konten ini mengikuti disiplin publikasi katalog?” — atas irisan katalog yang berbeda.

Konvensi berbeda dari kebenaran. aggrega lint tidak pernah memeriksa apakah konten terbentuk dengan baik atau dapat dikompilasi — itu adalah tugas aggrega validate, yang mencerminkan tiga cakupan yang sama untuk skema, pilar, resolusi referensi, extends, kapabilitas jenis input, dan render. Selector socket atau slot yang tidak dapat dibaca oleh tata bahasa selector merupakan kesalahan kebenaran, sehingga lint tidak melaporkan apa pun tentangnya: validate menolaknya, atas seluruh katalog atau atas satu Component atau Feature — lihat selector yang dideklarasikan. Kedua perintah saling melengkapi: validate memberi tahu Anda apakah konten benar; lint memberi tahu Anda apakah konten dapat dipublikasikan menurut konvensi katalog.

aggrega lint bersifat opsional. Compiler itu sendiri tetap tanpa opini sendiri tentang disiplin katalog; aturan-aturan ini berada dalam plugin terpisah yang Anda pilih untuk dijalankan. Workspace yang tidak pernah menjalankan aggrega lint tetap dapat di-build dan dipublikasikan.

Path entitas dapat diberikan secara posisional atau dengan --entity <path>. --release saling eksklusif dengan argumen entitas — keduanya memilih cakupan yang berbeda; memberikan keduanya akan menghentikan proses.

Konvensi seluruh katalog (tanpa argumen)

aggrega lint tanpa argumen menjalankan aturan struktural disiplin publikasi atas setiap entitas katalog yang ditemukan di bawah direktori katalog yang dikonfigurasi. Temuan bersifat anjuran — dilaporkan dengan tingkat keparahan warn, temuan tidak pernah menghentikan proses hanya karena satu temuan konvensi. Gunakan untuk menyisir katalog dari penyimpangan penamaan, kategori-direktori, dan prefiks anotasi. Aggregate, Manifest, Release, atau Workload di dalam direktori katalog dilewati alih-alih diperiksa: proses tersebut menghitung setiap jenis tersebut pada baris not checked: setelah ringkasannya dan mengarahkan Anda ke mode entitas, yang memeriksa dokumen dari jenis apa pun.

File YAML di bawah direktori katalog adalah dokumen Aggrega bila salah satu barisnya diawali, tanpa indentasi, dengan apiVersion: dan nilai yang diawali aggrega.ai/, baik dikutip maupun tidak. Dokumen Aggrega yang tidak dapat dibaca, yang YAML-nya tidak dapat di-parse, atau yang kind, metadata, atau spec-nya tidak berbentuk amplop entitas — misalnya metadata yang ditulis sebagai daftar — menghentikan eksekusi dengan E0175 setelah direktori dibaca, menyebutkan setiap file tersebut beserta alasan yang diberikan oleh pembacaan atau parser; tidak ada yang di-lint dan tidak ada baris conventions checked yang dicetak. Dokumen yang berhasil dimuat tetapi mendeklarasikan kind yang tidak ada di katalog mana pun — misalnya Componnent yang salah eja, atau tanpa kind sama sekali — menghentikan eksekusi yang sama dengan E0371, disebutkan di samping file-file tersebut beserta jenis yang dideklarasikannya; Manifest, Release, dan Workload yang diimpor Recipe dari direktorinya sendiri dilewati. YAML lain apa pun — template chart Helm, yang tidak dapat di-parse sampai dirender, values chart, definisi workflow — dilewati. --release berhenti dengan cara yang sama pada dokumen seperti itu di bawah direktori katalognya.

Direktori mana yang dibacanya bergantung pada bentuk workspace:

  • Workspace yang konfigurasinya tidak memberikan direktori katalog tersendiri kepada Release mana pun diperiksa sekali, atas tumpukan pencariannya: direktori --catalog, lalu workspace.catalog_dirs, lalu direktori catalog di root workspace jika ada.

  • Workspace yang menyebut beberapa Releases di bawah workspace.releases dapat menyimpan katalog dalam beberapa varian berdampingan, masing-masing dibaca oleh Release-nya sendiri, dan satu lintasan atas semuanya akan membaca setiap varian sekaligus — entitas dari satu varian membayangi entitas varian lain. Jadi workspace tersebut diperiksa sekali untuk setiap Release yang dimuatnya, atas direktori yang dibaca Release tersebut, dengan direktori --catalog lebih dulu dalam setiap lintasan; Release yang tidak disebut konfigurasi membaca daftar milik workspace. Setiap lintasan dilaporkan di bawah baris yang menyebut Release-nya dan direktori yang dibacanya, diikuti temuan lintasan tersebut dan ringkasannya sendiri:

    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 yang membaca direktori yang persis sama berbagi satu lintasan, yang menyebut masing-masing, sehingga sebuah temuan di sana dilaporkan sekali. Release yang tidak membaca direktori apa pun — entrinya menulis catalog_dirs: [] — dilaporkan sebagai tidak memiliki apa pun untuk diperiksa, dan lintasan lainnya berjalan seperti biasa. Dengan -o json, dokumen juga membawa passes: releases, catalogDirs, findings, dan summary dari setiap lintasan, sedangkan findings dan summary tingkat atas mencakup semua lintasan bersama-sama. Releases yang dimuat sebuah workspace adalah dokumen Release-nya — file YAML yang kind-nya adalah Release, di mana pun di bawah root workspace di luar direktori tersembunyi serta node_modules, vendor, dan dist.

Proses yang tidak memiliki apa pun untuk dibaca di lintasan mana pun ditolak alih-alih dilaporkan sebagai katalog yang bersih: letakkan entitas di bawah catalog/, berikan --catalog, atau tetapkan workspace.catalog_dirs — atau, di workspace yang menyebut beberapa Releases, catalog_dirs milik sebuah Release di bawah workspace.releases. Perintah ini tidak pernah secara implisit mengenumerasi direktori kerja saat ini.

Tautan di bawah direktori katalog yang mengarah keluar dari workspace — atau keluar dari direktori yang Anda sebutkan di luar workspace — tidak dibaca, dan proses berhenti di sana, dengan menyebut tautan tersebut, alih-alih melaporkan sebagai bersih sebuah katalog yang salah satu dokumennya tidak dapat dibaca; build atas direktori yang sama berhenti pada tautan yang sama. Batas workspace menguraikan aturan tersebut dan cara mengatasinya.

Konvensi di seluruh Release (--release)

aggrega lint --release <release-path> menjalankan aturan struktural yang sama atas file entitas katalog yang dijangkau closure hasil resolusi satu Release, alih-alih atas seluruh katalog atau satu entitas. Perintah ini menghitung closure melalui mesin yang sama yang digunakan build, lalu melakukan lint pada file katalog milik penulis setiap entitas. Entitas yang dipatok dari registry yang berada di slot cache tidak membawa file lokal untuk di-lint dan dilewati — aturan publikasi berlaku untuk file yang ditulis secara lokal. Seperti mode seluruh katalog, temuan bersifat anjuran dan tidak pernah menghentikan proses hanya karena satu temuan konvensi.

Ini juga satu-satunya cakupan yang memegang sebuah Release secara utuh, sehingga di sinilah aturan yang membaca Release dijalankan — aturan kredensial koneksi yang dijelaskan di Aturan disiplin. Aturan semacam itu dijalankan sekali per pemeriksaan, setelah aturan per entitas, atas tiga dokumen: Aggregate yang di-deploy oleh Release, sebagaimana ditulis penulisnya; Release, dengan rantai extends-nya digabungkan, sehingga Release turunan membawa apa yang diwarisinya; dan, untuk setiap komponen yang dideklarasikan Aggregate, Component yang instansnya adalah komponen tersebut, sebagaimana di-resolve oleh katalog. Tidak ada nilai parameter di antaranya, seperti di setiap cakupan: Release tiba tanpa blok parameters-nya, termasuk nilai yang diwarisinya dari basis, dan Aggregate tanpa nilai bawaannya maupun nilai yang diteruskannya ke setiap modul yang diimpornya — lihat Apa yang diberikan kepada plugin linter. Temuannya dilaporkan di bawah file Release.

Ini adalah padanan sisi konvensi dari aggrega validate --release, yang memeriksa kebenaran closure yang sama.

Linter yang dijalankan cakupan ini terikat pada catatan identitas plugin tepercaya di samping Release, sebagaimana build mengikatnya. Sebelum salah satunya berjalan, --release membandingkan lampiran plugins.linter yang dikonfigurasi dengan catatan kepercayaan plugin: plugin tercatat yang tidak lagi dilampirkan konfigurasi — linter atau gerbang — menghentikan lintasan, dan linter yang dibaca dari cache yang artefaknya bukan yang tercatat ditolak alih-alih dijalankan. Linter yang dibaca dari cache juga terikat pada tanda tangannya yang tercatat, saat dimuat: jika entrinya mencatat tanda tangan yang terverifikasi, materi tanda tangan yang disebut fakta tersebut di cache diperiksa kembali, dan lintasan berhenti dengan E0144 jika materi itu hilang atau berbeda, dan dengan E0332 jika materi itu dibuat untuk plugin yang berbeda dari linter yang dibaca — signature yang disalin dari entri lain — apa pun yang dinyatakan persyaratan tanda tangan; jika konfigurasi kepercayaan workspace mewajibkan tanda tangan, entri yang tidak mencatatnya — atau tidak ada entri untuk linter tersebut, termasuk catatan yang dihapus — menghentikan lintasan dengan E0331, dengan pengaturan yang sama yang akan membuat aggrega pull menolaknya karena tidak bertanda tangan. Masing-masing dari ketiganya menyebut cara mengatasinya, aggrega pull --release <release>, yang memverifikasi tanda tangan linter di registry-nya, mencatatnya, dan menyimpan ke cache bundle yang disebutnya, sambil menulis ulang salinan cache yang tidak lagi cocok dengan digest-nya. Linter yang disajikan dari salinan di dalam biner compiler tidak pernah terikat pada persyaratan tersebut. Ini adalah kegagalan lintasan, bukan temuan konvensi, sehingga menghentikan proses di mana sebuah temuan tidak akan menghentikannya. Cakupan seluruh katalog dan entitas tunggal tidak menyebut Release apa pun dan tidak membaca catatan apa pun, sehingga linter yang dibacanya dari cache hanya diperiksa terhadap manifest-nya yang di-cache. Sebelum semua itu, --release menyebutkan setiap penarikan yang tercatat terhadap apa yang menjadi dependensi Release, sebagai baris deprecation: dengan kata-kata yang dicetak aggrega build — baik penanda yang dicatat lockfile terhadap referensi yang di-pin maupun penanda yang dicatat catatan kepercayaan terhadap linter atau gerbang — sehingga lintasan tetap menyatakannya bahkan ketika salah satu penolakan di atas menghentikannya. Penarikan tidak mengubah temuan apa pun maupun kode keluar apa pun, dan catatan kepercayaan yang ada tetapi tidak dapat dibaca menghentikan lintasan alih-alih dianggap sebagai catatan yang tidak mencatat apa pun.

Disiplin entitas: lokal dan gerbang publikasi

Mode path entitas berjalan pada salah satu dari dua tingkat keparahan:

  • Bawaan (lokal). Menjalankan aturan disiplin atas konten entitas lokal dengan tingkat keparahan warn. Tanpa akses registry; pemeriksaan kenaikan versi dilewati. Gunakan saat menulis.
  • --pre-publish (gerbang publikasi). Mengambil versi terbaru entitas yang telah dipublikasikan dan bukan pra-rilis dari registry, menjalankan aturan yang sama dengan tingkat keparahan halt, dan juga mengklasifikasikan perubahan sebagai PATCH / MINOR / MAJOR serta menghentikan proses jika kenaikan metadata.version yang diusulkan lebih kecil daripada yang dibutuhkan perubahan. Gunakan dalam alur publikasi, sebelum aggrega push. --pre-publish hanya berlaku untuk bentuk entitas tunggal.

Kenaikan berlebih selalu diizinkan; kenaikan yang kurang akan menghentikan proses. Publikasi pertama sebuah entitas (tanpa versi sebelumnya di registry) melewati pemeriksaan kenaikan dan menampilkan peringatan yang menyatakan bahwa tidak ada verifikasi yang dilakukan.

Jenis yang diperiksa mode entitas

Mode entitas melakukan lint pada dokumen yang Anda sebutkan, apa pun jenisnya, dan menyerahkannya ke setiap aturan yang membaca satu entitas. Setiap aturan memutuskan sendiri jenis apa yang dijelaskannya, dan aturan yang diberi jenis yang tidak dijelaskannya tidak melaporkan apa pun. Jadi menyebutkan Aggregate, Manifest, Release, atau Workload — jenis yang dilewati oleh proses seluruh katalog dan dicantumkan pada baris not checked: miliknya — juga menjalankan aturan-aturan atas dokumen tersebut, dan hanya aturan yang menjelaskan jenis itu yang dapat melaporkan:

AturanJenis yang dilaporkannya dalam mode entitas
Prefiks anotasiJenis apa pun: aturan ini membaca metadata.annotations apa pun jenis dokumennya.
Ekstensi x-aggrega-* langsungJenis apa pun: aturan ini membaca spec.schema apa pun jenis dokumennya.
Bentuk namaComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, dan ArtifactLibrary.
Kategori cocok dengan direktoriComponent.
Slot rahasia mendeklarasikan sensitiveComponent dan Feature.
Anotasi kredensial metrik cocok dengan providesComponent.
Provides dideklarasikan oleh ComponentRecipe.
Ref dinamis, penimpaan IdSchemaLibrary.
Batas bawaan PluginPlugin.
Perbandingan kenaikan versi (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, dan Plugin (plugin yang terpasang di dalam compiler tidak dibandingkan); perubahan pada jenis lain apa pun diklasifikasikan sebagai MAJOR.
Kredensial koneksi cocok dengan key targetTidak ada: aturan ini membaca seluruh Release, sehingga hanya berjalan dengan --release.

Aggregate, Manifest, Release, dan Workload tidak mendeklarasikan metadata.annotations maupun spec.schema dalam skemanya, sehingga dokumen dari salah satunya yang cocok dengan skema jenisnya tidak memicu temuan apa pun dari dua aturan yang membaca jenis apa pun; kedua aturan itu hanya melaporkannya ketika dokumen itu tetap membawa salah satu key tersebut, yang ditolak oleh skema jenisnya sebagai properti yang tidak terduga. Yang ditambahkan dengan menyebutkan Aggregate adalah perbandingan kenaikan versi di bawah --pre-publish, yang membandingkannya dengan versi yang telah dipublikasikan sebagaimana dijelaskan rubrik di bawah.

Rubrik kenaikan versi

Dalam mode --pre-publish, perubahan dibandingkan dengan versi terpublikasi sebelumnya dan diklasifikasikan:

  • PATCH — perubahan yang hanya menyangkut dokumentasi atau komentar.
  • MINOR — perubahan yang murni menambah (field opsional baru, entri baru).
  • MAJOR — penghapusan, penyempitan tipe, atau field yang sebelumnya opsional menjadi wajib.

Perbandingan dilakukan per jenis entitas: Component, Feature, dan SchemaLibrary dibandingkan dengan memperhatikan field yang memuat skema; MappingLibrary dibandingkan pada tingkat kunci entri (isi entri bersifat buram, sehingga isi yang berubah diperlakukan secara konservatif sebagai MAJOR); Recipe dan FeatureRecipe dibandingkan pada field-field pentingnya. Aggregate dibandingkan pada deklarasi parameternya, komponennya, dan subsistemnya; nilai bawaan sebuah parameter tidak lebih menjangkau perbandingan daripada nilai parameter lainnya (lihat Apa yang diberikan kepada plugin linter), sehingga perubahan yang terbatas pada nilai bawaan — menambahkan, mengubah, atau menghapusnya — bukan bagian darinya, begitu pula perubahan pada kunci di luar kosakata slot parameter. Kenaikan yang kurang menghentikan proses dengan diagnostik yang menyebut kenaikan yang dibutuhkan.

Aturan disiplin

Sebagian besar aturan memiliki pengaturan per workspace di bawah lint.publishing_discipline dalam .aggrega-config.yaml dan override CLI yang sesuai, masing-masing override dengan padanan --no-. Prioritasnya adalah --no-<flag> di atas --<flag> di atas nilai konfigurasi workspace, di setiap cakupan: seluruh katalog, sebuah Release, dan satu entitas. Setiap aturan aktif secara bawaan, dan setiap nilai bawaan berlandaskan pada mekanisme platform atau pada konvensi katalog yang terdokumentasi; pengaturan tersebut adalah opsi penonaktifan bagi workspace yang memiliki alasan untuk melonggarkan salah satunya.

Aturan yang tidak memiliki pengaturan menyatakan hal itu di entrinya di bawah, dan alasannya sama dalam setiap kasus: aturan tersebut melaporkan fakta tentang entitas dan menyerahkan keputusan kepada penulis, sehingga tidak ada penilaian yang perlu dilonggarkan. Rubrik kenaikan versi yang dijelaskan di atas juga tidak memiliki pengaturan — rubrik ini membandingkan konten yang diusulkan dengan versi yang telah dipublikasikan dan melaporkan apa yang dibutuhkan perubahan, yang merupakan sifat perubahan, bukan preferensi workspace.

  • Prefiks anotasi — namespace yang dicadangkan (aggrega.ai/, dan feature.aggrega.ai/ di luar sebuah Feature) dimiliki platform dan ditolak pada kunci lain. Aktif secara bawaan; nonaktifkan dengan allow_aggrega_ai_prefix.
  • Bentuk nama — setiap jenis entitas memiliki konvensi bentuk nama (jumlah segmen untuk jenis cloud-native; PascalCase untuk jenis pustaka). Aktif secara bawaan; nonaktifkan dengan allow_nonstandard_names.
  • Referensi dinamis — entri SchemaLibrary tidak boleh menggunakan $dynamicAnchor / $dynamicRef (ekspansi $ref pada waktu kompilasi oleh platform tidak dapat me-resolve-nya). Aktif secara bawaan; nonaktifkan dengan allow_dynamic_refs.
  • Override id — entri SchemaLibrary tidak boleh mendeklarasikan $id-nya sendiri (platform menurunkan $id kanonis). Aktif secara bawaan; nonaktifkan dengan allow_id_overrides.
  • Kategori sesuai direktori — label component.aggrega.ai/category milik Component harus sesuai dengan segmen direktori pertama di bawah core/, yang diambil dari himpunan kategori tertutup (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Aktif secara bawaan untuk entitas di bawah path core/; nonaktifkan dengan allow_category_mismatches.
  • Ekstensi x-aggrega-* langsung — menulis kunci x-aggrega-* secara langsung dalam skema Component atau Feature tidak dianjurkan dan sebaiknya diganti dengan jalur penulisan kelas satu. Aktif secara bawaan; nonaktifkan dengan allow_direct_x_aggrega_extensions.
  • Provides yang dideklarasikan oleh Component — spec.provides milik Recipe memublikasikan satu kunci per entri, dan Component yang diimplementasikan Recipe tersebut mendeklarasikan, dalam pilar provides dari spec.schema-nya, kunci mana yang diekspos tipe tersebut. Terhadap deklarasi itulah referensi inject from: diperiksa, sehingga kunci yang dipublikasikan Recipe tanpa dideklarasikan Component akan dihasilkan lalu ditolak di tempat konsumen menyambungkannya. Publikasi di luar kontrak yang dideklarasikan diterima pada waktu build, itulah sebabnya temuan ini bersifat anjuran, bukan penolakan. Aktif secara bawaan untuk Recipes; nonaktifkan dengan allow_undeclared_recipe_provides.
  • Batas bawaan Plugin — spec.runtime milik Plugin membawa maxMemoryPages dan timeoutMs, dua batas yang diterapkan host ketika memuat dan menjalankan plugin. Plugin yang tidak mematok keduanya berjalan dengan nilai bawaan platform, yang merupakan hasil yang aman dan bukan galat, sehingga aturan ini melaporkan bahwa nilai bawaan sedang berlaku dan bahwa batas eksplisit tersedia untuk dipatok. Aktif secara bawaan untuk entitas Plugin; aturan ini tidak memiliki pengaturan.
  • Slot rahasia mendeklarasikan sensitivitas — slot lampiran dapat mematok, melalui selektor labelnya, jenis Feature yang mengisinya ke secret, dan dapat secara terpisah mendeklarasikan sensitive: true untuk mencatat bahwa apa pun yang mengisinya menangani materi rahasia. Selektor menyatakan pengisian mana yang dapat diterima; penanda menyatakan penanganannya. Slot yang mematok jenis dan tidak mendeklarasikan penanda membiarkan penanganan tersebut diturunkan ulang dari selektor alih-alih dibaca langsung. Aturan ini membaca setiap slot yang dideklarasikan entitas: slot dari blok lampirannya sendiri di bawah spec.featuresSchema, dan, pada Component, slot yang dideklarasikan setiap socket dependensi di bawah spec.usesSchema.<socket>.featuresSchema untuk koneksi yang disambungkan melaluinya — temuan tentang slot sebuah socket menyebut socket tersebut selain slotnya. Aktif secara bawaan untuk Components dan Features; aturan ini tidak memiliki pengaturan.
  • Kredensial koneksi cocok dengan kunci target (connection-credential-matches-target-key) — server yang memeriksa sebuah kunci menyimpan kunci yang diverifikasinya di sebuah slot pada Component miliknya sendiri, dan pemanggil menyajikan sebuah kunci pada koneksi yang digunakannya untuk mencapai server. Tidak satu pun dari kedua ujung melihat lampiran milik ujung lainnya, sehingga keduanya memegang satu kunci yang sama hanya karena penulisnya menuliskannya di kedua ujung — biasanya dengan membuat kedua lampiran membaca satu parameter yang sama — dan sebuah build tidak pernah membandingkannya. Aturan ini melakukannya, dan ini satu-satunya aturan yang membaca seluruh Release, sehingga aturan ini dijalankan di bawah --release dan tidak di cakupan lain mana pun. Aturan ini menemukan kedua ujung melalui nama yang diberikan katalog standar kepada keduanya: kunci target adalah slot api_key yang dideklarasikan Component-nya di spec.featuresSchema, dan kunci pemanggil adalah slot credential pada koneksi, yang ditulis di uses.<socket>.<alias>.features.credential dalam Aggregate atau pada koneksi yang dihubungkan oleh Release. Untuk setiap koneksi yang targetnya mendeklarasikan api_key dan tidak berlabel managed, aturan ini melaporkan koneksi yang membawa kredensial ke target yang slot kuncinya tidak terisi, slot kunci terisi tanpa kredensial pada koneksi, dan dua ujung yang menamai rahasianya secara berbeda. Yang dibandingkannya adalah lokator setiap ujung — origin yang ditulis sebuah lampiran, di values dalam Aggregate atau di infra dalam Release — sebagaimana ditulis oleh penulisnya, sehingga dua ujung yang membaca satu parameter yang sama dianggap sama dan dua literal dibandingkan berdasarkan teksnya; tidak ada yang di-resolve, dan sebuah temuan menyebutkan komponen, koneksi, target, dan kedua slot tetapi tidak pernah mengutip salah satu lokator, karena teks yang ditulis di sana bisa jadi rahasia itu sendiri. Target yang tidak mendeklarasikan slot api_key tidak menghasilkan apa pun, dan slot yang bukan kunci pemanggil, seperti token pull registry milik server model, tidak pernah dibaca. Target yang Component-nya berlabel component.aggrega.ai/hosting: managed juga tidak dinilai, apa pun isi slot api_key-nya: Component semacam itu mewakili layanan yang dijalankan oleh vendornya, sehingga tidak ada yang dijalankan Release yang memeriksa kunci padanya, dan ketika Component itu mendeklarasikan api_key — misalnya kunci ke API model yang di-hosting, dengan nama yang diberikan produk vendor tersebut — slot itu berisi kunci yang disajikan Release kepada vendor tersebut, bukan kunci yang disajikan para pemanggilnya. Target yang berlabel self-hosted, external, atau mixed, atau yang tidak memiliki label hosting, tetap dinilai. Koneksi pada socket scrape_target — nama yang diberikan katalog standar kepada socket yang digunakan scraper metrik untuk mencapai targetnya — adalah sebuah scrape, dan apakah kredensial sebuah scrape seharusnya berupa kunci pemanggil milik target bergantung pada produk target: sebagian menyajikan metriknya tanpa kredensial, sebagian menempatkannya di balik kunci yang disajikan setiap pemanggil, dan sebagian menerima token tersendiri. Jadi untuk sebuah scrape, aturan ini membaca apa yang dinyatakan Component target dalam anotasi observability.aggrega.ai/metrics-credential-nya: dengan none, scrape tidak dinilai sama sekali; dengan separate-token, kredensialnya tidak pernah dibandingkan dengan api_key milik target, sehingga tidak satu pun dari ketiga temuan dilaporkan padanya; dengan target-key, scrape dinilai seperti koneksi lainnya. Aturan ini hanya membaca ketiga nilai tersebut, sehingga scrape ke target tanpa anotasi itu, atau dengan nilai lain, dinilai seperti koneksi lainnya — dan setiap koneksi pada socket lain, termasuk koneksi ke model, alat, atau datastore, dinilai dengan cara yang sama apa pun isi anotasi target. Aturan ini membaca lampiran yang ditulis pada target dan pada koneksi: lampiran api_key yang mencapai target dari subsistem atau batas justru membuat koneksi tersebut tidak dinilai, lampiran yang ditambahkan oleh anotasi tidak termasuk di dalamnya, sehingga slot kunci yang hanya terisi dengan cara itu dibaca sebagai tidak terisi, ujung yang lampirannya tidak menulis lokator apa pun hanya dibandingkan dari segi terisi atau tidaknya, dan komponen yang disumbangkan oleh modul yang diimpor tidak dibaca. Karena nama slot, label hosting, nama socket scrape, dan anotasi metrik adalah konvensi katalog yang tidak ditandai oleh kata kunci schema mana pun, katalog yang menamai slot secara berbeda tidak menghasilkan apa pun, socket scraping dengan nama berbeda dinilai seperti socket lainnya, dan Component yang menyimpan kunci vendor di slot bernama api_key tanpa label managed dibaca sebagai target yang memeriksa kunci tersebut, karena nama slot, label, dan anotasi adalah semua yang dibaca aturan ini dari Component sebuah target. Aktif secara default; nonaktifkan dengan allow_connection_credential_mismatches.
  • Anotasi kredensial metrik cocok dengan provides (metrics-credential-annotation-matches-provides) — sebuah Component dapat menyatakan dua fakta tentang metriknya. Anotasi observability.aggrega.ai/metrics-credential miliknya menyatakan bagaimana metrik produk diautentikasi: none, metrik disajikan tanpa kredensial; target-key, metrik menerima kunci yang diwajibkan Component dari setiap pemanggil, yaitu kunci yang disimpan slot api_key miliknya; separate-token, metrik menerima token tersendiri. Kunci provides metrics_credential_required, yang dideklarasikan di pilar provides dari spec.schema miliknya, adalah apa yang dipublikasikan oleh masing-masing Recipes miliknya untuk menyatakan apakah metrik sebuah instans memerlukan kredensial — yang dapat bergantung pada cara instans dikonfigurasi, karena metrik di balik kunci pemanggil hanya memerlukannya selama sebuah kunci terlampir, sehingga anotasi tidak dapat menggantikannya. Keduanya menyatakan satu fakta tentang produk, jadi aturan ini mengharuskan keduanya selaras: Component yang dianotasi none yang mendeklarasikan kunci tersebut, dan Component yang dianotasi target-key atau separate-token yang tidak mendeklarasikannya, masing-masing dilaporkan, dan temuannya menyebutkan Component, nilai anotasi, serta kunci yang berlebih atau hilang. Component tanpa anotasi tersebut, atau dengan nilai lain, tidak menghasilkan apa pun. Aturan ini membaca Component sebagaimana ditulis, sehingga Component yang memperluas Component lain — yang schema-nya adalah schema basisnya — tidak menghasilkan apa pun dan basisnya dibaca di tempat ia dideklarasikan, dan pilar provides yang ditulis sebagai referensi, komposisi, atau badan ter-escape yang ditulis sebagai teks bukanlah pilar yang dapat dienumerasinya, sehingga Component tersebut juga tidak menghasilkan apa pun. Aktif secara default untuk Components; aturan ini tidak memiliki pengaturan.

Imutabilitas artefak bukan salah satu dari aturan ini, dan tidak memiliki pengaturan. name:version yang telah dipublikasikan bersifat final: aggrega push membandingkan digest yang sudah dipublikasikan pada tag tersebut dengan digest yang akan dihasilkan oleh konten yang hendak di-push, dan menolak menimpanya dengan konten yang berbeda. Melakukan push ulang konten yang identik byte demi byte tidak mengunggah apa pun dan hanya melampirkan apa yang masih kurang pada publikasi tersebut — tanggal publikasinya, dan tanda tangannya bila push menandatangani. Tidak ada flag maupun pengaturan konfigurasi workspace yang melonggarkan hal ini, karena registry tidak menyediakan jalur penimpaan yang dapat dipilih untuk diaktifkan oleh operator. Konten yang diubah dipublikasikan dengan versi baru; --pre-publish adalah yang memverifikasi kenaikan versi tersebut terhadap release sebelumnya.

Flag override per aturan berlaku per pemanggilan dan sengaja tidak memiliki variabel lingkungan — flag tersebut sudah didukung konfigurasi di .aggrega-config.yaml di bawah lint.publishing_discipline. Model prioritas AGGREGA_* secara umum dijelaskan di environment-variables.md.

Waktu build dan waktu publikasi

Aturan yang tidak menganjurkan x-aggrega-* juga dijalankan selama aggrega build, tempat aturan ini muncul sebagai peringatan; aggrega lint --pre-publish menaikkan temuan yang sama menjadi error. Build lokal membawa saran tersebut; gerbang publikasi menegakkannya.

Saat Anda menulis, di editor Anda

Editor Anda mengajukan dua pertanyaan berbeda tentang sebuah entitas katalog, dan keduanya adalah pertanyaan yang membuka halaman ini. Apakah entitas tersebut benar — apakah dapat di-parse, apakah pilar-pilarnya ter-resolve, apakah dapat di-render? Itulah aggrega validate, dan sesi editor selalu menjawabnya. Apakah entitas tersebut dapat dipublikasikan — apakah namanya mengikuti konvensi, apakah file berada di direktori yang diharapkan kategorinya, apakah prefiks anotasinya benar? Itulah aturan-aturan ini, dan sesi editor hanya menjawabnya bila Anda memintanya.

Fitur ini nonaktif kecuali Anda mengaktifkannya. Aktifkan dengan serve.lint_on_validate di .aggrega-config.yaml milik workspace yang entitasnya ingin Anda beri saran:

serve:
lint_on_validate: true

Tidak ada flag baris perintah untuk ini, dan hal itu disengaja: pertanyaannya menyangkut konten milik sebuah workspace tertentu, dan Anda adalah orang yang menulis workspace tersebut, bukan yang meluncurkan language server — editor Anda yang melakukannya.

Bila fitur ini aktif, setiap entitas yang Anda validasi juga membawa temuan-temuan ini, masing-masing menyebutkan aturan yang menghasilkannya, di samping temuan kebenaran. Tiga hal mengikutinya, dan ketiganya yang membuatnya dapat digunakan saat mengetik:

  • Temuan tetap bersifat saran. Entitas yang melanggar sebuah konvensi tetap tervalidasi, dan Release-nya tetap ter-resolve dan ter-render. Mengaktifkan pengaturan ini menambahkan lapisan saran; pengaturan ini tidak pernah membuat editor Anda menolak bekerja.
  • Anda dapat membedakan keduanya. Setiap masalah yang dipublikasikan menyebutkan lapisan yang memunculkannya, sehingga masalah penamaan dan kegagalan resolusi pada file yang sama terbaca sebagai dua hal berbeda, bukan sebagai satu masalah yang dilaporkan dua kali.
  • Yang Anda ketik adalah yang diperiksa. Aturan membaca buffer, bukan file di disk, sehingga nama yang Anda perbaiki berhenti dilaporkan sebelum Anda menyimpan.

Hanya mode konten lokal yang dijalankan pada lapisan itu: tidak ada registry yang dikonsultasikan, tidak ada yang diambil, tidak ada yang ditulis. Perbandingan --pre-publish dicapai dengan memintanya — editor Anda mengirim permintaan untuknya, sama seperti Anda mengetik --pre-publish di terminal — dan tidak pernah dengan mengubah pengaturan di atas. Pemeriksaan yang dijalankan setiap kali Anda menyentuh dokumen adalah justru tempat registry tidak boleh dijangkau, sehingga mode tersebut tetap menjadi sesuatu yang Anda panggil, bukan sesuatu yang ikut berjalan dengan sendirinya.

Meminta pemeriksaan secara langsung berfungsi apa pun isi pengaturannya, di ketiga cakupan di atas. Jadi workspace yang tidak pernah mengaktifkan lapisan per suntingan tetap dapat meminta editornya untuk menyisir katalog, closure sebuah Release, atau satu entitas — dan mendapatkan temuan yang sama dengan yang dicetak perintah ini. Pengaturan tersebut hanya menentukan apakah pemeriksaan juga dijalankan di tempat Anda tidak memintanya secara eksplisit.

Detail protokol tersebar di dua halaman: arti permintaan tersebut dan kapan mengirimkannya ada di halaman aggrega serve di referensi, sedangkan parameternya dan bentuk jawabannya, kolom demi kolom, ada di referensi format wire.

Memilih linter

Aturan-aturan ini dikirimkan sebagai plugin Wasm linter publikasi standar. Karena aturan berada di dalam plugin dan bukan di kompiler, sebuah perusahaan dapat mengarahkan aggrega lint ke plugin lain untuk menegakkan disiplin katalognya sendiri tanpa mengubah kompiler.

Sebuah workspace dapat melampirkan lebih dari satu linter di bawah plugins.linter, dan setiap lampiran dijalankan: dalam urutan lampiran ditulis, masing-masing pada fungsi entri miliknya sendiri, dengan semua temuannya dilaporkan bersama. Itulah yang memungkinkan sebuah katalog mempertahankan aturan standar dan menambahkan aturannya sendiri di sampingnya alih-alih memilih di antara keduanya. --plugin adalah pengecualiannya — flag ini menjalankan tepat satu artefak dari path sistem file sebagai pengganti lampiran yang dikonfigurasi, yang membuatnya berguna saat mengembangkan sebuah aturan.

Sebuah lampiran menyebut plugin-nya dengan uri:, dan function: menyebut fungsi entri pada plugin tersebut. Entri yang menyebut function: tanpa uri: menyebut fungsi yang tidak berada pada plugin mana pun, sehingga konfigurasi ditolak saat dibaca, dengan E0224, dengan menyebutkan berkas dan posisi entri dalam daftarnya — tambahkan uri dari plugin yang mengekspor fungsi tersebut. Entri yang tidak menyebut keduanya tidak melampirkan apa pun dan dilewati; jika entri itu satu-satunya, linter standar berjalan dengan fungsi entri default-nya sendiri, seperti saat tidak ada plugins.linter sama sekali.

Apa yang diterima plugin linter

Tidak ada nilai parameter yang mencapai plugin linter, di cakupan mana pun. Nilai sebuah parameter dapat berupa kredensial itu sendiri — origin dari sebuah lampiran rahasia dapat berupa template yang membaca parameter yang dipenuhi Release, dan rahasianya kemudian adalah nilai parameter tersebut — dan plugin yang dilampirkan sebuah workspace bisa jadi bukan buatannya sendiri, sehingga setiap dokumen diserahkan dengan nilai parameternya ditahan:

  • Sebuah Aggregate mempertahankan setiap deklarasi parameter, dengan hanya menyimpan kunci-kunci yang digunakan untuk menulis sebuah deklarasi — kosakata slot parameter: tipe, deskripsi, dan batasannya — dan setiap deklarasi yang bersarang di bawah properties, items, dan valuesType miliknya diperlakukan sama. default dari deklarasi ditahan di setiap tingkat, dengan menghapus kuncinya alih-alih mengosongkannya, sehingga plugin tidak dapat mengetahui apakah sebuah deklarasi memberikannya. Kunci di luar kosakata tersebut ditahan beserta apa pun isinya, di setiap tingkat: build tidak memberi makna apa pun pada kunci semacam itu, dan draf yang salah mengeja sebuah kunci dapat membawa rahasia di bawahnya. Entri di bawah parameters yang bukan deklarasi ditahan seluruhnya.
  • Setiap modul yang tercantum di bawah aggregates milik sebuah Aggregate kehilangan blok parameters-nya, yang berisi nilai-nilai yang diteruskan ke modul tersebut.
  • Sebuah Release kehilangan blok parameters-nya, baik nilai-nilainya ditulis secara inline maupun diimpor dengan $import.
  • Dokumen lain apa pun yang membawa blok parameters di bawah spec kehilangan blok tersebut seluruhnya; tidak ada jenis lain yang mendeklarasikannya.

Hal ini berlaku untuk entitas yang disebutkan di baris perintah, untuk versi terpublikasi yang dibandingkan dengannya oleh --pre-publish, untuk setiap entitas yang dilalui oleh pass seluruh katalog dan pass --release, dan untuk dokumen-dokumen yang diterima aturan yang membaca seluruh Release. Template yang membaca sebuah parameter bukanlah nilai dan mempertahankan teksnya, sehingga aturan tetap melihat parameter mana yang dibaca oleh nilai yang ditulis penulis.

Contoh

Menyisir seluruh katalog untuk mencari penyimpangan dari konvensi:

aggrega lint --catalog ./catalog

Menjalankan lint pada sebuah entitas secara lokal saat menulis:

aggrega lint core/datastore/postgres/component.yaml

Menjalankan gerbang publikasi sebelum memublikasikan versi baru:

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

Melonggarkan satu aturan untuk satu kali eksekusi:

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

Lihat juga

  • ./aggrega-validate.md — padanan untuk kebenaran di ketiga cakupan yang sama.
  • ./aggrega-build.md — melakukan validasi sebagai bagian dari kompilasi; memunculkan saran x-aggrega-* dengan tingkat keparahan warn.
  • ./aggrega-push.md — memublikasikan sebuah entitas ke registry; aggrega lint --pre-publish adalah gerbang yang mendahuluinya.
  • ./aggrega-pull.md — me-resolve dan menyematkan dependensi.
  • ./aggrega-serve.md — language server yang melaporkan temuan-temuan ini di editor Anda, dan pengaturan yang mengaktifkan lapisan per suntingan.
  • ../errors/warnings.md — peringatan non-fatal, termasuk temuan lint mode lokal.

Sinopsis

aggrega lint [entity-path] [flags]

Deskripsi

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.

Flag

FlagDefaultDeskripsi
--allow-aggrega-ai-prefixfalsePaksa allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalsePaksa allow_category_mismatches=true
--allow-connection-credential-mismatchesfalsePaksa allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalsePaksa allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalsePaksa allow_dynamic_refs=true untuk pemanggilan ini
--allow-id-overridesfalsePaksa allow_id_overrides=true untuk pemanggilan ini
--allow-nonstandard-namesfalsePaksa allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalsePaksa allow_undeclared_recipe_provides=true
--baseline—Bandingkan pemeriksaan evolusi pra-publikasi dengan versi spesifik yang sudah dipublikasikan ini, alih-alih versi tertinggi yang dipilih otomatis di bawah versi yang sedang dipublikasikan; harus berupa tag SemVer ketat yang ada di registry (memerlukan —pre-publish)
--catalog[]Direktori katalog; dapat diulang. Setiap —catalog <dir> ditambahkan di depan tumpukan pencarian katalog (kecocokan pertama yang menang): catalog_dirs milik workspace, atau, untuk Release yang diberi direktori sendiri oleh konfigurasi workspace di bawah workspace.releases, milik Release tersebut; tumpukan diakhiri dengan direktori bernama catalog di root workspace bila ada. Daftar catalog_dirs yang ditulis kosong tidak membaca katalog lokal sama sekali. Digunakan oleh pass konvensi seluruh katalog dan —release.
--entity—Path ke YAML entitas yang akan di-lint (atau berikan sebagai argumen posisional)
--no-allow-aggrega-ai-prefixfalsePaksa allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalsePaksa allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalsePaksa allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalsePaksa allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalsePaksa allow_dynamic_refs=false untuk pemanggilan ini
--no-allow-id-overridesfalsePaksa allow_id_overrides=false untuk pemanggilan ini
--no-allow-nonstandard-namesfalsePaksa allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalsePaksa allow_undeclared_recipe_provides=false
--output, -otextFormat output: text|json.
--plugin—Path sistem file ke artefak .wasm linter publikasi (menjalankan artefak ini alih-alih lampiran plugins.linter milik workspace)
--pre-publishfalseAmbil versi registry sebelumnya dan verifikasi kenaikan versi yang diusulkan terhadap klasifikasi evolusi schema
--release—Path ke YAML Release untuk memeriksa konvensi di seluruh closure dependensinya yang telah di-resolve (saling eksklusif dengan argumen entitas). Path relatif di-resolve terhadap direktori tempat Anda menjalankan perintah, bukan terhadap root workspace. Bila direktori tersebut tidak berada di workspace mana pun dan tidak ada root yang disebutkan, path absolut menemukan workspace dari folder milik Release itu sendiri