Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

aggrega serve

aggrega serve запускає Aggrega як довготривалий демон «компілятор як сервіс» для інтеграції з IDE. Він обмінюється даними за протоколом JSON-RPC 2.0 через stdin/stdout і зберігає стан розпізнавача каталогів, кешу розбору та діагностики між запитами, тож операції редактора отримують відгук менш ніж за секунду замість того, щоб за кожного натискання клавіші сплачувати повну вартість завантаження каталогу.

Зазвичай демон запускає як підпроцес розширення редактора, а не користувач вручну. Еталонним клієнтом є розширення для VS Code; інші редактори можуть інтегруватися, використовуючи той самий протокол.

Протокол

Протокол передавання — JSON-RPC 2.0 з кадруванням Content-Length у просторі імен методів aggrega/. Це навмисно не Language Server Protocol: Aggrega має доменні операції (запит до графа IR, сигнал інвалідації кешу), для яких у LSP немає аналога. Розширення редактора перекладає запити LSP редактора в ці методи aggrega/*; значення позиції, діапазону й розташування у формі LSP використовуються повторно там, де вони підходять.

Два методи зберігають стандартні для протоколу імена з $/, а не перейменовуються в простір імен aggrega/, бо обидва стосуються транспорту, не несуть значення для Aggrega, і клієнт, що вже говорить цим протоколом, обробляє їх без жодних доповнень: $/cancelRequest, який зупиняє запит, відповідь на який клієнтові більше не потрібна, і $/progress, яким демон повідомляє про тривалу операцію під час її виконання. Обидва описано нижче.

🔴 Кожен запит нижче містить workspaceRoot — абсолютний шлях робочого простору, з яким він працює, і для окремих методів це не повторюється. Три запити його не містять, бо їхній предмет — не робочий простір: aggrega/initialize, aggrega/getSchema і aggrega/scaffoldEntity, — хоча aggrega/scaffoldEntity, що записує або перелічує готовий до запуску приклад, таки називає робочий простір. Що отримує запит, який не називає жодного, див. у розділі Кожен запит називає робочий простір, якого він стосується, а куди надходять надіслані діагностики — у розділі Оголошення робочого простору, для якого ви хочете отримувати діагностики.

Структури поле за полем опубліковано як схему, і читати їх слід у довіднику форм передавання. Та сторінка описує об’єкт параметрів кожного методу, кожен результат і корисне навантаження кожного сповіщення — кожне поле з його типом, тим, чи воно обов’язкове, і тим, що воно несе, — а також три властивості, що діють для всієї поверхні, а не для окремого методу: два поля, які допускає кожен запит понад ті, що оголошує його власний метод, — це workspaceRoot вище та workDoneToken з розділу Відстеження тривалої операції; те, що об’єкт params із ключем, якого його метод не приймає, відхиляється, і у відмові названо допустимий набір; а також те, де відсутня колекція потрапляє в передавання як null, а не як порожня. Її згенеровано з цієї схеми, тож вона змінюється разом із контрактом.

Ця сторінка описує протокол, та — структури, і їх призначено читати разом. Тут: кадрування, призначення кожного методу, його охоплення, що він записує, які відмови він породжує і чому, коди помилок і що робити з кожним. Там: що передавати, ключ за ключем. Тож список нижче називає кожен метод і пояснює, що означає його виклик, а список полів для запиту, який ви складаєте, — у довіднику поруч.

Запити:

  • aggrega/initialize — рукостискання. Узгоджує кодування позицій (сервер надає перевагу UTF-8, потім UTF-16, потім UTF-32, а за замовчуванням використовує UTF-16), отримує робочий простір, який ви оголошуєте для надсилання діагностик, і повідомляє корінь цього робочого простору, рівень конфігурації, з якого визначено його налаштування, та маркер, що його визначив. Відповідь також містить version — версію бінарного файлу, що відповідає: те саме значення, яке для цього бінарного файлу повідомляє aggrega version. Воно описує запущений процес, тож після заміни файлу, з якого запущено демон, — скажімо, перезбирання за тим самим шляхом, — version і далі називає запущений демон, тоді як запит до файлу назве його заміну; читайте його тут, коли питання в тому, з якою версією ви спілкуєтеся. workspaceRoot необов’язковий, і він оголошує робочий простір, а не працює з ним — див. Оголошення робочого простору, для якого ви хочете отримувати діагностики. Надішліть capabilities.window.workDoneProgress: true, щоб повідомити, що ваш клієнт може обробляти сповіщення про перебіг; capabilities.workDoneProgress у відповіді повторює це, а для клієнта, що нічого не оголосив, це поле відсутнє. Див. Відстеження тривалої операції.
  • aggrega/validate — перевірити вміст файлу; повертає діагностики. release — шлях відносно кореня робочого простору, що називає сутність Release, відносно якої виконується перевірка, — те саме значення, яке приймає aggrega/irGraph, і те саме, яке приймає aggrega build --release під час запуску з кореня. Він необов’язковий і визначає охоплення відповіді: якщо назвати Release, перевірки, яким вона потрібна, виконуються відносно неї — сутність каталогу перевіряється як окрема сутність у термінах цієї Release, а будь-який інший документ — відносно замикання залежностей цієї Release; якщо його пропустити, відповідь охоплює те, чому документ може відповідати сам по собі, і містить checked, щоб на це вказати. Присутнє, але некоректне значення відхиляється в обох випадках — абсолютний шлях або шлях, що веде за межі кореня робочого простору, відкидається, а не розв’язується. Див. Перевірка в реальному часі.
  • aggrega/diagnostics — повернути знахідки, збережені для файлу. Якщо під час надходження запиту виконується перевірка того самого файлу, відповідь чекає на неї й повідомляє знайдене, тож відповідь ніколи не засвідчує бездоганність файлу, у якому демон саме шукає проблеми. Див. Запит діагностик під час виконання перевірки.
  • aggrega/hover — вміст підказки для сутності в позиції. release необов’язковий і дає відповідь у термінах цієї Release — див. Відповідь у термінах однієї Release.
  • aggrega/completion — варіанти автодоповнення в позиції. Там, де курсор називає сутність за типом, — type компонента, type приєднання Feature, значення extends:, implements: сутності Recipe або FeatureRecipe, — варіантами є імена цього типу, оголошені власними документами вашого робочого простору, а для Component або Feature — також імена, оголошені налаштованими catalog_dirs, кожне пропонується один раз і в порядку імен. Тож робочому простору, який бере свої Components і Features з каталогу, їх пропонують, а не лише те, що він створив сам. Recipes і FeatureRecipes, що пропонуються як значення відображення Manifest, беруться з власних документів робочого простору. Сутність, яка є лише в кеші артефактів або в реєстрі, не пропонується: відповідь на автодоповнення ніколи нічого не завантажує. release необов’язковий і дає відповідь у термінах цієї Release — див. Відповідь у термінах однієї Release.
  • aggrega/resolve — розв’язати сутність, на яку посилаються в позиції (перехід до визначення). release необов’язковий і дає відповідь у термінах цієї Release — див. Відповідь у термінах однієї Release.
  • aggrega/findReferences / aggrega/findImplementations. Кожен приймає необов’язковий release і дає відповідь у термінах цієї Release — див. Відповідь у термінах однієї Release.
  • aggrega/irGraph — скомпільований граф IR для сутності Release, для інтроспекції в редакторі. release — це шлях відносно кореня робочого простору, що називає сутність Release усередині нього, — те саме значення, яке приймає aggrega build --release під час запуску з кореня. Будь-яку іншу форму буде відхилено стандартною помилкою недійсних параметрів, яка називає, що слід надіслати натомість: абсолютний шлях, шлях, що веде за межі кореня робочого простору, — чи то виходить за них так, як записаний, чи то веде назовні через посилання, до файлу або до каталогу на шляху, — і порожнє значення відхиляються, а не розв’язуються, тож запит ніколи не звітує про файл, якого робочий простір не містить. Сутність Release, яку називає конфігурація вашого робочого простору як build.authoring_release або як ключ workspace.releases, належить робочому простору, хоч би де лежав її файл, тому посилання всередині робочого простору, що веде до неї, приймається — так само, як її перелічує aggrega/releaseCandidates. Каталог каталогу сутностей, який читає Release і який неможливо обійти — наприклад, той, що існує, але не може бути прочитаний, — відхиляється так, як його відхиляє aggrega inspect, ще до того, як буде прочитано будь-що інше: помилка — 1004 entity-not-resolvable, її повідомлення — це звіт, який командний рядок друкує для цього каталогу, в одному рядку ([CATALOG_ERROR] <directory>: catalog load: …), і граф для решти каталогів не будується. Каталог, який перелічує конфігурація робочого простору і який не є каталогом, — наприклад, на його місці нічого немає, — відхиляється так само й у той самий момент, 1004 entity-not-resolvable, а його повідомлення — це відмова, яку йому дає кожна команда і яка називає запис, файл конфігурації та рядок, що його перелічують, і параметр (Звідки читаються локальні сутності). Каталог сутностей, що містить посилання, яке веде за межі каталогу, у яких мають лишатися його читання, — документ або каталог, на який посилаються з іншого місця, усередині каталогу сутностей у робочому просторі чи всередині того, який конфігурація називає поза ним, — відхиляється так само й у той самий момент, з 1004 і власним реченням цієї умови, що називає посилання і те, куди воно веде: через таке посилання нічого не читається, а граф, побудований без нього, міг би натомість розв’язати іншу сутність з тим самим ім’ям. Те саме стосується посилання, що веде назовні серед документів поруч із Release, коли Release називає свою сутність Aggregate або свою сутність Manifest за ідентичністю. Файл, який Release, її Manifest або Release, яку вона розширює, називає за шляхом — aggregate:, manifest:, extends: або параметри $import:, — і який веде за межі робочого простору, як записано чи через посилання, відхиляється з власним реченням цієї умови (fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Посилання на інший файл веде за межі каталогу, у якому має лишатися)»), причому дані помилки вказують на ключ у Release, що привів до файлу, і з цього файлу нічого не читається; сутність Release, яку конфігурація називає поза робочим простором, так само обмежується каталогом, що її містить, тож шлях, який вона або Release з її ланцюжка записує і який виходить за межі цього каталогу, теж відхиляється. Зверніть увагу, що aggrega/releaseCandidates відповідає абсолютними шляхами, тож клієнт, який передає дані з однієї поверхні в іншу, перетворює їх між двома формами. Те, що цей параметр відхиляє написання, які приймають параметри окремого документа file і uri, зроблено навмисно, а Які написання приймає параметр, який ви надсилаєте пояснює, що це визначає. Граф приховує кожне значення, яке автор оголосив чутливим, точно так само, як --ir-graph приховує його в командному рядку: кожне замінюється маркером, який описує aggrega-inspect «Машинозчитуваний вивід», а все інше передається так, як його записав компілятор. unredacted: true запитує ці значення у відкритому вигляді — це написання в протоколі для --unredacted командного рядка і єдиний спосіб їх запитати; якщо параметр відсутній або false, відповідь їх приховує. Усе, куди потім потрапить відповідь, міститиме ці значення у відкритому вигляді, тож клієнт запитує їх лише тоді, коли це зробила людина, яка ним користується.
  • aggrega/build — компілює Release і записує його артефакти у вихідний каталог робочого простору, той самий каталог, у який записує aggrega build, коли його запущено з кореня робочого простору. release має той самий контракт, що й вище. Рендеринг виконується з усіма перевірками ввімкненими, тож розбіжність, на якій зупинилася б збірка з командного рядка, зупиняє і тут. Каталог каталогу, який читає Release і який не вдається обійти — наприклад, той, що існує, але не може бути прочитаний, — відхиляється так само, як його відхиляє aggrega build, ще до того, як щось буде записано: жодного артефакту і жодного lockfile там, де задано autoPull. Так само відхиляється каталог, який перелічує конфігурація робочого простору, але який не є каталогом, — тими словами, якими його відхиляє aggrega build (Where local entities are read from). Відмова — та сама, яку дає aggrega/irGraph для того самого каталогу: 1004 entity-not-resolvable зі звітом командного рядка в одному рядку; а посилання, що веде за межі читання каталогу каталогу або за межі документів поруч із Release, відхиляється так само, як його відхиляє aggrega/irGraph, і нічого не записується. Відповідь називає outputDirectory, у який виконано запис, і записані files — кожен відносно цього каталогу й у відсортованому порядку, — разом із будь-якими notices, що їх породив запуск; знахідки, які мають позицію в документі, натомість надходять через aggrega/publishDiagnostics. На Release, що відмовляє під час рендерингу, відповідається цією відмовою словами компілятора, з усіма причинами, а відмова публікується там, куди вона вказує, — див. A refusal raised while rendering. Якщо було задано autoPull, відповідь також містить dependencyResolution — той самий звіт, яким відповідає aggrega/resolveDependencies, тож клієнт, що заповнив залежності в межах збірки, читає, що було закріплено, не запитуючи вдруге, — а також звідки розв’язання цієї збірки взяло кожне посилання; це факт про той запуск, якого lockfile не записує. Кожне повідомлення має class поверхні, яка його породила, — deprecation, catalog, catalog-lint, extends, release-composition або dependency-resolution для рядка, який породило описане нижче розв’язання залежностей, — і порожній class, якщо демон не має назви для цієї поверхні; клієнт тоді показує просто text, а не вгадує найближчий відповідник. Файли, які запис знаходить у вихідному каталозі або в каталозі під ним, у який він записав файл чи через який пройшов, і яких ця збірка не записала, залишаються на місці й називаються в одному повідомленні після власних повідомлень запуску, з порожнім class, тим реченням, яким aggrega build виводить своє попередження, — див. Файли, які збірка не записала; files ніколи їх не називає. outputParent вказує, де всередині робочого простору опиняться артефакти, і його назва повністю передає його значення: це каталог, усередині якого створюється вихідний каталог, тож надсилання docs записує артефакти до docs/dist, а не в сам docs, — саме те, що дає збірка, запущена в docs у терміналі. Якщо його пропустити, збірка записує туди, куди записує запуск у корені робочого простору. Він читається інакше, ніж outputDir, який приймають інші запити із записом, і це зроблено навмисно: ті називають каталог, у який виконується запис, а цей називає батьківський каталог для нього, і вони мають різні назви, бо це різні речі. Це все одно місце призначення всередині робочого простору, тож абсолютне значення, значення, що виходить за межі кореня, і значення, що веде за межі кореня через посилання, — зв’язаний каталог поза коренем або ще не створений каталог під ним, — відхиляються, а не розв’язуються. Вихідний каталог, створений усередині нього, і кожен файл, який збірка там записує, також обмежені робочим простором: якщо один із них веде за межі робочого простору через посилання, збірка відхиляється з 1004 і власним реченням цієї умови, що називає посилання і те, куди воно веде, і нічого не очищується й не записується. autoPull розв’язує залежності Release перед рендерингом — те саме розв’язання, яке виконує aggrega/resolveDependencies, — і вимкнений, якщо запит його не просить, що відповідає типовому значенню самого командного рядка; без нього Release, що не має lockfile, відхиляється з помилкою про відсутній lockfile, яка називає, що слід запустити. Із заданим autoPull цей запит звертається до реєстрів і записує lockfile — див. Reaching a registry, and writing. Запит, що спершу виконує розв’язання, однаково рендерить Release один раз: з’ясування того, які віддалені посилання споживає Release, саме по собі є рендерингом, тож розв’язання вже відрендерило те, чого стосується збірка, і відповідь на збірку дається з того рендерингу, а не повторює його. policyInput називає каталог усередині робочого простору, відносно його кореня, у який збірка також записує корисне навантаження, яке кожна роль управління передає підключеному там плагіну, — файли, які записує aggrega build --policy-input, під тими самими назвами, — незалежно від того, завершилася збірка чи зупинилася; потім notices відповіді повідомляють, скільки файлів записано, і називають кожну роль, для якої не записано жодного файлу, з порожнім class. У разі невдалого запиту записані файли залишаються на диску, а цього звіту у відповіді немає: конверт помилки містить лише відмову. Це місце призначення, тож абсолютне значення або значення, що виходить за межі робочого простору, відхиляється до того, як щось запуститься.
  • aggrega/buildPreview — повідомляє, що записала б збірка Release, нічого з цього не записуючи. release має той самий контракт, що й вище. Запит виконує те саме обчислення, що й aggrega/build, з тими самими перевірками, тож Release або відмовить в обох, або буде звітований обома, — і саме тому вибір між ними є вибором щодо результату, а не щодо суворості. Каталог каталогу сутностей, який читає Release і який неможливо обійти або який містить посилання, що виводить за межі каталогу, в якому мають залишатися його читання, відхиляється так само, ще до будь-якого рендерингу, і так само — каталог, який перелічує конфігурація робочого простору, але який не є каталогом, як і в aggrega/build. Відповідь містить files — відносні щодо виводу імена, які створила б збірка, відсортовані, — разом із будь-якими notices; outputDirectory немає, бо нічого ніде не записано, щоб його називати. На Release, що відмовляє під час рендерингу, відповідають і публікують відмову так само, як це робить aggrega/build. Запит відхиляє autoPull з помилкою invalid-params, яка називає, що слід надіслати натомість: заповнення залежностей записує lockfile, а цей запит lockfile не записує. Він не звертається до жодного реєстру. policyInput — єдиний запис, який він виконує, і лише тоді, коли параметр надіслано: він записує корисні навантаження управління в цей каталог точно так само, як aggrega/build, — файли, які записує aggrega build --dry-run --policy-input, — не торкаючись вихідного каталогу й lockfile, з тим самим звітом у notices і тим самим обмеженням: у разі невдалого запиту записані файли залишаються на диску, а звіту у відповіді немає.
  • aggrega/resolveDependencies — розв’язує залежності каталогів і джерел сутності Release у кеш, закріплює зовнішні вхідні дані, які споживає її рендеринг, у сховищі з адресацією за вмістом і записує її lockfile. release — це шлях відносно кореня робочого простору, те саме значення, яке приймає aggrega/irGraph, і відхиляється воно в тих самих формах. upgrade відкидає записані закріплення й розв’язує залежності заново, підіймаючи кожну залежність до найвищої доступної версії; targets звужує це до посилань на сутності, які він називає, зберігаючи всі інші закріплення. verify перевіряє записане розв’язання щодо того, яке цей запит виконав би без нього, так само дотримуючись записаних закріплень, і не записує ні lockfile, ні запис довіри до плагінів, ні entity.lock — кеш читається й заповнюється так само, як і без нього, — відповідаючи verified: true і toolchain, який записано в lockfile. verify відхиляється як недійсні параметри поряд з upgrade, поряд з targets і поряд з pinSources за будь-якого його значення, ще до того, як щось буде розв’язано чи повідомлено про будь-який поступ: оновлення відкидає закріплення, яких verify має дотримуватися, названі цілі розв’язуються заново лише оновленням, а pinSources визначає, чи розв’язання записує закріплення, яких бракує в entity.lock, чи відмовляє через них, і жодного з цього не робить порівняння, яке не записує entity.lock. Командний рядок і інструмент асистента відхиляють ті самі пари. Відповідь називає lockfile, який було записано або з яким виконано порівняння, і кожне закріплене посилання в entities, libraries і plugins, причому кожен запис містить version, до якої його розв’язано, і його source — звідки цей запуск узяв посилання, тим словом, яке aggrega pull --detail виводить для того самого розв’язання: fetched-fresh, cache-reuse, local, in-binary або external, — а поряд sourceArtifacts, trustedPlugins, externalInputs — скільки зовнішніх вхідних даних закріплює lockfile після завершення запуску, враховуючи як перенесені, так і виявлені цим запуском, — і будь-які notices, які виникли під час розв’язання. 🔴 Успішна відповідь сама по собі не означає, що закріплення зовнішніх вхідних даних завершене. Якщо запуск закріпив усі залежності, але не зміг до кінця з’ясувати, які зовнішні вхідні дані споживає Release, він повертає incompleteExternalInputs із зазначенням того, що зупинило виявлення, і все одно відповідає успіхом — закріплення залежностей повні й записані на диск, тож повідомлення про невдачу всього запиту підказало б вам переробити вже правильну роботу. Прочитайте це поле, перш ніж вважати lockfile повністю закріпленим: воно відсутнє, коли нічого не залишилося невиявленим, тож сигналом є саме його наявність. Параметра каталогу каталогів немає: стек пошуку — той, який налаштовано в робочому просторі. Це єдиний у сесії запит на закріплення для сутності Release, і саме тут закріплюються також зовнішні вхідні дані — які URL-адреси споживає рендеринг, випливає з того, що він рендерить, тож цей запит рендерить Release, щоб це з’ясувати, а запит збирання потім обслуговується з того, що він записав. Сутність Recipe або FeatureRecipe, яку збирає Release і чий entity.lock не містить закріплення для вхідних даних, які читає сутність, призводить до відхилення запиту з зазначенням aggrega pin і кожного незаписаного вхідного елемента; pinSources: true натомість виконує цей крок закріплення для таких сутностей, записуючи entity.lock поряд із кожною, — той самий крок, що виконує aggrega/pin, із записом тих самих байтів. Якщо pinSources відсутній, він слідує налаштуванню pin_sources_at_pull робочого простору; якщо його надіслано, він перевизначає це налаштування в обох напрямках, тож false відмовляє навіть у робочому просторі, налаштованому на закріплення. Цей запит звертається до реєстрів і виконує запис — див. Звернення до реєстру та запис.
  • aggrega/pin — записує в entity.lock поряд із сутністю Recipe або FeatureRecipe закріплення вмісту для кожних вхідних даних, які сутність читає поза власним документом: віддаленого джерела, координати якого записано повністю, файлу, який імпортує запис artifacts, і кожного файлу, який локальне джерело додає до того, що містить публікація сутності. Це той самий крок, який aggrega pin виконує в терміналі, і він записує ті самі байти. entity обов’язковий і є шляхом відносно кореня робочого простору, що називає документ сутності; відхиляється він у тих самих трьох формах, що й release. Сутність Release не називається: віддалене джерело, координати якого не містять шаблону, називає один артефакт для кожної сутності Release, що використовує цю сутність, тож для його закріплення не потрібно нічого, що надає Release, тоді як віддалене джерело, координати якого походять із шаблону, закріплюється окремо для кожної Release запитом aggrega/resolveDependencies; локальне джерело, записане як шаблон, додає кожен файл у каталозі сутності, і кожен із них закріплюється тут. dryRun розв’язує вхідні дані й повертає lock, який записав би крок, як content, нічого не записуючи поряд із сутністю; кеш вмісту все одно заповнюється. Відповідь містить entity, kind, name і pinnable — false для типу, який не читає нічого, що записується в lock, і тоді нічого поряд із сутністю не змінено, а всі інші поля відсутні, — а інакше lock, який було записано, changed (false, якщо lock уже містив усі закріплення й залишився побайтово ідентичним), removed, якщо сутність тепер не читає нічого, що записується в lock, і її lock видалено, та pins — по одному запису на клас закріплень із кількістю, яку містить lock. Сам файл сутності ніколи не записується. Це виконує запис поряд із сутністю, усередині робочого простору, і звертається до хостів, які називають джерела сутності — див. Звернення до реєстру та запис.
  • aggrega/cacheStatus — що містять кеші на диску: по одному запису на кожен кешований елемент із його розміром і, якщо він є, дайджестом вмісту, згруповано за класами. Приймає робочий простір і нічого більше. Кожен клас містить reach — workspace для кешу артефактів у власному каталозі кешу цього робочого простору, machine для сховищ скомпільованих модулів, описів плагінів і пакетів документації, спільних для всіх проєктів на машині, — а scope прямо називає класи рівня машини. Він нічого не записує. Див. Звернення до реєстру та запис, щоб дізнатися, чому охоплення вказано у відповіді, яка нічого не змінює.
  • aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear — звільняють кешований вміст. Очищення видаляє те, на що не посилається жоден lockfile робочого простору; витіснення зменшує сховище скомпільованих модулів до maxSize — кількості байтів, записаної так, як її записує командний рядок (5GiB, 512MiB або кількість байтів); повне очищення стирає всі кеші, до яких звертається ця сесія. Кожна відповідь називає те, що видалено, причому кожне видалення містить reach класу, з якого воно походить, і кожна містить scope. Кожна відповідь також називає те, що залишено на місці, бо інший процес тримав це відкритим — Windows відмовляється видаляти відкритий файл, і операція продовжується з рештою, а не завершується невдачею: очищення або витіснення перелічує такі записи в heldOpen, а повне очищення для кожного спорожненого кешу підраховує залишені файли в heldOpenFiles і їхній розмір у heldOpenBytes. В інших системах список порожній, а лічильники нульові, і пізніший запуск може звільнити те, що залишилося. Ці запити виходять за межі робочого простору — див. Звернення до реєстру та запис.
  • aggrega/registryList — реєстри, до яких налаштовано звертатися цьому робочому простору: для кожного запису — хост, необов’язковий псевдонім, чи є він типовим, його політика довіри у вигляді окремих полів і чи є облікові дані для цього хоста. Приймає робочий простір і нічого більше. Він не звертається до жодного реєстру. Стан облікових даних повідомляє лише про наявність — ніколи не самі облікові дані, ніколи не їхню форму і ніколи не те, чи прийняв би їх реєстр, адже для цього потрібен мережевий обмін, якого перелік не виконує, — і читається він зі сховища облікових даних рівня машини, про що прямо повідомляє credentialStateIsMachineWide.
  • aggrega/search — пошук у локальному індексі налаштованих реєстрів. Кожне поле звужує пошук і кожне необов’язкове, тож порожній об’єкт параметрів запитує все, що містить індекс. Запит не звертається до мережі: індекс — це офлайн-знімок, записаний у власному каталозі кешу цього робочого простору. Указана версія — та, яку взяло б розв’язання: версія, відкликання якої має підпис, якому довіряє цей робочий простір, виключається й називається в retracted, — а відповідь містить власне походження: indexes подає вік знімка кожного реєстру, у якому виконувався пошук, stale позначає знімок, який варто оновити, а missingIndexHosts називає налаштовані реєстри без локального індексу, вміст яких тому відсутній у відповіді.
  • aggrega/registryAdd — реєструє реєстр і його політику довіри до підписів. host обов’язковий; усе інше формує політику або ціль запису. keyPath і trustedRoot називають файли: абсолютне значення — скажімо, файл, вибраний у діалоговому вікні, — читається там, куди воно вказує; відносне називає файл усередині робочого простору й розв’язується відносно кореня робочого простору, а не каталогу, у якому працює демон, а значення, що виходить за межі кореня або веде за його межі через посилання, відхиляється з помилкою недійсних параметрів до того, як щось буде прочитано чи записано. Відносний trustedRoot записується як файл, який він називає в робочому просторі, тож запис називає цей файл незалежно від того, у якому каталозі пізніше виконується перевірка. fetchTrust за замовчуванням має значення true, коли ключ відсутній, як і в командному рядку, і бере власну оголошену політику реєстру під час першого звернення; trust у відповіді повідомляє, що сталося: політику закріплено, реєстр не оголосив жодної (а з unreachable поруч — узагалі був недосяжний), замість неї закріплено вбудовану базову політику офіційного хабу, або отримання не виконувалося. Реєстрація та сама, яку виконує aggrega registry add: те саме отримання з тими самими мережевими налаштуваннями, що записує той самий запис байт у байт. В офлайн-робочому просторі отримання відхиляється до будь-якого з’єднання, тож до реєстру ніколи не звертаються, і реєстр, відмінний від офіційного хабу, відхиляється, якщо запит не надає identities або keyPath, які реєструють саме те, що надіслано, і не виконують отримання: повідомлення помилки — це речення, яке друкує командний рядок, із коротким кодом умови E0310 попереду, — так само, як повідомлення кожної відмови цього запиту, що називає умову, починається з її короткого коду, — і нічого не записується. Офіційний хаб усе одно записується з вбудованою базовою політикою, а відповідь містить trust.baseline зі значенням true і trust.reason, що пояснює: до хабу не зверталися по його політику довіри, бо робочий простір офлайн, — саме з цієї причини починається повідомлення командного рядка, — і без notAdvertised, бо до хабу ніколи не зверталися. За замовчуванням це записує глобальну конфігурацію — див. Звернення до реєстру та запис.
  • aggrega/registryRemove — видаляє запис реєстру, адресований за хостом або зручним псевдонімом. Токен, що нічому не відповідає, відхиляється, а не отримує відповідь про успіх над незміненою конфігурацією. За замовчуванням це записує глобальну конфігурацію — див. Звернення до реєстру та запис.
  • aggrega/logout — видаляє збережені облікові дані для реєстру, так само як aggrega logout у терміналі. registry обов’язковий і називає хост реєстру так, як ви на ньому автентифікувалися; зручного псевдоніма тут розв’язувати не потрібно, бо сховище облікових даних індексується за адресою, на якій автентифікується клієнт, а не за чимось, що називає конфігурація, тож хост, якого не налаштовує жоден робочий простір, усе ще може мати облікові дані, які можна видалити. Хост, для якого сховище не містить облікових даних, видаляється успішно, і нічого не перезаписується: виклик, що просив, щоб у хоста не було облікових даних, отримав те, що просив, тож це відповідь, а не помилка, і так само поводиться команда в терміналі. Відповідь містить registry і scope. Вона не містить жодної частини облікових даних у жодній формі й нічого не повідомляє про те, чи вони там були: щоб це з’ясувати, знадобилося б повторне читання сховища, якого ніхто не просив, тож запитуйте aggrega/registryList, коли питання саме в наявності. Запит не звертається до жодного реєстру: видалення збережених облікових даних — локальна дія, і чи прийняв би реєстр ці облікові дані, не перевіряється. Це змінює сховище облікових даних, спільне для всіх проєктів на машині — див. Звернення до реєстру та запис.
  • aggrega/registryUpdate — оновлює локальний індекс для пошуку, який читає aggrega/search. Якщо registry відсутній, оновлюються всі налаштовані реєстри; якщо його вказано, оновлюється лише цей реєстр. upgrade заново читає кожен репозиторій повністю, нічого не порівнюючи з уже записаним індексом; оновлення без нього й так заново читає все, що змінилося. Відповідь містить кількість записів кожного хоста, репозиторії, які не вдалося прочитати, — кожен із reason, що починається з виду останнього збою читання, якщо такий є, — readsRetried, кількість читань, які реєстр мимохідь відхилив або обірвав і які запитано знову, кожне враховане один раз, включно з нулем, виявлені маркери застарілості, error хоста, що зазнав збою, — з unreachable поруч, якщо реєстр був недосяжний, — і indexRoot, каталог у власному кеші цього робочого простору, куди записано індекси. Це звертається до кожного реєстру, який оновлюється — див. Звернення до реєстру та запис.
  • aggrega/publishEntity — упакувати сутність каталогу й опублікувати її в реєстрі. entity — шлях відносно кореня робочого простору, що називає документ для публікації; його відхиляють у тих самих трьох випадках, що й release, — відсутній, абсолютний або такий, що розв’язується за межі кореня. Сутності Plugin також потрібен plugin — шлях того самого типу, що називає виконуваний файл, опублікований у власному маніфесті сутності. registry — місце призначення; за замовчуванням це реєстр, налаштований для робочого простору. dryRun обчислює пакет і дайджест, який дала б його публікація, і не звертається до жодного реєстру. Якщо sign пропущено, діє власна політика реєстру призначення — так само чинить командний рядок, коли його прапорця немає, — а надсилання поля є вибором того, хто викликає; жоден із варіантів не послаблює відмову, бо політика реєстру чи робочого простору, що вимагає підпису, відхиляє непідписану публікацію незалежно від значення поля. pinSources: true запускає для сутності крок закріплення автора сутності перед упакуванням, тож entity.lock, який цей крок записує поруч, входить до опублікованого, — це той самий крок, що його виконує aggrega/pin. Він виконується перед будь-якою відмовою, що оцінює вміст сутності, — політикою підписування, захистом незмінності, — тож публікація, відхилена на цьому етапі, все одно залишає записаний lock-файл; відмова щодо самого запиту, як-от офлайн-робочий простір чи відсутність місця призначення, настає раніше й нічого не закріплює, так само як і відмова для сутності, що ділить каталог з іншою сутністю, куди крок не має записувати lock-файл. Якщо поле відсутнє, діє параметр робочого простору pin_sources_at_push; якщо надіслане, воно перевизначає цей параметр в обидва боки. Під dryRun крок повідомляє про lock-файл, який записав би, і нічого не записує. Публікація, що не виконує цей крок, відхиляє сутність Recipe або FeatureRecipe, чий entity.lock не містить закріплення для вхідних даних, які вона читає, або містить закріплення, якому вхідні дані вже не відповідають, — ще до упакування, також під dryRun, — називаючи aggrega pin, pinSources і pin_sources_at_push; це та сама відмова, яку aggrega/resolveDependencies видає щодо того самого lock-файлу. Відповідь містить reference, tag, kind, mediaType, пару size, опублікований digest — під dryRun дайджест, який дала б та публікація, той, що друкує aggrega push --dry-run, — signed, alreadyPublished, dryRun і reach; pin — ту саму відповідь, що дає aggrega/pin, — якщо крок виконувався; і wholeDirectorySource, якщо локальне джерело сутності записане як шаблон, — тоді це поле називає джерело так, як його написано. Таке джерело обирає свій каталог лише тоді, коли сутність Release заповнює шаблон, тож публікація містить усі файли з каталогу сутності, а не лише ті, що сутність називає, і саме з цього поля той, хто викликає, дізнається про це — також під час пробного запуску. Відповідь також містить windowsUnusableEntries, якщо архів публікації має записи, які Windows не може зберегти в записаному вигляді, — шлях із частиною, названою на честь пристрою, як-от CON, AUX або NUL, у будь-якому регістрі й з будь-яким розширенням, або частиною, що закінчується крапкою чи пробілом, — і називає кожен такий запис: спочатку ім’я файлу самого документа сутності, потім файли, які він несе; поле відсутнє, якщо таких записів немає, зокрема для сутності, опублікованої лише як документ. aggrega, запущений у Windows, відмовляється розпаковувати такий запис, тож робочий простір у Windows не може використовувати цю версію. Це ті самі записи, про які попереджає aggrega push, і запит, що попросив звітувати про перебіг, бачить ті самі рядки попередження серед поступу публікації; жодне з них нічого не відхиляє, тож публікація відбувається або відхиляється так само, як і без них, також під dryRun. Це записує в реєстр і виходить за межі цієї машини, а з кроком закріплення також записує поруч із сутністю — див. Звернення до реєстру та запис.
  • aggrega/publishArtifact — опублікувати окремий артефакт даних, як-от пакет документації. file — шлях відносно кореня робочого простору з тим самим контрактом, і його байти публікуються дослівно: жодна обгортка сутності не розбирається і жоден тип не обробляється. name і tag називають, під чим його опубліковано, і обидва обов’язкові. mediaType за замовчуванням має тип пакета документації. Відповідь містить reference, tag, mediaType, пару size, опублікований digest, alreadyPublished, dryRun і reach. Запит нічого не підписує — опублікований артефакт підписують згодом за посиланням за допомогою aggrega/signArtifacts, якому потрібне лише посилання з цієї відповіді. Це записує в реєстр і виходить за межі цієї машини — див. Звернення до реєстру та запис.
  • aggrega/signArtifacts — підписати вже опубліковані артефакти й приєднати кожен підпис. references містить одну або кілька адрес реєстру, а не шляхів, тож контракт відносних шляхів робочого простору до них не застосовується; порожній список або порожній запис у ньому відхиляється. Одна ідентичність обслуговує весь пакет і визначається до підписання будь-якого посилання, тож пакет, для якого взагалі немає доступних облікових даних, відхиляється на початку, а не посередині. Так само відхиляється пакет, посиланням якого потрібні різні облікові дані: запит не називає ключа, тож це означає, що конфігурація робочого простору називає наявний ключ для реєстру одного посилання і жодного або інший ключ — для реєстру другого; нічого не підписується, а відмова називає реєстри з кожного боку, як описано в References signed together need different signing credentials (Посилання, що підписуються разом, потребують різних облікових даних для підписування). Підписання посилання, за яким нічого не опубліковано, відхиляється, а не приєднується до порожнечі, а посилання, що вже має підпис, який перевіряє політика довіри його реєстру, залишається як є і зараховується як підписане, як описано в aggrega sign. jobs, необов’язковий, задає, скільки посилань підписується одночасно: якщо його немає, посилання підписуються одне за одним, а значення менше за 1 відхиляється помилкою invalid-params до читання будь-якого посилання. Кожне посилання однаково підписується точно так, як було б підписане окремо, як описано в aggrega sign, а хід виконання, про який повідомляє запит, і відповідь зберігають порядок, у якому надано посилання. Відповідь містить signed, кожен запис якого називає reference і опублікований digest, до якого прив’язаний його підпис, поряд із reach; пакет, у якому хоч одне посилання не вдалося, отримує відповідь-збій із назвою кожного такого посилання, а не результат зі скороченим списком. Це записує в реєстр і виходить за межі цієї машини — див. Звернення до реєстру та запис.
  • aggrega/deprecateArtifact — приєднати підписаний маркер застарілості до вже опублікованого артефакту. Надішліть або одне reference з його severity і reason, або from, що називає файл пакета відносно кореня робочого простору, — надсилання обох відхиляється. Поля вмісту обов’язкові, а не запитуються інтерактивно: за цим потоком ніхто не стежить, тож запит, у якому одного бракує, відхиляється з назвою того, що слід надіслати. Вони стосуються лише одного reference: файл пакета несе вміст кожного маркера у власних записах, тож severity, reason, replacement чи message, надіслані поряд із from, відхиляються як недійсний параметр із назвою кожного надісланого поля, а не ігноруються. Тут діють ті самі безключові вхідні дані, що їх приймають два запити підписування, бо маркер підписується за власним дайджестом, а записи файлу пакета прив’язуються до одних облікових даних так само, як посилання пакета підписування. Відповідь містить marked, кожен запис якого називає відкликане reference, його severity, позначку issuedOn і власний digest маніфесту маркера — маркер приєднується як нетегований referrer артефакту, який він відкликає, тож ніщо інше на нього не посилається, — поряд із reach. Це записує в реєстр і виходить за межі цієї машини — див. Звернення до реєстру та запис.
  • aggrega/catalogIndex — індекс сутностей: kind, name, apiVersion, description, labels, файл джерела та origin кожної сутності в робочому просторі, який назвав запит. Приймає робочий простір і, необов’язково, release: набір є властивістю цього кореня робочого простору та каталогів, які він налаштовує, або, з release, каталогів, які конфігурація надає цій сутності Release — див. Відповідь у термінах однієї сутності Release. Він охоплює обидва місця, звідки походить сутність, — документи Aggrega під коренем робочого простору та Features, які містять налаштовані каталоги, — оскільки саме з цією поверхнею клієнт зіставляє дані, коли йому потрібні описові поля сутності, а індекс, що знав би лише одне з двох, залишив би частину кожного списку кандидатів нерозв’язною. Документ робочого простору вважається сутністю, коли він оголошує і kind:, і metadata.name та не оголошує apiVersion, що належить групі іншого проєкту, тож YAML, який просто лежить у дереві, — файл values чарта, конфігурація CI, згенерований маніфест Kubernetes — пропускається, а не потрапляє до списку. Документ, що не оголошує apiVersion взагалі, потрапляє до звіту: це документ Aggrega з відсутнім полем, і побачивши його в списку, ви дізнаєтеся, що його треба виправити. Що означають origin і порожній file, див. у розділі Як адресується сутність. Жоден документ за посиланням, що веде за межі кореня робочого простору, не читається: каталог поза коренем не переглядається, а файл поза ним не читається, хоч би що він оголошував, тож сутність, яку ваш редактор показує за таким посиланням, не потрапляє до списку як власна сутність робочого простору — і не пропонується запитами aggrega/attachCandidates чи aggrega/connectionCandidates, які читають ті самі документи, навіть поки цей документ відкрито у вашому редакторі. Це діє незалежно від того, що оголошує документ. Єдиний виняток — сутність Release, яку називає конфігурація вашого робочого простору — як build.authoring_release або як ключ workspace.releases, з оцінкою за файлом, до якого веде посилання, тож назвати посилання чи цей файл однаково, — вона читається з файлу, до якого веде посилання, потрапляє до списку на місці самого посилання, так само як її перелічує aggrega/releaseCandidates, і не називається; файл, названий одним із цих параметрів, що оголошує щось інше, ніж Release, до списку не потрапляє, а його посилання називається. Налаштовані каталоги — це спосіб, у який робочий простір читає інші сутності, що зберігаються деінде, тож посилання на каталог, який конфігурація перелічує в catalog_dirs — для робочого простору чи для сутності Release, — не переглядається так, як власні документи робочого простору, і також не називається: конфігурація до нього дісталася, і його Features перелічуються з каталогу, як і Features кожного налаштованого каталогу. Features, перелічені з каталогів, ніколи не включають сутність за посиланням, що веде за межі каталогу, у межах якого мають залишатися читання каталогу, — робочого простору для каталогу всередині нього або самого каталогу для того, який конфігурація називає поза ним, — тож сутність, яку відповідь називає такою, що лежить за непрочитаним посиланням, ніколи не потрапляє до списку поруч із цією назвою. Відповідь називає кожне таке посилання в unreadLinkedDirs — для посилання на каталог — і в unreadLinkedFiles — для посилання, власна назва якого закінчується на .yaml або .yml і яке веде до файлу, — відносно кореня, там, де лежить посилання, у порядку перегляду робочого простору, тож клієнт може пояснити причину. Посилання, яке пошук пропускає за назвою, за розташуванням або через .gitignore, не називається, а у відповіді в термінах сутності Release не називається й посилання в каталозі, який читають лише інші Releases. Посилання в каталозі поза робочим простором не має місця відносно кореня, за яким його можна назвати, і не називається. Обидва поля присутні завжди і порожні, коли таких посилань немає. Якщо власний файл конфігурації робочого простору або накладка, якою володіє CI, поруч із ним сама є посиланням, що веде за межі робочого простору, цей файл називається в unreadLinkedFiles незалежно від того, як його обробляє пошук, а індекс є власним читанням робочого простору без будь-яких налаштувань — для нього не читається жоден каталог, а індекс у термінах сутності Release відхиляється; див. Корінь робочого простору та активна сутність Release.
  • aggrega/entityDefinition — у що розв’язується названа сутність: її kind, її власні name і version, її description і publishScope, якщо вони є, file, у якому її оголошено, authoredLength авторського тексту за нею та її definition як документ YAML із уже застосованим успадкуванням. file повідомляється для кожного типу як шлях, який можна відкрити, — відносний до кореня робочого простору для документа всередині нього, абсолютний для документа поза ним, згідно з розділом Як записується повідомлений шлях. Він порожній в одному випадку: сутність, розв’язана з реєстру, не має на цій машині авторського документа, який можна назвати. authoredLength відповідає на інше запитання — скільки авторського тексту зберегло розв’язання, — і лише сутність Aggregate обслуговується з ним, тож читайте ці два поля окремо, а не як пару. name — це ідентичність сутності, записана так, як одна сутність посилається на іншу, і вона може мати суфікс версії. Це єдиний запит тут, що починається з назви, а не з курсора, тож саме його слід надсилати, коли ви вже знаєте, яку сутність маєте на увазі. release необов’язковий і розв’язує назву в термінах цієї сутності Release — див. Відповідь у термінах однієї сутності Release. Назва, що ні в що не розв’язується, відхиляється, а не отримує у відповідь порожній документ; див. Як розрізнити дві відмови за назвою. Натомість name може бути посиланням на реєстр — oci://<host>/<repository>:<tag> або @<digest> замість :<tag>, — і тоді відповіддю є сутність, опублікована за цією координатою, прочитана з її реєстру, а published називає прочитане; див. Запит про координату.
  • aggrega/releaseClosure — замикання залежностей сутності Release: яких сутностей вона досягає і в яких розв’язаних версіях, у entities, libraries і plugins, разом з ідентичностями aggregate і manifest, у які розв’язалися два її вказівники, усіма mappingDiagnostics, які викликало розв’язання, та deprecations, записаними щодо досягнутого, — у її lock-файлі та в записі довіри плагінів поруч із ним, тож відкликаний плагін, приєднаний у ролі вердикту, називається так само, як відкликане закріплене посилання. release — це шлях відносно кореня робочого простору, що називає сутність Release всередині нього, те саме значення, що приймає aggrega/irGraph, і відхиляється в тих самих формах; з тієї самої причини він потребує lock-файлу. Нічого не рендериться. Її записи не називають source: вони кажуть, від чого залежить Release, а не що зробив один запуск, — про це повідомляє aggrega/resolveDependencies. Див. Замикання — це не граф, оскільки клієнт, що вже отримує граф, цього не має.
  • aggrega/attachCandidates — які Features можуть приєднуватися до вузла: ті, чию задекларовану застосовність задовольняють мітки вузла. Надсилайте рівно одну координату. node називає документ робочого простору за його metadata.name; graphNode називає вузол на скомпільованому графі release за ідентифікатором, під яким цей граф його зберігає; labels передає набір міток безпосередньо й нічого не називає — для клієнта, який уже має такий набір. Відповідь повторює координату, для якої вона дана (порожню, якщо повторювати нічого), містить nodeLabels — пари міток, щодо яких обчислювалася відповідність, labelSource, що вказує, якого виду цей набір міток, і кожного кандидата як kind, name, вихідний файл і origin, що його адресують. Повернення міток робить відповідь перевірюваною сама по собі: клієнт може пояснити, чому запропоновано сутність Feature, не складаючи власного уявлення про мітки вузла, — а саме так відповідь клієнта й відповідь компілятора розходяться. Для вузла графа пропонуються ті Features, яких досягає сутність Release цього вузла. Поруч із graphNode параметр connection називає одне з’єднання, яке малює компонент цього вузла, — його socket і alias, — і тоді відповідь також містить slots: кожен слот, який оголошує сокет цього з’єднання, разом із Features, що можуть його заповнити, або noSlotReason, якщо жоден заповнити не можна. Див. Що повідомляє відповідь щодо кандидатів на приєднання.
  • aggrega/connectionCandidates — з чим може з’єднуватися названа сутність. node — це metadata.name сутності, та сама координата, яку aggrega/attachCandidates приймає під цією назвою. Див. Що повідомляє відповідь щодо кандидатів на з’єднання нижче, оскільки дві половини відповіді не однаково повні, і відповідь вказує, яка з них яка.
  • aggrega/insertionPoint — де в авторському документі має розташовуватися новий запис під названим контейнером, у формі, яку клієнт застосовує, не розбираючи документ сам. file називає документ, що є в робочому просторі, — відносно кореня робочого простору, абсолютним шляхом або як його адресу file://; документ поза коренем, як записано чи через посилання, що веде за його межі (на файл або на каталог дорогою), відхиляється, хоч би як його названо і незалежно від того, чи маєте ви його копію; container — структурний шлях від кореня документа до контейнера, всередину якого йде запис, кожен елемент якого — ключ відображення або позиція в послідовності, записана десятковим числом. Цей шлях задаєте ви — демон читає власну структуру документа й ніколи не визначає, де щось має бути, за його назвою. Див. Що повідомляє відповідь щодо точки вставлення, оскільки самої позиції недостатньо, щоб застосувати редагування.
  • aggrega/attachmentContainer — у якому документі має бути приєднання сутності Feature для вузла і в якому контейнері всередині нього. graphNode називає вузол на скомпільованому графі release за ідентифікатором, під яким цей граф його зберігає, і обидва параметри обов’язкові: ідентифікатор вузла — це ключ графа однієї сутності Release і без нього нічого не означає. Відповідь містить node, file і container — список сегментів точно в тій формі, яку приймає aggrega/insertionPoint, тож ця пара поєднується без жодних проміжних обчислень. Для приєднання до одного з’єднання, яке малює компонент вузла, додайте connection з його socket, alias і document — aggregate або release, — і відповідь назве власний контейнер features цього з’єднання в цьому документі. Див. Що повідомляє відповідь щодо контейнера приєднання, оскільки file є частиною відповіді, а не тим, що ви вже знаєте.
  • aggrega/connectionAtPosition — у запис якого з’єднання потрапляє позиція в сутності Aggregate чи Release, з відповіддю в тих термінах, у яких два запити вище приймають з’єднання. file називає документ так само, як його називає aggrega/insertionPoint, і він читається насамперед із того, що сесія для нього зберігає; position — місце в ньому, line і character, що відлічуються від нуля в кодуванні сесії; release називає сутність Release, чий скомпільований граф фіксує з’єднання, і він обов’язковий також для позиції в сутності Aggregate, оскільки вузол графа і з’єднання існують лише на скомпільованому графі. Відповідь містить graphNode і connection — його socket, його alias і document, у якому прочитано позицію, — щоб передати їх aggrega/attachCandidates і aggrega/attachmentContainer без змін, або noConnectionReason, якщо там не записано жодного з’єднання. Див. Що повідомляє відповідь щодо з’єднання в позиції.
  • aggrega/editDocument — застосовує одне обмежене структуроване редагування до авторського документа, зберігаючи кожен байт, якого воно не торкається. Це друга половина двох методів визначення розташування вище: ті кажуть, де має бути запис, і залишають вам скласти й застосувати його, а цей складає й застосовує одне редагування. edit називає, яке з чотирьох — add-component, attach-feature, wire-edge, set-value, — а значення поза ними відхиляється, а не тлумачиться; node — структурний шлях від кореня документа, список сегментів точно в тій формі, яку приймає aggrega/insertionPoint; name — ключ, під яким записується запис, а value — те, що він містить, і їхнє значення випливає з edit; socket читається для wire-edge й ігнорується в інших випадках. dryRun робить усе, що робить звичайний запит, окрім запису, і відповідає відредагованим документом у content — для клієнта, який спершу показує результат авторові; при цьому нічого не створюється, а written порожній. file називає документ відносно кореня робочого простору або його абсолютним шляхом, а документ поза коренем — як записано чи через посилання, що веде за його межі, на файл або на каталог дорогою, — відхиляється без жодного читання чи запису. Це записує названий вами документ усередині робочого простору — воно не розв’язує жодної залежності, не звертається до жодного реєстру й не торкається мережі за жодного способу доставки, а запис можливий лише за умови, що складений документ проходить валідацію за схемою власного виду. Див. Що повідомляє відповідь щодо редагування документа, оскільки за замовчуванням виконується запис, а відмова залишає файл байт у байт таким, яким він був.
  • aggrega/releaseCandidates — документи Release робочого простору, названого в запиті, у вигляді абсолютних шляхів. Приймає робочий простір і нічого іншого: цей набір є властивістю кореня цього робочого простору. Належність визначається видом документа — kind: файлу дорівнює Release — а не назвою файлу, тож сутність Release, названу без звичного префікса, буде запропоновано, а файл, лише названий подібно, — ні. Саме це має показувати вибір «яка Release?» у редакторі, оскільки це той самий набір, з якого обирає каскад активної сутності Release нижче. Відповідь також містить lockfiles, що зіставляє кожну наведену сутність Release — з ключем, який точно збігається з рядком, під яким її наводить releases, — з абсолютним шляхом до її lock-файлу; це поле присутнє завжди і є порожнім об’єктом, якщо робочий простір не містить жодної сутності Release. Вона містить також unreadLinkedDirs, що називає — відносно кореня, де розташоване посилання, — кожне посилання, яке стоїть там, де перелік читав би каталог, і веде до каталогу поза коренем робочого простору: жоден каталог поза коренем не переглядається, тож сутність Release, яку ваш редактор показує в такому каталозі, не наводиться, і саме це поле дає змогу вибору пояснити чому. Посилання на каталог, який ваша конфігурація робочого простору перелічує в catalog_dirs, не називається: конфігурація дісталася до нього як до каталогу каталогів, а не як до місця зберігання Releases. Це поле присутнє завжди і порожнє, якщо такого посилання немає. Поруч із ним unreadLinkedFiles так само називає кожне посилання, власна назва якого закінчується на .yaml або .yml і яке веде до файлу поза коренем робочого простору: жоден такий файл не читається, хоч би що він містив, тож сутність Release, досяжна лише через одне з цих посилань, не наводиться, і крок каскаду нижче з єдиною сутністю Release її не враховує. Виняток — файл, який ваша конфігурація робочого простору називає сутністю Release, — як build.authoring_release або як ключ workspace.releases, з оцінкою за файлом, до якого веде посилання, тож назвати посилання чи цей файл однаково, — він читається й наводиться в місці самого посилання і не називається, за умови що він оголошує сутність Release; файл, що оголошує щось інше, не наводиться, а його посилання називається. Це поле присутнє завжди і порожнє, якщо такого посилання немає. Якщо власний файл конфігурації робочого простору або належне CI накладання поруч із ним саме є посиланням, що веде за межі робочого простору, цей файл називається тут незалежно від того, як його трактує пошук, а перелік читається без жодної конфігурації, тож сутність Release, яку конфігурація назвала б через посилання, не наводиться; див. Корінь робочого простору й активна сутність Release. Див. Де розташований lock-файл сутності Release.
  • aggrega/activeRelease — на яку сутність Release вказує робочий простір, названий у запиті, у вигляді абсолютного шляху в полі release, для клієнта, що вирішує, що вибрати за замовчуванням. Приймає робочий простір і нічого іншого. Поле присутнє завжди, а порожнє значення означає, що робочий простір не вказує на жодну, — це успішна відповідь, а не помилка, тож клієнт, який оновлює її при кожному перезапуску демона, не змушений трактувати звичайний робочий простір як збій. Якщо значення порожнє, відповідь також містить reason — однорядкове резюме того, що шукав каскад, і trace — покроковий звіт про це; обидва пропускаються, якщо сутність Release визначено. Якщо сутність Release визначено, відповідь натомість містить lockfile — абсолютний шлях до lock-файлу цієї сутності Release, який пропускається, якщо жодну не визначено. Сутність Release, яку вона називає, не обов’язково наводить aggrega/releaseCandidates — маркер може назвати сутність Release у каталозі, який той перелік пропускає, наприклад vendor/, або названу без розширення YAML, — тож саме з цієї відповіді клієнт читає lock-файл типової сутності Release. Див. Де розташований lock-файл сутності Release. Запитуйте її, а не виводьте відповідь з одного з вхідних даних каскаду: вхідні дані, яких каскад зрештою не використав, називають іншу сутність Release, ніж та, яку він обрав. Відповідь обчислюється в момент запиту, тож повторний запит після запису маркера, редагування конфігурації чи додавання файлу Release повідомляє нову відповідь, а не стан робочого простору на момент запуску демона.
  • aggrega/setActiveRelease — фіксує сутність Release як типову для робочого простору, названого в запиті, записуючи маркер .aggrega/active-release цього робочого простору, і відповідає точно так, як відповідає aggrega/activeRelease після запису маркера. Приймає робочий простір і release: шлях відносно кореня робочого простору, що називає сутність Release усередині нього, з тими самими вимогами, що й до release у aggrega/irGraph, — абсолютний шлях, шлях, що виходить за межі робочого простору, і порожнє значення відхиляються, як і шлях, що виводить назовні через посилання, якщо ваша конфігурація робочого простору не називає цю сутність Release. Маркер — це один рядок, що називає сутність Release відносно кореня, у формі, яку читає каскад нижче. Він записується всередині робочого простору й більше ніде: якщо .aggrega або сам маркер є посиланням, що веде за межі робочого простору, — незалежно від того, чи існує вже місце, куди воно веде, — запит відхиляється з помилкою invalid-params, повідомлення якої — власне речення цієї умови з її коротким кодом попереду, E0320: … (fatal-halts.md §«A path the operation writes leads through a link out of the directory it must stay inside (Шлях, який записує операція, веде через посилання за межі каталогу, у якому він має залишатися)»), що називає посилання і куди воно веде, і нічого не записується; через посилання, яке залишається в межах робочого простору, запис виконується. Відповідь називає те, на чому зупиняється каскад, а не повторює надіслане вами, і вони різняться, якщо build.authoring_release називає сутність Release, оскільки конфігурація має пріоритет над маркером. Фіксуйте типову сутність саме так, а не записуйте файл самостійно, щоб місце, куди потрапляє маркер, оцінювалося за правилом, якому підлягає кожен файл, що продукт записує в робочому просторі, — див. Межа робочого простору.
  • aggrega/effectiveConfiguration — конфігурація, що діє для робочого простору, названого в запиті, і шар, з якого походить кожне налаштування. Приймає робочий простір і нічого іншого: відповідь є властивістю цього робочого простору. layers перелічує файли конфігурації та перевизначення через змінні середовища, що зробили внесок, від найнижчого пріоритету; settings містить кожне атрибутоване налаштування як його назву через крапки, його чинне значення і source, що його визначило. source записується точно так само, як відповідний запис у layers, тож їх можна безпосередньо поєднати. Див. Що охоплює відповідь щодо чинної конфігурації, щоб дізнатися, який шар називає source, і які межі має значення рядка.
  • aggrega/configInit — створює робочу конфігурацію, реєструючи реєстр і його політику довіри до підписів, щоб нова машина могла завантажувати й перевіряти підписані артефакти без ручного редагування YAML. registry необов’язковий, і за відсутності значення створюється запис офіційного хабу — те саме типове значення, що й у aggrega config init; host у відповіді називає той реєстр, який було використано. global і workspace — це перевизначення цілі запису, і надсилання обох відхиляється. Запит відмовляється перезаписувати наявний файл конфігурації, називаючи цей файл, — надішліть force, щоб усе одно продовжити: тоді запис реєстру об’єднується з наявним вмістом, а інші налаштування зберігаються. dryRun виконує все те саме, що й звичайний запит, окрім запису, і відповідає створеною конфігурацією як content — для клієнта, який показує документ авторові перед збереженням; у цьому режимі нічого не створюється, а written дорівнює false. Відмова через наявний файл діє і з dryRun, тож надішліть разом із ним force, щоб отримати результат об’єднання, який дав би перезапис. В офлайн-робочому просторі можна створити запис лише офіційного хабу: цей запит не приймає ідентичностей чи ключа, тому будь-який інший реєстр відхиляється точно так само, як його відхиляє aggrega/registryAdd, разом із коротким кодом і реченням, і натомість додається через той запит із вручну вказаною політикою. Відповідь містить host, scope, trust і written, а також existed — true, якщо файл конфігурації вже існував (тоді запис реєстру об’єднується з ним, а не створюється новий файл), і відсутнє, якщо файл створюється. Типово цей запит записує глобальну конфігурацію — див. Доступ до реєстру та запис.
  • aggrega/configCapture — фіксує чинну конфігурацію, критичну для збирання, у власному файлі конфігурації цього робочого простору, щоб робочий простір збирався однаково без глобальної конфігурації машини під ним. Ціль запису не приймається: фіксація існує для того, щоб зробити один робочий простір самодостатнім, тому завжди записується файл цього робочого простору. allPlugins розширює зафіксований набір із сокетів, що визначають відрендерений результат, — прив’язок провайдерів і підключень governance для перетворення міток — до всіх сокетів плагінів, додаючи вердиктні гейти governance, гейти лінтерів і сокет імпорту. Відповідь містить configFile, workspaceRoot, captured, sockets і catalogDirs. Див. Що залишає по собі запис конфігурації, оскільки відповідь називає документ, який тепер існує, і наступна дія клієнта — відкрити його.
  • aggrega/skillsInstall — записує вбудовану в цей виконуваний файл навичку Aggrega в теку навичок кожного асистента, якого називає запит, — це та сама інсталяція, яку виконує aggrega skills install у терміналі. agents перелічує асистентів за ідентифікаторами — тими, які повідомляє aggrega/skillsList; ідентифікатор, наданий двічі, інсталюється один раз, а якщо кілька названих асистентів читають одну спільну теку, навичка записується туди один раз. Інсталяція в проєкт його вимагає. Запит global, який не називає жодного асистента, інсталює навичку для асистентів, знайдених на цій машині, як це робить aggrega skills install --global без --agent, — для кожного, чия тека конфігурації є в домашньому каталозі або чия команда є в PATH оточення демона, — і відхиляється без жодного запису, якщо не знайдено жодного; нічого не запитується в користувача, а installed називає асистентів, для яких записано навичку. Без global навичка потрапляє до теки проєкту кожного асистента всередині робочого простору, який називає запит, і ніколи — до каталогу, в якому запущено демон; з global: true вона потрапляє до користувацької теки кожного асистента в домашньому каталозі, який вказує оточення демона (HOME, або USERPROFILE у Windows). Кожне місце призначення перевіряється до будь-якого запису, тож відмова залишає кожну теку такою, якою вона була: ідентифікатор, для якого не відома тека навичок, відхиляється із зазначенням його самого та наявних ідентифікаторів, а файл у місці призначення без рядка коментаря, який має кожна записана копія навички, відхиляється із зазначенням його шляху. Копія з цим рядком — записана попередньою інсталяцією або взята з опублікованого репозиторію навичок — замінюється; саме так новіша версія aggrega оновлює навичку до своєї версії. Тека проєкту, досяжна через посилання, що веде за межі робочого простору, відхиляється, і нічого не записується, як і за будь-якого запису демона в робочому просторі, — див. Межа робочого простору. Відповідь містить skill, installed — по одному запису на кожну записану теку, у порядку, в якому названо асистентів, кожен з agents, які її читають, абсолютним шляхом folder і replaced, — та scope. З global це записує теки, які читає кожен проєкт на машині, — див. Звернення до реєстру та запис.
  • aggrega/skillsList — навички, що постачаються з цим виконуваним файлом, і кожен асистент, для якого aggrega/skillsInstall може їх записати, — перелік, який виводить aggrega skills list. Приймає лише робочий простір і нічого з нього не читає. skills містить name і description кожної навички; agents містить для кожного асистента id, name, projectFolder — відносно кореня проєкту, яким на цій поверхні є робочий простір, названий у запиті, — і userFolder — відносно домашнього каталогу; обидва шляхи розділені скісними рисками, а записи впорядковано за ідентифікатором. Нічого не записує й ні до чого не звертається.
  • aggrega/pluginAdd — шукає в налаштованому реєстрі плагін зазначеного типу й додає його до конфігурації. type і query обидва обов’язкові: type — одне з provider, governance, linter, importer і cli, а query зіставляється з назвами плагінів цього типу й має визначати рівно один, тож запит, що відповідає кільком, відхиляється з переліком кандидатів, а не розв’язується довільно. capability називає можливість, яку обслуговує прив’язка provider, і там є обов’язковим; role називає роль підключення governance — label-transform, ir-verdict або render-verdict — і там є обов’язковим; кожне з них читається лише для свого типу й відхиляється для будь-якого іншого, бо поле, яке мовчки нічого не робить, виглядало б так, ніби спрацювало. acceptCapabilities обов’язкове для cli і підтверджує задекларовані можливості цього плагіна: термінальна команда отримує це рішення, запитуючи користувача, а в цьому інтерфейсі немає кого запитати, тож викликач отримує його сам і надсилає. global і workspace — це перевизначення цілі запису, і надсилання обох відхиляється. dryRun виконує все те саме, що й звичайний запит, окрім запису, і відповідає отриманою конфігурацією як content; нічого не створюється й не змінюється, а written дорівнює false. Реєстр однаково опитується, а версія однаково визначається, бо ідентичність у цьому вмісті — це та ідентичність, яку закріпив би запис. dryRun відхиляється для типу cli, а не ігнорується: те, що фіксує додавання розширення команд, — це дайджест вмісту перевірених байтів, тобто запис, який підтримує компілятор, а не вміст, який хтось редагує, і додавання по ходу кешує ці байти — тому він записується, а не повертається. Версія закріплюється за вас: запит визначає один плагін, і в запис вноситься версія, яку запит називає як <name>:<version>, а якщо її не названо — найвища опублікована версія плагіна; названа версія, яку відкликало оголошення про відкликання, якому довіряє цей робочий простір, однаково закріплюється, а відповідь містить withdrawn: true. Цей запит звертається до реєстру, а додавання типу cli без зазначення області записує глобальну конфігурацію — див. Доступ до реєстру та запис. Див. Що повідомляє зміна плагіна.
  • aggrega/pluginRemove — видаляє запис налаштованого плагіна, щоб він більше не брав участі. type — той самий набір, що й для додавання, а query ідентифікує запис: коротку назву плагіна, його закріплене посилання або — для provider — можливість, яку обслуговує прив’язка. Обидва обов’язкові. global і workspace — ті самі перевизначення цілі запису, які так само відхиляються разом. Запит, що не відповідає жодному запису, відхиляється, а не подається як успіх над незміненою конфігурацією, тож викликачеві ніколи не повідомляють, що плагін перестав брати участь, коли це не так, і помилка в написанні ніколи не видаляє інший плагін. Запит не звертається до жодного реєстру: видалення працює лише з текстом конфігурації. Видалення типу cli без зазначення області записує глобальну конфігурацію — див. Доступ до реєстру та запис. Див. Що повідомляє зміна плагіна.
  • aggrega/pluginSync — узгоджує машинні записи сутності Plugin з її модулем: набір функцій хоста, виведений із власних імпортів модуля, і дзеркало команд, прочитане із самозвіту модуля. Жоден із цих записів не створюється вручну, бо обидва є першоджерелом у модулі. Обидва поля обов’язкові й жодне не має типового значення — записи виводяться з модуля, тож узгодження без жодного з них не має з чим узгоджувати, — і обидва є шляхами відносно кореня робочого простору, які відхиляються, якщо вони абсолютні або ведуть за його межі, як написано чи через посилання. Змінюються лише ці два блоки: кожен інший байт переноситься дослівно, включно з коментарями, порожніми рядками та стилем лапок, а файл, який уже фіксує те, що випливає з модуля, залишається побайтово ідентичним і позначається як незмінений. Цей запит записує названий вами файл сутності всередині робочого простору і не звертається до жодного реєстру. Див. Що повідомляє зміна плагіна.
  • aggrega/pluginGenCatalog — згенерувати по одній сутності Plugin для кожного вибраного гостьового модуля, об’єднавши поля контракту, отримані з самозвіту модуля, з написаним вручну накладенням для кожного плагіна. fromEmbedded і plugin — два режими вибору, і застосовується рівно один: усі гостьові модулі, які містить цей бінарний файл, або один модуль за шляхом, який ви вказуєте; запит, що називає обидва або жодного, відхиляється, а не розв’язується. overlay обов’язковий: це каталог накладень у режимі fromEmbedded або один файл накладення в режимі plugin — коли модулів кілька, накладення зіставляється з модулем за ідентичністю, а коли модуль один, зіставляти нічого. outputDir обов’язковий за обох способів доставки, і dryRun від нього не звільняє: пробний запуск змінює те, куди потрапляє вміст, а не те, для якого файлу цей вміст, тож кожен повернутий документ і далі називає шлях, для якого він призначений, а цей шлях складається з цього каталогу. Три шляхи тут оцінюються не однаково, і різниця випливає з того, що генерація робить із кожним. plugin і overlay читаються, і обидва — файли, які вибрали ви: модуль опиняється в тому каталозі, куди його збирає інструментарій, а накладення пишуть поруч із ним, — тож кожен може бути абсолютним і читається там, де він справді лежить. В outputDir записується, тому він відносний щодо кореня робочого простору й відхиляється, якщо абсолютний або веде за його межі — як записано чи через посилання; ще не створений каталог усередині пов’язаного каталогу, що веде назовні, відхиляється так само, як і той каталог. Повторний запуск на незмінних вхідних даних дає побайтово ідентичні сутності. Це записує згенеровані сутності в outputDir усередині робочого простору, якщо тільки dryRun не просить повернути їх як вміст. Див. Що повідомляє зміна плагіна.
  • aggrega/getSchema — JSON Schema для виду сутності чи контракту, прочитана з копії, вкомпільованої в запущений бінарний файл. kind — токен схеми в нижньому регістрі через дефіс (component, aggregate, release, recipe, ir, wasm-provider тощо), і він необов’язковий, бо визначає, яке з двох запитань ви ставите. Якщо вказати вид, відповідь містить kind і schema — схему як документ JSON, а не як рядок, що його містить. Якщо не вказати жодного, відповідь натомість містить kinds і entityKinds: які види можна вказувати, у двох обсягах. kinds — кожен токен, про який можна запитати цей бінарний файл, у тому самому порядку, в якому їх виводить aggrega get-schema --list. entityKinds — вужчий набір видів, документи яких пише автор; кожен запис містить токен kind, який слід надсилати назад, значення documentKind, що йде у власне поле kind: документа, і acceptedBy, що вказує, чи приймають документ цього виду валідація однієї сутності, публікація та інспекція за іменем. Перш ніж будувати засіб вибору з будь-якого з них, див. Які види можна пропонувати автору. Відповідь зі схемою та перелік ніколи не поєднуються, тож з відповіді видно, на яке запитання відповіли. Токен, якому не відповідає жодна схема, відхиляється з повним допустимим набором у повідомленні, тож помилку в написанні можна виправити без другого виклику. Запит нічого не бере з робочого простору, не звертається до жодного реєстру й нічого не записує, тож відповідає навіть у робочому просторі, де нічого немає, — саме це робить його придатним для прив’язки схем у редакторі до того бінарного файлу, яким редактор справді керує, а не до будь-якої копії схем, встановленої деінде.
  • aggrega/scaffoldEntity — початковий документ для виду сутності: рівно ті поля, яких вимагає схема цього виду, із заповненими фіксованими apiVersion і kind та заповнювачем усюди, де потрібне значення. kind обов’язковий і є токеном схеми в нижньому регістрі через дефіс — component, aggregate, release, recipe, manifest, feature тощо; aggrega/getSchema без kind повідомляє, які токени можна надсилати, а токен, якому не відповідає жодна схема, відхиляється з цим набором у повідомленні, тож помилку в написанні можна виправити без другого виклику. Клієнт, що пропонує автору вибрати вид, читає entityKinds цього методу — набір видів, документи яких можна писати. name необов’язковий і заповнює metadata.name для видів, схема яких його вимагає. Відповідь містить kind і skeleton. Див. Що дає відповідь на запит заготовки, бо відповідь — це документ, який слід записати, а не документ, який уже записано. Заготовка виводиться з тієї самої схеми, яку повідомляє aggrega/getSchema, тож обидва відповідають з одного джерела. Якщо замість kind надіслано example, він записує один із готових до запуску прикладів документації в новий каталог робочого простору, як це робить aggrega scaffold --example у терміналі; якщо надіслано лише list: true, він відповідає всіма наявними прикладами й нічого не записує. Обидві форми потребують робочого простору, тож запит будь-якої з них називає його в workspaceRoot, а запит, що не називає жодного, відхиляється. dir називає новий каталог відносно кореня робочого простору, а типово це назва прикладу; абсолютне значення або таке, що розв’язується за межі кореня, — як записано або через посилання, — відхиляється, перш ніж щось буде прочитано, а каталог, що будь-що містить, відхиляється й залишається як є. Відповідь на перелік містить examples, кожен із name, level і summary; відповідь на запис містить example, dir, files — кожен записаний файл, відносно dir, — next, команди, які сторінка прикладу наводить для його збирання, відсутні, якщо вона їх не наводить, і version, версію документації, з якої прочитано приклад. Поля двох форм, надіслані разом, — kind з example, list з example або kind, name з example або list чи dir без example, — відхиляються, перш ніж щось буде прочитано, тими самими словами, якими їх відхиляє інструмент асистента. Запис отримує пакет документації, якщо на машині немає копії, яку допускає власна перевірка підпису робочого простору, і записує всередині робочого простору — див. Звернення до реєстру та запис.
  • aggrega/import — перетворити зовнішній опис джерела на чернетки файлів Aggrega, те саме перетворення, яке aggrega import виконує в терміналі. source обов’язковий і називає файл або каталог для перетворення — абсолютним шляхом або відносно кореня робочого простору: опис, експортований іншим інструментом, лежить там, де ви його зберегли, тож його читають там, де він справді є, а не лише в робочому просторі. Каталог читається так, як його читає aggrega import: ті його файли, які вибирають оголошені шаблони файлів імпортера, за винятком теки результатів збирання робочого простору dist/, і в межах самого каталогу, хоч де він лежить, тож жодне посилання всередині нього не веде назовні. outputDir необов’язковий і називає каталог для чернеток, і на нього ця домовленість не поширюється: у нього записується, тож це шлях усередині робочого простору, а абсолютне значення або таке, що веде за межі кореня — як записано чи через посилання, зокрема ще не створений каталог під ним, — відхиляється. Якщо його пропустити, чернетки потрапляють у корінь робочого простору, куди їх записує aggrega import, коли не вказано призначення, — також і з dryRun. format явно називає формат джерела; якщо його пропустити, формат розпізнається за сигнатурами, які оголошують імпортери — як каталогу робочого простору, так і основні імпортери компілятора, — а джерело, яке не розпізнає жоден або розпізнають імпортери кількох форматів, відхиляється з проханням вказати format, а не вгадується. target називає можливість провайдера, наприклад compose чи helm — слово, до якого прив’язується spec.capability сутності Recipe, — і поруч із чернетками імпортера створює чернетку Manifest, на основі якої збирається створена сутність Release для цього провайдера, точно так, як це робить aggrega import --target: manifest.yaml, що зіставляє кожен тип компонента й кожен тип функції, потрібні чернеткам, — зокрема типи каталожної сутності Aggregate, яку створена сутність Aggregate включає до свого складу, — із сутністю Recipe або рецептом функції цієї можливості, які пропонує для нього каталог робочого простору, за іменем із кваліфікатором можливості без версії: з єдиним наявним або, серед кількох, із названим за типом. spec.manifest сутності Release встановлюється на нього; тип без жодного або з кількома, жоден з яких не названо так, лишається незіставленим із висновком warn, що його називає, а зіставлення, яке імпортер створив сам, зберігається там, де каталог пропонує його для цього типу й можливості, а інакше відкидається з висновком warn. target, до якого не прив’язується жодна сутність Recipe в каталозі, відхиляється ще до запуску імпортера з назвою цього значення та можливостей, до яких прив’язуються Recipes каталогу, і нічого не записується; якщо його пропустити, Manifest не створюється — крім режиму sync, який створює чернетку для цілі, названої в записі попереднього імпорту. Основний імпортер, якого на машині ще немає, завантажується першим імпортом, якому він потрібен, — див. Що повідомляє відповідь на імпорт. dryRun робить усе, що й звичайний запит, крім запису, і повертає чернетки як вміст — для клієнта, що спершу показує їх автору; нічого не створюється, а written порожній. sync оновлює те, що попередній імпорт створив у outputDir, відповідно до джерела, змінюючи лише те, що записав імпорт, як це робить aggrega import --sync; без нього запит, чернетки якого перезаписали б наявну сутність Aggregate, відхиляється. Відповідь містить format, outputDir, written, files, drift, diagnostics, decisions і halted. Див. Що повідомляє відповідь на імпорт, бо джерело, яке імпортер не зміг повністю перетворити, — це успішна відповідь, а не помилка.
  • aggrega/explainError — що компілятор оголошує про умову, яку називає код, і опубліковані записи, що пояснюють, як виправити авторський документ. code обов’язковий і приймає будь-який з ідентифікаторів умови: короткий код, який діагностика несе в shortCode, або описовий — у code. Це розгортання коду, який уже несуть діагностики в цьому протоколі, і це та сама відповідь, яку aggrega explain друкує в терміналі. Відповідь завжди містить умову — shortCode, code і message, — бо це оголошено всередині двійкового файлу й не потребує мережі; entries містить опублікований покроковий опис, а note пояснює, чому його немає, якщо його немає. Це отримує пакет документації, якщо на машині немає копії, яку допускає власна перевірка підпису робочого простору — див. Доступ до реєстру та запис. Див. Розгортання коду, який несла діагностика.
  • aggrega/invalidate — сигнал інвалідації кешу від спостерігача файлів редактора.

Сповіщення:

  • $/cancelRequest — від клієнта до сервера: зупинити поточний запит, надісланий під цим id. Демон скасовує роботу цього запиту; операція помічає скасування на наступній межі кроку, а не миттєво, тож уже розпочата робота ще якусь мить триває. Скасування id, під яким нічого не виконується, — безпечна операція без наслідків.
  • $/progress — від сервера до клієнта: що робить тривала операція під час виконання, на токені, про який запит просив звітувати. Надсилається лише для запиту, що містив такий токен. Див. Спостереження за тривалою операцією.
  • aggrega/shutdown — почати кооперативне завершення: поточні запити завершуються, нові запити відхиляються, потім демон виходить.
  • aggrega/publishDiagnostics — набір діагностик, який надсилає сервер (використовується для попереджень про розбіжність lockfile і для стану під час запуску). Кожен запис містить source, що називає, який із діагностичних шарів демона його підняв: aggrega — для висновку про авторські документи, aggrega-build — для попередження, яке підняла збірка (кожного попередження, яке вона підняла, тобто того самого набору, що друкує aggrega build), і aggrega-lint — для висновку щодо домовленостей публікації, тих самих висновків, що друкує aggrega lint. Поле завжди присутнє в кожному записі, тож клієнт може групувати їх, а не показувати один нерозрізнений список, і йому ніколи не доводиться відрізняти відсутнє джерело від одного з шарів. Фрейм для файлу надсилається лише тоді, коли його набір відрізняється від того, про який цьому клієнту повідомили востаннє, тож запит, що повторно обчислює ті самі висновки, нічого не надсилає; перший фрейм файлу і фрейм, що спорожнює набір файлу, є відмінностями й надсилаються завжди.

Запит до самого процесу на зупинку доходить до демона на тих самих умовах. Переривання з термінала або запит на завершення від супервізора чи середовища виконання контейнерів починає те саме завершення, що й aggrega/shutdown: поточні запити завершуються, нові запити відхиляються, потім демон виходить. Другий запит негайно завершує процес. Клієнт, який запускає демон, може зупинити його будь-яким із цих способів, і той, хто зупиняє його через протокол, і той, хто надсилає йому сигнал, отримують однакове завершення.

Перевірка в реальному часі

На кожен запит aggrega/validate демон перевіряє буфер редактора на відповідність схемі документа й повертає діагностику, спрямовану на проблемний ключ, — той самий вердикт, який дала б збірка, але для незбереженого вмісту. Запит, що не надсилає content, стосується файлу в тому вигляді, у якому він є на диску; порожній надісланий content — це порожній буфер, а не запит щодо файлу. Файл, надісланий без вмісту, має належати робочому простору й бути доступним для читання — файл поза робочим простором, файл, до якого ведуть через посилання за його межі, або файл, якого немає, відхиляється з кодом недійсних параметрів. Сутності каталогу, Aggregates, Manifests і Releases розпізнаються за їхніми apiVersion і kind. Два документи, що не мають такого заголовка, — конфігурація робочого простору .aggrega-config.yaml і lockfile сутності Release, названої в запиті, — натомість розпізнаються за назвою файлу, тож сміттєвий або неправильно сформований ключ у будь-якому з них так само підкреслюється в реальному часі. Файли, що не є документами Aggrega, — шаблони чартів Helm, файли Compose, маніфести Kubernetes і файли .lock інших екосистем, як-от Cargo.lock чи flake.lock, — не отримують діагностики; демон ніколи не звітує про сторонні файли.

Ще не заповнений заповнювач названо біля його ключа разом із тим, що він приймає. Сутність каталогу того виду, який aggrega validate перевіряє як окрему сутність, також читається на предмет обов’язкових значень, залишених порожнім рядком, за тим самим прочитанням, яке застосовує ця команда, тож демон називає кожен заповнювач, який команда називає для тих самих байтів. Кожен заповнювач — це один запис: його message повідомляє, що ключ є ще не заповненим заповнювачем, його suggest — що приймає значення, а його keyPath містить шлях ключа через крапку. Запис заступає власну знахідку схеми для цього порожнього значення, а кожна інша знахідка в документі звітується так, як її звітує перевірка схеми. Заповнювач, який схема допускає порожнім, також називається, хоча перевірка схеми нічого про нього не повідомляє, — вам трапляться саме capability і implements чернетки сутності Recipe або FeatureRecipe. Якщо перевірка схеми також відхиляє документ, кожен запис містить код цієї перевірки, E0215, а якщо вона документ приймає, записи не містять коду: ті самі ідентифікатори, що й у звіті команди для цих байтів. Запис малюється біля ключа з порожнім значенням, на рядку, де його називає команда, — навіть для ключа, власна назва якого містить крапку, як-от мітка component.aggrega.ai/type, де знахідку перевірки схеми щодо цього ключа малюють біля ключа, що його охоплює, — а keyPath називає ключ повністю. Це діє незалежно від того, чи називає запит сутність Release, бо на це питання документ відповідає сам, а документ, що ще не має значення, ще не є тим, щодо якого запитують про домовленості публікації: цей шар для нього очищено, так само як для документа, форму якого відхиляє схема.

Кожен запит називає сутність Release, якої він стосується, а демон власної не зберігає. Семантичні перевірки розв’язують замикання залежностей цієї сутності Release і читають її lockfile для закріплених версій — або, для сутності каталогу, читають каталоги, з якими збирається ця сутність Release, як описано в наступному абзаці, — тож два запити, що називають дві сутності Releases, отримують відповідь про ту сутність Release, яку назвав кожен із них. Між ними нічого не переноситься: немає вибраної сутності Release, яку треба змінювати, і зміна сутності Release, щодо якої ви перевіряєте, — це інше значення в наступному запиті, а не щось, що демону треба наказувати забути.

Сутність каталогу, названа разом із сутністю Release, перевіряється як окрема сутність у термінах цієї сутності Release. file, що містить Component, Feature, Recipe, FeatureRecipe або Plugin, надісланий із release, отримує перевірку, яку виконує aggrega validate <path> --release <release>, над незбереженим буфером редактора: його посилання — сутність Component, яку реалізує Recipe, бібліотека, на яку посилається стовп, — розв’язуються через каталоги, які конфігурація робочого простору надає цій сутності Release, тож один файл може бути чистим у термінах сутності Release, що з ним збирається, і не пройти перевірку в термінах сутності Release, каталоги якої не містять того, на що він посилається. Це той самий вердикт, який командний рядок і інструмент validate у aggrega mcp дають для тієї самої сутності поруч із тією самою сутністю Release, і, як і вони, ця перевірка не обходить замикання й не читає lockfile. Блокувальна знахідка — це один запис помилки власними словами перевірки з її кодами, намальований біля ключа, який вона називає в сутності, а якщо не називає жодного — біля ключа kind: сутності, як описано в Що містить запис діагностики, — хіба що збірка вже звітує про цю ваду у файлі, і тоді запис збірки є єдиним звітом; попередження, яке перевірка видає під час читання каталогу, — це запис-попередження перед ним; чиста перевірка над каталогами, що всі наявні, не дає жодного запису. Невдале твердження — те, що викликає fail, у сутності Recipe чи в сутності Component, яку вона реалізує, — тут не блокувальна знахідка, а запис-попередження словами перевірки з її кодами, завершений реченням A Release must satisfy this assertion before a build of it can pass. і намальований там, де була б блокувальна знахідка: твердження сутності Recipe — біля власного ключа цього твердження в assertions, твердження сутності Component — біля ключа kind: сутності Recipe. Як і блокувальна знахідка, воно поступається записом збірки, що звітує про ту саму ваду у файлі. Перевірка будує сутність навколо заповнювачів і типових значень схеми, а не значень, які задає сутність Release, тож вона не може відрізнити твердження, що чекає на сутність Release, від зламаного, і залишає вердикт збірці, яка звітує про те саме твердження як про помилку (невдале твердження — це попередження). Каталог, який конфігурація робочого простору вказує для сутності Release і який не є каталогом — скажімо, там нічого не існує, — зупиняє перевірку: файл містить один запис помилки замість вердикту перевірки — відмову, яку кожна команда дає цьому каталогу, із назвою запису, файлу конфігурації та рядка, що його вказує, і налаштування (Звідки читаються локальні сутності). release, що не називає жодного файлу або називає каталог, отримує відповідь у файлі реченням, з яким його відхиляє командний рядок, а не перевіряється в термінах робочого простору. Те, чого збірка однієї сутності не може замінити, оцінюється так, як його оцінює командний рядок, а те, що командний рядок відкладає чи не перевіряє, тут не дає жодного запису, — див. що не перевіряє коректність окремої сутності, а для сутності Recipe, шаблон якої читає значення, що його постачає лише ребро топології чи приєднані облікові дані, — коректність окремої сутності. Власна сутність Aggregate цієї сутності Release, Manifest, Release і бібліотека не перевіряються поодинці, бо перевірка окремої сутності не приймає цих видів; для них залишаються перевірки замикання, описані вище. Буфер із вмістом Workload читається як YAML, що не є документом Aggrega, бо цей вміст пишеться в полі workload: сутності Recipe або FeatureRecipe і перевіряється там, де він розташований; командний рядок та інструмент validate, отримавши файл Workload за шляхом, перевіряють його форму окремо.

Вказувати сутність Release необов’язково, і відповідь повідомляє, про що з двох ви запитали. Вкажіть її — і отримаєте все описане вище. Не вкажете — і отримаєте перевірки, на які документ відповідає сам: чи він розбирається, чи допустима його власна форма і, для сутності каталогу того типу, що перевіряється як окрема сутність, які заповнювачі він ще має заповнити, — без розв’язання сутності Release, без обходу замикання і без читання lockfile; тоді відповідь містить checked: "document". Якщо сутність Release вказано, цього ключа немає, бо така відповідь — повний вердикт методу і не потребує уточнень.

Читайте ключ, а не робіть висновків з діагностики, бо дві відповіді можуть виглядати однаково. Коректно сформований документ, перевірений без сутності Release, повертає порожній список діагностики — саме те, що повертає й чистий повний вердикт, тож checked — єдине, що відрізняє «нічого не так» від «нічого, що потребує сутності Release, не перевірялося». З того самого правила випливає наслідок: lockfile розпізнається за його відповідністю сутності Release, вказаній у запиті, тож запит без неї не розпізнає жодного lockfile і нічого про нього не повідомляє.

На запит щодо робочого простору без жодної сутності Release надається відповідь, а не відмова, і саме це зберігає решту можливостей демона там придатними. Валідація заповнює кеш розбору, який читають усі інші файлові операції, тож репозиторій лише з каталогом, заготовка з однією сутністю Aggregate чи чернетковий каталог усе одно отримують підказки при наведенні, автодоповнення, перехід до визначення, посилання, реалізації та кешовану діагностику. Відмова натомість позбавила б усього цього саме в тих робочих просторах, де клієнт не має сутності Release, яку можна вказати.

Що містить запис діагностики

Кожен запис указує свою позицію через line і column, обидва з відліком від 1 у кодуванні позицій, узгодженому під час рукостискання, і додає end_line та end_column, коли охоплює цілу лексему. message — текст, який клієнт показує користувачеві, severity класифікує його, а source називає, який із шарів демона його породив, як описано вище.

Шари відповідають на різні запитання про один файл, тож записи з кожного можуть стояти на одному рядку, і жоден не дублює іншого: один каже, що розгортання некоректне, інший — що сутність не придатна до публікації. Клієнт, який показав би їх одним списком, повідомив би про одну проблему двічі, і саме читання source їх розрізняє.

Де розташований запис, залежить від того, про що він, а не від того, який шар його породив. Знахідка щодо написаного автором розташовується на ключі, під яким це написано, тож редактор показує її там, де потрібне редагування. Знахідка щодо форми розгорнутої топології називає компонент і ключ доставки, а не рядок — це координати в розгорнутій топології, а не в документі, — тож вона показується на ключі kind: документа, а свої координати називає в повідомленні. Обидва типи потрапляють до шару aggrega-build, бо збірка породжує обидва. Відмова, яку збірка породила під час рендерингу, теж потрапляє до цього шару — на документ, на який вказує сама відмова: Workload, що не проходить своїх перевірок, — на ключ workload її Recipe, невдале твердження Recipe — на власний ключ цього твердження, запис, який відхиляє композиція графа, — на ключ, під яким його записала сутність Release чи Aggregate, а кожна знахідка відмови, що об’єднує кілька, — на власний документ і ключ; а якщо вона не вказує на жоден документ — на ключ kind: сутності Aggregate; це описано в розділі Відмова, породжена під час рендерингу. Тож клієнт розміщує кожен запис за його власними line і column і ніколи не виводить позицію з шару.

Знахідка, що не називає жодного ключа, наявного в документі, показується на ключі, який називає документ. Знахідка, яку власні перевірки документа породжують щодо його змісту, знахідка перевірки окремої сутності, а також попередження чи відмова, породжені збіркою, показуються кожна на ключі, який вони називають; якщо вони не називають жодного або називають ключ, якого в документі немає, їх показано на ключі kind: документа, або на його metadata.name, якщо kind: не оголошено, і на початку файлу лише тоді, коли документ не оголошує жодного з них або не розбирається. Документ часто починається з коментаря — кожен файл каталогу містить заголовок ліцензії, — і запис на першому рядку стояв би на цьому коментарі й читався б як помилка в ньому, тоді як власна ідентичність документа — це рядок, написаний автором. Запис про щось інше, ніж зміст документа, розміщується на початку файлу: запис Dependencies: про залежності сутності Release, етап, що зупинився, нічого не назвавши в документі, розбіжний lockfile, посилання, яке рендеринг мусив відхилити, сутність Release, що не завантажилася, — так само й запис aggrega-lint, правило якого не обчислило рядка. Там, де позицію вказують, а не показують, знахідка без ключа так і не має його: відповідь-помилка відмови, що не називає ключа, містить у своєму data лише документ.

На якому документі публікується запис, випливає з того самого правила. Валідація із вказаною сутністю Release відповідає про сутність Aggregate цієї Release, саму Release, документ кожного модуля, який імпортує Aggregate, і сутність Manifest, яку називає Release. Знахідка, розташована в сутності Release, — відмова щодо запису, який Release робить на одному зі з’єднань компонента, щодо розміру, який вона дає цьому з’єднанню, щодо вкладення, яке вона там заповнює чи задає розмір, щодо з’єднання, яке вона прокладає, щодо сутності Feature, яку лише Release приєднує до компонента чи до межі, або щодо infra, яке вона дає вкладенню, — публікується під час валідації документа Release, на ключі в Release, що її записав, і зовсім не публікується на Aggregate. Знахідка, розташована у власному документі модуля, — відмова щодо того, що оголошує один із компонентів модуля, щодо сокета, який прокладають його вкладення, щодо його значень або значень на його власних з’єднаннях, — публікується під час валідації документа цього модуля, на ключі там, що її записав, і зовсім не публікується на Aggregate. Знахідка про таблицю відображень сутності Manifest — запис, що відображає тип на Recipe чи FeatureRecipe, які його не реалізують, запис, закріплення версії в якому не вдається розібрати, або відображений тип, ланцюжок extends якого неможливо простежити, — публікується під час валідації цього Manifest, на ключі запису відображення, якого вона стосується, і зовсім не публікується на Aggregate; якщо відкритий текст Manifest не містить цього запису — запису, успадкованого через власний extends, або запису, видаленого незбереженим редагуванням, — знахідка публікується в першому рядку Manifest. Усі інші знахідки валідації цієї Release публікуються на Aggregate, зокрема знахідки рівня залежностей, що не називають жодного документа вашого робочого простору: відкликане посилання чи плагін, сутність Component чи Feature каталогу, ланцюжок extends якої не розв’язується або схема якої некоректна, плагін-шлюз, якому не відповідає запис довіри, екземпляр компонента, який не розв’язується жодним відображенням, сутність Recipe чи FeatureRecipe, провайдер якої не може рендерити оголошений нею тип вхідних даних, а також рекомендації щодо перекриття опор схеми та звуження під час розширення. Тож знахідка про написане оператором з’являється, поки відкрито Release, знахідка про те, що оголошує модуль, — поки відкрито цей модуль, а знахідка про відображення — поки відкрито Manifest, хоч би який етап збірки її породив; редактор, що перевіряє кожен відкритий документ щодо Release, показує там кожну з них. Сутність Release, залежності якої взагалі неможливо розв’язати, не породжує жодної з цих знахідок, а невдача їх розв’язання — це один запис на початку власного документа Release і кожного іншого документа, перевіреного щодо неї, який демон розпізнає, як описано в розділі Валідація в реальному часі, і не перевіряє як окрему сутність — її Aggregate, її Manifest, бібліотеки, іншої Release, конфігурації робочого простору, — з префіксом Dependencies: і з власним поясненням розв’язання, що його зупинило. На власному документі Release запис — це лише це пояснення. На кожному іншому документі він спершу каже, що документ перевіряється щодо цієї Release, і називає її так, як її називає запит, — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved:, а далі пояснення, — бо ніщо в цьому документі не каже, щодо якої Release його перевірено: редактор, що перевіряє кожен відкритий документ щодо однієї вибраної Release, ставить запис на документи, які не мають до неї стосунку, і саме назва показує, що причина — у виборі. Файл, який демон не розпізнає, такого запису не містить, хоч би яку Release вказано з ним.

Відповідь містить кожен шар, наявний для файлу, хоч би як далеко просунулася валідація. Відповідь aggrega/validate — це весь поточний стан файлу: що знайшла ця валідація, записи aggrega-build, які збірка, попередній перегляд чи запит графа опублікували на файлі, і його знахідки щодо домовленостей публікації, кожне під своїм source. Валідація, що зупиняється на буфері, — той, що не розбирається, або документ, оболонку якого відхиляє схема, — відповідає так само: повідомляє власну знахідку й залишає всі записи збірки на файлі, бо нічого не дізналася про збірку. Тож клієнт може замінити те, що зберігає для файлу, шар за шаром, з будь-якої відповіді.

Одна помилка повідомляється один раз. Власна валідація документа і збірка можуть знайти в ньому ту саму помилку: перевірка окремої сутності рендерить сутність Recipe, яку рендерить і збірка, валідація компонує граф, який компонує збірка, а сутність Release, залежності якої не розв’язуються, не проходить обох. Поки збірка повідомляє про таку помилку в документі, валідація цього документа не повідомляє про неї вдруге: запис aggrega, що називає ту саму умову — той самий code, — що й відмова збірки в тому самому документі, розміщений на тому самому проміжку або на жодному власному ключі — там, де розміщується запис, що не називає ключа, або на початку файлу, — вилучається з кожної відповіді та кожної публікації для цього документа, і звіт збірки залишається єдиним. Звіт збірки — це запис відмови на шарі aggrega-build; або, для aggrega/build, aggrega/buildPreview чи aggrega/irGraph, відхилених із 1004, бо залежність не розв’язується, — сама ця відповідь (яку ніщо не публікує) на документі, який називає її data.file, інакше її data.lockfile, інакше сутність Release, названа в запиті; при цьому враховується остання така відповідь для сутності Release. Валідація зберігає те, що знайшла: щойно жодна збірка більше не повідомляє про помилку — наступний запуск публікує шар без неї, наступна відповідь збірки, попереднього перегляду чи графа для цієї сутності Release є будь-якою іншою, або підключається клієнт, якому не надходило такої відповіді 1004, — власний запис документа знову повідомляється, а там, де жодна збірка не запускалася, нічого не вилучається. Запис aggrega, розміщений на ключі, на якому немає жодної відмови збірки, залишається, навіть коли називає ту саму умову, бо це може бути друга помилка такого типу, про яку збірка не повідомила.

code — це стабільний, придатний для машинного зіставлення код того, про що повідомляє запис, тож клієнт може розгалужуватися за ним, не зіставляючи текст повідомлення. Один ключ містить код, хоч би хто його призначив, а source вказує, який саме код ви маєте, бо шари називають речі з різних словників.

  • У записі aggrega — знахідці щодо написаних документів — код є рядком, під яким зареєстровано умову, записаним як пакет, що її оголошує, а потім правило в kebab-case. Це те саме значення, яке споживач на Go читає за допомогою CodeOf; його форму та поверхню зіставлення описано в довіднику сентинелів помилок.
  • У записі aggrega-build — попередженні, яке згенерувала збірка, — код є тим, що призначило місце виникнення, і цей шар містить попередження з двох різних словників, бо збірка генерує попередження про два різні типи речей. Попередження про форму розгорнутої топології містить код класу, як-от unsupported-field, призначений там, де його згенеровано, — чи то плагін рендерингу, чи сам рендер; код класу називає клас попереджень, а не зареєстровану умову, тож він не має рядка в довіднику сентинелів, а довідник попереджень описує клас unsupported-field і прапорець, що його вимикає. Попередження про написані документи — ім’я, що відрізняється на одну правку від оголошеного, параметр, який ніщо не читає, — містить рядок, під яким зареєстровано його умову, у тій самій формі, що й запис aggrega, і з рядком у довіднику сентинелів. В обох випадках код називає, чим є знахідка, а не хто її знайшов, тож один клас доходить до вас під одним кодом, хоч би скільки місць його генерували, і саме читання коду, а не шару, вказує, який із двох ви маєте. Відмова, на якій збірка зупинилася під час рендерингу, — єдиний запис тут, що не є попередженням, і вона так само містить рядок, під яким зареєстровано її умову.
  • У записі aggrega-lint — знахідці щодо домовленостей публікації — код є ідентичністю знахідки: ідентичністю правила, яке її породило, або, для знахідки, що не називає жодного правила (такі може повідомляти ваш власний лінтер під власним кодом), — цим кодом. Це ідентифікатор, який aggrega lint виводить у рядку знахідки після короткого коду, якщо він є, і значення, яке aggrega lint --output json містить для тієї самої знахідки як ruleId або як code для знахідки, що не називає жодного правила. Одна знахідка зберігає одну ідентичність на всіх поверхнях, тож клієнт, який групує чи приглушує правило в редакторі, групує й приглушує те саме правило в терміналі. Кожне правило з набору правил лінтера публікації, який оголошує Aggrega, зареєстровано як умову під цією ідентичністю, тож його наведено в таблиці всіх умов під коротким кодом, який aggrega lint виводить на початку рядка тієї самої знахідки і який aggrega lint --output json містить у ній як shortCode. Правило вашого власного лінтера, яке Aggrega не оголошує, не називає жодної зареєстрованої умови, як і знахідка, що не називає жодного правила, навіть якщо її власний код збігається з ідентичністю правила, яке оголошує Aggrega, — тож жодного з них там не наведено. Правила описано в розділі про aggrega lint у довіднику.

Хоч би який був шар, ключ відповідає на одне питання — що це, у термінах, які машина може зіставити, — тож розширення редактора, яке підсвічує, групує чи пригнічує один клас знахідок, орієнтується на код і продовжує працювати, коли змінюється формулювання повідомлення.

Зверніть увагу, який об’єкт що містить: у записі діагностики це рядок, на відміну від числового code в оболонці помилки JSON-RPC, описаній у розділі Коди помилок нижче. Відповідь містить одне або інше, але ніколи обидва в одному місці.

Ключ пропускається, якщо ніщо з того, що створило запис, не призначило коду, і такий випадок є в кожного типу. Буфер, який не прочитає жоден парсер YAML, повідомляє власний текст парсера без коду, бо за ним не стоїть жодна власна умова Aggrega; етап, що повідомляє про збій, не називаючи умови, так само не має коду; а попередження, джерело якого не призначило коду, надходить без нього. Тож вважайте code необов’язковим, так само як end_line і end_column, і розгалужуйтеся за ним лише тоді, коли він присутній. Код — це те, що повідомляє діагностика, і ніколи не те, що її обирає: жоден запит не приймає коду, а записавши його назад у власний код, ви отримаєте рядок, а не спосіб зіставлення.

Ідентифікатор, з яким звіряється програма, і той, який цитує людина

Умова має два ідентифікатори, і вони призначені для двох різних читачів. code — це той, що описаний вище: кваліфікований і з дефісами, тож програма, яка розгалужується за ним, читається відповідно до свого змісту. shortCode — це літера E і чотири цифри, як-от E0164, і саме його людина може прочитати вголос, ввести в поле пошуку або вставити в issue. Обидва називають ту саму умову, і жоден не є скороченням іншого.

Який із них використовувати, залежить від того, хто читає. Звіряйтеся з code у своєму розширенні; показуйте автору shortCode. Розширення, яке показувало б лише code, залишає читача з ідентифікатором, призначеним для програми, а те, що звірялося б із shortCode, звіряється з номером, який нічого не говорить про умову. Саме через такий поділ передаються обидва, а не один.

codeDescription — це місце, де опубліковано умову; він передається як { "href": … }, тобто як власна структура протоколу для посилання, яке можна відкрити, щоб дізнатися більше про діагностику. Редактор, що підтримує протокол, перетворює його на елемент «докладніше», не знаючи нічого про Aggrega, і жодному клієнту не потрібна копія пояснень. Адреса вказує на опублікований список усіх умов, де запис для shortCode називає умову й веде далі до покрокового опису виправлення в авторському документі.

Самого пояснювального тексту в записі немає, і це навмисно. Діагностика видається при кожному редагуванні, тож пояснення, що передавалося б із кожною, повторно публікувало б ті самі абзаци при кожному натисканні клавіші для читача, який зазвичай уже їх прочитав. Клієнт, якому потрібен текст, запитує його один раз за допомогою aggrega/explainError нижче; клієнту, який може перейти за посиланням, не потрібне ні те, ні інше.

Обидва ключі присутні саме тоді, коли запис називає зареєстровану умову, і в іншому разі відсутні разом. Їх визначає те, що стоїть за записом, а не те, який шар його опублікував, тож читайте ключі, а не шар:

  • Запис, що називає зареєстровану умову, містить усі три. shortCode розв’язується, а посилання вказує на список, у якому він розв’язується.
  • Запис, код якого називає клас, містить лише code. Клас попередження рендерингу та ідентичність знахідки щодо домовленостей від вашого власного лінтера — правила, яке Aggrega не оголошує, або коду, який містить знахідка, що не називає жодного правила, — є справжніми ідентифікаторами, за якими можна групувати й приглушувати, і жоден із них не є зареєстрованою умовою, тож немає номера, який можна процитувати, і за адресою немає нічого, що їх описує. Посилання, надіслане попри це, відкривало б сторінку не про проблему читача, тому жодного не надсилається. Це звичайна форма на шарі aggrega-build, хоча попередження збірки, яке таки називає зареєстровану умову, містить усі три, як і будь-яке інше. На шарі aggrega-lint звичайною формою є повний набір: правило з набору правил лінтера публікації, який оголошує Aggrega, є зареєстрованою умовою, тож його знахідка містить той самий shortCode, який aggrega lint виводить на початку рядка знахідки, і посилання поруч із ним.
  • Запис, що нічого не називає, не містить жодного ідентифікатора.

Отже, три випадки можна розрізнити лише за ключами: відсутність code означає, що нічого назвати, code без shortCode поруч означає ідентифікатор, який далі не розв’язується, а повний набір означає ідентифікатор, про який є де прочитати. Вважайте два нові ключі необов’язковими так само, як code, і пропонуйте читачеві щось відкрити лише там, де надійшов codeDescription.

Розгортання коду, який містила діагностика

aggrega/explainError перетворює будь-який з ідентифікаторів умови на те, що компілятор оголошує про неї, і на опубліковані записи, які пояснюють виправлення в авторському документі. Це те саме розгортання, яке aggrega explain виконує в терміналі, а інструмент explain-error — для асистента, і всі три відповідають з одного місця, тож код, розгорнутий тут, і той самий код, розгорнутий там, — це одна відповідь, а не три, які випадково збігаються.

code обов’язковий і приймає будь-який ідентифікатор — shortCode, який містила діагностика, або code поруч із ним, — бо клієнт, що має один із них, не може отримати інший, не запитавши. Порожнє значення відхиляється із зазначенням, що слід надіслати.

Відповідь завжди містить shortCode, code і message: два ідентифікатори умови й речення, яким починається кожна діагностика, що її називає. Їх оголошено всередині бінарного файлу, тож вони надходять без мережі й без кешу, і саме це дає змогу відповісти навіть робочому простору, який не має документації. reference — це та сама адреса, яку містить codeDescription діагностики, для клієнта, який радше відправить свого читача до документації, ніж показуватиме текст.

entries містить опублікований покроковий опис: кожен запис як heading, яким він починається, і body під ним, у тому порядку, в якому сама документація пов’язує їх з умовою. Його пропущено, якщо покроковий опис не вдалося додати, і тоді note пояснює чому: опублікована сторінка ще не документує жодного запису для цієї умови або цей робочий простір не може прочитати документацію — на машині немає копії або є лише така, яку відхиляє перевірка підпису робочого простору. У будь-якому разі умова над ним залишається чинною — відповідь не є збоєм, і клієнт показує те, що надійшло, і примітку поруч. entries і note ніколи не надходять разом.

Код, який ніщо не розв’язує, відхиляється, а не отримує відповідь з умовою, усі поля якої порожні, і кожна відмова вказує, який це випадок: код, під яким не зареєстровано жодної умови, номер, який колись називав умову й ніколи не називатиме іншої, або код, який цей бінарний файл не оголошує, коли опублікований список узагалі не вдалося прочитати, — останній випадок залишає відкритими обидва способи виправлення, оскільки список, опублікований для іншої версії, може називати умову, яку цей бінарний файл не оголошує.

Документація читається з пакета, кешованого для робочого простору, який називає запит, і отримується під час першого використання, якщо її немає, — це єдине, для чого цей запит звертається до реєстру; див. Звернення до реєстру й запис. У робочий простір нічого не записується. Жодна перевірка не запускає цього: розгортання відбувається тому, що його запросив запит, тож до реєстру ніколи не звертаються під час перевірки чи огляду документа.

Публікаційні домовленості: на запит і під час кожного редагування

Демон відповідає на два різні запитання про сутність каталогу, і це ті самі запитання, на які в терміналі відповідають aggrega validate і aggrega lint: чи розгортання коректне і чи сутність придатна до публікації за домовленостями каталогу. Валідація завжди відповідає на перше. На друге вона відповідає лише тоді, коли ви про це просите.

aggrega/lint просить про це прямо. Надішліть entity для однієї сутності каталогу, release для кожної сутності, якої досягає замикання залежностей цієї сутності Release, або жодного з них, щоб перевірити кожну сутність у налаштованих каталогах-директоріях, — це три області дії, які має команда. Надсилання і entity, і release називає два різні предмети й відхиляється. Відповідь містить checked — кількість документів сутностей, охоплених запуском, і files — знахідки, згруповані за документом, якого кожна стосується, і впорядковані за шляхом; записи кожного файлу мають форму діагностики, описану вище. halted вказує, чи власний вердикт запуску відмовляє в публікації.

Якщо не надіслати жодного, перевіряється весь каталог — так, як це робить aggrega lint без аргументу. Робочий простір, конфігурація якого не задає власних директорій каталогу для Release, перевіряється один раз, за його власними директоріями, і відповідь є такою, як описано вище. Робочий простір, що називає сутності Releases у workspace.releases, перевіряється один раз для кожної сутності Release у ньому, за директоріями, які читає ця сутність Release, і ніколи за всіма ними разом, — тож варіанти каталогу, що зберігаються поруч, по одному на Release, кожен перевіряється в термінах тієї сутності Release, яка їх читає. Тоді відповідь також містить passes, по одному запису на прохід: releases — сутності Releases, для яких його виконано, кожна відносно кореня робочого простору, причому сутності Releases, що читають ті самі директорії, ділять один запис; catalogDirs — директорії, які він прочитав, записані так, як files записує шлях, і порожні для сутності Release, що не читає жодної, про що повідомляється, а не спричиняє збій інших; а також власні лічильники та files цього проходу, які й вказують, для якої сутності Release знайдено знахідку. checked, лічильники та files навколо них охоплюють усі проходи разом, тож клієнт, який не читає passes, однаково читає весь запуск. Запуск, у якому жоден прохід не має директорії для читання, відхиляється, а не отримує відповідь як чистий каталог.

Задайте prePublish разом з entity, щоб порівняти цю сутність із її попередньо опублікованою версією і класифікувати запропоноване підвищення версії відносно неї. Це єдиний режим тут, який звертається до реєстру, і він виконується, бо запит його назвав: операцію, що звертається назовні, допускає те, що викликач про неї попросив. Він має сенс лише з entity, тому prePublish без сутності відхиляється.

aggrega/lint нічого не публікує в сесію. Він відповідає про предмет, який йому передали, а запис його знахідок у список проблем редактора замінив би те, що валідація опублікувала для файлів, яких запит ніколи не охоплював. За жодного режиму нічого не записується на диск.

serve.lint_on_validate виконує ті самі правила під час кожної валідації, і він вимкнений, доки ви його не ввімкнете. Увімкніть його в .aggrega-config.yaml у тому робочому просторі, щодо сутностей якого ви хочете отримувати поради:

serve:
lint_on_validate: true

Прапорця для нього немає, бо запитання, на яке він відповідає, стосується власного вмісту робочого простору, і це запитання має той, хто створює робочий простір, а не той, хто запустив демон. Коли його ввімкнено, валідація сутності каталогу також публікує знахідки щодо домовленостей під джерелом aggrega-lint; коли вимкнено — за замовчуванням — валідація повідомляє лише шари коректності, і жодна знахідка щодо домовленостей до вас не доходить. Сесія редактора нічого не каже про те, чи придатна сутність до публікації, доки ви не попросите цей шар.

На цьому шарі три речі діють незалежно від значення ключа. Виконується лише режим, що читає локальний вміст, тож жоден реєстр не опитується, нічого не завантажується й нічого не записується; порівняння перед публікацією досягається надсиланням aggrega/lint з prePublish, а не валідацією, бо перевірка, що виконується під час кожного редагування, — саме те місце, де до реєстру звертатися не можна. Правила обчислюються щодо буфера, який передав запит, а не файлу на диску, тож ім’я, яке ви виправили, перестає повідомлятися ще до збереження. А знахідки є рекомендаційними — документ, що їх спричиняє, однаково проходить валідацію, а його сутність Release однаково розв’язується та рендериться, — тож це додає шар і ніколи не відмову.

Ключ керує цим шаром і нічим іншим. aggrega/lint відповідає на будь-який запит за будь-якого значення, бо викликач, що його надсилає, попросив перевірку на ім’я.

Перевіряються лише ті види, що публікуються в каталог, бо саме про них домовленості. Документи, які не є вмістом каталогу, — серед них Aggregate і Release, — пропускаються, як і YAML, що взагалі не є документом Aggrega. Саме це дає сесії мовчати про документи, з якими автор проводить більшість часу.

Як записується повідомлений шлях

Коли відповідь називає документ, який демон знайшов для вас, одне правило визначає, як записано цей шлях: відносно кореня робочого простору, якщо документ усередині нього, і абсолютним шляхом, якщо ні. Це стосується file в ідентичності сутності, file у визначенні сутності та file, за яким згруповано кожну групу у відповіді lint. Обидва записи — шляхи, які можна відкрити: перший відносно названого вами кореня, другий як є, — і жоден ніколи не залишається порожнім через те, де розташований документ.

Друга половина правила потрібна для налаштованого каталогу. Робочий простір може вказувати на каталоги будь-де на машині, і документ у такому каталозі так само реальний, як документ під коренем. Його називає абсолютний шлях, і це той самий запис, який aggrega lint і діагностика зупинки виводять для цього файлу в терміналі, — тож один файл має одне ім’я, хоч би до якої поверхні ви зверталися. Чого ви не отримаєте, то це шляху, що піднімається вище кореня: він називав би різні файли залежно від того, звідки його читають.

Який запис ви отримали, видно зі значення: усе, що ваша платформа читає як абсолютний шлях, — друга форма, а все інше — відносно кореня робочого простору. Перевіряти це, щоб відкрити файл, не потрібно — приєднання відносного шляху до кореня і відкриття абсолютного як є працюють обидва, — але клієнт, що групує за документами робочого простору, може розрізнити їх, не запитуючи.

Чого це правило не стосується. Шлях, який ви надсилаєте, регулюється власним контрактом відповідного запиту, описаним разом із запитом вище, і зазвичай суворішим: місце призначення відхиляється, якщо воно не відносне щодо кореня робочого простору або не розв’язується всередині нього, включно з посиланнями. Сповіщення aggrega/publishDiagnostics завжди передає свій file абсолютним, і всередині кореня, і поза ним, бо це значення — ідентифікатор, який ви зіставляєте з власними відкритими документами, а не координата в робочому просторі: ваш редактор розв’язує його як шлях файлової системи. aggrega/releaseCandidates і aggrega/activeRelease називають кожну сутність Release і кожен lock-файл абсолютним шляхом, як зазначено в їхніх описах вище. А aggrega/irGraph передає скомпільований граф так, як його записав компілятор, — приховуючи лише значення, які автор оголосив чутливими, — тож будь-який шлях усередині нього є тим, який записав компілятор, у формі, яку фіксує власний контракт графа, а не таким, який склав для вас цей протокол.

Які записи приймає параметр, що ви надсилаєте

Які записи приймає параметр, визначає те, що називає шлях, а не те, який метод його передає. Власний опис кожного запиту вище містить контракт для його параметрів; далі йдеться про відмінність між ними і про те, чому це відмінність, а не непослідовність, яку доводиться запам’ятовувати для кожного методу.

Параметр, що називає документ, який у вас уже є, можна записати трьома способами: відносно кореня робочого простору, абсолютно або як адресу file://, яку клієнт мовного сервера надсилає для відкритого документа. Це file або uri у aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint і aggrega/connectionAtPosition. Усі три називають один документ і отримують однакову відповідь, бо кожен зводиться до одного канонічного запису на межі запиту, перш ніж його щось прочитає, — тож документ, перевірений за шляхом, знаходиться за адресою, і навпаки, а вибір запису нічого не змінює у відповіді. Адреса читається як шлях, який вона називає, з декодованими percent-escape-послідовностями, коли її authority порожній або localhost; адреса, що називає іншу машину, читається як мережевий ресурс цієї машини в системі, яка так відкриває там документ, а деінде не називає нічого, що демон може відкрити. Адреса, яка також містить query, fragment, облікові дані або порт, теж не називає нічого, що демон може відкрити. Значення, яке не починається з file://, незалежно від регістру літер, ніколи не читається як адреса, а відмова «файл не перевірено» називає надіслане вами значення, хоч би яким був запис. З них aggrega/insertionPoint і aggrega/connectionAtPosition — два запити, що читають документ із диска, коли у вас немає його копії, і відповідають лише для документа всередині робочого простору: документ поза коренем — як записано або через посилання, що веде назовні, до файлу чи до каталогу на шляху, — відхиляється за будь-якого з трьох записів, а документ усередині кореня отримує відповідь за всіма трьома. Решта вісім нічого не читають із диска за шляхом, який називають, — aggrega/validate бере байти документа з content, а інші відповідають на основі перевіреного, — тож вони відповідають для документа, хоч би де він у вас був, у робочому просторі чи ні, і жодне назване ними посилання не відстежується для читання файлу. Параметр, що називає документ, який ви вибрали поза робочим простором, — той самий випадок із тієї самої причини: source запиту aggrega/import читається там, де він насправді є, як зазначено в його описі. Обидва — винятки з межі робочого простору за класом: документ, який клієнт тримає відкритим, і файл, який вибрала людина, — а Межа робочого простору пояснює, чому кожен із них є винятком.

Параметр, за яким демон має знайти документ усередині робочого простору, приймає лише шлях відносно робочого простору. Головний із них — release: у aggrega/irGraph і за тим самим контрактом скрізь, де він з’являється, — а абсолютне значення відхиляється з помилкою invalid-params, яка формулює контракт, а потім називає конкретну ваду. Запити, що пишуть усередині робочого простору, застосовують той самий контракт до своїх місць призначення, як зазначено в описі кожного. Кожен такий шлях потім оцінюється за тим, куди він веде, за одним правилом, хоч запит його читає, хоч пише, — за визначенням «усередині», яке дає Межа робочого простору, — і шлях, що веде назовні, відхиляється з власною помилкою запиту, яка цитує значення так, як ви його надіслали, без жодного читання чи запису: так само посилання на файл назовні і посилання на каталог на шляху, а також ще не створений шлях під пов’язаним каталогом, що веде назовні, — він відхиляється через посилання, а не записується чи шукається назовні й повідомляється як відсутній. Це охоплює кожен шлях, який запит називає демону для читання, — release скрізь, де він є, entity запиту aggrega/lint і entity, plugin, file та from запитів публікації, — тож запит не може через посилання прочитати файл, який власні переліки робочого простору оминають, — і кожне місце призначення: каталоги, у які пишуть генерація, імпорт і збірка, сутність, біля якої aggrega/pin пише свій lock, файл сутності та модуль, які aggrega/pluginSync читає й переписує, і документ, який редагує aggrega/editDocument. Єдиний виняток — release, що називає сутність Release, названу конфігурацією вашого робочого простору, як зазначено в описі aggrega/irGraph.

Вони відрізняються, бо відрізняються вади. Параметр, що називає документ, який у вас уже є, залишає лише одне питання — який документ, — тож зведення вашого запису до канонічного нічого не втрачає, а прийняття кожного запису вам теж нічого не коштує. Параметр, що вибирає документ із робочого простору, у такому становищі не перебуває: у бібліотеках шляхів, якими, ймовірно, користується клієнт, приєднання абсолютного значення до кореня дає це абсолютне значення, а не помилку. Тож мовчки виправлене значення змусило б демон читати шлях, якого робочий простір ніколи не містив, і повідомляти знахідки щодо нього, а вам розповідали б про файл, якого не існує. Відповідь — відмова, а не виправлення, бо демон, що виправляв би таке значення, залишав би кожного клієнта, який його надсилає, у переконанні, що контракт необов’язковий.

Як адресується сутність

Кожна сутність, яку називає відповідь, адресується однаково: kind, name і file. Поєднуйте за цими трьома ключами з aggrega/catalogIndex усе, що хочете показати: саме ця поверхня містить повний описовий набір сутності — apiVersion, description і labels, — тож відповідь, якій достатньо лише назвати сутність, повідомляє три адресні ключі й залишає опис одному місцю. Пошук за назвою, як-от aggrega/entityDefinition, повторює кілька описових полів, яких стосується його власна відповідь; індекс лишається поверхнею для поєднання, коли вам потрібен увесь набір.

Там, де відповідь може називати сутності з кількох місць, кожна ідентичність містить origin поруч із цими трьома ключами. Так роблять і aggrega/catalogIndex, і aggrega/attachCandidates, бо їхні сутності походять із документів робочого простору та з налаштованих каталогів. Відповідь, що спирається лише на одне місце, повідомляє три ключі без origin, оскільки ключ з одним можливим значенням нічого не повідомляє: кожна сутність, яку називає така відповідь, є документом робочого простору, а її file — шлях відносно робочого простору, який можна відкрити. Тож читайте origin там, де він є, а не вимагайте його всюди; поєднуєте ви в будь-якому разі за трьома ключами.

origin належить відповіді, що перелічує сутності, де розрізнення сукупностей — завдання читача. Відповідь за назвою, як-от aggrega/entityDefinition, його не містить: вона називає ту одну сутність, до якої розв’язалася назва, тож розділяти немає чого. Її власний пункт вище пояснює, коли її file порожній; не тлумачте цю порожнечу через значення origin нижче, які описують перелік.

origin вказує, звідки демон прочитав сутність, і саме він робить file зрозумілим.

  • workspace — документ Aggrega під коренем робочого простору. file — його шлях відносно цього кореня, який ваш клієнт може відкрити.
  • catalog — сутність, розв’язана з налаштованих каталогів. file у цьому переліку порожній, а name є повною адресою. Він порожній, бо перелік повідомляє те, що перелічив пошук у каталозі, — ідентичність, а не документ, тож запис не має шляху для повідомлення; це не шлях, приховений через своє розташування. Коли вам потрібен документ, запитайте aggrega/entityDefinition для тієї самої назви: цей запит розв’язує сутність і повідомляє її file за правилом вище, тож каталог поза коренем робочого простору там називається абсолютним шляхом. name — це координата, яку однаково використовують сутності Aggregate, Recipe і пошук у каталозі.

Читайте обидва разом, а не перевіряйте лише file. Порожній file сам по собі не скаже, чи сутність не має шляху в робочому просторі, чи його просто не повідомили; origin відповідає на це прямо.

Якщо сутність Feature досяжна обома способами — корінь робочого простору сам є одним із налаштованих каталогів, що поширено, — її повідомляють один раз, як документ робочого простору, бо саме файл цієї копії можна відкрити.

Що повідомляє відповідь про кандидатів на приєднання

aggrega/attachCandidates відповідає на одне запитання — які Features допускає цей набір міток — і пропонує три способи вказати, який набір міток ви маєте на увазі. Надсилайте рівно одну координату; дві координати або жодної буде відхилено, а не впорядковано за пріоритетом.

{node} адресує документ робочого простору за його metadata.name і більше нічого не потребує. Збіг обчислюється щодо міток, які цей документ оголошує в metadata.labels, а відповідь повідомляє labelSource: "declared".

{graphNode, release} адресує вузол скомпільованого графа. graphNode — це ідентифікатор, під яким граф зберігає вузол, той самий, що ви читаєте з aggrega/irGraph, включно з кваліфікованою формою, яку має вузол, внесений підагрегатом. release — шлях відносно кореня робочого простору, що називає сутність Release, граф якої слід побудувати, те саме значення, яке приймає aggrega/irGraph. Збіг обчислюється щодо остаточних міток вузла, а відповідь повідомляє labelSource: "resolved".

{labels} містить сам набір міток і нічого не адресує. Це форма, що лежить в основі двох інших: збіг є функцією набору міток і доступних Features, тож клієнтові, який уже має набір міток, нічого не потрібно називати й нічого не потрібно чекати. Надішліть JSON-об’єкт пар міток; відповідь повідомляє labelSource: "supplied" і порожній node, оскільки цей запит нічого не адресував. Порожній об’єкт є координатою — він запитує про вузол без міток, — тоді як повна відсутність ключа або надсилання null нічого не адресує і відхиляється.

Дві координати-імені розділено, бо їхні простори ідентифікаторів перетинаються. Ідентифікатор вузла графа і metadata.name документа можуть бути тим самим рядком, але називати різні речі, тож один параметр для обох був би неоднозначним, а демон, який вгадував би, який простір ви мали на увазі, іноді впевнено відповідав би про не той об’єкт. Неоднозначність усуває саме те, що ви вказуєте, яке запитання ставите.

labelSource повідомляє, наскільки далеко сягає відповідь, і три значення не взаємозамінні. declared — це збіг за тим, що один документ каже про себе, тобто те, що видно під час читання вихідного коду. resolved — це збіг за мітками, які вузол фактично отримує, тобто за тим, щодо чого збірка оцінює застосовність, — тож відповідь resolved є твердженням про те, що вирішила б збірка, а відповідь declared ним не є. supplied означає, що демон не читав жодних міток і зіставив те, що ви надіслали; наскільки вагома така відповідь, повністю залежить від того, звідки взявся ваш набір міток.

Саме тому клієнт, який має граф, має надсилати {labels}, а не ім’я. Остаточні мітки вузла — це мітки типу компонента, до якого він розв’язується, а не документа, що випадково має той самий ідентифікатор, і приєднання label-transform може потім додати, змінити чи вилучити їх — тож мітки, які визначають застосовність вузла, не обов’язково збігаються з мітками, оголошеними будь-яким окремим документом. Клієнт, що малює граф, уже має цей набір з aggrega/irGraph; передавши його назад, він отримає ту саму відповідь, що дає координата {graphNode, release}, без повторної побудови графа. Передавайте назад набір, який повідомив сам демон, — мітки вузла з aggrega/irGraph, мітки сутності з aggrega/catalogIndex, — і ваше уявлення про мітки вузла не зможе розійтися з уявленням демона, бо набір ніколи не залишав його власної відповіді. Якщо ж зібрати набір самостійно, ви ставите гіпотетичне запитання, на яке відповідають чесно і яке не є твердженням про жоден вузол робочого простору.

Кандидати надходять із робочого простору та з каталогу. Робочий простір, який зберігає свої Features у каталозі, а не у власному дереві, не має жодної локальної сутності Feature, і всі його кандидати мають origin: "catalog". Для вузла графа обидва джерела читаються в термінах сутності Release цього вузла: каталожні Features — це ті, що оголошують каталоги, які конфігурація робочого простору надає цій сутності Release, а власні документи робочого простору пропонуються за винятком тих, що лежать у каталозі, який читають лише інші Releases. Тому робочий простір, що зберігає варіант Feature для кожної Release, пропонує графу кожної Release її власний варіант і ніколи чужий, тоді як Feature, записана поряд із каталогами, поза будь-яким каталогом, пропонується для кожної Release. {node} і {labels} не називають жодної Release, тож вони використовують усі документи робочого простору та власні catalog_dirs робочого простору. Feature, яка взагалі не оголошує застосовності, є кандидатом для кожного вузла — відсутнє оголошення не висуває вимог, — тоді як Feature, чиє оголошення неможливо прочитати, не є кандидатом для жодного, бо вважати нечитабельний селектор задоволеним означало б дозволити друкарській помилці розширити те, що ви пропонуєте.

Ім’я, яке не розв’язується, — це помилка, а не порожній список. Ці дві відповіді означають різне: порожній масив candidates каже, що до цього вузла нічого не може бути приєднано, а повідомляти так про ім’я з помилкою означало б подавати друкарську помилку як усталену відповідь. Відмова називає простір, у якому відбувався пошук, тож ви знаєте, що шукати — документ робочого простору чи вузол графа. {labels} не має такого ризику — немає імені, яке можна було б набрати неправильно, — тож набір міток, який нічого не допускає, повертається як успішна відповідь із порожнім масивом, а запит, який демон не може прочитати, однаково відхиляється до будь-якого зіставлення.

Координаті вузла графа потрібен lockfile; двом іншим — ні. Побудова графа означає розв’язання всього, до чого сягає Release, тож цей шлях відхиляється з помилкою про відсутній lockfile, якщо його не згенеровано, і називає команду, яку слід виконати, — та сама передумова, що й у aggrega/irGraph, з тієї самої причини. Адресування документа робочого простору не будує графа, а надання набору міток не будує взагалі нічого, тож обидва відповідають і для робочого простору, який ще ніхто не підготував.

Метод лише повідомляє і ніколи не створює. Він нічого не змінює, нічого не записує і не створює жодного приєднання. Складання й застосування будь-якого редагування — справа редактора, де розташовані буфер та історія скасувань.

Що саме розв’язується, залежить від координати, і всі три різні. {node} нічого не розв’язує і не звертається ні до реєстру, ні до мережі — кандидати надходять із робочого простору та з каталогів, які вже є на диску. {labels} розв’язує ще менше: він нічого не шукає, бо шукати нічого. {graphNode, release} будує граф сутності Release, тож розв’язує замикання залежностей цієї Release так само, як aggrega/irGraph: спершу з локальних каталогів і кешу артефактів, а з налаштованого реєстру — для сутності, якої немає в жодному з них. Усі три відповідають офлайн для робочого простору, всі сутності якого локальні; лише координата вузла графа може шукати далі.

Запит про з’єднання

З’єднання, яке проводить компонент, може мати власні приєднання, що заповнюють слоти, оголошені його сокетом у сутності Component, яка споживає залежність, — наприклад, облікові дані, які компонент пред’являє тому, до чого веде з’єднання. Надішліть connection поряд із {graphNode, release}, щоб дізнатися, що туди можна помістити: socket — це сокет залежності, через який підключено з’єднання, а alias — ім’я, яке воно має в цьому сокеті, обидва точно так, як їх написав автор. З’єднання існує лише на скомпільованому графі, тому connection поряд із node або labels відхиляється, так само як і з’єднання без сокета чи без псевдоніма або таке, якого вузол не проводить.

Відповідь — це відповідь для вузла графа плюс слоти з’єднання. candidates зберігає своє значення — Features, які можуть приєднуватися до самого вузла, — а додається slots, по одному запису на кожен слот, оголошений сокетом, у порядку, в якому їх оголошує сутність Component:

  • slot — ім’я, під яким приєднання, що його заповнює, записується в features з’єднання.
  • selector, required, inject, sensitive і description — слот точно так, як сутність Component оголошує його на сокеті, порожні або false там, де вона нічого не оголошує. selector — це обмеження, за яким звужено кандидатів, тож пояснити кандидата або його відсутність можна лише з відповіді.
  • candidates — Features, які можуть заповнити цей слот на цьому з’єднанні. Збірка перевіряє таке приєднання за двома правилами, і застосовуються обидва: оголошена застосовність сутності Feature щодо остаточних міток вузла, за якою перевіряється кожне приєднання вузла, і selector слота щодо власних міток сутності Feature. Отже, кандидати слота завжди входять до кандидатів вузла, звужених селектором. Сутність Feature, щодо міток якої селектор неможливо обчислити, не пропонується, бо збірка її відхиляє, а не приймає.

Там, де жоден слот не можна заповнити, slots — порожній список, а noSlotReason пояснює чому. Читайте причину, а не сприймайте порожній список як «жодна Feature не підійшла» — це була б інша відповідь, і саме причина дає змогу їх розрізнити:

  • feature-created-connection — з’єднання провела сутність Feature зі свого блоку залежностей. Приєднання записується лише на з’єднанні, яке проводить компонент або сутність Release, тож сюди нічого не потрапляє, хоч би що оголошував сокет.
  • ad-hoc-socket — сокет не оголошено в сутності Component. Автор назвав його, що допустимо, а неоголошений сокет не оголошує жодного слота.
  • no-slot-declared — сутність Component оголошує сокет без жодного слота.

noSlotReason відсутнє там, де слот існує, а slots і noSlotReason обидва відсутні у відповіді на запит, який не називав з’єднання, — тож запит без з’єднання отримує відповідь без жодного з цих полів.

document приймається і тут нічого не змінює. Слоти належать сокету, а кандидати — сутностям Features, і вони однакові, хоч би в якому документі записано приєднання; куди воно потрапляє, відповідає aggrega/attachmentContainer. Значення, відмінне від aggregate або release, однаково відхиляється, бо значення, яке прийнято й проігноровано, відправник сприймає як враховане.

Що повідомляє відповідь про кандидатів для з’єднання

aggrega/connectionCandidates відповідає одразу на два запитання, і лише на одне з них відповідь повна. Якщо читати відповідь як єдиний відфільтрований список, друге буде витлумачено хибно.

Кожен повідомлений сокет містить targets — локальні для робочого простору сутності Components, чиї оголошені мітки задовольняють обмеження на мітки, яке цей сокет оголошує щодо того, що може його задовольнити, — а також selector, з якого обчислено ці цілі, прапорець required, який оголошує сокет, і declaration. targets завжди є масивом, порожнім, а не відсутнім, тож сокет, який ніщо не задовольняє, однаково повідомляється як сокет, оголошений сутністю.

Половина про цілі повна. Набір визначається обчисленням оголошеного обмеження сокета щодо оголошених міток кандидата — тим самим обчисленням, яке виконує збірка, тож те, що ви пропонуєте, — це саме те, що те саме обмеження допускає під час збірки. Сокет, який не оголошує обмеження, залишає свої цілі необмеженими й повідомляє кожну сутність Component — це значення порожнього селектора в мові обмежень, а не помилка.

Половина про сокети відкрита, і саме declaration разом з adHocSocketsAccepted дають змогу це розрізнити. Автор сутності Aggregate володіє її топологією й може підключити сокет, який сутність компонента в каталозі ніколи не оголошувала, тож сокети, оголошені сутністю, — це корисний початковий набір, а не набір допустимих назв сокетів. Подавайте їх як пропозиції, а не як єдині варіанти: засіб вибору, який пропонував би лише оголошені сокети, казав би авторові, що його свобода вужча, ніж є насправді.

  • declaration має значення declared, коли адресована сутність перелічує сокет у своєму usesSchema, і ad-hoc, коли ні. Це ті самі два значення, які має ребро в графі IR, тож один словник відповідає на запитання «звідки взявся цей сокет», де б ви його не зустріли.
  • adHocSocketsAccepted повідомляє, чи приймає поверхня адресованої сутності сокет, якого не перелічує її власне оголошення. Це значення не завжди істинне: власна поверхня залежностей сутності Component його приймає, а поверхня приєднання сутності Feature — ні, бо приєднання бере участь у топології, яку оголошує приєднана сутність Feature, а не створює власну. Ситуативний сокет на поверхні, яка його не приймає, повідомляється без цілей, бо жодне з’єднання через нього не збереться.

Зазначення socket у запиті обмежує відповідь цим одним сокетом, і це єдиний спосіб запитати про сокет, який сутність не оголошує, — неоголошений сокет не з’являється в жодному оголошенні, яке можна було б перелічити. Пропустіть його, щоб отримати всі сокети, оголошені сутністю, у порядку, в якому їх написано.

Те, що повідомляється, — це збіг за оголошеними мітками. Збірка обчислює обмеження сокета щодо остаточних міток вузла на дальньому кінці ребра, а це мітки типу компонента, до якого розв’язується цей вузол, після того як свій вплив мало будь-яке приєднання label-transform, — не обов’язково мітки документа, який ви назвали. Тож позитивна відповідь тут не є обіцянкою щодо того, що вирішить збірка, — це те саме обмеження, яке aggrega/attachCandidates має для свого джерела міток declared.

Метод повідомляє й ніколи не створює. Він нічого не розв’язує, не звертається до жодного реєстру чи мережі й нічого не записує: не створює ребра й не пропонує тексту. Складання й застосування редагування — справа редактора, адже саме там є буфер та історія скасувань.

Для ідентичностей сутностей у targets — kind, name і file — виконайте об’єднання з aggrega/catalogIndex, як описано в розділі Як адресується сутність. Описові поля повідомляються там і навмисно не повторюються тут, тож ця відповідь не містить їхньої другої копії, яка могла б розійтися з першою. Цілі — це сутності Components робочого простору, тож кожна має file, який можна відкрити, і жодна не містить origin: ця відповідь спирається на одне джерело, а об’єднання виконується за трьома ключами.

Що повідомляє відповідь про контейнер вкладення

aggrega/attachmentContainer стоїть між запитами кандидатів вище та точкою вставлення нижче. Ті кажуть, що може приєднатися до вузла; цей каже, до якого контейнера належить вкладення для нього і в якому документі; наступний каже, куди в байтах цього документа потрапляє текст.

Запитуйте контейнер, а не складайте його самі. Ідентифікатор вузла та шлях підсистеми, що його охоплює, обидва записуються з крапками між частинами, а крапка є допустимим символом в імені, яке вводить автор, — тож ззовні документа неможливо відрізнити структурну крапку від крапки всередині імені. Клієнт, який склав би шлях сам, отримав би щось, що читається правильно, але адресує ключ, якого ніхто не писав, і подальше редагування створило б цей ключ, а не було б відхилене. Обидва шляхи склав компілятор, тож саме компілятор і розбирає їх.

Ідентифікатор вузла взагалі не містить сліду підсистеми, що його охоплює. Компонент, створений усередині subsystems.billing.subsystems.payments, має в графі ключ ledger, точнісінько як компонент верхнього рівня, тож в ідентифікаторі немає нічого, від чого клієнт міг би відштовхнутися, хоч як ретельно він його розбиває.

Відповідь складається з трьох полів.

  • node повторює вузол, якого стосується відповідь, тож клієнт із кількома незавершеними запитами зіставляє кожну відповідь із її запитом, не відстежуючи порядку самостійно.
  • file — документ, у якому створено вузол, відносно робочого простору. Він є частиною відповіді, а не тим, що ви вже знаєте: вузол, який додав імпортований модуль, створено у власному документі цього модуля під іменем, яке дав йому модуль, тож і файл, і останній сегмент контейнера відрізняються від усього, що назвав запит.
  • container — структурний шлях від кореня цього документа у вигляді списку сегментів: ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Кожен рівень охопної підсистеми знову стоїть під ключем subsystems, саме так його записує документ. Компонент, який автор написав на верхньому рівні, натомість має ["spec", "components", "checkout", "features"], бо область, у яку компілюється такий компонент, не міститься в жодному файлі.

Це список сегментів і ніколи не об’єднаний рядок, і саме в цьому сенс такої форми. Об’єднаний шлях довелося б знову розбивати тому, хто його отримав, тобто неоднозначність, описана вище, повернулася б на один виклик пізніше. Передавайте список у aggrega/insertionPoint як його container без змін.

Він читає структуру і ніколи не зміст. Відповідь виводиться з документа, у якому створено вузол, області, у якій він перебуває, та імені, яке ввів автор. Ніщо не зчитується з того, як названо компонент, який тип він має чи що каже будь-яка мітка.

Він повідомляє і ніколи не записує. Метод нічого не змінює і нічого не записує в жоден документ. Він не створює вкладення, не складає тексту й не застосовує редагування; він не вирішує, що може приєднатися, — це робить aggrega/attachCandidates.

Запит, що називає вузол, якого немає в графі, відхиляється, а не отримує відповідь. Ідентифікатори вузлів — це власні ключі графа (читайте їх із графа, який повертає aggrega/irGraph), а вузол, який додав імпортований модуль, має кваліфікований ідентифікатор. Вузол, для якого граф не записує документа, теж відхиляється: місце вкладення — це факт про документ, тож вузол без документа не має відповіді, а не має порожню.

Він потребує lock-файлу з тієї ж причини, що й aggrega/irGraph: назвати контейнер означає побудувати граф сутності Release, а граф, побудований із байтів, за які ніщо не ручається, повідомлявся б точнісінько як перевірений.

Вкладення на з’єднанні

Надішліть connection поруч із {graphNode, release} — його socket, його alias і його document, — і відповідь назве контейнер features у власному записі цього з’єднання замість запису вузла. document тут обов’язковий, бо вкладення на з’єднанні, яке провела сутність Aggregate, може містити будь-який із документів: розробник пише його в записі з’єднання в сутності Aggregate, оператор — у записі для цього ребра в сутності Release.

  • aggregate називає запис з’єднання в документі, у якому створено вузол, — ["spec", "components", "gateway", "uses", "models", "gpt", "features"] для компонента верхнього рівня, де кожна охопна підсистема записується рівень за рівнем, як описано вище. З’єднання, яке провела сутність Release, не має запису в сутності Aggregate, тож там воно відхиляється.
  • release називає запис для ребра під власним записом сутності Release для вузла — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — незалежно від того, чи сутність Release уже пише цей запис для ребра. Якщо ні, aggrega/insertionPoint повідомляє ключі, які ще треба записати, у missingContainerKeys. file тоді — документ сутності Release. Сутність Release, яка взагалі не пише запису для вузла, відхиляється: де розміщено вузол, вирішує оператор, і відповідь цього не визначає.

З’єднання, яке провела сутність Feature, відхиляється в обох документах із причини, яку наводить feature-created-connection вище. Вузол, сокет і псевдонім зіставляються точно так, як записані, а з’єднання, якого вузол не проводить, відхиляється, а не отримує у відповідь шлях. Усі інші властивості, описані вище, залишаються незмінними: відповідь є списком сегментів, вона читає структуру і ніколи не зміст, і нічого не записує.

Що повідомляє відповідь connection-at-position

aggrega/connectionAtPosition — це крок перед двома запитами щодо з’єднань вище, для клієнта, який має місце в документі, а не вузол у графі, — наприклад, курсор на записі з’єднання. Він відповідає, яке з’єднання записано там, у координатах, які приймають ті запити, і на цьому зупиняється.

Відповідь — одна з двох половин, ніколи не обидві.

  • graphNode і connection — вузол, компонент якого прокладає з’єднання, за ідентифікатором, під яким його зберігає скомпільований граф, і з’єднання за його socket та alias, де document називає документ, у якому прочитано позицію: aggregate для Aggregate або модуля, який він імпортує, release для Release. Передайте graphNode, той самий release і connection до aggrega/attachCandidates, щоб отримати слоти, які оголошує сокет з’єднання, і до aggrega/attachmentContainer, щоб дізнатися, куди йде вкладення на ньому; контейнер, який він називає, розташований усередині того самого запису, у який потрапила позиція.
  • noConnectionReason — чому з’єднання не повідомлено. Набір закритий:
    • no-connection-entry — позиція не перебуває в жодному записі, у якому записується вкладення. З’єднання, записане як список цілей (db: [store]), і з’єднання, яке прокладає власний блок залежностей Feature, не мають такого запису, тож позиція на будь-якому з них теж дає цю відповідь.
    • feature-created-connection — позиція перебуває в записі Release для з’єднання, яке проклала Feature, і цей запис не має вкладення з причини, наведеної у відповіді щодо слотів вище. Release записує такий запис там, де блок залежностей Feature прокладає з’єднання через сокет, який також оголошує Component-споживач; запис збирається незалежно від того, чи нічого не конфігурує, чи задає infra для окремого ребра з’єднання.
    • unknown-connection — позиція перебуває в записі, який Release записує для з’єднання, якого немає в скомпільованому графі. Release, що збирається, може містити такий запис — наприклад, запис під псевдонімом, який ніщо не прокладає і який нічого не конфігурує (немає target, немає infra, немає features), або запис для компонента, вимкненого перемикачем active:, з’єднання якого виходять зі збірки разом із ним.

Які записи враховуються. В Aggregate — кожне з’єднання, яке прокладає компонент, у його записі під псевдонімом з’єднання в документі, де компонент створено, — для компонента, який додає імпортований модуль, це власний документ того модуля. У Release — кожен запис для окремого ребра, який він записує, незалежно від того, чи запис прокладає своє з’єднання, чи конфігурує з’єднання, яке проклав Aggregate. Де розташований кожен запис, фіксує скомпільований граф, тож те, чи є ключ з’єднанням, ніколи не визначається з його назви. Компонента, вимкненого перемикачем active:, немає в скомпільованому графі, тому його власні записи в Aggregate дають відповідь no-connection-entry, а запис Release для одного з його з’єднань — unknown-connection.

Позиція будь-де всередині запису перебуває в ньому. Запис тягнеться від ключа псевдоніма до останнього рядка з відступом під ним, тож позиція на псевдонімі, на його target або всередині його features отримує відповідь для цього з’єднання, а там, де записи вкладені, перемагає найглибший. Позиція на власному ключі сокета, над записаними під ним псевдонімами, не перебуває в жодному з них — чи містить сокет один псевдонім, чи кілька, — так само як і позиція у відступі перед ключем псевдоніма.

Який документ який — випливає з Release. Власний файл Release читається для записів, які він записує; будь-який інший файл читається для записів, які граф фіксує як місця створення компонентів. Документ, з якого граф Release нічого не читає, у кожній позиції дає відповідь no-connection-entry.

Він лише повідомляє й ніколи не записує, і читає документ так само, як aggrega/insertionPoint: спершу з копії сеансу, інакше з диска, у межах робочого простору, з тими самими відмовами для документа, що перебуває поза ним, не читається або не є коректним YAML. Він вимагає lockfile з тієї самої причини, що й aggrega/attachmentContainer, і будує граф, нічого не рендерячи.

Що повідомляє відповідь про точку вставлення

aggrega/insertionPoint — це відповідник двох запитів кандидатів вище. Ті кажуть, що може приєднатися чи з’єднатися; цей каже, куди в одному конкретному документі належить текст для цього. Він відповідає і на цьому зупиняється.

Ви називаєте контейнер; демон знаходить його. container — це структурний шлях від кореня документа, ["spec", "components", "web", "features"], і це ваше твердження про те, де запис такого виду належить у документі такого виду. Демон не виводить цей шлях із того, як називається сутність, який тип вона має чи що вона, здається, означає. Він читає байти, які написав автор, і повідомляє, які сегменти шляху цей документ уже має, у яких стовпцях розташовані його записи та до якого останнього рядка сягає його найглибший блок. Отже, знання про те, який ключ, залишається за викликачем, а знання про те, куди в цьому файлі йдуть записи цього ключа, надходить звідси.

Для приєднання Feature до вузла скомпільованого графа викликачеві не потрібно знати цей ключ самостійно: запитайте в aggrega/attachmentContainer документ і контейнер і передайте обидва сюди без змін.

Відповідь — це позиція нульової ширини плюс те, що вам треба написати довкола неї. file — це документ, відносно робочого простору. container повторює шлях, про який ви запитували, тож клієнт із кількома незавершеними запитами зіставляє кожну відповідь із її запитанням, не ведучи власного порядку. position вставляє, а не замінює: ніщо, що вже є в документі, не перезаписується і не зсувається.

  • precededByLineBreak — почніть текст, який ви пишете, з розриву рядка. Позиція розташована в кінці рядка, після якого йде новий запис; вона перебуває в межах діапазону незалежно від того, чи закінчується файл символом нового рядка, і не порушує жодного вже написаного байта. Значення false буває лише для документа, у якому немає нічого, після чого можна розташуватися, і тоді ви пишете з початку файлу.
  • missingContainerKeys — сегменти шляху контейнера, яких цей документ ще не містить, починаючи з зовнішнього. Кожен слід записати як окремий ключ, перш ніж запис зможе потрапити всередину найглибшого. Список порожній, якщо весь шлях уже є.
  • entryIndent — стовпець, з якого починається перший рядок самого запису, у пробілах від початку рядка.
  • indentStep — наскільки далі відступається кожен рівень вкладеності.
  • indentStepMeasured — чи було цей крок виміряно з власної вкладеності цього документа. Якщо значення false, документ не має вкладеності для вимірювання, і крок є резервним, тож клієнт, який волів би встановити власний, знає, що може це зробити.
  • entryShape — mapping або sequence, визначене з того, що контейнер уже містить, і unknown, якщо контейнера ще немає або він нічого не містить. unknown не є помилкою: документ не вказав, якої форми набувають його записи, тож цей вибір за вами.

Застосування. Запишіть розрив рядка, якщо встановлено precededByLineBreak. Потім по одному рядку на кожен запис missingContainerKeys, починаючи з зовнішнього, кожен — ключ, за яким іде двокрапка; перший із відступом entryIndent мінус indentStep, помножений на кількість відсутніх ключів, а кожен наступний — на indentStep далі. Потім сам запис із відступом entryIndent. Якщо missingContainerKeys порожній, запис — єдиний рядок, який ви пишете.

Читайте missingContainerKeys, навіть коли очікуєте, що контейнер є. Позиція, застосована без ключів, які мають їй передувати, дає документ, що більше не розбирається, і це та єдина помилка, яку не можна прочитати з цієї відповіді як відсутню.

position рахує від нуля, на відміну від позиції діагностики. І line, і character відраховуються від 0, що відповідає значенням позицій у стилі LSP, які повторно використовує цей протокол, тоді як line і column у записі діагностики відраховуються від 1, як описано в розділі What a diagnostic entry carries (Що містить запис діагностики). Клієнт, який передає дані з однієї поверхні в іншу, перетворює їх.

positionEncoding називає одиниці, у яких вимірюється character, і це кодування, узгоджене під час рукостискання. Його повідомляють у відповіді, а не залишають неявним, оскільки позицію, одиниці якої викликач має вгадувати, він не може застосувати: зміщення, виміряні одним способом і застосовані до буфера, виміряного інакше, пошкоджують документ на першому символі поза ASCII.

Запит, що не вказує на місце, куди може потрапити запис, відхиляється, а не отримує відповідь. Кожен із цих випадків — стан запиту, а не робочого простору, тож він повертається зі стандартним кодом invalid-params, і повторна спроба нічого не змінить, доки не зміниться file або container.

  • Документ не названо, він не перебуває в робочому просторі, його не вдалося прочитати, або він не є коректним YAML — документ без структури не має позиції, яку можна повідомити.
  • Шлях контейнера нічого не називає: він не має сегментів, або один із його сегментів порожній.
  • Шлях проходить через значення, яке документ містить як скаляр. Усередину скаляра нічого не можна додати, а його заміна була б переписуванням, а не вставленням.
  • Шлях сягає колекції, яку автор написав у потоковому стилі. Додавання запису до неї переписує байти, які автор уже написав, замість додавання рядка, а це редагування, а не позиція.
  • Шлях адресує блокову послідовність чимось, що не є одним із її індексів. Записи послідовності адресуються за позицією, тож ім’я в ній нічого не досягає, і не можна створити запис, який мав би це ім’я.

Він читає буфер, який утримує редактор, а не лише файл на диску. Спершу перевіряється кеш розбору демона, тож позиція повідомляється щодо незбереженого вмісту, якщо він є, і щодо самого файлу, якщо кеш нічого для нього не містить.

Він повідомляє і ніколи не записує. Метод нічого не змінює, нічого не розв’язує, не звертається до реєстру чи мережі й нічого не записує в жоден документ. Він не складає текст запису і не застосовує його. Складання та застосування редагування — справа редактора, адже саме там буфер та історія скасувань.

Що повідомляє відповідь на редагування документа

aggrega/editDocument — це друга половина пари, описаної вище: ті запити кажуть, куди належить запис, і залишають вам скласти й застосувати його; цей складає й застосовує запис, і він записує. Обидва варіанти доступні, бо клієнту з незбереженим буфером і клієнту, що редагує вміст на диску, потрібні різні половини: редактор із власною історією скасування сам вставляє текст, а клієнт, якому зручніше, щоб файл відредагували, ніж щоб йому сказали, де редагувати, надсилає цей запит.

Один виклик застосовує одне редагування, і набір редагувань закритий. edit визначає, яке саме: add-component додає екземпляр компонента в контейнер components, attach-feature приєднує сутність Feature до вузла, wire-edge прокладає з’єднання в одному із сокетів залежностей вузла, а set-value задає одне значення на вузлі. Немає редагування, яке видаляє, замінює вже написаний вами блок, щось переупорядковує або дослівно записує надані вами байти, тож це не засіб запису файлів під вужчою назвою, і значення поза цими чотирма відхиляється, а не тлумачиться. У відмові перелічено, що можна вказати.

Вузол ви вказуєте як структурний шлях — так само, як його приймають два запити вище. node — це шлях від кореня документа, ["spec", "components", "web"], а контейнер, у який потрапляє запис, випливає з edit. Для add-component шлях вказує на сам контейнер components, бо запис, що додається, і є вузлом. name — ключ, під яким записується запис: ім’я екземпляра, ім’я приєднання, псевдонім з’єднання або ключ значення. value — те, що містить запис, а його значення випливає з edit: сутність, яку запитує запис, вузол, на який указує з’єднання, або скаляр, якому дорівнює значення. socket читається для wire-edge і в інших випадках ігнорується.

Шлях, а не ім’я — з тієї самої причини, з якої його приймає запит на визначення місця: ім’я довелося б шукати, а ім’я, що трапляється на двох рівнях, залишило б компілятору вирішувати, яке з них ви мали на увазі. Тож клієнт, який знає, який вузол редагує, так і каже, а клієнт, який не знає, розуміє, що перед будь-яким редагуванням має відповісти на запитання.

Кожен байт, якого редагування не торкається, зберігається. Документ розбирається лише для того, щоб знайти контейнер і рядок, яким закінчується його блок; запис формується й вставляється на рівні рядків. Коментарі, порожні рядки, стиль лапок, згорнуті й літеральні скаляри, шаблонні вирази та наявність завершального символу нового рядка переносяться без змін, а крок вкладеності вимірюється за власними відступами документа, а не нав’язується, тож запис потрапляє в той стиль, у якому ви вже пишете. Той самий запит до того самого документа дає ті самі байти, тож клієнт може порівнювати два запуски, а під час рецензування одне редагування читається як один diff.

Результат має бути документом, який ви могли б набрати вручну, і саме від цього залежить запис. Складений документ перевіряється за схемою його власного виду й потрапляє на диск, лише якщо перевірку пройдено. Запит, що створив би щось, що відхиляє схема авторингу, повертається як E0275 — редагування відхилено, бо результівний документ був би недійсним, і нічого не записано — із зазначенням властивості, яку схема не допустила, і її місця. Файл залишається байт у байт таким, як був, тож відхилене редагування неможливо відрізнити від того, якого ніколи не пробували, і ви можете повторити виправлений запит до того самого документа, з якого почали. Тому ж тут не повторюється жодне правило: вимога, щоб документ Release містив значення розробника, відхиляється тією самою схемою, яка відхилила б документ, набраний вручну.

Що є семантично допустимим, тут не вирішується. Чи оголошує сокет залежності виробник і чи виконано умови застосовності сутності Feature — це належить до розв’язання, яке виконує збірка, і кожне з цього має власні звіти. Тож ви можете вказати з’єднання, про яке цей запит ніколи не чув, а сутність Aggregate може описати сокет, який її сутність із каталогу не оголошує заздалегідь; що можна споживати через сокет, і далі оголошує виробник. Коли питання саме в цьому, виконайте aggrega/validate із зазначенням Release або запитайте граф.

Відповідь називає, що було додано і що потрапило на диск, і це різні питання. content містить документ, створений редагуванням, за обох способів доставки. written називає файл, що потрапив на диск, і порожнє за dryRun. container — структурний шлях контейнера, у який потрапив запис, тож ви можете знайти щойно додане, не виводячи це правило заново. createdContainers називає сегменти, які записало це редагування, бо документ їх не містив, від зовнішнього до внутрішнього; у звичайному випадку, коли весь шлях уже був, воно порожнє, і саме за ним можна відрізнити запис, доданий в наявний блок, від запису, який створив власний блок. file і edit повторюють надіслане вами, тож клієнт із кількома незавершеними запитами зіставляє кожну відповідь із її запитом. written, container і createdContainers завжди є масивами — порожніми, а не відсутніми.

За dryRun нічого не створюється. written порожнє, content містить документ, який створив би запис, а файл не змінюється, тож редактор може показати результат авторові, щоб той зберіг, змінив або відкинув його. Типова поведінка — запис, бо продуктом операції є відредагований документ, і поверхня, що його створює, мусить його надати: запит, який нічого не каже про доставку, редагує файл.

Усе інше, що робить запис, робить і пробний запуск. Складений документ у будь-якому разі перевіряється за схемою його власного виду, тож редагування, яке відхилив би запис, відхиляється й за dryRun із зазначенням тієї самої властивості, — а отже, помилка, яку ви отримуєте під час пробного запуску, і є тією помилкою, яку дав би запис.

Запис, який уже є і містить те, що ви запитали, — це операція без дії: документ повертається незмінним, і нічого не записується. Запис із таким іменем, що містить щось інше, відхиляється, а не замінюється, бо заміна написаного автором не є одним із чотирьох редагувань.

Після запису демон перечитує документ. Те, що він зберігав для цього файлу, відкидається, а його подання на рівні робочого простору скидається, тож наступний запит на перевірку, підказку, автодоповнення чи граф обробляється за байтами, створеними редагуванням, а не за версією, яку воно замінило. Саме редагування читає файл на диску, а не буфер, який ви тримаєте, — на відміну від запиту на визначення місця вище, що спершу звертається до незбереженого вмісту. Це зроблено навмисно: запис із незбереженого буфера переніс би на сторінку вміст, який автор не зберіг, під виглядом застосування одного запису. Збережіть буфер, а потім редагуйте.

Запит, що не вказує на місце, куди може потрапити запис, відхиляється, а не отримує відповідь, зі стандартним кодом invalid-params, і повторна спроба нічого не змінить, доки не зміниться запит. Документ не вказано, він поза робочим простором, його не вдалося прочитати, він не є коректним YAML або не оголошує виду, за схемою якого можна перевірити результат; edit не вказано або воно не є одним із чотирьох; node нічого не вказує або один із його сегментів порожній; не задано name; для wire-edge не вказано socket; для set-value задано відображення або послідовність там, де має бути скаляр; шлях до вузла веде до скаляра чи послідовності або до колекції, написаної в потоковому стилі, де додавання рядка переписало б байти, вже наявні на сторінці; або шлях до вузла не веде ні до чого в документі.

За будь-якого способу доставки він не розв’язує жодних залежностей, не звертається до реєстру й не використовує мережу.

Що охоплює відповідь про ефективну конфігурацію

aggrega/effectiveConfiguration відповідає на два запитання: яка конфігурація діє в цьому сеансі та який шар визначив кожне налаштування. Це та сама відповідь, яку друкує aggrega config show --origin; вона обчислюється один раз і повідомляється на обох поверхнях, тож вони не можуть розходитися щодо того, звідки взялося налаштування.

source має одну з чотирьох форм. Абсолютний шлях до файлу конфігурації — зокрема глобального файлу, який читає демон, запущений як aggrega --config <file> serve, названого тим шляхом, що його було передано; змінна середовища з префіксом env:, наприклад env:AGGREGA_SIGNING_REQUIRED; глобальний прапорець, указаний у командному рядку, яким було запущено демон, названий як прапорець, наприклад --offline для демона, запущеного як aggrega --offline serve; або (built-in defaults) для налаштування, яке не задає жоден шар. Перші три з’являються дослівно в layers. Типові значення — ні, бо типові значення не є шаром, що зробив внесок: це те, що діє там, де жоден шар нічого не задав.

Налаштування приписується шару з найвищим пріоритетом, який його задає, хоч би яке значення цей шар записує. Якщо файл конфігурації записує вбудоване типове значення або повторює значення, яке вже задає файл під ним, називається саме цей файл: це він утримує значення. Файл задає налаштування, містячи його ключ, зокрема супутній ключ списку _append, а змінна середовища — будучи експортованою з непорожнім значенням. Файл конфігурації, яким володіє ваш конвеєр, ніколи не називається для ключа, який він ігнорує. aggrega config show --origin звітує за тим самим правилом.

Кожне налаштування, яке оголошує схема конфігурації, враховано, хоча не для кожного є власний рядок. Адитивний супутній ключ списку _append повідомляється в рядку списку, до якого він додає, тож шар, що робить внесок лише через супутній ключ, називається в рядку цього списку, а супутній ключ власного рядка не має. Налаштування всередині записів списку — політика довіри реєстру, вхідні дані прикріплення плагіна — охоплюється рядком цього списку.

Ще два обмеження, кожне з яких робить відповідь грубішою, ніж здається.

  • Налаштування-список або налаштування-словник приписується цілком шару з найвищим пріоритетом, який його задає. Приписування окремих записів не відстежується, тож список, складений із двох шарів, повідомляє лише шар із вищим пріоритетом, а запис, внесений нижчим шаром, не можна відрізнити від запису, який написав вищий шар.
  • Вимога підпису приписується першому шару, який її ввімкнув, а не останньому, що її згадав. Це налаштування компонується так, що будь-який шар, який його вмикає, перемагає, і жоден пізніший шар не може його вимкнути, тож перший шар, що його ввімкнув, і є тим, який зробив ефективне значення таким, яким воно є. Шар, що записує required: false, нічого не вмикає, тож там, де кожен шар, що його згадує, записує false, налаштування повідомляє (built-in defaults).

Кожне повідомлене значення — це результат розв’язання, отриманий, коли цей робочий простір було вперше названо. Редагування файлу конфігурації не змінює значення тут; перезапуск демона — змінює. Так задумано: ці значення — конфігурація, за якою відповідають на кожен інший запит щодо цього робочого простору, і саме це робить їх порівнянними з коренем і шаром конфігурації, які повідомило для нього рукостискання. Клієнт, що показує конфігурацію поряд із файлом, який редагує користувач, має вказувати, яке з двох він показує.

Приписування шарів обчислюється в момент запиту, за файлами в їхньому поточному стані. Тож файл конфігурації, відредагований пізніше, може змінити source, тоді як значення поруч лишається таким, яким його було розв’язано. Дві половини відповідають на різні запитання — що діє і який шар це визначив, — і зафіксовано лише першу. Перезапустіть демон, щоб знову їх узгодити.

Він лише звітує й ніколи не записує. Метод не змінює конфігурацію, не створює файлів і нічого не розв’язує з реєстру чи мережі.

Вміст файлу окремого шару тут не надається. Командний рядок може надрукувати власні байти одного шару дослівно, зі збереженими коментарями та форматуванням; цей метод повідомляє результат розв’язання, а не байти. Клієнт, якому потрібен текст шару, має шлях у layers і може його відкрити.

Що залишає після себе запис конфігурації

aggrega/configInit і aggrega/configCapture обидва створюють документ конфігурації й обидва записують його. Відповідь називає файл; відкрити його — ваша наступна дія, а не заміна запису. Жоден із них не передає вам вміст, щоб ви розмістили його самі, якщо ви прямо про це не попросите, бо можливість, результатом якої є документ, що так і не був записаний, — це інша можливість під тією самою назвою.

Ці два запити різняться тим, наскільки далеко вони сягають, і кожна відповідь це вказує. Прочитайте її, перш ніж показувати результат.

  • Початкове заповнення за замовчуванням записує конфігурацію, спільну для всіх робочих просторів на машині. Реєстр і ідентичності, яким ви на ньому довіряєте, зазвичай однакові, де б ви не працювали, тому запис потрапляє саме туди, якщо запит не надсилає workspace: true. scope містить configFile, який було записано, і machineWide, що вказує, чи це спільний файл, — це виводиться з файлу, до якого розв’язався запис, а не з того, що просив запит, тож відповідь не може описати зміну для всієї машини як локальну.
  • Заморожування ніколи не виходить за межі робочого простору. Воно не приймає ні цілі запису, ні перевизначення: уся його мета — зробити один проєкт самодостатнім, тому воно завжди записує власний .aggrega-config.yaml цього проєкту. Саме тому його відповідь містить configFile і workspaceRoot і не заявляє жодної області дії — немає охоплення, яке треба було б указувати.

Початкове заповнення відмовляє замість перезапису. Файл конфігурації, який уже існує, залишається недоторканим, і відмова називає його, бо початкове заповнення призначене для конфігурації, якої ще немає, тоді як спільний запис, якому воно делегує, за задумом виконує злиття. Надішліть force, щоб записати попри це; запис реєстру зливається з тим, що вже є, а інші налаштування зберігаються. Відхилений запит не змінює нічого.

trust повідомляє, що сталося з оголошеною політикою реєстру, у вигляді окремих результатів, а не тексту. pinned означає, що реєстр оголосив політику і її було взято, а identities рахує ідентичності. notAdvertised означає, що реєстр опитали і він не оголосив жодної політики, і це не збій — початкове заповнення продовжується, а reason повідомляє, що зробила кінцева точка. Реєстр, до якого не вдалося достукатися, позначається так само, оскільки жодна політика не повернулася і заповнення так само продовжується, і поруч містить unreachable там, де сам збій показує, що до реєстру так і не достукалися: його ім’я не розв’язалося, з’єднання з ним було відхилено або не вдалося відкрити, чи не вдалося встановити з ним захищене з’єднання. Реєстр, який відповів — повідомленням «не знайдено» або статусом помилки, — ніколи не містить unreachable, тож читайте цей ключ, а не слова в reason, щоб відрізнити реєстр, який не публікує політики, від того, якого так і не опитали. baseline означає, що було закріплено вбудовану базову політику офіційного хабу, бо жодної оголошеної політики не було взято, а reason пояснює чому; запис містить політику, тож нічого закріплювати вручну не потрібно. Ці два ключі відповідають на різні питання, тому хаб, який опитали і який нічого не оголосив, містить обидва, а хаб в офлайн-робочому просторі — якого не опитували — містить лише baseline, а reason повідомляє, що робочий простір офлайн. Будь-який інший реєстр, що нічого не оголошує, містить лише notAdvertised, заповнюється без політики, і порада, що йде далі, — закріпити ідентичності вручну; в офлайні такий запит відхиляється, а не отримує відповідь. skipped означає, що спроби отримання не було. Клієнт, який вважав би помилкою будь-що, крім pinned, повідомляв би про робочу конфігурацію як про зламану.

За dryRun нічого не створюється. written має значення false, content містить документ, який створив би запис, а файл, для якого призначений цей вміст, — це scope.configFile. Жоден каталог не створюється і жоден файл не змінюється, тож редактор може показати текст автору й дозволити йому зберегти, змінити або відкинути його.

Пробний запуск відрізняється від запису рівно в одному — він не записує, — тож кожну відмову, яку виконує запис, виконує і він. Тут важлива відмова через наявний файл: dryRun над файлом конфігурації, який уже існує, відхиляється з назвою файлу точно так само, як запис. Саме це робить відповідь придатною як предикат: якщо пробний запуск відмовляє, запис відмовив би з тієї самої причини і з тим самим повідомленням. Надішліть force разом із dryRun, щоб натомість отримати злиття, яке створив би перезапис, усе ще нічого не записуючи. До реєстру звертаються по його оголошену політику довіри за будь-якого способу доставки, бо політика в цьому вмісті — це та політика, яку закріпив би запис.

Те, що повідомляє заморожування, — це те, що воно записало, а не його опис. sockets перелічує кожен сокет плагіна, який було заморожено, разом із замороженими в ньому підключеннями; catalogDirs містить каталоги каталогів. Обидва завжди є масивами — порожніми, а не відсутніми.

  • socket і field — не той самий рядок, і різниця не косметична. socket називає сокет, до якого прив’язані підключення; field — це ключ, під яким їх записано у файлі. Вони різняться лише для сокета провайдера, який записується під ключем у множині, — тож використовуйте field, коли вказуєте читачеві на рядок у документі, і socket, коли називаєте сам сокет.
  • Кожне підключення містить uri, capability, function і role, присутні лише там, де вони в підключення є. Вони називають підключення, а не відтворюють його повністю: необов’язкові вхідні дані підключення, що задаються під час підключення, заморожуються у файл дослівно й у відповіді не повторюються. Авторитетною копією є файл.
  • captured: false — це успіх. Проєкт, у конфігурації якого збирання не бере участі, не має нічого критичного для збирання, що можна заморозити, тож файл залишається як є, а обидва списки повертаються порожніми. Якщо вважати це помилкою, справний робочий простір буде показано як зламаний.

За замовчуванням заморожується лише те, що визначає байти результату — прив’язки провайдерів і підключення керування, що перетворюють мітки. Шлюзи вердиктів керування та лінтерів і сокет імпорту не включаються, бо вони мають різнитися між середовищами, і їх заморожування перенесло б шлюзи одного середовища в кожну робочу копію. allPlugins: true розширює набір до всіх сокетів плагінів. Належність визначається для кожного підключення, а не для кожного сокета, тож сокет керування з одним підключенням перетворення міток і одним підключенням вердикту за замовчуванням додає лише перше.

Кожне значення заморожується з його ефективним значенням — тим, що виходить після злиття конфігурації машини з власною конфігурацією проєкту, — тож прив’язка, яка сьогодні походить лише з конфігурації машини, записується в проєкт і переноситься разом із ним. Інструментальні налаштування для всієї машини, зокрема політика довіри реєстру, не є критичними для збирання й залишаються там, де є. Повторне заморожування незміненої конфігурації перезаписує ті самі байти, тож клієнт може пропонувати його вільно: другий виклик залишає документ, який тримає читач, точно таким, яким він був.

Що повідомляє зміна плагіна

Усі чотири запити щодо плагінів за замовчуванням виконують запис, і поділяються вони за тим, що записують: два змінюють файл конфігурації, а два створюють документи в робочому просторі. Два з них — додавання та генерація — приймають dryRun, який виконує все інше, що робить запит, і нічого не записує. Читайте власний звіт відповіді про те, куди потрапила зміна, а не виводьте це із запиту — для одного з них запит, що нічого не каже про область дії, означає найширше охоплення.

І додавання, і видалення містять scope, і його виведено з файлу, до якого розв’язався запис. configFile — це той файл, machineWide вказує, чи це той файл, через який розв’язується кожен робочий простір на цій машині, а workspaceRoot називає робочий простір, над яким було відкрито цей сеанс, тож відповідь, обмежена робочим простором, каже, який саме це був простір. machineWide визначається за розв’язаним файлом, а не за тим, що просив запит, і саме це не дає відповіді описати зміну на рівні всієї машини як локальну.

🔴 Додавання типу cli, яке не називає ні global, ні workspace, реєструє команду для всієї машини. Розширення команд — це інструментарій рівня машини, тому без перевизначення воно записується в глобальний файл конфігурації, через який розв’язується кожен робочий простір на цій машині, — і зареєстрована ним команда стає командою верхнього рівня aggrega для кожного проєкту на цій машині, зокрема для проєктів, яких ніхто в цьому сеансі не називав. Додавання provider, governance, linter або importer працює навпаки: вони формують збірку одного проєкту, тож без перевизначення потрапляють до власного .aggrega-config.yaml цього проєкту. Видалення дотримується того самого правила для тих самих типів. Надішліть workspace: true, щоб залишити розширення команд локальним, або global: true, щоб винести будь-яке з інших до спільного файлу; надсилання обох відхиляється. scope у відповіді є авторитетним твердженням у будь-якому разі, і клієнтові слід показати його, перш ніж діяти на основі результату.

Додавання називає те, що було додано, і рівно одне з трьох полів вказує, що це було. type повторює тип, для якого додано запис, а далі: identity містить голу ідентичність сутності із закріпленою версією для прив’язки governance, linter або importer; uri містить адресу артефакту плагіна oci:// разом із capability, яку він тепер обслуговує, для прив’язки provider; а reference містить закріплене посилання, чиї команди було зареєстровано, для встановлення cli. Отже, викликач зчитує, яку прив’язку було додано, з відповіді, а не виводить це заново з надісланого типу. Видалення повторює type і query поряд зі своїм scope і більше нічого — про запис, якого вже немає, більше нічого повідомити.

Додавання також містить written, а за dryRun — content. written — це те, за чим розгалужується клієнт: true вказує на файл конфігурації, що тепер є на диску і який клієнт може відкрити, а за dryRun воно false, і content натомість містить документ конфігурації, який створив би запис. Обидва ніколи не мають значення одночасно, а файл, для якого призначено content, — це scope.configFile, тож ніщо у відповіді не містить другої копії цього шляху — що тут важливо, бо файл прив’язки global — той, через який розв’язується кожен робочий простір на цій машині.

Плагін без опублікованої версії відхиляється, а не прив’язується без закріплення. Додавання розв’язує запит до одного плагіна й закріплює його найвищу опубліковану версію, тож запис, який воно створює, містить версію. Плагін, репозиторій якого не публікує жодної відповідної версії, відхиляється із зазначенням його назви, а версія, яку відкликало відкликання, якому довіряє цей робочий простір, пропускається на користь наступної нижчої.

Версія, яку називає запит, закріплюється навіть тоді, коли її відкликано, і withdrawn про це повідомляє. query, записаний як <name>:<version>, закріплює цю версію замість найновішої — для всіх типів, окрім provider, який прив’язується лише за назвою й відхиляє версію, — а називання версії і є перевизначенням: якщо оголошення про відкликання, якому довіряє цей робочий простір, її відкликало, вона однаково закріплюється, а відповідь містить withdrawn: true — факт, який aggrega plugin add повідомляє в терміналі рядком retraction:. withdrawn відсутнє в усіх інших відповідях, тож його наявність і є всім сигналом — а його відсутність не є твердженням, що версію не відкликано. Якщо позначки відкликання названої версії не вдалося прочитати, withdrawn відсутнє, а retraction містить unscreened із поясненням причини, як і для додавання без названої версії, що натрапляє на ту саму помилку; додавання без названої версії натомість повідомляє в retraction, до якого висновку дійшла перевірка відкликання щодо обраної ним версії.

Вирівнювання повідомляє, чи змінило воно щось, і саме на це поле слід зважати. changed відрізняє запис від вирівнювання, яке виявило, що записи вже правильні: незмінений файл залишено побайтово ідентичним, тож клієнтові, що тримає цей документ, нічого перезавантажувати, а повторний запуск запиту вдруге не повідомляє про зміни. entity називає файл, hostFunctions містить виведений набір, а commands містить дзеркало як значення, а не як рядок, який друкує термінал, — кожен запис має name, необов’язковий description і flags, де кожен прапорець містить свій name і необов’язкові shorthand, description, type та default. Запис атомарний, тож клієнт, який читає цей файл під час вирівнювання, ніколи не бачить частковий документ.

Генерація заповнює рівно одну половину своєї відповіді, і власний dryRun відповіді вказує, яку. За замовчуванням сутності записуються, а notices містить те, що генерація повідомила про виконані записи. За dryRun нічого не створюється й не змінюється: documents містить кожну згенеровану сутність як path, для якого вона призначена, та її content, тож клієнт може помістити їх у власну модель документів, де їх видно до збереження і де їх можна змінити або відкинути. Обидві половини ніколи не заповнені одночасно, тож те, який спосіб доставки виконано, можна зчитати з відповіді, а не з того, що було запитано.

Те, куди запит щодо плагіна ЗАПИСУЄ, завжди лежить усередині робочого простору, який цей запит назвав; те, що він ЧИТАЄ, визначається для кожного поля окремо. Абсолютне призначення, призначення, що виходить за межі кореня, і призначення, що виводить за його межі через посилання, відхиляються, а не розв’язуються, — тож генерація не може створити сутності в дереві, над яким ваш сеанс ніколи не відкривався, хоч би що вона надіслала. Шлях, який запит лише читає, — окреме питання, на яке відповідають поле за полем, а не одним правилом для всіх: aggrega/pluginGenCatalog читає модуль і його накладку звідки завгодно, де ви їх вибрали, бо зібраний вами модуль лежить у вихідному каталозі вашого інструментарію, і відмова читати його там відмовила б в операції, у якій уся її мета. aggrega/pluginSync читає свої два шляхи всередині робочого простору, бо цей запит стосується файлу, який робочий простір уже містить. Наведені вище запити пошуку розташування приймають абсолютний шлях знову з іншої причини — це документ, який клієнт уже тримає відкритим, названий у будь-якому написанні, яке він має.

Запит, у якому бракує чогось потрібного операції, відхиляється із зазначенням поля, яке слід надіслати. Додавання або видалення без type чи query; додавання provider без capability або governance без role; додавання cli без acceptCapabilities; вирівнювання без entity чи plugin; генерація, що називає обидва режими вибору або жодного, чи без overlay або outputDir. Кожен такий запит повертається зі стандартним кодом invalid-params, і повторна спроба нічого не змінює, доки не зміниться запит. Видалення, запит якого не збігається з жодним записом, теж відхиляється із зазначенням типу, запиту та файлу, у якому шукали, — це стан конфігурації, а не запиту, тож виправляти, можливо, доведеться будь-що з двох.

Ніщо не запитується інтерактивно, і те єдине рішення, про яке спитали б людину, надходить натомість як поле. Термінальна команда питає того, хто спостерігає, чи приймає він оголошені можливості плагіна-розширення команд. За цим потоком ніхто не спостерігає, тож отримати й надіслати acceptCapabilities — справа викликача, а запит без нього відхиляється із зазначенням того, що слід надіслати, а не встановлює плагін на підставі згоди, якої ніхто не давав. Демон, запущений без засобів для встановлення розширення команд, одразу відхиляє додавання cli, а не повідомляє про успіх, який нічого не встановив.

Які види можна пропонувати автору

aggrega/getSchema без kind відповідає, які види ви можете назвати, і відповідає у двох обсягах, бо клієнтові для різних завдань потрібні різні. Читайте той, про який ви питаєте.

kinds — це кожен токен, на який відповідає бінарний файл. entityKinds — це набір видів, документи яких пише автор. Широкий список містить проміжне представлення, lockfile, конфігурацію робочого простору та контракти сокетів плагінів поряд із видами, які ви створюєте, — кожна з них справжня схема, але не документ, файл якого хтось пише. Тож широкий список — той, з якого слід налаштовувати прив’язку схем у редакторі, а вузький — той, з якого слід будувати засіб вибору. Засіб вибору, побудований із широкого списку, пропонує значення, яких не приймає жодна схема для створення документів, і автор натрапляє на відмову лише після того, як вибере одне з них.

Вузький набір вужчий і за види сутностей, і жодна схема не каже, які саме. Вид, що належить платформі й чий вміст пишеться всередині документа іншого виду, не є документом, який варто пропонувати автору для початку. Workload — саме такий вид: вміст workload пишеться в полі workload: сутності Recipe або FeatureRecipe, або безпосередньо, або з файлу, який це поле імпортує, тож окремого документа workload, до якого можна звернутися, немає — див. поверхню створення Workload, щоб дізнатися, куди йде цей вміст. Його схема фіксує apiVersion і kind так само, як схема виду, що створюється автором, бо саме це дає змогу перевіряти вміст там, де він розміщений; фіксовані значення ідентифікують вміст, але не роблять його адресованим. Тож вони не є ознакою того, що вид можна створювати як чернетку. Відповідь містить entityKinds, а байти схеми — ні.

Кожен запис entityKinds містить обидва написання, потрібні клієнтові, і жодне не виводиться з іншого. kind — токен у нижньому регістрі з дефісами: надсилайте його назад як kind до цього методу або до aggrega/scaffoldEntity. documentKind — значення, яке сам документ містить у полі верхнього рівня kind:. Для виду, назва якого складається з кількох слів, вони відрізняються не лише регістром: жодними перетвореннями featurerecipe не отримати FeatureRecipe. Беріть кожне із запису, а не виводьте одне з іншого, і клієнтові не залишиться жодного відображення, яке треба підтримувати.

Кожен запис також повідомляє, які операції приймають документ цього виду, тож елемент керування, що пропонує ці операції для документа, пропонує лише ті, що не відмовляють йому через його вид. acceptedBy містить три булеві значення, кожне присутнє в кожному записі, і кожне стосується документа названого виду окремо — за його шляхом або, для перегляду, за його іменем — без нічого іншого, надісланого поряд. singleEntityValidation — чи перевіряє aggrega validate <path> документ цього виду, а не відмовляє йому, називаючи область усього каталогу або сутності Release, яка його перевіряє. publication — чи публікує його aggrega/publishEntity, що називає лише цей документ: для Plugin це false, бо його публікація також прив’язує виконуваний файл, який запит називає в plugin, тож запит, що називає лише документ, відхиляється; для Manifest і Release це false, бо жоден із цих видів не публікується. inspectionByName — чи розв’язує aggrega/entityDefinition ім’я до сутності цього виду, де ім’я надсилається так, як воно пишеться там, де одна сутність посилається на іншу: Plugin як <pluginType>/<name>, а Recipe або FeatureRecipe як <capability>/<name> або лише за іменем, якщо це ім’я оголошує лише одна можливість. true означає, що операція не відмовляє документу через те, що він цього виду; вона все ще може відмовити конкретному документу через те, що в ньому написано.

Не тримайте власного списку. Які види існують — властивість бінарного файлу, з яким ви взаємодієте, тож список, записаний у клієнт, збігається в день написання й перестає збігатися в день, коли додано вид, — і тоді автор бачить, що його виду немає саме в тому елементі керування, який мав його пропонувати. Запитуйте, і відповідь відповідатиме бінарному файлу.

Обидві половини надходять разом і лише тоді, коли ви не називаєте жодного виду. Запит, що називає вид, відповідає схемою цього виду й не містить жодного списку, тож із відповіді видно, яке питання ви поставили. Токен, якому не відповідає жодна схема, відхиляється з усім допустимим набором у повідомленні, зі стандартним кодом invalid-params, тож одруківка — це запит, який слід виправити, а не питання до людини.

Він відповідає й у робочому просторі, де нічого немає. Словник скомпільовано в бінарний файл, тож для цього не потрібні ні документ, ні lockfile, ні каталог — а саме в такому робочому просторі перебуває автор, що починає свій перший документ.

Що дає відповідь на запит заготовки

Цей розділ стосується створення чернетки. Інша форма методу записує готовий до запуску приклад, і її відповідь описано разом із методом вище.

aggrega/scaffoldEntity повертає текст. skeleton — це YAML для названого вами виду: кожне поле, якого вимагає схема цього виду, у порядку, в якому схема їх оголошує. Поле, яке схема закріплює за одним фіксованим значенням, надходить заповненим — apiVersion і kind ви помітите першими, — metadata.name містить надіслане вами name, а кожне інше обов’язкове значення надходить як заповнювач, типізований відповідно до оголошеного там схемою: порожній рядок, нуль, false, порожній список, порожнє відображення. kind повторює токен, для якого виведено документ, тож клієнт із кількома незавершеними запитами співвідносить відповідь за самою відповіддю, а не веде власну кореляцію.

Він нічого не записує, і саме це слід враховувати під час проєктування. Метод не створює файлу, не вибирає шляху й не торкається жодного каталогу. Ви отримуєте документ, який треба записати, а не записаний документ, — тож редактор поміщає текст у новий незбережений буфер, який автор може прочитати, змінити або відкинути, а момент, коли новий файл потрапляє на диск, лишається там, де буфер та історія скасувань. Жоден інший запит не бере цей документ і не розміщує його кудись від вашого імені; вирішувати, де житиме новий документ, — справа редактора.

Він нічого не розв’язує і нічого не потребує від робочого простору. Документ виводиться зі схем, які містить бінарний файл, тож метод не звертається ні до реєстру, ні до мережі, не консультується з каталогом і не читає жодного файлу. Він відповідає однаково в будь-якому робочому просторі, зокрема в порожньому каталозі, де ще немає жодного документа Aggrega, — а це саме той робочий простір, у якому перебуває автор, що починає свій перший документ, і де більшість інших методів тут спершу вимагали б документ або lockfile.

Той самий запит дає ті самі байти, хоч би де його поставили. Документ створюється одним обчисленням, спільним з іншими поверхнями, що пропонують цю можливість, тож редактор і асистент, яких попросили про той самий вид і ту саму назву, показують авторові той самий початковий текст.

Заготовка містить поля, яких вимагає її вид, і вона не є готовим документом. Вона містить обов’язкові поля і нічого більше: необов’язкове поле, яке вам потрібне, ви додаєте самі, а кожен заповнювач — це значення, яке ще треба надати. Заповніть заповнювачі, а тоді запустіть aggrega/validate для буфера. Для сутності каталогу того виду, який aggrega validate перевіряє як окрему сутність, цей метод називає кожен заповнювач, який ще треба надати, кожен за його ключем і з тим, що він приймає, за тим самим прочитанням, яке команда застосовує до збереженого файлу, — включно із заповнювачем, який схема допускає порожнім; найчастіше вам трапляться capability та implements у чернетці сутності Recipe або FeatureRecipe. Для будь-якого іншого виду він перевіряє буфер на відповідність схемі його виду, тож заповнювач, який схема не допускає порожнім, — скажімо, версія, — повертається як знахідка цієї схеми, а той, що схема допускає порожнім, жодної знахідки не викликає. У розділі Перевірка в реальному часі описано запис, у вигляді якого надходить кожен заповнювач.

Що повідомляє відповідь на імпорт

aggrega/import перетворює джерело, написане для іншого інструмента, на чернетки документів Aggrega, і записує їх — на відміну від описаного вище scaffold, який повертає вам текст. written називає кожен файл, що потрапив на диск, відносно outputDir; files містить кожен файл, який записує запит, разом із його content, незалежно від того, чи його було записано, — кожну чернетку, створену імпортером, а потім запис про те, що записав імпорт, або в режимі sync — що змінює синхронізація. Ці два поля відповідають на різні запитання, тож читайте те, що відповідає вашому: що тепер є на диску чи що було створено.

Ви обираєте, куди потраплять чернетки, або залишаєте це кореню робочого простору. outputDir необов’язковий, як і aggrega import --output-dir та output_dir інструмента import асистента: запит, що не називає каталогу, створює чернетки в корені робочого простору — там, куди пише aggrega import, коли йому не задано місця призначення, хоч би де він запускався, — а запит, що називає каталог, створює чернетки в ньому. Названий каталог — це шлях усередині робочого простору, а відносне значення розв’язується відносно кореня робочого простору, а не відносно каталогу, у якому випадково перебуває демон. source, яке ви перетворюєте, — інший випадок, і воно так не обмежується: ви самі вибрали цей файл чи каталог, тож його читають там, де він є, і це не змінює місця, куди потрапляють чернетки. Якщо каталогу не існує, його буде створено. У режимі dryRun нічого не записується, а кожна чернетка все одно називає шлях, для якого вона призначена, відносно outputDir, який називає відповідь, — каталогу, який ви надіслали, або кореня робочого простору.

Запит ніколи не перезаписує сутність Aggregate, що вже є в outputDir. Aggregate — це документ, який автор і далі редагує після створення чернетки, тож запит, одна з чернеток якого потрапила б на файл, що читається як Aggregate, відхиляється із зазначенням чернетки та розташування Aggregate, і нічого не записується — так само й у режимі dryRun, оскільки пробний запуск відхиляє те, що відхиляє запис. Натомість надішліть sync, щоб оновити його відповідно до джерела, або назвіть інший outputDir, щоб створити чернетку поруч. Будь-який інший файл, що вже є за шляхом чернетки, перезаписується, а файл, створений попереднім імпортом, якого цей імпорт не створює, залишається на місці. Кожен запит, що створює хоч якусь чернетку, також записує .aggrega-import.json в outputDir — запис про те, що записав імпорт: target, який було надіслано, якщо його надіслали, знімок каталогу, який було прочитано, якщо його прочитали, і кожен створений файл, а в створеній сутності Aggregate чи Release — кожен ключ на будь-якій глибині з дайджестом записаного там тексту, решту ж створених файлів записано цілком, — і files та written містять його після чернеток. Це JSON, тож ніщо, що читає YAML-документи робочого простору, його не читає; sync, як і aggrega import --sync, читає його, щоб оновити чернетки відповідно до їхнього джерела. sync без target створює чернетки для цілі, яку називає запис, тобто для сутності Manifest, створеної попереднім імпортом; із надісланим target — для нього, і тоді запис називає його. Записана ціль, до якої не прив’язується жодна сутність Recipe в каталозі, відхиляється так само, як надіслана, і відмова повідомляє, що це записана ціль. Оскільки створена сутність Release записується ключ за ключем, середовище, яке її автор записує там, де імпорт залишив для нього коментар, є ключем, записаним автором, і синхронізація залишає його байт у байт.

Надішліть sync, щоб оновити те, що попередній імпорт створив в outputDir, відповідно до джерела, змінюючи лише те, що записав імпорт. Кожну частину оцінюють трьома способами: що, згідно із записом, імпорт востаннє там записав, що є на диску і що джерело створює зараз. Частина, яку джерело залишило такою, якою імпорт її востаннє записав, лишається точно такою, як на диску, незалежно від того, чи редагував її автор. Частина, яку джерело змінило, записується наново, частина, яку воно прибрало, видаляється — створений файл видаляється цілком, — а частина, яку воно додало, додається поруч із частинами, що оточують її в чернетці, і все це лише там, де вміст диска збігається з тим, що імпорт востаннє записав, і не містить нічого доданого автором. Усе інше лишається байт у байт: ключ, який автор додав будь-де, — параметр, сутність Feature, зокрема й під створеним екземпляром Component, інша сутність Component, — коментар, записаний не безпосередньо над створеним ключем, і кожен файл, якого немає в записі. Синхронізація в каталог, де немає запису й нічого немає за шляхами чернеток, записує всю чернетку, як і запит без sync.

drift — це те, що синхронізація оновила, і це відповідь на запитання «чи змінилося джерело». Він перелічує кожну частину, яку змінила синхронізація, — або, у режимі dryRun, кожну частину, яку вона змінила б, — у порядку, у якому їх називає чернетка, кожну як change (added, removed або changed), file — створений файл, у якому вона міститься, відносно outputDir, і key — ключі, що ведуть до неї у створеній сутності Aggregate чи Release, у вигляді списку, тож ключ із крапкою лишається одним елементом; key порожній там, де частина — це весь файл, і саме так називається створений файл, який синхронізація видаляє. aggrega import виводить ті самі елементи у стандартний потік помилок як <change> <key> in <file> або <change> <file>, а його код завершення з --sync --dry-run показує, чи змінилося джерело; ця поверхня не має коду завершення, тож надішліть sync із dryRun і перевірте, чи порожній drift. drift — порожній список для запиту, що не є синхронізацією, для синхронізації, узгодженої з джерелом, і для синхронізації, імпортер якої не зміг завершити роботу. У режимі sync files містить кожен створений файл, який змінює синхронізація, із вмістом, який вона йому надає, а потім запис, якщо змінюється й він, а written називає ті, що потрапили на диск, — тож узгоджена синхронізація повертає обидва поля як порожні списки. Створений файл, який синхронізація видаляє, називається в drift і в жодному зі списків: його елемент removed із порожнім key — єдиний опис цього файлу у відповіді, а в режимі dryRun він називає файл, який видалив би запис.

Синхронізація ніколи не переписує те, що написав автор, а натомість відмовляє. Синхронізація, яка змінила б чи видалила частину, відредаговану автором, додала б частину там, де автор уже її написав, або видалила б частину, що містить щось додане автором, відхиляється із зазначенням кожної такої частини та причини в окремому рядку, тими самими словами, що й aggrega import --sync, — <file> <key>: <why> або <file>: <why> для цілого файлу, — і нічого не записується; коментар, записаний безпосередньо над створеним ключем, редагує цей ключ. Синхронізація поверх сутності Aggregate, якої немає в жодному записі, відхиляється із зазначенням Aggregate і запису, так само як і синхронізація, запис якої неможливо прочитати, оскільки без запису її частини неможливо відрізнити від авторських. Обидві відмови повертаються як помилка invalid-params, так само й у режимі dryRun, і називають sync. Узгодьте кожну названу частину вручну або поверніть те, що там записав імпорт, і надішліть запит знову.

🔴 halted: true — не помилка, і сприймати її як помилку — саме та хиба, від якої слід застерегтися під час проєктування. Імпортер, який не зміг перетворити все, однаково створює чернетки того, що зміг: відповідь містить ці чернетки, written називає їх, а diagnostics повідомляє, що пропущено. Це найкорисніша відповідь, яку дає операція, і вона надходить як результат, а не як збій, саме для того, щоб ви могли показати автору обидві половини. У режимі sync така сама відповідь нічого не записує — files, written і drift порожні, — бо часткова чернетка виглядала б як джерело, що прибрало кожну частину, до якої імпортер не дійшов. Джерело, яке імпортер узагалі не зміг прочитати, — інший випадок, і воно повертається як помилка.

Кожне діагностичне повідомлення містить severity і message, а також code, якщо імпортер його призначив. Розгалужуйте логіку за code, коли потрібно реагувати на конкретну умову, а читачеві показуйте message; severity береться з того самого набору, у якому звітує кожен сокет плагінів, — halt, warn, info, — тож halted є підсумком елементів, а не окремим судженням. files, written, drift, diagnostics і decisions завжди є масивами — порожніми, а не відсутніми.

decisions показує, де імпорт робив припущення. Він містить один запис для кожного вузла джерела, який зіставив імпортер, у порядку імпортера і точно так, як імпортер його повідомив: sourceNode — id, type і paramsSummary вузла; candidates — кожна сутність Component каталогу, яку імпортер розглядав для нього, як componentName, score, tier і signals — внесок кожного з її сигналів у table, category, domainLabels, shape і name; chosen — обрана ціль target, режим mode, у якому її записано, — reference на наявну сутність Component або draft, — і tier вибору; rationale — чому; і swapHint — як вибрати інакше. candidates відсутній, якщо імпортер не розглядав жодного кандидата, chosen — якщо він не зробив вибору, а rationale і swapHint — якщо він їх не написав. Кожне значення належить самому імпортеру — як він оцінює кандидата і де пролягають його рівні, вирішує він, — тож показуйте запис як його пояснення зіставлення, а не як вердикт. Рішення надходять і під dryRun, і коли halted має значення true: припущення часткового імпорту — саме те, що потрібно авторові, який його перевіряє, а імпортер, що не повідомляє жодного, відповідає порожнім списком. Якщо ви показуєте їх як текст, aggrega import уже формулює одне рішення як mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, де оцінка — це оцінка найкращого кандидата.

Формат розпізнається за джерелом, якщо ви його не вказали. Розпізнавання використовує сигнатури, які оголошують імпортери, — і з каталогу робочого простору, і базові імпортери компілятора, — і які записує сутність Plugin кожного імпортера: синтаксис, у якому читається джерело, імена файлів, до яких застосовується сигнатура, і шляхи, які розібране дерево мусить або не мусить містити, — тож сам демон не знає жодного формату, а формат нового імпортера розпізнається без жодних інших змін. Виявлення читає лише надіслане вами джерело — у каталозі лише файли, які вибирають шаблони файлів сигнатури, — і не звертається до мережі, розбираючи кожен прочитаний файл парсером, який каталог робочого простору надає для синтаксису, — або, для синтаксису, для якого каталог не надає парсера, тим, що має сам компілятор, — по одному разу для кожного синтаксису, у якому його читає сигнатура, що застосовується до його імені; потім імпортер читає джерело тим самим парсером. Сигнатура, що не оголошує шаблону файлів, застосовується до надісланого вами файлу хоч як би він називався і до жодного файлу каталогу; сигнатури імпортерів Langflow, Flowise і n8n саме такі й читають JSON, а сигнатура імпортера Dify читає YAML, тож розпізнавання окремо надісланого файлу читає його як JSON і як YAML, для чого парсер у каталозі робочого простору не потрібен: компілятор має парсери JSON і YAML, а парсер, наданий каталогом, використовується замість них. Джерело, якому не відповідає жодна сигнатура, відхиляється із запитом format і переліком форматів, які оголошують імпортери, — або, для каталогу, із запитом одного з його файлів, надісланого окремо, чи format, імпортер якого оголошує шаблони файлів, і переліком лише таких форматів, — за умови No importer recognises the source (Жоден імпортер не розпізнає джерело); джерело, якому відповідають сигнатури кількох форматів, відхиляється з їх переліком за умови More than one importer recognises the source (Джерело розпізнає більше ніж один імпортер). data кожної відмови містить code і shortCode її умови, тож клієнт запитує формат за кодом, а не за текстом. Жоден формат не вгадується, бо вгаданий формат визначає не той імпортер і дає впевнену нісенітницю. format у відповіді — той, що було використано, виявлений або вказаний, тож клієнт, який його пропустив, дізнається, що отримав.

Надісланий вами каталог читається у файли, які називає його імпортер, а каталог, який неможливо прочитати, — це помилка. Якщо source називає каталог, імпортер отримує ті його файли, які вибирають шаблони файлів, оголошені його сигнатурами, за винятком каталогу результатів збирання робочого простору dist/, кожен під своїм шляхом усередині каталогу, у відсортованому порядку, поряд із файлами, які його запис plugins.importer називає в with.sources. Імпортер, що не оголошує шаблонів файлів, каталог без файлів, які вони вибирають, файл каталогу і файл із with.sources з однаковим іменем, а також посилання серед файлів, які читав би імпорт, або на каталог, що веде за межі каталогу, — кожне з цього повертається як помилка з кодом умови, і нічого не записується.

Який імпортер запускається, вирішує робочий простір, а не запит. Формат зіставляється з імпортером, який його оголошує, серед плагінів каталогу робочого простору та базових імпортерів компілятора — з тим, який під’єднує запис plugins.importer у конфігурації робочого простору, якщо він під’єднує один із них, — тож запит не може вибрати модуль чи вказати на модуль на диску. Формат, який не оголошує жоден імпортер, відхиляється з назвою формату, а формат, який оголошують два імпортери, жоден із яких не під’єднано, — зокрема базовий імпортер та імпортер з іншою назвою, що є в каталозі для того самого формату, — відхиляється як неоднозначний, а не визначається довільно.

Основний імпортер, якого ще немає на машині, завантажується один раз — першим імпортом, якому він потрібен. Він надходить із типового реєстру робочого простору, має збігатися з модулем, який публікує випуск компілятора, і перевіряється так само, як pull перевіряє плагін, що його завантажує, — його підпис за політикою довіри цього реєстру та хост-функції, які він використовує, — і зберігається в кеші вмісту робочого простору, що є єдиним, що для нього записується: жодного lockfile і жодного запису про довірені плагіни. Кожен наступний імпорт читає його звідти й не звертається до жодного реєстру. Модуль, який не проходить перевірку, — це помилка з кодом відповідної умови, і нічого не зберігається; модуль, який не вдається завантажити, — робочий простір офлайн, його реєстр недоступний або реєстр його не містить, — це помилка за умовою A plugin’s .wasm is not on this machine (файлу .wasm плагіна немає на цій машині), яка називає імпортер, його версію і те, що розміщує його модуль на машині. Сам запит не називає жодного реєстру, а імпорт, для якого всі потрібні імпортери та каталог, який він читає, уже є на машині, взагалі не звертається до мережі.

Якщо робочий простір не називає жодної теки каталогу, імпорт читає каталог, який публікує його типовий реєстр. Робочий простір, у якому ні workspace.catalog_dirs, ні AGGREGA_CATALOG_DIRS, ні корінь не називають теки каталогу, читає каталог стандартної бібліотеки як один підписаний знімок за адресою catalog/snapshot у своєму типовому реєстрі. Знімок завантажується один раз: його підпис перевіряється за політикою довіри цього реєстру, після чого він зберігається в кеші вмісту робочого простору й читається звідти як тека каталогу, прив’язана до свого дайджесту, і жоден реєстр більше про нього не запитується. Який знімок читає запит: з upgrade — найновіший; інакше той, який називає запис в outputDir, завантажений за дайджестом, якщо машина його не має; інакше той, який робочий простір востаннє завантажив як найновіший; інакше найновіший. Запис, який створює імпорт, називає прочитаний знімок за його дайджестом, тож пізніший запит у той самий outputDir читає той самий каталог. У режимі офлайн запит, якому довелося б завантажити знімок, — це помилка за умовою The workspace is offline and the step needs the network (Робочий простір офлайн, а крок потребує мережі), яка називає, що слід запустити, а upgrade відхиляється незалежно від того, що є на машині, оскільки лише реєстр може сказати, який знімок найновіший. Реєстр, який не публікує жодного знімка, залишає імпорт без каталогу, і запис warn у diagnostics про це повідомляє. Робочий простір, який називає теку каталогу, імпортує відносно неї й не завантажує жодного знімка, і upgrade там нічого не змінює.

Під dryRun нічого не створюється. written порожній, files містить ті самі файли, які створив би запис, — із sync файли, які записала б синхронізація, поряд із drift, який вона б оновила, — і жоден каталог не створюється, тож редактор може показати їх авторові, щоб той зберіг, змінив або відкинув їх. Усе інше, що робить запис, виконується: той самий імпортер працює з тим самим джерелом і повідомляє ту саму діагностику, тож джерело, яке запис відхилив би, відхиляється й тут. Базовий імпортер або знімок каталогу, завантажений під dryRun, зберігається в кеші вмісту так само, як і під час запису, бо отримання того, на чому працює імпорт, — частина його запуску, а не розміщення чернеток.

Шлях, який повертає імпортер, утримується всередині outputDir. Шляхи чернеток надходять від імпортера, а не від вас, тож шлях, що виходить за межі вихідного каталогу, відхиляється і взагалі нічого не записується — навіть чернетки з коректними шляхами. Відмова називає проблемний шлях, і саме це показує вам, що виправляти слід імпортер, а не ваш запит.

На яке питання відповідає кожен запит про сутність

Про сутність вам можуть розповісти чотири запити, і вони не взаємозамінні. Вибір між ними залежить від того, що ви маєте на руках, коли запитуєте.

Ви маєте курсор. aggrega/hover і aggrega/resolve приймають файл і позицію та визначають, яку сутність мають на увазі, з того, що там написано. Вони охоплюють форми посилань, які справді містить документ, — значення extends, тип компонента або функції, implements сутності Recipe, посилання на рецепти в сутності Manifest, два вказівники шляхів сутності Release, ціль uses і власне metadata.name сутності. Використовуйте їх, коли координатою є курсор користувача: користувач читає документ і хоче знати, на що вказує посилання.

Ви маєте ім’я. aggrega/entityDefinition приймає ідентичність безпосередньо. Нічого не потрібно відкривати, позиція не задіяна, і сутність не мусить бути згадана там, де клієнт може її знайти. Використовуйте його, коли користувач ввів ім’я, вибрав його зі списку або перейшов до чогось, ідентичність чого ваш клієнт уже знає, — для наведення спершу треба знайти місце, де написано ім’я, а цієї роботи вам робити не потрібно.

Ви ще нічого не маєте. aggrega/catalogIndex перелічує, що містить робочий простір, з описовими полями для кожної сутності. Використовуйте його, щоб заповнити список вибору, а потім передайте вибране ім’я до aggrega/entityDefinition.

Ви маєте Release. aggrega/releaseClosure відповідає про сутність Release, а не про окрему сутність, і йому присвячено розділ нижче.

Визначення, яке повертає запит за іменем, — це сутність у розв’язаному вигляді, а не така, як її оголошує будь-який окремий файл. Сутність Component або Feature, що розширює базову, повертається з контрактом цієї базової сутності, якого немає в документі, що оголошує її ім’я, — тож відповідь стосується того, чим сутність є, і власноручне читання файлу не дало б вам того самого.

Воно надходить як документ YAML, а не як структура всередині відповіді, і це зроблено навмисно: опора схеми має кілька авторських форм — вміст, виписаний повністю, посилання на спільний документ або маркер, що вміст походить від базової сутності, — і документ відтворює ту, до якої дійшло розв’язання, в авторському порядку ключів. Розбирайте його як документ, якщо вам потрібні його поля; показуйте як є, якщо розміщуєте його на панелі.

Як розрізнити дві відмови за іменем

Ім’я, яке ні до чого не розв’язується, відхиляється, а не отримує у відповідь порожній документ, бо порожня відповідь подала б друкарську помилку як сутність, якій нічого про себе сказати. Є два способи, якими ім’я ні до чого не розв’язується, вони вимагають від читача різних дій, і ви розрізняєте їх за тим, що містить data помилки, а не читаючи повідомлення:

  • У data немає file. Ніщо в робочому просторі не оголошує це ім’я, і жоден рівень каталогу його не розв’язує. Майже завжди виправляти слід запит — друкарська помилка або ім’я з каталогу, якого цей робочий простір не має на своєму шляху пошуку.
  • У data є file. Документ робочого простору таки оголошує це ім’я, але каталог усе одно нічого для нього не розв’язав. Сутність записано, і щось її відхилило, — це стан робочого простору, який виправляє людина. Якщо рівно один документ, що його каталог прочитав і відхилив, оголошує це ім’я (звичайна причина), повідомлення починається з цієї відмови, викладеної один раз: її категорія і короткий код, документ за шляхом, яким його повідомлено, і що з ним не так, наприклад рядок і обмеження, яке він порушує; далі зазначається, що файл було пропущено під час завантаження, і перелічуються інші файли, які завантаження відхилило. Інакше повідомлення називає документ, що оголошує ім’я, перелічує файли, які завантаження відхилило, і пояснює, звідки цей робочий простір читає локальні сутності та що змінити, щоб документ було прочитано, — пояснення, яке пропускається, коли ім’я оголошує відхилений документ, бо цей документ уже лежить там, де читає каталог.

Обидві мають код entity-not-resolvable, тож розгалужуйтеся за наявністю file, а не за кодом.

Запит про координату

Ви маєте посилання на реєстр. Надішліть його як name запиту aggrega/entityDefinition, і відповіддю буде сутність, опублікована за цією координатою, у тій самій формі результату, що й для імені, плюс published, заповнена з того, що було опубліковано, а не з того, що розв’язав каталог:

  • definition — документ сутності точно в тому вигляді, в якому його опубліковано. Координата, сутність якої опубліковано з оголошеними нею файлами, містить архів, і документ розпаковується з нього; координата, сутність якої не оголошує жодного файлу, містить свій документ без змін, а сутність Plugin читається з її маніфесту, а не з виконуваного файлу, опублікованого разом із нею. Успадкування не застосовується.
  • authoredLength — довжина цього документа, бо визначення тут є авторським документом, а не відтворенням розв’язаного.
  • file порожнє, бо сутність, прочитана з реєстру, не має на цій машині документа, який можна назвати.
  • publishScope пропущено: ви вже маєте координату, а саме там сутність і опубліковано.
  • published — те, що було прочитано, і воно присутнє в цій відповіді й у жодній відповіді за іменем: reference; archive — чи були її байти архівом, з якого розпаковано документ (false, якщо координата містила сам документ); mediaType, який оголошує маніфест; і manifestDigest цього маніфесту, який можна надіслати після @ замість тегу, щоб знову прочитати точно ті самі байти.

Запит звертається до реєстру, який називає посилання, з обліковими даними користувача, від імені якого працює цей демон, і з мережевою позицією цього робочого простору, тож робочий простір в автономному режимі його відхиляє. Отримані байти перевіряються за дайджестом, який записує для них власний маніфест артефакту, і ні за чим іншим — підпис не перевіряється, про відкликання не повідомляється, — і нічого не записується. Посилання, яке не вдається прочитати, відхиляється з entity-not-resolvable, і повідомлення починається з короткого коду умови, що пояснює причину, — тих самих умов, про які повідомляє aggrega inspect, — і закінчується тим, що з цим робити. Посилання, яке не називає репозиторію або не містить ні тегу, ні дайджесту, є некоректним запитом і відхиляється як invalid params.

Замикання — це не граф

aggrega/irGraph і aggrega/releaseClosure виводяться з того самого розв’язання тієї самої сутності Release і відповідають на різні запитання. Клієнт, який уже отримує граф, цілком може припустити, що має й замикання, але це не так.

Граф показує, що розгортає Release, — його вузли, межі, у яких вони перебувають, що з чим з’єднано, а також значення й вкладення, які несе кожен вузол. Це картина.

Замикання показує, що було залучено для його побудови і в яких версіях. Кожна сутність, до якої доходить Release, незалежно від того, чи стала вона вузлом; спільні документи, на які спираються ці сутності; і плагіни, що формують вивід. Це специфікація матеріалів.

Жодне з них не можна відновити з іншого. Сутність може бути досягнута, так і не з’явившись як вузол, — сутність Recipe, на яку Manifest відображає тип компонента, досягається кожною збіркою і не є вузлом у жодній із них, — а вузол не несе версії, до якої розв’язався його тип. Тож читач, який питає «чому змінилася ця версія?», «на що вплине зміна цього спільного документа?» або «від чого насправді залежить ця сутність Release?», питає про замикання, а читач, який питає «що розгортає ця сутність Release?», питає про граф.

Чого не робить запит замикання. Він нічого не рендерить і не публікує нічого з того, що знаходить. Зокрема, він не видає попередження про дрейф і жодної рекомендації рендерингу: вони належать запиту, який їх запросив, а публікація замінює цілий шар діагностики, тож перелік, який публікував би, стер би те, що запит графа вже показав користувачеві. Запитуйте граф, коли потрібен вердикт щодо дрейфу. Єдине, що він таки публікує, — не його власна знахідка: запит, який виявляє, що lockfile зник, відкликає попередження про дрейф, що на ньому ґрунтується, хоч би який це був запит, — див. Відстеження lockfile.

Йому потрібен lockfile, як і графу. Версії, які повідомляє перелік, — це ті, до яких розв’язалася ця сутність Release, а робочий простір, який ніхто не підготував, ще їх не розв’язав. Перелік, створений без нього, повідомляв би те, що каталог випадково містить сьогодні, а це інше запитання, ніж те, від чого залежить ця сутність Release. Відмова називає lockfile і Release, тож клієнт може одразу запропонувати aggrega pull --release <release>.

kind у записі замикання присутній лише там, де він відомий. Посилання збирається з певної позиції в документі, і одні позиції вказують, на який вид вони посилаються, а інші — ні. Поле повідомляється там, де місце посилання його зафіксувало, і пропускається там, де ні, а не вгадується з форми імені. Воно повідомляється як слово, яке автор пише на початку документа, — те саме слово, яке для того самого запису використовує кожна поверхня, що повідомляє замикання.

Те саме слово запитує той самий документ і деінде. aggrega inspect <release> --closure відповідає на це запитання в командному рядку, а режим release інструмента describe відповідає на нього через протокол інструментів асистента. Усі три виконують одне розв’язання над сутністю Release, тож не можуть розійтися в тому, від чого залежить Release. Див. aggrega inspect, розділ «Замикання залежностей».

Модель кешу

Операції керуються кешем: викличте aggrega/validate для файлу перед hover / completion / resolve / diagnostics для нього. Цей початковий виклик не потребує сутності Release — валідація, яка не називає жодної, однаково розбирає буфер і заповнює кеш, — тож ці операції працюють і в робочому просторі, де немає Release, яку можна назвати. Кеш розбору звіряється з часом зміни кожного файлу на диску під час кожного читання, тож зовнішні зміни (збереження в редакторі, git checkout) підхоплюються автоматично — aggrega/invalidate від редактора є оптимізацією, а не вимогою коректності.

Кеш належить робочому простору, який його заповнив. Файл, перевірений в одному робочому просторі, кешується для цього простору, тож про той самий шлях, запитаний в іншому, повідомляється, що його ще не перевірено, а не дається відповідь із запису першого. Саме це не дає запитанню про другий робочий простір ні відповісти хибно, ні позбавити перший його прогрітого стану, — і aggrega/invalidate так само очищає лише той робочий простір, який називає.

Запит діагностики під час виконання валідації

Валідація заповнює дві речі щодо файлу — розбір, який вона передає іншим операціям, і знахідки, про які вона повідомляє, — і заповнює їх з невеликим інтервалом. aggrega/diagnostics — єдиний запит, який читає обидві: йому потрібен розбір, щоб знати, що на запит про цей файл він може відповісти, а відповідає він зі знахідок. Тож запит, що надійшов між цими двома моментами, вирішував би, що може відповісти, тоді як відповісти ще нічим.

Натомість він чекає. Надішліть aggrega/diagnostics для файлу, який саме зараз перевіряється, і відповідь надійде, коли ця валідація завершиться, разом із тим, що вона знайшла. Для файлу існує одна правильна відповідь незалежно від часу, і саме її ви отримуєте — це ніколи не порожній список для файлу, валідація якого ось-ось повідомить про помилки, а це єдина хибна відповідь, від якої клієнт не може оговтатися, бо ніщо не спонукає вас знову запитати про файл, про який вам сказали, що він чистий. Інші операції за позицією — hover, completion, resolve, findReferences, findImplementations — читають розбір і відповідають із розбору, тож їм нема на що чекати, і вони ніколи не чекають.

Дві речі завершують очікування достроково, і обидві у вас уже є. $/cancelRequest з id цього запиту зупиняє його, і кооперативний aggrega/shutdown зупиняє його. Жодна з них не потребує нічого додаткового в запиті.

І очікування обмежене. Якщо валідація не завершилася в межах відведеного на неї демоном часу, запит відхиляється з кодом validation-in-flight, а не отримує порожню відповідь, — див. Коди помилок. Така відмова означає, що робота, на яку ви чекаєте, справді виконується, тож варто незабаром запитати знову; це не сигнал надіслати ще одну валідацію, яка додала б роботи й ні на що не відповіла б.

Демон, який виконує запити по одному, відповідає на них у порядку надходження, тож ніщо не перекривається і очікування ніколи не виникає. Демон, який виконує їх паралельно, відповідає на ті самі запитання так само, і саме очікування це забезпечує: відповідь, яку ви отримуєте, — це відповідь, яку дав би вам послідовний порядок.

Розміри у відповіді

Відповідь, що повідомляє кількість байтів, повідомляє її двічі: як число і як ту саму кількість, записану текстом. Назва текстового поля — це назва числового поля з доданим Text: size і sizeText, totalSize і totalSizeText, reclaimedBytes і reclaimedBytesText і так далі в усіх відповідях, що містять розмір.

Відображайте текстову форму, а обчислюйте з числом. Сенс надсилати обидва в тому, що клієнтові ніколи не доводиться записувати розмір самостійно: демон записує його тим самим форматувальником, що й командний рядок, тож aggrega cache status і aggrega/cacheStatus показують певний кеш однаково, аж до округлення. Клієнт, який складав би власний текст, розійшовся б із цим уперше, щойно по-іншому визначив би межу.

Текстова форма використовує двійкові одиниці — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB, — тобто ту саму лексику, яку aggrega/cacheEvict приймає в maxSize, тож розмір, прочитаний з однієї відповіді, можна надіслати назад у наступному запиті, не переписуючи його. Для величин, більших за байти, текст має один десятковий знак, тож він називає кількість так, як її хоче бачити читач, а не з точністю до байта; коли вам потрібне точне значення, для цього є числове поле.

Там, де число необов’язкове, необов’язковий і текст, і ці два поля ніколи не бувають присутні наполовину: розмір плагіна у відповіді на публікацію містить pluginSize і pluginSizeText разом або не містить жодного з них.

Кожен запит називає робочий простір, якого він стосується

Надсилайте workspaceRoot у кожному запиті: абсолютний шлях до кореня робочого простору, з яким працює цей запит. Демон не має власного робочого простору й не пам’ятає жодного між запитами, тож відповідь на запит стосується робочого простору, який він назвав, і нічого іншого. Два запити, що називають два робочі простори, отримують дві відповіді, і жоден не бачить сутностей, Releases, кешованих результатів розбору чи діагностики іншого.

Запит, що не називає жодного, відхиляється стандартною помилкою invalid-params із назвою параметра, як і порожнє значення, яке не вказує жодного робочого простору й обробляється як відсутнє. З тієї самої причини відхиляються ще дві форми, кожну з яких названо в повідомленні: відносний шлях, бо корінь робочого простору не має відносно чого бути відносним; і шлях, що не є наявним каталогом, бо робочий простір — це дерево.

Трьом запитам не потрібен workspaceRoot, і кожному тому, що його предмет — не робочий простір. aggrega/getSchema і aggrega/scaffoldEntity відповідають на основі схем, вкомпільованих у запущений виконуваний файл, тож робочий простір нічого не додає до жодного з них — саме це дозволяє обом відповідати в каталозі, який ніхто не готував. aggrega/initialize — третій, і в ньому ви оголошуєте робочий простір, а не працюєте з ним. Інша форма aggrega/scaffoldEntity — запис або перелік готових до запуску прикладів документації — таки працює з робочим простором, і запит до неї називає його, як і будь-який інший.

Кешований стан кожного робочого простору зберігається окремо, і названий другий нічого не коштує першому. Індекс каталогу, кеш розбору й діагностика робочого простору належать цьому робочому простору, тож запитання про інше місце не витісняє того, що редактор накопичив для відкритої кимось теки. Два написання одного кореня — це один робочий простір, тож шлях із внутрішнім . або подвоєним роздільником потрапляє в той самий «теплий» стан, що й його звичайна форма.

Оголошення робочого простору, для якого надсилати діагностику

Діагностика надходить двома шляхами: ви запитуєте її, або демон надсилає її сам. Демон надсилає діагностику лише для робочого простору, оголошеного вами під час рукостискання. Кожен інший запит повертає свої результати у власній відповіді й нічого не надсилає.

Оголосіть його, надіславши workspaceRoot в aggrega/initialize. Це все, що робить оголошення — воно нічого не закріплює, і жоден пізніший запит не обробляється відносно нього.

Причина такого обмеження — у призначенні надісланої діагностики. Надсилання підтримує актуальним список проблем редактора, поки хтось друкує, і це саме те, чого не слід робити з відповіддю, яку ніхто не просив побачити: без цього правила запитання про другий робочий простір — наприклад, від іншого інструмента, що спільно використовує демон, — заповнило б список проблем читача результатами щодо файлів, яких він ніколи не відкривав. Обмеження надсилання не пускає запитання одного клієнта до списку проблем іншого.

Поле необов’язкове, і три речі, які ви можете ним мати на увазі, розрізняються:

що ви надсилаєтекуди надсилається діагностикащо повідомляє рукостискання
нічогоробочий простір, над яким запущено процесцей робочий простір
корінь робочого просторуцей робочий простірцей робочий простір
порожній рядокнікуди — жодна діагностика не надсилаєтьсяпорожній корінь

Якщо нічого не надіслати, надсилання діагностики залишається спрямованим на робочий простір, над яким запущено процес, тож клієнт, що нічого не оголошує, отримує діагностику цього робочого простору. Надсилання порожнього рядка — чесне оголошення для клієнта, який не є редактором і не має списку проблем для синхронізації: кожен результат усе одно доходить до нього у відповіді на запит, що його породив.

Оголошений робочий простір визначається точно так само, як і названий у запиті, тож оголошення з відносним шляхом або шляхом, що не є каталогом, відхиляється під час рукостискання, а не залишає надсилання спрямованим у неочікуване місце.

Корінь робочого простору й активна сутність Release

Демон визначає кожен робочий простір, який називає запит, так само, як його визначає кожна команда aggrega, а в розділі Конфігурація описано, що закріплює корінь і в якому порядку. Для клієнта важливі два наслідки. Файл .aggrega-config.yaml без блоку workspace: нічого не закріплює: він і далі додає свої налаштування, але голий файл налаштувань не може перетворити кожен батьківський каталог на корінь робочого простору. А коли нічого не закріплює корінь, використовується робочий каталог — демон запускається, і операції просто нічого не знаходять, а не відмовляються виконуватися.

Процес також запускається над робочим простором — з --workspace-root або підіймаючись від свого робочого каталогу, — і це визначення робить дві речі й жодних інших: воно задає розмір пулу робітників, що є властивістю процесу, а не будь-якого запиту, і воно є типовим оголошенням для надсилання діагностики. Жоден запит не отримує відповіді щодо нього.

Конфігурація так само є тим самим каскадом, який читає кожна команда, і його описано в розділі Конфігурація. Демон додає лише те, що прочитання каскаду для кожного робочого простору виконується один раз, коли цей робочий простір уперше названо, і повторно використовується для кожного наступного запиту щодо нього. Файл конфігурації, який прочитав би цей каскад і який є посиланням, що веде за межі робочого простору, — власний .aggrega-config.yaml робочого простору або накладка CI поруч із ним, — не читається ні тут, ні в терміналі, і нічого іншого, що налаштував би цей файл, замість нього не читається. Від термінала відрізняється те, що все ж отримує відповідь. Демон, запущений над таким робочим простором, стартує й один раз повідомляє про це у своєму потоці помилок; запит, що називає такий простір, у будь-якому разі отримує відповідь так. aggrega/releaseCandidates і aggrega/catalogIndex — два запити, що перелічують вміст робочого простору, — відповідають на нього, прочитавши його без жодної конфігурації: перелічуються власні документи робочого простору, жоден каталог каталогу не читається, а утриманий файл називається в unreadLinkedFiles, незалежно від того, чи натрапив на нього пошук. Саме за цією назвою клієнт дізнається, що конфігурація робочого простору веде за його межі. Кожен інший запит, що називає цей робочий простір, — збирання, граф, валідація, типова сутність Release, ефективна конфігурація, запис і aggrega/catalogIndex у термінах сутності Release, — залежить від цієї конфігурації, тож його відхилено з помилкою invalid-params, що містить E0321 — read-leads-out-of-workspace у полі data помилки — і речення, яке називає посилання та місце, куди воно веде. Рукостискання також відповідає для такого робочого простору, повідомляючи defaults як його configSource, оскільки жоден файл конфігурації не вніс нічого, чим відповідають переліки. Видаліть посилання або зробіть так, щоб воно вело до файлу всередині робочого простору, і наступний запит прочитає конфігурацію. Під файлами проєкту лежить глобальний рівень: файл, який називає --config у командному рядку, що запустив демон, — для кожного робочого простору, який він обслуговує; інакше файл, який називає змінна середовища AGGREGA_CONFIG, коли її задано; а інакше типове розташування — у Windows aggrega\config.yaml у каталозі, який називає змінна середовища APPDATA, а деінде aggrega/config.yaml у каталозі, який називає XDG_CONFIG_HOME, з резервним варіантом ~/.config/aggrega/config.yaml, — що завантажується, якщо існує. Під ним лежать вбудовані типові значення.

Операції, що діють на сутність Release, приймають її як параметр; демон сам жодної не вибирає. Робочий простір і далі оголошує, на яку сутність Release він указує, і це оголошення читає чотирикроковий каскад: поле конфігурації build.authoring_release, потім файл-маркер .aggrega/active-release, потім евристика «одна сутність Release у робочому просторі», потім резервний варіант лише з Aggregate. Тож маркер, який ви записуєте, має перевагу над евристикою, а маркер, що називає сутність Release, яку не вдається завантажити, переходить до евристики, а не до резервного варіанта. Маркер, що називає сутність Release за межами робочого простору — абсолютним шляхом, шляхом, що виходить за корінь, або через посилання, що веде за його межі, — не читається, якщо конфігурація вашого робочого простору не називає цю сутність Release як build.authoring_release або як ключ workspace.releases: конфігурація є способом дістатися сутності Release, що зберігається поза робочим простором, а маркер — ні. Тоді каскад рухається далі так само, як для маркера, який він не може завантажити, а якщо він ні на чому не зупиняється, trace пояснює причину в рядку маркера, а reason — у своєму реченні про маркер.

aggrega/activeRelease повідомляє, що вибирає цей каскад, і це пропозиція для клієнта, а не налаштування, за яким діє демон. Запитуйте демон, а не читайте вхідні дані каскаду самостійно: поле конфігурації та файл-маркер — це два з чотирьох вхідних даних, тож те, яке з них ви прочитаєте, називає вибір робочого простору лише тоді, коли саме воно виявилося переможним. Найочевидніший випадок — маркер, що називає сутність Release, яку не вдається завантажити: каскад вибирає зовсім іншу сутність Release, а той, хто читає маркер, повідомив би про ту, що не завантажилася.

Каскад виконується тоді, коли ви запитуєте, і не раніше, що має два наслідки, на які варто покладатися. Рукостискання залишається швидким незалежно від розміру дерева, бо не чекає обходу робочого простору. А відповідь стежить за робочим простором: запишіть маркер — за допомогою aggrega/setActiveRelease, який відповідає самим новим вибором, — змініть конфігурацію, додайте чи видаліть файл сутності Release, потім запитайте знову, і ви отримаєте нову відповідь від того самого демона. Зміна сутності Release, з якою ви працюєте, ніколи не потребує перезапуску демона — клієнт надсилає інше значення release у наступному запиті.

Операції, що шукають по всьому робочому простору, а не в одному буфері, — completion, hover, resolve, findReferences і findImplementations — перелічують YAML під коренем робочого простору, і цей перелік враховує .gitignore. Свій внесок робить кожен .gitignore від кореня робочого простору до власного каталогу файлу, причому перемагає найближчий, тож YAML-файл, який ігнорує ваш репозиторій, не пропонується як кандидат на доповнення і не повідомляється як визначення чи посилання. Файл .gitignore, який є посиланням, що веде за межі робочого простору, не читається, тож файл деінде на машині ніколи не вирішує, у яких документах робочого простору виконується пошук. Тому вендорні дерева та згенерований вивід залишаються поза міжфайловими результатами без окремого налаштування виключень, яке треба підтримувати, — а документ, який ви очікуєте знайти, але проігнорували, не з’явиться; це єдиний випадок, який варто перевірити, коли посилання ніби бракує. Components і Features, які completion також пропонує з ваших налаштованих catalog_dirs, — це інше читання: вони походять із цих каталогів у тому вигляді, як їх налаштовано, — тих самих каталогів, які читає збирання сутності Release, коли конфігурація не дає цій сутності Release власних, або, для запиту, що називає сутність Release, власних каталогів цієї сутності, — тож сутності каталогу пропонуються незалежно від того, чи покриває його .gitignore, — за винятком сутності за посиланням, яке веде за межі каталогу, в якому мають залишатися читання каталогу каталогу: така сутність не читається й не пропонується.

Запит, який називає сутність Release, читає каталоги цієї сутності Release — ті самі, що їх читає її збірка в терміналі: власні, якщо конфігурація робочого простору задає їх у workspace.releases, а інакше — catalog_dirs робочого простору. Це стосується aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate і aggrega/lint із зазначеною сутністю Release, aggrega/attachCandidates і aggrega/attachmentContainer, адресованих вузлу графа сутності Release, а також aggrega/connectionAtPosition і запитів, перелічених у наступному розділі, коли вони її називають. Тож один сеанс відповідає щодо кожної сутності Release у робочому просторі, який зберігає окремий варіант каталогу для кожної Release, — кожній з її власного варіанта, і для цього не потрібно надсилати нічого, крім шляху до Release. Запит, що не стосується жодної окремої сутності Release, — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover і resolve без зазначеної Release, а також aggrega/attachCandidates, адресований сутності або набору міток, — читає catalog_dirs робочого простору. Виняток — aggrega/lint, що не називає ні сутності, ні Release, у робочому просторі, який називає Releases у workspace.releases: там він перевіряє весь каталог один раз для кожної сутності Release, щоразу проходячи каталогами цієї Release, як описано в розділі Публікування домовленостей на запит і під час кожного редагування. Див. Власні каталоги для сутності Release.

Відповідь у термінах однієї сутності Release

aggrega/catalogIndex, aggrega/entityDefinition і п’ять запитів, що починаються від позиції курсора, — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences і aggrega/findImplementations — не стосуються жодної окремої сутності Release, і кожен приймає необов’язковий параметр release, який прив’язує його до однієї з них. Це шлях відносно кореня робочого простору, до якого застосовуються ті самі вимоги, що й в інших запитах, які приймають Release; значення, яке не вказує на жоден файл Release або вказує на каталог, відхиляється, а не отримує відповідь у термінах робочого простору, що виглядала б як відповідь у термінах Release.

Що досяжне для сутності Release — для кожного з цих запитів: документи робочого простору в каталогах, які читає її стек, і кожен документ робочого простору, що не лежить у жодному каталозі, — Release, її Aggregate та її Manifest, записані поруч із каталогами. Документ робочого простору в каталозі, який читають лише інші Releases, не входить до її відповіді: його не перелічено, не розв’язано й не запропоновано. Саме це не дає сплутати варіанти однієї сутності, що зберігаються поруч для різних Releases.

  • Перелік. Якщо назвати сутність Release, буде перелічено сутності, які бачить ця Release. Перелічені Features — ті, що оголошують каталоги цієї Release, а документ робочого простору в каталозі, який читають лише інші Releases, пропускається — тож робочий простір, що зберігає окремий варіант однієї сутності для кожної Release, перелічує той один варіант, з яким збирається ця Release, а не всі варіанти поруч. Документ, що не лежить у жодному каталозі, як-от Release, її Aggregate та її Manifest, записані поруч із каталогами, належить до переліку кожної Release.
  • Пошук за назвою. Якщо назвати сутність Release, назва розв’язується через каталоги цієї Release, тож назва, яку оголошують кілька варіантів, розв’язується до варіанта, з яким збирається ця Release. Назву, яку її каталоги не розв’язують, буде відхилено з поясненням, що називає запис цієї Release у workspace.releases, оскільки саме цей запис прочитав пошук. Посилання на реєстр не приймає Release і з нею відхиляється: його читають із реєстру, який його публікує, хоч би яку Release було названо.
  • Наведення й перехід до визначення. Якщо назвати сутність Release, посилання під курсором спершу розв’язується через каталоги цієї Release у порядку, який задає конфігурація робочого простору, — це те саме розв’язання, що виконує пошук за назвою в термінах цієї Release, — тож показана сутність і відкритий документ — це варіант, до якого його розв’язують ці каталоги, навіть якщо документ робочого простору деінде оголошує ту саму назву. Лише там, де жоден документ у цих каталогах не дає відповіді, шукають у документах робочого простору, досяжних для цієї Release. Якщо Release не названо, порядок зворотний: спершу шукають у документах робочого простору, тож посилання, на яке відповідає документ робочого простору, зберігає цю відповідь, а власні catalog_dirs робочого простору перевіряються лише там, де жоден документ не оголошує назву, — так знаходиться сутність, яку містить лише налаштований каталог, зокрема поза деревом робочого простору. Якщо редактор містить незбережену копію документа, до якого розв’язують каталоги Release, і ця копія досі оголошує назву, відповідь читається з копії, тож позиція потрапляє на рядок, який показує редактор.
  • Автодоповнення. Якщо назвати сутність Release, пропонуються назви, які оголошують документи робочого простору, досяжні для цієї Release, разом із Components і Features, які оголошують каталоги цієї Release.
  • Посилання та реалізації. Якщо назвати сутність Release, розташування в документі робочого простору, недосяжному для цієї Release, не повідомляється, тож варіант, що зберігається для іншої Release, ніколи не потрапляє до переліку посилань чи реалізацій цієї.
  • Що можна приєднати до вузла графа. aggrega/attachCandidates, адресований вузлу графа сутності Release, завжди відповідає в термінах цієї Release — див. Що повідомляє відповідь щодо кандидатів на приєднання.

Якщо Release не названо, відповідь дається за власними каталогами робочого простору, як описано в абзаці вище.

Звернення до реєстру та запис

Більшість запитів тут відповідають на основі робочого простору та того, що вже є в кеші, і нічого не записують. Кілька названих запитів роблять більше, і вони поділяються за двома незалежними осями: до чого запит звертається і наскільки далеко сягає те, що він змінює.

Запити, що звертаються до реєстру, поділяються на ті, що читають, і ті, що публікують. aggrega/resolveDependencies завантажує те, що потрібно сутності Release, а aggrega/build приєднується до нього тоді — і лише тоді, — коли його поле autoPull вимагає спершу розв’язати залежності; у такому разі він звертається до реєстру й записує lockfile перед рендерингом; aggrega/registryUpdate обходить кожен налаштований реєстр, щоб перебудувати локальний пошуковий індекс; aggrega/pluginAdd шукає в налаштованому реєстрі плагін, названий у запиті, і читає його опубліковані версії, щоб закріпити одну з них; aggrega/registryAdd запитує в реєстру, який він реєструє, політику довіри, яку цей реєстр оголошує, якщо тільки запит не відмовляється від завантаження або не надає власну політику, а aggrega/configInit запитує те саме в реєстру, який він ініціалізує; aggrega/explainError один раз отримує пакет документації, з якого він читає покроковий опис умови, якщо в кеші, спільному для всіх проєктів на машині, немає копії, яку допускає власна перевірка підпису робочого простору, — див. aggrega explain; aggrega/scaffoldEntity, якому надіслано example або list, отримує той самий пакет на тих самих умовах, а під час запису потім розміщує приклад у новому каталозі робочого простору; aggrega/import один раз завантажує базовий імпортер з типового реєстру робочого простору, якщо машина ще його не має, а в робочому просторі, який не називає жодної теки каталогу, також опублікований знімок каталогу, який він читає, — див. Що повідомляє відповідь на імпорт; а aggrega/entityDefinition читає сутність, яку називає посилання на реєстр, коли таке посилання надіслано як його name, нічого не записуючи. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts і aggrega/deprecateArtifact записують до реєстру — байти, підпис або маркер відкликання. Запит звертається до реєстру лише тоді, коли його надіслано саме для цього: перелік повідомляє те, що закріплює конфігурація, пошук читає офлайн-знімок, а публікація, запитана з dryRun, обчислює, що вона надіслала б, і ні з ким не зв’язується.

Правило стосується того, коли виконується операція, а не того, який інтерфейс її виконує. Операція, що завантажує або записує, виконується тому, що її назвав запит, і ніколи як побічний ефект перевірки документа, огляду графа чи переліку сутностей робочого простору. Тож редактор, який виконує перевірку після кожного натискання клавіші, не звертається до мережі й не переписує lockfile, тоді як дія «розв’язати залежності», яку натискає користувач, робить саме те, що робить aggrega pull, — те саме розв’язання за обома інтерфейсами, що записує побайтово ідентичний lockfile і заповнює той самий кеш артефактів.

Нічого не запитується в користувача. За цим потоком ніхто не стежить, тож ідентичність визначається з наданого або наявного в середовищі джерела облікових даних і ніколи не через запитання. Там, де термінальна команда поставила б запитання людині, — реєстр, якому потрібні облікові дані, можливість, яку обслуговує більш ніж один плагін-провайдер, текст, який має містити відкликання, — запит завершується помилкою з повідомленням, що називає, що слід надати, замість блокування в очікуванні відповіді, яка ніколи не надійде. Відмова залишає робочий простір точно таким, яким він був: жоден lockfile не записується й жоден частковий запис не лишається, а публікація, яка не змогла визначити облікові дані, відмовляє ще до того, як будь-які байти дійдуть до реєстру.

Деякі зміни сягають за межі цього робочого простору, і відповідь повідомляє, які саме

Запит називає один робочий простір, тож відповідь, яка нічого не каже про власну досяжність, сприймається як така, що стосується цього робочого простору. Для кількох із цих запитів таке прочитання було б хибним, тому кожен із них містить свою область дії, і клієнт має показати її, перш ніж діяти на основі результату.

Публікація, підписування та відкликання повністю виходять за межі машини, і це найширша досяжність серед усього, що тут є. Інші записи нижче змінюють те, що розв’язує ця машина; ці змінюють те, що отримують усі, хто розв’язує з цього реєстру. Опубліковані байти — це те, що отримує кожен споживач цього реєстру, а повторна публікація іншого вмісту під тим самим тегом відхиляється, а не пропонується, тож жоден запит тут не скасовує публікацію — рішення полягає в публікації нової версії. Підпис і маркер відкликання прикріплюються як сусідні до артефакту об’єкти, а не замінюють його, тож самі байти лишаються незмінними; але кожен, хто завантажує артефакт після цього, завантажує й їх, і жоден із них не можна відкликати в того, хто вже його має. Відкликання найлегше хибно витлумачити з усіх трьох: версія лишається доступною для завантаження, тоді як ретракція, якій довіряє робочий простір, виключає її з того, що обиратиме розв’язання в ньому.

Підписування використовує облікові дані, і варто знати, звідки вони беруться, перш ніж підключати клієнт. Безключове підписування визначає токен ідентичності в такому порядку: з identityToken у запиті, потім з AGGREGA_IDENTITY_TOKEN у середовищі демона, потім з наявної в середовищі кінцевої точки OIDC GitHub Actions, якщо вона доступна, потім з SIGSTORE_ID_TOKEN. Якщо жодне з них не дає токена, операція відмовляє й називає, що слід надіслати; вона ніколи не відкриває браузер, бо дивитися в нього нікому. Підписування ключем — це офлайн-альтернатива, і запит не називає шляху до ключа: те, що читає запит, розташоване всередині названого ним робочого простору, а приватний ключ ніколи не зберігається в робочому просторі, тож ключ натомість береться з блоку signing: власної конфігурації цього робочого простору. Див. aggrega sign, щоб дізнатися про два режими підписування й те, до чого звертається кожен із них.

Кожна з чотирьох відповідей містить reach з полями registries — кожен хост реєстру, до якого звернувся виклик, названий один раз, у порядку першого звернення, тож пакет підписування або пакетний файл, посилання якого охоплюють кілька реєстрів, називає кожен із них, — і beyondThisMachine, яке виводиться з того, що виклик фактично прикріпив, а не з того, що він запитував: true саме тоді, коли він вивантажив вміст або прикріпив підпис, дату публікації чи маркер застарілості, і false для пробного запуску та для виклику, який виявив, що все, що він прикріпив би, уже є, — повторної публікації версії, яка вже повна, або пакета підписування, кожне посилання якого вже мало підпис, що проходить перевірку. Пробний запуск однаково називає місце призначення, до якого він звернувся б. Показуйте це, перш ніж діяти на основі результату.

Реєстрація або видалення реєстру за замовчуванням записує конфігурацію, спільну для всіх робочих просторів на машині. Реєстр та ідентичності, яким ви в ньому довіряєте, зазвичай однакові, хоч би де ви працювали, тож саме туди потрапляє запис, якщо тільки запит не надсилає workspace: true. Наслідок варто сказати прямо: aggrega/registryAdd і aggrega/registryRemove змінюють те, через що розв’язує кожен проєкт на цій машині, включно з проєктами, яких ніхто в цьому сеансі не називав. Обидві відповіді містять scope з configFile, який було записано, і machineWide, що вказує, чи це спільний файл. Видалення небезпечніше з двох, бо повторне додавання — не та сама дія: закріплена політика довіри зникає, а пізніша реєстрація закріплює те, що реєстр оголошуватиме на той момент.

Ініціалізація конфігурації за замовчуванням записує той самий спільний файл, і з тієї ж причини. aggrega/configInit реєструє реєстр і його політику довіри, а це інструментарій рівня машини, тож без перевизначення він записує конфігурацію, через яку розв’язує кожен проєкт на машині, — і один раз звертається до цього реєстру, щоб прочитати оголошену ним політику. Його відповідь містить ту саму пару scope, що й два методи реєстру. Від них він відрізняється в одному, на що варто покладатися: він відмовляє, а не перезаписує наявний файл конфігурації, тож не може замінити конфігурацію, з якою хтось працює, якщо тільки запит не надсилає force. Фіксація — протилежний випадок: aggrega/configCapture не приймає жодного перевизначення, завжди записує власний файл конфігурації проєкту й не звертається до жодного реєстру, тож ніщо з того, що він робить, не видно іншому проєкту. Див. Що залишає по собі запис конфігурації.

🔴 Додавання або видалення плагіна розширення команд за замовчуванням записує той самий спільний файл, і саме це слід прочитати уважно. aggrega/pluginAdd і aggrega/pluginRemove приймають type, і тип визначає, куди йде запис, якщо перевизначення не надіслано. Запис provider, governance, linter або importer формує збірку одного проєкту, тож він потрапляє до власної конфігурації цього проєкту. Запис cli — це інструментарій рівня машини, тож додавання типу cli, яке не вказує ні global, ні workspace, реєструє команду в глобальному файлі конфігурації, через який виконує розв’язання кожен робочий простір на цій машині, — команда стає командою верхнього рівня aggrega для кожного проєкту на цій машині, включно з проєктами, яких ніхто в цьому сеансі не називав, а скасувати її можна лише окремим видаленням, а не відкатом. Надішліть workspace: true, щоб залишити її локальною. Обидві відповіді містять scope із записаним configFile і machineWide, що вказує, чи це спільний файл, і визначається за файлом, до якого було розв’язано запис. Додавання також звертається до реєстру, у якому шукало, тож воно перебуває на обох осях водночас. Див. Що повідомляє зміна плагіна.

Два інші запити щодо плагінів записують лише всередині робочого простору. aggrega/pluginSync записує файл сутності Plugin, який називає запит, а aggrega/pluginGenCatalog записує згенеровані сутності в outputDir, який називає запит, — обидва всередині робочого простору, названого запитом, обидва відхиляють місце призначення, що є абсолютним або розв’язується за його межі, і жоден не видимий іншому проєкту. aggrega/pluginGenCatalog читає свій модуль і накладку звідти, де ви їх вибрали, і це не розширює місця, куди він записує: обидва розв’язуються за різними правилами, тож генерація може читати модуль, зібраний будь-де, а створені нею сутності все одно потрапляють у робочий простір. aggrega/pluginGenCatalog з dryRun нічого не записує, а натомість повертає вміст.

Закріплення сутності теж записує лише всередині робочого простору й звертається до хостів, які називають її джерела. aggrega/pin записує entity.lock поруч із сутністю, яку називає запит, тобто за шляхом усередині робочого простору, і заповнює кеш вмісту робочого простору отриманими джерелами; ніщо із записаного ним не видиме іншому проєкту. Він звертається назовні, щоб розв’язати кожне віддалене джерело, яке називає сутність, — репозиторій чартів, хост Git, URL, — і це той самий обсяг звернень, що й у aggrega/resolveDependencies для джерел, які споживає сутність Release. aggrega/resolveDependencies і aggrega/publishEntity, яким надіслано pinSources, виконують той самий крок, тож кожен із них теж записує поруч із сутностями, які закріплює; отже, публікація із закріпленням зачіпає і робочий простір, і реєстр. Публікація без закріплення нічого не записує поруч із сутністю, але все одно звертається до цих хостів: щоб порівняти lock-файл із тим, що записав би крок, треба повністю отримати кожне віддалене джерело, яке виписує сутність.

Інсталяція навички асистента залишається всередині робочого простору, якщо запит не надсилає global. aggrega/skillsInstall записує теку навичок проєкту кожного названого асистента всередині робочого простору, названого в запиті, і ніщо з записаного там не видно іншому проєкту; scope у його відповіді містить machineWide зі значенням false. З global: true він натомість записує користувацьку теку кожного асистента в домашньому каталозі, яку цей асистент читає в кожному проєкті на машині, і machineWide має значення true. В обох випадках він не звертається ні до реєстру, ні до мережі.

Видалення збережених облікових даних сягає ширше, ніж будь-що інше тут, що обмежується цією машиною. aggrega/logout змінює сховище облікових даних, а це сховище спільне не лише для кожного проєкту на машині, а й для кожного іншого інструмента, що автентифікується в тих самих реєстрах, — тож облікові дані, видалені через сеанс, зникають для всіх них, і aggrega/registryList повідомлятиме про їхню відсутність і в кожному іншому робочому просторі. Відповідь містить scope з machineWide, яке завжди дорівнює true: це сховище не має форми в межах робочого простору, тож немає перевизначення, яке можна надіслати, і немає чого вмикати в запиті. scope навмисно не називає файлу, на відміну від записів конфігурації вище. Сховище делегує тому помічникові облікових даних або зв’язці ключів ОС, які налаштовано на машині, тож видалення часто обслуговує щось, що зовсім не є файлом, і назва шляху вказала б вам на місце, якого видалення не обов’язково торкнулося.

Видалення не є оберненою дією до автентифікації, і клієнт не повинен пропонувати його як таку. Ця поверхня видаляє облікові дані й не отримує їх: щоб повернути облікові дані, треба знову автентифікуватися за допомогою aggrega login у терміналі, бо для їх збереження потрібен секрет, який вводить людина, а цей потік ніхто не переглядає. Тож «вихід», який пропонує клієнт, звідси є односторонньою дією. Ці дві дії розрізняє те, чи має операція щось отримати від того, хто нею керує, — видалення несе своє єдине значення в запиті, а отримання облікових даних — ні, — а не те, чи бере участь людина, адже обидві дії обрала людина.

Звільнення вмісту кешу теж сягає за межі робочого простору. Сховища скомпільованих модулів і описів плагінів спільні для кожного проєкту на машині, тож aggrega/cachePrune, aggrega/cacheEvict і aggrega/cacheClear можуть видалити вміст, від якого залежить інший проєкт. Кожне видалення містить reach класу, з якого воно походить, а кожна відповідь містить scope.machineWideClasses. aggrega/cacheStatus містить той самий обсяг для кожного класу, хоча нічого не змінює, бо клієнтові, який вирішує, чи звільняти, він потрібен до того, як він діятиме.

Оновлення пошукового індексу працює навпаки. aggrega/registryUpdate звертається до кожного налаштованого реєстру, а те, що він записує, потрапляє до власного налаштованого каталогу кешу цього робочого простору — тож він не змінює нічого, через що виконує розв’язання інший проєкт. indexRoot у відповіді називає цей каталог.

Часткове оновлення дає відповідь, а не збій. Запит, що називає один реєстр, оновлення якого не вдалося, є помилкою, бо немає відповіді, яку можна дати. Запит, що оновлює кожен налаштований реєстр, виконується успішно, навіть якщо деякі з них або всі зазнали збою: оновлені було проіндексовано й записано, failed називає решту, а кожен хост містить власну помилку. Читайте failed, а не наявність помилки.

Те, чи вдалося звернутися до реєстру, визначає ключ, а не тлумачення повідомлення. Хост, що зазнав збою, містить unreachable: true, якщо до реєстру так і не вдалося звернутися, — його ім’я не розв’язалося, з’єднання з ним було відхилено або не вдалося відкрити, чи не вдалося встановити захищене з’єднання, — і відмова запиту, що називає один реєстр, містить той самий ключ у своєму data. Реєстр, до якого вдалося звернутися, але який зазнав збою через список, що повторювався, або статус помилки, не містить жодного з них, а його error чи повідомлення відмови каже, що він відповів. Ключ визначається за самим збоєм, тож він не залежить від того, як резолвер цієї машини формулює збій, і він встановлюється лише там, де збій показує, що до реєстру так і не звернулися: про збій, який не показує нічого визначеного, як-от вичерпаний ліміт часу без запису про те, який крок він перервав, повідомляється без нього. Позначайте реєстр як недосяжний за ключем, а помилку показуйте як причину.

Командний рядок повідомляє про той самий обхід ненульовим кодом виходу, і те, хто ви як читач, визначає, чого вартий цей код. Для людини в терміналі це не повна картина: aggrega registry update виводить, скільки з вибраних реєстрів він проіндексував, що знайшов кожен, які він не проіндексував і куди було записано індекс, — тож підсумок каже, що сталося, а код виходу каже лише, чи все вдалося. Для скрипту це повна картина, бо ця команда не пропонує режиму структурованого виводу, тож її код виходу — єдиний доступний машинозчитуваний вердикт. Саме тому дві поверхні відповідають на той самий частковий обхід по-різному, і обидві мають рацію: ця передає структурованому викликачеві failed і завершується успішно, а командний рядок має один біт і витрачає його на «чи було пропущено якийсь реєстр».

Спостереження за тривалою операцією

Більшість запитів тут відповідають на основі того, що вже є на диску, і відповідають одразу. Кілька спершу виконують справжню роботу — розв’язують залежності сутності Release, закріплюють її зовнішні вхідні дані, публікують, підписують, відкликають, — і викликач чекає. Такі запити повідомляють, що вони роблять, під час роботи, і це вмикається окремо для кожного запиту.

Увімкнення складається з двох кроків, у такому порядку.

  1. Оголосіть можливість під час рукостискання й дочекайтеся відповіді. Надішліть capabilities.window.workDoneProgress: true в aggrega/initialize. Не надсилайте нічого іншого, доки не надійде ця відповідь: запити обслуговуються паралельно, тож запит, записаний до відповіді на рукостискання, може виконуватися одночасно з рукостисканням, яке мало домовитися про нього. Кожен клієнт і так зобов’язаний протоколу дотримуватися цього порядку; це ще одна річ, яка від нього залежить.
  2. Додайте токен до параметрів запиту. Додайте workDoneToken до параметрів запиту, про хід якого ви хочете отримувати повідомлення. Значення обираєте ви — рядок або число, — і саме воно пов’язує сповіщення з цим викликом. Створюйте новий токен для кожного виклику.

Сповіщення. Кожне з них — це $/progress, де params.token дорівнює вашому токену, а params.value містить одне корисне навантаження:

value.kindміститьколи
begintitle — що відбувається, фразою, яку можна показати читачевіодин раз, коли робота починається
reportmessage — один рядок власного звіту операції про себебудь-яку кількість разів, у міру того як операція їх записує
endнічого, крім видуодин раз, коли робота завершена

Зіставляйте за токеном, ніколи за ідентифікатором запиту. Сповіщення не містить ідентифікатора — воно не є відповіддю ні на що, — і токен є єдиним, що в ньому вказує на ваш виклик. Так зроблено навмисно: у багатьох клієнтах ідентифікатор запиту належить транспорту й ніколи не доходить до коду, який зробив виклик, тоді як токен — це значення, яке цей код уже має.

report містить власний текст компілятора. Повідомлення — це один рядок, який операція записала під час роботи, переданий з видаленими пробілами на початку й у кінці без жодних інших змін — не переформульований, не скорочений, не перескладений, — а рядок, який операція записала порожнім, відкидається, а не повідомляється як порожнє повідомлення. Тож клієнт показує отримане як є. Це та сама властивість, яку мають власні діагностики відповіді: одна умова зберігає одне формулювання, скільки б поверхонь про неї не повідомляло.

Крок, на який чекає операція, — це теж report. Коли операція переходить до кроку, на який чекає, — читання реєстру, отримання артефакту, компіляції плагіна, — report містить назву кроку тими словами, які командний рядок показує для того самого кроку поруч зі своїм індикатором очікування. Повідомляються лише кроки, до яких перейдено між begin і end.

Один рядок виводу — це один report. Операція, яка записує кілька рядків одночасно, створює по одному сповіщенню на рядок, а рядок, який операція записує частинами, повідомляється, щойно він завершений, — тож повідомлення ніколи не буває пів речення.

Немає ні частки, ні відсотка, і це не пропуск, що чекає на доопрацювання. Операції, які тут повідомляють про хід, опрацьовують набір, розмір якого невідомий на початку роботи, — скільки посилань обходить розв’язання, скільки шарів вивантажує публікація, — тож будь-яка частка була б вигаданою. Показуйте невизначений індикатор і останнє message.

Фрейми надходять до відповіді й ніколи після неї. begin надходить, щойно робота справді почалася, тож запит, відхилений через параметри, — абсолютний шлях, відсутнє обов’язкове поле, — не створює жодного сповіщення, лише свою помилку. end надходить до відповіді, а те, чи операція завершилася успішно, міститься у відповіді, а не повторюється в end.

Зупинка роботи — це окреме сповіщення. Надішліть $/cancelRequest з ідентифікатором, під яким ви надіслали запит. Токен у скасуванні участі не бере, а скасування не прибирає вже надіслані фрейми.

Які запити повідомляють про хід і чого чекати від решти

Про хід повідомляють саме ці: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.

Дві речі справджуються для кожного з них, і обидві є причиною, чому він у списку: він звертається до реєстру або віддаленої URL-адреси від вашого імені, тож його тривалість визначає щось поза машиною; і він уже записує власний звіт про себе під час роботи — той звіт, який читає людина, що дивиться в термінал. Тож повідомлення про хід передає вам той самий звіт, а не другий, складений для передачі, і для цього не довелося нічого змінювати в тому, що робить операція.

Кожен інший запит приймає токен і нічого не надсилає. Надсилання токена нешкідливе, а не помилкове: його прийнято, сповіщення не надходять, а відповідь точно така, яку ви отримали б без нього. Тож клієнт може додавати токен до будь-чого й просто нічого не показувати, коли нічого не надходить.

🔴 Не сприймайте тишу як «цей запит миттєвий». Більшість решти справді відповідають на основі того, що вже є на диску, — перевірка, підказка при наведенні, автодоповнення, граф, перелік кешу, читання конфігурації, — але не всі: оновлення індексу реєстру, додавання плагіна, перевірка перед публікацією та перше розгортання коду на машині, де немає документації, яку може читати робочий простір, — усі звертаються до реєстру, а компіляція сутності Release є справжньою роботою. Вони тривають стільки, скільки тривають, і сьогодні нічого не повідомляють. Показуйте невизначений індикатор для будь-якого запиту, на який ви готові чекати, і вважайте сповіщення подробицями, які ви отримуєте, коли вони доступні, а не тим, що повідомляє вам про виконання роботи.

Дві відмови

Обидві є помилками invalid-params, і обидві вказують, що робити, бо токен, який мовчки нічого не робить, змусив би вас чекати на потік, що ніколи не надійде.

  • Токен із сеансу, який не оголосив можливість window.workDoneProgress, відхиляється із зазначенням можливості, яку слід оголосити. Оголосіть її під час рукостискання або не додавайте токен.
  • Токен, який не є ні рядком, ні числом, відхиляється із зазначенням двох допустимих форм. Відсутній токен і явне null не є відмовами — обидва означають, що ви не просили повідомлень про хід.

Відстеження lockfile

Демон перевіряє lockfile на розбіжності під час кожного aggrega/irGraph щодо сутності Release, яку назвав цей запит, і повідомляє про розбіжність як про неблокувальне попередження. Попередження називає команду, яка переписує цей lockfile із цією сутністю Release, у тому вигляді, у якому її надіслав запит, — aggrega pull --release, після чого йде надісланий вами release; саме так її пишуть у терміналі в корені робочого простору. aggrega/irGraph вимагає наявності lockfile. Окремої перевірки під час запуску немає: запит указує, якої сутності Release він стосується, тож висновок обчислюється для цієї сутності Release тоді, коли його запитують, а не один раз для однієї наперед вибраної сутності Release.

Попередження про розбіжність зникає, коли зникає його lockfile. Попередження публікується для lockfile, щодо якого його було видано, а в lockfile, якого більше немає, не лишилося закріплень, які могли б розійтися, — команда, яку називає попередження, записала б новий файл, а не виправила старий. Тому кожен запит, який виявляє відсутність lockfile, відкликає попередження, перш ніж відмовити з помилкою про відсутній lockfile: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates і aggrega/attachmentContainer, запитані щодо вузла графа, а також aggrega/connectionAtPosition. Відкликання надходить як сповіщення aggrega/publishDiagnostics для lockfile з порожнім списком, раніше за відмову. Його надсилає той із цих запитів, який першим дізнається про видалення, тож клієнт, який повідомляє про видалення, а потім запитує будь-що про цю сутність Release, отримує очищене попередження, не запитуючи саме граф. Lockfile, який досі існує і досі має розбіжності, зберігає своє попередження впродовж кожного з цих запитів. aggrega/invalidate, що називає lockfile, відкидає те, що демон зберігає для нього, але нічого не надсилає; клієнтові повідомляє наступний запит. А lockfile, який демон навіть не може перевірити, — скажімо, такий, каталог якого йому не дозволено читати, — нічого не відкликає, бо він може й далі існувати, а попередження може й далі бути слушним.

aggrega/build і aggrega/buildPreview теж його вимагають, і вони звіряють із ним сутність Release, а не попереджають: вони виконують рендеринг у режимі поверхні, що створює артефакт, тож lockfile, який більше не відповідає тому, у що розв’язується сутність Release, зупиняє їх там, де інспекцію він лише попередив би. Сутність Release без lockfile відхиляється з помилкою про відсутній lockfile. Виняток — збирання, поле autoPull якого просить спершу розв’язати залежності: таке збирання записує lockfile, а потім виконує рендеринг за записаним, і lockfile, створений у такий спосіб, удруге на розбіжності не перевіряється, бо розв’язання, яке його записало, виконало ту саму перевірку перед записом і не записує lockfile, який ця перевірка відхиляє.

Lockfile, який існує, але не містить дайджесту для плагіна, граф не зупиняє — зупиняє відсутній lockfile. Це дві різні умови, і відмову спричиняє лише друга. aggrega/irGraph не звіряє байти, у які він розв’язує, із записаними дайджестами: про закріплення, яке неможливо перевірити, повідомляється, а не відмовляється, і граф малюється з висновком на панелі Problems, бо редактор, що відмовляється малювати граф, лишає читача ні з чим, тоді як повідомлення дає йому, з чим працювати. В інших місцях плагін теж виконується, з попередженням про те, що його байти ніщо не перевірило. Від чого aggrega/irGraph відмовляється, то це від відсутнього lockfile: він зупиняється, перш ніж щось розв’язати, і відповідає помилкою про відсутній lockfile, називаючи lockfile, який шукав, і сутність Release, тож клієнт може одразу запропонувати aggrega pull --release <release> — або надіслати aggrega/resolveDependencies для цієї сутності Release і записати lockfile, не виходячи із сеансу. Розрізняти ці дві умови важливо, бо намальований граф — це картина, на основі якої читач потім міркує, а граф, побудований із байтів, яких ніщо не перевірило, малюється точнісінько як перевірений, і висновок лежить там, куди читач не дивиться. Тож граф не є висновком щодо байтів, що за ним стоять: aggrega/build і aggrega/buildPreview — це поверхні, які звіряють сутність Release із записаними дайджестами і зупиняються там, де інспекція лише повідомляє.

aggrega/validate, коли запит називає сутність Release, читає lockfile цієї сутності Release лише заради закріплень і повідомлень про застарілість — і не читає жодного для сутності каталогу, яку перевіряє як окрему сутність, так само як не читає командний рядок. Він не звіряє плагіни, які виконує, із записаними дайджестами і не відтворює набір під’єднань transform-плагінів із lockfile — він виконує валідацію щодо конфігурації робочого простору в її поточному вигляді, і саме так має діяти редактор, поки ви редагуєте цю конфігурацію. aggrega validate і aggrega build роблять і те, і те, і лишаються авторитетними поверхнями для висновку щодо закоміченого робочого простору.

Його повідомлення про застарілість охоплюють обидва місця, де записується відкликання. Маркер на закріпленому посиланні міститься в lock-файлі; маркер на плагіні, приєднаному в ролі, що повертає вердикт «прийняти чи відхилити», — приєднанні plugins.governance в ir-verdict або render-verdict чи приєднанні plugins.linter, — міститься в записі довіри плагінів поруч із ним, тож валідація читає обидва й називає кожне відкликане посилання і кожен відкликаний плагін попередженням на початку Aggregate, у формулюванні, яке виводить aggrega build. Повідомлення не змінює жодного вердикту. Запис довіри, який існує, але не може бути прочитаний, повідомляється як помилка замість валідації, а не читається як запис, у якому нічого не записано. aggrega/releaseClosure повідомляє той самий набір у своєму deprecations.

Де розташований lockfile сутності Release

Кожна відповідь, що називає сутність Release, називає і її lockfile, тож клієнтові ніколи не доводиться обчислювати шлях. aggrega/activeRelease передає його як lockfile поруч із release, aggrega/releaseCandidates — як мапу lockfiles поруч із releases, а помилка про відсутній lockfile — як lockfile у своєму data. Кожне з них — це файл, який записує aggrega pull --release <release> і читає aggrega build, і файл, наявність якого перевіряє кожен запит, згаданий вище, — тож клієнт, який стежить за lockfile сутності Release, щоб помітити його запис, перезапис чи видалення, стежить саме за тим файлом, який має на увазі демон. Lockfile лежить поруч зі своєю сутністю Release і має ім’я сутності Release, у якому розширення .yaml або .yml замінено на .lock; сутність Release з будь-яким іншим розширенням зберігає повне ім’я, тож lockfile для release.rel — це release.rel.lock. Беріть шлях із відповіді, а не складайте його за цим описом, і тоді вони не розійдуться.

Зовнішні посилання, яких потребує рендеринг

Рендеринг може запитувати вміст за віддаленою URL-адресою — наприклад, схему значень чарту з віддаленим посиланням. Зовнішні вхідні дані заморожено для кожного рендерингу, який цей демон виконує у відповідь на запит, що лише просив щось повідомити. Посилання, яке закріплює lockfile сутності Release, обслуговується зі сховища з адресацією за вмістом, тобто це читання вмісту, що вже є на диску, а не завантаження, і перед тим, як віддати його байти, їх звіряють із тим, що записано в lockfile, — тож рендеринг тут бачить те саме, що й збірка, і видає ті самі попередження, що й збірка. Посилання, яке lockfile не закріплює, відхиляється, а не завантажується: щоб отримати його, довелося б звернутися до мережі й записати blob у сховище, а сеанс не робить ні того, ні іншого на запит, що лише просив щось повідомити. Це правило з розділу Звернення до реєстру та запис, прочитане з боку рендерингу, і воно діє незалежно від того, як було досягнуто такого рендерингу.

Запит, що існує для закріплення, є винятком, і це той самий виняток, який уже містить правило реєстру. aggrega/resolveDependencies має завдання отримувати, тож рендеринг, який він виконує, щоб з’ясувати, які посилання використовує ця сутність Release, звертається до мережі й записує те, що закріплює, — саме тому його результатом є lockfile, а не звіт. Жоден рендеринг, який запит графа чи збірки виконує для себе, нічого з цього не робить.

Збірку, якій доручено спершу розв’язати залежності, обслуговують саме з того рендерингу, тому вона рендерить сутність Release один раз. Розв’язання вже відрендерило те, чого стосується збірка, з урахуванням щойно записаних закріплень і під тими перевірками, які виконує збірка, тож збірка подає той рендеринг, а не виконує другий, — а отримання й надалі належить розв’язанню, а не збірці. Так використовується лише рендеринг, що завершився: якщо розв’язання закріпило залежності, але не змогло завершити виявлення зовнішніх посилань, збірка рендерить сама з урахуванням тих закріплень, що таки записалися, а незакріплене посилання відхиляється й повідомляється там точно так само, як у збірці, що нічого не розв’язувала.

Про відхилення повідомляється, а не замовчується, бо ніщо в результаті не каже, якого посилання в ньому бракувало. З постачальниками, які містить цей бінарний файл, постачальник, що запросив посилання, повертає відмову, тож рендеринг, який натрапив на відхилене посилання, не завершується. Тому кожне відхилене посилання надходить окремим записом на шарі aggrega-build, що називає посилання й команду, яка його закріплює: aggrega pull --release <release> або aggrega/resolveDependencies для тієї самої роботи без виходу із сеансу. Ці записи є попередженнями, а не відмовою — граф однаково повертається, з тим самим статусом, що й у попередження про розбіжність вище, — і їх приписують сутності Aggregate на початку файлу, бо посилання, якого потребував рендеринг, не називає жодного ключа, написаного автором. Вони надходять у тій самій публікації, що й власні попередження рендерингу, яка замінює цей шар повністю, тож про посилання, яке ви згодом закріпите, перестають повідомляти без потреби будь-що очищати. Повністю закріплений рендеринг нічого з цього не повідомляє. Форму кожного запису див. у розділі Що містить запис діагностики.

Для aggrega/irGraph це залежить від того, чи взагалі виконується етап рендерингу. Запит графа пропускає рендеринг, якщо його не ввімкнено --build-on-inspect або ключем serve.build_on_inspect, який цей прапорець перевизначає; коли перемикач вимкнено, ніщо не запитує зовнішнього посилання і нема чого відхиляти. Саме ввімкнення приносить у сеанс редактора і власні попередження рендерингу, і ці.

Чим сеанс відрізняється від такого самого заморожування в командному рядку. aggrega build так само заморожує зовнішні вхідні дані для пробного запуску, і незакріплене посилання поводиться однаково на обох поверхнях: про нього повідомляється як про знахідку, що називає посилання, а потім рендеринг зупиняється, бо постачальник, який його запросив, повертає відмову. Відрізняється повторне завантаження. У командному рядку закріплене посилання, збережена копія якого зникла, завантажується знову за записаним дайджестом; рендеринг, що відповідає на запит графа чи збірки, нічого не завантажує повторно, бо не звертається до мережі, тож він не може повернутися по закріплене посилання, якого сховище вже не має, — і таке посилання не належить до описаних вище відхилень, що називають те, чого lockfile не закріплює. Відновлює його прохання до сеансу закріпити: названі вище запити звертаються до мережі й повертають відсутні байти. Що саме завантажує й записує закріплення, див. у aggrega pull.

Що все ж повідомляє відхилений запуск

Запит, що відмовляє, відповідає конвертом помилки, і знахідки, які запуск уже встиг зробити, не передаються в цьому конверті — конверт узагалі не містить тіла результату. Вони доходять до вас так само, як і під час запуску, що завершився: як публікація діагностики на шарі aggrega-build, описана в розділі Що містить діагностичний запис. Тож клієнт, що обробляє відмову, читає конверт, щоб дізнатися, що змінити, а свою панель проблем — щоб дізнатися, що знайшов запуск, і жодне з них не замінює іншого. Відмова, що виникла під час рендерингу, — це єдина відмова, яка водночас є знахідкою щодо написаного автором, тому вона доходить до обох, як описано в наступному розділі.

Ця публікація відбувається незалежно від того, чи дійшов запуск до кінця. Запуск, що зупинився посередині, все одно знайшов усе до точки зупинки, і читачеві, який утратив би ці знахідки, довелося б запускати знову, щоб їх побачити, — тому попередження публікуються з того, до чого дійшов запуск, а відмова повертається після цього. Це той самий набір з тією самою точністю, розміщений на тих самих авторських ключах: відмова не зводить знахідку до речення. Відхилені зовнішні посилання передаються в тій самій публікації, з тієї самої причини й тим самим шляхом.

Межу визначає те, як далеко зайшов запуск, а не те, що може вмістити шар. Відмова від однієї з перевірок, що виконуються до запуску компілятора, — замикання сутності Release не вдалося розв’язати, сутність Manifest зіставляє тип із рецептом, який його не реалізує, lockfile більше не відповідає тому, у що розв’язується сутність Release, закріплений запис у кеші більше не відповідає записаному для нього дайджесту, і жоден каталог не містить закріплених байтів, — не має попереджень для публікації, бо жодне ще не було видано. Тоді шар не містить нічого, а не щось застаріле; а запуск, що не дійшов до визначення документа, взагалі нічого не публікує, залишаючи все, що вже є на вашій панелі проблем, точно таким, яким воно було, замість того щоб очищати записи, про які він нічого не дізнався.

Відмова, що виникла під час рендерингу

Сутність Release, яку компілятор відхиляє під час рендерингу, — Workload, що називає слот, якого не оголошує його Component, твердження, що не виконується, шаблон, який неможливо обчислити, реалізація, якій бракує того, що вона має надати, — повідомляється там, куди вказує, і словами компілятора, на кожен запит, що її рендерить: aggrega/build, aggrega/buildPreview і aggrega/irGraph з увімкненим етапом рендерингу. Відповіддю є конверт помилки з кодом -32603, чиє message — це відмова з усіма причинами під нею, тими самими словами, які командний рядок друкує для тієї самої збірки: вузол, що рендериться, потім те, що в ньому відмовило, кожна причина після тієї, яку вона пояснює, — а на початку, якщо відмова називає зареєстровану умову, короткий код цієї умови, як і в кожній відмові, що її називає. Її data називає документ, на який вказує відмова, як file, а діапазон ключа в ньому — як line, column, end_line і end_column, поруч із code і shortCode умови; відмова, що не називає ключа або називає ключ, якого документ не містить, несе лише file, а та, що не вказує на жоден документ, називає сутність Aggregate цієї сутності Release.

Та сама відмова публікується на шарі aggrega-build, на тому документі, на тому ключі, як запис із рівнем серйозності error, що несе власний keyPath відмови та message конверта без короткого коду перед ним, а також — якщо відмова називає зареєстровану умову — code, shortCode і codeDescription цієї умови, причому короткий код там передається у власному полі. Вона передається в тій єдиній публікації, що несе попередження, видані запуском до зупинки, тож замінює шар так само, як і вони: наступний запуск сутності Release, що виконує рендеринг, публікує шар без неї, а документ, на якому вона була, публікується порожнім, що й прибирає її з вашої панелі проблем.

Місце, куди вказує відмова, — це те, що називає сама відмова, і не точніше. Перевірки сутності Workload оцінюють документ, створений її шаблоном, а шаблон може записати рядки, яких не писав жоден автор, — цикл, умову, текст, імпортований із файлу чи бібліотеки, — тож рядок відрендереного Workload не відповідає рядку Recipe. Тому відмова щодо Workload розміщується на ключі workload сутності Recipe, а шляхи, які вона називає всередині відрендереного документа, залишаються в її повідомленні. Твердження, що не виконується, розміщується на власному ключі під assertions у Recipe або FeatureRecipe, що його оголошує; твердження, яке оголошує Component або Feature, видається до того, як з’являється будь-який документ, який можна назвати, і розміщується на ключі kind: сутності Aggregate. Відмова від кроку, що називає документ, але не ключ, розміщується на ключі kind: цього документа.

Відмова, що об’єднує кілька знахідок, публікується знахідка за знахідкою. Композиція графа, з яким працює рендеринг, відмовляє з усіма знайденими порушеннями в одній відмові — запис, що називає ціль, якій ніщо не відповідає, два з’єднання одного компонента з однаковим псевдонімом, — і командний рядок друкує кожне як окрему діагностику під власним заголовком. Тут кожне є окремим записом на шарі aggrega-build, на документі й на ключі, які називає ця знахідка, — на Release, де його написала сутність Release, на Aggregate, де це зробила сутність Aggregate, — власними словами та з власними кодами. message відповіді містить усі знахідки, а її data називає, куди вказує перша.

Значення, яке автор оголосив чутливим, тут приховується точно так само, як його приховує командний рядок. Текст відмови — це текст, виданий компілятором, ніщо на цій поверхні його не переформульовує, а компілятор приховує оголошене значення там, де видається відмова, — замість нього <redacted>, — тож ця відповідь, цей запис і термінал передають його однаковими словами; що відмова повідомляє про оголошене значення пояснює, як саме, і які відмови лежать поза цим.

Відмова від перевірки, що виконується до рендерингу, — це не те. Перелічені вище перевірки відповідають так, як описано в Що все ж повідомляє відхилений запуск. Твердження, яке оголошує Component або Feature, і відмова щодо скомпонованого графа перебувають посередині: кожне видається до рендерингу кожним запитом, що розв’язує граф сутності Release, тож aggrega/irGraph відповідає ним і публікує його, як описано вище, також і з вимкненим етапом рендерингу; aggrega/releaseClosure, aggrega/attachCandidates і aggrega/attachmentContainer, запитані про вузол графа, а також aggrega/connectionAtPosition відповідають ним із тим самим конвертом і нічого не публікують, бо не мають власної панелі проблем.

Коди помилок

Відповіді використовують стандартні коди помилок JSON-RPC, а також діапазон рівня застосунку в смузі 1xxx. Клієнт редактора може розгалужуватися за кодом, не розбираючи повідомлення.

  • 1001 file-not-validated — демон не має для файлу в його поточному стані нічого, з чого запит міг би отримати відповідь: немає результату розбору файлу або, для aggrega/diagnostics, немає результату розбору файлу чи нічого збереженого для файлу, що було б відповіддю валідації для тексту, який демон має зараз. Надішліть для нього aggrega/validate і запитайте знову.
  • 1003 lockfile-absent — сутність Release, названа в запиті, не має lockfile, а запитана операція його потребує.
  • 1004 entity-not-resolvable — ім’я не збіглося з жодною сутністю в жодному рівні каталогу, ані в сутності Release, названій у запиті; або посилання на реєстр, надіслане як ім’я, не вдалося прочитати як сутність, і повідомлення називає умову, що пояснює причину; або lockfile сутності Release є посиланням, що веде за межі робочого простору, яке відхиляється ще до того, як щось його прочитає, причому data називає lockfile і сутність Release, а повідомлення починається з короткого коду умови, E0321 — див. межу робочого простору.
  • 1005 shutting-down — демон завершує роботу після сповіщення про вимкнення і відхиляє нові запити. Не повторюйте запит до того самого підпроцесу.
  • 1006 validation-in-flight — валідація файлу виконується і не завершилася в межах часу, який їй дозволив запит, що очікує. Невдовзі запитайте знову і нічого не надсилайте.

1002 не призначено, і він доступний для наступної умови, якій знадобиться код.

File-not-validated і validation-in-flight повідомляють протилежні стани, і дії, яких вони вимагають, теж протилежні. File-not-validated означає, що демон не має для файлу в його поточному стані нічого, з чого запит міг би отримати відповідь, — немає результату розбору файлу або, для aggrega/diagnostics, немає результату розбору файлу чи нічого збереженого для файлу, що було б відповіддю валідації для тексту, який демон має зараз: надішліть aggrega/validate і запитайте знову. Валідація, скасована на півдорозі, залишає файл у цьому стані, бо вона нічого не зберігає, а те, що попередня валідація знайшла щодо іншого тексту, не є відповіддю для тексту, який демон має зараз; попередня відповідь залишається чинною, доки текст той самий, який вона перевірила. Результати, які демон надсилає щодо файлу, який він сам прочитав із диска, — lockfile, що розійшовся з очікуваним станом, сутність Release, яка не завантажується, — не є валідацією тексту, який маєте ви, тож на цей запит вони теж не відповідають. До цього стану можуть призвести й дві валідації різних текстів, надіслані з невеликим інтервалом, коли першою завершилася та, чий текст демон зберіг: запит відхиляється, хоча цей текст було перевірено, а повторна валідація дає на нього відповідь. Це сформульовано в термінах розбору, а не файлу, бо буфер, який не прочитає жоден парсер, перебуває саме в такому становищі — валідація виконалася і повідомила, що знайшла, а розбору, з якого можна відповісти, досі немає. Validation-in-flight означає, що валідація файлу виконується і не завершилася в межах часу, який їй дозволив запит, що очікує: невдовзі запитайте знову і нічого не надсилайте, бо потрібний вам стан уже на шляху, а друга валідація лише додала б роботи. Якщо сприймати ці два коди як одну умову, клієнт надсилатиме валідацію саме тоді, коли це хибний крок. Дві смуги означають для клієнта різне: код 1xxx називає стан робочого простору, на який може вплинути користувач, — провалідувати файл, згенерувати lockfile, — тоді як стандартний код, як-от invalid-params, називає неправильно сформований запит, який виправляє клієнт, а не користувач. Значення release, яке присутнє, але сформоване неправильно — абсолютне або таке, що розв’язується за межами кореня робочого простору, — належить до другої смуги: виправляти треба не робочий простір, а запит. Пропуск release не належить до жодної смуги, бо це взагалі не помилка; він обирає вужчу з двох відповідей, описаних у розділі Жива валідація.

Помилка може містити об’єкт data, і кожен ключ у ньому називає одну річ і лише її. file — це вихідний документ, якого стосується збій: документ, що валідується, сутність Release, завантаження якої не вдалося, документ робочого простору, що оголошує ім’я, яке ніщо не розв’язало, або документ, на який указує відмова, що виникла під час рендерингу, — і саме в ньому супровідні line і column визначають позицію. Ці два ключі самі необов’язкові: збій, що стосується цілого документа, містить лише file. lockfile — це lockfile. release — це сутність Release, якої стосується помилка, записана так, як її назвав запит, тож клієнт може скласти aggrega pull --release <release>, не видобуваючи її назад із повідомлення. unreachable означає, що реєстр, названий у відхиленому запиті, був недосяжний: його містить відхилене оновлення індексу, що називає один реєстр, і це значення прочитано із самого збою, а реєстр, який відповів, залишає ключ відсутнім. Кожен ключ необов’язковий і присутній лише тоді, коли демон має це значення; жоден не замінює інший, тож те, на що вказує ключ, ніколи не залежить від коду поруч.

code і shortCode у data називають умову, про яку повідомляє відмова, у кожній відмові, що повідомляє про зареєстровану умову, незалежно від її числового коду: описовий код, за яким розгалужується програма, і короткий код, який цитує людина, — ті самі два ідентифікатори під тими самими іменами, що їх містить діагностичний запис для тієї самої умови, наведені в таблиці всіх умов. Розгалужуйтеся за code. Числовий код називає стан запиту і залишається тим самим для багатьох умов — збірка, відхилена через посилання каталогу, що веде назовні, і збірка, відхилена через ім’я, яке ні до чого не розв’язується, обидві мають 1004, — а повідомлення є прозою, яку можуть переформулювати, тож жодне з них не відрізняє одну умову від іншої. Invalid-params — один із таких спільних кодів: його отримує і запит, що називає робочий простір, файл конфігурації якого веде за його межі, і там read-leads-out-of-workspace повідомляє, що вада в структурі робочого простору, яку виправляє людина, а не в запиті. Відмова, що не повідомляє про зареєстровану умову, не містить жодного з цих ключів, і обидва присутні разом або не присутні взагалі. Повідомлення відмови, що називає умову, починається з її короткого коду, E0321: …, один раз — у такій формі людина бачить його в кожній такій відмові; відмові, повідомлення якої вже починається із заголовка у квадратних дужках, що містить код, — однорядкового звіту про документ каталогу, який відхилило завантаження, — він повторно не додається.

Звіт про те, як виконався каскад сутностей Release робочого простору, передається у відповіді на aggrega/activeRelease, у її полі trace, а не в помилці: робочий простір, що не вказує на жодну сутність Release, — це звичайний стан, а не невдалий запит. Це діагностична проза, написана для читання людиною, а не структура для розбору. Показуйте її як є — записуйте в журнал або в панель, яку користувач може відкрити, — і не зіставляйте з нею шаблони, не видобувайте з неї значення і не розгалужуйтеся за мітками, які вона використовує: її формулювання, компонування і ці мітки відстежують сам каскад і змінюються щоразу, коли змінюється каскад. Клієнт, що передає текст без змін, продовжує працювати після такої зміни; клієнт, що вивчив його форму, на ній ламається.

Див. також

  • ../schema/other/serve-wire.md — форми повідомлень, якими обмінюється цей протокол, згенеровані з опублікованої схеми: об’єкт параметрів кожного методу, кожен результат і корисне навантаження кожного сповіщення, поле за полем.
  • ./aggrega-build.md — команда збирання, конвеєр компілятора, перевірки й розв’язання залежностей якої також виконує aggrega/build, тож обидва інтерфейси записують одне дерево виводу, а не два.
  • ./aggrega-version.md — команда версії, якою розширення редактора перевіряє сумісність із демоном.
  • ./aggrega-pull.md — lockfile, який читає механізм виявлення розбіжностей демона.
  • ./aggrega-lint.md — домовленості публікації, про які демон звітує на запит, а також під час кожної валідації, щойно ввімкнено serve.lint_on_validate.

Синтаксис

aggrega serve [flags]

Опис

Run the Aggrega compiler as a long-running service. The daemon
reads JSON-RPC 2.0 messages from stdin and writes responses to stdout
under the aggrega/ method namespace. State (parsed YAML, diagnostics,
resolved catalog) holds across requests so IDE clients can issue many
cheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path every
aggrega command uses: --workspace-root when set (used as-is, validated
to exist as a directory), otherwise discovery walking upward from the
current working directory. A directory anchors the workspace when it
holds a .aggrega-config.yaml carrying a workspace: block, or — as a
fallback — any of .aggrega/, aggregate*.yaml, release*.yaml,
manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yaml
files from the workspace root down to the working directory (nearer
overrides farther), beneath which the global config file — the one
--config names, else the one the AGGREGA_CONFIG environment variable
names, else the default location when a file is there — and the
built-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for a
cooperative cross-platform exit: the daemon completes the in-flight
handler if any, refuses new requests with code 1005, and exits
cleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, or
a termination request from a supervisor or container runtime — takes
the same path on the same terms: the first request drains the daemon
and it exits cleanly, and a second ends the process at once.

Прапорці

ПрапорецьЗа замовчуваннямОпис
--build-on-inspectfalseВиконувати етап рендерингу артефактів під час перегляду графа IR, щоб попередження, які aggrega build видає під час рендерингу, також з’являлися як проблеми в редакторі. Не додає жодної з перевірок, на яких збирання зупиняється. На диск нічого не записується: ні відрендерених артефактів, ні каталогу виводу, ні lockfile. Вимкнено за замовчуванням, як і в aggrega inspect, яка теж не видає таких попереджень. Якщо задано, перевизначає ключ конфігурації serve.build_on_inspect.