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

Дисципліна трансляції помилок

Конвеєр компіляції Aggrega видає помилки з багатьох джерел — валідаторів схем, резолвера, будівника IR, провайдерів, рушія шаблонів Go, а також базових бібліотек YAML / Helm / docker-compose, які обгортають провайдери. Помилки, що доходять до CLI, починаються із заголовка у квадратних дужках, який називає до двох речей — категорію, що вказує, на яку частину слід звернути увагу (для більшості значень — на джерело авторингу, де виникла помилка), і короткий код умови, що зупинила збирання, — після чого йдуть вказівник на джерело та повідомлення. Якщо умову спричинив плагін, код уточнюється плагіном, який її спричинив, бо про ту саму умову може повідомити більш ніж один плагін. Ця сторінка описує форму такого виводу, щоб автори могли безпосередньо тлумачити повідомлення про помилки.

Каталог помилок (кожна фатальна зупинка з порадами щодо виправлення) наведено в fatal-halts.md. Чотири рівні валідації схем і взаємодію форм їхніх помилок описано в vocabulary/validation-surface.md.

Категорії помилок

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

  • [DEVELOPER_ERROR] — збій пов’язаний з авторингом сутності Aggregate. Виправлення потрібне в YAML сутності Aggregate або в частині каталогу, яку пише розробник (значення сутності Component, сокети uses, приєднання сутностей Feature). Приклади поверхонь: зупинки резолвера через проблеми на боці Aggregate; порушення селекторів і appliesTo у тому, що написав Aggregate.
  • [OPS_ERROR] — збій пов’язаний із власними документами оператора, Release і Manifest. Виправлення потрібне в YAML сутності Release (топологія меж, значення параметрів, приєднання сутностей Feature на рівні Release) або в YAML сутності Manifest (через який Recipe розгортається тип і прив’язки анотацій, записані поруч). Приклади поверхонь: валідація схеми Release; обчислення шаблонів шляхів меж; колізії subDirectory між провайдерами; відмови зіставлення та прив’язки анотацій у Manifest; правило, що відхиляє з’єднання, яке підключає Release, або приєднання, яке він заповнює на з’єднанні, — селектор сокета, селектор слота, слот, який сокет оголошує обов’язковим; правило, що відхиляє Feature, який приєднує лише Release, до компонента або до межі, — appliesTo цього Feature, селектор слота, його оголошена схема.
  • [CATALOG_ERROR] — збій пов’язаний із сутністю каталогу (Recipe, FeatureRecipe, Component, Feature, Plugin). Виправлення потрібне у вмісті каталогу. Приклади поверхонь: правила форми Recipe; перехресні перевірки featuresSchema сутності Workload; помилки розбору шаблонів у шаблонах, написаних у каталозі.
  • [TRANSLATION_ERROR] — збій пов’язаний із синтезом на боці провайдера (плагін провайдера намагається перекласти Workload, вивід valuesMapping або підключений оверлей у нативні артефакти провайдера). Виправлення зазвичай потрібне у формі services / containers / volumes сутності Workload, у виводі шаблону valuesMapping сутності Recipe або в структурі оверлею режиму source.
  • [FETCH_ERROR] — збій пов’язаний з отриманням закріпленої залежності з реєстру або віддаленого джерела, а не з будь-якою поверхнею авторингу. Виправлення зазвичай операційне: автентифікуйтеся в реєстрі (docker login <registry>), відновіть з’єднання або повторно закріпіть артефакт, що змінився чи був підроблений (aggrega pull --upgrade --release <release>). Приклади поверхонь: сутність каталогу або чарт не знайдено в реєстрі; автентифікація потрібна або не вдалася; мережа недоступна; дайджест кешованого артефакту не збігається з lock-файлом. Помилки отримання містять у повідомленні конкретну вказівку щодо усунення.
  • [POLICY_ERROR] — збірку відхилив плагін політик, приєднаний у ролі вердикту управління. Це не збій поверхні авторингу: вхідні дані коректні, але не проходять правило управління (відповідності, FinOps або безпеки), яке застосовує плагін. Виправлення полягає в тому, щоб привести написане вами у відповідність до застосовуваної політики або переглянути приєднання політики. Повідомлення називає плагін, що відхилив збірку, і містить надане ним повідомлення правила.
  • [TRUST_ERROR] — рівень довіри та підписування відхилив операцію. Ця категорія називає аспект, а не поверхню авторингу, і охоплює два способи виправлення, які можна розрізнити за коротким кодом поруч. Ваша конфігурація довіри неправильна: політика довіри, яку неможливо прочитати, закріплений корінь довіри, який неможливо завантажити, keyless-політика, що не оголошує жодної довіреної ідентичності, політика підписування, що вимагає підпис для типу артефакту, який ви публікуєте, або плагін, записаний як довірений для приєднання вердикту, яке ваша конфігурація більше не приєднує. Цей артефакт не пройшов перевірку: підпис, що не перевіряється відносно якоря довіри, артефакт без підпису там, де він потрібен, підпис від справжнього, але недовіреного підписувача, або плагін, записана довірена ідентичність якого більше не збігається з тим, що резолвиться. У першому випадку виправлення потрібне у вашій конфігурації або в закоміченому записі довіри; у другому — це рішення щодо артефакту: відновіть перевірений або перевірте й повторно запишіть те, що змінилося.

