aggrega serve
aggrega serve menjalankan Aggrega sebagai daemon compiler-as-service yang berjalan lama untuk integrasi IDE. Daemon ini berkomunikasi dengan JSON-RPC 2.0 melalui stdin/stdout dan menyimpan state catalog-resolver, parse-cache, dan diagnostik di antara permintaan, sehingga operasi editor mendapat umpan balik dalam waktu kurang dari satu detik alih-alih menanggung biaya penuh pemuatan katalog pada setiap ketukan tombol.
Daemon biasanya dijalankan sebagai subproses oleh ekstensi editor, bukan dijalankan secara manual. Ekstensi VS Code adalah klien referensinya; editor lain dapat berintegrasi dengan menggunakan protokol yang sama.
Protokol
Protokol wire-nya adalah JSON-RPC 2.0 dengan framing Content-Length, di bawah namespace metode aggrega/. Protokol ini dengan sengaja bukan Language Server Protocol — Aggrega memiliki operasi domain (kueri graf IR, sinyal invalidasi cache) yang tidak memiliki padanan dalam LSP. Ekstensi editor menerjemahkan antara permintaan LSP dari editor dan metode aggrega/* ini; nilai posisi, rentang, dan lokasi berbentuk LSP digunakan ulang jika cocok.
Dua metode mempertahankan nama $/ standar protokolnya alih-alih diganti namanya ke dalam namespace aggrega/, karena keduanya adalah urusan transport yang tidak membawa makna Aggrega, dan klien yang sudah menggunakan protokol tersebut menanganinya tanpa tambahan apa pun: $/cancelRequest, yang menghentikan permintaan yang jawabannya tidak lagi diinginkan klien, dan $/progress, yang merupakan cara daemon melaporkan operasi panjang selagi berjalan. Keduanya dijelaskan di bawah.
🔴 Setiap permintaan di bawah membawa workspaceRoot, path absolut workspace yang ditindaknya, dan hal ini tidak diulang per metode. Tiga permintaan tidak membawanya, karena subjeknya bukan workspace: aggrega/initialize, aggrega/getSchema, dan aggrega/scaffoldEntity — kecuali bahwa aggrega/scaffoldEntity yang menulis atau mencantumkan contoh yang dapat dijalankan memang menyebutkan workspace. Lihat Setiap permintaan menyebutkan workspace yang dituju untuk apa yang didapat permintaan yang tidak menyebutkan workspace, dan Mendeklarasikan workspace yang diagnostiknya ingin Anda terima untuk ke mana diagnostik yang dikirim pergi.
Bentuk field demi field dipublikasikan sebagai skema, dan referensi bentuk wire adalah tempat untuk membacanya. Halaman tersebut menyatakan objek parameter setiap metode, setiap hasil, dan setiap payload notifikasi — setiap field dengan tipenya, apakah wajib, dan apa yang dibawanya — bersama tiga properti yang berlaku di seluruh permukaan alih-alih per metode: dua field yang diterima setiap permintaan di luar yang dideklarasikan metodenya sendiri, yaitu workspaceRoot di atas dan workDoneToken dari Memantau operasi yang panjang; bahwa objek params yang membawa kunci yang tidak diterima metodenya akan ditolak, dengan himpunan yang diterima disebutkan dalam penolakan; dan di mana koleksi yang tidak ada sampai di wire sebagai null alih-alih sebagai koleksi kosong. Halaman itu dihasilkan dari skema tersebut, sehingga berubah ketika kontraknya berubah.
Halaman ini memuat protokolnya, halaman itu memuat bentuknya, dan keduanya dimaksudkan untuk dibaca bersama. Di sini: framing, kegunaan setiap metode, seberapa jauh jangkauannya, apa yang ditulisnya, penolakan apa yang dimunculkannya dan mengapa, kode kesalahan, dan apa yang harus dilakukan untuk masing-masing. Di sana: apa yang harus dikirim melalui wire, kunci demi kunci. Jadi, daftar di bawah menyebutkan setiap metode dan menyatakan apa arti memanggilnya, dan daftar field untuk permintaan yang sedang Anda susun ada di referensi di sebelahnya.
Permintaan:
aggrega/initialize— handshake. Menegosiasikan encoding posisi (server lebih memilih UTF-8, lalu UTF-16, lalu UTF-32, dan default-nya UTF-16), menerima workspace yang Anda deklarasikan untuk diagnostik yang dikirim, dan melaporkan root workspace tersebut, lapisan konfigurasi tempat pengaturannya diresolusi, serta penanda yang meresolusinya. Balasannya juga membawaversion, versi biner yang menjawab: nilai yang sama yang dilaporkanaggrega versionuntuk biner tersebut. Nilai ini menggambarkan proses yang sedang berjalan, sehingga setelah file tempat daemon dijalankan diganti — misalnya oleh build ulang ke path yang sama —versiontetap menyebutkan daemon yang berjalan, sedangkan menanyai file tersebut menyebutkan penggantinya; bacalah di sini ketika pertanyaannya adalah dengan versi mana Anda berkomunikasi.workspaceRootbersifat opsional dan mendeklarasikan workspace alih-alih menindaknya — lihat Mendeklarasikan workspace yang diagnostiknya ingin Anda terima. Kirimcapabilities.window.workDoneProgress: trueuntuk menyatakan bahwa klien Anda dapat menangani notifikasi progres;capabilities.workDoneProgresspada balasan menggemakannya, dan field tersebut tidak ada untuk klien yang tidak mendeklarasikan apa pun. Lihat Memantau operasi yang panjang.aggrega/validate— memvalidasi konten file; mengembalikan diagnostik.releaseadalah path relatif terhadap root workspace yang menyebutkan Release yang menjadi acuan validasi — nilai yang sama yang diterimaaggrega/irGraph, dan nilai yang sama yang diterimaaggrega build --releaseketika dijalankan dari root. Parameter ini opsional, dan menentukan seberapa jauh jawabannya menjangkau: sebutkan Release dan pemeriksaan yang memerlukannya dijalankan terhadapnya — entitas katalog diperiksa sebagai entitas tunggal dalam ketentuan Release tersebut, dan dokumen lain apa pun terhadap closure dependensi Release tersebut; hilangkan parameter ini dan jawabannya mencakup apa yang dapat dituntut dari dokumen itu sendiri, serta membawacheckeduntuk menyatakannya. Nilai yang ada tetapi salah bentuk ditolak dalam kedua kasus — path absolut, atau path yang teresolusi di luar root workspace, ditolak alih-alih diresolusi. Lihat Validasi langsung.aggrega/diagnostics— mengembalikan temuan yang disimpan untuk suatu file. Jika validasi file yang sama sedang berjalan ketika permintaan tiba, jawabannya menunggu validasi tersebut dan melaporkan apa yang ditemukannya, sehingga balasannya tidak pernah menjadi pernyataan bersih untuk file yang sedang diperiksa masalahnya oleh daemon. Lihat Meminta diagnostik saat validasi sedang berjalan.aggrega/hover— konten hover untuk entitas pada suatu posisi.releasebersifat opsional dan menjawab dalam ketentuan Release tersebut — lihat Menjawab dalam ketentuan satu Release.aggrega/completion— kandidat pelengkapan pada suatu posisi. Di mana kursor menyebutkan entitas berdasarkan jenisnya —typesebuah komponen,typesebuah lampiran Feature, nilaiextends:,implements:milik Recipe atau FeatureRecipe — kandidatnya adalah nama-nama jenis tersebut yang dideklarasikan oleh dokumen workspace Anda sendiri dan, untuk Component atau Feature, juga nama-nama yang dideklarasikan olehcatalog_dirsyang Anda konfigurasi, masing-masing ditawarkan satu kali dan dalam urutan nama. Karena itu, workspace yang mengambil Components dan Features-nya dari katalog akan ditawari keduanya, bukan hanya apa yang ditulisnya sendiri. Recipes dan FeatureRecipes, yang ditawarkan pada nilai pemetaan Manifest, berasal dari dokumen workspace itu sendiri. Entitas yang hanya ada di cache artefak atau registry tidak ditawarkan: menjawab pelengkapan tidak pernah mengunduh apa pun.releasebersifat opsional dan menjawab dalam ketentuan Release tersebut — lihat Menjawab dalam ketentuan satu Release.aggrega/resolve— meresolusi entitas yang dirujuk pada suatu posisi (go-to-definition).releasebersifat opsional dan menjawab dalam ketentuan Release tersebut — lihat Menjawab dalam ketentuan satu Release.aggrega/findReferences/aggrega/findImplementations. Masing-masing menerimareleaseopsional dan menjawab dalam ketentuan Release tersebut — lihat Menjawab dalam ketentuan satu Release.aggrega/irGraph— graf IR terkompilasi untuk suatu Release, untuk introspeksi editor.releaseadalah path relatif terhadap root workspace, yang menyebutkan Release di dalamnya — nilai yang sama yang diterimaaggrega build --releaseketika dijalankan dari root. Bentuk lain apa pun ditolak dengan kesalahan standar invalid-params yang menyebutkan apa yang harus dikirim sebagai gantinya: path absolut, path yang teresolusi di luar root workspace — baik keluar sebagaimana tertulis maupun melalui link, ke file atau ke direktori di sepanjang jalan — dan nilai kosong semuanya ditolak alih-alih diresolusi, sehingga permintaan tidak pernah melaporkan file yang tidak dimiliki workspace. Release yang disebutkan oleh konfigurasi workspace Anda, sebagaibuild.authoring_releaseatau sebagai kunciworkspace.releases, adalah milik workspace di mana pun file-nya berada, sehingga link di dalam workspace yang mengarah kepadanya diterima, sebagaimanaaggrega/releaseCandidatesmencantumkannya. Direktori katalog yang dibaca Release dan tidak dapat ditelusuri — misalnya direktori yang ada tetapi tidak dapat dibaca — ditolak sebagaimanaaggrega inspectmenolaknya, sebelum hal lain dibaca: kesalahannya adalah1004entity-not-resolvable, pesannya adalah laporan yang dicetak baris perintah untuk direktori tersebut, dalam satu baris ([CATALOG_ERROR] <directory>: catalog load: …), dan tidak ada graf yang digambar atas direktori yang tersisa. Direktori yang dicantumkan konfigurasi workspace tetapi bukan direktori — misalnya tidak ada apa pun di sana — ditolak dengan cara yang sama dan pada saat yang sama,1004entity-not-resolvable, dengan pesan berupa penolakan yang diberikan setiap perintah kepadanya, yang menyebutkan entri tersebut, file konfigurasi dan baris yang mencantumkannya, serta pengaturannya (Dari mana entitas lokal dibaca). Direktori katalog yang berisi link yang keluar dari direktori tempat pembacaannya harus tetap berada — dokumen atau direktori yang di-link dari tempat lain, di bawah direktori katalog di dalam workspace atau di bawah direktori yang disebutkan konfigurasi di luarnya — ditolak dengan cara yang sama dan pada saat yang sama, dengan1004dan kalimat kondisi itu sendiri yang menyebutkan link tersebut dan ke mana arahnya: tidak ada yang dibaca melalui link seperti itu, dan graf yang digambar tanpanya dapat meresolusi entitas lain dengan nama yang sama sebagai gantinya. Begitu pula link yang keluar di antara dokumen di samping Release, di mana Release menyebutkan Aggregate atau Manifest-nya berdasarkan identitas. File yang disebutkan melalui path oleh Release, Manifest-nya, atau Release yang diperluasnya —aggregate:,manifest:,extends:, atau$import:pada parameters — dan yang keluar dari workspace, sebagaimana tertulis atau melalui link, ditolak dengan kalimat kondisi itu sendiri (fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Referensi ke file lain keluar dari direktori tempat ia harus tetap berada)”), dengan data kesalahan yang menempatkannya pada kunci di Release yang mengarah ke file tersebut, dan tidak ada yang dibaca dari file itu; Release yang disebutkan konfigurasi di luar workspace dibatasi dengan cara yang sama pada direktori yang memuatnya, sehingga path yang ditulisnya, atau yang ditulis Release yang dituju rantainya, dan yang keluar dari direktori itu juga ditolak. Perhatikan bahwaaggrega/releaseCandidatesmenjawab dengan path absolut, sehingga klien yang mengisi satu permukaan dari yang lain mengonversi di antara keduanya. Bahwa parameter ini menolak ejaan yang diterima parameter per dokumenfiledanurimemang disengaja, dan Ejaan mana yang diterima parameter yang Anda kirim menjelaskan apa yang menentukannya. Graf ini menahan setiap nilai yang dideklarasikan sensitif oleh penulis, persis seperti--ir-graphmenahannya di baris perintah: masing-masing diganti dengan penanda yang dijelaskanaggrega-inspectdi “Keluaran yang dapat dibaca mesin”, dan semua hal lainnya dibawa sebagaimana dicatat compiler.unredacted: truememinta nilai-nilai tersebut dalam bentuk terbuka — ejaan protokol untuk--unredactedpada baris perintah, dan satu-satunya cara memintanya; jika tidak ada ataufalse, jawabannya menahannya. Apa pun yang dijangkau jawaban kemudian membawa nilai-nilai tersebut dalam bentuk terbuka, sehingga klien hanya memintanya jika orang yang menggunakannya telah memintanya.aggrega/build— mengompilasi Release dan menulis artefaknya ke direktori keluaran workspace, direktori yang sama yang ditulisiaggrega buildketika dijalankan dari root workspace.releasemembawa kontrak yang sama seperti di atas. Metode ini merender dengan setiap gerbang aktif, sehingga divergensi yang akan menghentikan build baris perintah juga menghentikannya di sini. Direktori katalog yang dibaca Release dan tidak dapat ditelusuri — misalnya direktori yang ada tetapi tidak dapat dibaca — ditolak sebagaimanaaggrega buildmenolaknya, sebelum apa pun ditulis: tidak ada artefak, dan tidak ada lockfile jikaautoPulldisetel. Demikian pula direktori yang dicantumkan konfigurasi workspace tetapi bukan merupakan direktori, dengan kata-kata yang digunakanaggrega builduntuk menolaknya (Dari mana entitas lokal dibaca). Penolakannya sama dengan yang diberikanaggrega/irGraphuntuk direktori yang sama,1004entity-not-resolvable dengan laporan baris perintah dalam satu baris, dan link yang keluar dari pembacaan direktori katalog, atau dari dokumen di samping Release, ditolak sebagaimanaaggrega/irGraphmenolaknya, tanpa ada yang ditulis. Jawabannya menyebutkanoutputDirectorytempat ia menulis danfilesyang ditulisnya, masing-masing relatif terhadap direktori tersebut dan diurutkan, bersamanoticesapa pun yang dimunculkan proses; temuan yang membawa posisi dokumen dikirim melaluiaggrega/publishDiagnosticssebagai gantinya. Release yang menolak saat dirender dijawab dengan penolakan tersebut dalam kata-kata compiler, termasuk setiap penyebabnya, dan penolakan itu dipublikasikan di tempat yang ditunjuknya — lihat Penolakan yang muncul saat rendering. JikaautoPulldisetel, jawabannya juga membawadependencyResolution, laporan yang sama dengan jawabanaggrega/resolveDependencies, sehingga klien yang mengisi dependensi sebagai bagian dari build dapat membaca apa yang di-pin tanpa bertanya lagi — dan dari mana resolusi build ini mengambil setiap referensi, fakta tentang proses tersebut yang tidak dicatat lockfile. Setiap pemberitahuan membawaclassdari permukaan yang memunculkannya —deprecation,catalog,catalog-lint,extends,release-composition, ataudependency-resolutionuntuk baris yang dimunculkan resolusi dependensi di bawah — danclasskosong jika daemon tidak memiliki nama untuk permukaan tersebut, yang ditampilkan klien sebagaitextapa adanya alih-alih menebak padanan terdekat. File yang ditemukan penulisan di direktori keluaran, atau di direktori di bawahnya yang ditulisi file atau dilewatinya, yang tidak ditulis oleh build ini dibiarkan di tempatnya dan disebutkan dalam satu pemberitahuan setelah pemberitahuan milik proses itu sendiri, di bawahclasskosong, dalam kalimat yang digunakanaggrega builduntuk mencetak peringatannya — lihat File yang tidak ditulis oleh build;filestidak pernah menyebutkannya.outputParentmenyatakan ke mana di dalam workspace artefak ditempatkan, dan namanya adalah keseluruhan maknanya: ini adalah direktori tempat direktori keluaran dibuat di dalamnya, sehingga mengirimdocsakan menulis artefak kedocs/distalih-alih kedocsitu sendiri — persis seperti yang dihasilkan build yang dijalankan didocsdari terminal. Hilangkan parameter ini dan build menulis ke tempat yang ditulisi build yang dijalankan di root workspace. Parameter ini dibaca berbeda darioutputDiryang diterima permintaan penulisan lain di sini, dan memang disengaja: permintaan-permintaan itu menyebutkan direktori yang menjadi tujuan penulisan, sedangkan parameter ini menyebutkan induk direktori tersebut, dan keduanya memiliki nama yang berbeda karena keduanya adalah hal yang berbeda. Parameter ini tetap merupakan tujuan di dalam workspace, sehingga nilai absolut, nilai yang naik keluar dari root, dan nilai yang keluar darinya melalui link — direktori yang di-link di luar root, atau direktori yang belum dibuat di bawah direktori semacam itu — ditolak alih-alih diresolusi. Direktori keluaran yang dibuat di dalamnya, dan setiap file yang ditulis build di sana, juga dibatasi pada workspace: jika salah satunya keluar dari workspace melalui link, build ditolak dengan1004dan kalimat kondisi itu sendiri yang menyebutkan link tersebut dan ke mana arahnya, dan tidak ada yang dikosongkan atau ditulis.autoPullmeresolusi dependensi Release sebelum merender, resolusi yang sama yang dilakukanaggrega/resolveDependencies, dan nonaktif kecuali permintaan memintanya, sesuai dengan default baris perintah itu sendiri; tanpanya, Release yang tidak memiliki lockfile ditolak dengan kesalahan lockfile-tidak-ada yang menyebutkan apa yang harus dijalankan. DenganautoPulldisetel, permintaan ini menjangkau registry dan menulis lockfile — lihat Menjangkau registry, dan menulis. Permintaan yang meresolusi terlebih dahulu tetap merender Release sekali: mencari tahu referensi jarak jauh mana yang dikonsumsi Release itu sendiri adalah render, sehingga resolusi sudah merender apa yang menjadi pokok build, dan build dijawab dari render tersebut alih-alih mengulanginya.policyInputmenyebutkan direktori di dalam workspace, relatif terhadap root-nya, tempat build juga menulis payload yang diserahkan setiap peran tata kelola kepada plugin yang dilampirkan di sana — file yang ditulisaggrega build --policy-input, dengan nama yang sama — baik build selesai maupun berhenti;noticesjawaban kemudian menyatakan berapa file yang ditulis dan menyebutkan setiap peran yang tidak mendapat file apa pun, di bawahclasskosong. Pada permintaan yang gagal, file yang sudah ditulis tetap ada di disk dan catatan tersebut tidak ada dalam balasan: amplop kesalahan hanya membawa penolakan. Parameter ini adalah tujuan, sehingga nilai absolut atau nilai yang naik keluar dari workspace ditolak sebelum apa pun dijalankan.aggrega/buildPreview— melaporkan apa yang akan ditulis oleh build Release, tanpa menulis apa pun.releasemembawa kontrak yang sama seperti di atas. Metode ini menjalankan komputasi yang sama denganaggrega/build, di bawah gerbang yang sama, sehingga Release akan ditolak oleh keduanya atau dilaporkan oleh keduanya — itulah yang membuat pilihan di antara keduanya menjadi pilihan tentang keluaran, bukan tentang ketegasan. Direktori katalog yang dibaca Release dan tidak dapat ditelusuri, atau yang berisi link yang keluar dari direktori tempat pembacaannya harus tetap berada, ditolak dengan cara yang sama, sebelum apa pun dirender, demikian pula direktori yang dicantumkan konfigurasi workspace tetapi bukan merupakan direktori, seperti padaaggrega/build. Jawabannya membawafiles, nama-nama relatif-keluaran yang akan dihasilkan build, diurutkan, bersamanoticesapa pun; tidak adaoutputDirectory, karena tidak ada yang ditulis di mana pun untuk disebutkan. Release yang menolak saat dirender dijawab dan dipublikasikan persis sepertiaggrega/buildmenjawab dan memublikasikannya. Metode ini menolakautoPulldengan kesalahan invalid-params yang menyebutkan apa yang harus dikirim sebagai gantinya: mengisi dependensi menulis lockfile, dan permintaan ini tidak menulis lockfile. Metode ini tidak menjangkau registry mana pun.policyInputadalah satu-satunya penulisan yang dilakukannya, dan hanya jika dikirim: metode ini menulis payload tata kelola ke direktori tersebut persis sepertiaggrega/build— file yang ditulisaggrega build --dry-run --policy-input— tanpa menyentuh direktori keluaran dan lockfile, dengan catatan yang sama dinoticesdan batasan yang sama: pada permintaan yang gagal, file yang sudah ditulis tetap ada di disk dan catatan tersebut tidak ada dalam balasan.aggrega/resolveDependencies— meresolusi dependensi katalog dan sumber Release ke dalam cache, mem-pin input eksternal yang dikonsumsi rendernya ke dalam penyimpanan beralamat konten, dan menulis lockfile-nya.releaseadalah path relatif terhadap root workspace, nilai yang sama yang diterimaaggrega/irGraph, dan ditolak dalam bentuk yang sama.upgrademembuang pin yang tercatat dan meresolusi ulang, menaikkan setiap dependensi ke versi tertinggi yang tersedia;targetsmempersempitnya ke referensi entitas yang disebutkannya, mempertahankan setiap pin lainnya.verifymemeriksa resolusi yang tercatat terhadap resolusi yang akan dilakukan permintaan ini tanpanya, dengan menghormati pin yang tercatat dengan cara yang sama, dan tidak menulis lockfile, catatan kepercayaan plugin, maupunentity.lock— cache dibaca dan diisi sebagaimana tanpanya — dan menjawabverified: truesertatoolchainyang dicatat lockfile.verifyditolak sebagai parameter tidak valid jika disertaiupgrade, disertaitargets, dan disertaipinSourcesapa pun nilainya, sebelum apa pun diresolusi atau progres apa pun dilaporkan: upgrade membuang pin yang justru harus dihormati verify, target yang disebutkan hanya diresolusi ulang oleh upgrade, danpinSourcesmenentukan apakah resolusi mencatat pin yang kurang darientity.lockatau menolak karenanya, dan tidak satu pun dari keduanya dilakukan oleh perbandingan yang tidak menulisentity.lock. Baris perintah dan alat asisten menolak pasangan yang sama. Jawabannya menyebutkanlockfileyang ditulisnya atau yang dibandingkannya dan setiap referensi yang di-pin-nya, dalamentities,libraries, danplugins, setiap entri membawaversionhasil resolusinya dansource-nya — dari mana proses ini mengambil referensi tersebut, dalam kata yang dicetakaggrega pull --detailuntuk resolusi yang sama:fetched-fresh,cache-reuse,local,in-binary, atauexternal— bersamasourceArtifacts,trustedPlugins,externalInputs— berapa banyak input eksternal yang di-pin lockfile setelah proses selesai, menghitung baik yang dibawa dari sebelumnya maupun yang ditemukan proses ini — dannoticesapa pun yang dimunculkan resolusi. 🔴 Jawaban yang berhasil tidak dengan sendirinya berarti pin input eksternal sudah lengkap. Jika proses telah mem-pin setiap dependensi tetapi tidak dapat menyelesaikan penentuan input eksternal mana yang dikonsumsi Release, proses tersebut menjawab denganincompleteExternalInputsyang menyatakan apa yang menghentikan penemuan, dan tetap menjawab sebagai keberhasilan — pin dependensi sudah lengkap dan ada di disk, sehingga melaporkan seluruh permintaan sebagai gagal akan menyuruh Anda mengulang pekerjaan yang sudah benar. Baca field tersebut sebelum memperlakukan lockfile sebagai sepenuhnya ter-pin: field ini tidak ada ketika tidak ada yang tersisa belum ditemukan, sehingga keberadaannya adalah sinyalnya. Tidak ada parameter direktori katalog: tumpukan pencarian adalah yang dikonfigurasi workspace. Ini adalah satu-satunya permintaan pin dalam sesi untuk suatu Release, dan di sinilah input eksternal juga di-pin — URL mana yang dikonsumsi render bergantung pada apa yang direndernya, sehingga permintaan ini merender Release untuk mengetahuinya, dan permintaan build kemudian dilayani dari apa yang dicatatnya. Recipe atau FeatureRecipe yang dibangun Release danentity.lock-nya tidak mencatat pin untuk input yang dibaca entitas tersebut membuat permintaan ditolak, dengan menyebutkanaggrega pindan setiap input yang tidak tercatat;pinSources: truemenjalankan langkah pin tersebut atas entitas-entitas itu sebagai gantinya, menulisentity.lockdi samping masing-masing — langkah yang sama yang dijalankanaggrega/pin, menulis byte yang sama. Jika tidak ada,pinSourcesmengikutipin_sources_at_pullmilik workspace; jika dikirim, nilainya menimpa pengaturan tersebut ke dua arah, sehinggafalsemenolak bahkan di workspace yang dikonfigurasi untuk mem-pin. Permintaan ini menjangkau registry dan menulis — lihat Menjangkau registry, dan menulis.aggrega/pin— mencatat, dalamentity.lockdi samping Recipe atau FeatureRecipe, pin konten untuk setiap input yang dibaca entitas dari luar dokumennya sendiri: sumber jarak jauh yang koordinatnya ditulis lengkap, file yang diimpor oleh entri artifacts, dan setiap file yang disumbangkan sumber lokal ke apa yang dibawa publikasi entitas tersebut. Ini adalah langkah yang sama yang dijalankanaggrega pindi terminal, dan menulis byte yang sama.entitywajib dan merupakan path relatif terhadap root workspace yang menyebutkan dokumen entitas, ditolak dalam tiga bentuk yang sama sepertirelease. Tidak ada Release yang disebutkan: sumber jarak jauh yang koordinatnya tidak membawa template menyebutkan satu artefak untuk setiap Release yang menggunakan entitas tersebut, sehingga tidak ada yang disediakan Release yang diperlukan untuk mem-pin-nya, sedangkan sumber jarak jauh yang koordinatnya berasal dari template di-pin per Release olehaggrega/resolveDependencies; sumber lokal yang ditulis sebagai template menyumbangkan setiap file di direktori entitas, dan masing-masing di-pin di sini.dryRunmeresolusi input dan menjawab dengan lock yang akan ditulis langkah tersebut sebagaicontent, tanpa menulis apa pun di samping entitas; cache konten tetap terisi. Jawabannya membawaentity,kind,name, danpinnable— false untuk jenis yang tidak membaca apa pun yang dicatat lock, dan dalam hal itu tidak ada yang disentuh di samping entitas dan setiap field lainnya tidak ada — dan jika tidak,lockyang ditulisnya,changed(false ketika lock sudah mencatat setiap pin dan dibiarkan identik byte demi byte),removedjika entitas kini tidak membaca apa pun yang dicatat lock dan lock-nya dihapus, sertapins, satu entri per kelas pin dengan jumlah yang dimuat lock. File entitas itu sendiri tidak pernah ditulis. Ini menulis di samping entitas, di dalam workspace, dan menjangkau host yang disebutkan sumber entitas — lihat Menjangkau registry, dan menulis.aggrega/cacheStatus— apa yang dimuat cache di disk: satu entri per elemen yang di-cache dengan ukurannya dan, jika ada, digest kontennya, dikelompokkan per kelas. Hanya menerima workspace. Setiap kelas membawareach—workspaceuntuk cache artefak di bawah direktori cache milik workspace ini,machineuntuk penyimpanan modul terkompilasi, deskripsi plugin, dan bundel dokumentasi yang digunakan bersama oleh setiap proyek di mesin — danscopemenyebutkan kelas tingkat mesin secara langsung. Metode ini tidak menulis apa pun. Lihat Menjangkau registry, dan menulis untuk alasan jangkauan dicantumkan pada jawaban yang tidak mengubah apa pun.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— mengambil kembali ruang dari konten yang di-cache. Prune menghapus apa yang tidak dirujuk lockfile workspace mana pun; eviction memangkas penyimpanan modul terkompilasi hinggamaxSize, jumlah byte yang ditulis sebagaimana baris perintah menulisnya (5GiB,512MiB, atau jumlah byte); clear mengosongkan setiap cache yang dituju sesi ini. Setiap jawaban menyebutkan apa yang dihapusnya, dengan setiap penghapusan membawareachdari kelas asalnya, dan masing-masing membawascope. Setiap jawaban juga menyebutkan apa yang dibiarkan di tempatnya karena proses lain sedang membukanya — Windows menolak menghapus file yang terbuka, dan operasi berlanjut dengan sisanya alih-alih gagal: prune atau eviction mencantumkan entri-entri tersebut dalamheldOpen, dan clear menghitung, untuk setiap cache yang dikosongkannya, file yang ditinggalkannya dalamheldOpenFilesdan ukurannya dalamheldOpenBytes. Di sistem lain daftarnya kosong dan hitungannya nol, dan proses berikutnya dapat mengambil kembali apa yang tertinggal. Metode-metode ini menjangkau melampaui workspace — lihat Menjangkau registry, dan menulis.aggrega/registryList— registry yang dikonfigurasi untuk dijangkau workspace ini: untuk setiap entri, host-nya, alias opsional, apakah merupakan default, postur kepercayaannya sebagai field terpisah, dan apakah kredensial untuk host tersebut ada. Hanya menerima workspace. Metode ini tidak menghubungi registry mana pun. Status kredensial hanya melaporkan keberadaannya — tidak pernah kredensialnya, tidak pernah bentuknya, dan tidak pernah apakah registry akan menerimanya, yang memerlukan perjalanan pulang-pergi jaringan yang tidak dilakukan oleh sebuah daftar — dan dibaca dari penyimpanan kredensial tingkat mesin, yang dinyatakan secara eksplisit olehcredentialStateIsMachineWide.aggrega/search— mencari di indeks lokal registry yang dikonfigurasi. Setiap field mempersempit pencarian dan semuanya opsional, sehingga objek params kosong meminta semua yang dimuat indeks. Metode ini tidak menghubungi jaringan: indeksnya adalah snapshot offline yang ditulis di bawah direktori cache milik workspace ini. Versi yang dilaporkan adalah versi yang akan diambil resolusi — versi yang penarikannya membawa tanda tangan yang dipercaya workspace ini dikecualikan dan disebutkan dalamretracted— dan jawabannya membawa asal-usulnya sendiri:indexesmemberikan usia snapshot setiap registry yang dicari,stalemenandai yang layak diperbarui, danmissingIndexHostsmenyebutkan registry terkonfigurasi yang tidak memiliki indeks lokal, sehingga isinya tidak ada dalam jawaban.aggrega/registryAdd— mendaftarkan registry dan kebijakan kepercayaan tanda tangannya.hostwajib; semua hal lainnya membentuk kebijakan atau target penulisan.keyPathdantrustedRootmenyebutkan file: nilai absolut — misalnya file yang dipilih dalam dialog — dibaca di tempat yang ditunjuknya; nilai relatif menyebutkan file di dalam workspace, diresolusi terhadap root workspace alih-alih terhadap direktori tempat daemon berjalan, dan nilai yang naik keluar dari root atau keluar darinya melalui link ditolak dengan kesalahan invalid-params sebelum apa pun dibaca atau ditulis.trustedRootrelatif dicatat sebagai file yang disebutkannya di workspace, sehingga entri tersebut menyebutkan file itu di direktori mana pun verifikasi berikutnya dijalankan.fetchTrustdefault-nya true ketika kuncinya tidak ada, sesuai dengan baris perintah, dan mengambil kebijakan yang diiklankan registry itu sendiri pada kontak pertama;trustdalam jawaban menyatakan apa yang terjadi — kebijakan telah di-pin, registry tidak mengiklankan kebijakan apa pun (dan, denganunreachabledi sampingnya, sama sekali tidak dapat dijangkau), baseline bawaan hub resmi di-pin sebagai gantinya, atau tidak ada pengambilan yang dicoba. Pendaftaran ini sama dengan yang dilakukanaggrega registry add: pengambilan yang sama di bawah postur jaringan yang sama, menulis entri yang sama byte demi byte. Di workspace offline, pengambilan ditolak sebelum koneksi apa pun dibuat, sehingga registry tidak pernah ditanya, dan registry selain hub resmi ditolak kecuali permintaan menyediakanidentitiesataukeyPath, yang mendaftarkan persis apa yang dikirim dan tidak melakukan pengambilan: pesan kesalahannya adalah kalimat yang dicetak baris perintah, didahului kode singkat kondisiE0310— sebagaimana pesan setiap penolakan permintaan ini yang menyebutkan suatu kondisi diawali dengan kode singkatnya — dan tidak ada yang ditulis. Hub resmi tetap ditulis dengan baseline bawaannya, dijawab dengantrust.baselinetrue dantrust.reasonyang menyatakan bahwa hub tidak ditanya tentang kebijakan kepercayaannya karena workspace sedang offline — alasan yang mengawali pemberitahuan baris perintah — dan tanpanotAdvertised, karena hub tidak pernah ditanya. Ini menulis konfigurasi global secara default — lihat Menjangkau registry, dan menulis.aggrega/registryRemove— menghapus entri registry, yang dirujuk melalui host atau alias ramah. Token yang tidak cocok dengan apa pun ditolak alih-alih dijawab sebagai keberhasilan atas konfigurasi yang tidak berubah. Ini menulis konfigurasi global secara default — lihat Menjangkau registry, dan menulis.aggrega/logout— menghapus kredensial yang tersimpan untuk suatu registry, penghapusan yang sama yang dilakukanaggrega logoutdi terminal.registrywajib dan menyebutkan host registry sebagaimana Anda mengautentikasi ke sana; tidak ada alias ramah yang perlu diresolusi di sini, karena penyimpanan kredensial diindeks berdasarkan alamat tempat klien mengautentikasi, bukan berdasarkan apa pun yang disebutkan konfigurasi, sehingga host yang tidak dikonfigurasi workspace mana pun tetap dapat memiliki kredensial yang dapat Anda hapus. Host yang tidak memiliki kredensial di penyimpanan dihapus dengan berhasil dan tidak ada yang ditulis ulang — pemanggil yang meminta agar suatu host tidak memiliki kredensial telah mendapatkan apa yang dimintanya, sehingga itu adalah jawaban, bukan kesalahan, dan begitu pula yang dilakukan perintah terminal. Jawabannya membawaregistrydanscope. Jawaban tersebut tidak membawa bagian apa pun dari kredensial dalam bentuk apa pun, dan tidak melaporkan apa pun tentang apakah sebelumnya ada kredensial: memastikannya memerlukan pembacaan kedua atas penyimpanan yang tidak diminta siapa pun, jadi tanyakanaggrega/registryListketika keberadaan menjadi pertanyaannya. Metode ini tidak menghubungi registry mana pun — menghapus kredensial tersimpan adalah tindakan lokal, dan apakah registry itu akan menerima kredensial tersebut tidak ditanyakan. Ini mengubah penyimpanan kredensial yang digunakan bersama oleh setiap proyek di mesin — lihat Menjangkau registry, dan menulis.aggrega/registryUpdate— memperbarui indeks lokal yang dapat dicari yang dibacaaggrega/search.registryyang tidak ada memperbarui setiap registry yang dikonfigurasi; menyebutkan salah satu hanya memperbarui registry tersebut.upgrademembaca ulang setiap repositori secara penuh, tanpa membandingkan apa pun dengan indeks yang sudah ditulis; pembaruan tanpanya pun sudah membaca ulang apa saja yang berubah. Jawabannya membawa jumlah record setiap host, repositori yang tidak dapat dibacanya — masing-masing denganreasonyang diawali jenis kegagalan terakhir pembacaan tersebut jika ada —readsRetried, berapa banyak pembacaannya yang ditolak atau diputus registry di tengah jalan dan diminta lagi, masing-masing dihitung sekali dan termasuk nol, penanda deprecation yang ditemuinya,errordari host yang gagal — denganunreachabledi sampingnya jika registry itu tidak dapat dijangkau — danindexRoot, direktori di bawah cache milik workspace ini tempat indeks ditulis. Ini menjangkau setiap registry yang diperbaruinya — lihat Menjangkau registry, dan menulis.aggrega/publishEntity— membundel entitas katalog dan memublikasikannya ke registri.entityadalah path relatif terhadap root workspace yang menamai dokumen yang akan dipublikasikan, ditolak dalam tiga bentuk yang sama sepertirelease— tidak ada, absolut, atau ter-resolve di luar root. Entitas Plugin juga memerlukanplugin, jenis path yang sama, yang menamai executable yang dipublikasikan di dalam manifest milik entitas itu sendiri.registryadalah tujuan dan secara default adalah registri yang dikonfigurasi di workspace.dryRunmenghitung bundel dan digest yang akan dihasilkan oleh publikasinya, dan tidak menghubungi registri mana pun. Menghilangkansignmengikuti kebijakan registri tujuan itu sendiri, yang merupakan perilaku command line ketika flag-nya tidak ada, sedangkan mengirimkannya adalah pilihan pemanggil — dan keduanya tidak melonggarkan penolakan, karena kebijakan registri atau workspace yang mewajibkan tanda tangan menolak publikasi tanpa tanda tangan apa pun isi field tersebut.pinSources: truemenjalankan langkah pin milik penulis entitas pada entitas sebelum dibundel, sehinggaentity.lockyang ditulis langkah tersebut di sampingnya menjadi bagian dari apa yang dipublikasikan — langkah yang sama yang dijalankanaggrega/pin. Langkah ini berjalan sebelum penolakan apa pun yang menilai isi entitas — kebijakan penandatanganan, penjaga imutabilitas — sehingga publikasi yang ditolak di sana tetap meninggalkan lock yang sudah ditulis; penolakan yang menyangkut permintaan itu sendiri, seperti workspace offline atau tidak adanya tujuan, datang lebih dulu dan tidak mem-pin apa pun, demikian pula penolakan terhadap entitas yang berbagi direktori dengan entitas lain, yang tidak boleh ditulisi lock oleh langkah tersebut. Jika tidak ada, field ini mengikutipin_sources_at_pushmilik workspace; jika dikirim, field ini menimpa pengaturan tersebut ke kedua arah. Di bawahdryRun, langkah tersebut melaporkan lock yang akan ditulisnya dan tidak menulis apa pun. Publikasi yang tidak menjalankan langkah tersebut menolak Recipe atau FeatureRecipe yangentity.lock-nya tidak mencatat pin untuk input yang dibacanya, atau pin yang tidak lagi cocok dengan input tersebut, sebelum apa pun dibundel — juga di bawahdryRun— dengan menyebutaggrega pin,pinSources, danpin_sources_at_push; ini adalah penolakan yang dimunculkanaggrega/resolveDependenciesatas lock yang sama. Respons memuatreference,tag,kind,mediaType, pasangansize,digestyang dipublikasikan — di bawahdryRun, digest yang akan dihasilkan publikasi tersebut, yaitu yang dicetak olehaggrega push --dry-run—signed,alreadyPublished,dryRun, danreach;pin— respons yang sama dengan yang diberikanaggrega/pin— jika langkah tersebut dijalankan; danwholeDirectorySourcejika sumber lokal entitas ditulis sebagai template, dengan menamai sumber tersebut sebagaimana ditulis. Sumber seperti itu baru memilih direktorinya setelah sebuah Release mengisi template tersebut, sehingga publikasi membawa setiap file di direktori entitas, bukan hanya file yang dinamai entitas, dan field ini adalah cara pemanggil mengetahui bahwa hal itu terjadi — juga pada dry run. Respons juga memuatwindowsUnusableEntriesjika arsip yang dibawa publikasi berisi entri yang tidak dapat disimpan Windows sebagaimana ditulis — path dengan bagian yang dinamai sesuai perangkat, sepertiCON,AUX, atauNUL, dalam huruf besar atau kecil apa pun dan dengan ekstensi apa pun yang mengikutinya, atau bagian yang diakhiri titik atau spasi — dengan menamai masing-masing, nama file dokumen entitas itu sendiri terlebih dahulu, lalu file-file yang dibawanya; field ini tidak ada jika tidak ada entri seperti itu, termasuk untuk entitas yang dipublikasikan hanya sebagai dokumennya.aggregayang berjalan di Windows menolak membongkar entri seperti itu, sehingga workspace Windows tidak dapat menggunakan versi tersebut. Inilah entri yang diperingatkan olehaggrega push, dan permintaan yang meminta laporan membaca baris peringatan yang sama di antara progres publikasi; keduanya tidak menolak apa pun, sehingga publikasi berlanjut atau ditolak persis seperti yang akan terjadi tanpa entri tersebut, juga di bawahdryRun. Ini menulis ke registri dan menjangkau ke luar mesin ini, dan dengan langkah pin juga menulis di samping entitas — lihat Menjangkau registri, dan menulis.aggrega/publishArtifact— memublikasikan artefak data mandiri, seperti bundel dokumentasi.fileadalah path relatif terhadap root workspace, dengan kontrak yang sama, dan byte-nya dipublikasikan apa adanya: tidak ada amplop entitas yang di-parse dan tidak ada dispatch berdasarkan kind.namedantagmenamai sebagai apa artefak itu dipublikasikan, dan keduanya wajib.mediaTypesecara default adalah tipe bundel dokumentasi. Respons memuatreference,tag,mediaType, pasangansize,digestyang dipublikasikan,alreadyPublished,dryRun, danreach. Permintaan ini tidak menandatangani apa pun — artefak yang dipublikasikan ditandatangani setelahnya berdasarkan referensi denganaggrega/signArtifacts, yang hanya memerlukan referensi yang dilaporkan respons ini. Ini menulis ke registri dan menjangkau ke luar mesin ini — lihat Menjangkau registri, dan menulis.aggrega/signArtifacts— menandatangani artefak yang sudah dipublikasikan dan melampirkan setiap tanda tangan.referencesmemuat satu atau beberapa alamat registri, bukan path, sehingga tidak berlaku kontrak relatif terhadap workspace; daftar kosong, atau entri kosong di dalamnya, ditolak. Satu identitas melayani seluruh batch dan di-resolve sebelum referensi mana pun ditandatangani, sehingga batch yang sama sekali tidak memiliki kredensial yang tersedia ditolak di awal, bukan di tengah jalan. Begitu pula batch yang referensinya akan memerlukan kredensial berbeda: permintaan tidak menamai kunci apa pun, jadi itu berarti konfigurasi workspace menamai kunci yang dimiliki untuk registri satu referensi dan tidak ada kunci, atau kunci lain, untuk registri referensi kedua — tidak ada yang ditandatangani, dan penolakan menamai registri di setiap sisi, seperti yang dijelaskan References signed together need different signing credentials (Referensi yang ditandatangani bersama memerlukan kredensial penandatanganan yang berbeda). Menandatangani referensi yang tidak memiliki publikasi apa pun ditolak alih-alih dilampirkan ke ketiadaan, dan referensi yang sudah membawa tanda tangan yang diverifikasi oleh kebijakan kepercayaan registrinya dibiarkan apa adanya dan dihitung sebagai sudah ditandatangani, seperti yang dijelaskanaggrega sign.jobs, yang opsional, adalah jumlah referensi yang ditandatangani sekaligus: jika tidak ada, referensi ditandatangani satu per satu, dan nilai di bawah 1 ditolak dengan galat invalid-params sebelum referensi apa pun dibaca. Setiap referensi tetap ditandatangani persis seperti jika ditandatangani sendirian, seperti yang dijelaskanaggrega sign, dan progres yang dilaporkan permintaan maupun respons sama-sama mempertahankan urutan referensi diberikan. Respons memuatsigned, dengan setiap entri menamai sebuahreferencedandigestyang dipublikasikan yang menjadi komitmen tanda tangannya, bersamareach; batch yang salah satu referensinya gagal dijawab sebagai kegagalan yang menamai masing-masing referensi tersebut, bukan sebagai hasil dengan daftar yang lebih pendek. Ini menulis ke registri dan menjangkau ke luar mesin ini — lihat Menjangkau registri, dan menulis.aggrega/deprecateArtifact— melampirkan penanda deprecation yang ditandatangani ke artefak yang sudah dipublikasikan. Kirim satureferencebesertaseveritydanreason-nya, ataufromyang menamai file batch relatif terhadap root workspace — mengirim keduanya ditolak. Field konten bersifat wajib alih-alih ditanyakan secara interaktif: tidak ada yang memantau stream ini, sehingga permintaan yang kekurangan salah satunya ditolak dengan menyebutkan apa yang harus dikirim. Field tersebut hanya berlaku untuk satureferencesaja: file batch membawa konten setiap penanda dalam entrinya sendiri, sehinggaseverity,reason,replacement, ataumessageyang dikirim bersamafromditolak sebagai parameter tidak valid dengan menyebutkan setiap field yang dikirim, alih-alih diabaikan. Input tanpa kunci yang sama yang diterima kedua permintaan penandatanganan berlaku di sini, karena penanda ditandatangani berdasarkan digest-nya sendiri, dan entri file batch terikat pada satu kredensial persis seperti referensi dalam batch penandatanganan. Respons memuatmarked, dengan setiap entri menamaireferenceyang ditarik,severity-nya, cap waktuissuedOn, dandigestmanifest milik penanda itu sendiri — penanda dilampirkan sebagai referrer tanpa tag dari artefak yang ditariknya, sehingga tidak ada hal lain yang mengalamatkannya — bersamareach. Ini menulis ke registri dan menjangkau ke luar mesin ini — lihat Menjangkau registri, dan menulis.aggrega/catalogIndex— indeks entitas:kind,name,apiVersion,description,labels, file sumber, danorigindari setiap entitas di workspace yang dinamai permintaan. Menerima workspace dan, secara opsional,release: himpunannya adalah properti dari root workspace tersebut dan direktori katalog yang dikonfigurasinya, atau, denganrelease, dari direktori yang diberikan konfigurasi kepada Release tersebut — lihat Menjawab dalam konteks satu Release. Indeks ini mencakup kedua tempat asal entitas — dokumen Aggrega di bawah root workspace, dan Features yang dimuat direktori katalog yang dikonfigurasi — karena inilah permukaan yang digunakan klien untuk melakukan join ketika memerlukan field deskriptif sebuah entitas, dan indeks yang hanya mengetahui salah satu dari keduanya akan membuat sebagian setiap daftar kandidat tidak dapat di-resolve. Dokumen workspace dihitung sebagai entitas ketika mendeklarasikankind:sekaligusmetadata.namedan tidak mendeklarasikanapiVersionyang termasuk dalam grup proyek lain, sehingga YAML yang kebetulan berada di pohon direktori — file values sebuah chart, konfigurasi CI, manifest Kubernetes yang sudah di-render — dilewati alih-alih dicantumkan. Dokumen yang sama sekali tidak mendeklarasikanapiVersiondilaporkan: itu adalah dokumen Aggrega yang kekurangan satu field, dan melihatnya tercantum adalah cara Anda mengetahui bahwa dokumen itu ada dan perlu diperbaiki. Lihat Cara sebuah entitas dialamatkan untuk artiorigindanfileyang kosong. Tidak ada dokumen di balik link yang mengarah ke luar root workspace yang dibaca: direktori di luar root tidak ditelusuri, dan file di luarnya tidak dibaca apa pun yang dideklarasikannya, sehingga entitas yang ditampilkan editor Anda di bawah link seperti itu tidak dicantumkan sebagai milik workspace — dan tidak ditawarkan olehaggrega/attachCandidatesatauaggrega/connectionCandidates, yang membaca dokumen yang sama, bahkan ketika editor Anda sedang membuka dokumen tersebut. Hal itu berlaku apa pun yang dideklarasikan dokumen tersebut. Satu-satunya pengecualian adalah Release yang dinamai konfigurasi workspace Anda — sebagaibuild.authoring_release, atau sebagai kunci dariworkspace.releases, dinilai berdasarkan file yang dituju link, sehingga menamai link atau file tersebut dihitung sama — yang dibaca dari file yang dituju link, dicantumkan di tempat link itu sendiri, sebagaimanaaggrega/releaseCandidatesmencantumkannya, dan tidak dinamai; file yang dinamai salah satu pengaturan tersebut yang mendeklarasikan sesuatu selain Release tidak dicantumkan, dan link-nya dinamai. Direktori katalog yang dikonfigurasi adalah cara workspace membaca entitas lain yang disimpan di tempat lain, sehingga link ke direktori yang dicantumkan konfigurasi di bawahcatalog_dirs— untuk workspace atau untuk sebuah Release — tidak ditelusuri seperti dokumen milik workspace sendiri dan juga tidak dinamai: konfigurasi telah menjangkaunya, dan Features-nya dicantumkan dari katalog, sebagaimana Features milik setiap direktori katalog yang dikonfigurasi. Features yang dicantumkan dari direktori katalog tidak pernah menyertakan Feature di balik link yang mengarah ke luar direktori tempat pembacaan direktori katalog harus tetap berada — workspace, untuk direktori katalog di dalamnya, atau direktori itu sendiri, untuk direktori yang dinamai konfigurasi di luar workspace — sehingga entitas yang dinamai respons sebagai berada di balik link yang tidak dibacanya tidak pernah juga dicantumkan di samping nama tersebut. Respons menamai setiap link seperti itu diunreadLinkedDirs, untuk link ke direktori, dan diunreadLinkedFiles, untuk link yang namanya sendiri diakhiri.yamlatau.ymldan yang mengarah ke file — relatif terhadap root, di tempat link itu berada, dalam urutan penelusuran workspace — sehingga klien dapat menjelaskan alasannya. Link yang dikecualikan oleh pencarian, karena namanya, karena letaknya, atau karena.gitignore, tidak dinamai, dan dalam respons dalam konteks sebuah Release, begitu pula link di bawah direktori katalog yang hanya dibaca oleh Releases lain. Link di bawah direktori katalog di luar workspace tidak memiliki tempat relatif terhadap root untuk dinamai, dan tidak dinamai. Keduanya selalu ada, dan kosong jika tidak ada link seperti itu. Jika file konfigurasi milik workspace itu sendiri, atau overlay milik CI di sampingnya, merupakan link yang mengarah ke luar workspace, file tersebut dinamai diunreadLinkedFilesbagaimanapun pencarian memperlakukannya, dan indeksnya adalah pembacaan milik workspace sendiri tanpa konfigurasi apa pun — tidak ada direktori katalog yang dibaca untuknya, dan indeks dalam konteks sebuah Release ditolak; lihat Root workspace dan Release aktif.aggrega/entityDefinition— hasil resolve entitas yang dinamai:kind-nya,namedanversionmiliknya sendiri,descriptiondanpublishScope-nya jika ada,filetempat entitas itu dideklarasikan,authoredLengthdari teks tulisan penulis di baliknya, dandefinition-nya sebagai dokumen YAML dengan pewarisan yang sudah diterapkan.filedilaporkan untuk setiap kind, sebagai path yang dapat Anda buka — relatif terhadap root workspace untuk dokumen di dalamnya, absolut untuk dokumen di luarnya, sesuai Cara penulisan path yang dilaporkan. Field ini kosong dalam satu kasus: entitas yang di-resolve dari registri tidak memiliki dokumen tulisan penulis di mesin ini untuk dinamai.authoredLengthmenjawab pertanyaan yang berbeda — seberapa banyak teks tulisan penulis yang dipertahankan oleh resolusi — dan hanya Aggregate yang disajikan dengan teks semacam itu, jadi bacalah keduanya secara terpisah, bukan sebagai pasangan.nameadalah identitas entitas, ditulis dengan cara satu entitas mereferensikan entitas lain, dan dapat membawa sufiks versi. Ini adalah satu-satunya permintaan di sini yang berangkat dari nama, bukan dari kursor, sehingga inilah yang perlu ditanyakan ketika Anda sudah tahu entitas mana yang Anda maksud.releasebersifat opsional dan me-resolve nama dalam konteks Release tersebut — lihat Menjawab dalam konteks satu Release. Nama yang tidak ter-resolve ke apa pun ditolak alih-alih dijawab dengan dokumen kosong; lihat Membedakan dua penolakan berdasarkan nama.namejuga dapat berupa referensi registri —oci://<host>/<repository>:<tag>, atau@<digest>sebagai pengganti:<tag>— dan responsnya kemudian adalah entitas yang dipublikasikan pada koordinat tersebut, dibaca dari registrinya, denganpublishedyang menamai apa yang dibaca; lihat Menanyakan sebuah koordinat.aggrega/releaseClosure— closure dependensi sebuah Release: entitas mana yang dijangkaunya dan pada versi ter-resolve mana, dientities,libraries, danplugins, bersama identitasaggregatedanmanifestyang menjadi hasil resolve kedua pointernya,mappingDiagnosticsapa pun yang dimunculkan resolusi, dandeprecationsyang tercatat terhadap apa yang dijangkaunya — di lockfile-nya dan di catatan kepercayaan plugin di sampingnya, sehingga plugin yang ditarik dan dilampirkan dalam peran putusan disebutkan sebagaimana referensi ter-pin yang ditarik disebutkan.releaseadalah path relatif terhadap root workspace yang menamai Release di dalamnya, nilai yang sama yang diterimaaggrega/irGraphdan ditolak dalam bentuk yang sama, dan memerlukan lockfile karena alasan yang sama. Tidak ada yang di-render. Entri-entrinya tidak menamaisourceapa pun: entri tersebut menyatakan apa yang menjadi dependensi Release, bukan apa yang dilakukan satu eksekusi, yang merupakan hal yang dilaporkanaggrega/resolveDependencies. Lihat Closure bukan graf, karena klien yang sudah menerima graf tidak memiliki informasi ini.aggrega/attachCandidates— Features mana yang dapat dilampirkan ke sebuah node: Features yang applicability-nya yang dideklarasikan dipenuhi oleh label node tersebut. Kirim tepat satu koordinat.nodemenamai dokumen workspace berdasarkanmetadata.name-nya;graphNodemenamai node pada graf terkompilasi milikrelease, berdasarkan id yang digunakan graf tersebut sebagai kuncinya;labelsmembawa himpunan label secara langsung dan tidak menamai apa pun, untuk klien yang sudah memilikinya. Respons mengulangi koordinat yang dijawabnya — kosong jika tidak ada yang perlu diulang — memuatnodeLabels, pasangan label yang digunakan untuk mengevaluasi kecocokan,labelSourceyang menyatakan jenis himpunan label tersebut, dan setiap kandidat sebagaikind,name, file sumber, danoriginyang mengalamatkannya. Mengembalikan label itulah yang membuat respons dapat diaudit dari dirinya sendiri: klien dapat menjelaskan mengapa sebuah Feature ditawarkan tanpa membentuk gagasannya sendiri tentang label node, yang merupakan cara jawaban klien dan jawaban compiler menjadi berbeda. Untuk node graf, Features yang ditawarkan adalah Features yang dijangkau oleh Release milik node tersebut. Di sampinggraphNode,connectionmenamai satu koneksi yang ditarik komponen node tersebut —socketdanalias-nya — dan respons kemudian juga memuatslots, setiap slot yang dideklarasikan socket koneksi tersebut beserta Features yang dapat mengisinya, ataunoSlotReasonjika tidak ada yang dapat diisi. Lihat Apa yang diberitahukan respons kandidat lampiran.aggrega/connectionCandidates— apa yang dapat dihubungkan dengan entitas yang dinamai.nodeadalahmetadata.namesebuah entitas, koordinat yang sama yang diterimaaggrega/attachCandidatesdengan nama tersebut. Lihat Apa yang diberitahukan respons kandidat koneksi di bawah, karena kedua bagian respons tidak sama lengkapnya dan respons menyatakan mana yang mana.aggrega/insertionPoint— tempat sebuah entri baru di bawah kontainer yang dinamai seharusnya berada dalam dokumen tulisan penulis, dinyatakan sedemikian rupa sehingga klien dapat menerapkannya tanpa mem-parse dokumen itu sendiri.filemenamai dokumen yang dimuat workspace, relatif terhadap root workspace, absolut, atau sebagai alamatfile://-nya; dokumen di luar root, sebagaimana ditulis atau melalui link yang mengarah ke luar root — ke file, atau ke direktori di sepanjang jalan — ditolak dengan ejaan apa pun yang menamainya, dan terlepas dari apakah Anda memiliki salinannya atau tidak;containeradalah path struktural dari root dokumen ke kontainer tempat entri dimasukkan, dengan setiap elemen berupa kunci mapping atau posisi sequence yang ditulis dalam desimal. Path tersebut Anda yang menyediakan — daemon membaca struktur dokumen itu sendiri dan tidak pernah menyimpulkan tempat sesuatu seharusnya berada dari namanya. Lihat Apa yang diberitahukan respons titik penyisipan, karena posisi saja tidak cukup untuk menerapkan pengeditan.aggrega/attachmentContainer— dokumen mana yang menjadi tempat lampiran Feature untuk sebuah node, dan kontainer mana di dalamnya.graphNodemenamai node pada graf terkompilasi milikrelease, berdasarkan id yang digunakan graf tersebut sebagai kuncinya, dan keduanya wajib: id node adalah kunci graf milik satu Release dan tidak berarti apa-apa tanpanya. Respons memuatnode,file, dancontainer— daftar segmen tepat dalam bentuk yang diterimaaggrega/insertionPoint, sehingga pasangan tersebut dapat digabungkan tanpa ada yang perlu disimpulkan di antaranya. Untuk lampiran pada satu koneksi yang ditarik komponen node, tambahkanconnectiondengansocket,alias, dandocument-nya —aggregateataurelease— dan respons menamai kontainerfeaturesmilik koneksi tersebut di dokumen itu. Lihat Apa yang diberitahukan respons kontainer lampiran, karenafilemerupakan bagian dari respons, bukan sesuatu yang sudah Anda ketahui.aggrega/connectionAtPosition— di dalam entri koneksi mana sebuah posisi dalam Aggregate atau Release berada, dijawab dalam istilah yang digunakan kedua permintaan di atas untuk menerima koneksi.filemenamai dokumen dengan caraaggrega/insertionPointmenamai dokumen, dan dokumen tersebut dibaca terlebih dahulu dari apa yang dimiliki sesi untuknya;positionadalah tempat di dalamnya, sebuahlinedan sebuahcharacteryang dihitung dari nol dalam encoding sesi;releasemenamai Release yang graf terkompilasinya mencatat koneksi, dan wajib juga untuk posisi di dalam Aggregate, karena node graf dan koneksi hanya ada pada graf terkompilasi. Respons memuatgraphNodedanconnection—socket,alias, dandocumenttempat posisi tersebut dibaca — untuk diteruskan tanpa perubahan keaggrega/attachCandidatesdanaggrega/attachmentContainer, ataunoConnectionReasonjika tidak ada koneksi yang ditulis di sana. Lihat Apa yang diberitahukan respons koneksi pada posisi.aggrega/editDocument— menerapkan satu pengeditan terstruktur yang terbatas ke dokumen tulisan penulis, dengan mempertahankan setiap byte yang tidak disentuhnya. Ini adalah separuh lain dari dua metode penentuan lokasi di atas: keduanya menyatakan tempat sebuah entri berada dan menyerahkan kepada Anda untuk menyusun dan menerapkannya, sedangkan yang ini menyusun dan menerapkan satu entri.editmenamai yang mana dari empat —add-component,attach-feature,wire-edge,set-value— dan nilai di luar keempatnya ditolak alih-alih ditafsirkan;nodeadalah path struktural dari root dokumen, daftar segmen tepat dalam bentuk yang diterimaaggrega/insertionPoint;nameadalah kunci tempat entri ditulis danvalueadalah isinya, yang maknanya mengikutiedit;socketdibaca untukwire-edgedan diabaikan selain itu.dryRunmelakukan semua yang dilakukan permintaan biasa kecuali menulis, dengan menjawab menggunakan dokumen yang telah diedit sebagaicontent, untuk klien yang menampilkan hasilnya kepada penulis terlebih dahulu; tidak ada yang dibuat dalam mode ini danwrittenkosong.filemenamai dokumen relatif terhadap root workspace atau berdasarkan path absolutnya, dan dokumen di luar root — sebagaimana ditulis, atau melalui link yang mengarah ke luar root, ke file atau ke direktori di sepanjang jalan — ditolak tanpa ada yang dibaca atau ditulis. Ini menulis dokumen yang Anda namai, di dalam workspace — tidak me-resolve dependensi apa pun, tidak menjangkau registri apa pun, dan tidak menyentuh jaringan dalam kedua cara pengiriman, dan penulisan bergantung pada validasi dokumen yang disusun terhadap skema kind-nya sendiri. Lihat Apa yang diberitahukan respons pengeditan dokumen, karena perilaku default-nya adalah menulis dan penolakan membiarkan file identik byte demi byte seperti semula.aggrega/releaseCandidates— dokumen Release dari workspace yang dinamai permintaan, sebagai path absolut. Menerima workspace dan tidak ada yang lain: himpunannya adalah properti dari root workspace tersebut. Keanggotaan ditentukan oleh kind dokumen —kind:file tersebut adalahRelease— dan bukan oleh nama file, sehingga Release yang dinamai tanpa prefiks konvensional tetap ditawarkan, sedangkan file yang sekadar dinamai seperti Release tidak. Inilah yang seharusnya dicantumkan pemilih “Release yang mana?” di editor, karena ini adalah himpunan yang sama yang menjadi sumber pilihan cascade Release aktif di bawah. Respons juga memuatlockfiles, yang memetakan setiap Release yang dicantumkan — dengan kunci berupa string yang persis sama dengan yang digunakanreleasesuntuk mencantumkannya — ke path absolut lockfile-nya; field ini selalu ada, dan berupa objek kosong jika workspace tidak memuat Release apa pun. Respons juga memuatunreadLinkedDirs, yang menamai — relatif terhadap root, di tempat link itu berada — setiap link yang berada di tempat daftar akan membaca direktori dan mengarah ke direktori di luar root workspace: tidak ada direktori di luar root yang ditelusuri, sehingga Release yang ditampilkan editor Anda di dalam direktori tersebut tidak dicantumkan, dan field inilah yang memungkinkan pemilih menjelaskan alasannya. Link ke direktori yang dicantumkan konfigurasi workspace Anda di bawahcatalog_dirstidak dinamai: konfigurasi telah menjangkaunya, sebagai direktori katalog, bukan sebagai tempat Releases disimpan. Field ini selalu ada, dan kosong jika tidak ada link seperti itu. Di sampingnya,unreadLinkedFilesmenamai dengan cara yang sama setiap link yang namanya sendiri diakhiri.yamlatau.ymldan yang mengarah ke file di luar root workspace: tidak ada file seperti itu yang dibaca, apa pun isinya, sehingga Release yang hanya dapat dijangkau melalui salah satu link ini tidak dicantumkan, dan langkah Release tunggal dalam cascade di bawah tidak menghitungnya. Pengecualiannya adalah file yang dinamai konfigurasi workspace Anda sebagai Release — sebagaibuild.authoring_release, atau sebagai kunci dariworkspace.releases, dinilai berdasarkan file yang dituju link, sehingga menamai link atau file tersebut dihitung sama — yang dibaca dan dicantumkan di tempat link itu sendiri, dan tidak dinamai, asalkan file tersebut mendeklarasikan Release; file yang mendeklarasikan hal lain tidak dicantumkan, dan link-nya dinamai. Field ini selalu ada, dan kosong jika tidak ada link seperti itu. Jika file konfigurasi milik workspace itu sendiri, atau overlay milik CI di sampingnya, merupakan link yang mengarah ke luar workspace, file tersebut dinamai di sini bagaimanapun pencarian memperlakukannya, dan daftar dibaca tanpa konfigurasi apa pun, sehingga Release yang akan dinamai konfigurasi melalui link tidak dicantumkan; lihat Root workspace dan Release aktif. Lihat Letak lockfile sebuah Release.aggrega/activeRelease— Release mana yang ditunjuk oleh workspace yang dinamai permintaan, sebagai path absolut dalam fieldrelease, untuk klien yang memutuskan apa yang dipilih secara default. Menerima workspace dan tidak ada yang lain. Field ini selalu ada, dan nilai kosong berarti workspace tidak menunjuk Release apa pun — respons yang berhasil, bukan error, sehingga klien yang memperbaruinya setiap kali daemon dimulai ulang tidak dipaksa memperlakukan workspace biasa sebagai kegagalan. Jika nilainya kosong, respons juga memuatreason, ringkasan satu baris tentang apa yang dicari cascade, dantrace, uraian langkah demi langkahnya; keduanya dihilangkan jika sebuah Release berhasil di-resolve. Jika sebuah Release berhasil di-resolve, respons memuatlockfilesebagai gantinya, path absolut lockfile Release tersebut, yang dihilangkan jika tidak ada yang di-resolve. Release yang dinamainya tidak harus salah satu yang dicantumkanaggrega/releaseCandidates— penanda dapat menamai Release di direktori yang dikecualikan daftar tersebut, sepertivendor/, atau Release yang dinamai tanpa ekstensi YAML — sehingga respons inilah tempat klien membaca lockfile Release default. Lihat Letak lockfile sebuah Release. Tanyakan hal ini alih-alih menyimpulkan jawabannya dari salah satu input cascade: input yang pada akhirnya tidak digunakan cascade menamai Release yang berbeda dari yang dipilihnya. Jawaban dihitung saat Anda bertanya, sehingga bertanya lagi setelah menulis penanda, mengedit konfigurasi, atau menambahkan file Release melaporkan jawaban yang baru, bukan workspace sebagaimana keadaannya saat daemon dimulai.aggrega/setActiveRelease— mencatat sebuah Release sebagai default workspace yang dinamai permintaan, dengan menulis penanda.aggrega/active-releasemilik workspace tersebut, dan menjawab persis sepertiaggrega/activeReleasemenjawab setelah penanda ditulis. Menerima workspace danrelease: path relatif terhadap root workspace yang menamai Release di dalamnya, terikat pada kontrak yang sama denganreleasemilikaggrega/irGraph— path absolut, path yang keluar dari workspace, dan nilai kosong ditolak, begitu pula path yang mengarah ke luar melalui link, kecuali konfigurasi workspace Anda menamai Release tersebut. Penanda adalah satu baris yang menamai Release relatif terhadap root, bentuk yang dibaca cascade di bawah. Penanda ditulis di dalam workspace dan tidak di tempat lain: jika.aggrega, atau penanda itu sendiri, merupakan link yang mengarah ke luar workspace — baik tempat yang dituju sudah ada maupun belum — permintaan ditolak dengan error invalid-params, yang pesannya adalah kalimat milik kondisi itu sendiri dengan kode pendeknya di depan,E0320: …(fatal-halts.md §“A path the operation writes leads through a link out of the directory it must stay inside (Path yang ditulis operasi mengarah melalui link ke luar direktori tempat path itu harus tetap berada)”), yang menamai link dan tujuannya, dan tidak ada yang ditulis; link yang tetap berada di dalam workspace ditulis melaluinya. Respons menamai apa yang ditetapkan cascade alih-alih mengulang apa yang Anda kirim, dan keduanya berbeda jikabuild.authoring_releasemenamai sebuah Release, karena konfigurasi lebih diutamakan daripada penanda. Catat default dengan cara ini alih-alih menulis file sendiri, sehingga tempat penanda berakhir dinilai berdasarkan aturan yang berlaku untuk setiap file yang ditulis produk di workspace — lihat Batas workspace.aggrega/effectiveConfiguration— konfigurasi yang berlaku untuk workspace yang dinamai permintaan, dan lapisan asal setiap pengaturan. Menerima workspace dan tidak ada yang lain: respons adalah properti dari workspace tersebut.layersmencantumkan file konfigurasi dan override lingkungan yang berkontribusi, dimulai dari prioritas terendah;settingsmemuat setiap pengaturan yang diatribusikan sebagai nama bertitiknya, nilai efektifnya, dansourceyang menentukannya. Sebuahsourcedieja persis seperti entri yang cocok dilayers, sehingga keduanya dapat digabungkan secara langsung. Lihat Cakupan respons konfigurasi efektif untuk lapisan mana yang dinamai sebuahsourcedan batasan arti sebuah baris.aggrega/configInit— menyiapkan konfigurasi yang berfungsi dengan mendaftarkan registri beserta kebijakan kepercayaan tanda tangannya, sehingga mesin baru dapat menarik dan memverifikasi artefak bertanda tangan tanpa mengedit YAML secara manual.registrybersifat opsional dan nilai yang tidak ada akan menyiapkan hub resmi, default yang sama yang digunakanaggrega config init;hostdalam respons menamai registri mana yang digunakan.globaldanworkspaceadalah override target penulisan dan mengirim keduanya ditolak. Permintaan ini menolak menimpa file konfigurasi yang sudah ada, dengan menamai file tersebut — kirimforceuntuk tetap melanjutkan, yang menggabungkan entri registri ke dalam apa yang sudah ada dan mempertahankan pengaturan lainnya.dryRunmelakukan semua yang dilakukan permintaan biasa kecuali menulis, dengan menjawab menggunakan konfigurasi yang disiapkan sebagaicontent, untuk klien yang menampilkan dokumen kepada penulis sebelum disimpan; tidak ada yang dibuat dalam mode ini danwrittenbernilai false. Penolakan karena file sudah ada juga berlaku di bawahdryRun, jadi kirimforcebersamanya untuk mendapatkan jawaban berupa penggabungan yang akan dihasilkan oleh penulisan yang menimpa. Di workspace offline hanya hub resmi yang dapat disiapkan: permintaan ini tidak menerima identitas atau kunci, sehingga registri lain mana pun ditolak persis sepertiaggrega/registryAddmenolaknya, termasuk kode pendek dan kalimatnya, dan harus ditambahkan melalui permintaan tersebut dengan kebijakan yang diberikan secara manual. Respons memuathost,scope,trust, danwritten, sertaexisted, bernilai true jika file konfigurasi sudah ada — sehingga entri registri digabungkan ke dalamnya alih-alih membuat file baru — dan tidak ada jika file dibuat. Ini menulis konfigurasi global secara default — lihat Menjangkau registri, dan menulis.aggrega/configCapture— membekukan konfigurasi efektif yang penting bagi build ke dalam file konfigurasi milik workspace ini sendiri, sehingga workspace di-build dengan hasil yang sama tanpa konfigurasi global mesin di bawahnya. Tidak menerima target penulisan: pembekuan ada untuk membuat satu workspace mandiri, sehingga selalu menulis file milik workspace tersebut.allPluginsmemperluas himpunan yang dibekukan dari socket yang menentukan output yang di-render — binding provider dan lampiran governance transformasi label — ke setiap socket plugin, dengan menambahkan gate governance verdict dan linter serta socket import. Respons memuatconfigFile,workspaceRoot,captured,sockets, dancatalogDirs. Lihat Apa yang ditinggalkan penulisan konfigurasi, karena respons menamai dokumen yang kini ada dan tindakan klien berikutnya adalah membukanya.aggrega/skillsInstall— menulis skill Aggrega yang tertanam dalam biner ini ke folder skill setiap asisten yang disebut permintaan, instalasi yang sama dengan yang dilakukanaggrega skills installdi terminal.agentsmencantumkan asisten berdasarkan pengidentifikasi, yaitu pengidentifikasi yang dilaporkanaggrega/skillsList; pengidentifikasi yang diberikan dua kali dipasang sekali, dan jika beberapa asisten yang disebut membaca satu folder bersama, skill ditulis di sana sekali. Instalasi proyek mewajibkannya. Permintaanglobalyang tidak menyebutkan asisten mana pun memasang skill untuk asisten yang ditemukan di mesin ini, seperti yang dilakukanaggrega skills install --globaltanpa--agent— setiap asisten yang folder konfigurasinya berada di direktori home, atau yang perintahnya ada diPATHlingkungan daemon — dan ditolak tanpa ada yang ditulis jika tidak ada yang ditemukan; tidak ada yang ditanyakan, daninstalledmenyebutkan asisten yang skill-nya ditulis. Tanpaglobal, skill ditempatkan di folder proyek setiap asisten di dalam workspace yang disebut permintaan, tidak pernah di direktori tempat daemon dijalankan; denganglobal: true, skill ditempatkan di folder per pengguna setiap asisten di bawah direktori home yang ditunjuk lingkungan daemon (HOME, atauUSERPROFILEdi Windows). Setiap tujuan diperiksa sebelum apa pun ditulis, sehingga penolakan membiarkan setiap folder seperti semula: pengidentifikasi yang tidak memiliki folder skill yang dikenal ditolak dengan menyebutkannya beserta pengidentifikasi yang ada, dan file di tujuan yang tidak membawa baris komentar yang dibawa setiap salinan skill yang ditulis ditolak dengan menyebutkan path-nya. Salinan yang membawa baris itu — yang ditulis instalasi sebelumnya, atau diambil dari repositori skill yang dipublikasikan — diganti, dan dengan cara itulahaggregayang lebih baru membawa skill ke versinya sendiri. Folder proyek yang dicapai melalui link yang mengarah ke luar workspace ditolak tanpa ada yang ditulis, sebagaimana setiap penulisan yang dilakukan daemon di workspace — lihat Batas workspace. Jawabannya membawaskill,installed— satu entri per folder yang ditulis, dalam urutan asisten disebut, masing-masing denganagentsyang membacanya,folderabsolut, danreplaced— sertascope. Denganglobal, ini menulis folder yang dibaca setiap proyek di mesin — lihat Menjangkau registry, dan menulis.aggrega/skillsList— skill yang disertakan biner ini dan setiap asisten yang dapat dituliskan skill-skill tersebut olehaggrega/skillsInstall, yaitu daftar yang dicetakaggrega skills list. Hanya menerima workspace dan tidak membaca apa pun darinya.skillsmembawanamedandescriptionsetiap skill;agentsmembawaid,name,projectFoldersetiap asisten — relatif terhadap root proyek, yang pada permukaan ini adalah workspace yang disebut permintaan — danuserFolder, relatif terhadap direktori home; keduanya dipisahkan dengan garis miring, dan entri diurutkan menurut pengidentifikasi. Tidak menulis apa pun dan tidak menjangkau apa pun.aggrega/pluginAdd— mencari plugin dengan tipe yang dinamai di registri yang dikonfigurasi dan menambahkannya ke konfigurasi.typedanquerysama-sama wajib:typeadalah salah satu dariprovider,governance,linter,importer, dancli, danquerydicocokkan dengan nama plugin bertipe tersebut dan harus ter-resolve ke tepat satu, sehingga kueri yang cocok dengan beberapa plugin ditolak dengan menyertakan kandidatnya alih-alih di-resolve secara sembarang.capabilitymenamai kapabilitas yang dilayani bindingproviderdan wajib untuk tipe tersebut;rolemenamai peran lampirangovernance—label-transform,ir-verdict, ataurender-verdict— dan wajib untuk tipe tersebut; masing-masing hanya dibaca untuk tipenya sendiri dan ditolak pada tipe lain, karena field yang diam-diam tidak melakukan apa pun akan tampak seolah-olah berhasil.acceptCapabilitieswajib untukclidan mengonfirmasi kapabilitas yang dideklarasikan plugin tersebut: perintah terminal memperoleh keputusan itu dengan bertanya, sedangkan permukaan ini tidak memiliki siapa pun untuk ditanya, sehingga pemanggil yang memperolehnya dan mengirimkannya.globaldanworkspaceadalah override target penulisan dan mengirim keduanya ditolak.dryRunmelakukan semua yang dilakukan permintaan biasa kecuali menulis, dengan menjawab menggunakan konfigurasi yang dihasilkan sebagaicontent; tidak ada yang dibuat atau diubah danwrittenbernilai false. Registri tetap dicari dan versi tetap di-resolve, karena identitas dalam konten tersebut adalah identitas yang akan di-pin oleh penulisan.dryRunditolak pada tipecli, alih-alih diabaikan: yang dicatat oleh penambahan ekstensi perintah adalah digest konten dari byte yang telah diverifikasinya, catatan yang dipelihara compiler, bukan konten yang diedit siapa pun, dan penambahan tersebut menyimpan byte itu di cache seiring berjalannya proses — sehingga hasilnya ditulis alih-alih dikembalikan. Versi di-pin untuk Anda — kueri ter-resolve ke satu plugin, dan versi yang dinamai kueri sebagai<name>:<version>, atau jika tidak ada, versi terpublikasi tertinggi plugin tersebut, ditulis ke dalam entri; versi yang dinamai yang telah ditarik oleh retraksi yang dipercaya workspace ini tetap di-pin dan jawabannya memuatwithdrawn: true. Ini menjangkau registri, dan penambahan bertipecliyang tidak menamai salah satu dari kedua cakupan menulis konfigurasi global — lihat Menjangkau registri, dan menulis. Lihat Apa yang diberitahukan perubahan plugin.aggrega/pluginRemove— menghapus entri plugin yang dikonfigurasi sehingga plugin tersebut tidak lagi berpartisipasi.typeadalah himpunan yang sama yang diterima penambahan, danquerymengidentifikasi entri: nama pendek plugin, referensinya yang di-pin, atau — untukprovider— kapabilitas yang dilayani binding. Keduanya wajib.globaldanworkspaceadalah override target penulisan yang sama, yang ditolak bersama-sama dengan cara yang sama. Kueri yang tidak cocok dengan entri apa pun ditolak alih-alih dijawab sebagai keberhasilan atas konfigurasi yang tidak berubah, sehingga pemanggil tidak pernah diberi tahu bahwa sebuah plugin berhenti berpartisipasi padahal tidak, dan salah ketik tidak pernah menghapus plugin yang berbeda. Permintaan ini tidak menghubungi registri apa pun: penghapusan hanya bekerja pada teks konfigurasi. Penghapusan bertipecliyang tidak menamai salah satu dari kedua cakupan menulis konfigurasi global — lihat Menjangkau registri, dan menulis. Lihat Apa yang diberitahukan perubahan plugin.aggrega/pluginSync— menyelaraskan catatan milik mesin dari sebuah entitas Plugin dengan modulnya: himpunan fungsi host yang diturunkan dari import modul itu sendiri, dan cermin perintah yang dibaca dari laporan diri modul. Tidak satu pun dari kedua catatan tersebut ditulis secara manual, karena keduanya bersumber kebenaran pada modul. Kedua field wajib dan tidak satu pun memiliki default — catatan diturunkan dari modul, sehingga penyelarasan yang tidak menamai keduanya tidak memiliki apa pun untuk diselaraskan — dan keduanya adalah path relatif terhadap root workspace, ditolak jika absolut atau ter-resolve di luarnya, sebagaimana ditulis atau melalui link. Hanya kedua blok itu yang berubah: setiap byte lain dipertahankan apa adanya, termasuk komentar, baris kosong, dan gaya kutipan, dan file yang sudah mencatat apa yang disiratkan modul dibiarkan identik byte demi byte dan dilaporkan sebagai tidak berubah. Ini menulis file entitas yang Anda namai, di dalam workspace, dan tidak menghubungi registri apa pun. Lihat Apa yang diberitahukan perubahan plugin.aggrega/pluginGenCatalog— menghasilkan satu entitas Plugin per guest yang dipilih, dengan menggabungkan field kontrak yang diturunkan dari laporan diri guest dengan overlay per plugin yang ditulis secara manual.fromEmbeddeddanpluginadalah dua mode pemilihan dan tepat satu yang berlaku: setiap guest yang dibawa biner ini, atau satu modul di jalur yang Anda sebutkan; menyebutkan keduanya, atau tidak menyebutkan keduanya, ditolak alih-alih diselesaikan.overlaywajib diisi, dan berupa direktori overlay di bawahfromEmbeddedatau satu file overlay di bawahplugin— sebuah overlay dicocokkan dengan guest berdasarkan identitas jika ada beberapa, dan tidak ada yang perlu dicocokkan jika hanya ada satu.outputDirwajib diisi di kedua cara pengiriman, dandryRuntidak membebaskannya: uji coba mengubah ke mana konten pergi, bukan untuk file mana konten itu, sehingga setiap dokumen yang dikembalikan tetap menyebutkan jalur yang menjadi tujuannya dan jalur itu disusun dari direktori ini. Ketiga jalur di sini tidak dinilai dengan cara yang sama, dan pembedaannya mengikuti apa yang dilakukan proses pembuatan terhadap masing-masing.plugindanoverlaydibaca, dan keduanya adalah file yang Anda pilih — sebuah modul berada di direktori mana pun tempat toolchain-nya melakukan build, dan overlay-nya ditulis di sampingnya — sehingga masing-masing boleh absolut dan dibaca di tempat sebenarnya berada.outputDirditulisi, sehingga bersifat relatif terhadap root workspace dan ditolak jika absolut atau teresolusi ke luar root tersebut, baik sebagaimana tertulis maupun melalui tautan — direktori yang belum dibuat di bawah direktori bertautan yang mengarah ke luar ditolak sebagaimana direktori itu ditolak. Menjalankan ulang dengan input yang tidak berubah menghasilkan entitas yang identik byte demi byte. Ini menulis entitas yang dihasilkan di bawahoutputDir, di dalam workspace, kecualidryRunmemintanya sebagai konten. Lihat Apa yang disampaikan perubahan plugin kepada Anda.aggrega/getSchema— JSON Schema untuk suatu jenis entitas atau kontrak, dibaca dari salinan yang dikompilasi ke dalam biner yang sedang berjalan.kindadalah token skema berhuruf kecil dengan tanda hubung —component,aggregate,release,recipe,ir,wasm-provider, dan seterusnya — dan bersifat opsional, karena token ini memilih pertanyaan mana dari dua pertanyaan yang Anda ajukan. Sebutkan suatu jenis dan respons berisikinddanschema, yaitu skema sebagai dokumen JSON, bukan sebagai string yang memuatnya. Jangan sebutkan jenis apa pun dan respons berisikindsdanentityKinds: jenis mana yang boleh Anda sebutkan, dalam dua cakupan.kindsadalah setiap token yang dapat diminta dari biner ini, dalam urutan yang sama dengan yang dicetak olehaggrega get-schema --list.entityKindsadalah himpunan yang lebih sempit berupa jenis yang dokumennya ditulis oleh penulis, dengan setiap entri berisi tokenkindyang harus dikirim kembali, nilaidocumentKindyang masuk ke fieldkind:milik dokumen itu sendiri, danacceptedBy, yang menyatakan apakah validasi entitas tunggal, publikasi, dan inspeksi berdasarkan nama menerima dokumen jenis tersebut. Lihat Jenis mana yang boleh Anda tawarkan kepada penulis sebelum Anda membangun pemilih dari salah satunya. Jawaban skema dan enumerasi tidak pernah digabungkan, sehingga pertanyaan mana yang dijawab dapat dibaca dari respons. Token yang tidak sesuai dengan skema mana pun ditolak dengan seluruh himpunan yang valid dicantumkan di pesan, sehingga salah ketik dapat diperbaiki tanpa panggilan kedua. Perintah ini tidak mengambil apa pun dari workspace, tidak menghubungi registry, dan tidak menulis apa pun, sehingga dapat menjawab di workspace yang sama sekali kosong — dan itulah yang membuatnya dapat digunakan untuk menghubungkan asosiasi skema editor dengan biner yang benar-benar dikendalikan oleh editor tersebut, alih-alih dengan salinan skema mana pun yang terpasang di tempat lain.aggrega/scaffoldEntity— dokumen awal untuk suatu jenis entitas: tepat field yang diwajibkan oleh skema jenis tersebut, denganapiVersiondankindyang tetap sudah terisi dan placeholder di setiap tempat yang memerlukan nilai.kindwajib diisi dan merupakan token skema berhuruf kecil dengan tanda hubung —component,aggregate,release,recipe,manifest,feature, dan seterusnya;aggrega/getSchematanpakindmelaporkan token mana yang boleh Anda kirim, dan token yang tidak sesuai dengan skema mana pun ditolak dengan himpunan itu dicantumkan di pesan sehingga salah ketik dapat diperbaiki tanpa panggilan kedua. Klien yang menawarkan pilihan jenis kepada penulis membacaentityKindsdari metode tersebut, yaitu himpunan jenis yang dokumennya dapat ditulis.namebersifat opsional dan mengisi awalmetadata.nameuntuk jenis yang skemanya mewajibkannya. Respons berisikinddanskeleton. Lihat Apa yang diberikan respons scaffold kepada Anda, karena jawabannya adalah dokumen yang harus ditulis, bukan dokumen yang sudah ditulis. Kerangka tersebut diturunkan dari skema yang sama yang dilaporkanaggrega/getSchema, sehingga keduanya menjawab dari satu sumber. Jika dikirimiexamplealih-alihkind, metode ini menulis salah satu contoh dokumentasi yang dapat dijalankan ke direktori baru di workspace, seperti yang dilakukanaggrega scaffold --exampledi terminal; jika hanya dikirimilist: true, metode ini menjawab dengan setiap contoh yang ada dan tidak menulis apa pun. Kedua bentuk memerlukan workspace, sehingga permintaan untuk salah satunya menyebutkannya diworkspaceRootdan permintaan yang tidak menyebutkannya ditolak.dirmenamai direktori baru relatif terhadap root workspace, dan defaultnya adalah nama contoh; nilai absolut, atau nilai yang ter-resolve ke luar root — sebagaimana ditulis, atau melalui link — ditolak sebelum apa pun dibaca, dan direktori yang berisi apa pun ditolak dan dibiarkan apa adanya. Jawaban untuk daftar membawaexamples, masing-masing denganname,level, dansummary; jawaban untuk penulisan membawaexample,dir,files— setiap file yang ditulis, relatif terhadapdir—next, perintah yang diberikan halaman contoh untuk mem-build-nya, tidak ada jika halaman tidak memberikannya, danversion, versi dokumentasi tempat contoh dibaca. Field dari dua bentuk yang dikirim bersamaan —kinddenganexample,listdenganexampleataukind,namedenganexampleataulist, ataudirtanpaexample— ditolak sebelum apa pun dibaca, dengan kata-kata yang sama seperti penolakan oleh tool asisten. Penulisan memperoleh bundel dokumentasi jika mesin tidak menyimpan salinan yang lolos pemeriksaan tanda tangan milik workspace itu sendiri, dan menulis di dalam workspace — lihat Menjangkau registry, dan menulis.aggrega/import— mengubah deskripsi sumber asing menjadi draf file authoring Aggrega, konversi yang sama yang dilakukanaggrega importdi terminal.sourcewajib diisi dan menyebutkan file atau direktori yang akan dikonversi, baik sebagai jalur absolut maupun relatif terhadap root workspace — deskripsi yang diekspor oleh alat lain berada di mana pun Anda menyimpannya, sehingga dibaca di tempat sebenarnya berada, bukan hanya di dalam workspace. Sebuah direktori dibaca sebagaimanaaggrega importmembacanya: file di dalamnya yang dipilih oleh pola file yang dideklarasikan importer, kecuali folder output build workspacedist/, dan dibatasi pada dirinya sendiri di mana pun letaknya, sehingga tidak ada tautan di dalamnya yang diikuti ke luar.outputDirbersifat opsional dan menyebutkan direktori tempat draf disimpan, dan tidak mengikuti kontrak tersebut: direktori ini ditulisi, sehingga berupa jalur di dalam workspace, dan nilai absolut, atau nilai yang teresolusi ke luar root — sebagaimana tertulis, atau melalui tautan, termasuk direktori yang belum dibuat di bawahnya — ditolak. Jika dihilangkan, draf ditempatkan di bawah root workspace, tempataggrega importmenulisnya ketika tidak menyebutkan tujuan — termasuk di bawahdryRun.formatmenyebutkan format sumber secara eksplisit; jika dihilangkan, format dikenali dari tanda tangan yang dideklarasikan importer — baik importer dari katalog workspace maupun importer inti compiler — dan sumber yang tidak dikenali oleh importer mana pun, atau dikenali oleh importer dari lebih dari satu format, ditolak dengan memintaformatalih-alih ditebak.targetmenyebutkan capability provider, seperticomposeatauhelm— kata yang diikat olehspec.capabilitysebuah Recipe — dan membuat draf, di samping draf importer, Manifest yang menjadi acuan build Release yang didraf untuk provider tersebut, persis seperti yang dilakukanaggrega import --target:manifest.yaml, yang memetakan setiap tipe komponen dan tipe fitur yang dibutuhkan draf — termasuk tipe dari Aggregate katalog yang disusun oleh Aggregate yang didraf — ke Recipe atau resep fitur dengan capability tersebut yang ditawarkan katalog workspace untuknya, berdasarkan nama yang dikualifikasi capability tanpa versi: satu-satunya yang ada, atau, di antara beberapa, yang dinamai sesuai tipe tersebut.spec.manifestmilik Release diatur ke manifest tersebut; tipe yang tidak memiliki satu pun, atau memiliki beberapa tetapi tidak ada yang dinamai demikian, dibiarkan tidak terpetakan dengan temuanwarnyang menyebutkannya, dan pemetaan yang didraf sendiri oleh importer dipertahankan jika katalog menawarkannya untuk tipe dan capability tersebut, dan jika tidak, dibuang dengan temuanwarn.targetyang tidak diikat oleh Recipe mana pun di katalog ditolak sebelum importer berjalan, dengan menyebutkan target tersebut dan capability yang diikat oleh Recipes di katalog, dan tidak ada yang ditulis; jika dihilangkan, tidak ada Manifest yang didraf — kecuali di bawahsync, yang membuat draf untuk target yang disebutkan oleh catatan impor sebelumnya. Importer inti yang belum dimiliki mesin akan diambil oleh impor pertama yang membutuhkannya — lihat Apa yang disampaikan respons impor kepada Anda.dryRunmelakukan semua yang dilakukan permintaan biasa kecuali menulis, dan menjawab dengan draf sebagai konten, untuk klien yang terlebih dahulu menampilkannya kepada penulis; tidak ada yang dibuat dalam mode ini danwrittenkosong.syncmemperbarui apa yang didraf oleh impor sebelumnya dioutputDiragar sesuai dengan sumber, hanya mengubah apa yang ditulis oleh impor tersebut, seperti yang dilakukanaggrega import --sync; tanpa opsi ini, permintaan yang drafnya akan menimpa Aggregate yang sudah ada ditolak. Jawaban berisiformat,outputDir,written,files,drift,diagnostics,decisions, danhalted. Lihat Apa yang disampaikan respons impor kepada Anda, karena sumber yang tidak dapat dikonversi sepenuhnya oleh importer merupakan jawaban yang berhasil, bukan error.aggrega/explainError— apa yang dideklarasikan compiler tentang kondisi yang disebutkan oleh sebuah kode, beserta entri terbitan yang mengajarkan perbaikan authoring-nya.codewajib diisi dan menerima salah satu dari dua pengenal sebuah kondisi: kode pendek yang dibawa diagnostik dishortCode, atau kode deskriptif dicode. Ini adalah ekspansi dari kode yang sudah dibawa oleh diagnostik di jalur ini, dan merupakan jawaban yang sama dengan yang dicetakaggrega explaindi terminal. Jawaban selalu berisi kondisinya —shortCode,code, danmessage— karena bagian itu dideklarasikan di dalam biner dan tidak memerlukan jaringan;entriesberisi panduan langkah demi langkah yang diterbitkan, dannotemenyatakan mengapa panduan itu tidak ada, jika memang tidak ada. Ini memperoleh bundel dokumentasi jika mesin tidak memiliki salinan yang diterima oleh pemeriksaan tanda tangan milik workspace itu sendiri — lihat Menjangkau registry, dan menulis. Lihat Mengekspansi kode yang dibawa diagnostik.aggrega/invalidate— sinyal invalidasi cache dari pemantau file editor.
Notifikasi:
$/cancelRequest— dari klien ke server: menghentikan permintaan yang sedang berjalan yang dikirim dengan id tersebut. Daemon membatalkan pekerjaan permintaan itu; sebuah operasi menyadari pembatalan pada batas langkah berikutnya, bukan seketika, sehingga pekerjaan yang sudah berjalan masih berlanjut sesaat. Membatalkan id yang tidak sedang menjalankan apa pun adalah operasi tanpa efek yang aman.$/progress— dari server ke klien: apa yang sedang dilakukan operasi panjang selama operasi itu berlangsung, pada token yang diminta oleh permintaan untuk menerima laporan. Hanya dikirim untuk permintaan yang membawa token tersebut. Lihat Memantau operasi panjang.aggrega/shutdown— memulai pengosongan kooperatif: permintaan yang sedang berjalan diselesaikan, permintaan baru ditolak, lalu daemon keluar.aggrega/publishDiagnostics— himpunan diagnostik yang didorong oleh server (digunakan untuk peringatan pergeseran lockfile dan status saat startup). Setiap entri membawasourceyang menyebutkan lapisan diagnostik daemon mana yang memunculkannya:aggregauntuk temuan tentang dokumen yang ditulis,aggrega-builduntuk saran yang dimunculkan oleh build — setiap saran yang dimunculkannya, yaitu himpunan yang sama dengan yang dicetakaggrega build— danaggrega-lintuntuk temuan tentang konvensi publikasi, temuan yang sama dengan yang dicetakaggrega lint. Field ini selalu ada di setiap entri, sehingga klien dapat mengelompokkannya alih-alih menampilkan satu daftar yang tidak dibedakan, dan tidak pernah perlu membedakan sumber yang tidak ada dari salah satu lapisan. Sebuah frame dikirim untuk sebuah file hanya jika himpunannya berbeda dari himpunan yang terakhir diberitahukan kepada klien ini, sehingga permintaan yang menghitung ulang temuan yang sama tidak mengirim apa pun; frame pertama sebuah file, dan frame yang mengosongkan himpunan sebuah file, keduanya merupakan perbedaan dan selalu dikirim.
Meminta proses itu sendiri untuk berhenti menjangkau daemon dengan ketentuan yang sama. Interupsi dari terminal, atau permintaan penghentian dari supervisor atau runtime kontainer, memulai pengosongan yang sama dengan yang dimulai aggrega/shutdown: permintaan yang sedang berjalan diselesaikan, permintaan baru ditolak, lalu daemon keluar. Permintaan kedua langsung mengakhiri proses. Klien yang menjalankan daemon dapat menghentikannya dengan cara mana pun, dan klien yang menghentikannya melalui protokol maupun yang mengirim sinyal kepadanya mendapatkan pengosongan yang sama.
Validasi langsung
Pada setiap aggrega/validate, daemon memvalidasi buffer editor terhadap skema dokumen dan mengembalikan diagnostik yang menunjuk ke key yang bermasalah — putusan yang sama dengan yang akan diberikan build, atas konten yang belum disimpan. Permintaan yang tidak mengirim content menanyakan file sebagaimana adanya di disk; content yang dikirim kosong adalah buffer kosong, bukan permintaan atas file. File yang dikirim tanpa kontennya harus merupakan file yang ada di workspace dan dapat dibaca — file di luar workspace, file yang dijangkau melalui tautan yang mengarah ke luar, atau file yang tidak ada ditolak dengan kode invalid-params. Entitas katalog, Aggregates, Manifests, dan Releases dikenali dari apiVersion dan kind-nya. Dua dokumen yang tidak memiliki header semacam itu — konfigurasi workspace .aggrega-config.yaml dan lockfile Release yang disebutkan permintaan — dikenali dari nama filenya, sehingga key sampah atau key yang salah bentuk di salah satunya juga langsung diberi garis bawah berlekuk. File yang bukan dokumen Aggrega — template chart Helm, file Compose, manifest Kubernetes, dan file .lock dari ekosistem lain seperti Cargo.lock atau flake.lock — tidak menerima diagnostik; daemon tidak pernah melaporkan apa pun tentang file asing.
Placeholder yang masih terutang disebutkan pada key-nya, beserta apa yang diterimanya. Entitas katalog dengan jenis yang diperiksa aggrega validate sebagai entitas tunggal juga dibaca untuk nilai wajib yang dibiarkannya sebagai string kosong, dengan pembacaan yang diterapkan perintah tersebut, sehingga daemon menyebutkan setiap placeholder yang disebutkan perintah untuk byte yang sama. Setiap placeholder adalah satu entri: message-nya menyatakan bahwa key tersebut adalah placeholder yang masih terutang, suggest-nya menyatakan apa yang diterima nilai tersebut, dan keyPath-nya membawa jalur bertitik dari key tersebut. Entri ini menggantikan temuan skema itu sendiri untuk nilai kosong tersebut, dan setiap temuan lain pada dokumen dilaporkan sebagaimana pemeriksaan skema melaporkannya. Placeholder yang oleh skema diizinkan kosong juga disebutkan, meskipun pemeriksaan skema tidak melaporkan apa pun tentangnya — capability dan implements dari Recipe atau FeatureRecipe yang didraf adalah yang akan Anda temui. Jika pemeriksaan skema juga menolak dokumen tersebut, setiap entri membawa kode pemeriksaan itu, E0215, dan jika menerimanya, entri tidak membawa kode: pengenal yang sama dengan yang dibawa laporan perintah untuk byte tersebut. Sebuah entri digambar pada key yang memuat nilai kosong, di baris tempat perintah menyebutkannya — bahkan untuk key yang namanya sendiri mengandung titik, seperti label component.aggrega.ai/type, di mana temuan yang dilaporkan pemeriksaan skema pada key itu digambar pada key yang melingkupinya — dan keyPath menyebutkan key tersebut secara lengkap. Hal ini berlaku baik permintaan menyebutkan Release maupun tidak, karena ini adalah pertanyaan yang dijawab dokumen itu sendiri, dan dokumen yang masih berutang nilai belum ditanyai tentang konvensi publikasi: lapisan itu dikosongkan untuknya, sebagaimana untuk dokumen yang bentuknya ditolak skema.
Setiap permintaan menyebutkan Release yang dimaksud, dan daemon tidak menyimpan Release miliknya sendiri. Pemeriksaan semantik meresolusi closure dependensi Release tersebut dan membaca lockfile Release tersebut untuk pin-nya — atau, untuk entitas katalog, membaca direktori katalog yang digunakan Release tersebut untuk build, seperti dijelaskan paragraf berikutnya — sehingga dua permintaan yang menyebutkan dua Releases masing-masing dijawab tentang Release yang disebutkannya. Tidak ada yang terbawa di antara keduanya: tidak ada Release terpilih yang perlu diubah, dan mengubah Release yang menjadi acuan validasi Anda hanyalah nilai yang berbeda pada permintaan berikutnya, bukan sesuatu yang harus diperintahkan kepada daemon untuk dilupakan.
Entitas katalog yang disebutkan bersama Release diperiksa sebagai entitas tunggal, menurut ketentuan Release tersebut. file yang memuat Component, Feature, Recipe, FeatureRecipe, atau Plugin, yang dikirim dengan release, mendapatkan pemeriksaan yang dijalankan aggrega validate <path> --release <release>, atas buffer editor yang belum disimpan: referensinya — Component yang diimplementasikan sebuah Recipe, pustaka yang dirujuk sebuah pilar — diresolusi melalui direktori katalog yang diberikan konfigurasi workspace kepada Release tersebut, sehingga satu file dapat bersih menurut ketentuan Release yang melakukan build dengannya dan gagal menurut ketentuan Release yang direktorinya tidak memuat apa yang dirujuknya. Itulah putusan yang diberikan baris perintah dan alat validate dari aggrega mcp untuk entitas yang sama di samping Release yang sama, dan seperti keduanya, pemeriksaan ini tidak menelusuri closure dan tidak membaca lockfile. Temuan yang memblokir adalah satu entri error dengan kata-kata pemeriksaan itu sendiri dan membawa kodenya, digambar pada key yang disebutkannya di entitas dan, jika tidak menyebutkan key apa pun, pada key kind: entitas, sebagaimana dijelaskan Apa yang dibawa entri diagnostik — kecuali jika build sudah melaporkan kesalahan itu pada file tersebut, dan dalam hal itu entri build menjadi satu-satunya laporan; saran yang dimunculkan pemeriksaan saat membaca katalog adalah entri peringatan yang mendahuluinya; pemeriksaan bersih atas direktori yang semuanya ada tidak menghasilkan entri. Asersi yang gagal — asersi yang memanggil fail, di dalam Recipe atau di dalam Component yang diimplementasikannya — di sini bukan temuan yang memblokir melainkan entri peringatan, dengan kata-kata pemeriksaan dan membawa kodenya, ditutup dengan kalimat A Release must satisfy this assertion before a build of it can pass., dan digambar di tempat temuan yang memblokir akan berada: asersi Recipe pada key milik asersi itu sendiri di bawah assertions, asersi Component pada key kind: milik Recipe. Seperti temuan yang memblokir, entri ini mengalah kepada entri build yang melaporkan kesalahan yang sama pada file tersebut. Pemeriksaan membangun entitas di sekitar placeholder dan nilai default skema, bukan nilai yang ditetapkan Release, sehingga tidak dapat membedakan asersi yang menunggu Release dari asersi yang rusak, dan menyerahkan putusan kepada build, yang melaporkan asersi yang sama sebagai error (asersi yang gagal adalah peringatan). Direktori yang dicantumkan konfigurasi workspace untuk Release tetapi bukan direktori — misalnya tidak ada apa pun di sana — menghentikan pemeriksaan di situ: file membawa satu entri error alih-alih putusan pemeriksaan, yaitu penolakan yang diberikan setiap perintah untuk direktori itu, yang menyebutkan entri tersebut, file konfigurasi dan baris yang mencantumkannya, serta pengaturannya (Dari mana entitas lokal dibaca). release yang tidak menyebutkan file, atau yang menyebutkan direktori, dijawab pada file dengan kalimat yang digunakan baris perintah untuk menolaknya, alih-alih diperiksa menurut ketentuan workspace. Apa yang tidak dapat digantikan oleh build satu entitas dinilai sebagaimana baris perintah menilainya, dan apa yang dikesampingkan atau tidak diperiksa baris perintah tidak menghasilkan entri di sini — lihat apa yang tidak diperiksa oleh kebenaran entitas tunggal, dan, untuk Recipe yang template-nya membaca nilai yang hanya disediakan oleh sisi topologi atau kredensial yang dilampirkan, kebenaran entitas tunggal. Aggregate milik Release itu sendiri, Manifest, Release, dan pustaka tidak diperiksa satu per satu, karena pemeriksaan entitas tunggal tidak menerima jenis-jenis tersebut; jenis-jenis itu tetap mendapatkan pemeriksaan closure di atas. Buffer yang memuat konten Workload dibaca sebagai YAML yang bukan dokumen Aggrega, karena konten itu ditulis di dalam field workload: milik Recipe atau FeatureRecipe dan diperiksa di sana, tempat konten itu berada; baris perintah dan alat validate, ketika diberi file Workload melalui jalur, memeriksa bentuknya secara tersendiri.
Menyebutkan Release bersifat opsional, dan jawabannya menyatakan mana dari keduanya yang Anda minta. Sebutkan satu dan Anda mendapatkan semua yang dijelaskan di atas. Jangan sebutkan apa pun dan Anda mendapatkan pemeriksaan yang dijawab dokumen untuk dirinya sendiri — apakah dokumen dapat diurai, apakah bentuknya sendiri dapat diterima, dan, untuk entitas katalog dengan jenis yang divalidasi sebagai entitas tunggal, placeholder mana yang masih terutang — tanpa meresolusi Release, menelusuri closure, atau membaca lockfile; balasan kemudian berisi checked: "document". Sebutkan Release dan key tersebut tidak ada, karena jawaban itu adalah putusan lengkap metode dan tidak ada yang perlu dikualifikasi.
Baca key tersebut alih-alih menyimpulkan dari diagnostik, karena kedua jawaban dapat terlihat identik. Dokumen yang tersusun dengan baik dan divalidasi tanpa Release membalas dengan daftar diagnostik kosong, yang persis sama dengan balasan putusan lengkap yang bersih, sehingga checked adalah satu-satunya hal yang membedakan “tidak ada yang salah” dari “tidak ada hal yang memerlukan Release yang diperiksa”. Satu konsekuensi mengikuti dari aturan yang sama: lockfile dikenali dari korelasinya dengan Release yang disebutkan permintaan, sehingga permintaan yang tidak menyebutkan Release tidak mengenali lockfile apa pun dan tidak melaporkan apa pun tentangnya.
Workspace yang tidak memuat Release dijawab alih-alih ditolak, dan itulah yang membuat bagian lain daemon tetap dapat digunakan di sana. Validasi adalah hal yang mengisi cache penguraian yang dibaca setiap operasi file lainnya, sehingga repositori yang hanya berisi katalog, scaffold dengan satu Aggregate, atau direktori coretan tetap mendapatkan hover, pelengkapan, buka definisi, referensi, implementasi, dan diagnostik yang di-cache. Menolaknya akan menghilangkan semua itu, tepat di workspace tempat klien tidak memiliki Release untuk disebutkan.
Apa yang dibawa entri diagnostik
Setiap entri menentukan posisinya dengan line dan column, keduanya berbasis 1 dalam encoding posisi yang dinegosiasikan saat handshake, dan menambahkan end_line dan end_column jika mencakup satu token utuh. message adalah teks yang ditampilkan klien kepada pengguna, severity mengklasifikasikannya, dan source menyebutkan lapisan daemon mana yang memunculkannya, seperti dijelaskan di atas.
Lapisan-lapisan tersebut menjawab pertanyaan yang berbeda tentang satu file, sehingga entri dari masing-masing dapat berada di baris yang sama tanpa ada yang menjadi duplikat dari yang lain: satu menyatakan bahwa deployment tidak benar, yang lain bahwa entitas tidak dapat dipublikasikan. Klien yang menampilkannya sebagai satu daftar akan melaporkan satu masalah dua kali, dan membaca source adalah hal yang memisahkannya.
Letak sebuah entri bergantung pada apa yang dibahasnya, bukan pada lapisan mana yang memunculkannya. Temuan tentang sesuatu yang ditulis penulis ditempatkan pada key tempat penulis menuliskannya, sehingga editor menggambarnya di tempat suntingan seharusnya dilakukan. Temuan tentang bentuk topologi yang di-deploy menyebutkan sebuah komponen dan key pengiriman, bukan baris — itu adalah koordinat dalam topologi yang di-deploy, bukan dalam dokumen — sehingga digambar pada key kind: dokumen dan sebagai gantinya menyebutkan koordinatnya di pesan. Kedua jenis tersebut mencapai lapisan aggrega-build, karena build memunculkan keduanya. Penolakan yang dimunculkan build saat melakukan render juga mencapai lapisan itu, pada dokumen yang ditunjuk oleh penolakan itu sendiri — Workload yang tidak memenuhi pemeriksaannya pada key workload milik Recipe-nya, asersi Recipe yang gagal pada key milik asersi itu sendiri, entri yang ditolak oleh komposisi graf pada key tempat Release atau Aggregate menuliskannya, dan setiap temuan dari penolakan yang menggabungkan beberapa temuan pada dokumen dan key-nya sendiri — dan, jika tidak menunjuk ke dokumen mana pun, pada key kind: milik Aggregate; Penolakan yang dimunculkan saat render menjelaskannya. Jadi klien menempatkan setiap entri berdasarkan line dan column miliknya sendiri dan tidak pernah menyimpulkan posisi dari lapisan.
Temuan yang tidak menyebutkan key yang ada di dokumen digambar pada key yang menamai dokumen tersebut. Temuan yang dimunculkan pemeriksaan milik dokumen itu sendiri tentang isinya, temuan pemeriksaan entitas tunggal, serta saran atau penolakan yang dimunculkan build masing-masing digambar pada key yang disebutkannya; jika tidak menyebutkan key apa pun, atau menyebutkan key yang tidak ada di dokumen, temuan itu digambar pada key kind: dokumen, atau pada metadata.name-nya jika dokumen tidak mendeklarasikan kind:, dan di awal file hanya jika dokumen tidak mendeklarasikan keduanya atau tidak dapat diurai. Dokumen umumnya dibuka dengan komentar — setiap file katalog membawa header lisensi — dan entri yang digambar di baris pertamanya akan berada di atas komentar itu dan terbaca sebagai kesalahan di dalamnya, padahal identitas dokumen itu sendiri adalah baris yang ditulis penulisnya. Entri tentang sesuatu selain isi dokumen ditempatkan di awal file: entri Dependencies: tentang dependensi Release, tahap yang berhenti tanpa menyebutkan apa pun di dokumen, lockfile yang bergeser, referensi yang terpaksa ditolak oleh render, Release yang tidak termuat — dan demikian pula entri aggrega-lint yang aturannya tidak menghitung baris apa pun. Jika posisi dinyatakan alih-alih digambar, temuan yang tidak menyebutkan key tetap tidak memilikinya: jawaban error dari penolakan yang tidak menyebutkan key hanya membawa dokumen di dalam data-nya.
Pada dokumen mana sebuah entri dipublikasikan mengikuti aturan yang sama. Validasi yang menyebutkan Release menjawab Aggregate milik Release tersebut, Release itu sendiri, dokumen setiap modul yang diimpor Aggregate, dan Manifest yang disebutkan Release. Temuan yang ditempatkan di Release — penolakan atas entri yang ditulis Release pada salah satu koneksi sebuah komponen, atas ukuran yang diberikannya pada koneksi itu, atas lampiran yang diisi atau diberi ukurannya di sana, atas koneksi yang dirangkainya, atas Feature yang hanya dilampirkan Release ke sebuah komponen atau ke sebuah batas, atau atas infra yang diberikannya kepada sebuah lampiran — dipublikasikan ketika dokumen Release divalidasi, pada key di Release yang menuliskannya, dan sama sekali tidak pada Aggregate. Temuan yang ditempatkan di dokumen milik sebuah modul sendiri — penolakan atas apa yang dideklarasikan salah satu komponen modul tersebut, atas socket yang dirangkai lampiran-lampirannya, atas nilai-nilainya, atau atas nilai pada koneksinya sendiri — dipublikasikan ketika dokumen modul itu divalidasi, pada key di sana yang menuliskannya, dan sama sekali tidak pada Aggregate. Temuan tentang tabel pemetaan Manifest — entri yang memetakan sebuah tipe ke Recipe atau FeatureRecipe yang tidak mengimplementasikannya, entri yang pin versinya tidak dapat diurai, atau tipe terpetakan yang rantai extends-nya tidak dapat diikuti — dipublikasikan ketika Manifest tersebut divalidasi, pada key entri pemetaan yang bersangkutan, dan sama sekali tidak pada Aggregate; jika teks Manifest yang terbuka tidak menuliskan entri tersebut — entri yang diwarisinya melalui extends miliknya sendiri, atau entri yang dihapus oleh suntingan yang belum disimpan — temuan dipublikasikan pada baris pertama Manifest. Setiap temuan lain yang dimunculkan validasi Release tersebut dipublikasikan pada Aggregate, di antaranya temuan tingkat dependensi yang tidak menyebutkan dokumen apa pun di workspace Anda — referensi atau plugin yang ditarik, Component atau Feature katalog yang rantai extends-nya tidak dapat diresolusi atau yang skemanya tidak valid, plugin gerbang yang tidak cocok dengan catatan kepercayaan, instans komponen yang tidak diresolusi oleh pemetaan mana pun, Recipe atau FeatureRecipe yang penyedianya tidak dapat merender jenis input yang dideklarasikannya, serta saran tumpang-tindih pilar skema dan penyempitan saat extend. Jadi temuan tentang apa yang ditulis operator muncul saat Release terbuka, temuan tentang apa yang dideklarasikan sebuah modul muncul saat modul itu terbuka, dan temuan tentang pemetaan muncul saat Manifest terbuka, tahap build mana pun yang memunculkannya; editor yang memvalidasi setiap dokumen yang terbuka terhadap Release menampilkan masing-masing di sana. Release yang dependensinya sama sekali tidak dapat diresolusi tidak memunculkan satu pun temuan tersebut, dan kegagalan meresolusinya menjadi satu entri di awal dokumen milik Release itu sendiri dan setiap dokumen lain yang divalidasi terhadapnya yang dikenali daemon, sebagaimana dijelaskan Validasi langsung, dan tidak diperiksanya sebagai entitas tunggal — Aggregate-nya, Manifest-nya, sebuah pustaka, Release lain, konfigurasi workspace — dengan awalan Dependencies: dan membawa penjelasan resolusi itu sendiri tentang apa yang menghentikannya. Pada dokumen milik Release itu sendiri, entri tersebut adalah penjelasan itu dan tidak lebih. Pada setiap dokumen lain, entri tersebut pertama-tama menyatakan bahwa dokumen diperiksa terhadap Release tersebut dan menyebutkan Release itu sebagaimana permintaan menyebutkannya — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: diikuti penjelasannya — karena tidak ada apa pun di dokumen itu yang menyatakan terhadap Release mana dokumen itu diperiksa: editor yang memeriksa setiap dokumen yang terbuka terhadap satu Release yang dipilih menempatkan entri tersebut pada dokumen yang tidak ada hubungannya dengan Release itu, dan namanyalah yang memberi tahu Anda bahwa pilihan tersebut adalah penyebabnya. File yang tidak dikenali daemon tidak membawa entri semacam itu, Release mana pun yang disebutkan bersamanya.
Sebuah jawaban membawa setiap lapisan yang ada pada file, sejauh apa pun validasi berjalan. Jawaban aggrega/validate adalah seluruh status file saat ini: apa yang ditemukan validasi ini, entri aggrega-build yang dipublikasikan pada file oleh build, pratinjau, atau permintaan graf, dan temuan konvensi publikasinya, masing-masing di bawah source-nya sendiri. Validasi yang berhenti pada buffer — buffer yang tidak dapat diurai, atau dokumen yang amplopnya ditolak skema — menjawab dengan cara yang sama: melaporkan temuannya sendiri dan membiarkan setiap entri build pada file tetap ada, karena validasi itu tidak mempelajari apa pun tentang build. Jadi klien dapat mengganti apa yang dipegangnya untuk file tersebut, lapisan demi lapisan, dari jawaban mana pun.
Satu kesalahan dilaporkan satu kali. Validasi milik dokumen itu sendiri dan build dapat menemukan kesalahan yang sama di dalamnya: pemeriksaan entitas tunggal melakukan render atas Recipe yang juga di-render oleh build, validasi menyusun graf yang disusun build, dan Release yang dependensinya tidak teresolusi membuat keduanya gagal. Selama build melaporkan kesalahan semacam itu pada sebuah dokumen, validasi dokumen itu tidak melaporkannya untuk kedua kalinya: entri aggrega yang menyebutkan kondisi yang sama — code yang sama — dengan penolakan build pada dokumen yang sama, yang ditempatkan pada rentang yang sama atau tidak pada key miliknya sendiri — digambar di tempat entri tanpa key digambar, atau di awal file — dihilangkan dari setiap jawaban dan setiap publikasi untuk dokumen tersebut, dan laporan build berdiri sendiri. Laporan build adalah entri penolakan pada lapisan aggrega-build; atau, untuk aggrega/build, aggrega/buildPreview, atau aggrega/irGraph yang ditolak dengan 1004 karena sebuah dependensi tidak teresolusi, jawaban itu sendiri — yang tidak dipublikasikan oleh apa pun — pada dokumen yang disebutkan data.file-nya, atau jika tidak ada, data.lockfile-nya, atau jika tidak ada, Release yang disebutkan permintaan, dengan jawaban semacam itu yang terakhir untuk sebuah Release sebagai yang berlaku. Validasi tetap menyimpan apa yang ditemukannya: begitu tidak ada build yang melaporkan kesalahan tersebut — eksekusi berikutnya memublikasikan lapisan tanpa kesalahan itu, jawaban build, pratinjau, atau graf berikutnya untuk Release tersebut berupa hal lain, atau terhubung klien yang tidak pernah menerima jawaban 1004 semacam itu — entri milik dokumen itu sendiri dilaporkan kembali, dan jika belum ada build yang berjalan, tidak ada yang dihilangkan. Entri aggrega yang ditempatkan pada key yang tidak memiliki penolakan build tetap ada, bahkan jika menyebutkan kondisi yang sama, karena entri itu bisa jadi kesalahan kedua dari jenis tersebut yang belum dilaporkan build.
code adalah kode yang stabil dan dapat dicocokkan mesin untuk apa yang dilaporkan entri, sehingga klien dapat bercabang berdasarkan kode itu tanpa mencocokkan teks pesan. Satu key membawa kode tersebut, siapa pun yang menetapkannya, dan source memberi tahu Anda jenis mana yang sedang Anda pegang, karena lapisan-lapisan menamai sesuatu dari kosakata yang berbeda.
- Pada entri
aggrega— temuan tentang dokumen yang ditulis — kode adalah string tempat kondisi tersebut didaftarkan, ditulis sebagai paket yang mendeklarasikan diikuti aturan dalam kebab-case. Ini adalah nilai yang sama yang dibaca konsumen Go denganCodeOf, yang bentuk dan permukaan yang dapat dicocokkannya dijelaskan di referensi sentinel error. - Pada entri
aggrega-build— saran yang dimunculkan build — kode adalah apa pun yang ditetapkan oleh titik yang memunculkannya, dan lapisan ini membawa saran dari dua kosakata yang berbeda karena build memunculkan saran tentang dua jenis hal yang berbeda. Saran tentang bentuk topologi yang di-deploy membawa kode kelas, sepertiunsupported-field, yang ditetapkan di mana pun saran itu dimunculkan, baik di plugin rendering maupun di render itu sendiri; kode kelas menamai kelas saran, bukan kondisi terdaftar, sehingga tidak memiliki baris di referensi sentinel, dan referensi peringatan menjelaskan kelasunsupported-fielddan flag yang membungkamnya. Saran tentang dokumen yang ditulis — nama yang berjarak satu suntingan dari nama yang dideklarasikan, parameter yang tidak dibaca apa pun — membawa string tempat kondisinya didaftarkan, dalam bentuk yang sama dengan entriaggregadan dengan baris di referensi sentinel. Bagaimanapun, kode menamai apa temuan itu, bukan siapa yang menemukannya, sehingga satu kelas sampai kepada Anda dengan satu kode berapa pun banyaknya tempat yang memunculkannya, dan membaca kode alih-alih lapisan adalah hal yang memberi tahu Anda mana dari keduanya yang sedang Anda pegang. Penolakan tempat build berhenti saat melakukan render adalah satu-satunya entri di sini yang bukan saran, dan entri itu membawa string tempat kondisinya didaftarkan dengan cara yang sama. - Pada entri
aggrega-lint— temuan konvensi publikasi — kode adalah identitas temuan tersebut: identitas aturan yang menghasilkannya, atau, untuk temuan yang tidak menyebutkan aturan — yang dapat dilaporkan linter milik Anda sendiri dengan kodenya sendiri — kode tersebut. Ini adalah pengenal yang dicetakaggrega lintpada baris temuan, setelah kode pendek jika ada, dan nilai yang dibawaaggrega lint --output jsonuntuk temuan yang sama, sebagairuleId, atau sebagaicodeuntuk temuan yang tidak menyebutkan aturan. Satu temuan mempertahankan satu identitas di seluruh antarmuka, sehingga klien yang mengelompokkan atau menekan sebuah aturan di editor mengelompokkan dan menekan aturan yang sama di terminal. Setiap aturan dalam set aturan linter publikasi yang dideklarasikan Aggrega didaftarkan sebagai kondisi dengan identitas tersebut, sehingga tercantum di tabel semua kondisi dengan kode pendek yang dicetakaggrega lintdi awal baris temuan yang sama dan yang dibawaaggrega lint --output jsonpadanya sebagaishortCode. Aturan dari linter milik Anda sendiri yang tidak dideklarasikan Aggrega tidak menyebutkan kondisi terdaftar, demikian pula temuan yang tidak menyebutkan aturan, bahkan jika kodenya sendiri mengeja identitas aturan yang dideklarasikan Aggrega — sehingga keduanya tidak tercantum di sana. Aturan-aturan tersebut dijelaskan di referensiaggrega lint.
Apa pun lapisannya, key ini menjawab satu pertanyaan — apa ini, dalam istilah yang dapat dicocokkan mesin — sehingga ekstensi editor yang menyorot, mengelompokkan, atau menekan satu kelas temuan berpatokan pada kode, dan tetap berfungsi ketika susunan kata pesan berubah.
Perhatikan objek mana yang membawa apa: ini adalah string pada entri diagnostik, berbeda dari code numerik pada amplop error JSON-RPC yang dijelaskan di bawah pada Kode error. Sebuah respons membawa salah satunya, tidak pernah keduanya di satu tempat.
Key ini dihilangkan jika tidak ada apa pun yang menghasilkan entri tersebut menetapkan kode, dan setiap jenis memiliki kasus itu. Buffer yang tidak dapat dibaca parser YAML mana pun melaporkan teks parser itu sendiri dan tanpa kode, karena tidak ada kondisi milik Aggrega sendiri di baliknya; tahap yang melaporkan kegagalan tanpa menyebutkan kondisi juga tidak memiliki kondisi untuk dilaporkan; dan saran yang pemunculnya tidak menetapkan kode tiba tanpa kode. Jadi perlakukan code sebagai opsional, sama seperti end_line dan end_column, dan bercabanglah berdasarkan kode itu hanya jika ada. Kode adalah apa yang dilaporkan diagnostik dan tidak pernah apa yang memilihnya: tidak ada permintaan yang menerima kode, dan menuliskan kembali kode ke dalam kode Anda sendiri memberi Anda string, bukan cara untuk mencocokkan.
Pengenal yang dicocokkan program, dan pengenal yang dikutip manusia
Sebuah kondisi membawa dua pengenal, dan keduanya ditujukan untuk dua pembaca yang berbeda. code adalah pengenal di atas: terkualifikasi dan memakai tanda hubung, sehingga program yang bercabang berdasarkan pengenal itu terbaca sesuai maknanya. shortCode adalah huruf E dan empat digit — E0164 — dan merupakan pengenal yang dapat dibacakan oleh manusia, diketik di kotak pencarian, atau ditempelkan ke sebuah issue. Keduanya menyebutkan kondisi yang sama dan tidak ada yang merupakan singkatan dari yang lain.
Mana yang dipakai bergantung pada siapa yang membaca. Cocokkan berdasarkan code di ekstensi Anda; tampilkan shortCode kepada penulis. Ekstensi yang hanya menampilkan code membuat pembaca memegang pengenal yang ditujukan untuk program, dan ekstensi yang mencocokkan berdasarkan shortCode mencocokkan angka yang tidak mengatakan apa pun tentang kondisi tersebut. Pembagian itulah alasan keduanya dikirim, bukan hanya satu.
codeDescription adalah tempat kondisi tersebut dipublikasikan, dibawa sebagai { "href": … }, yaitu struktur milik protokol itu sendiri untuk referensi yang dapat dibuka guna mengetahui lebih lanjut tentang sebuah diagnostik. Editor yang memahami protokol mengubahnya menjadi opsi “pelajari lebih lanjut” tanpa perlu diajari apa pun tentang Aggrega, dan tidak ada klien yang memerlukan salinan penjelasannya. Alamat tersebut mengarah ke daftar terbitan semua kondisi, tempat entri untuk sebuah shortCode menyebutkan kondisinya dan berlanjut ke panduan langkah demi langkah perbaikan authoring-nya.
Teks penjelasannya sendiri tidak ada di entri, dan itu disengaja. Diagnostik dipancarkan pada setiap suntingan, sehingga penjelasan yang menyertai masing-masing akan menerbitkan ulang paragraf yang sama pada setiap ketukan tombol kepada pembaca yang biasanya sudah membacanya. Klien yang menginginkan teks memintanya sekali, dengan aggrega/explainError di bawah; klien yang dapat mengikuti tautan tidak memerlukan keduanya.
Kedua key ada tepat ketika entri menyebutkan kondisi terdaftar, dan tidak ada bersama-sama jika sebaliknya. Yang menentukannya adalah apa yang berada di balik entri, bukan lapisan mana yang memublikasikannya, jadi bacalah key-nya, bukan lapisannya:
- Entri yang menyebutkan kondisi terdaftar membawa ketiganya.
shortCodeteresolusi, dan referensinya mengarah ke daftar tempat kode itu teresolusi. - Entri yang kodenya menyebutkan kelas hanya membawa
code. Kelas saran render, dan identitas temuan konvensi dari linter milik Anda sendiri — aturan yang tidak dideklarasikan Aggrega, atau kode yang dibawa temuan yang tidak menyebutkan aturan — adalah pengenal nyata yang dapat Anda gunakan untuk mengelompokkan dan menekan, dan keduanya bukan kondisi terdaftar — sehingga tidak ada angka untuk dikutip dan tidak ada apa pun di alamat tersebut yang menjelaskannya. Referensi yang tetap dikirim akan menjadi tautan yang membuka halaman yang tidak membahas masalah pembaca, itulah sebabnya tidak ada yang dikirim. Ini adalah bentuk biasa pada lapisanaggrega-build, meskipun saran build yang memang menyebutkan kondisi terdaftar membawa ketiganya seperti entri lainnya. Pada lapisanaggrega-lint, bentuk biasanya adalah set lengkap: aturan dalam set aturan linter publikasi yang dideklarasikan Aggrega adalah kondisi terdaftar, sehingga temuannya membawashortCodeyang sama dengan yang dicetakaggrega lintdi awal baris temuan, beserta referensi di sampingnya. - Entri yang tidak menyebutkan apa pun tidak membawa pengenal sama sekali.
Jadi ketiga kasus dapat dibedakan dari key-nya saja: tidak ada code berarti tidak ada yang disebutkan, code tanpa shortCode di sampingnya berarti pengenal yang tidak teresolusi lebih jauh, dan set lengkap berarti pengenal dengan tempat untuk membaca tentangnya. Perlakukan kedua key baru itu sebagai opsional, sama seperti code, dan tawarkan sesuatu untuk dibuka kepada pembaca hanya jika codeDescription tiba.
Mengekspansi kode yang dibawa diagnostik
aggrega/explainError mengubah salah satu dari dua pengenal sebuah kondisi menjadi apa yang dideklarasikan compiler tentangnya dan entri terbitan yang mengajarkan perbaikan authoring-nya. Ini adalah ekspansi yang sama dengan yang dilakukan aggrega explain di terminal dan yang dilakukan alat explain-error untuk asisten, dan ketiganya menjawab dari satu tempat, sehingga kode yang diekspansi di sini dan kode yang sama yang diekspansi di sana adalah satu jawaban, bukan tiga jawaban yang kebetulan sama.
code wajib diisi dan menerima salah satu pengenal — shortCode yang dibawa diagnostik, atau code di sampingnya — karena klien yang memegang salah satunya tidak memiliki cara untuk memperoleh yang lain tanpa bertanya. Nilai kosong ditolak dengan menyebutkan apa yang harus dikirim.
Jawaban selalu membawa shortCode, code, dan message: dua pengenal kondisi dan kalimat pembuka setiap diagnostik yang menyebutkannya. Semua itu dideklarasikan di dalam biner, sehingga tiba tanpa jaringan dan tanpa cache, dan itulah yang memungkinkan workspace yang tidak memuat dokumentasi tetap dijawab. reference adalah alamat yang sama dengan yang dibawa codeDescription sebuah diagnostik, untuk klien yang lebih suka mengarahkan pembacanya ke dokumentasi daripada merender teks.
entries membawa panduan langkah demi langkah yang diterbitkan, setiap entri sebagai heading yang membukanya dan body di bawahnya, dalam urutan yang digunakan dokumentasi itu sendiri untuk memasangkannya dengan kondisi tersebut. Field ini dihilangkan jika panduan tidak dapat ditambahkan, dan note kemudian menyatakan alasannya: halaman terbitan belum mendokumentasikan entri untuk kondisi ini, atau workspace ini tidak dapat membaca dokumentasi — mesin tidak memiliki salinan, atau hanya memiliki salinan yang ditolak oleh pemeriksaan tanda tangan workspace. Bagaimanapun, kondisi di atasnya tetap berlaku — jawabannya bukan kegagalan, dan klien menampilkan apa yang tiba beserta catatan di sampingnya. entries dan note tidak pernah tiba bersamaan.
Kode yang tidak dapat diresolusi oleh apa pun ditolak alih-alih dijawab dengan kondisi yang semua field-nya kosong, dan setiap penolakan menyatakan kasus mana yang terjadi: kode yang tidak memiliki kondisi terdaftar, angka yang pernah menyebutkan sebuah kondisi dan tidak pernah menyebutkan kondisi lain, atau kode yang tidak dideklarasikan biner ini ketika daftar terbitan sama sekali tidak dapat dibaca — kasus terakhir membiarkan kedua perbaikan tetap terbuka, karena daftar yang diterbitkan untuk versi lain dapat menyebutkan kondisi yang tidak dideklarasikan biner ini.
Dokumentasi dibaca dari bundel yang di-cache untuk workspace yang disebutkan permintaan, diperoleh pada penggunaan pertama jika tidak ada, dan itulah satu-satunya hal yang membuat permintaan ini menjangkau registry — lihat Menjangkau registry, dan menulis. Tidak ada yang ditulis ke workspace. Tidak ada validasi yang memicunya: ekspansi terjadi karena sebuah permintaan memintanya, sehingga registry tidak pernah dijangkau saat dokumen sedang divalidasi atau diinspeksi.
Konvensi publikasi, atas permintaan dan pada setiap pengeditan
Daemon menjawab dua pertanyaan berbeda tentang sebuah entitas katalog, dan keduanya adalah pertanyaan yang dijawab oleh aggrega validate dan aggrega lint di terminal: apakah deployment benar, dan apakah entitas tersebut dapat dipublikasikan menurut konvensi katalog. Validasi selalu menjawab pertanyaan pertama. Validasi menjawab pertanyaan kedua hanya jika Anda memintanya.
aggrega/lint memintanya secara eksplisit. Kirim entity untuk satu entitas katalog, release untuk setiap entitas yang dicapai oleh closure dependensi Release tersebut, atau tidak keduanya untuk memeriksa setiap entitas di bawah direktori katalog yang dikonfigurasi: tiga cakupan yang dimiliki perintah tersebut. Mengirim entity dan release sekaligus menyebut dua subjek yang berbeda dan ditolak. Jawabannya memuat checked, jumlah dokumen entitas yang dicakup oleh eksekusi, dan files, temuan yang dikelompokkan menurut dokumen yang masing-masing dibahas dan diurutkan menurut path, dengan entri setiap file dalam bentuk diagnostik yang dijelaskan di atas. halted menyatakan apakah putusan eksekusi itu sendiri menolak publikasi.
Tidak mengirim keduanya akan memeriksa seluruh katalog seperti yang dilakukan aggrega lint tanpa argumen. Workspace yang konfigurasinya tidak memberikan direktori katalog Release miliknya sendiri diperiksa sekali, atas direktorinya sendiri, dan jawabannya adalah yang dijelaskan di atas. Workspace yang menyebut beberapa Releases di bawah workspace.releases diperiksa sekali untuk setiap Release di dalamnya, atas direktori yang dibaca Release tersebut, dan tidak pernah atas semuanya sekaligus, sehingga varian katalog yang disimpan berdampingan, satu per Release, masing-masing diperiksa menurut ketentuan Release yang membacanya. Jawabannya kemudian juga memuat passes, satu entri per putaran: releases, Releases yang menjadi sasaran putaran itu, masing-masing relatif terhadap root workspace, dengan Releases yang membaca direktori yang sama berbagi satu entri; catalogDirs, direktori yang dibacanya, ditulis seperti files menulis sebuah path, dan kosong untuk Release yang tidak membaca direktori apa pun, yang dilaporkan alih-alih menggagalkan yang lain; serta hitungan dan files milik putaran tersebut, yang menunjukkan untuk Release mana sebuah temuan ditemukan. checked, hitungan, dan files di sekitarnya mencakup semua putaran bersama-sama, sehingga klien yang tidak membaca passes tetap membaca seluruh eksekusi. Eksekusi yang tidak satu putaran pun memiliki direktori untuk dibaca ditolak alih-alih dijawab sebagai katalog yang bersih.
Atur prePublish bersama entity untuk membandingkan entitas tersebut dengan versi yang dipublikasikan sebelumnya dan mengklasifikasikan kenaikan versi yang diusulkan terhadapnya. Itulah satu-satunya mode di sini yang menjangkau registry, dan mode ini dijalankan karena permintaan menyebutnya: yang mengizinkan operasi yang menjangkau ke luar adalah bahwa pemanggil memintanya. Mode ini hanya bermakna dengan entity, sehingga prePublish tanpa entitas ditolak.
aggrega/lint tidak memublikasikan apa pun ke dalam sesi. Ia menjawab tentang subjek yang diberikan kepadanya, dan menulis temuannya ke daftar masalah editor akan menggantikan apa yang telah dipublikasikan oleh validasi untuk file yang tidak pernah dicakup oleh permintaan tersebut. Tidak ada yang ditulis ke disk dalam mode apa pun.
serve.lint_on_validate menjalankan aturan yang sama pada setiap validasi, dan nonaktif kecuali Anda mengaktifkannya. Aktifkan di .aggrega-config.yaml, di workspace yang entitasnya ingin Anda dapatkan sarannya:
serve: lint_on_validate: trueTidak ada flag untuk ini, karena pertanyaan yang dijawabnya menyangkut konten workspace itu sendiri, dan orang yang memiliki pertanyaan itu adalah orang yang menulis workspace, bukan siapa pun yang meluncurkan daemon. Jika diaktifkan, validasi sebuah entitas katalog juga memublikasikan temuan konvensi di bawah sumber aggrega-lint; jika dinonaktifkan, yang merupakan default, validasi hanya melaporkan lapisan kebenaran dan tidak ada temuan konvensi yang sampai kepada Anda. Sesi editor tidak mengatakan apa pun tentang apakah sebuah entitas dapat dipublikasikan sampai Anda meminta lapisan tersebut.
Tiga hal berlaku pada lapisan itu, apa pun yang dinyatakan kunci tersebut. Hanya mode yang membaca konten lokal yang dijalankan, sehingga tidak ada registry yang dihubungi, tidak ada yang diambil, dan tidak ada yang ditulis; perbandingan pra-publikasi dicapai dengan mengirim aggrega/lint dengan prePublish, tidak pernah melalui validasi, karena pemeriksaan yang dijalankan pada setiap pengeditan justru merupakan tempat registry tidak boleh dijangkau. Aturan dievaluasi terhadap buffer yang dibawa permintaan, bukan terhadap file di disk, sehingga nama yang Anda perbaiki berhenti dilaporkan sebelum Anda menyimpan. Dan temuannya bersifat anjuran: dokumen yang memunculkannya tetap tervalidasi, dan Release-nya tetap di-resolve dan di-render, sehingga ini menambahkan sebuah lapisan dan tidak pernah sebuah penolakan.
Kunci tersebut mengendalikan lapisan itu dan tidak ada yang lain. aggrega/lint menjawab apa pun yang ditanyakan kepadanya dengan kedua nilai, karena pemanggil yang mengirimnya telah meminta pemeriksaan itu secara eksplisit.
Hanya jenis yang dipublikasikan ke katalog yang diperiksa, karena itulah yang menjadi pokok konvensi. Dokumen yang bukan konten katalog, termasuk Aggregate dan Release, dilewati, demikian pula YAML yang sama sekali bukan dokumen Aggrega. Itulah yang membuat sesi tetap tenang terhadap dokumen tempat seorang penulis menghabiskan sebagian besar waktunya.
Cara penulisan path yang dilaporkan
Ketika sebuah jawaban menyebut dokumen yang ditemukan daemon untuk Anda, satu aturan menentukan cara path tersebut ditulis: relatif terhadap root workspace jika dokumen berada di dalamnya, dan path absolut jika tidak. Ini mencakup file pada identitas entitas, file pada definisi entitas, dan file yang menjadi kunci setiap grup dalam jawaban lint. Kedua bentuk itu adalah path yang dapat Anda buka, yang pertama terhadap root yang Anda sebutkan, yang kedua apa adanya, dan keduanya tidak pernah dibiarkan kosong karena lokasi dokumen.
Paruh kedua aturan inilah yang dibutuhkan direktori katalog yang dikonfigurasi. Workspace dapat menunjuk ke direktori katalog di mana saja pada mesin, dan dokumen di salah satunya sama nyatanya dengan dokumen di bawah root. Path absolut adalah yang menamainya, dan itu adalah bentuk yang sama yang dicetak aggrega lint dan diagnostik yang menghentikan proses untuk file tersebut di terminal, sehingga satu file memiliki satu nama, permukaan mana pun yang Anda tanyai. Yang tidak akan Anda terima adalah path yang naik melampaui root, yang akan menyebut file yang berbeda bergantung pada dari mana path itu dibaca.
Bentuk mana yang Anda terima dapat dibaca dari nilainya: apa pun yang dibaca platform Anda sebagai path absolut adalah bentuk kedua, dan selebihnya relatif terhadap root workspace. Anda tidak perlu mengujinya untuk membuka file (menggabungkan path relatif ke root dan membuka path absolut apa adanya sama-sama berfungsi), tetapi klien yang mengelompokkan menurut dokumen workspace dapat membedakan keduanya tanpa bertanya.
Yang tidak dicakup aturan ini. Path yang Anda kirim diatur oleh kontrak milik permintaan tersebut, yang dinyatakan bersama permintaan di atas dan biasanya lebih ketat: tujuan ditolak kecuali relatif terhadap root workspace dan ter-resolve di dalamnya, termasuk tautannya. Notifikasi aggrega/publishDiagnostics membawa file-nya secara absolut dalam setiap kasus, di dalam maupun di luar root, karena nilai itu adalah pengenal yang Anda cocokkan dengan dokumen terbuka Anda sendiri, bukan koordinat di workspace; editor Anda me-resolve-nya sebagai path sistem file. aggrega/releaseCandidates dan aggrega/activeRelease menyebut setiap Release dan lockfile dengan path absolutnya, seperti yang dinyatakan entri masing-masing di atas. Dan aggrega/irGraph membawa graf terkompilasi sebagaimana dicatat oleh compiler, dengan hanya menahan nilai yang dideklarasikan sensitif oleh penulis, sehingga path apa pun yang tercatat di dalamnya adalah path yang dicatat compiler, dalam bentuk yang ditetapkan oleh kontrak graf itu sendiri, bukan path yang disusun protokol ini untuk Anda.
Bentuk yang diterima parameter yang Anda kirim
Yang dinamai sebuah path, bukan metode mana yang membawanya, yang menentukan bentuk mana yang diterima parameter tersebut. Entri masing-masing permintaan di atas menyatakan kontrak untuk parameter yang diterimanya; berikut ini adalah perbedaan di antara keduanya, dan mengapa itu merupakan perbedaan, bukan inkonsistensi yang harus Anda hafalkan per metode.
Parameter yang menyebut dokumen yang sudah Anda pegang dapat ditulis dengan tiga cara: relatif terhadap root workspace, absolut, atau sebagai alamat file:// yang dikirim klien language server untuk dokumen yang terbuka. Itulah file atau uri dari aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint, dan aggrega/connectionAtPosition. Ketiganya menyebut satu dokumen dan dijawab dengan cara yang sama, karena masing-masing direduksi menjadi satu bentuk kanonis di batas permintaan sebelum apa pun membacanya, sehingga dokumen yang Anda validasi dengan path-nya ditemukan dengan alamatnya, dan sebaliknya, dan bentuk mana yang Anda kirim tidak mengubah apa pun pada jawabannya. Alamat dibaca sebagai path yang dinamainya, dengan percent-escape-nya didekode, ketika authority-nya kosong atau localhost; alamat yang menyebut mesin lain dibaca sebagai berbagi jaringan mesin tersebut pada sistem yang membuka dokumen di sana dengan cara itu, dan tidak menyebut apa pun yang dapat dibuka daemon di tempat lain. Alamat yang juga membawa query, fragmen, kredensial, atau port juga tidak menyebut apa pun yang dapat dibuka daemon. Nilai yang tidak diawali file://, apa pun huruf besar-kecilnya, tidak pernah dibaca sebagai alamat, dan penolakan file-tidak-tervalidasi menyebut nilai yang Anda kirim, dalam bentuk apa pun nilai itu. Di antara semuanya, aggrega/insertionPoint dan aggrega/connectionAtPosition adalah dua yang membaca dokumen dari disk ketika Anda tidak memegang salinannya, dan keduanya hanya menjawab untuk dokumen di dalam workspace: dokumen di luar root (sebagaimana ditulis, atau melalui tautan yang mengarah keluar darinya, ke file atau ke direktori di sepanjang jalan) ditolak dalam bentuk mana pun dari ketiganya yang menyebutnya, dan dokumen di dalam root dijawab dalam ketiga bentuk. Delapan lainnya tidak membaca apa pun dari disk pada path yang disebutnya (aggrega/validate mengambil byte dokumen dari content, dan sisanya menjawab dari apa yang telah divalidasi), sehingga mereka menjawab untuk dokumen di mana pun Anda memegangnya, di dalam workspace atau tidak, dan tidak ada tautan yang disebutnya yang diikuti untuk membaca file. Parameter yang menyebut dokumen yang Anda pilih dari luar workspace adalah kasus yang sama dengan alasan yang sama: source milik aggrega/import dibaca di tempat ia sebenarnya berada, seperti yang dinyatakan entrinya sendiri. Keduanya merupakan pengecualian terhadap batas workspace berdasarkan kelasnya (dokumen yang tetap dibuka klien, dan file yang dipilih seseorang) dan Batas workspace menjelaskan mengapa masing-masing merupakan pengecualian.
Parameter yang digunakan daemon untuk menemukan dokumen di dalam workspace menerima path relatif workspace dan tidak ada yang lain. release adalah yang perlu diketahui (pada aggrega/irGraph, dan dengan kontrak yang sama di mana pun ia muncul) dan nilai absolut ditolak dengan galat invalid-params, yang menyatakan kontraknya lalu menyebut kesalahan spesifiknya. Permintaan yang menulis di dalam workspace menerapkan kontrak yang sama pada tujuannya, seperti yang dinyatakan entri masing-masing. Setiap path seperti itu kemudian dinilai berdasarkan ke mana ia mengarah, dengan satu aturan baik permintaan membacanya maupun menulisnya (definisi bagian dalam yang dinyatakan Batas workspace) dan path yang mengarah keluar ditolak dengan galat milik permintaan itu sendiri, yang mengutip nilai sebagaimana Anda kirim, tanpa ada yang dibaca atau ditulis: baik tautan ke file di luar maupun tautan ke direktori di sepanjang jalan, serta path yang belum dibuat di bawah direktori bertaut yang mengarah keluar, yang ditolak karena tautannya alih-alih ditulis, atau dicari di luar dan dilaporkan hilang. Itu mencakup setiap path yang disebut permintaan untuk dibaca daemon (release di mana pun ia muncul, entity milik aggrega/lint, serta entity, plugin, file, dan from milik permintaan publikasi) sehingga permintaan tidak dapat membaca melalui tautan sebuah file yang tidak dicantumkan oleh daftar workspace itu sendiri, dan setiap tujuan: direktori tempat generasi, impor, dan build menulis, entitas yang di sebelahnya aggrega/pin menulis lock-nya, file entitas dan modul yang dibaca dan ditulis ulang oleh aggrega/pluginSync, serta dokumen yang diedit aggrega/editDocument. release yang menyebut Release yang disebut oleh konfigurasi workspace Anda adalah satu-satunya pengecualian, seperti yang dinyatakan entri aggrega/irGraph.
Keduanya berbeda karena kesalahannya berbeda. Parameter yang menyebut dokumen yang sudah Anda pegang hanya menyisakan satu pertanyaan, yaitu dokumen yang mana, sehingga mereduksi bentuk Anda ke bentuk kanonis tidak kehilangan apa pun, dan menerima setiap bentuk juga tidak merugikan Anda. Parameter yang memilih dokumen dari dalam workspace tidak berada dalam posisi itu: dalam pustaka path yang kemungkinan digunakan klien, menggabungkan nilai absolut ke sebuah root menghasilkan nilai absolut itu alih-alih galat. Jadi nilai yang diperbaiki diam-diam akan membuat daemon membaca (dan melaporkan temuan terhadap) path yang tidak pernah dimuat workspace, dan Anda akan diberi tahu tentang file yang tidak ada. Menolak adalah jawabannya, bukan memperbaiki, karena daemon yang memperbaiki nilai seperti itu akan membuat setiap klien yang mengirimnya percaya bahwa kontrak itu opsional.
Cara entitas dialamatkan
Setiap entitas yang disebut sebuah jawaban dialamatkan dengan cara yang sama: kind, name, dan file. Lakukan join pada ketiganya terhadap aggrega/catalogIndex untuk apa pun yang ingin Anda tampilkan: itulah permukaan yang membawa set deskriptif lengkap sebuah entitas (apiVersion, description, dan labels), sehingga jawaban yang hanya perlu menyebut entitas melaporkan tiga kunci pengalamatan dan menyerahkan deskripsi ke satu tempat. Pencarian berdasarkan nama seperti aggrega/entityDefinition mengulang beberapa field deskriptif yang menjadi pokok jawabannya sendiri; indeks tetap menjadi permukaan untuk join ketika Anda menginginkan set tersebut.
Jika sebuah jawaban dapat menyebut entitas dari lebih dari satu tempat, setiap identitas membawa origin di samping ketiga kunci tersebut. aggrega/catalogIndex dan aggrega/attachCandidates keduanya melakukannya, karena entitasnya berasal dari dokumen workspace dan dari direktori katalog yang dikonfigurasi. Jawaban yang hanya mengambil dari satu tempat hanya melaporkan tiga kunci dan tanpa origin, karena kunci yang hanya memiliki satu nilai yang mungkin tidak memberi tahu Anda apa pun: setiap entitas yang disebut jawaban seperti itu adalah dokumen workspace, dan file-nya adalah path relatif workspace yang dapat Anda buka. Jadi bacalah origin di tempat ia ada alih-alih mewajibkannya di mana-mana; tiga kunci itulah yang menjadi dasar join Anda dalam kedua kasus.
origin milik jawaban yang mendaftar entitas, tempat membedakan populasi adalah masalah pembaca. Jawaban berdasarkan nama seperti aggrega/entityDefinition tidak membawanya: jawaban itu menyebut satu entitas yang menjadi hasil resolve nama tersebut, sehingga tidak ada populasi yang perlu dipisahkan. Butir miliknya sendiri di atas menyatakan kapan file-nya kosong; jangan menafsirkan kekosongan itu melalui nilai origin di bawah, yang menggambarkan sebuah daftar.
origin menyatakan dari mana daemon membaca entitas tersebut, dan itulah yang membuat file dapat dibaca.
workspace— dokumen Aggrega di bawah root workspace.fileadalah path-nya relatif terhadap root itu, yang merupakan path yang dapat dibuka klien Anda.catalog— entitas yang di-resolve dari direktori katalog yang dikonfigurasi.filekosong pada daftar ini, dannameadalah alamat lengkapnya. Field itu kosong karena daftar tersebut melaporkan apa yang dienumerasi oleh pencarian katalog, yaitu sebuah identitas, bukan dokumen, sehingga entri tersebut tidak memiliki path untuk dilaporkan; ini bukan path yang ditahan karena lokasinya. Tanyakan nama yang sama kepadaaggrega/entityDefinitionketika Anda menginginkan dokumennya: permintaan itu me-resolve entitas dan melaporkanfile-nya sesuai aturan di atas, sehingga direktori katalog di luar root workspace disebut di sana dengan path absolutnya.nameadalah koordinat yang memang digunakan oleh Aggregate, Recipe, dan pencarian katalog.
Bacalah keduanya bersama-sama alih-alih hanya menguji file. file yang kosong saja tidak dapat memberi tahu Anda apakah entitas tidak memiliki path workspace atau apakah path-nya sekadar tidak dilaporkan; origin menjawabnya secara langsung.
Jika sebuah Feature dapat dijangkau dengan kedua cara (root workspace itu sendiri adalah salah satu direktori katalog yang dikonfigurasi, yang merupakan tata letak umum), Feature itu dilaporkan sekali, sebagai dokumen workspace, karena itulah salinan yang file-nya dapat Anda buka.
Yang disampaikan jawaban attach-candidate kepada Anda
aggrega/attachCandidates menjawab satu pertanyaan (Features mana yang diterima oleh set label ini) dan menawarkan tiga cara untuk menyatakan set label yang Anda maksud. Kirim tepat satu koordinat; mengirim dua, atau tidak sama sekali, ditolak alih-alih diberi peringkat.
{node} mengalamatkan dokumen workspace dengan metadata.name-nya dan tidak memerlukan hal lain. Pencocokan dievaluasi terhadap label yang dideklarasikan dokumen itu di metadata.labels, dan jawabannya melaporkan labelSource: "declared".
{graphNode, release} mengalamatkan node pada graf terkompilasi. graphNode adalah id yang digunakan graf sebagai kunci node tersebut, id yang sama yang Anda baca dari aggrega/irGraph, termasuk bentuk berkualifikasi yang dibawa node yang disumbangkan oleh sub-aggregate. release adalah path relatif terhadap root workspace yang menyebut Release yang grafnya akan dibangun, nilai yang sama yang diterima aggrega/irGraph. Pencocokan dievaluasi terhadap label final node tersebut, dan jawabannya melaporkan labelSource: "resolved".
{labels} membawa set label itu sendiri dan tidak mengalamatkan apa pun. Inilah bentuk yang mendasari dua lainnya: pencocokan adalah fungsi dari set label dan Features yang tersedia, sehingga klien yang sudah memegang set label tidak perlu menyebut apa pun dan tidak perlu menunggu apa pun. Kirim objek JSON berisi pasangan label; jawabannya melaporkan labelSource: "supplied" dan node yang kosong, karena permintaan ini tidak mengalamatkan node apa pun. Objek kosong adalah sebuah koordinat (menanyakan node tanpa label), sedangkan menghilangkan kunci sepenuhnya, atau mengirim null, tidak mengalamatkan apa pun dan ditolak.
Dua koordinat nama dipisahkan karena ruang pengenalnya tumpang-tindih. Id node graf dan metadata.name sebuah dokumen dapat berupa string yang sama sambil menyebut hal yang berbeda, sehingga satu parameter yang membawa keduanya akan ambigu, dan daemon yang menebak ruang mana yang Anda maksud kadang akan menjawab dengan yakin untuk subjek yang salah. Menyatakan pertanyaan mana yang Anda ajukan adalah yang menghilangkan ambiguitas tersebut.
labelSource memberi tahu Anda seberapa jauh jangkauan jawaban, dan ketiga nilainya tidak dapat saling menggantikan. declared adalah pencocokan atas apa yang dinyatakan sebuah dokumen tentang dirinya sendiri, yaitu apa yang dapat dilihat oleh pembacaan sumber. resolved adalah pencocokan atas label yang benar-benar dimiliki node pada akhirnya, yaitu yang menjadi dasar build mengevaluasi penerapan, sehingga jawaban resolved adalah pernyataan tentang apa yang akan diputuskan build, sedangkan jawaban declared bukan. supplied menyatakan bahwa daemon sama sekali tidak membaca label dan mencocokkan apa yang Anda kirim; seberapa kuat jawaban itu sepenuhnya bergantung pada asal set label Anda.
Itulah sebabnya klien yang memegang graf sebaiknya mengirim {labels} alih-alih nama. Label final sebuah node adalah label dari tipe komponen yang menjadi hasil resolve-nya, bukan label dokumen yang kebetulan berbagi id-nya, dan attachment label-transform kemudian dapat menambah, mengubah, atau menghapusnya, sehingga label yang menentukan penerapan sebuah node belum tentu label yang dideklarasikan oleh satu dokumen tertentu. Klien yang menggambar graf sudah memiliki set itu dari aggrega/irGraph; mengirimkannya kembali menghasilkan jawaban yang sama dengan yang diberikan koordinat {graphNode, release}, tanpa membangun ulang graf untuk mendapatkannya. Kirim kembali set yang dilaporkan oleh daemon sendiri (set milik node dari aggrega/irGraph, set milik entitas dari aggrega/catalogIndex) dan gambaran Anda tentang label sebuah node tidak dapat menyimpang dari gambaran daemon, karena set itu tidak pernah meninggalkan jawabannya sendiri. Jika Anda menyusunnya sendiri, Anda mengajukan pertanyaan hipotetis, yang dijawab dengan jujur dan bukan pernyataan tentang node mana pun yang dimuat workspace.
Kandidat berasal dari workspace dan dari katalog. Workspace yang menyimpan Features-nya di katalog alih-alih di pohonnya sendiri sama sekali tidak memiliki Feature lokal, dan kandidatnya seluruhnya origin: "catalog". Untuk node graf, keduanya dibaca menurut ketentuan Release milik node tersebut: Features katalog adalah yang dideklarasikan oleh direktori katalog yang diberikan konfigurasi workspace kepada Release itu, dan dokumen workspace sendiri ditawarkan kecuali yang berada di bawah direktori katalog yang hanya dibaca oleh Releases lain. Karena itu, workspace yang menyimpan satu varian sebuah Feature per Release menawarkan kepada graf setiap Release variannya sendiri dan tidak pernah varian milik Release lain, sedangkan Feature yang ditulis di samping katalog, di bawah direktori katalog mana pun tidak, ditawarkan untuk setiap Release. {node} dan {labels} tidak menyebut Release apa pun, sehingga keduanya mengambil dari setiap dokumen workspace dan dari catalog_dirs milik workspace itu sendiri. Feature yang sama sekali tidak mendeklarasikan penerapan adalah kandidat untuk setiap node (deklarasi yang tidak ada tidak menyatakan persyaratan apa pun), sedangkan Feature yang deklarasinya tidak dapat dibaca bukan kandidat untuk node mana pun, karena memperlakukan selektor yang tidak terbaca sebagai terpenuhi akan membiarkan salah ketik memperluas apa yang Anda tawarkan.
Nama yang tidak ter-resolve adalah galat, bukan daftar kosong. Kedua jawaban itu bermakna berbeda: array candidates yang kosong menyatakan bahwa node ini tidak memiliki apa pun yang dapat dilampirkan kepadanya, dan melaporkan nama yang salah ketik dengan cara itu akan menyajikan salah ketik sebagai jawaban yang pasti. Penolakan menyebut ruang yang dicarinya, sehingga Anda tahu apakah harus mencari dokumen workspace atau node graf. {labels} tidak memiliki risiko seperti itu (tidak ada nama yang bisa salah ketik), sehingga set label yang tidak diterima oleh apa pun kembali sebagai jawaban sukses yang membawa array kosong, dan permintaan yang tidak dapat dibaca daemon tetap ditolak sebelum pencocokan apa pun dijalankan.
Koordinat node graf memerlukan lockfile; dua lainnya tidak. Membangun graf berarti me-resolve apa yang dicapai Release, sehingga jalur itu menolak dengan galat lockfile tidak ada ketika belum ada lockfile yang dihasilkan, dengan menyebut perintah yang harus dijalankan, prasyarat yang sama yang dimiliki aggrega/irGraph, dengan alasan yang sama. Mengalamatkan dokumen workspace tidak membangun graf, dan memberikan set label sama sekali tidak membangun apa pun, sehingga keduanya menjawab pada workspace yang belum disiapkan siapa pun.
Metode ini melaporkan dan tidak pernah membuat. Metode ini tidak mengubah apa pun, tidak menulis apa pun, dan tidak membuat attachment. Menyusun dan menerapkan pengeditan apa pun adalah tugas editor, tempat buffer dan riwayat urungkan berada.
Apa yang di-resolve-nya bergantung pada koordinat, dan ketiganya tidak sama. {node} tidak me-resolve apa pun dan tidak menjangkau registry atau jaringan; kandidat berasal dari workspace dan dari direktori katalog, keduanya sudah ada di disk. {labels} me-resolve lebih sedikit lagi: ia tidak mencari apa pun, karena tidak ada yang perlu dicari. {graphNode, release} membangun graf Release, sehingga me-resolve closure dependensi Release itu dengan cara yang sama seperti aggrega/irGraph: pertama dari direktori katalog lokal dan cache artefak, lalu dari registry yang dikonfigurasi untuk entitas yang tidak dimuat oleh keduanya. Ketiganya menjawab secara offline untuk workspace yang semua entitasnya lokal; hanya koordinat node graf yang dapat mencari lebih jauh.
Bertanya tentang koneksi
Koneksi yang ditarik sebuah komponen dapat membawa attachment-nya sendiri, yang mengisi slot yang dideklarasikan socket-nya pada Component konsumen, misalnya kredensial yang diberikan komponen kepada apa pun yang dijangkau koneksi tersebut. Kirim connection di samping {graphNode, release} untuk menanyakan apa yang boleh ditempatkan di sana: socket adalah socket dependensi yang menjadi jalur koneksi tersebut dan alias adalah nama yang dibawanya di dalam socket itu, keduanya persis seperti yang ditulis penulis. Koneksi hanya ada pada graf terkompilasi, sehingga connection di samping node atau labels ditolak, demikian pula koneksi yang tidak menyebut socket atau alias, atau koneksi yang tidak ditarik oleh node tersebut.
Jawabannya adalah jawaban node graf ditambah slot koneksi. candidates mempertahankan maknanya (Features yang dapat dilampirkan ke node itu sendiri) dan slots ditambahkan, satu entri per slot yang dideklarasikan socket, dalam urutan Component mendeklarasikannya:
slot— nama yang digunakan untuk menulis attachment yang mengisinya di dalamfeatureskoneksi.selector,required,inject,sensitive, dandescription— slot persis seperti yang dideklarasikan Component pada socket, kosong atau false jika tidak mendeklarasikan apa pun.selectoradalah batasan yang digunakan untuk menyaring kandidat, sehingga Anda dapat menjelaskan sebuah kandidat, atau ketiadaannya, hanya dari jawaban.candidates— Features yang dapat mengisi slot ini pada koneksi ini. Build menerapkan dua aturan pada attachment seperti itu, dan keduanya diterapkan: penerapan yang dideklarasikan Feature terhadap label final node, yang berlaku untuk setiap attachment yang dibawa node, danselectorslot terhadap label milik Feature itu sendiri. Jadi kandidat sebuah slot selalu termasuk di antara kandidat node, disaring oleh selektor. Feature yang labelnya tidak dapat dievaluasi oleh selektor tidak ditawarkan, karena build menolaknya alih-alih menerimanya.
Jika tidak ada slot yang dapat diisi, slots adalah daftar kosong dan noSlotReason menyatakan alasannya. Bacalah alasannya alih-alih menganggap daftar kosong sebagai “tidak ada Feature yang cocok”: itu akan menjadi jawaban yang berbeda, dan alasan itulah yang membedakan keduanya:
feature-created-connection— sebuah Feature menarik koneksi tersebut, dari blok dependensinya sendiri. Attachment hanya ditulis pada koneksi yang ditarik oleh komponen atau Release, sehingga tidak ada yang ditempatkan di sini, apa pun yang dideklarasikan socket.ad-hoc-socket— socket tersebut tidak dideklarasikan oleh Component. Penulis menyebutnya, yang diperbolehkan, dan socket yang tidak dideklarasikan tidak mendeklarasikan slot.no-slot-declared— Component mendeklarasikan socket tanpa slot di dalamnya.
noSlotReason tidak ada di mana pun slot ada, dan slots serta noSlotReason keduanya tidak ada dalam jawaban atas permintaan yang tidak menyebut koneksi, sehingga permintaan yang tidak menyebut koneksi dijawab tanpa kedua field tersebut.
document diterima dan tidak mengubah apa pun di sini. Slot adalah milik socket dan kandidat adalah milik Features, sama saja dalam dokumen mana pun sebuah attachment ditulis; ke mana attachment itu ditempatkan adalah jawaban aggrega/attachmentContainer. Nilai selain aggregate atau release tetap ditolak, karena nilai yang diterima lalu diabaikan tampak bagi pengirimnya sebagai nilai yang dihormati.
Yang disampaikan jawaban connection-candidate kepada Anda
aggrega/connectionCandidates menjawab dua pertanyaan sekaligus, dan hanya salah satunya yang memiliki jawaban lengkap. Membaca jawaban sebagai satu daftar yang disaring membuat pertanyaan yang lain disalahpahami.
Setiap socket yang dilaporkan membawa targets (Components lokal workspace yang label terdeklarasinya memenuhi batasan label yang dideklarasikan socket itu atas apa yang dapat memenuhinya), ditambah selector yang menjadi dasar perhitungan target tersebut, flag required yang dideklarasikan socket, dan declaration. targets selalu berupa array, kosong alih-alih tidak ada, sehingga socket yang tidak dipenuhi apa pun tetap dilaporkan sebagai socket yang dideklarasikan entitas.
Paruh target bersifat lengkap. Himpunannya ditentukan dengan mengevaluasi batasan terdeklarasi socket terhadap label terdeklarasi kandidat, evaluasi yang sama yang dilakukan build, sehingga apa yang Anda tawarkan adalah apa yang diterima batasan yang sama selama build. Socket yang tidak mendeklarasikan batasan membiarkan targetnya tanpa batasan dan melaporkan setiap Component; itulah makna bahasa batasan untuk selektor kosong, bukan galat.
Paruh socket bersifat terbuka, dan declaration serta adHocSocketsAccepted adalah cara Anda mengetahuinya. Penulis Aggregate memiliki topologinya dan dapat menyambungkan socket yang tidak pernah dideklarasikan oleh entitas katalog komponen tersebut, sehingga socket yang dideklarasikan entitas adalah himpunan awal yang membantu dan bukan himpunan nama socket yang sah. Sajikan sebagai saran, bukan sebagai satu-satunya pilihan; pemilih yang hanya menawarkan socket terdeklarasi akan memberi tahu penulis bahwa kebebasannya lebih sempit daripada yang sebenarnya.
declarationbernilaideclaredketika entitas yang dialamatkan mencantumkan socket diusesSchema-nya, danad-hocketika tidak. Itu adalah dua nilai yang sama yang dibawa sebuah edge di graf IR, sehingga satu kosakata menjawab “dari mana socket ini berasal” di mana pun Anda menemui pertanyaan itu.adHocSocketsAcceptedmelaporkan apakah permukaan entitas yang dialamatkan menerima socket yang tidak dicantumkan deklarasinya sendiri. Nilainya tidak selalu benar: permukaan dependensi sebuah Component menerimanya, dan permukaan attachment sebuah Feature tidak, karena attachment berpartisipasi dalam topologi yang dideklarasikan Feature yang dilampirinya alih-alih menyusun topologinya sendiri. Socket ad hoc pada permukaan yang tidak menerimanya dilaporkan tanpa target, karena tidak ada koneksi melaluinya yang akan ter-build.
Menyebut socket dalam permintaan membatasi jawaban pada satu socket itu, dan itulah satu-satunya cara untuk bertanya tentang socket yang tidak dideklarasikan entitas; socket yang tidak dideklarasikan tidak muncul dalam deklarasi mana pun untuk dienumerasi. Hilangkan untuk mendapatkan setiap socket yang dideklarasikan entitas, dalam urutan penulisannya.
Yang dilaporkannya adalah pencocokan atas label terdeklarasi. Build mengevaluasi batasan socket terhadap label final node di ujung lain edge, dan itu adalah label dari tipe komponen yang menjadi hasil resolve node tersebut, setelah attachment label-transform mana pun ikut berperan, belum tentu label dokumen yang Anda sebut. Jadi jawaban positif di sini bukanlah janji tentang apa yang akan diputuskan build; ini adalah batas yang sama yang dimiliki aggrega/attachCandidates di bawah sumber label declared-nya.
Metode ini melaporkan dan tidak pernah membuat. Metode ini tidak me-resolve apa pun, tidak menjangkau registry atau jaringan, dan tidak menulis apa pun: ia tidak membuat edge dan tidak mengusulkan teks. Menyusun dan menerapkan pengeditan adalah tugas editor, tempat buffer dan riwayat urungkan berada.
Untuk identitas entitas di targets (kind, name, dan file), lakukan join terhadap aggrega/catalogIndex seperti yang dijelaskan di Cara entitas dialamatkan. Field deskriptif dilaporkan di sana dan sengaja tidak diulang di sini, sehingga jawaban ini tidak membawa salinan kedua yang bisa menjadi tidak selaras. Target adalah Components workspace, sehingga masing-masing memiliki file yang dapat Anda buka dan tidak ada yang membawa origin: jawaban ini mengambil dari satu tempat, dan join dilakukan pada tiga kunci.
Yang disampaikan jawaban attachment-container kepada Anda
aggrega/attachmentContainer berada di antara permintaan kandidat di atas dan titik penyisipan di bawah. Permintaan-permintaan itu menyatakan apa yang dapat dilampirkan ke sebuah node; yang ini menyatakan di kontainer mana attachment untuknya ditempatkan, dan di dokumen mana; yang berikutnya menyatakan di bagian mana dari byte dokumen itu teksnya ditempatkan.
Mintalah kontainernya alih-alih menyusunnya. Id sebuah node dan path subsistem yang melingkupinya sama-sama ditulis dengan titik di antara bagian-bagiannya, dan titik adalah karakter yang sah dalam nama yang diketik penulis, sehingga dari luar dokumen tidak ada cara untuk membedakan titik struktural dari titik di dalam nama. Klien yang menyusun path sendiri akan menghasilkan sesuatu yang terbaca benar dan mengalamatkan kunci yang tidak pernah ditulis siapa pun, dan pengeditan yang menyusul akan membuat kunci itu alih-alih ditolak. Compiler-lah yang menyusun kedua path tersebut, jadi compiler pula yang menguraikannya.
Id node sama sekali tidak membawa jejak subsistem yang melingkupinya. Komponen yang ditulis di dalam subsystems.billing.subsystems.payments dijadikan kunci di graf sebagai ledger, persis seperti komponen tingkat atas, sehingga tidak ada apa pun di dalam id yang dapat diolah klien, betapa pun cermatnya ia memecahnya.
Jawabannya terdiri atas tiga field.
nodemengulang node yang menjadi pokok jawaban, sehingga klien dengan beberapa permintaan yang masih tertunda memasangkan setiap jawaban dengan pertanyaannya tanpa menyimpan urutannya sendiri.fileadalah dokumen tempat node itu ditulis, relatif terhadap workspace. Field ini merupakan bagian dari jawaban, bukan sesuatu yang sudah Anda ketahui: node yang disumbangkan oleh modul yang diimpor ditulis di dokumen milik modul itu sendiri dengan nama yang diberikan modul tersebut, sehingga baik file maupun segmen terakhir kontainer berbeda dari apa pun yang disebut permintaan.containeradalah path struktural dari root dokumen itu, sebagai daftar segmen:["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Setiap tingkat subsistem yang melingkupi kembali berada di bawah kuncisubsystems, yang merupakan cara dokumen menuliskannya. Komponen yang ditulis penulis di tingkat atas justru menyebut["spec", "components", "checkout", "features"], karena cakupan tempat komponen seperti itu dikompilasi bukanlah cakupan yang dimuat oleh file mana pun.
Ini adalah daftar segmen dan tidak pernah string yang digabungkan, dan itulah inti dari bentuk ini. Path yang digabungkan harus dipecah lagi oleh siapa pun yang menerimanya, yang berarti ambiguitas di atas muncul kembali satu panggilan kemudian. Teruskan daftar itu tanpa diubah ke aggrega/insertionPoint sebagai container-nya.
Metode ini membaca struktur dan tidak pernah makna. Jawabannya diturunkan dari dokumen tempat node ditulis, cakupan tempat node berada, dan nama yang diketik penulis. Tidak ada yang dibaca dari nama sebuah komponen, tipe yang dibawanya, atau isi sebuah label.
Metode ini melaporkan dan tidak pernah menulis. Metode ini tidak mengubah apa pun dan tidak menulis apa pun ke dokumen mana pun. Ia tidak membuat attachment, tidak menyusun teks, dan tidak menerapkan pengeditan; ia tidak memutuskan apa yang dapat dilampirkan, yang merupakan tugas aggrega/attachCandidates.
Permintaan yang menyebut node yang tidak dimuat graf ditolak alih-alih dijawab. Id node adalah kunci milik graf itu sendiri (bacalah dari graf yang dikembalikan aggrega/irGraph) dan node yang disumbangkan oleh modul yang diimpor membawa id berkualifikasi. Node yang tidak memiliki dokumen tercatat di graf juga ditolak: tempat sebuah attachment ditempatkan adalah fakta tentang sebuah dokumen, sehingga node tanpa dokumen tidak memiliki jawaban, alih-alih memiliki jawaban kosong.
Metode ini memerlukan lockfile, dengan alasan yang sama seperti aggrega/irGraph: menyebut kontainer berarti membangun graf Release, dan graf yang dibangun dari byte yang tidak dijamin oleh apa pun akan dilaporkan persis seperti graf yang telah diperiksa.
Attachment pada koneksi
Kirim connection di samping {graphNode, release} (beserta socket, alias, dan document-nya) dan jawabannya menyebut kontainer features pada entri milik koneksi itu sendiri alih-alih entri node. document wajib di sini, karena kedua dokumen dapat memuat attachment pada koneksi yang ditarik Aggregate: developer menulisnya pada entri koneksi di Aggregate, operator pada entri per-edge Release untuk koneksi itu.
aggregatemenyebut entri koneksi di dokumen tempat node ditulis:["spec", "components", "gateway", "uses", "models", "gpt", "features"]untuk komponen tingkat atas, dengan setiap subsistem yang melingkupi ditulis tingkat demi tingkat seperti di atas. Koneksi yang ditarik Release tidak memiliki entri di Aggregate, sehingga ditolak di sana.releasemenyebut entri per-edge di bawah entri milik Release untuk node tersebut (["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]), baik Release sudah menulis entri per-edge itu maupun belum. Jika belum,aggrega/insertionPointmelaporkan kunci yang masih harus ditulis dimissingContainerKeys.filekemudian adalah dokumen Release. Release yang sama sekali tidak menulis entri untuk node tersebut ditolak: tempat node ditempatkan adalah hal yang harus ditulis operator, dan jawaban tidak memutuskannya.
Koneksi yang ditarik Feature ditolak di kedua dokumen, dengan alasan yang diberikan feature-created-connection di atas. Node, socket, dan alias dicocokkan persis seperti yang ditulis, dan koneksi yang tidak ditarik node ditolak alih-alih dijawab dengan sebuah path. Setiap properti lain di atas tetap berlaku: jawabannya adalah daftar segmen, membaca struktur dan tidak pernah makna, dan tidak menulis apa pun.
Yang disampaikan jawaban connection-at-position kepada Anda
aggrega/connectionAtPosition adalah langkah sebelum dua permintaan koneksi di atas, untuk klien yang memegang sebuah posisi di dokumen alih-alih node pada graf, misalnya kursor pada entri sebuah koneksi. Metode ini menjawab koneksi mana yang ditulis di sana, dalam koordinat yang diterima permintaan-permintaan itu, lalu berhenti.
Jawabannya adalah salah satu dari dua paruh, tidak pernah keduanya.
graphNodedanconnection— node yang komponennya menarik koneksi, dengan id yang digunakan graf terkompilasi sebagai kuncinya, dan koneksi dengansocketdanalias-nya, dengandocumentmenyebut dokumen tempat posisi dibaca:aggregateuntuk Aggregate atau modul yang diimpornya,releaseuntuk Release. TeruskangraphNode,releaseyang sama, danconnectionkeaggrega/attachCandidatesuntuk slot yang dideklarasikan socket koneksi, dan keaggrega/attachmentContaineruntuk tempat attachment padanya ditempatkan; kontainer yang disebutnya berada di dalam entri tempat posisi itu jatuh.noConnectionReason— mengapa tidak ada koneksi yang dilaporkan. Himpunannya tertutup:no-connection-entry— posisi tidak berada pada entri mana pun tempat attachment ditulis. Koneksi yang ditulis sebagai daftar target (db: [store]) dan koneksi yang ditarik oleh blok dependensi milik sebuah Feature tidak membawa entri seperti itu, sehingga posisi pada salah satunya juga mendapat jawaban ini.feature-created-connection— posisi berada pada entri Release untuk koneksi yang ditarik sebuah Feature, yang tidak membawa attachment dengan alasan yang diberikan jawaban slot di atas. Release menulis entri seperti itu ketika blok dependensi sebuah Feature menarik melalui socket yang juga dideklarasikan oleh Component konsumen; entri itu ter-build baik tidak mengonfigurasi apa pun maupun mengaturinfraper-edge koneksi.unknown-connection— posisi berada pada entri yang ditulis Release untuk koneksi yang tidak dimuat graf terkompilasi. Release yang ter-build dapat memuat entri seperti itu, misalnya entri di bawah alias yang tidak ditarik apa pun dan tidak mengonfigurasi apa pun (tanpatarget, tanpainfra, tanpafeatures), atau entri untuk komponen yang dimatikan oleh toggleactive:, yang koneksinya ikut keluar dari build bersamanya.
Entri mana yang dihitung. Di Aggregate, setiap koneksi yang ditarik komponen, pada entrinya di bawah alias koneksi di dokumen tempat komponen itu ditulis (untuk komponen yang disumbangkan modul yang diimpor, dokumen milik modul itu sendiri). Di Release, setiap entri per-edge yang ditulisnya, baik entri itu menarik koneksinya maupun mengonfigurasi koneksi yang ditarik Aggregate. Letak setiap entri adalah apa yang dicatat graf terkompilasi, sehingga apakah sebuah kunci merupakan koneksi tidak pernah disimpulkan dari namanya. Komponen yang dimatikan oleh toggle active: tidak ada di graf terkompilasi, sehingga entrinya sendiri di Aggregate menjawab no-connection-entry, sedangkan entri Release untuk salah satu koneksinya menjawab unknown-connection.
Posisi di mana pun di dalam sebuah entri berada di dalam entri itu. Entri membentang dari kunci aliasnya hingga baris terakhir yang diindentasi di bawahnya, sehingga posisi pada alias, pada target-nya, atau di dalam features-nya dijawab untuk koneksi itu, dan jika entri bersarang, entri terdalam yang berlaku. Posisi pada kunci milik socket itu sendiri, di atas alias yang ditulis di bawahnya, tidak berada di dalam satu pun alias tersebut, baik socket memuat satu alias maupun beberapa, demikian pula posisi di indentasi sebelum kunci alias.
Dokumen mana yang mana ditentukan oleh Release. File milik Release dibaca untuk entri yang ditulisnya; file lain mana pun dibaca untuk entri tempat graf mencatat komponen sebagai ditulis. Dokumen yang sama sekali tidak dibaca oleh graf Release menjawab no-connection-entry di setiap posisi.
Metode ini melaporkan dan tidak pernah menulis, dan membaca dokumen dengan cara yang sama seperti aggrega/insertionPoint: pertama dari salinan sesi dan jika tidak ada dari disk, di dalam workspace, dengan penolakan yang sama untuk dokumen yang berada di luarnya, tidak dapat dibaca, atau bukan YAML yang well-formed. Metode ini memerlukan lockfile, dengan alasan yang sama dengan aggrega/attachmentContainer, dan membangun graf tanpa me-render apa pun.
Apa yang disampaikan respons titik penyisipan kepada Anda
aggrega/insertionPoint adalah padanan dari dua permintaan kandidat di atas. Keduanya menyatakan apa yang boleh dilampirkan atau dihubungkan; yang ini menyatakan di mana teksnya ditempatkan dalam satu dokumen tertentu. Permintaan ini menjawab lalu berhenti di situ.
Anda menyebutkan kontainernya; daemon menemukannya. container adalah jalur struktural dari akar dokumen — ["spec", "components", "web", "features"] — dan merupakan pernyataan Anda tentang tempat entri jenis ini berada dalam dokumen jenis ini. Daemon tidak menurunkan jalur tersebut dari nama sebuah entitas, tipe yang dibawanya, atau makna yang tampak darinya. Daemon membaca byte yang ditulis penulis dan melaporkan segmen jalur mana yang sudah dimiliki dokumen ini, kolom tempat entri-entrinya berada, dan baris terakhir yang dicapai blok terdalamnya. Jadi, mengetahui kunci yang mana tetap menjadi urusan pemanggil, sedangkan mengetahui di mana entri kunci itu ditempatkan dalam berkas ini berasal dari sini.
Untuk lampiran Feature pada sebuah node dari graf yang telah dikompilasi, pemanggil tidak perlu mengetahui kunci itu sendiri: mintalah dokumen dan kontainernya kepada aggrega/attachmentContainer, lalu teruskan keduanya ke sini tanpa diubah.
Jawabannya adalah posisi selebar nol ditambah apa yang harus Anda tulis di sekitarnya. file adalah dokumennya, relatif terhadap workspace. container mengulang jalur yang Anda tanyakan, sehingga klien dengan beberapa permintaan yang belum terjawab dapat memasangkan setiap jawaban dengan pertanyaannya tanpa menyimpan urutannya sendiri. position menyisipkan, bukan menggantikan: tidak ada isi dokumen yang sudah ada yang ditimpa atau digeser.
precededByLineBreak— awali teks yang Anda tulis dengan jeda baris. Posisinya berada di akhir baris yang diikuti oleh entri baru, yang tetap valid baik berkas diakhiri baris baru maupun tidak, dan tidak mengubah byte apa pun yang sudah ditulis. Nilainya false hanya untuk dokumen yang tidak memuat apa pun untuk diikuti, dan dalam kasus itu penulisan dimulai dari awal berkas.missingContainerKeys— segmen jalur kontainer yang belum dimuat dokumen ini, dimulai dari yang terluar. Masing-masing harus ditulis sebagai kunci tersendiri sebelum entri dapat ditempatkan di dalam yang terdalam. Nilainya kosong jika seluruh jalur sudah ada.entryIndent— kolom tempat baris pertama entri itu sendiri dimulai, dihitung dalam spasi dari awal baris.indentStep— seberapa jauh lagi setiap tingkat penyarangan diindentasi.indentStepMeasured— apakah langkah tersebut diukur dari penyarangan dokumen ini sendiri. Jika nilainya false, dokumen tidak menunjukkan penyarangan yang dapat diukur dan langkahnya adalah nilai cadangan, sehingga klien yang lebih suka menerapkan nilainya sendiri tahu bahwa hal itu boleh dilakukan.entryShape—mappingatausequence, dibaca dari apa yang sudah dimuat kontainer, danunknownjika kontainer belum ada atau tidak memuat apa pun.unknownbukan kegagalan: dokumen belum menyatakan bentuk entri-entrinya, jadi pilihan itu ada pada Anda.
Menerapkannya. Tulis jeda baris jika precededByLineBreak disetel. Lalu satu baris untuk setiap entri missingContainerKeys, dimulai dari yang terluar, masing-masing berupa kunci yang diikuti titik dua — yang pertama diindentasi pada entryIndent dikurangi indentStep kali jumlah kunci yang hilang, dan setiap berikutnya indentStep lebih jauh. Lalu entri itu sendiri, diindentasi pada entryIndent. Jika missingContainerKeys kosong, entri tersebut adalah satu-satunya baris yang Anda tulis.
Baca missingContainerKeys meskipun Anda mengharapkan kontainernya sudah ada. Posisi yang diterapkan tanpa kunci-kunci yang harus mendahuluinya menghasilkan dokumen yang tidak dapat diurai lagi, dan itulah satu-satunya kegagalan yang tidak boleh dibaca sebagai tidak ada dari jawaban ini.
position dihitung dari nol, berbeda dengan posisi pada diagnostik. line dan character sama-sama berbasis 0, sesuai dengan nilai posisi berbentuk LSP yang digunakan ulang oleh protokol ini, sedangkan line dan column pada entri diagnostik berbasis 1 seperti yang dijelaskan di Apa yang dimuat entri diagnostik. Klien yang mengisi satu antarmuka dari antarmuka lainnya melakukan konversi di antara keduanya.
positionEncoding menyebutkan satuan yang digunakan untuk mengukur character, dan merupakan encoding yang dinegosiasikan saat handshake. Nilai ini dilaporkan dalam jawaban alih-alih dibiarkan implisit karena posisi yang satuannya harus ditebak pemanggil adalah posisi yang tidak dapat diterapkannya: offset yang diukur dengan satu cara dan diterapkan ke buffer yang diukur dengan cara lain akan merusak dokumen pada karakter pertama di luar ASCII.
Permintaan yang tidak menunjuk tempat yang dapat ditempati sebuah entri ditolak, bukan dijawab. Setiap kasus berikut adalah keadaan permintaan, bukan keadaan workspace, sehingga dikembalikan dengan kode invalid-params standar dan percobaan ulang tidak mengubah apa pun sampai file atau container berubah.
- Dokumen tidak disebutkan, tidak berada di dalam workspace, tidak dapat dibaca, atau bukan YAML yang tersusun dengan benar — dokumen tanpa struktur tidak memiliki posisi untuk dilaporkan.
- Jalur kontainer tidak menunjuk apa pun: jalur itu tidak memiliki segmen, atau salah satu segmennya kosong.
- Jalur melewati nilai yang dimuat dokumen sebagai skalar. Tidak ada yang dapat ditambahkan di dalam skalar, dan menggantinya berarti menulis ulang, bukan menyisipkan.
- Jalur mencapai koleksi yang ditulis penulis dalam gaya flow. Menambahkan entri ke koleksi itu berarti menulis ulang byte yang sudah ditulis penulis alih-alih menambahkan baris, dan itu adalah suntingan, bukan posisi.
- Jalur menunjuk sequence blok dengan sesuatu yang bukan salah satu indeksnya. Entri sebuah sequence ditunjuk berdasarkan posisi, sehingga sebuah nama tidak mencapai apa pun di dalamnya dan tidak ada entri yang dapat dibuat untuk membawa nama itu.
Permintaan ini membaca buffer yang dipegang editor, bukan hanya berkas di disk. Cache penguraian daemon diperiksa terlebih dahulu, sehingga posisi dilaporkan terhadap konten yang belum disimpan jika ada, dan terhadap berkas itu sendiri jika cache tidak memuat apa pun untuknya.
Permintaan ini melaporkan dan tidak pernah menulis. Metode ini tidak mengubah apa pun, tidak meresolusi apa pun, tidak menghubungi registry atau jaringan, dan tidak menulis apa pun ke dokumen mana pun. Metode ini tidak menyusun teks sebuah entri dan tidak menerapkannya. Menyusun dan menerapkan suntingan adalah tugas editor, tempat buffer dan riwayat urungkan berada.
Apa yang disampaikan respons penyuntingan dokumen kepada Anda
aggrega/editDocument adalah separuh lain dari pasangan di atas: keduanya menyatakan di mana sebuah entri ditempatkan dan menyerahkan penyusunan serta penerapannya kepada Anda; yang ini menyusun dan menerapkan satu entri, dan menulis. Keduanya tetap tersedia, karena klien yang memegang buffer yang belum disimpan dan klien yang menyunting isi disk menginginkan separuh yang berbeda — editor dengan riwayat urungkannya sendiri menempatkan teks sendiri, sedangkan klien yang lebih suka berkasnya disunting daripada diberi tahu di mana harus menyunting mengirim permintaan ini.
Satu panggilan menerapkan satu suntingan, dan himpunan suntingan bersifat tertutup. edit menyebutkan yang mana: add-component menambahkan instans komponen di bawah kontainer komponen, attach-feature melampirkan Feature ke sebuah node, wire-edge menyambungkan koneksi di dalam salah satu soket dependensi sebuah node, dan set-value menyetel satu nilai pada sebuah node. Tidak ada suntingan yang menghapus, mengganti blok yang sudah Anda tulis, mengubah urutan apa pun, atau menulis apa adanya byte yang Anda berikan — jadi ini bukan penulis berkas dengan nama yang lebih sempit, dan nilai di luar keempatnya ditolak alih-alih ditafsirkan. Penolakan tersebut mencantumkan apa saja yang boleh Anda sebutkan.
Anda menyebutkan node sebagai jalur struktural, persis seperti yang diterima dua permintaan di atas. node adalah jejak dari akar dokumen — ["spec", "components", "web"] — dan kontainer tempat entri ditempatkan ditentukan oleh edit. Untuk add-component, jalur menunjuk kontainer komponen itu sendiri, karena entri yang ditambahkan adalah node tersebut. name adalah kunci tempat entri ditulis: nama instans, nama lampiran, alias koneksi, atau kunci nilai. value adalah isi entri tersebut, dan maknanya ditentukan oleh edit — entitas yang diminta entri, node yang dituju sebuah koneksi, atau skalar yang menjadi nilai yang disetel. socket dibaca untuk wire-edge dan diabaikan untuk yang lain.
Jalur alih-alih nama, dengan alasan yang sama seperti permintaan penentuan lokasi menerimanya: sebuah nama harus dicari, dan nama yang muncul di dua tingkat akan membuat kompilator memutuskan mana yang Anda maksud. Jadi klien yang tahu node mana yang sedang disuntingnya menyatakannya, dan klien yang tidak tahu menyadari bahwa ada pertanyaan yang harus dijawab sebelum menyunting apa pun.
Setiap byte yang tidak disentuh suntingan tetap utuh. Dokumen diurai hanya untuk menemukan kontainer dan baris tempat bloknya berakhir; entri dirender dan disisipkan pada tingkat baris. Komentar, baris kosong, gaya kutipan, skalar folded dan literal, ekspresi template, serta bentuk baris baru di akhir semuanya dipertahankan tanpa perubahan, dan langkah penyarangan diukur dari indentasi dokumen itu sendiri alih-alih dipaksakan — sehingga entri muncul dalam gaya yang sudah Anda gunakan. Permintaan yang sama terhadap dokumen yang sama menghasilkan byte yang sama, sehingga klien dapat membandingkan dua eksekusi dan peninjauan membaca satu suntingan sebagai satu diff.
Hasilnya harus berupa dokumen yang sebenarnya bisa Anda ketik sendiri, dan penulisan bergantung pada hal itu. Dokumen yang disusun divalidasi terhadap skema jenisnya sendiri dan hanya mencapai disk jika lolos. Permintaan yang akan menghasilkan sesuatu yang ditolak skema penulisan dikembalikan sebagai E0275 — the edit was refused because the resulting document would not be valid, and nothing was written (suntingan ditolak karena dokumen yang dihasilkan tidak akan valid, dan tidak ada yang ditulis) — dengan membawa properti yang tidak akan diterima skema beserta letaknya. Berkas dibiarkan sama persis byte demi byte seperti semula, sehingga suntingan yang ditolak tidak dapat dibedakan dari suntingan yang tidak pernah dicoba dan Anda dapat mencoba ulang permintaan yang sudah diperbaiki terhadap dokumen awal Anda. Itu juga sebabnya tidak ada aturan yang diulang di sini: permintaan agar dokumen Release memuat nilai developer ditolak oleh skema yang sama yang akan menolak dokumen yang diketik secara manual.
Apa yang dapat diterima secara semantis tidak diputuskan di sini. Apakah sebuah soket dependensi merupakan soket yang dideklarasikan produsen, atau apakah kelayakan penerapan sebuah Feature terpenuhi, menjadi bagian dari resolusi yang dilakukan build, masing-masing dengan pelaporannya sendiri. Jadi Anda boleh menyebutkan koneksi yang belum pernah dikenal permintaan ini, dan sebuah Aggregate boleh menulis soket yang tidak dideklarasikan sebelumnya oleh entitas katalognya; apa yang boleh dikonsumsi melalui sebuah soket tetap menjadi hak produsen untuk mendeklarasikannya. Jalankan aggrega/validate dengan menyebutkan sebuah Release, atau minta grafnya, jika itu pertanyaannya.
Jawaban menyebutkan apa yang ditempatkan dan apa yang mencapai disk, dan keduanya pertanyaan yang berbeda. content memuat dokumen yang dihasilkan suntingan dalam kedua mode pengiriman. written menyebutkan berkas yang mencapai disk, dan kosong dalam dryRun. container adalah jalur struktural kontainer tempat entri ditempatkan, sehingga Anda dapat menemukan apa yang baru saja Anda tambahkan tanpa menurunkan ulang aturan itu. createdContainers menyebutkan segmen-segmen yang ditulis suntingan ini karena dokumen belum memuatnya, dimulai dari yang terluar — kosong dalam kasus biasa ketika seluruh jalur sudah ada, dan dengan membacanya Anda dapat membedakan entri yang ditambahkan di dalam blok yang sudah ada dari entri yang membuat bloknya sendiri. file dan edit mengulang apa yang Anda kirim, sehingga klien dengan beberapa permintaan yang belum terjawab dapat memasangkan setiap jawaban dengan pertanyaannya. written, container, dan createdContainers selalu berupa array, kosong alih-alih tidak ada.
Dalam dryRun tidak ada yang dibuat. written kosong, content memuat dokumen yang akan dihasilkan oleh penulisan, dan berkas tidak disentuh — sehingga editor dapat menyajikan hasilnya kepada penulis untuk disimpan, diubah, atau dibuang. Perilaku bawaannya adalah menulis, karena produk operasi ini adalah dokumen yang disunting dan antarmuka yang menghasilkannya wajib menyerahkannya: permintaan yang tidak menyatakan apa pun tentang pengiriman akan menyunting berkas.
Semua hal lain yang dilakukan penulisan juga dilakukan dry run. Dokumen yang disusun divalidasi terhadap skema jenisnya sendiri dalam kedua kasus, sehingga suntingan yang akan ditolak penulisan juga ditolak dalam dryRun, dengan menyebutkan properti yang sama — artinya galat yang Anda dapatkan dari dry run adalah galat yang akan diberikan penulisan kepada Anda.
Entri yang sudah ada dan memuat apa yang Anda minta adalah no-op — dokumen dikembalikan tanpa perubahan dan tidak ada yang ditulis. Entri dengan nama itu yang memuat hal lain ditolak alih-alih diganti, karena mengganti apa yang ditulis penulis bukan salah satu dari keempat suntingan.
Setelah penulisan, daemon membaca ulang dokumen. Apa yang dipegangnya untuk berkas itu dibuang dan tampilan tingkat workspace-nya disetel ulang, sehingga permintaan validasi, hover, pelengkapan, atau graf berikutnya dijawab dari byte yang dihasilkan suntingan, bukan dari versi yang digantikannya. Suntingan itu sendiri membaca berkas di disk, bukan buffer yang Anda pegang — berbeda dengan permintaan penentuan lokasi di atas, yang memeriksa konten yang belum disimpan terlebih dahulu. Hal ini disengaja: menulis dari buffer yang belum disimpan akan menempatkan konten yang belum disimpan penulis ke halaman dengan dalih menerapkan satu entri. Simpan buffer, lalu sunting.
Permintaan yang tidak menunjuk tempat yang dapat ditempati sebuah entri ditolak, bukan dijawab, dengan kode invalid-params standar, dan percobaan ulang tidak mengubah apa pun sampai permintaannya berubah. Dokumen tidak disebutkan, tidak berada di dalam workspace, tidak dapat dibaca, bukan YAML yang tersusun dengan benar, atau tidak mendeklarasikan jenis apa pun yang skemanya dapat digunakan untuk memeriksa hasilnya; edit tidak disebutkan atau bukan salah satu dari keempatnya; node tidak menunjuk apa pun, atau salah satu segmennya kosong; tidak ada name yang diberikan; wire-edge tidak menyebutkan socket; set-value diberi mapping atau sequence di tempat yang seharusnya skalar; jalur node mencapai skalar atau sequence, atau koleksi yang ditulis dalam gaya flow, di mana menambahkan baris akan menulis ulang byte yang sudah ada di halaman; atau jalur node tidak mencapai apa pun dalam dokumen.
Permintaan ini tidak meresolusi dependensi apa pun, tidak menghubungi registry, dan tidak menyentuh jaringan dalam kedua mode pengiriman.
Cakupan respons konfigurasi efektif
aggrega/effectiveConfiguration menjawab dua pertanyaan: konfigurasi apa yang berlaku dalam sesi ini, dan lapisan mana yang menentukan setiap pengaturan. Ini adalah jawaban yang sama dengan yang dicetak aggrega config show --origin, dihitung sekali dan dilaporkan di kedua antarmuka, sehingga keduanya tidak mungkin berbeda pendapat tentang asal sebuah pengaturan.
Sebuah source memiliki salah satu dari empat bentuk. Jalur absolut sebuah berkas konfigurasi — termasuk berkas global yang dibaca daemon yang dijalankan sebagai aggrega --config <file> serve, disebutkan dengan jalur yang diberikan kepadanya; variabel lingkungan di balik prefiks env:, seperti env:AGGREGA_SIGNING_REQUIRED; flag global yang diketik pada baris perintah yang menjalankan daemon, disebutkan sebagai flag tersebut, seperti --offline untuk daemon yang dijalankan sebagai aggrega --offline serve; atau (built-in defaults) untuk pengaturan yang tidak disetel lapisan mana pun. Tiga yang pertama muncul apa adanya di layers. Nilai bawaan tidak, karena nilai bawaan bukan lapisan yang berkontribusi — nilai bawaan adalah apa yang berlaku ketika tidak ada lapisan yang menentukan.
Sebuah pengaturan diatribusikan ke lapisan berprioritas tertinggi yang menyetelnya, apa pun nilai yang ditulis lapisan itu. Berkas konfigurasi yang menulis nilai bawaan yang tertanam, atau mengulang nilai yang sudah disetel berkas di bawahnya, adalah berkas yang disebutkan: berkas itulah yang menahan nilai tersebut. Sebuah berkas menyetel pengaturan dengan memuat kuncinya, termasuk pendamping _append sebuah daftar, dan variabel lingkungan dengan diekspor bersama nilai yang tidak kosong. Berkas konfigurasi milik pipeline Anda tidak pernah disebutkan untuk kunci yang diabaikannya. aggrega config show --origin melaporkan dengan aturan yang sama.
Setiap pengaturan yang dideklarasikan skema konfigurasi diperhitungkan, meskipun tidak masing-masing dengan barisnya sendiri. Pendamping aditif _append sebuah daftar dilaporkan pada baris daftar yang ditambahinya, sehingga lapisan yang berkontribusi hanya melalui pendamping itu disebutkan pada baris daftar tersebut dan pendampingnya tidak memiliki baris. Pengaturan di dalam entri-entri sebuah daftar — kebijakan kepercayaan sebuah registry, input lampiran sebuah plugin — tercakup oleh baris daftar itu.
Dua batasan lagi, yang masing-masing membuat jawaban lebih kasar daripada kelihatannya.
- Pengaturan berupa daftar atau map diatribusikan secara keseluruhan, ke lapisan berprioritas tertinggi yang menyetelnya. Atribusi per entri tidak dilacak, sehingga daftar yang disusun dari dua lapisan hanya melaporkan lapisan yang berprioritas lebih tinggi, dan entri yang disumbangkan lapisan yang lebih rendah tidak dapat dibedakan dari entri yang ditulis lapisan yang lebih tinggi.
- Persyaratan penandatanganan diatribusikan ke lapisan pertama yang mengaktifkannya, bukan lapisan terakhir yang menyebutkannya. Pengaturan itu digabungkan sedemikian rupa sehingga lapisan mana pun yang mengaktifkannya menang dan tidak ada lapisan berikutnya yang dapat menonaktifkannya, sehingga lapisan pertama yang mengaktifkannya adalah lapisan yang membuat nilai efektifnya seperti sekarang. Lapisan yang menulis
required: falsetidak mengaktifkan apa pun, sehingga jika setiap lapisan yang menyebutkannya menulisfalse, pengaturan tersebut melaporkan(built-in defaults).
Setiap nilai yang dilaporkan adalah resolusi yang diambil ketika workspace itu pertama kali disebutkan. Menyunting berkas konfigurasi tidak mengubah nilai di sini; memulai ulang daemon akan mengubahnya. Hal ini disengaja — nilai-nilai tersebut adalah konfigurasi yang digunakan untuk menjawab setiap permintaan lain tentang workspace itu, dan itulah yang membuatnya dapat dibandingkan dengan akar dan lapisan konfigurasi yang dilaporkan handshake untuknya. Klien yang menampilkan konfigurasi di samping berkas yang sedang disunting pengguna sebaiknya menyatakan mana dari keduanya yang sedang ditampilkannya.
Atribusi lapisan dihitung saat Anda bertanya, berdasarkan berkas sebagaimana adanya. Jadi berkas konfigurasi yang disunting setelahnya dapat memindahkan sebuah source sementara nilai di sampingnya tetap seperti saat diresolusi. Kedua bagian itu menjawab pertanyaan yang berbeda — apa yang berlaku, dan lapisan mana yang menentukannya — dan hanya yang pertama yang tetap. Mulai ulang daemon untuk menyelaraskannya kembali.
Permintaan ini melaporkan dan tidak pernah menulis. Metode ini tidak mengubah konfigurasi apa pun, tidak membuat berkas, dan tidak meresolusi apa pun dari registry atau jaringan.
Isi berkas satu lapisan tidak disajikan di sini. Baris perintah dapat mencetak byte milik satu lapisan apa adanya, dengan komentar dan format dipertahankan; metode ini melaporkan resolusinya alih-alih byte-nya. Klien yang menginginkan teks sebuah lapisan memiliki jalurnya di layers dan dapat membukanya.
Apa yang ditinggalkan penulisan konfigurasi
aggrega/configInit dan aggrega/configCapture sama-sama menghasilkan dokumen konfigurasi, dan keduanya menuliskannya. Jawaban menyebutkan berkasnya; membukanya adalah langkah Anda berikutnya, bukan pengganti penulisan. Tidak satu pun dari keduanya memberikan konten untuk Anda tempatkan sendiri kecuali Anda memintanya secara tegas, karena kapabilitas yang produknya berupa dokumen yang tidak pernah ditulis adalah kapabilitas lain dengan nama yang sama.
Keduanya berbeda dalam jangkauannya, dan setiap jawaban menyatakan yang mana. Bacalah sebelum Anda menampilkan hasilnya.
- Inisialisasi secara bawaan menulis konfigurasi yang dibagikan ke semua workspace di mesin. Sebuah registry dan identitas yang Anda percayai di dalamnya biasanya sama di mana pun Anda bekerja, jadi ke sanalah entri ditempatkan kecuali permintaan mengirim
workspace: true.scopememuatconfigFileyang ditulis danmachineWideyang menyatakan apakah itu berkas bersama — diturunkan dari berkas tujuan resolusi penulisan, bukan dari apa yang diminta permintaan, sehingga jawaban tidak dapat menggambarkan perubahan di seluruh mesin sebagai perubahan lokal. - Pembekuan tidak pernah menjangkau melampaui workspace. Pembekuan tidak menerima target penulisan maupun penimpaan: seluruh tujuannya adalah membuat satu proyek mandiri, sehingga selalu menulis
.aggrega-config.yamlmilik proyek itu sendiri. Itulah sebabnya jawabannya memuatconfigFiledanworkspaceRootdan tidak mengklaim cakupan apa pun — tidak ada jangkauan yang perlu dinyatakan.
Inisialisasi menolak alih-alih menimpa. Berkas konfigurasi yang sudah ada dibiarkan tidak tersentuh dan penolakan menyebutkannya, karena inisialisasi ditujukan untuk konfigurasi yang belum ada, sedangkan penulisan bersama yang menjadi tempat delegasinya memang dirancang untuk menggabungkan. Kirim force untuk tetap menulis; entri registry digabungkan ke apa yang sudah ada dan pengaturan lainnya dipertahankan. Permintaan yang ditolak sama sekali tidak mengubah apa pun.
trust menyatakan apa hasil dari kebijakan yang diumumkan registry, sebagai hasil-hasil terpisah alih-alih sebagai prosa. pinned berarti registry mengumumkan sebuah kebijakan dan kebijakan itu diambil, dengan identities menghitung identitasnya. notAdvertised berarti registry ditanya dan tidak mengumumkan kebijakan apa pun, yang bukan kegagalan — inisialisasi berlanjut, dan reason menyatakan apa yang dilakukan endpoint. Registry yang tidak dapat dijangkau juga dilaporkan demikian, karena tidak ada kebijakan yang kembali dan inisialisasi tetap berlanjut, serta membawa unreachable di sampingnya jika kegagalan itu sendiri menunjukkan bahwa registry tidak pernah dijangkau: namanya tidak dapat diresolusi, koneksi ke registry itu ditolak atau tidak dapat dibuka, atau koneksi aman ke registry itu tidak dapat dibangun. Registry yang menjawab — dengan not-found, atau dengan status galat — tidak pernah membawa unreachable, jadi bacalah kunci itu alih-alih kata-kata dalam reason untuk membedakan registry yang tidak menerbitkan kebijakan dari registry yang tidak pernah ditanya. baseline berarti baseline bawaan hub resmi disematkan karena tidak ada kebijakan yang diumumkan yang diambil, dengan reason menyatakan alasannya; entri tersebut membawa kebijakan, jadi tidak ada yang perlu disematkan secara manual. Kedua kunci menjawab pertanyaan yang berbeda, sehingga hub yang ditanya dan tidak mengumumkan apa pun membawa keduanya, dan hub dalam workspace luring — yang tidak pernah ditanya — hanya membawa baseline, dengan reason menyatakan bahwa workspace sedang luring. Registry lain yang tidak mengumumkan apa pun hanya membawa notAdvertised, diinisialisasi tanpa kebijakan, dan saran yang menyertainya adalah menyematkan identitas secara manual; dalam keadaan luring, permintaannya ditolak alih-alih dijawab. skipped berarti tidak ada pengambilan yang dicoba. Klien yang memperlakukan apa pun selain pinned sebagai galat akan melaporkan konfigurasi yang berfungsi sebagai rusak.
Dalam dryRun tidak ada yang dibuat. written bernilai false, content memuat dokumen yang akan dihasilkan oleh penulisan, dan berkas tujuan konten itu adalah scope.configFile. Tidak ada direktori yang dibuat dan tidak ada berkas yang disentuh, sehingga editor dapat menyajikan teksnya kepada penulis dan membiarkannya menyimpan, mengubah, atau membuangnya.
Dry run berbeda dari penulisan hanya dalam satu hal — dry run tidak menulis — sehingga setiap penolakan yang dilakukan penulisan juga dilakukannya. Penolakan karena berkas sudah ada adalah yang penting di sini: dryRun atas berkas konfigurasi yang sudah ada ditolak, dengan menyebutkan berkasnya, persis seperti penulisan. Itulah yang membuat respons ini dapat digunakan sebagai predikat — jika dry run menolak, penulisan juga akan menolak, dengan alasan yang sama dan pesan yang sama. Kirim force bersama dryRun untuk mendapatkan jawaban berupa hasil penggabungan yang akan dihasilkan oleh penulisan yang menimpa, tetap tanpa menulis apa pun. Registry dihubungi untuk kebijakan kepercayaan yang diumumkannya dalam kedua mode pengiriman, karena kebijakan dalam konten tersebut adalah kebijakan yang akan disematkan oleh penulisan.
Apa yang dilaporkan pembekuan adalah apa yang ditulisnya, bukan deskripsinya. sockets mencantumkan setiap soket plugin yang dibekukan beserta lampiran yang dibekukan di sana; catalogDirs memuat direktori katalog. Keduanya selalu berupa array, kosong alih-alih tidak ada.
socketdanfieldbukan string yang sama, dan perbedaannya bukan sekadar kosmetik.socketmenyebutkan soket tempat lampiran-lampiran terikat;fieldadalah kunci tempat lampiran-lampiran itu ditulis dalam berkas. Keduanya hanya berbeda untuk soket provider, yang ditulis di bawah kunci berbentuk jamak — jadi gunakanfieldsaat Anda mengarahkan pembaca ke sebuah baris dalam dokumen dansocketsaat Anda menyebutkan soket itu sendiri.- Setiap lampiran membawa
uri,capability,function, danrole, yang hanya ada jika lampiran tersebut memilikinya. Semuanya menyebutkan lampiran alih-alih mereproduksinya secara utuh: input opsional sebuah lampiran yang diberikan saat pelampiran dibekukan ke dalam berkas apa adanya dan tidak diulang dalam jawaban. Berkas itulah salinan yang otoritatif. captured: falseadalah keberhasilan. Proyek yang konfigurasinya tidak berperan dalam build tidak memiliki apa pun yang penting bagi build untuk dibekukan, sehingga berkas dibiarkan apa adanya dan kedua daftar dikembalikan kosong. Memperlakukannya sebagai galat berarti melaporkan workspace yang sehat sebagai rusak.
Secara bawaan, hanya hal yang menentukan byte keluaran yang dibekukan — binding provider, dan lampiran governance yang mentransformasi label. Gerbang verdict governance dan linter serta soket impor dikecualikan, karena memang dimaksudkan untuk berbeda antarlingkungan dan membekukannya akan membawa gerbang satu lingkungan ke setiap checkout. allPlugins: true memperluas himpunan ke setiap soket plugin. Keanggotaan ditentukan per lampiran, bukan per soket, sehingga soket governance yang membawa satu lampiran transformasi label dan satu lampiran verdict hanya menyumbangkan yang pertama secara bawaan.
Setiap nilai dibekukan pada nilai efektifnya — hasil gabungan konfigurasi mesin dan konfigurasi proyek itu sendiri — sehingga binding yang saat ini hanya berasal dari konfigurasi mesin ditulis ke dalam proyek dan ikut terbawa bersamanya. Pengaturan perkakas tingkat mesin, termasuk kebijakan kepercayaan sebuah registry, tidak penting bagi build dan tetap berada di tempatnya. Membekukan dua kali atas konfigurasi yang tidak berubah menulis ulang byte yang sama, sehingga klien dapat menawarkannya dengan bebas: panggilan kedua membiarkan dokumen yang sedang dibuka pembaca persis seperti semula.
Apa yang disampaikan perubahan plugin kepada Anda
Keempat permintaan plugin semuanya menulis secara bawaan, dan terbagi menurut apa yang ditulisnya: dua mengubah berkas konfigurasi, dan dua menghasilkan dokumen di workspace. Dua di antaranya — penambahan dan pembuatan — menerima dryRun, yang melakukan semua hal lain yang dilakukan permintaan tanpa menulis apa pun. Bacalah keterangan jawaban itu sendiri tentang di mana perubahan ditempatkan alih-alih menyimpulkannya dari permintaan — untuk salah satunya, permintaan yang tidak menyatakan apa pun tentang cakupan berarti jangkauan terluas.
Penambahan dan penghapusan sama-sama membawa scope, yang diturunkan dari berkas tujuan resolusi penulisan. configFile adalah berkas itu, machineWide menyatakan apakah itu berkas yang menjadi jalur resolusi setiap workspace di mesin ini, dan workspaceRoot menyebutkan workspace tempat sesi ini dibuka, sehingga jawaban bercakupan workspace menyatakan workspace mana yang dimaksud. machineWide dibaca dari berkas hasil resolusi, bukan dari apa yang diminta permintaan, dan itulah yang mencegah jawaban menggambarkan perubahan di seluruh mesin sebagai perubahan lokal.
🔴 Penambahan bertipe cli yang tidak menyebutkan global maupun workspace mendaftarkan perintah di seluruh mesin. Ekstensi perintah adalah perkakas tingkat mesin, sehingga tanpa penimpaan ia ditulis ke berkas konfigurasi global yang menjadi jalur resolusi setiap workspace di mesin ini — dan perintah yang didaftarkannya kemudian menjadi perintah aggrega tingkat atas untuk setiap proyek di mesin itu, termasuk proyek yang tidak pernah disebutkan siapa pun dalam sesi ini. Penambahan provider, governance, linter, atau importer berlaku sebaliknya: semuanya membentuk build satu proyek, sehingga tanpa penimpaan ditempatkan di .aggrega-config.yaml milik proyek itu sendiri. Penghapusan mengikuti aturan yang sama untuk tipe yang sama. Kirim workspace: true untuk menjaga ekstensi perintah tetap lokal, atau global: true untuk memindahkan salah satu tipe lainnya ke berkas bersama; mengirim keduanya akan ditolak. scope pada jawaban dalam hal apa pun adalah pernyataan yang otoritatif, dan klien sebaiknya menampilkannya sebelum bertindak berdasarkan hasilnya.
Penambahan menyebutkan apa yang ditempatkan, dan tepat satu dari tiga field menyatakan jenis hal apa itu. type mengulang tipe yang menjadi tujuan penambahan entri, lalu: identity memuat identitas entitas polos yang disematkan versinya untuk lampiran governance, linter, atau importer; uri memuat alamat artefak oci:// milik plugin, bersama capability yang kini dilayaninya, untuk binding provider; dan reference memuat referensi tersemat yang perintah-perintahnya didaftarkan untuk instalasi cli. Jadi pemanggil membaca jenis lampiran yang ditempatkan dari jawaban alih-alih menurunkannya ulang dari tipe yang dikirimnya. Penghapusan mengulang type dan query di samping scope-nya dan tidak ada yang lain — tidak ada lagi yang perlu dilaporkan tentang entri yang sudah tidak ada.
Penambahan juga membawa written dan, dalam dryRun, content. written adalah dasar percabangan klien: true menyebutkan berkas konfigurasi yang kini ada di disk dan dapat dibuka klien, dan dalam dryRun nilainya false dan content sebagai gantinya memuat dokumen konfigurasi yang akan dihasilkan oleh penulisan. Keduanya tidak pernah bermakna sekaligus, dan berkas tujuan content adalah scope.configFile, sehingga tidak ada bagian jawaban yang membawa salinan kedua jalur itu — hal yang penting di sini, karena berkas lampiran global adalah berkas yang menjadi jalur resolusi setiap workspace di mesin ini.
Plugin tanpa versi yang diterbitkan ditolak alih-alih dilampirkan tanpa versi tersemat. Penambahan meresolusi kueri ke satu plugin dan menyematkan versi terbitnya yang tertinggi, sehingga entri yang ditulisnya membawa sebuah versi. Plugin yang repositorinya tidak menerbitkan versi yang sesuai ditolak dengan menyebutkannya, dan versi yang telah ditarik oleh retraksi yang dipercayai workspace ini dilewati demi versi berikutnya yang lebih rendah.
Versi yang dinamai kueri tetap di-pin meskipun telah ditarik, dan withdrawn menyatakannya. query yang ditulis sebagai <name>:<version> mem-pin versi tersebut alih-alih yang terbaru — pada setiap tipe kecuali provider, yang di-bind hanya berdasarkan nama dan menolak versi — dan menamai versi adalah override-nya: jika retraksi yang dipercaya workspace ini telah menariknya, versi itu tetap di-pin, dan jawabannya memuat withdrawn: true — fakta yang dinyatakan aggrega plugin add sebagai baris retraction: di terminal. withdrawn tidak ada pada setiap jawaban lain, sehingga kehadirannya adalah keseluruhan sinyalnya — dan ketiadaannya bukan pernyataan bahwa versi tersebut tidak ditarik. Jika penanda penarikan dari versi yang dinamai tidak dapat dibaca, withdrawn tidak ada dan retraction memuat unscreened yang menyebutkan alasannya, sebagaimana pada penambahan tanpa versi yang dinamai yang mengalami kegagalan yang sama; penambahan tanpa versi yang dinamai justru melaporkan di retraction apa yang disimpulkan pemeriksaan penarikan tentang versi yang dipilihnya.
Penyelarasan melaporkan apakah ia mengubah sesuatu, dan field itulah yang menjadi dasar tindakan. changed membedakan penulisan dari penyelarasan yang mendapati catatannya sudah benar: berkas yang tidak berubah dibiarkan identik byte demi byte, sehingga klien yang memegang dokumen itu tidak perlu memuat ulang apa pun, dan menjalankan permintaan dua kali tidak melaporkan perubahan pada kali kedua. entity menyebutkan berkasnya, hostFunctions memuat himpunan turunan, dan commands memuat cerminannya sebagai nilai alih-alih sebagai baris yang dicetak terminal — setiap entri berupa name, description opsional, dan flags, setiap flag membawa name-nya serta shorthand, description, type, dan default yang opsional. Penulisannya atomik, sehingga klien yang membaca berkas itu selama penyelarasan berjalan tidak pernah melihat dokumen yang setengah jadi.
Pembuatan mengisi tepat satu separuh jawabannya, dan dryRun milik jawaban itu sendiri menyatakan yang mana. Secara bawaan, entitas ditulis dan notices memuat apa yang disampaikan pembuatan tentang penulisan yang dilakukannya. Dalam dryRun tidak ada yang dibuat atau diubah: documents memuat setiap entitas yang dihasilkan sebagai path tujuannya dan content-nya, sehingga klien dapat memasukkannya ke model dokumennya sendiri, tempat entitas itu terlihat sebelum disimpan dan dapat diubah atau dibuang. Kedua separuh tidak pernah terisi bersamaan, sehingga mode pengiriman mana yang dijalankan dapat dibaca dari respons alih-alih dari apa yang diminta.
Tempat permintaan plugin MENULIS selalu berada di dalam workspace yang disebutkan permintaan itu; apa yang DIBACANYA ditentukan per field. Tujuan absolut, tujuan yang naik keluar dari akar, dan tujuan yang keluar darinya melalui tautan ditolak alih-alih diresolusi — sehingga pembuatan tidak dapat membuat entitas di pohon yang tidak pernah menjadi tempat sesi Anda dibuka, apa pun yang dikirimnya. Jalur yang hanya dibaca oleh sebuah permintaan adalah pertanyaan tersendiri, yang dijawab field demi field alih-alih dengan satu aturan untuk semuanya: aggrega/pluginGenCatalog membaca modul dan overlay-nya dari mana pun Anda memilihnya, karena modul yang Anda build berada di direktori keluaran toolchain Anda dan menolak membacanya di sana berarti menolak seluruh tujuan operasi itu. aggrega/pluginSync membaca kedua jalurnya di dalam workspace, karena permintaan itu menyangkut berkas yang sudah dimuat workspace. Permintaan penentuan lokasi di atas menerima jalur absolut karena alasan yang berbeda lagi — dokumen yang sudah dibuka klien, disebutkan dengan ejaan apa pun yang dipegangnya.
Permintaan yang tidak memuat sesuatu yang diperlukan operasi ditolak dengan menyebutkan field yang harus dikirim. Penambahan atau penghapusan tanpa type atau query; penambahan provider tanpa capability, atau penambahan governance tanpa role; penambahan cli tanpa acceptCapabilities; penyelarasan tanpa entity atau plugin; pembuatan yang menyebutkan kedua mode pemilihan atau tidak satu pun, atau yang tidak memuat overlay atau outputDir. Masing-masing dikembalikan dengan kode invalid-params standar, dan percobaan ulang tidak mengubah apa pun sampai permintaannya berubah. Penghapusan yang kuerinya tidak cocok dengan entri mana pun juga ditolak, dengan menyebutkan tipe, kueri, dan berkas tempat pencariannya — itu adalah keadaan konfigurasi, bukan keadaan permintaan, sehingga yang perlu diperbaiki bisa salah satu dari keduanya.
Tidak ada yang ditanyakan secara interaktif, dan satu-satunya keputusan yang semestinya ditanyakan kepada seseorang datang sebagai field. Perintah terminal menanyakan kepada siapa pun yang sedang menyimak apakah mereka menerima kapabilitas yang dideklarasikan sebuah plugin ekstensi perintah. Tidak ada yang menyimak aliran ini, sehingga acceptCapabilities menjadi tanggung jawab pemanggil untuk diperoleh dan dikirim, dan permintaan yang tidak memuatnya ditolak dengan menyebutkan apa yang harus dikirim alih-alih menginstal berdasarkan persetujuan yang tidak pernah diberikan siapa pun. Daemon yang dijalankan tanpa sarana untuk menginstal ekstensi perintah langsung menolak penambahan cli, alih-alih melaporkan keberhasilan yang tidak menginstal apa pun.
Jenis yang boleh Anda tawarkan kepada penulis
aggrega/getSchema tanpa kind menjawab jenis mana saja yang boleh Anda sebutkan, dan menjawab dalam dua cakupan karena klien memerlukan cakupan yang berbeda untuk tugas yang berbeda. Bacalah yang sedang Anda tanyakan.
kinds adalah setiap token yang dijawab biner. entityKinds adalah himpunan jenis yang dokumennya ditulis oleh penulis. Daftar yang luas memuat representasi perantara, lockfile, konfigurasi workspace, dan kontrak soket plugin di samping jenis-jenis yang Anda tulis — masing-masing skema yang nyata, tetapi bukan dokumen yang berkasnya ditulis seseorang. Jadi daftar yang luas adalah dasar untuk menyambungkan asosiasi skema sebuah editor, dan daftar yang sempit adalah dasar untuk membangun pemilih. Pemilih yang dibangun dari daftar yang luas menawarkan nilai yang tidak diterima skema penulisan mana pun, dan penulis baru menemui penolakannya setelah memilih salah satunya.
Himpunan yang sempit juga lebih sempit daripada jenis entitas, dan tidak ada skema yang memberi tahu Anda yang mana. Jenis milik platform yang kontennya ditulis di dalam dokumen jenis lain bukanlah dokumen yang ditawarkan kepada penulis untuk memulai. Workload adalah jenis seperti itu: konten workload ditulis di field workload: milik sebuah Recipe atau FeatureRecipe, baik secara inline maupun dari berkas yang diimpor field itu, sehingga tidak ada dokumen workload yang dapat dituju secara tersendiri — lihat antarmuka penulisan Workload untuk mengetahui tempat konten itu ditulis. Skemanya menetapkan apiVersion dan kind persis seperti skema jenis yang ditulis penulis, karena itulah yang memungkinkan konten divalidasi di tempatnya berada; nilai-nilai tetap itu mengidentifikasi konten dan tidak membuatnya dapat dituju. Jadi nilai-nilai itu bukan tanda bahwa sebuah jenis layak dibuatkan draf. entityKinds membawa jawabannya, dan tidak ada apa pun dalam byte skema yang membawanya.
Setiap entri entityKinds membawa kedua ejaan yang diperlukan klien, dan tidak satu pun dapat diturunkan dari yang lain. kind adalah token huruf kecil yang dipisah tanda hubung — kirim kembali sebagai kind ke metode ini atau ke aggrega/scaffoldEntity. documentKind adalah nilai yang dibawa dokumen itu sendiri di field kind: tingkat atasnya. Keduanya berbeda lebih dari sekadar huruf besar-kecil untuk jenis yang namanya terdiri dari lebih dari satu kata: tidak ada yang dapat Anda lakukan terhadap featurerecipe yang menghasilkan FeatureRecipe. Ambil masing-masing dari entri alih-alih menurunkan yang satu dari yang lain, dan tidak ada lagi pemetaan yang perlu dipelihara klien.
Setiap entri juga menyatakan operasi mana yang menerima dokumen dari jenisnya, sehingga kontrol yang menawarkan operasi-operasi itu pada sebuah dokumen hanya menawarkan operasi yang tidak menolaknya karena jenisnya. acceptedBy membawa tiga boolean, masing-masing ada di setiap entri, dan masing-masing menyangkut dokumen dari jenis yang disebutkan secara tersendiri — melalui jalurnya, atau melalui namanya untuk inspeksi — tanpa ada hal lain yang dikirim bersamanya. singleEntityValidation menyatakan apakah aggrega validate <path> memeriksa dokumen dari jenis itu, alih-alih menolaknya dan menyebutkan cakupan seluruh katalog atau Release yang memeriksanya sebagai gantinya. publication menyatakan apakah aggrega/publishEntity yang hanya menyebutkan dokumen tersebut akan menerbitkannya: sebuah Plugin bernilai false, karena penerbitannya juga mengikat executable yang disebutkan permintaan di plugin, sehingga permintaan yang hanya menyebutkan dokumennya ditolak; sebuah Manifest dan sebuah Release bernilai false karena kedua jenis itu tidak diterbitkan. inspectionByName menyatakan apakah aggrega/entityDefinition meresolusi sebuah nama menjadi entitas dari jenis itu, dengan nama dikirim sebagaimana ditulis ketika satu entitas mereferensikan entitas lain — Plugin sebagai <pluginType>/<name>, dan Recipe atau FeatureRecipe sebagai <capability>/<name>, atau dengan namanya saja jika hanya satu kapabilitas yang mendeklarasikan nama itu. Nilai true menyatakan bahwa operasi tidak menolak dokumen karena jenisnya; operasi tetap dapat menolak dokumen tertentu karena isi dokumen tersebut.
Jangan menyimpan daftar sendiri. Jenis apa saja yang ada adalah properti dari biner yang sedang Anda ajak berkomunikasi, sehingga daftar yang ditulis di dalam klien akan sesuai pada hari daftar itu ditulis dan berhenti sesuai pada hari sebuah jenis ditambahkan — dan yang kemudian dilihat penulis adalah jenisnya tidak ada di satu-satunya kontrol yang seharusnya menawarkannya. Tanyakan, dan jawabannya mengikuti biner.
Kedua bagian datang bersamaan, dan hanya jika Anda tidak menyebutkan jenis apa pun. Permintaan yang menyebutkan sebuah jenis dijawab dengan skema jenis itu dan tidak membawa kedua daftar tersebut, sehingga pertanyaan mana yang Anda ajukan dapat dibaca dari respons. Token yang tidak dijawab skema mana pun ditolak dengan seluruh himpunan yang valid di dalam pesannya, dengan kode invalid-params standar, sehingga salah ketik adalah permintaan yang perlu diperbaiki, bukan sesuatu yang perlu ditanyakan kepada seseorang.
Permintaan ini menjawab di workspace yang tidak memuat apa pun. Kosakatanya dikompilasi ke dalam biner, sehingga permintaan ini tidak memerlukan dokumen, lockfile, maupun katalog — dan itulah workspace tempat penulis yang memulai dokumen pertamanya berada.
Apa yang diberikan respons scaffold kepada Anda
Bagian ini membahas pembuatan draf. Bentuk lain metode ini menulis contoh yang dapat dijalankan, dan jawabannya dijelaskan bersama metode di atas.
aggrega/scaffoldEntity mengembalikan teks. skeleton adalah YAML untuk jenis yang Anda sebutkan: setiap field yang diwajibkan skema jenis itu, dalam urutan yang dideklarasikan skema. Field yang ditetapkan skema ke satu nilai tetap datang dalam keadaan terisi — apiVersion dan kind adalah yang akan Anda perhatikan — metadata.name membawa name yang Anda kirim, dan setiap nilai wajib lainnya datang sebagai placeholder yang bertipe sesuai deklarasi skema di tempat itu: string kosong, nol, false, daftar kosong, mapping kosong. kind mengulang token yang menjadi dasar penurunan dokumen, sehingga klien dengan beberapa permintaan yang belum terjawab dapat mengaitkan jawaban dari jawaban itu sendiri alih-alih memelihara korelasinya sendiri.
Metode ini tidak menulis apa pun, dan itulah bagian yang perlu diperhitungkan dalam desain. Metode ini tidak membuat berkas, tidak memilih jalur, dan tidak menyentuh direktori. Yang Anda terima adalah dokumen untuk ditulis, bukan dokumen yang sudah ditulis — sehingga editor menaruh teks itu ke dalam buffer baru yang belum disimpan yang dapat dibaca, disunting, atau dibuang oleh penulis, dan saat berkas baru sampai ke disk tetap berada di tempat buffer dan riwayat undo berada. Tidak ada permintaan lain yang mengambil dokumen ini dan menaruhnya di suatu tempat atas nama Anda; menentukan lokasi dokumen baru adalah urusan editor.
Metode ini tidak meresolusi apa pun, dan tidak memerlukan apa pun dari workspace. Dokumen diturunkan dari skema yang dibawa biner, sehingga metode ini tidak menjangkau registry maupun jaringan, tidak merujuk katalog, dan tidak membaca berkas. Metode ini menjawab dengan cara yang sama di setiap workspace, termasuk direktori kosong yang belum memuat dokumen Aggrega — yang justru merupakan workspace tempat penulis yang memulai dokumen pertamanya berada, dan tempat sebagian besar metode lain di sini akan terlebih dahulu memerlukan dokumen atau lockfile.
Permintaan yang sama menghasilkan byte yang sama di mana pun diajukan. Dokumen dihasilkan oleh satu komputasi yang digunakan bersama dengan antarmuka lain yang menawarkan kapabilitas ini, sehingga editor dan asisten yang diminta jenis dan nama yang sama menampilkan teks awal yang sama kepada penulis.
Kerangka ini membawa field yang diwajibkan jenisnya, dan bukan dokumen yang sudah selesai. Kerangka ini membawa field wajib dan tidak ada yang lain: field opsional yang Anda inginkan adalah field yang Anda tambahkan sendiri, dan setiap placeholder adalah nilai yang masih harus diisi. Isi placeholder-nya, lalu jalankan aggrega/validate pada buffer. Untuk entitas katalog dari jenis yang diperiksa aggrega validate sebagai entitas tunggal, metode itu menyebutkan setiap placeholder yang masih harus diisi, masing-masing pada kuncinya beserta apa yang diterimanya, dengan pembacaan yang sama dengan yang diterapkan perintah itu pada berkas yang disimpan — termasuk placeholder yang boleh kosong menurut skema, dengan capability dan implements pada draf Recipe atau FeatureRecipe sebagai yang akan Anda temui. Untuk jenis lainnya, metode itu memeriksa buffer terhadap skema jenisnya, sehingga placeholder yang tidak boleh kosong menurut skema — misalnya sebuah versi — kembali sebagai temuan skema itu, dan placeholder yang boleh kosong tidak menghasilkan temuan. Validasi langsung menjelaskan entri yang menjadi wujud setiap placeholder.
Apa yang disampaikan respons impor kepada Anda
aggrega/import mengonversi sumber yang ditulis untuk alat lain menjadi draf dokumen Aggrega, dan menuliskannya — berbeda dengan scaffold di atas, yang menyerahkan teks kepada Anda. written menyebutkan setiap file yang sampai ke disk, relatif terhadap outputDir; files memuat setiap file yang ditulis oleh permintaan beserta content-nya, baik ditulis maupun tidak — setiap draf yang dihasilkan importer, lalu catatan tentang apa yang ditulis impor, atau di bawah sync apa yang diubah oleh sinkronisasi. Keduanya menjawab pertanyaan yang berbeda, jadi bacalah yang sesuai dengan pertanyaan Anda: apa yang kini ada di disk, atau apa yang dihasilkan.
Anda memilih ke mana draf ditempatkan, atau menyerahkannya ke root workspace. outputDir bersifat opsional, sebagaimana aggrega import --output-dir dan output_dir pada alat import milik asisten: permintaan yang tidak menyebutkannya membuat draf di bawah root workspace — tempat aggrega import menulis bila tidak diberi tujuan, di mana pun ia dijalankan — dan permintaan yang menyebutkannya membuat draf di sana. Direktori yang disebutkan adalah path di dalam workspace, dan nilai relatif di-resolve terhadap root workspace, bukan terhadap direktori tempat daemon kebetulan berada. source yang Anda konversi adalah kasus lain dan tidak dibatasi dengan cara ini: Anda yang memilih file atau direktori itu, sehingga ia dibaca di mana pun ia berada, dan membacanya di sana tidak memindahkan tempat draf ditempatkan. Direktori dibuat jika belum ada. Di bawah dryRun tidak ada yang ditulis, dan setiap draf tetap menyebutkan path tujuannya, relatif terhadap outputDir yang disebutkan respons — direktori yang Anda kirim, atau root workspace.
Permintaan tidak pernah menimpa Aggregate yang sudah ada di outputDir. Aggregate adalah dokumen yang terus disunting penulis setelah draf dibuat, sehingga permintaan yang salah satu drafnya akan mendarat pada file yang terbaca sebagai Aggregate ditolak, dengan menyebutkan draf tersebut dan letak Aggregate itu, dan tidak ada apa pun yang ditulis — juga di bawah dryRun, karena dry run menolak apa yang ditolak oleh penulisan. Kirim sync untuk memperbaruinya sesuai sumber, atau sebutkan outputDir lain untuk membuat draf di sampingnya. Setiap file lain yang sudah ada di path draf akan ditimpa, dan file yang dibuat oleh impor sebelumnya tetapi tidak dibuat oleh impor ini dibiarkan di tempatnya. Setiap permintaan yang membuat draf apa pun juga menulis .aggrega-import.json di outputDir, catatan tentang apa yang ditulis impor — target yang dikirimkan, jika ada, snapshot katalog yang dibaca, jika ada, serta setiap file draf dan, dalam Aggregate atau Release hasil draf, setiap key di setiap kedalaman, dengan digest dari teks yang ditulis di sana, sedangkan file draf lainnya dicatat utuh — dan files serta written memuatnya setelah draf. File itu berformat JSON, sehingga tidak ada yang membaca dokumen YAML workspace yang akan membacanya; sync, seperti aggrega import --sync, membacanya untuk memperbarui draf sesuai sumbernya. sync yang tidak dikirimi target membuat draf untuk target yang disebutkan catatan, sehingga ia membuat draf Manifest yang dibuat oleh impor sebelumnya; yang dikirimi target membuat draf untuk target itu, dan catatan kemudian menyebutkannya. Target tercatat yang tidak diikat oleh Recipe mana pun di katalog ditolak seperti target yang dikirim, dengan penolakan yang menyatakan bahwa target tersebut adalah target tercatat. Karena Release hasil draf dicatat key demi key, environment yang ditulis penulisnya di tempat impor meninggalkan komentar untuknya adalah key yang ditulis penulis, dan sinkronisasi membiarkannya byte demi byte.
Kirim sync untuk memperbarui apa yang dibuat impor sebelumnya di outputDir sesuai sumber, dengan hanya mengubah apa yang ditulis impor. Setiap bagian dinilai dengan tiga cara — apa yang menurut catatan terakhir ditulis impor di sana, apa yang ada di disk, dan apa yang kini dihasilkan sumber. Bagian yang dibiarkan sumber seperti terakhir ditulis impor tetap persis seperti di disk, baik disunting penulis maupun tidak. Bagian yang diubah sumber ditulis ulang, bagian yang dihapusnya dibuang — file draf dihapus utuh — dan bagian yang ditambahkannya ditambahkan di samping bagian-bagian yang disebutkan draf di sekitarnya, masing-masing hanya jika apa yang ada di disk adalah apa yang terakhir ditulis impor dan tidak memuat apa pun yang ditambahkan penulis. Semua yang lain tetap byte demi byte: key yang ditambahkan penulis di mana pun — parameter, Feature, termasuk di bawah instance Component hasil draf, Component lain — komentar yang tidak ditulis tepat di atas key draf, dan setiap file yang tidak tercantum dalam catatan. Sinkronisasi ke direktori yang tidak memuat catatan dan tidak ada apa pun di path drafnya menulis seluruh draf, seperti halnya permintaan tanpa sync.
drift adalah apa yang diperbarui oleh sinkronisasi, dan merupakan jawaban atas “apakah sumber telah berubah”. Ia mencantumkan setiap bagian yang diubah sinkronisasi — atau, di bawah dryRun, setiap bagian yang akan diubahnya — dalam urutan yang disebutkan draf, masing-masing sebagai change (added, removed, atau changed), file, file draf tempat bagian itu berada, relatif terhadap outputDir, dan key, key-key yang mengarah ke bagian itu dalam Aggregate atau Release hasil draf sebagai list, sehingga key yang memuat titik tetap menjadi satu entri; key kosong jika bagian itu adalah seluruh file, yang merupakan cara file draf yang dihapus sinkronisasi disebutkan. aggrega import mencetak entri yang sama ke standard error sebagai <change> <key> in <file> atau <change> <file>, dan status keluarnya di bawah --sync --dry-run menyatakan apakah sumber telah bergeser; antarmuka ini tidak memiliki status keluar, jadi kirim sync dengan dryRun dan periksa apakah drift kosong. drift adalah list kosong untuk permintaan yang bukan sinkronisasi, untuk sinkronisasi yang selaras dengan sumbernya, dan untuk sinkronisasi yang importernya tidak dapat menyelesaikan proses. Di bawah sync, files memuat setiap file draf yang diubah sinkronisasi, dengan konten yang diberikannya, lalu catatan jika catatan itu juga berubah, dan written menyebutkan file yang sampai ke disk — sehingga sinkronisasi yang selaras menjawab keduanya sebagai list kosong. File draf yang dihapus sinkronisasi disebutkan dalam drift dan tidak dalam kedua list itu: entri removed-nya, dengan key kosong, adalah satu-satunya keterangan jawaban tentang file itu, dan di bawah dryRun menyebutkan file yang akan dihapus oleh penulisan.
Sinkronisasi tidak pernah menulis ulang apa yang ditulis penulis, dan sebagai gantinya menolak. Sinkronisasi yang akan mengubah atau membuang bagian yang disunting penulis, menambahkan bagian di tempat penulis sudah menulisnya, atau membuang bagian yang memuat sesuatu yang ditambahkan penulis akan ditolak, dengan menyebutkan setiap bagian tersebut beserta alasannya pada barisnya sendiri, dengan kata-kata yang digunakan aggrega import --sync — <file> <key>: <why>, atau <file>: <why> untuk seluruh file — dan tidak ada yang ditulis; komentar yang ditulis tepat di atas key draf dianggap menyunting key tersebut. Sinkronisasi atas Aggregate yang tidak tercantum dalam catatan mana pun ditolak dengan menyebutkan Aggregate dan catatan itu, demikian pula sinkronisasi yang catatannya tidak dapat dibaca, karena tanpa catatan bagian-bagiannya tidak dapat dibedakan dari bagian milik penulis. Kedua penolakan dikembalikan sebagai error invalid-params, juga di bawah dryRun, dan menyebutkan sync. Rekonsiliasikan setiap bagian yang disebutkan secara manual, atau kembalikan apa yang ditulis impor di sana, lalu kirim permintaan lagi.
🔴 halted: true bukan error, dan memperlakukannya sebagai error adalah kesalahan yang harus diantisipasi dalam desain. Importer yang tidak dapat mengonversi semuanya tetap membuat draf untuk apa yang dapat dikonversinya: respons memuat draf tersebut, written menyebutkannya, dan diagnostics menyatakan apa yang tertinggal. Itulah jawaban paling berguna yang diberikan operasi ini, dan ia datang sebagai hasil, bukan sebagai kegagalan, justru agar Anda dapat menunjukkan kedua bagian itu kepada penulis. Di bawah sync, jawaban yang sama tidak menulis apa pun — files, written, dan drift kosong — karena draf parsial akan terbaca sebagai sumber yang membuang setiap bagian yang tidak dicapai importer. Sumber yang sama sekali tidak dapat dibaca importer adalah kasus lain dan memang dikembalikan sebagai error.
Setiap diagnostik memuat severity dan message, ditambah code jika importer menetapkannya. Lakukan percabangan berdasarkan code bila Anda ingin bereaksi terhadap kondisi tertentu, dan tampilkan message kepada pembaca; severity diambil dari himpunan yang sama dengan yang digunakan setiap socket plugin untuk melapor — halt, warn, info — sehingga halted adalah ringkasan dari entri-entri tersebut, bukan penilaian terpisah. files, written, drift, diagnostics, dan decisions selalu berupa array, kosong alih-alih tidak ada.
decisions menyatakan di mana impor menebak. Isinya satu entri per node sumber yang dipetakan importer, dalam urutan importer dan persis seperti yang dilaporkan importer: sourceNode, yaitu id, type, dan paramsSummary node tersebut; candidates, setiap Component katalog yang ditimbang importer untuknya sebagai componentName, score, tier, dan signals — kontribusi setiap sinyalnya, di bawah table, category, domainLabels, shape, dan name; chosen, yaitu target yang dipilihnya, mode tempat ia menuliskannya — sebuah reference ke Component yang sudah ada atau sebuah draft — serta tier pilihan tersebut; rationale, alasannya; dan swapHint, cara memilih secara berbeda. candidates tidak ada jika importer tidak menimbang kandidat apa pun, chosen jika importer tidak membuat pilihan, dan rationale serta swapHint jika importer tidak menuliskannya. Setiap nilai berasal dari importer itu sendiri — cara ia menilai kandidat dan letak batas tier-nya adalah pilihannya — jadi tampilkan entri sebagai penjelasan importer tentang pemetaan, bukan sebagai putusan. Keputusan ini dikirim baik di bawah dryRun maupun ketika halted bernilai true: tebakan dari impor parsial justru yang dibutuhkan penulis yang meninjaunya, dan importer yang tidak melaporkan keputusan apa pun menjawab dengan daftar kosong. Jika Anda menampilkannya sebagai teks, aggrega import sudah merumuskan satu keputusan sebagai mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, dengan skor dari kandidat terbaik.
Format dikenali dari sumber kecuali Anda menyebutkannya. Pengenalan menggunakan signature yang dideklarasikan importer — baik importer katalog workspace maupun importer inti compiler — yang dicatat oleh entitas Plugin setiap importer — sintaks tempat sumber dibaca, nama file yang berlaku untuk suatu signature, serta path yang harus atau tidak boleh dimuat oleh pohon hasil parsing — sehingga daemon sendiri tidak mengenal format apa pun dan format importer baru dikenali tanpa perubahan lain. Deteksi hanya membaca sumber yang Anda kirim — dari sebuah direktori, hanya file yang dipilih oleh pola file suatu signature — dan tidak mengakses jaringan, mem-parsing setiap file yang dibacanya melalui parser yang disediakan katalog workspace untuk suatu sintaks — atau, untuk sintaks yang parsernya tidak disediakan katalog, parser yang dibawa compiler sendiri — satu kali untuk setiap sintaks yang digunakan oleh signature yang berlaku untuk nama file tersebut; importer kemudian membaca sumber melalui parser yang sama. Signature yang tidak mendeklarasikan pola file berlaku untuk file yang Anda kirim apa pun namanya, dan tidak berlaku untuk file mana pun dalam direktori; signature importer Langflow, Flowise, dan n8n termasuk jenis ini dan membaca JSON, sedangkan signature importer Dify membaca YAML, sehingga mengenali file yang Anda kirim secara tersendiri berarti membacanya sebagai JSON dan sebagai YAML, yang tidak memerlukan parser di katalog workspace: compiler membawa parser JSON dan YAML, dan parser yang disediakan katalog digunakan sebagai gantinya. Sumber yang tidak cocok dengan signature mana pun ditolak dengan meminta format dan menyebutkan format yang diiklankan importer — atau, untuk direktori, dengan meminta salah satu filenya dikirim secara tersendiri atau format yang importernya mendeklarasikan pola file, dengan hanya menyebutkan format-format itu — di bawah kondisi No importer recognises the source (Tidak ada importer yang mengenali sumber); sumber yang cocok dengan signature dari lebih dari satu format ditolak dengan menyebutkan format-format tersebut, di bawah kondisi More than one importer recognises the source (Lebih dari satu importer mengenali sumber). data setiap penolakan memuat code dan shortCode kondisinya, sehingga klien meminta format berdasarkan kode, bukan berdasarkan kata-kata. Keduanya tidak ditebak, karena format hasil tebakan me-resolve importer yang salah dan menghasilkan omong kosong yang meyakinkan. format dalam respons adalah format yang digunakan, baik dideteksi maupun disebutkan, sehingga klien yang tidak menyertakannya mengetahui apa yang diperolehnya.
Direktori yang Anda kirim dibaca menjadi file-file yang disebutkan importernya, dan direktori yang tidak dapat dibacanya merupakan error. Jika source menyebutkan sebuah direktori, importer menerima file-file di dalamnya yang dipilih oleh pola file yang dideklarasikan signature-nya, kecuali folder keluaran build workspace dist/, masing-masing dinamai dengan path-nya di dalam direktori, dalam urutan terurut, di samping file-file yang disebutkan entri plugins.importer-nya di bawah with.sources. Importer yang tidak mendeklarasikan pola file, direktori yang tidak memuat file yang dipilih pola tersebut, file direktori dan file with.sources dengan nama yang sama, serta link di antara file yang akan dibaca impor, atau ke sebuah direktori, yang mengarah keluar dari direktori, masing-masing dikembalikan sebagai error yang memuat kode kondisinya, tanpa ada yang ditulis.
Importer mana yang dijalankan adalah keputusan workspace, bukan keputusan permintaan. Format di-resolve ke importer yang mengiklankannya di antara plugin katalog workspace dan importer inti compiler — importer yang dilampirkan oleh entri plugins.importer dalam konfigurasi workspace, jika entri tersebut melampirkan salah satunya — sehingga permintaan tidak dapat memilih modul atau menunjuk modul di disk. Format yang tidak diiklankan importer mana pun ditolak dengan menyebutkan format tersebut, dan format yang diiklankan dua importer tanpa ada yang dilampirkan — termasuk importer inti dan importer dengan nama lain yang dimuat katalog untuk format yang sama — ditolak sebagai ambigu, bukan di-resolve secara sembarang.
Importer inti yang belum ada di mesin diambil satu kali, oleh impor pertama yang membutuhkannya. Importer tersebut berasal dari registry default workspace, terikat pada modul yang diterbitkan rilis compiler dan diverifikasi sebagaimana pull memverifikasi plugin yang diambilnya — signature-nya di bawah kebijakan kepercayaan registry tersebut, serta fungsi host yang digunakannya — dan disimpan di cache konten workspace, yang merupakan satu-satunya hal yang ditulis untuknya: tanpa lockfile, dan tanpa catatan plugin tepercaya. Setiap impor berikutnya membacanya dari sana dan tidak mengakses registry. Modul yang gagal diverifikasi merupakan error yang memuat kode kondisinya, dan tidak ada yang disimpan; modul yang tidak dapat diambil — workspace sedang offline, registry-nya tidak dapat dijangkau, atau registry tidak memuatnya — merupakan error di bawah A plugin’s .wasm is not on this machine (File plugin tidak ada di mesin ini), yang menyebutkan importer, versinya, dan cara menempatkan modulnya di mesin. Permintaan itu sendiri tidak menyebutkan registry, dan impor yang semua importer serta katalog yang dibacanya sudah ada di mesin sama sekali tidak mengakses jaringan.
Jika workspace tidak menyebutkan folder katalog apa pun, impor membaca katalog yang diterbitkan registry default-nya. Workspace yang workspace.catalog_dirs, AGGREGA_CATALOG_DIRS, dan root-nya tidak menyebutkan folder katalog apa pun membaca katalog pustaka standar sebagai satu snapshot bertanda tangan, di catalog/snapshot pada registry default-nya. Snapshot diambil satu kali: tanda tangannya diverifikasi di bawah kebijakan kepercayaan registry tersebut, lalu snapshot disimpan di cache konten workspace dan dibaca di sana sebagai folder katalog, terikat pada digest-nya, tanpa meminta registry mana pun lagi. Snapshot mana yang dibaca suatu permintaan: dengan upgrade, yang terbaru; jika tidak, yang disebutkan catatan di outputDir, diambil berdasarkan digest-nya jika mesin tidak menyimpannya; jika tidak, yang terakhir diambil workspace sebagai yang terbaru; jika tidak, yang terbaru. Catatan yang ditulis impor menyebutkan snapshot yang dibacanya, berdasarkan digest-nya, sehingga permintaan berikutnya ke outputDir yang sama membaca katalog yang sama. Dalam mode offline, permintaan yang harus mengambil snapshot merupakan error di bawah The workspace is offline and the step needs the network (Workspace sedang offline dan langkah ini memerlukan jaringan), yang menyebutkan apa yang harus dijalankan, dan upgrade ditolak apa pun yang disimpan mesin, karena hanya registry yang dapat menyatakan snapshot mana yang terbaru. Registry yang tidak menerbitkan snapshot apa pun membuat impor tanpa katalog, dan entri warn di diagnostics menyatakannya. Workspace yang menyebutkan folder katalog mengimpor terhadap folder itu dan tidak mengambil snapshot, dan upgrade tidak mengubah apa pun di sana.
Di bawah dryRun tidak ada yang dibuat. written kosong, files memuat file yang sama yang akan dihasilkan oleh penulisan — dengan sync, file yang akan ditulis sync, di samping drift yang akan diperbaruinya — dan tidak ada direktori yang dibuat — sehingga editor dapat menyajikannya kepada penulis untuk disimpan, diubah, atau dibuang. Semua hal lain yang dilakukan penulisan tetap dilakukan: importer yang sama berjalan atas sumber yang sama dan melaporkan diagnostik yang sama, sehingga sumber yang akan ditolak oleh penulisan juga ditolak di sini. Importer inti atau snapshot katalog yang diambil di bawah dryRun disimpan di cache konten sebagaimana pada penulisan, karena memperoleh apa yang menjadi dasar berjalannya impor merupakan bagian dari menjalankannya, bukan dari menempatkan draf.
Path yang dikembalikan importer dibatasi di dalam outputDir. Path draf berasal dari importer, bukan dari Anda, sehingga path yang keluar dari direktori output ditolak dan sama sekali tidak ada yang ditulis — bahkan draf yang path-nya benar pun tidak. Penolakan tersebut menyebutkan path yang bermasalah, yang memberi tahu Anda bahwa yang perlu diperbaiki adalah importer, bukan permintaan Anda.
Pertanyaan yang dijawab oleh setiap permintaan entitas
Empat permintaan di sini akan memberi tahu Anda tentang sebuah entitas, dan keempatnya tidak dapat saling menggantikan. Memilih di antaranya bergantung pada apa yang Anda pegang saat bertanya.
Anda memegang kursor. aggrega/hover dan aggrega/resolve menerima sebuah file dan sebuah posisi, lalu menentukan entitas mana yang dimaksud dari apa yang tertulis di sana. Keduanya mencakup bentuk referensi yang benar-benar dimuat sebuah dokumen — nilai extends, tipe component atau feature, implements milik Recipe, referensi recipe milik Manifest, dua penunjuk path milik Release, target uses, dan metadata.name milik entitas itu sendiri. Gunakan keduanya ketika kursor pengguna adalah koordinatnya: pengguna sedang membaca dokumen dan ingin tahu ke mana sebuah referensi menunjuk.
Anda memegang nama. aggrega/entityDefinition menerima identitas secara langsung. Tidak ada yang harus dibuka, tidak ada posisi yang terlibat, dan entitas tidak harus disebut di mana pun yang dapat ditemukan klien. Gunakan permintaan ini ketika pengguna mengetik nama, memilih satu dari daftar, atau mengikuti sesuatu yang identitasnya sudah diketahui klien Anda — hover mengharuskan Anda terlebih dahulu menemukan tempat nama itu ditulis, yaitu pekerjaan yang tidak perlu Anda lakukan.
Anda belum memegang apa pun. aggrega/catalogIndex mencantumkan isi workspace, beserta field deskriptif untuk setiap entitas. Gunakan permintaan ini untuk mengisi pemilih, lalu berikan nama yang dipilih ke aggrega/entityDefinition.
Anda memegang Release. aggrega/releaseClosure menjawab tentang sebuah Release, bukan tentang satu entitas, dan dibahas pada bagian di bawah.
Definisi yang dikembalikan oleh permintaan berdasarkan nama adalah entitas sebagaimana telah di-resolve, bukan sebagaimana dideklarasikan oleh satu file mana pun. Component atau Feature yang memperluas sebuah basis dikembalikan dengan membawa kontrak basis tersebut, yang tidak muncul di mana pun dalam dokumen yang mendeklarasikan namanya — jadi jawabannya adalah tentang apa entitas itu, dan membaca file itu sendiri tidak akan memberi Anda hal yang sama.
Definisi tersebut tiba sebagai dokumen YAML, bukan sebagai struktur di dalam respons, dan hal itu disengaja: sebuah pilar skema memiliki beberapa bentuk penulisan — konten yang ditulis lengkap, referensi ke dokumen bersama, atau penanda yang menyatakan bahwa konten berasal dari basis — dan dokumen tersebut mereproduksi bentuk mana pun yang dihasilkan resolusi, dalam urutan kunci milik penulis sendiri. Parse sebagai dokumen jika Anda memerlukan field-nya; tampilkan apa adanya jika Anda menaruhnya di panel.
Membedakan dua penolakan berdasarkan nama
Nama yang tidak ter-resolve ke apa pun ditolak, bukan dijawab dengan dokumen kosong, karena jawaban kosong akan melaporkan salah ketik sebagai entitas yang tidak punya apa pun untuk dikatakan tentang dirinya. Ada dua cara sebuah nama tidak ter-resolve ke apa pun, keduanya menuntut hal yang berbeda dari pembaca, dan Anda membedakannya dari apa yang dibawa data milik error, bukan dengan membaca pesannya:
- Tidak ada
filedalamdata. Tidak ada apa pun di workspace yang mendeklarasikan nama itu dan tidak ada tingkat katalog yang me-resolve-nya. Hampir selalu permintaannyalah yang perlu diperbaiki — salah ketik, atau nama dari katalog yang tidak ada di search path workspace ini. - Ada
filedalamdata. Sebuah dokumen workspace memang mendeklarasikan nama itu, tetapi katalog tetap tidak me-resolve apa pun untuknya. Entitas tersebut tertulis dan ada sesuatu yang menolaknya, yaitu keadaan workspace yang diperbaiki oleh seseorang. Jika tepat satu dokumen yang dibaca dan ditolak katalog mendeklarasikan nama itu — penyebab yang umum — pesan diawali dengan penolakan tersebut, dinyatakan sekali: kategori dan kode singkatnya, dokumen menurut path tempat dokumen itu dilaporkan, dan apa yang salah dengannya, seperti baris dan batasan yang dilanggarnya; lalu pesan mencatat bahwa file tersebut dilewati saat pemuatan, dan mencantumkan file lain yang ditolak pemuatan. Jika tidak, pesan menyebutkan dokumen yang mendeklarasikan, mencantumkan file yang ditolak pemuatan, dan menyatakan dari mana workspace ini membaca entitas lokal serta apa yang harus diubah agar dokumen tersebut dibaca — penjelasan yang dihilangkan jika dokumen yang ditolak mendeklarasikan nama itu, karena dokumen tersebut sudah berada di tempat katalog membaca.
Keduanya membawa kode entity-not-resolvable, jadi buat percabangan berdasarkan ada atau tidaknya file, bukan berdasarkan kodenya.
Bertanya tentang sebuah koordinat
Anda memegang referensi registry. Kirimkan sebagai name dari aggrega/entityDefinition, dan jawabannya adalah entitas yang dipublikasikan pada koordinat itu, dalam bentuk hasil yang sama dengan yang diterima sebuah nama ditambah published, diisi dari apa yang dipublikasikan, bukan dari apa yang di-resolve oleh katalog:
definitionadalah dokumen entitas persis seperti saat dipublikasikan. Koordinat yang entitasnya dipublikasikan bersama file yang dideklarasikannya membawa sebuah arsip, dan dokumen diekstrak darinya; koordinat yang entitasnya tidak mendeklarasikan file membawa dokumennya tanpa perubahan, dan entitas sebuah Plugin dibaca dari manifest-nya, bukan dari executable yang dipublikasikan bersamanya. Tidak ada pewarisan yang diterapkan.authoredLengthadalah panjang dokumen tersebut, karena definisi di sini adalah dokumen yang ditulis, bukan hasil render dari dokumen yang telah di-resolve.filekosong, karena entitas yang dibaca dari registry tidak memiliki dokumen di mesin ini untuk disebutkan.publishScopedihilangkan: Anda sudah memegang koordinatnya, yaitu tempat entitas itu dipublikasikan.publishedadalah apa yang dibaca, dan field ini ada pada jawaban ini dan tidak pada jawaban berdasarkan nama mana pun:reference;archive, apakah byte-nya berupa arsip tempat dokumen diekstrak —falsejika koordinat menyimpan dokumen itu sendiri;mediaTypeyang dideklarasikan manifest; danmanifestDigestmilik manifest tersebut, yang dapat Anda kirim setelah@sebagai pengganti tag untuk membaca kembali byte yang persis sama.
Permintaan ini menjangkau registry yang disebut oleh referensi, dengan kredensial pengguna yang menjalankan daemon ini dan postur jaringan workspace ini, sehingga workspace yang offline menolaknya. Byte yang diambil diperiksa terhadap digest yang dicatat oleh manifest artefak itu sendiri dan tidak terhadap hal lain — tidak ada tanda tangan yang diverifikasi dan tidak ada penarikan yang dilaporkan — dan tidak ada yang ditulis. Referensi yang tidak dapat dibaca ditolak dengan entity-not-resolvable, dan pesannya diawali dengan kode singkat kondisi yang menyatakan alasannya — kondisi yang sama dengan yang dilaporkan aggrega inspect — dan diakhiri dengan apa yang harus dilakukan. Referensi yang tidak menyebutkan repository, atau tidak menyebutkan tag maupun digest, adalah permintaan yang salah bentuk dan ditolak sebagai invalid params.
Closure bukanlah graf
aggrega/irGraph dan aggrega/releaseClosure diturunkan dari resolusi yang sama atas Release yang sama dan menjawab pertanyaan yang berbeda. Klien yang sudah menerima graf dapat saja berasumsi bahwa ia juga sudah memiliki yang satu ini, padahal tidak.
Graf menyatakan apa yang di-deploy oleh Release — node-nodenya, batas tempat node itu berada, apa yang terhubung ke apa, serta nilai dan lampiran yang dibawa setiap node. Graf adalah gambarannya.
Closure menyatakan apa yang ditarik untuk membangunnya, dan pada versi berapa. Setiap entitas yang dijangkau Release, baik menjadi node maupun tidak; dokumen bersama yang dirujuk entitas-entitas tersebut; dan plugin yang membentuk keluaran. Closure adalah daftar bahan (bill of materials).
Keduanya tidak dapat dipulihkan dari satu sama lain. Sebuah entitas dapat dijangkau tanpa pernah muncul sebagai node — Recipe yang dipetakan oleh sebuah Manifest untuk suatu tipe komponen dijangkau oleh setiap build dan tidak menjadi node di build mana pun — dan sebuah node tidak membawa versi hasil resolusi tipenya. Jadi pembaca yang bertanya “mengapa versi ini berubah?”, “apa yang akan terdampak jika dokumen bersama ini diubah?”, atau “sebenarnya Release ini bergantung pada apa?” sedang meminta closure, sedangkan pembaca yang bertanya “apa yang di-deploy Release ini?” sedang meminta graf.
Apa yang tidak dilakukan permintaan closure. Permintaan ini tidak merender apa pun dan tidak memublikasikan apa pun yang ditemukannya. Secara khusus, permintaan ini tidak memunculkan peringatan drift maupun saran render: keduanya milik permintaan yang memintanya, dan publikasi menggantikan seluruh lapisan diagnostik, sehingga daftar yang memublikasikan akan menghapus apa yang telah ditampilkan permintaan graf kepada pengguna. Mintalah graf jika Anda menginginkan putusan drift. Satu-satunya hal yang dipublikasikannya bukanlah temuannya sendiri: permintaan yang mendapati lockfile telah hilang akan menarik peringatan drift yang bergantung padanya, apa pun jenis permintaannya — lihat Kesadaran lockfile.
Permintaan ini memerlukan lockfile, seperti halnya graf. Versi yang dilaporkan daftar adalah versi hasil resolusi Release ini, dan workspace yang belum disiapkan siapa pun belum meresolusinya. Daftar yang dihasilkan tanpa lockfile akan melaporkan apa yang kebetulan dimiliki katalog saat ini, yang merupakan pertanyaan berbeda dari apa yang menjadi dependensi Release ini. Penolakan tersebut menyebutkan lockfile dan Release, sehingga klien dapat langsung menawarkan aggrega pull --release <release>.
kind pada entri closure hanya ada jika diketahui. Sebuah referensi dikumpulkan dari suatu posisi dalam dokumen, dan sebagian posisi menyatakan jenis yang dirujuknya sementara yang lain tidak. Field ini dilaporkan jika lokasi referensi mencatatnya dan dihilangkan jika tidak, alih-alih ditebak dari bentuk namanya. Field ini dilaporkan sebagai kata yang ditulis penulis di awal dokumen, yaitu kata yang sama yang digunakan setiap permukaan yang melaporkan closure untuk entri yang sama.
Kata yang sama meminta dokumen yang sama di tempat lain. aggrega inspect <release> --closure menjawab pertanyaan ini di baris perintah, dan mode release dari alat describe menjawabnya melalui protokol alat asisten. Ketiganya menjalankan satu resolusi atas Release, sehingga ketiganya tidak mungkin berbeda pendapat tentang dependensi sebuah Release. Lihat aggrega inspect “The dependency closure”.
Model cache
Operasi digerakkan oleh cache: panggil aggrega/validate untuk sebuah file sebelum hover / completion / resolve / diagnostics pada file tersebut. Panggilan pengisian itu tidak memerlukan Release — validasi yang tidak menyebut Release apa pun tetap mengurai buffer dan mengisi cache — sehingga operasi-operasi ini berfungsi di workspace yang tidak memiliki Release untuk disebut. Cache penguraian diperiksa terhadap waktu modifikasi setiap file di disk pada setiap pembacaan, sehingga suntingan eksternal (penyimpanan oleh editor, sebuah git checkout) terdeteksi secara otomatis — aggrega/invalidate dari editor adalah optimisasi, bukan persyaratan kebenaran.
Cache dimiliki oleh workspace yang mengisinya. File yang divalidasi di bawah satu workspace di-cache untuk workspace tersebut, sehingga path yang sama yang ditanyakan di bawah workspace lain dilaporkan sebagai belum divalidasi alih-alih dijawab dari entri milik workspace pertama. Hal inilah yang mencegah pertanyaan tentang workspace kedua menghasilkan jawaban yang salah ataupun membuat workspace pertama kehilangan keadaan hangatnya — dan aggrega/invalidate juga hanya membersihkan workspace yang disebutnya.
Meminta diagnostik saat validasi sedang berjalan
Validasi mengisi dua hal tentang sebuah file — hasil penguraian yang diserahkannya ke operasi lain, dan temuan yang dilaporkannya — dan keduanya diisi dengan selang waktu sesaat. aggrega/diagnostics adalah satu-satunya permintaan yang membaca keduanya: permintaan ini memerlukan hasil penguraian untuk mengetahui bahwa file tersebut dapat dijawabnya, dan menjawab berdasarkan temuan. Jadi, permintaan yang tiba di antara kedua saat itu akan memutuskan bahwa ia dapat menjawab padahal belum ada apa pun untuk menjawab.
Sebagai gantinya, permintaan itu menunggu. Kirim aggrega/diagnostics untuk file yang sedang divalidasi saat ini, dan balasannya tiba ketika validasi tersebut selesai, membawa apa yang ditemukannya. Hanya ada satu jawaban yang benar untuk file itu, apa pun waktunya, dan itulah jawaban yang Anda terima — jawabannya tidak pernah berupa daftar kosong untuk file yang validasinya akan melaporkan galat, yang merupakan satu-satunya jawaban salah yang tidak dapat dipulihkan oleh klien, karena tidak ada yang mendorong Anda untuk bertanya lagi tentang file yang telah dinyatakan bersih. Operasi berbasis posisi lainnya — hover, completion, resolve, findReferences, findImplementations — membaca hasil penguraian dan menjawab dari hasil penguraian, sehingga tidak ada yang perlu ditunggu dan operasi tersebut tidak pernah menunggu.
Dua hal mengakhiri penantian lebih awal, dan keduanya sudah Anda miliki. $/cancelRequest untuk id permintaan tersebut menghentikannya, dan aggrega/shutdown yang kooperatif juga menghentikannya. Keduanya tidak memerlukan tambahan apa pun pada permintaan.
Dan penantian itu dibatasi. Jika validasi belum selesai dalam batas waktu yang ditetapkan daemon untuknya, permintaan ditolak dengan kode validation-in-flight alih-alih dijawab kosong — lihat Kode galat. Penolakan itu berarti pekerjaan yang Anda tunggu memang sedang berlangsung, sehingga yang perlu dilakukan adalah bertanya lagi sebentar kemudian; ini bukan isyarat untuk mengirim validasi lain, yang hanya akan menambah pekerjaan tanpa menjawab apa pun.
Daemon yang menjalankan permintaan satu per satu menjawabnya sesuai urutan kedatangan, sehingga tidak ada yang tumpang tindih dan tidak pernah terjadi penantian. Daemon yang menjalankannya secara bersamaan menjawab pertanyaan yang sama dengan cara yang sama, dan penantian itulah yang membuatnya demikian: jawaban yang Anda terima adalah jawaban yang akan diberikan oleh urutan serial.
Ukuran dalam sebuah jawaban
Jawaban yang melaporkan suatu kuantitas byte melaporkannya dua kali: sebagai angka, dan sebagai kuantitas yang sama dalam bentuk tertulis. Field tertulis adalah nama field numerik dengan tambahan Text — size dan sizeText, totalSize dan totalSizeText, reclaimedBytes dan reclaimedBytesText, dan seterusnya untuk setiap jawaban yang memuat ukuran.
Tampilkan bentuk tertulisnya dan lakukan perhitungan dengan angkanya. Tujuan mengirim keduanya adalah agar klien tidak pernah perlu menuliskan ukuran sendiri: daemon menuliskannya dengan formatter yang sama dengan yang digunakan baris perintah, sehingga aggrega cache status dan aggrega/cacheStatus menampilkan suatu cache secara identik, hingga ke pembulatannya. Klien yang menyusun teksnya sendiri akan menyimpang dari itu begitu pertama kali berbeda pendapat tentang suatu batas.
Bentuk tertulis menggunakan satuan biner — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — yang merupakan kosakata yang sama dengan yang diterima aggrega/cacheEvict dalam maxSize, sehingga ukuran yang dibaca dari satu jawaban dapat dikirim kembali dalam permintaan berikutnya tanpa ditulis ulang. Di atas satuan byte, teks memuat satu angka desimal, sehingga teks menyebut kuantitas sebagaimana ingin dilihat pembaca, bukan hingga ke byte; ketika Anda memerlukan jumlah persisnya, untuk itulah field numerik tersedia.
Jika angkanya opsional, teksnya ikut opsional, dan keduanya tidak pernah hadir setengah-setengah: ukuran plugin pada jawaban publish memuat pluginSize dan pluginSizeText bersamaan atau tidak memuat keduanya.
Setiap permintaan menyebut workspace yang menjadi subjeknya
Kirim workspaceRoot pada setiap permintaan: path absolut dari root workspace yang menjadi sasaran permintaan tersebut. Daemon tidak memiliki workspace sendiri dan tidak mengingat workspace apa pun di antara permintaan, sehingga jawaban atas suatu permintaan hanya menyangkut workspace yang disebutnya dan tidak ada yang lain. Dua permintaan yang menyebut dua workspace mendapatkan dua jawaban, dan tidak satu pun dapat melihat entitas, Releases, hasil parse yang di-cache, atau diagnostik milik yang lain.
Permintaan yang tidak menyebut workspace apa pun ditolak dengan galat invalid-params standar yang menyebut parameter tersebut, demikian pula nilai kosong, yang tidak menyatakan workspace apa pun dan dijawab sebagai workspace yang tidak ada. Dua bentuk lain ditolak dengan alasan yang sama, masing-masing disebut dalam pesannya: path relatif, karena root workspace tidak memiliki acuan untuk menjadi relatif; dan path yang bukan direktori yang ada, karena workspace adalah sebuah pohon.
Tiga permintaan tidak memerlukan workspaceRoot, masing-masing karena subjeknya bukan workspace. aggrega/getSchema dan aggrega/scaffoldEntity menjawab dari skema yang dikompilasi ke dalam biner yang sedang berjalan, sehingga workspace tidak menyumbang apa pun bagi keduanya — itulah yang memungkinkan keduanya menjawab di direktori yang belum disiapkan siapa pun. aggrega/initialize adalah yang ketiga, dan di sanalah Anda mendeklarasikan workspace alih-alih bertindak atasnya. Bentuk lain aggrega/scaffoldEntity, yaitu menulis atau mencantumkan contoh dokumentasi yang dapat dijalankan, memang bertindak atas workspace, dan permintaan untuknya menyebutkan workspace seperti permintaan lainnya.
Status cache setiap workspace disimpan secara terpisah, dan menyebut workspace kedua tidak merugikan yang pertama. Indeks katalog, cache parse, dan diagnostik suatu workspace milik workspace tersebut, sehingga pertanyaan tentang tempat lain tidak mengusir apa yang telah dikumpulkan editor untuk folder yang sedang dibuka seseorang. Dua penulisan dari satu root adalah satu workspace, sehingga path yang memuat . di tengah atau pemisah ganda mencapai status hangat yang sama dengan bentuk polosnya.
Mendeklarasikan workspace yang diagnostiknya ingin Anda terima melalui push
Diagnostik dikirim melalui dua cara: Anda memintanya, atau daemon mendorongnya (push). Daemon hanya mendorong untuk workspace yang Anda deklarasikan saat handshake. Setiap permintaan lain menjawab dengan temuannya dalam responsnya sendiri dan tidak mendorong apa pun.
Deklarasikan dengan mengirim workspaceRoot pada aggrega/initialize. Hanya itulah yang dilakukan deklarasi tersebut — deklarasi ini tidak menjangkarkan apa pun, dan tidak ada permintaan berikutnya yang dijawab berdasarkan deklarasi itu.
Alasan membatasinya adalah tujuan dari diagnostik yang didorong. Push itulah yang menjaga daftar masalah editor tetap mutakhir saat seseorang mengetik, dan justru keliru dilakukan untuk jawaban yang tidak diminta siapa pun: tanpa aturan ini, pertanyaan tentang workspace kedua — misalnya oleh alat lain yang berbagi daemon — akan mengisi daftar masalah pembaca dengan temuan tentang file yang tidak pernah mereka buka. Membatasi push menjaga pertanyaan satu pemanggil agar tidak masuk ke daftar masalah pemanggil lain.
Field ini opsional, dan tiga maksud yang dapat Anda sampaikan melaluinya dapat dibedakan:
| yang Anda kirim | tujuan push | yang dilaporkan handshake |
|---|---|---|
| tidak ada | workspace tempat proses dijalankan | workspace tersebut |
| sebuah root workspace | workspace tersebut | workspace tersebut |
| string kosong | tidak ke mana pun — tidak ada diagnostik yang pernah didorong | root kosong |
Tidak mengirim apa pun membiarkan pengiriman diagnostik tetap pada workspace tempat proses dijalankan, sehingga klien yang tidak mendeklarasikan apa pun menerima diagnostik untuk workspace tersebut. Mengirim string kosong adalah deklarasi yang jujur bagi pemanggil yang bukan editor dan tidak memiliki daftar masalah untuk disinkronkan: setiap temuan tetap sampai kepadanya, pada respons atas permintaan yang menghasilkannya.
Workspace yang dideklarasikan di-resolve persis seperti workspace yang disebut dalam permintaan, sehingga deklarasi yang menyebut path relatif, atau path yang bukan direktori, ditolak saat handshake alih-alih membiarkan push diarahkan ke tempat yang tidak terduga.
Root workspace dan Release aktif
Daemon me-resolve setiap workspace yang disebutkan oleh sebuah permintaan dengan cara yang sama seperti setiap perintah aggrega me-resolve-nya, dan Configuration memuat apa yang menjangkarkan sebuah root dan dalam urutan apa. Dua konsekuensi penting bagi klien. Sebuah .aggrega-config.yaml tanpa blok workspace: tidak menjangkarkan: file itu tetap menyumbangkan pengaturannya, tetapi file pengaturan saja tidak dapat mengubah setiap direktori induk menjadi root workspace. Dan ketika tidak ada yang menjangkarkan, direktori kerja yang digunakan — daemon tetap berjalan dan operasi hanya tidak me-resolve apa pun, alih-alih menolak dijalankan.
Proses juga diluncurkan atas sebuah workspace, dari --workspace-root atau dengan menelusuri ke atas dari direktori kerjanya, dan resolusi itu melakukan dua hal dan tidak lebih: menentukan ukuran pool worker, yang merupakan properti proses dan bukan properti permintaan mana pun, dan menjadi deklarasi default untuk diagnostik yang di-push. Tidak ada permintaan yang dijawab berdasarkan resolusi itu.
Konfigurasi juga merupakan kaskade yang sama yang dibaca setiap perintah, dan Configuration adalah tempat kaskade itu dijelaskan. Yang ditambahkan daemon hanyalah bahwa pembacaan konfigurasi setiap workspace dilakukan sekali, ketika workspace itu pertama kali disebutkan, lalu digunakan kembali untuk setiap permintaan berikutnya tentang workspace itu. File konfigurasi yang akan dibaca kaskade itu dan merupakan tautan yang mengarah ke luar workspace — .aggrega-config.yaml milik workspace itu sendiri, atau overlay milik CI di sebelahnya — tidak dibaca, di sini maupun di terminal, dan tidak ada hal lain yang akan dikonfigurasi file itu yang dibaca sebagai gantinya. Yang berbeda dari terminal adalah apa yang tetap menjawab. Daemon yang diluncurkan atas workspace seperti itu tetap berjalan, dan menyatakannya sekali di aliran error-nya; permintaan yang menyebut workspace seperti itu dijawab sebagai berikut dalam kedua kasus. aggrega/releaseCandidates dan aggrega/catalogIndex — dua permintaan yang mencantumkan isi sebuah workspace — menjawabnya, dibaca tanpa konfigurasi apa pun: dokumen milik workspace itu sendiri dicantumkan, tidak ada direktori katalog yang dibaca, dan file yang ditahan disebutkan dalam unreadLinkedFiles, terlepas dari apakah pencarian menemuinya atau tidak. Nama itu adalah cara klien mengetahui bahwa konfigurasi workspace mengarah ke luarnya. Setiap permintaan lain yang menyebut workspace itu — build, graf, validasi, Release default, konfigurasi efektif, penulisan, dan aggrega/catalogIndex dalam konteks sebuah Release — ditentukan oleh konfigurasi itu, sehingga ditolak dengan error invalid-params yang membawa E0321 — read-leads-out-of-workspace dalam data error tersebut — dan kalimat yang menyebutkan tautan itu serta ke mana ia mengarah. Handshake juga menjawab untuk workspace seperti itu, dengan melaporkan defaults sebagai configSource-nya, karena tidak ada file konfigurasi yang menyumbangkan apa pun yang digunakan daftar-daftar itu untuk menjawab. Hapus tautan itu, atau buat agar mengarah ke file di dalam workspace, dan permintaan berikutnya akan membaca konfigurasi. Di bawah file-file proyek terdapat lapisan global: file yang disebutkan --config pada baris perintah yang memulai daemon, untuk setiap workspace yang dilayaninya; jika tidak, file yang disebutkan variabel lingkungan AGGREGA_CONFIG ketika variabel itu diatur; dan jika tidak, lokasi default — di Windows aggrega\config.yaml di dalam direktori yang disebutkan variabel lingkungan APPDATA, dan di tempat lain aggrega/config.yaml di dalam direktori yang disebutkan XDG_CONFIG_HOME, dengan cadangan ~/.config/aggrega/config.yaml — dimuat jika ada. Default bawaan berada di bawahnya.
Operasi yang bekerja pada sebuah Release menerimanya sebagai parameter; daemon tidak memilih Release sendiri. Sebuah workspace tetap mendeklarasikan Release mana yang ditunjuknya, dan kaskade empat langkah membaca deklarasi itu: field konfigurasi build.authoring_release, lalu file penanda .aggrega/active-release, lalu heuristik satu-Release-dalam-workspace, lalu fallback khusus Aggregate. Karena itu, penanda yang Anda tulis lebih diutamakan daripada heuristik, dan penanda yang menyebut Release yang tidak dapat dimuat akan berlanjut ke heuristik, bukan ke fallback. Penanda yang menyebut Release di luar workspace — melalui path absolut, path yang naik keluar dari root, atau tautan yang mengarah ke luarnya — tidak dibaca, kecuali konfigurasi workspace Anda menyebut Release itu sebagai build.authoring_release atau sebagai kunci dari workspace.releases: konfigurasi adalah cara untuk menjangkau Release yang disimpan di luar workspace, dan penanda bukan. Kaskade kemudian berlanjut persis seperti untuk penanda yang tidak dapat dimuatnya, dan ketika tidak menghasilkan apa pun, trace menjelaskan alasannya pada baris penanda dan reason dalam kalimatnya tentang penanda.
aggrega/activeRelease melaporkan apa yang dipilih kaskade itu, dan merupakan saran bagi klien, bukan pengaturan yang dijalankan daemon. Tanyakan kepada daemon alih-alih membaca sendiri input kaskade: field konfigurasi dan file penanda adalah dua dari empat input, sehingga input mana pun yang Anda baca hanya menyebut pilihan workspace jika kebetulan input itulah yang menang. Penanda yang menyebut Release yang tidak dapat dimuat adalah contoh paling jelas — kaskade memilih Release yang sama sekali berbeda, sedangkan pembaca penanda akan melaporkan Release yang gagal.
Kaskade berjalan ketika Anda meminta dan tidak sebelumnya, yang memiliki dua konsekuensi yang dapat diandalkan. Handshake tetap cepat berapa pun ukuran pohonnya, karena tidak menunggu penelusuran workspace. Dan jawabannya mengikuti workspace: tulis penanda — dengan aggrega/setActiveRelease, yang menjawab dengan pilihan baru itu sendiri — ubah konfigurasi, tambahkan atau hapus file Release, lalu tanyakan lagi, dan Anda mendapatkan jawaban baru dari daemon yang sama. Mengganti Release yang Anda kerjakan tidak pernah memerlukan restart daemon — klien mengirim release yang berbeda pada permintaan berikutnya.
Operasi yang mencari di seluruh workspace alih-alih satu buffer — completion, hover, resolve, findReferences dan findImplementations — mengenumerasi YAML di bawah root workspace, dan enumerasi itu mematuhi .gitignore. Setiap .gitignore dari root workspace hingga direktori file itu sendiri ikut berkontribusi, dengan yang terdekat yang menang, sehingga file YAML yang diabaikan repositori Anda tidak ditawarkan sebagai kandidat completion dan tidak dilaporkan sebagai definisi atau referensi. .gitignore yang merupakan tautan yang mengarah ke luar workspace tidak dibaca, sehingga file di tempat lain pada mesin tidak pernah menentukan dokumen workspace mana yang dicari. Karena itu, pohon vendor dan output yang dihasilkan tetap berada di luar hasil lintas file tanpa pengaturan pengecualian terpisah yang perlu dipelihara — dan dokumen yang Anda harapkan ditemukan tetapi telah Anda abaikan tidak akan muncul, yang merupakan satu-satunya kasus yang perlu diperiksa ketika sebuah referensi tampaknya hilang. Components dan Features yang juga ditawarkan completion dari catalog_dirs yang Anda konfigurasi adalah pembacaan yang berbeda: semuanya berasal dari direktori-direktori itu sebagaimana dikonfigurasi — direktori yang sama yang dibaca build sebuah Release ketika konfigurasi tidak memberi Release itu direktori sendiri, atau, untuk permintaan yang menyebut sebuah Release, direktori milik Release itu sendiri — sehingga entitas direktori katalog ditawarkan terlepas dari apakah .gitignore mencakupnya atau tidak — kecuali entitas yang berada di balik tautan yang mengarah ke luar direktori tempat pembacaan direktori katalog harus tetap berada, yang tidak dibaca dan tidak ditawarkan.
Permintaan yang menyebut sebuah Release membaca direktori katalog Release tersebut, yaitu direktori yang dibaca oleh build Release itu di terminal: direktorinya sendiri, jika konfigurasi workspace memberinya direktori di bawah workspace.releases, dan catalog_dirs milik workspace jika tidak. Hal ini mencakup aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate dan aggrega/lint yang menyebut sebuah Release, aggrega/attachCandidates dan aggrega/attachmentContainer yang ditujukan ke sebuah node dalam graf sebuah Release, serta aggrega/connectionAtPosition, dan permintaan yang dicantumkan bagian berikutnya ketika permintaan itu menyebut sebuah Release. Dengan demikian, satu sesi menjawab setiap Release dalam workspace yang menyimpan satu varian katalog per Release, masing-masing dari variannya sendiri, tanpa ada yang dikirim selain path Release tersebut. Permintaan yang tidak menyangkut satu Release tertentu — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover dan resolve yang tidak menyebut Release, serta aggrega/attachCandidates yang ditujukan ke sebuah entitas atau sekumpulan label — membaca catalog_dirs milik workspace. aggrega/lint yang tidak menyebut entitas maupun Release menjadi pengecualian dalam workspace yang menyebut beberapa Releases di bawah workspace.releases: di sana perintah ini memeriksa seluruh katalog sekali untuk setiap Release, dengan setiap putaran membaca direktori Release tersebut, sebagaimana dijelaskan dalam Memublikasikan konvensi, atas permintaan dan pada setiap suntingan. Lihat Memberi sebuah Release direktori katalognya sendiri.
Menjawab dalam konteks satu Release
aggrega/catalogIndex, aggrega/entityDefinition dan lima permintaan yang berawal dari posisi kursor — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences dan aggrega/findImplementations — tidak menyangkut satu Release tertentu, dan masing-masing menerima release opsional yang membuatnya menyangkut satu Release. Nilainya adalah path relatif terhadap root workspace, yang tunduk pada kontrak yang sama dengan permintaan lain yang menerima Release; nilai yang tidak menyebut file Release, atau yang menyebut sebuah direktori, ditolak alih-alih dijawab dalam konteks workspace sementara tampak seolah-olah dalam konteks Release tersebut.
Apa yang dijangkau sebuah Release, untuk setiap permintaan di sini: dokumen workspace di bawah direktori katalog yang dibaca stack-nya, dan setiap dokumen workspace yang sama sekali tidak berada di bawah direktori katalog mana pun — sebuah Release, Aggregate-nya, dan Manifest-nya yang ditulis di samping katalog. Dokumen workspace di bawah direktori katalog yang hanya dibaca oleh Releases lain bukan bagian dari jawabannya: tidak dicantumkan, tidak di-resolve, tidak ditawarkan. Itulah yang mencegah varian-varian dari satu entitas, yang disimpan berdampingan untuk Releases yang berbeda, tercampur.
- Daftar. Menyebut sebuah Release akan mencantumkan entitas yang dilihat Release tersebut. Features yang dicantumkan adalah yang dideklarasikan oleh direktori katalog Release itu, dan dokumen workspace di bawah direktori katalog yang hanya dibaca oleh Releases lain tidak disertakan — sehingga workspace yang menyimpan satu varian entitas per Release mencantumkan satu varian yang dipakai Release tersebut untuk build, bukan setiap varian secara berdampingan. Dokumen yang sama sekali tidak berada di bawah direktori katalog mana pun, seperti sebuah Release, Aggregate-nya, dan Manifest-nya yang ditulis di samping katalog, termasuk dalam daftar setiap Release.
- Pencarian berdasarkan nama. Menyebut sebuah Release akan me-resolve nama melalui direktori katalog Release tersebut, sehingga nama yang dideklarasikan oleh beberapa varian di-resolve ke varian yang dipakai Release itu untuk build. Nama yang tidak dapat di-resolve oleh direktorinya ditolak dengan penjelasan yang menyebut entri Release tersebut di bawah
workspace.releases, karena entri itulah yang dibaca oleh pencarian. Referensi registry tidak menerima Release, dan ditolak jika disertai Release: referensi itu dibaca dari registry yang memublikasikannya, Release mana pun yang disebut. - Hover dan go-to-definition. Jika sebuah Release disebut, referensi di kursor pertama-tama di-resolve melalui direktori katalog Release tersebut, dalam urutan yang diberikan konfigurasi workspace — resolusi yang sama dengan yang dilakukan pencarian berdasarkan nama dalam konteks Release itu — sehingga entitas yang ditampilkan, dan dokumen yang dibuka, adalah varian yang dihasilkan resolusi direktori tersebut, bahkan jika dokumen workspace di tempat lain mendeklarasikan nama yang sama. Hanya jika tidak ada dokumen di bawah direktori tersebut yang menjawabnya, dokumen workspace yang dijangkau Release itu akan dicari. Jika tidak ada Release yang disebut, urutannya terbalik: dokumen workspace dicari terlebih dahulu, sehingga referensi yang dijawab oleh dokumen workspace mempertahankan jawaban itu, dan
catalog_dirsmilik workspace hanya dirujuk jika tidak ada dokumen yang mendeklarasikan nama tersebut — yang memungkinkan ditemukannya entitas yang hanya dimiliki direktori katalog yang dikonfigurasi, termasuk yang berada di luar pohon workspace. Jika editor menyimpan salinan yang belum disimpan dari dokumen hasil resolusi direktori sebuah Release, dan salinan itu masih mendeklarasikan nama tersebut, jawabannya dibaca dari salinan itu, sehingga posisi jatuh pada baris yang ditampilkan editor. - Completion. Jika sebuah Release disebut, nama yang ditawarkan adalah nama yang dideklarasikan oleh dokumen workspace yang dijangkau Release tersebut, bersama dengan Components dan Features yang dideklarasikan oleh direktori katalog Release itu.
- Referensi dan implementasi. Jika sebuah Release disebut, lokasi dalam dokumen workspace yang tidak dijangkau Release tersebut tidak dilaporkan, sehingga varian yang disimpan untuk Release lain tidak pernah dicantumkan sebagai referensi atau implementasi Release ini.
- Apa yang dapat dilampirkan ke node graf.
aggrega/attachCandidatesyang ditujukan ke sebuah node dalam graf sebuah Release selalu berada dalam konteks Release tersebut — lihat Apa yang disampaikan respons attach-candidate kepada Anda.
Jika tidak ada Release yang disebut, jawaban diberikan berdasarkan direktori katalog milik workspace sendiri, sebagaimana dijelaskan paragraf di atas.
Menjangkau registry, dan menulis
Sebagian besar permintaan di sini menjawab dari workspace dan dari apa yang sudah ada di cache, dan tidak menulis apa pun. Sejumlah kecil permintaan tertentu melakukan lebih dari itu, dan permintaan tersebut terbagi menurut dua sumbu yang saling independen: apa yang dijangkau oleh suatu permintaan, dan seberapa jauh dampak dari apa yang diubahnya.
Permintaan yang keluar ke registry terbagi menjadi permintaan yang membaca dan permintaan yang memublikasikan. aggrega/resolveDependencies mengambil apa yang dibutuhkan oleh suatu Release, dan aggrega/build ikut serta — dan hanya ketika — field autoPull-nya memintanya untuk menyelesaikan dependensi terlebih dahulu, dalam hal ini permintaan tersebut menjangkau registry dan menulis lockfile sebelum merender; aggrega/registryUpdate menelusuri setiap registry yang dikonfigurasi untuk membangun ulang indeks pencarian lokal; aggrega/pluginAdd mencari plugin yang disebutkan oleh permintaan di registry yang dikonfigurasi dan membaca versi-versinya yang telah dipublikasikan untuk mem-pin salah satunya; aggrega/registryAdd meminta kepada registry yang didaftarkannya kebijakan kepercayaan yang diiklankan oleh registry tersebut, kecuali jika permintaan menolak pengambilan itu atau menyertakan kebijakannya sendiri, dan aggrega/configInit meminta hal yang sama kepada registry yang sedang disemainya; aggrega/explainError memperoleh bundel dokumentasi yang menjadi sumber bacaan penjelasan langkah demi langkah suatu kondisi, satu kali, jika cache yang dibagikan oleh setiap proyek di mesin tersebut tidak menyimpan salinan yang lolos pemeriksaan tanda tangan milik workspace itu sendiri — lihat aggrega explain; aggrega/scaffoldEntity yang dikirimi example atau list memperoleh bundel yang sama dengan ketentuan yang sama, lalu pada penulisan menulis contoh ke direktori baru di workspace; aggrega/import mengambil importer inti dari registry default workspace, satu kali, jika mesin belum menyimpannya, dan, di workspace yang tidak menyebutkan folder katalog apa pun, snapshot katalog terbitan yang dibacanya — lihat Apa yang disampaikan respons import kepada Anda; dan aggrega/entityDefinition membaca entitas yang dirujuk oleh referensi registry ketika referensi tersebut dikirim sebagai name-nya, tanpa menulis apa pun. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts dan aggrega/deprecateArtifact menulis ke registry — byte, tanda tangan, atau penanda penarikan. Suatu permintaan menjangkau registry hanya ketika permintaan itu dikirim untuk melakukannya: daftar melaporkan apa yang di-pin oleh konfigurasi, pencarian membaca snapshot offline, dan publikasi yang diminta dengan dryRun menghitung apa yang akan dikirimnya tanpa menghubungi siapa pun.
Aturan ini menyangkut kapan suatu operasi berjalan, bukan permukaan mana yang menjalankannya. Operasi yang mengambil atau menulis berjalan karena suatu permintaan menyebutkannya, dan tidak pernah sebagai efek samping dari memvalidasi dokumen, memeriksa graf, atau mendaftar entitas suatu workspace. Jadi, editor yang memvalidasi pada setiap ketukan tombol tidak menjangkau jaringan dan tidak menulis ulang lockfile, sedangkan tindakan “resolve dependencies” yang diklik pengguna melakukan tepat apa yang dilakukan aggrega pull — resolusi yang sama, di balik kedua permukaan, yang menulis lockfile yang identik byte demi byte dan mengisi cache artefak yang sama.
Tidak ada yang ditanyakan melalui prompt. Tidak ada yang mengamati aliran ini, sehingga identitas diselesaikan dari sumber kredensial yang disertakan atau yang tersedia di lingkungan, dan tidak pernah dengan bertanya. Di mana perintah terminal akan mengajukan pertanyaan kepada seseorang — registry yang memerlukan kredensial, kapabilitas yang dilayani oleh lebih dari satu plugin provider, teks yang harus dibawa oleh suatu penarikan — permintaan gagal dengan pesan yang menyebutkan apa yang harus disertakan, alih-alih tertahan menunggu jawaban yang tidak akan pernah datang. Penolakan membiarkan workspace persis seperti semula: tidak ada lockfile yang ditulis dan tidak ada catatan parsial yang tertinggal, dan publikasi yang tidak dapat menyelesaikan kredensial menolak sebelum byte apa pun mencapai registry.
Beberapa perubahan menjangkau melampaui workspace ini, dan jawabannya menyebutkan yang mana
Suatu permintaan menyebutkan satu workspace, sehingga jawaban yang tidak menyebutkan apa pun tentang jangkauannya sendiri terbaca sebagai jawaban tentang workspace tersebut. Untuk beberapa permintaan ini, pembacaan itu keliru, sehingga masing-masing membawa cakupannya, dan klien sebaiknya menampilkannya sebelum bertindak berdasarkan hasilnya.
Memublikasikan, menandatangani, dan menarik menjangkau sepenuhnya melampaui mesin, yang merupakan jangkauan terluas dari apa pun di sini. Penulisan lain di bawah ini mengubah apa yang diselesaikan oleh mesin ini; ketiganya mengubah apa yang dilakukan oleh setiap orang yang melakukan resolusi dari registry tersebut. Byte yang dipublikasikan adalah apa yang diterima setiap konsumen registry tersebut, dan memublikasikan ulang konten yang berbeda di atas suatu tag ditolak alih-alih ditawarkan, sehingga tidak ada permintaan di sini yang menarik kembali publikasi — jawabannya adalah memublikasikan versi baru. Tanda tangan dan penanda penarikan dilampirkan sebagai sibling dari artefak alih-alih menggantikannya, sehingga byte itu sendiri tidak tersentuh; tetapi siapa pun yang mengambil artefak setelahnya juga mengambil keduanya, dan keduanya tidak dapat ditarik kembali dari siapa pun yang sudah memilikinya. Penarikan adalah yang paling berisiko disalahartikan di antara ketiganya: versinya tetap dapat diambil, sedangkan retraksi yang dipercaya oleh suatu workspace mengeluarkannya dari apa yang akan dipilih oleh resolusi di sana.
Penandatanganan menggunakan kredensial, dan asal kredensial tersebut perlu diketahui sebelum Anda menghubungkan klien. Penandatanganan tanpa kunci menyelesaikan token identitas, secara berurutan, dari identityToken pada permintaan, lalu AGGREGA_IDENTITY_TOKEN di lingkungan daemon, lalu endpoint OIDC GitHub Actions yang tersedia di lingkungan jika dapat dijangkau, lalu SIGSTORE_ID_TOKEN. Jika tidak ada satu pun yang menghasilkan token, operasi menolak dan menyebutkan apa yang harus dikirim; operasi tidak pernah membuka browser, karena tidak ada yang akan melihatnya. Penandatanganan dengan kunci adalah alternatif offline, dan suatu permintaan tidak menyebutkan path kunci: apa yang dibaca oleh suatu permintaan berada di dalam workspace yang disebutkannya, dan kunci privat tidak pernah disimpan di dalam workspace, sehingga kunci diambil dari blok signing: dalam konfigurasi workspace itu sendiri. Lihat aggrega sign untuk kedua mode penandatanganan dan apa yang dihubungi oleh masing-masing.
Keempat jawaban tersebut masing-masing membawa reach, yang berisi registries — setiap host registry yang dituju oleh panggilan, masing-masing disebutkan sekali, dalam urutan pertama kali dituju oleh panggilan, sehingga batch penandatanganan atau file batch yang referensinya mencakup beberapa registry menyebutkan masing-masing — dan beyondThisMachine, yang diturunkan dari apa yang benar-benar dilampirkan oleh panggilan, bukan dari apa yang dimintanya: bernilai true tepat ketika panggilan mengunggah konten atau melampirkan tanda tangan, tanggal publikasi, atau penanda deprecation, dan false untuk dry run dan untuk panggilan yang mendapati semua yang akan dilampirkannya sudah ada — publikasi yang dijalankan ulang atas versi yang sudah lengkap, atau batch penandatanganan yang setiap referensinya sudah membawa tanda tangan yang terverifikasi. Dry run tetap menyebutkan tujuan yang akan ditujunya. Tampilkan sebelum bertindak berdasarkan hasilnya.
Mendaftarkan atau menghapus registry menulis konfigurasi yang dibagikan di semua workspace pada mesin, secara default. Registry dan identitas yang Anda percayai di dalamnya biasanya sama di mana pun Anda bekerja, sehingga di sanalah entri tersebut ditempatkan kecuali permintaan mengirim workspace: true. Konsekuensinya perlu dinyatakan dengan jelas: aggrega/registryAdd dan aggrega/registryRemove mengubah apa yang menjadi jalur resolusi setiap proyek di mesin tersebut, termasuk proyek yang tidak disebutkan oleh siapa pun dalam sesi ini. Kedua jawaban membawa scope, dengan configFile yang ditulis dan machineWide yang menyatakan apakah file tersebut adalah file bersama. Penghapusan adalah yang lebih berisiko di antara keduanya, karena menambahkan kembali bukanlah tindakan yang sama — kebijakan kepercayaan yang telah di-pin hilang, dan pendaftaran berikutnya mem-pin apa pun yang diiklankan registry pada saat itu.
Menyemai konfigurasi menulis file bersama yang sama secara default, dan karena alasan yang sama. aggrega/configInit mendaftarkan registry beserta kebijakan kepercayaannya, yang merupakan perkakas untuk seluruh mesin, sehingga tanpa override ia menulis konfigurasi yang menjadi jalur resolusi setiap proyek di mesin tersebut — dan ia menjangkau registry tersebut satu kali untuk membaca kebijakan yang diiklankannya. Jawabannya membawa pasangan scope yang sama dengan yang dibawa oleh kedua metode registry. Ia berbeda dari keduanya dalam satu hal yang dapat diandalkan: ia menolak alih-alih menimpa file konfigurasi yang sudah ada, sehingga ia tidak dapat menggantikan konfigurasi yang sedang digunakan seseorang kecuali permintaan mengirim force. Pembekuan adalah kasus sebaliknya: aggrega/configCapture tidak menerima override sama sekali, selalu menulis file konfigurasi milik proyek itu sendiri dan tidak menjangkau registry, sehingga tidak ada yang dilakukannya yang terlihat oleh proyek lain. Lihat Apa yang ditinggalkan oleh penulisan konfigurasi.
🔴 Menambahkan atau menghapus plugin ekstensi perintah secara default menulis berkas bersama yang sama, dan inilah yang perlu dibaca dengan cermat. aggrega/pluginAdd dan aggrega/pluginRemove menerima type, dan tipe tersebut menentukan ke mana penulisan dilakukan bila tidak ada penimpaan yang dikirim. Entri provider, governance, linter atau importer membentuk build satu proyek, sehingga ditulis ke konfigurasi milik proyek itu sendiri. Entri cli adalah perkakas tingkat mesin, sehingga penambahan bertipe cli yang tidak menyebut global maupun workspace mendaftarkan perintah tersebut di berkas konfigurasi global yang digunakan oleh setiap workspace di mesin ini untuk resolusi — perintah itu menjadi perintah aggrega tingkat atas bagi setiap proyek di mesin tersebut, termasuk proyek yang tidak disebut oleh siapa pun dalam sesi ini, dan menariknya kembali merupakan penghapusan tersendiri, bukan pembatalan. Kirim workspace: true agar tetap lokal. Kedua jawaban membawa scope, dengan configFile yang ditulis dan machineWide yang menyatakan apakah berkas itu adalah berkas bersama, diturunkan dari berkas yang menjadi tujuan resolusi penulisan. Penambahan juga menjangkau registry yang dicarinya, sehingga berada pada kedua sumbu sekaligus. Lihat Apa yang diberitahukan oleh perubahan plugin.
Dua permintaan plugin lainnya hanya menulis di dalam workspace. aggrega/pluginSync menulis berkas entitas Plugin yang disebut permintaan, dan aggrega/pluginGenCatalog menulis entitas yang dihasilkan di bawah outputDir yang disebut permintaan — keduanya di dalam workspace yang disebut permintaan, keduanya menolak tujuan yang absolut atau yang teresolusi ke luar workspace, dan tidak satu pun terlihat oleh proyek lain. aggrega/pluginGenCatalog membaca modul dan overlay-nya dari mana pun Anda memilihnya, dan hal itu tidak memperluas tempat ia menulis: keduanya diresolusi dengan aturan yang berbeda, sehingga suatu pembuatan dapat membaca modul yang Anda build di mana saja sementara entitas yang dihasilkannya tetap berada di dalam workspace. aggrega/pluginGenCatalog dengan dryRun tidak menulis apa pun dan sebagai gantinya mengembalikan kontennya.
Mem-pin entitas juga hanya menulis di dalam workspace, dan menjangkau host yang disebut oleh sumbernya. aggrega/pin menulis entity.lock di samping entitas yang disebut permintaan, yang merupakan path di dalam workspace, dan mengisi cache konten workspace dengan sumber yang diambilnya; tidak ada yang ditulisnya yang terlihat oleh proyek lain. Ia menjangkau ke luar untuk meresolusi setiap sumber jarak jauh yang disebut entitas — repositori chart, host Git, URL — yang merupakan jangkauan yang sama dengan yang dimiliki aggrega/resolveDependencies untuk sumber yang dikonsumsi sebuah Release. aggrega/resolveDependencies dan aggrega/publishEntity yang dikirimi pinSources menjalankan langkah yang sama ini, sehingga masing-masing juga menulis di samping entitas yang di-pin-nya; dengan demikian, publikasi yang mem-pin menjangkau workspace sekaligus registry. Publikasi yang tidak mem-pin tidak menulis apa pun di samping entitas, namun tetap menjangkau host tersebut: membandingkan lock dengan apa yang akan dicatat oleh langkah itu berarti mengambil secara penuh setiap sumber jarak jauh yang dituliskan entitas.
Memasang skill asisten tetap berada di dalam workspace kecuali permintaan mengirim global. aggrega/skillsInstall menulis folder skill proyek setiap asisten yang disebut di dalam workspace yang disebut permintaan, dan tidak ada yang ditulisnya di sana yang terlihat oleh proyek lain; scope jawabannya membawa machineWide bernilai false. Dengan global: true, metode ini justru menulis folder per pengguna setiap asisten di bawah direktori home, yang dibaca asisten tersebut di setiap proyek di mesin, dan machineWide bernilai true. Dalam kedua kasus, metode ini tidak menjangkau registry mana pun maupun jaringan.
Menghapus kredensial yang tersimpan menjangkau lebih luas daripada apa pun di sini yang berhenti di mesin ini. aggrega/logout mengubah penyimpanan kredensial, dan penyimpanan itu digunakan bersama tidak hanya oleh setiap proyek di mesin tetapi juga oleh setiap alat lain yang melakukan autentikasi ke registry yang sama — sehingga kredensial yang dihapus melalui suatu sesi hilang bagi semuanya, dan aggrega/registryList akan melaporkannya tidak ada di setiap workspace lain juga. Jawabannya membawa scope dengan machineWide, yang selalu bernilai true: penyimpanan ini tidak memiliki bentuk berlingkup workspace untuk diresolusi, sehingga tidak ada penimpaan untuk dikirim dan tidak ada yang dapat dipilih oleh permintaan. scope sengaja tidak menyebut berkas, berbeda dengan penulisan konfigurasi di atas. Penyimpanan ini mendelegasikan ke credential helper atau keychain OS apa pun yang dikonfigurasi di mesin, sehingga penghapusan sering kali dilayani oleh sesuatu yang sama sekali bukan berkas, dan menyebut path akan mengarahkan Anda ke lokasi yang belum tentu disentuh oleh penghapusan.
Penghapusan bukanlah kebalikan dari autentikasi, dan klien tidak boleh menawarkannya sebagai kebalikan. Antarmuka ini menghapus kredensial dan tidak memperolehnya: mendapatkan kredensial kembali berarti melakukan autentikasi lagi dengan aggrega login di terminal, karena menyimpannya memerlukan rahasia yang diketik oleh seseorang dan tidak ada yang memantau aliran ini. Jadi “log out” yang ditawarkan klien bersifat satu arah dari sini. Yang membedakan keduanya adalah apakah operasi harus memperoleh sesuatu dari siapa pun yang menjalankannya — penghapusan membawa satu nilainya di dalam permintaan, sedangkan memperoleh kredensial tidak — dan bukan apakah seseorang terlibat, karena seseorang memilih keduanya.
Mengklaim kembali konten cache juga menjangkau melampaui workspace. Penyimpanan modul terkompilasi dan plugin-describe
digunakan bersama oleh setiap proyek di mesin, sehingga aggrega/cachePrune, aggrega/cacheEvict dan
aggrega/cacheClear dapat menghapus konten yang diandalkan proyek lain. Setiap penghapusan membawa reach
dari kelas asalnya, dan setiap jawaban membawa scope.machineWideClasses. aggrega/cacheStatus
membawa jangkauan yang sama pada setiap kelas meskipun tidak mengubah apa pun, karena klien yang memutuskan
apakah akan mengklaim kembali membutuhkannya sebelum bertindak.
Menyegarkan indeks pencarian adalah kebalikannya. aggrega/registryUpdate menjangkau setiap
registry yang dikonfigurasi, dan apa yang ditulisnya berada di bawah direktori cache yang dikonfigurasi milik workspace ini sendiri —
sehingga tidak mengubah apa pun yang digunakan proyek lain untuk resolusi. indexRoot dalam jawaban menyebut direktori
tersebut.
Penyegaran sebagian tetap menjawab, bukan gagal. Permintaan yang menyebut satu registry yang penyegarannya gagal
merupakan error, karena tidak ada jawaban yang dapat diberikan. Permintaan yang menyegarkan setiap registry yang dikonfigurasi
berhasil meskipun sebagian, atau semuanya, gagal: yang berhasil disegarkan diindeks dan ditulis,
failed menyebut sisanya, dan setiap host membawa error-nya sendiri. Bacalah failed, bukan keberadaan
suatu error.
Apakah sebuah registry dapat dijangkau ditentukan oleh sebuah kunci, bukan dengan membaca pesannya. Host yang gagal
membawa unreachable: true jika registry tidak pernah dijangkau — namanya tidak teresolusi, koneksi
ke sana ditolak atau tidak dapat dibuka, atau koneksi aman ke sana tidak dapat
dibangun — dan penolakan permintaan yang menyebut satu registry membawa kunci yang sama dalam data-nya.
Registry yang berhasil dijangkau namun gagal, dengan daftar yang berulang atau status error,
tidak membawa keduanya, dan error-nya, atau pesan penolakan, menyatakan apa jawabannya. Kunci ini dibaca
dari kegagalan itu sendiri, sehingga tidak bergantung pada cara resolver mesin ini merumuskan kegagalan, dan
hanya ditetapkan jika kegagalan menunjukkan bahwa registry tidak pernah dijangkau: kegagalan yang tidak menunjukkan apa pun
ke arah mana pun, seperti batas waktu yang habis tanpa catatan tentang langkah mana yang diinterupsinya,
dilaporkan tanpa kunci tersebut. Nyatakan registry sebagai tidak terjangkau berdasarkan kunci, dan tampilkan error sebagai alasannya.
Baris perintah melaporkan penelusuran yang sama itu sebagai exit bukan nol, dan jenis pembaca Anda menentukan seberapa berarti
exit tersebut. Bagi orang di terminal, itu bukan keseluruhan laporan: aggrega registry update
mencetak berapa banyak registry terpilih yang diindeksnya, apa yang ditemukan masing-masing, mana yang tidak
diindeksnya, dan di mana indeks ditulis — sehingga ringkasan menyatakan apa yang terjadi dan status exit hanya menyatakan
apakah semuanya berhasil. Bagi skrip, itulah keseluruhan laporan, karena perintah tersebut tidak menyediakan
mode keluaran terstruktur, sehingga status exit-nya adalah satu-satunya putusan yang dapat dibaca mesin. Itulah sebabnya
kedua antarmuka menjawab penelusuran sebagian yang sama secara berbeda dan keduanya benar: antarmuka ini memberikan failed
kepada pemanggil terstruktur dan berhasil, sedangkan baris perintah hanya memiliki satu bit untuk digunakan dan menggunakannya untuk
“apakah ada registry yang terlewat”.
Memantau operasi yang panjang
Sebagian besar permintaan di sini menjawab dari apa yang sudah ada di disk dan langsung menjawab. Beberapa melakukan pekerjaan nyata terlebih dahulu — menyelesaikan dependensi sebuah Release, menyematkan input eksternalnya, menerbitkan, menandatangani, menarik — dan pemanggil menunggu. Permintaan tersebut melaporkan apa yang sedang dikerjakannya selama mengerjakannya, dan fitur ini bersifat opsional per permintaan.
Mengaktifkannya memerlukan dua langkah, dengan urutan ini.
- Deklarasikan kapabilitas tersebut saat handshake, dan tunggu balasannya. Kirim
capabilities.window.workDoneProgress: truepadaaggrega/initialize. Jangan mengirim apa pun sebelum balasan itu tiba: permintaan dilayani secara bersamaan, sehingga permintaan yang ditulis sebelum handshake dijawab dapat berjalan berdampingan dengan handshake yang seharusnya menegosiasikannya. Setiap klien sudah wajib menjaga urutan itu menurut protokol; ini adalah satu hal lagi yang bergantung padanya. - Letakkan token di params permintaan. Tambahkan
workDoneTokenke params permintaan yang ingin Anda pantau laporannya. Nilainya Anda pilih sendiri — string atau angka — dan nilai itulah yang mengaitkan notifikasi dengan panggilan tersebut. Buat token baru untuk setiap panggilan.
Notifikasi. Setiap notifikasi adalah $/progress dengan params.token diisi token Anda dan params.value membawa satu payload:
value.kind | membawa | kapan |
|---|---|---|
begin | title — apa yang sedang terjadi, dalam frasa yang dapat Anda tampilkan kepada pembaca | sekali, saat pekerjaan dimulai |
report | message — satu baris catatan operasi tentang dirinya sendiri | berapa kali pun, saat operasi menuliskannya |
end | tidak ada selain jenisnya | sekali, saat pekerjaan selesai |
Korelasikan berdasarkan token, jangan pernah berdasarkan id permintaan. Notifikasi tidak membawa id — notifikasi bukan respons terhadap apa pun — dan token adalah satu-satunya hal di dalamnya yang merujuk kembali ke panggilan Anda. Hal ini disengaja: di banyak klien, id permintaan menjadi milik lapisan transport dan tidak pernah mencapai kode yang melakukan panggilan, sedangkan token adalah nilai yang sudah dipegang kode tersebut.
Sebuah report membawa teks compiler itu sendiri. Pesannya adalah satu baris yang ditulis operasi saat bekerja, diteruskan dengan spasi di sekelilingnya dihapus dan tanpa perubahan lain — tidak disusun ulang kata-katanya, tidak diringkas, tidak dirangkai ulang — dan baris yang ditulis kosong oleh operasi dibuang alih-alih dilaporkan sebagai pesan kosong. Jadi, klien menampilkan apa yang diterimanya apa adanya. Ini adalah sifat yang sama dengan diagnostik milik respons: satu kondisi memiliki satu rumusan, berapa pun banyaknya permukaan yang melaporkannya.
Langkah yang ditunggu operasi juga merupakan report. Saat operasi memasuki langkah yang ditunggunya — membaca registry, mengambil artefak, mengompilasi plugin — sebuah report membawa nama langkah tersebut, dengan kata-kata yang ditampilkan baris perintah di samping indikator putarnya untuk langkah yang sama. Hanya langkah yang dimasuki antara begin dan end yang dilaporkan.
Satu baris output adalah satu report. Operasi yang menulis beberapa baris sekaligus menghasilkan satu notifikasi per baris, dan baris yang ditulis operasi sepotong-sepotong dilaporkan setelah lengkap — sehingga pesan tidak pernah berupa setengah kalimat.
Tidak ada pecahan dan tidak ada persentase, dan itu bukan kekurangan yang menunggu dikerjakan. Operasi yang melapor di sini mengerjakan sekumpulan item yang ukurannya tidak diketahui saat pekerjaan dimulai — berapa banyak referensi yang ditelusuri sebuah resolusi, berapa banyak layer yang diunggah sebuah publikasi — sehingga pecahan apa pun hanya akan dikarang. Tampilkan indikator tak tentu dan tunjukkan message terbaru.
Frame tiba sebelum respons dan tidak pernah sesudahnya. Sebuah begin tiba setelah pekerjaan benar-benar dimulai, sehingga permintaan yang ditolak karena params-nya — path yang absolut, field wajib yang hilang — tidak menghasilkan notifikasi sama sekali, hanya error-nya. end tiba sebelum respons, dan berhasil tidaknya operasi terdapat pada respons, bukan diulang di end.
Menghentikan pekerjaan adalah notifikasi tersendiri. Kirim $/cancelRequest dengan id yang Anda gunakan saat mengirim permintaan. Token tidak berperan dalam pembatalan, dan pembatalan tidak menghapus frame yang sudah terkirim.
Permintaan mana yang melapor, dan apa yang diharapkan dari sisanya
Tepat permintaan berikut yang melapor: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Dua hal berlaku untuk setiap permintaan tersebut, dan keduanya menjadi alasan permintaan itu ada dalam daftar: permintaan itu menjangkau registry atau URL jarak jauh atas nama Anda, sehingga lamanya ditentukan oleh sesuatu di luar mesin; dan permintaan itu sudah menulis catatannya sendiri sambil berjalan — catatan yang dibaca oleh orang yang memantau terminal. Jadi, pelaporan memberikan catatan yang sama itu kepada Anda, bukan catatan kedua yang disusun untuk jalur komunikasi, dan tidak ada yang perlu diubah dari apa yang dilakukan operasi untuk menghasilkannya.
Setiap permintaan lain menerima token dan tidak mengirim apa pun. Mengirim token tidak berbahaya dan bukan error: token diterima, tidak ada notifikasi yang tiba, dan jawabannya persis sama dengan jawaban yang akan Anda dapatkan tanpanya. Jadi, klien boleh melampirkan token pada permintaan apa pun yang diinginkannya dan cukup tidak menampilkan apa-apa ketika tidak ada yang datang.
🔴 Jangan artikan keheningan sebagai “yang ini instan.” Sebagian besar sisanya memang menjawab dari apa yang sudah ada di disk — validasi, hover, completion, graf, daftar cache, pembacaan konfigurasi — tetapi tidak semuanya: menyegarkan indeks registry, menambahkan plugin, pemeriksaan pra-publikasi, dan ekspansi pertama sebuah kode pada mesin yang tidak menyimpan dokumentasi yang boleh dibaca workspace semuanya menjangkau registry, dan mengompilasi sebuah Release adalah pekerjaan nyata. Permintaan tersebut memakan waktu selama yang diperlukan dan saat ini tidak melaporkan apa pun. Tampilkan indikator tak tentu untuk setiap permintaan yang siap Anda tunggu, dan perlakukan notifikasi sebagai detail yang Anda peroleh bila tersedia, bukan sebagai penanda bahwa pekerjaan sedang berlangsung.
Dua penolakan
Keduanya adalah error invalid-params dan keduanya menyebutkan apa yang harus dilakukan, karena token yang diam-diam tidak berbuat apa-apa akan membuat Anda menunggu aliran yang tidak pernah datang.
- Token dari sesi yang tidak mendeklarasikan kapabilitas
window.workDoneProgressditolak, dengan menyebutkan kapabilitas yang harus dideklarasikan. Deklarasikan kapabilitas itu saat handshake, atau jangan sertakan token. - Token yang bukan string maupun angka ditolak, dengan menyebutkan kedua bentuk tersebut. Token yang tidak ada, dan
nullyang eksplisit, bukan penolakan — keduanya berarti Anda tidak meminta laporan.
Kesadaran terhadap lockfile
Daemon memeriksa drift pada lockfile di setiap aggrega/irGraph, terhadap Release yang disebut oleh permintaan tersebut, dan menampilkan drift sebagai peringatan yang tidak memblokir. Peringatan itu menyebutkan perintah yang menulis ulang lockfile tersebut dengan Release di dalamnya, dieja sebagaimana permintaan mengirimkannya — aggrega pull --release diikuti oleh release yang Anda kirim, yaitu cara perintah itu ditulis di terminal pada root workspace. aggrega/irGraph mengharuskan adanya lockfile. Tidak ada pemeriksaan terpisah saat startup: sebuah permintaan menyatakan Release mana yang dimaksudnya, sehingga putusan dihitung untuk Release tersebut saat diminta, bukan sekali untuk satu Release yang dipilih sebelumnya.
Peringatan drift hilang ketika lockfile-nya hilang. Peringatan dipublikasikan pada lockfile tempat peringatan itu dimunculkan, dan lockfile yang sudah tidak ada tidak lagi memiliki pin yang dapat mengalami drift — perintah yang disebut peringatan akan menulis file baru alih-alih memperbaiki file lama. Karena itu, setiap permintaan yang mendapati lockfile hilang menarik peringatan tersebut sebelum menolak dengan galat lockfile-absent: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates dan aggrega/attachmentContainer yang ditanyakan tentang sebuah node graf, serta aggrega/connectionAtPosition. Penarikan itu tiba sebagai notifikasi aggrega/publishDiagnostics untuk lockfile tersebut yang membawa daftar kosong, sebelum penolakan. Penarikan berasal dari permintaan mana pun di antara permintaan tersebut yang pertama kali mengetahui penghapusan, sehingga klien yang melaporkan penghapusan lalu menanyakan apa pun tentang Release tersebut akan mendapati peringatannya dihapus tanpa harus meminta graf secara khusus. Lockfile yang masih ada dan masih mengalami drift mempertahankan peringatannya di sepanjang semua permintaan tersebut. aggrega/invalidate yang menyebut lockfile tersebut membuang apa yang disimpan daemon untuknya tetapi tidak mengirim apa pun; permintaan berikutnyalah yang memberi tahu klien. Dan lockfile yang bahkan tidak dapat diperiksa oleh daemon — misalnya yang direktorinya tidak boleh dibaca — tidak menarik apa pun, karena file itu mungkin masih ada dan peringatannya mungkin masih benar.
aggrega/build dan aggrega/buildPreview juga mengharuskannya, dan keduanya menegakkan lockfile tersebut terhadap Release alih-alih memberi peringatan — keduanya merender dengan sikap sebuah permukaan yang menghasilkan artefak, sehingga lockfile yang tidak lagi cocok dengan hasil resolusi Release menghentikan keduanya, padahal pada inspeksi hal itu hanya akan memunculkan peringatan. Release tanpa lockfile ditolak dengan galat lockfile-absent. Pengecualiannya adalah build yang field autoPull-nya memintanya meresolusi dependensi terlebih dahulu: build tersebut menulis lockfile lalu merender berdasarkan apa yang ditulisnya, dan lockfile yang dihasilkan dengan cara itu tidak diperiksa drift-nya untuk kedua kalinya, karena resolusi yang menulisnya telah menjalankan pemeriksaan yang sama terhadapnya sebelum menulisnya dan tidak menulis lockfile yang ditolak oleh pemeriksaan itu.
Lockfile yang ada tetapi tidak mencatat digest untuk sebuah plugin tidak menghentikan graf — lockfile yang tidak ada yang menghentikannya. Keduanya adalah dua kondisi berbeda dan hanya yang kedua yang menolak. aggrega/irGraph tidak mencocokkan byte yang diresolusinya dengan digest yang tercatat: pin yang tidak dapat diverifikasinya dilaporkan alih-alih ditolak, dan graf digambar dengan temuan tersebut di panel Problems, karena editor yang menolak menggambar graf tidak meninggalkan apa pun bagi pembaca, sedangkan laporan memberi mereka sesuatu untuk ditindaklanjuti. Di tempat lain plugin juga tetap berjalan, dengan sebuah peringatan yang menyatakan bahwa tidak ada yang memeriksa byte-nya. Yang ditolak aggrega/irGraph adalah lockfile yang tidak ada: ia berhenti sebelum meresolusi apa pun dan menjawab dengan galat lockfile-absent, menyebutkan lockfile yang dicarinya dan Release-nya, sehingga klien dapat langsung menawarkan aggrega pull --release <release> — atau mengirim aggrega/resolveDependencies untuk Release tersebut dan menulis lockfile tanpa meninggalkan sesi. Memisahkan keduanya penting, karena graf yang tergambar adalah gambaran yang kemudian dinalar oleh pembaca, dan graf yang dibangun dari byte yang tidak diperiksa siapa pun digambar persis seperti graf yang telah diperiksa, dengan temuan berada di tempat yang tidak sedang dilihat pembaca. Jadi graf bukanlah putusan atas byte di baliknya — aggrega/build dan aggrega/buildPreview adalah permukaan yang menegakkan digest yang tercatat terhadap sebuah Release, berhenti di tempat inspeksi hanya melaporkan.
aggrega/validate, ketika sebuah permintaan menyebut sebuah Release, membaca lockfile Release tersebut hanya untuk pin dan pemberitahuan deprecation-nya — dan tidak membaca lockfile apa pun untuk entitas katalog yang diperiksanya sebagai satu entitas, sebagaimana baris perintah juga tidak membacanya. Ia tidak mencocokkan plugin yang dijalankannya dengan digest yang tercatat, dan tidak membangun ulang himpunan lampiran transform-plugin dari lockfile — ia memvalidasi terhadap konfigurasi workspace sebagaimana adanya di hadapan Anda, yang memang harus dilakukan editor selagi Anda menyunting konfigurasi tersebut. aggrega validate dan aggrega build melakukan keduanya, dan tetap menjadi permukaan otoritatif untuk putusan tentang workspace yang telah di-commit.
Pemberitahuan deprecation-nya mencakup kedua tempat penarikan dicatat. Penanda pada referensi yang di-pin ada di lockfile; penanda pada plugin yang dilampirkan dalam peran yang mengembalikan putusan terima-atau-tolak — lampiran plugins.governance pada ir-verdict atau render-verdict, atau lampiran plugins.linter — ada di catatan kepercayaan plugin di sampingnya, sehingga validasi membaca keduanya dan menyebutkan setiap referensi yang ditarik dan setiap plugin yang ditarik sebagai peringatan di awal Aggregate, dengan kata-kata yang dicetak aggrega build. Pemberitahuan tidak mengubah putusan apa pun. Catatan kepercayaan yang ada tetapi tidak dapat dibaca dilaporkan sebagai galat sebagai pengganti validasi, alih-alih dibaca sebagai catatan yang tidak mencatat apa pun. aggrega/releaseClosure melaporkan himpunan yang sama dalam deprecations-nya.
Lokasi lockfile sebuah Release
Setiap jawaban yang menyebut sebuah Release juga menyebut lockfile-nya, sehingga klien tidak pernah perlu menyimpulkan path-nya. aggrega/activeRelease membawanya sebagai lockfile di samping release, aggrega/releaseCandidates sebagai map lockfiles di samping releases, dan galat lockfile-absent sebagai lockfile di dalam data-nya. Masing-masing adalah file yang ditulis oleh aggrega pull --release <release> dan dibaca oleh aggrega build, serta file yang diperiksa oleh setiap permintaan di atas — sehingga klien yang mengawasi lockfile sebuah Release, untuk mengetahui saat file itu ditulis, ditulis ulang, atau dihapus, mengawasi file yang dimaksud daemon. Lockfile terletak di samping Release-nya dan memakai nama Release tersebut dengan ekstensi .yaml atau .yml diganti dengan .lock; Release yang dinamai dengan ekstensi lain mempertahankan seluruh namanya, sehingga lockfile dari release.rel adalah release.rel.lock. Bacalah path dari jawaban alih-alih menyusunnya dari deskripsi tersebut, sehingga keduanya tidak dapat berselisih.
Referensi eksternal yang diminta oleh sebuah render
Sebuah render dapat meminta konten dari URL jarak jauh — misalnya skema values sebuah chart dengan referensi jarak jauh. Input eksternal dibekukan untuk setiap render yang dilakukan daemon ini sebagai jawaban atas permintaan yang hanya meminta untuk diberi tahu sesuatu. Referensi yang di-pin oleh lockfile milik Release dilayani dari penyimpanan beralamat konten, yang merupakan pembacaan konten yang sudah ada di disk, bukan pengambilan, dan referensi itu diperiksa terhadap apa yang dicatat lockfile sebelum byte-nya dilayani — sehingga render di sini melihat apa yang dilihat build, dan memunculkan peringatan yang dimunculkan build. Referensi yang tidak di-pin oleh lockfile ditolak alih-alih diambil: memperolehnya berarti menjangkau jaringan dan menulis sebuah blob ke dalam penyimpanan, dan sebuah sesi tidak melakukan keduanya pada permintaan yang hanya meminta untuk diberi tahu sesuatu. Itulah aturan pada Menjangkau registry, dan menulis dibaca dari sisi render, dan aturan itu berlaku bagaimana pun render tersebut dicapai.
Permintaan yang ada untuk melakukan pin adalah pengecualiannya, dan itu adalah pengecualian yang sama yang sudah dimiliki aturan registry. aggrega/resolveDependencies diminta untuk memperoleh, sehingga render yang dilakukannya untuk menemukan referensi mana yang dikonsumsi Release ini menjangkau jaringan dan menulis apa yang di-pin-nya — itulah yang membuat hasilnya berupa lockfile, bukan laporan. Tidak ada render yang dilakukan permintaan graf atau build untuk dirinya sendiri yang melakukan hal-hal tersebut.
Build yang diminta untuk melakukan resolusi terlebih dahulu dijawab dari render itu juga, itulah sebabnya build tersebut merender Release satu kali. Resolusi telah merender apa yang menjadi pokok build, terhadap pin yang baru saja ditulisnya dan di bawah gerbang yang dijalankan build, sehingga build menyajikan render tersebut alih-alih melakukan render kedua — dan perolehan tetap menjadi milik resolusi, bukan milik build. Hanya render yang selesai yang digunakan dengan cara itu: jika suatu resolusi telah mem-pin dependensinya tetapi tidak dapat menyelesaikan penemuan referensi eksternal, build merender sendiri terhadap pin yang berhasil tercatat, dan referensi yang tidak di-pin ditolak dan dilaporkan di sana persis seperti pada build yang tidak meresolusi apa pun.
Penolakan dilaporkan alih-alih diserap, karena tidak ada apa pun pada suatu hasil yang menyatakan referensi mana yang hilang darinya. Dengan provider yang dibawa biner ini, provider yang meminta referensi tersebut mengembalikan penolakan, sehingga render yang mencapai referensi yang ditolak tidak selesai. Karena itu, setiap referensi yang ditolak tiba sebagai entri tersendiri pada lapisan aggrega-build, yang menyebutkan referensi tersebut dan perintah yang mem-pin-nya: aggrega pull --release <release>, atau aggrega/resolveDependencies untuk pekerjaan yang sama tanpa meninggalkan sesi. Entri-entri tersebut bersifat peringatan, bukan penolakan — graf tetap dikembalikan, dengan kedudukan yang sama seperti peringatan drift di atas — dan entri-entri itu diatribusikan ke Aggregate di bagian awal file, karena referensi yang diminta oleh sebuah render tidak menyebutkan kunci apa pun yang ditulis penulis. Entri-entri itu dikirim dalam publikasi yang sama dengan peringatan milik render itu sendiri, yang menggantikan lapisan tersebut secara utuh, sehingga referensi yang kemudian Anda pin berhenti dilaporkan tanpa perlu ada yang menghapusnya. Render yang sepenuhnya di-pin tidak menyatakan apa pun tentang hal ini. Lihat Apa yang dimuat entri diagnostik untuk bentuk setiap entri.
Pada aggrega/irGraph, hal ini bergantung pada apakah tahap rendering berjalan sama sekali. Permintaan graf melewati render kecuali --build-on-inspect, atau kunci serve.build_on_inspect yang ditimpanya, mengaktifkannya; dengan pengaturan itu nonaktif, tidak ada yang meminta referensi eksternal dan tidak ada yang perlu ditolak. Mengaktifkannya adalah hal yang membawa peringatan milik render itu sendiri maupun peringatan-peringatan ini ke dalam sesi editor.
Di mana sebuah sesi berbeda dari pembekuan yang sama di baris perintah. aggrega build juga membekukan input eksternal untuk dry run, dan referensi yang tidak di-pin berperilaku sama pada kedua permukaan: referensi itu dilaporkan sebagai temuan yang menyebutkan referensi tersebut, lalu render berhenti, karena provider yang memintanya mengembalikan penolakan. Yang berbeda adalah pengambilan ulang. Di baris perintah, referensi yang di-pin yang salinan tersimpannya hilang diambil kembali berdasarkan digest yang tercatat; render yang menjawab permintaan graf atau build tidak mengambil ulang apa pun, karena render tersebut tidak menjangkau jaringan, sehingga render itu tidak dapat kembali mengambil referensi yang di-pin yang tidak lagi disimpan oleh penyimpanan — dan referensi semacam itu tidak termasuk penolakan yang dijelaskan di atas, yang menyebutkan apa yang tidak di-pin oleh lockfile. Meminta sesi untuk melakukan pin adalah cara memulihkannya: permintaan yang disebutkan di atas menjangkau jaringan dan mengembalikan byte yang hilang. Lihat aggrega pull untuk apa yang diambil dan dicatat oleh proses pin.
Apa yang masih disampaikan oleh eksekusi yang ditolak
Permintaan yang menolak menjawab dengan amplop galat, dan temuan yang telah dibuat oleh eksekusi tersebut tidak dibawa di dalam amplop itu — amplop tidak membawa badan hasil sama sekali. Temuan tersebut sampai kepada Anda dengan cara yang sama seperti pada eksekusi yang selesai: sebagai publikasi diagnostik pada lapisan aggrega-build, yang dijelaskan di bagian Apa yang dibawa oleh entri diagnostik. Jadi, klien yang menangani penolakan membaca amplop untuk mengetahui apa yang perlu diubah dan permukaan masalahnya untuk mengetahui apa yang ditemukan eksekusi, dan keduanya tidak saling menggantikan. Penolakan yang dimunculkan saat merender adalah satu-satunya penolakan yang juga merupakan temuan tentang apa yang ditulis penulis, sehingga penolakan itu sampai ke keduanya, seperti yang dijelaskan bagian berikutnya.
Publikasi itu terjadi baik eksekusi mencapai akhirnya maupun tidak. Eksekusi yang berhenti di tengah jalan tetap telah menemukan segala sesuatu sebelum titik ia berhenti, dan pembaca yang kehilangan temuan tersebut harus menjalankannya lagi untuk melihatnya — sehingga peringatan dipublikasikan dari apa yang dicapai eksekusi, dan penolakan dikembalikan sesudahnya. Kumpulannya sama dengan ketelitian yang sama, ditempatkan pada kunci penulisan yang sama: penolakan tidak menurunkan temuan menjadi sekadar kalimat. Referensi eksternal yang ditolak dibawa dalam publikasi yang sama itu, dengan alasan yang sama dan melalui jalur yang sama.
Yang membatasinya adalah seberapa jauh eksekusi berjalan, bukan apa yang dapat dibawa lapisan. Penolakan dari salah satu pemeriksaan yang berjalan sebelum kompiler dimulai — closure Release tidak dapat di-resolve, Manifest memetakan suatu tipe ke recipe yang tidak mengimplementasikannya, lockfile tidak lagi cocok dengan hasil resolve Release, entri yang di-pin di cache tidak lagi cocok dengan digest yang tercatat untuknya dan tidak ada direktori katalog yang menyimpan byte yang di-pin — tidak memiliki peringatan untuk dipublikasikan, karena belum ada yang dimunculkan. Lapisan kemudian tidak membawa apa pun alih-alih sesuatu yang usang; dan eksekusi yang belum sampai menyebutkan sebuah dokumen tidak memublikasikan apa pun sama sekali, sehingga apa pun yang sudah ada di permukaan masalah Anda tetap persis seperti semula alih-alih menghapus entri yang tidak diketahuinya.
Penolakan yang dimunculkan saat merender
Release yang ditolak kompiler saat merendernya — Workload yang menyebut slot yang tidak dideklarasikan oleh Component-nya, asersi yang gagal, templat yang tidak dapat dievaluasi, realisasi yang kurang dari apa yang harus disediakannya — dilaporkan di tempat yang ditunjuknya dan dengan kata-kata kompiler, pada setiap permintaan yang merendernya: aggrega/build, aggrega/buildPreview, dan aggrega/irGraph dengan tahap rendering diaktifkan. Jawabannya adalah amplop galat dengan kode -32603, yang message-nya adalah penolakan beserta setiap penyebab di bawahnya, dengan kata-kata yang dicetak baris perintah untuk build yang sama: node yang sedang dirender, lalu apa di dalamnya yang menolak, setiap penyebab setelah penyebab yang dijelaskannya — diawali, jika penolakan menyebut kondisi terdaftar, oleh kode pendek kondisi tersebut, sebagaimana setiap penolakan yang menyebutnya. data-nya menyebut dokumen yang ditunjuk penolakan sebagai file, dan rentang kunci di sana sebagai line, column, end_line dan end_column, di samping code dan shortCode kondisi tersebut; penolakan yang tidak menyebut kunci, atau menyebut kunci yang tidak ada di dokumen, hanya membawa file, dan penolakan yang tidak menunjuk dokumen apa pun menyebut Aggregate milik Release.
Penolakan yang sama dipublikasikan pada lapisan aggrega-build, pada dokumen itu, di kunci itu, sebagai entri dengan tingkat keparahan error yang membawa keyPath milik penolakan itu sendiri dan message milik amplop tanpa kode pendek di depannya, dan — jika penolakan menyebut kondisi terdaftar — code, shortCode dan codeDescription kondisi tersebut, dengan kode pendek dibawa dalam bidangnya sendiri di sana. Penolakan itu dibawa dalam satu publikasi yang membawa peringatan yang dimunculkan eksekusi sebelum berhenti, sehingga ia menggantikan lapisan seperti halnya peringatan itu: eksekusi Release berikutnya yang merender memublikasikan lapisan tanpanya, dan dokumen tempatnya berada dipublikasikan kosong, yang menghapusnya dari permukaan masalah Anda.
Tempat yang ditunjuk penolakan adalah apa yang disebut penolakan itu sendiri, dan tidak lebih rinci. Pemeriksaan Workload menilai dokumen yang dihasilkan templatnya, dan templat dapat menulis baris yang tidak ditulis penulis mana pun — perulangan, kondisi, teks yang diimpor dari berkas atau pustaka — sehingga sebuah baris Workload yang dirender tidak terpetakan ke baris Recipe. Oleh karena itu, penolakan tentang Workload ditempatkan pada kunci workload milik Recipe, dan path yang disebutnya di dalam dokumen yang dirender tetap berada dalam pesannya. Asersi yang gagal ditempatkan pada kuncinya sendiri di bawah assertions dalam Recipe atau FeatureRecipe yang mendeklarasikannya; asersi yang dideklarasikan Component atau Feature dimunculkan sebelum ada dokumen yang dapat disebut, dan ditempatkan pada kunci kind: milik Aggregate. Penolakan dari langkah yang menyebut dokumen tetapi tidak menyebut kunci ditempatkan pada kunci kind: dokumen tersebut.
Penolakan yang menggabungkan beberapa temuan dipublikasikan temuan demi temuan. Komposisi graf yang menjadi dasar render menolak dengan setiap pelanggaran yang ditemukannya dalam satu penolakan — entri yang menyebut target yang tidak dijawab oleh apa pun, dua koneksi dari satu komponen yang diberi satu alias — dan baris perintah mencetak masing-masing sebagai diagnostik tersendiri, di bawah kepalanya sendiri. Di sini masing-masing adalah entri tersendiri pada lapisan aggrega-build, pada dokumen dan di kunci yang disebut temuan tersebut — Release jika Release yang menulisnya, Aggregate jika Aggregate yang menulisnya — dengan kata-katanya sendiri dan kodenya sendiri. message jawaban membawa setiap temuan, dan data-nya menyebut tempat yang ditunjuk temuan pertama.
Nilai yang dideklarasikan sensitif oleh penulis disembunyikan di sini persis seperti baris perintah menyembunyikannya. Teks penolakan adalah teks yang dimunculkan kompiler, tidak ada apa pun di permukaan ini yang mengubah kata-katanya, dan kompiler menyembunyikan nilai yang dideklarasikan di tempat penolakan dimunculkan — <redacted> sebagai gantinya — sehingga jawaban ini, entri ini, dan terminal membawanya dengan kata-kata yang sama; apa yang dikatakan penolakan tentang nilai yang dideklarasikan menjelaskan caranya, dan penolakan mana yang berada di luarnya.
Penolakan dari gerbang yang berjalan sebelum render bukanlah hal ini. Pemeriksaan yang tercantum di atas menjawab seperti yang dijelaskan Apa yang tetap disampaikan oleh proses yang ditolak. Asersi yang dideklarasikan Component atau Feature, dan penolakan atas graf yang dikomposisikan, berada di antara keduanya: masing-masing dimunculkan sebelum render, oleh setiap permintaan yang me-resolve graf Release, sehingga aggrega/irGraph menjawab dan memublikasikannya seperti di atas juga dengan tahap rendering dinonaktifkan; aggrega/releaseClosure, aggrega/attachCandidates dan aggrega/attachmentContainer yang ditanya tentang node graf, serta aggrega/connectionAtPosition, menjawabnya dengan amplop yang sama dan tidak memublikasikan apa pun, karena tidak memiliki permukaan masalah.
Kode galat
Respons menggunakan kode galat JSON-RPC standar ditambah rentang tingkat aplikasi pada pita 1xxx. Klien editor dapat bercabang berdasarkan kode tanpa mengurai pesannya.
1001file-not-validated — daemon tidak memegang apa pun untuk file tersebut, sebagaimana keadaannya sekarang, yang dapat dijadikan dasar jawaban permintaan: tidak ada hasil penguraian file tersebut, atau, untukaggrega/diagnostics, tidak ada hasil penguraian file tersebut atau tidak ada apa pun yang dipegang untuk file itu yang merupakan jawaban validasi untuk teks yang kini dipegang daemon. Kirimaggrega/validateuntuk file itu lalu tanyakan lagi.1003lockfile-absent — Release yang disebut permintaan tidak memiliki lockfile, padahal operasi yang diminta memerlukannya.1004entity-not-resolvable — nama tersebut tidak cocok dengan entitas mana pun di tingkat katalog mana pun, maupun di Release yang disebut permintaan; atau referensi registry yang dikirim sebagai nama tidak dapat dibaca sebagai entitas, dan pesannya menyebut kondisi yang menjelaskan alasannya; atau lockfile milik Release adalah tautan yang mengarah ke luar workspace, yang ditolak sebelum apa pun membacanya, dengandatamenyebut lockfile dan Release tersebut serta pesan yang diawali kode singkat kondisinya,E0321— lihat batas workspace.1005shutting-down — daemon sedang menuntaskan pekerjaan setelah notifikasi shutdown dan menolak permintaan baru. Jangan mencoba ulang terhadap subproses yang sama.1006validation-in-flight — validasi file tersebut sedang berjalan dan tidak selesai dalam batas waktu yang diberikan oleh permintaan yang menunggu. Tanyakan lagi sebentar kemudian dan jangan mengirim apa pun.
1002 tidak dialokasikan, dan tersedia untuk kondisi berikutnya yang memerlukan kode.
File-not-validated dan validation-in-flight melaporkan keadaan yang berlawanan, dan tindakan yang dituntut masing-masing juga berlawanan. File-not-validated berarti daemon tidak memegang apa pun untuk file tersebut, sebagaimana keadaannya sekarang, yang dapat dijadikan dasar jawaban permintaan — tidak ada hasil penguraian file tersebut, atau, untuk aggrega/diagnostics, tidak ada hasil penguraian file tersebut atau tidak ada apa pun yang dipegang untuk file itu yang merupakan jawaban validasi untuk teks yang kini dipegang daemon: kirim aggrega/validate lalu tanyakan lagi. Validasi yang dibatalkan di tengah jalan membiarkan file dalam keadaan ini, karena validasi tersebut tidak menyimpan apa pun dan apa yang ditemukan validasi sebelumnya tentang teks yang berbeda bukanlah jawaban untuk teks yang kini dipegang daemon; jawaban sebelumnya tetap berlaku selama teksnya adalah teks yang diperiksanya. Temuan yang didorong daemon tentang file yang dibacanya sendiri dari disk — lockfile yang telah menyimpang, Release yang tidak dapat dimuat — bukanlah validasi atas teks yang Anda pegang, sehingga temuan tersebut juga tidak menjawab permintaan ini. Dua validasi atas teks yang berbeda yang dikirim berdekatan juga dapat membuat Anda berada dalam keadaan ini, yaitu ketika validasi yang teksnya disimpan daemon selesai lebih dulu: permintaan ditolak meskipun teks itu sudah diperiksa, dan memvalidasi lagi akan menjawabnya. Kode ini dinyatakan dalam hal hasil penguraian, bukan file, karena buffer yang tidak akan dibaca parser mana pun berada tepat pada posisi itu — validasi telah berjalan dan melaporkan temuannya, tetapi tetap tidak ada hasil penguraian untuk dijadikan dasar jawaban. Validation-in-flight berarti validasinya sedang berjalan dan tidak selesai dalam batas waktu yang diberikan oleh permintaan yang menunggu: tanyakan lagi sebentar kemudian dan jangan mengirim apa pun, karena keadaan yang Anda perlukan sudah dalam perjalanan dan validasi kedua hanya akan menambah pekerjaan. Membaca keduanya sebagai satu kondisi membuat klien mengirim validasi justru dalam kasus ketika mengirimnya adalah langkah yang salah. Kedua pita memiliki arti berbeda bagi klien: kode 1xxx menyebut keadaan workspace yang dapat ditindaklanjuti pengguna — memvalidasi file, membuat lockfile — sedangkan kode standar seperti invalid-params menyebut permintaan yang salah bentuk, yang diperbaiki oleh klien, bukan pengguna. Nilai release yang ada tetapi salah bentuk — absolut, atau mengarah ke luar root workspace — masuk ke pita kedua: bukan workspace yang berada dalam keadaan yang harus diperbaiki pengguna, melainkan permintaannya. Menghilangkan release tidak masuk ke pita mana pun, karena hal itu sama sekali bukan galat; hal itu memilih yang lebih sempit dari dua jawaban yang dijelaskan di bagian Validasi langsung.
Galat dapat membawa objek data, dan setiap kunci di dalamnya menyebut satu hal dan hanya hal itu. file adalah dokumen sumber yang menjadi pokok kegagalan — dokumen yang sedang divalidasi, Release yang gagal dimuat, dokumen workspace yang mendeklarasikan nama yang tidak terselesaikan, atau dokumen yang ditunjuk oleh penolakan yang dimunculkan saat merender — dan di dalam dokumen itulah line dan column yang menyertainya menentukan posisi. Keduanya sendiri opsional: kegagalan mengenai seluruh dokumen hanya membawa file. lockfile adalah sebuah lockfile. release adalah Release yang menjadi pokok galat, ditulis sebagaimana permintaan menyebutnya, sehingga klien dapat menyusun aggrega pull --release <release> tanpa mengurainya kembali dari pesan. unreachable menyatakan bahwa registry yang disebut permintaan yang ditolak tidak dapat dijangkau: penyegaran indeks yang ditolak dan menyebut satu registry membawanya, dibaca dari kegagalan itu sendiri, dan registry yang menjawab membuatnya tidak ada. Setiap kunci bersifat opsional dan hanya ada ketika daemon memegang nilai tersebut; tidak ada yang menggantikan yang lain, sehingga apa yang ditunjuk sebuah kunci tidak pernah bergantung pada kode di sampingnya.
code dan shortCode di dalam data menyebut kondisi yang dilaporkan sebuah penolakan, pada setiap penolakan yang melaporkan kondisi terdaftar, apa pun kode numeriknya: kode deskriptif yang dijadikan dasar percabangan program dan kode singkat yang dikutip orang, dua pengidentifikasi yang sama, dengan nama yang sama, yang dibawa oleh entri diagnostik untuk kondisi yang sama, dan tercantum dalam tabel setiap kondisi. Bercabanglah berdasarkan code. Kode numerik menyebut keadaan permintaan dan tetap sama untuk banyak kondisi — build yang ditolak karena tautan katalog mengarah ke luar dan build yang ditolak karena sebuah nama tidak terselesaikan sama-sama 1004 — dan pesannya berupa prosa yang dapat diubah susunan katanya, sehingga tidak satu pun dari keduanya membedakan satu kondisi dari yang lain. Invalid-params adalah salah satu kode bersama tersebut: permintaan yang menyebut workspace yang file konfigurasinya mengarah ke luar workspace itu juga memicunya, dan di sana read-leads-out-of-workspace menyatakan bahwa kesalahannya ada pada tata letak workspace, yang diperbaiki oleh orang, bukan pada permintaan. Penolakan yang tidak melaporkan kondisi terdaftar tidak membawa kedua kunci, dan keduanya hadir bersama atau tidak sama sekali. Pesan penolakan yang menyebut suatu kondisi diawali kode singkatnya, E0321: …, satu kali, yang merupakan bentuk yang dijumpai pembaca pada setiap penolakan semacam itu; penolakan yang pesannya sudah diawali kepala dalam kurung siku yang membawa kode tersebut — laporan satu baris tentang dokumen katalog yang ditolak saat dimuat — tidak diberi kode itu lagi.
Uraian tentang bagaimana kaskade Release workspace berjalan dibawa pada jawaban aggrega/activeRelease, di kolom trace, bukan pada galat: workspace yang tidak menunjuk Release mana pun adalah keadaan biasa, bukan permintaan yang gagal. Uraian ini adalah prosa diagnostik yang ditulis untuk dibaca orang, bukan struktur untuk diurai. Tampilkan apa adanya — tulis ke log, atau ke panel yang dapat dibuka pengguna — dan jangan mencocokkan pola terhadapnya, mengambil nilai darinya, atau bercabang berdasarkan label yang digunakannya: susunan kata, tata letak, dan label tersebut mengikuti kaskade itu sendiri dan berubah setiap kali kaskade berubah. Klien yang meneruskan teks apa adanya tetap berfungsi melewati perubahan semacam itu; klien yang telah mempelajari bentuknya akan rusak karenanya.
Lihat juga
- ../schema/other/serve-wire.md — bentuk pesan yang dipertukarkan protokol ini, dihasilkan dari skema yang dipublikasikan: objek parameter setiap metode, setiap hasil, dan setiap payload notifikasi, per field.
- ./aggrega-build.md — perintah build, yang pipeline kompiler, gerbang, dan resolusi dependensinya juga dijalankan oleh
aggrega/build, sehingga kedua antarmuka menulis satu pohon keluaran, bukan dua. - ./aggrega-version.md — perintah version yang digunakan ekstensi editor untuk memeriksa kompatibilitas daemon.
- ./aggrega-pull.md — lockfile yang dibaca oleh antarmuka drift daemon.
- ./aggrega-lint.md — konvensi publikasi yang dilaporkan daemon atas permintaan, dan pada setiap validasi setelah
serve.lint_on_validatediaktifkan.
Sinopsis
aggrega serve [flags]Deskripsi
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.Flag
| Flag | Default | Deskripsi |
|---|---|---|
--build-on-inspect | false | Menjalankan tahap perenderan artefak saat memeriksa graf IR, sehingga peringatan yang dimunculkan aggrega build saat merender juga tampil sebagai masalah di editor. Opsi ini tidak menambahkan satu pun pemeriksaan yang menghentikan build. Tidak ada yang ditulis ke disk: tidak ada artefak hasil render, tidak ada direktori keluaran, tidak ada lockfile. Nonaktif secara default, sama seperti aggrega inspect, yang juga tidak memunculkan peringatan semacam itu. Jika diatur, menimpa kunci konfigurasi serve.build_on_inspect. |