Знахідка щодо приєднання сутності Feature відповідає документу, що його записав

Feature можна приєднати в будь-якому з документів — Aggregate приєднує його на компоненті або на підсистемі, Release — у своєму записі для компонента або на межі, — тож категорія знахідки щодо приєднання визначається тим, де приєднання записано, а не компонентом, якого воно стосується. Знахідка позиціонується на записі features:, який записав приєднання, у тому документі, і відноситься до автора цього документа: приєднання, яке робить лише Release, повідомляється за власним шляхом Release як [OPS_ERROR], а те, яке робить Aggregate, — за шляхом Aggregate як [DEVELOPER_ERROR].

[OPS_ERROR E0007] release.yaml at .spec.boundaries.main.components.app.features.metrics
selector violation ("component.aggrega.ai/type in (server, worker)", declared by Feature "core/prometheus-exporter", not satisfied by the labels of "app"). Add the labels the Feature's appliesTo requires to this component's type, or attach a Feature whose applicability the component already satisfies.

Там, де одне приєднання записують обидва документи — Aggregate називає свій Feature, Release задає його розміри, — знахідка щодо приєднання в цілому позиціонується там, де названо його Feature, тобто в Aggregate. Знахідка щодо однієї частини його конфігурації позиціонується там, де цю частину записано: його values належать розробникові, в Aggregate, а його infra — операторові, в Release. Приєднання, створене розгортанням на основі анотацій, не записав жоден запис features:, тож знахідка щодо нього позиціонується на компоненті, у документі, що оголошує компонент, як [DEVELOPER_ERROR].

Обов’язковий слот, залишений порожнім, — це єдиний випадок, який не записав жоден документ. Немає приєднання, на яке можна вказати, тож знахідка залишається на компоненті в Aggregate і відноситься до [DEVELOPER_ERROR], а її спосіб виправлення називає обидва документи, бо слот може заповнити будь-який із них: «Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it.» (Приєднайте Feature із цим іменем в Aggregate або в Release, на компоненті або в області видимості над ним.)

Редактор використовує те саме розміщення: знахідка, позиціонована в Release, показується в документі Release, на ключі, який її записав, і зовсім не показується в документі Aggregate; знахідка, позиціонована в документі модуля, який імпортує Aggregate, так само показується в документі цього модуля.

Форма виводу

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

[CATEGORY SHORTCODE] <source>
<message>

Заголовок містить два токени, і вони відповідають на різні запитання. Категорія — одна з наведених вище — вказує, яку область слід розглянути. Короткий код — це літера E і чотири цифри, і він називає точну умову, що зупинила збірку: наведіть його у звіті, введіть у пошук або знайдіть у таблиці всіх умов у sentinels.md. Жоден не виводиться з іншого, тому друкуються обидва, — а там, де категорія охоплює більше ніж один спосіб виправлення, як [TRUST_ERROR], саме короткий код підказує, з яким ви зіткнулися.

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

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

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

[CATEGORY PLUGIN/SHORTCODE] <source>
<message>

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

Останній сегмент розшифровується так само, як будь-який інший короткий код, хоч який плагін його згенерував: його наведено в таблиці всіх умов у sentinels.md, і aggrega explain його розшифровує. Цитуйте лише останній сегмент — кваліфікатор указує, який плагін натрапив на умову, а не яка це умова. Якщо плагін називає код, який Aggrega не оголошує, — номер, якого не має жодна умова, або виведений з ужитку, — цей код не друкується: збирання зупиняється на E0293, уточненому цим плагіном, а його повідомлення цитує код, запропонований плагіном, називає ті загальні умови й зберігає власне речення плагіна.

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

Будь-який токен може бути відсутнім, і відсутній пропускається

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

  • Немає короткого коду. Збій не називає жодної власної умови Aggrega — найчастіше це помилка, про яку повідомила бібліотека, яку обгортає компілятор. Заголовок друкує лише категорію, тож ви все одно знаєте, яку область розглянути.
  • Немає категорії. Збій не має області, до якої вас скерувати, тому жодну не вгадують. Заголовок друкує лише короткий код, і саме код ви шукаєте. Таке виникає у двох ситуаціях, і вони виглядають однаково, бо для ваших цілей вони однакові — жодна не вказує, куди дивитися, а код повідомляє, що сталося. Перша — помилка в самому компіляторі, коли повідомлення про це каже і просить вас повідомити про неї; на практиці це випадок, коли власні подання каталогу в компіляторі суперечать одне одному. Друга — збій, що називає умову, але ніколи не проходив через область, яка відносить його до певної категорії, що є звичайною формою для відмови на межі команди. Категорію ніколи не вигадують, щоб заповнити прогалину, і в цьому сенс пропуску, а не його обмеження: категорія відповідає на запитання «яку область мені розглянути», а відповідь, надана там, де в запитання її немає, — не обережна відповідь, а хибна, за якою діятимуть насамперед. Варто також сказати, що зворотний висновок не діє: заголовок, який має категорію, не завжди вказує на щось, що ви написали, бо [FETCH_ERROR], [POLICY_ERROR] і [TRUST_ERROR] називають область, а не поверхню авторингу.
  • Немає жодного. Квадратні дужки повністю пропускаються, і діагностика — це саме повідомлення. Це збій, що не називає жодної власної умови Aggrega і не має області, до якої вас скерувати: команда, що відхиляє свої аргументи, файл, який вона не може прочитати, скасування або помилка, про яку повідомила бібліотека, яку обгортає компілятор, без жодної нашої умови під нею. Немає нічого, що можна знайти в sentinels.md, і повідомлення — це все, що збій має сказати.

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

[CATEGORY] <source>: <message>

Категорія, відсутня в заголовку, відсутня і тут, разом із дужками, тож цей рядок ніколи не має вигляду [] <source>: <message>. Однорядкова форма повторно обгортається в зовнішні фрейми, коли збій піднімається вгору, тож порожній тег переносився б у кожен із них.

Джерело — це структурований вказівник: зазвичай <file>:<line>:<column>, коли доступна позиція в YAML, або логічний ідентифікатор (ім’я сутності каталогу, ім’я Release, шлях межі), коли позиція у файлі не застосовна. Третя форма, <file> at <key>, з’являється, коли вказівник знає і документ, і ключ авторингу в ньому, але не позицію в байтах: файл — це те, що ви відкриваєте, а ключ — те, на що дивитися після відкриття. Повідомлення — це діагностика відповідної поверхні.

Збій, що стосується одного екземпляра вашої збірки — компонента, компонента, який вносить модуль, або самого модуля, — називає цей екземпляр після позиції у формі (instance <name>), тож aggregate.yaml (instance shop) — це Aggregate, що оголошує модуль shop. Якщо збій не має документа, на який можна вказати, екземпляр стоїть окремо як instance <name>: провайдер, що зазнає збою під час рендерингу компонента adminer, виводить [TRANSLATION_ERROR E0082] instance adminer, а рядки під ним містять решту збою, зокрема будь-який документ, який він називає. Ім’я — це те, під яким Aggregate оголошує компонент; компонент, який вносить модуль, називається своїм шляхом через модуль, наприклад shop.cart. Екземпляр ніколи не виводиться там, де має бути файл, тож те, з чого починається вказівник джерела, — це завжди документ, який можна відкрити, або один із наведених вище логічних ідентифікаторів.

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

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.checkout
missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.inventory
missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")

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

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

[CATEGORY SHORTCODE] <source>
<message>
expression: <the template excerpt that triggered the failure>
active pillars:
<one line per top-level pillar key in scope at the point of failure>

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

Вкладені фрейми контексту

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

[CATALOG_ERROR E0094] aggrega-catalog
catalog load
caused by: [CATALOG_ERROR] aggrega-catalog/recipe/compose/mariadb-copy/1.0.0/recipe.yaml
duplicate entity identity within a single catalog directory (recipe identity "compose/mariadb:1.0.0")

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

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

Ланцюжок стає глибшим щоразу, коли помилка перетинає більше поверхонь на шляху назовні, і правило діє на будь-якій глибині. Шаблон, відхилений усередині синтезованого Workload сутності Recipe, перетинає три: вузол, що рендериться, поверхню шаблонів Recipe і сам шаблон:

[CATALOG_ERROR E0060] instance db
rendering node "db"
caused by: [CATALOG_ERROR]
recipe "mariadb" workload template
caused by: [CATALOG_ERROR] workload[mariadb]
template references a root the render context does not define (template "workload[mariadb]" references ".nosuchroot.database", the render context defines .context, .values, .infra, .locals, .provides, .features, .metadata, .attachment_name, .inject, .inject_raw, .steps, .source, .workload, .boundary)

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

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

[OPS_ERROR E0099]
recipe resolution
caused by (2):
[OPS_ERROR] .spec.components.edge
no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.edge, "edge", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it
---
[OPS_ERROR] .spec.components.internal
no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.internal, "internal", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it

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

Скрізь діє одна граматика роздільників: --- між сусідніми помилками, caused by: між вкладеними фреймами контексту.

Відхилений файл каталогу та збій, який він пояснює

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

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

[CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml
document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema
note: this file was skipped at load, so the catalog holds nothing under the identity it declares.
This Release reaches that identity, so what failed is the attempt to resolve the reference to it:
resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"

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

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

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

[E0105]
resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"
note: catalog files skipped at load. A refusal outside this Release's closure is tolerated and never fails a build,
so this failure is explained only by a refusal naming something this Release reaches:
- Recipe "server-recipe" (catalog/recipes/helm/server.yaml): [CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml: document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema

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

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

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

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

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

Файл, що оголошує вид, якого не містить жоден каталог, називається лише там, де він пояснює збій. Документ, який оголошує apiVersion Aggrega і kind, якого не містить жоден каталог, — наприклад, Componnent із помилкою в написанні, — пропускається кожним завантаженням, тож він не є відмовою і не наводиться серед відмов. Коли посилання, що не вдалося, запитує ім’я, яке оголошує цей файл, і версію, якщо посилання її вказує, звіт називає файл в окремій примітці під збоєм, незалежно від того, до якого виду посилання було віднесено під час збирання, — на кожній поверхні, переліченій нижче, і в aggrega build, незалежно від того, чи читає він наявний lock-файл, чи спершу заповнює його:

[E0114]
resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>)
note: a catalog file declares the name this reference asks for under a kind a catalog does not hold,
so the load skipped it:
- Componnent "<name>" (<path>): [CATALOG_ERROR E0371] <path>: catalog document declares a kind a catalog does not hold (kind "Componnent"). a catalog holds Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Aggregate and Plugin documents, and passes over a Workload, a Manifest or a Release; correct the kind, or move the file out of the catalog directories

Збій і далі йде першим: вид, який оголошує файл, не задає жодної ідентичності, тож файл ніколи не виокремлюється як відмова, з якої починається звіт. Пояснення того, звідки читаються локальні сутності, не включається до цього звіту, бо файл уже лежить там, звідки читає каталог, і його переміщення не допомогло б. Файл виду, якого не містить жоден каталог, що оголошує якесь інше ім’я, нічого не пояснює щодо цього збою і не згадується. aggrega serve, повідомлення якого займають один рядок, містить ту саму примітку в цьому рядку — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it:, а після неї відмову файлу, — і ніколи не наводить такий файл серед файлів, пропущених під час завантаження; інструмент describe з aggrega mcp, коли в нього запитують ім’я в термінах сутності Release, так само називає файл замість цього пояснення. aggrega validate і aggrega lint для всього каталогу повідомляють про кожен такий файл незалежно від того, чи щось до нього доходить, — див. fatal-halts.md §«A catalog document declares a kind a catalog does not hold (Документ каталогу оголошує вид, якого каталог не містить)».

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

Якщо відхилений документ сам є тим, про що звітує команда, відхилення повідомляється один раз. aggrega inspect <name> завантажує каталог суворо, тож документ, який завантаження відхиляє, зупиняє його, і виводиться відхилення цього документа як єдина діагностика: заголовок із категорією та коротким кодом відхилення, документ як його джерело, а під ним те, що не так із документом, — для порушення схеми це порушені ключі з їхніми рядками й стовпцями та порада. Завантаження, яке його видало, пройшло через каталог, який обходило, і крок, що читав файл, але вони не виводяться як окремі фрейми, бо кожен знову назвав би той самий документ, не додавши жодного факту. aggrega serve, коли його запитують, на що посилається ім’я, яке оголошує відхилений документ, відповідає тим самим відхиленням тими самими словами в одному рядку, після чого йде примітка, що файл було пропущено під час завантаження. Як і вище, умова відхилення в будь-якому разі лишається придатною для зіставлення.

Обидві форми доходять до вас усюди, де виконується це розв’язання. aggrega build, aggrega pull, aggrega validate --release і aggrega inspect --closure виводять їх у терміналі, як і aggrega validate над однією сутністю Recipe, ціль implements якої не знайдено, а ШІ-асистент, підключений через aggrega mcp, отримує той самий звіт від інструментів build і validate, а також першу відмову одним рядком під час читання через catalog:// сутності, яку оголошує відхилений файл. Те, з якої поверхні ви запитали, нічого не змінює в тому, який файл вам пропонують відкрити, — клієнт, що звертається до aggrega mcp через HTTP, отримує шлях відносно кореня робочого простору й не отримує шляху поза робочим простором, який обслуговує цей сервер, — а там, де першим іде відхилення, контракт написання, на який вказує відповідь, стосується виду, що його оголошує відхилений документ, — а не виду посилання, яке завершилося збоєм.

Клас збоїв конверта документа

Кожен документ сутності — сутності каталогу, Aggregates, Manifests, Releases — під час завантаження, ще до типізованого розбору, перевіряється на відповідність опублікованій JSON-схемі свого виду. Документ, що порушує свій конверт (невідомий ключ, відсутнє обов’язкове поле, значення неправильної форми, заборонена конструкція, як-от values: у Release), гучно зупиняє роботу з діагностикою, яка спершу називає умову, потім вид сутності й файл, потім кожен проблемний ключ або форму з рядком і стовпцем, де він розташований, і нарешті — що з цим робити:

[OPS_ERROR E0215] release.yaml
document envelope validation failed (Release, at release.yaml); 12:7: spec.boundaries.main.values: against /$defs/boundary: unexpected property: "values". correct the document to match its kind's schema

Діагностика починається з умови, називає вид і файл і завершується тим, що робити; кожне порушення між ними містить лише line:column, оскільки заголовок уже назвав файл. Кожен проблемний ключ повідомляється у власній позиції, а не в позиції блоку, що його містить, тож рядок і стовпець вказують на ключ, який потрібно змінити. Якщо форма в цій позиції походить із повторно використовуваного визначення в схемі, діагностика називає це визначення після слова against — against /$defs/boundary вище, — щоб було зрозуміло, з яким контрактом звірявся ключ, і щоб визначення не читалося як ще один крок шляху ключа, який ви написали. Документ із кількома порушеннями перелічує кожне в його власній позиції, у порядку ключів, а звіт зупиняється після чотирьох, подаючи кількість решти.

Про те, куди вказує позиція, варто знати дві речі, бо обидві корисні, а не несподівані:

  • Відсутній обов’язковий ключ не має власної позиції — його за визначенням немає в документі. Натомість порушення вказує на охопний ключ, саме там і має бути відсутній запис. Тож spec.capability: missing required property вказує на spec:, і саме туди його слід додати.
  • Ключ, власна назва якого містить крапку, — кожна мітка component.aggrega.ai/… і анотація features.aggrega.ai/… — повідомляється на рівні блоку, що його містить, а не самого запису, оскільки крапки читаються як кроки вглиб документа. Порушення в мітці вказує на labels:.

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

Категорія відповідає поверхні авторингу: [CATALOG_ERROR] для сутностей каталогу, [DEVELOPER_ERROR] для Aggregates, [OPS_ERROR] для Releases і Manifests. Та сама перевірка працює на кожній поверхні, що завантажує сутності, — aggrega build, aggrega lint, aggrega validate і діагностика редактора, яку публікує aggrega serve, — тож зайвий або написаний з помилкою ключ відхиляється там, де документ уперше прочитано, а не мовчки відкидається. Кожна з цих поверхонь визначає позицію однаково, тож вони вказують на той самий ключ, і кожна бере речення умови з самої умови: рядок, який підкреслює ваш редактор, — це рядок, який називає термінал, а речення, яким починається запис редактора, — це речення, яким починає термінал. Чого дві поверхні не поділяють, то це повного повідомлення, і це навмисно: термінал групує всі знахідки під одним заголовком і завершує порадою для шляху, тоді як редактор видає по одному запису на знахідку, розміщеному на її власному ключі, не повторюючи ні файлу, до якого він уже прив’язаний, ні поради, яку інакше довелося б повторювати для кожного підкреслення. Отже, збігається саме та частина, за якою ви впізнаєте умову.

Ланцюжки з кількох помилок

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

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge.uses.reviewed_upstream.internal
selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.
---
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge2.uses.reviewed_upstream.internal
selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

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

Читання помилки від початку до кінця

У більшості контекстів створення префікс категорії разом із вказівником на джерело визначають, що саме слід виправити:

КатегоріяДе виправлятиПриклади проявів
[DEVELOPER_ERROR]YAML сутності AggregateПорушення селекторів / appliesTo у тому, що написав Aggregate; невідповідність сокета uses на боці Aggregate; зупинки резолвера через написане розробником.
[OPS_ERROR]YAML сутності Release / YAML сутності ManifestШаблон шляху межі посилається на непідтримуване поле; subDirectory спричиняє колізію шляхів; зупинки резолвера через написане в Release; з’єднання, яке створює Release, або вкладення, яке воно заповнює на з’єднанні, відхилене правилами сокета чи слота; Feature, яку приєднує лише Release, до компонента чи до межі, відхилена правилами Feature чи слота; відхилено зіставлення або прив’язку анотації в Manifest.
[CATALOG_ERROR]Recipe / FeatureRecipe / Component / Feature / PluginПравила форми Recipe; шаблон FeatureRecipe посилається на поле, доступне лише для окремого компонента, за executionScope: boundary; перехресна перевірка featuresSchema сутності Workload не проходить.
[TRANSLATION_ERROR]Workload / вихід valuesMapping / накладання джерелаВизначення порту проби Helm; колізія імен сервісів compose між межами; два учасники compose оголошують один том або ім’я конфігурації верхнього рівня з конфліктними тілами; невідповідність імені чарта в парасольковому helm-chart.
[FETCH_ERROR]Реєстр / отримання з віддаленого джерела (операційне, не пов’язане зі створенням)Артефакт не знайдено в реєстрі; потрібна автентифікація; мережа недоступна; кешований дайджест не збігається з lock-файлом. Виправлення: автентифікуйтеся, відновіть з’єднання або виконайте aggrega pull --upgrade --release <release>.
[POLICY_ERROR]Plugin політики (правило керування)Plugin політики, приєднаний у ролі вердикту керування, відхилив зібрану збірку згідно з правилом, яке він застосовує. Виправлення: задовольніть застосовану політику або перегляньте приєднання.
[TRUST_ERROR]Конфігурація довіри або власний підпис артефакту (проблема, а не поверхня створення)Нечитабельна політика довіри або закріплений корінь довіри; безключова політика, що не оголошує жодної довіреної ідентичності; політика підписування, що вимагає підпису для виду, який публікується; записаний шлюз приєднання вердикту, який конфігурація більше не приєднує. Або: підпис, що не проходить перевірку; артефакт без підпису там, де він потрібен; недовірений підписант; plugin, чия записана довірена ідентичність більше не збігається. Виправлення: виправте конфігурацію або зафіксований запис довіри чи ухваліть рішення щодо артефакту — короткий код указує, що саме.

Префікси контексту окремого провайдера (helm: node "<id>": ..., compose: node "<id>": ...) з’являються в частині повідомлення виводів [TRANSLATION_ERROR] і [CATALOG_ERROR], щоб локалізувати провайдера зі збоєм, коли задіяно більше одного провайдера.

Власні помилки бібліотек

Помилки, що виникають усередині базової бібліотеки (помилки завантаження чартів Helm SDK, помилки парсера YAML docker-compose, помилки файлового вводу-виводу через відсутній шлях до джерела), обгортаються контекстним префіксом відповідного провайдера й з’являються під [TRANSLATION_ERROR] або [CATALOG_ERROR] залежно від того, чи спрацювали вони під час синтезу, чи під час завантаження вмісту каталогу. Обгорнуте повідомлення бібліотеки дослівно зберігає діагностику оригінального інструмента, щоб автори могли зіставити його з власною документацією цього інструмента.

Перехресні посилання

  • fatal-halts.md — каталог усіх фатальних зупинок за окремими помилками з очікуваним повідомленням і способом виправлення.
  • warnings.md — нефатальні попередження, які видає компілятор.
  • vocabulary/validation-surface.md — чотири рівні валідації за схемою і те, як взаємодіють форми їхніх помилок.