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

aggrega validate

aggrega validate перевіряє коректність — схему, структуру стовпів, розв’язання посилань між документами, ланцюжки extends, здатність провайдера щодо типу вхідних даних і (для сутності, що рендериться) те, що вона справді рендериться. Команда має три режими, які обираються її аргументом і застосовують ту саму дисципліну коректності на трьох рівнях: увесь каталог (без аргументу), замикання залежностей однієї сутності Release (--release) та файл однієї сутності (шлях до сутності). Кожен рівень відповідає на те саме запитання — «чи коректний цей вміст?» — для різної частини каталогу.

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

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

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

Коректність усього каталогу (без аргументу)

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

  • Структура опори схеми — блок spec.schema: кожної сутності Component і Feature розгортається й перевіряється (та сама перевірка опори схеми, яку застосовує збірка), зокрема з розгортанням компактної форми.
  • Розв’язання посилань між документами — посилання $ref і $import на записи SchemaLibrary розв’язуються, а SchemaLibrary, яку неможливо розв’язати або яка є некоректною з іншої причини, відхиляється.
  • Ланцюжки extends — кожна сутність, що оголошує extends, розв’язується відносно свого батька, і перевіряється об’єднана форма батько+нащадок. Батько, якого немає в директоріях каталогу, читається там, де його читає збірка: з кешу артефактів, за закріпленням, яке lock-файл сутності Release записує для нього, — з lock-файлів сутностей Releases, для яких виконується прохід, або кожної сутності Release у робочому просторі, коли його перевіряють за один прохід. Тож база, опублікована в реєстрі, проходить валідацію, щойно aggrega pull отримає й закріпить її, а батько, якого немає ні там, ні там, зупиняє запуск, називаючи aggrega pull --release <release>. Нічого не завантажується.
  • Оголошені селектори — кожен селектор міток, який документ сутності Component чи Feature оголошує на сокеті залежності в spec.usesSchema або на слоті вкладення в spec.featuresSchema — зокрема, для Component, на слотах, які оголошує сокет, — читається за граматикою селекторів, незалежно від того, чи щось під’єднано до сокета або заповнює слот. Див. оголошені селектори.
  • Колізії розташувань OCI — дві різні ідентичності каталогу, які публікувалися б в одне розташування реєстру, явно відхиляються, тож збірка ніколи непомітно не перезапише опубліковані байти однієї сутності байтами іншої.
  • Здатність Provider щодо типу вхідних даних — сутність Recipe або FeatureRecipe, що оголошує блок workload:, прив’язаний до провайдера, який не може виконувати синтез, позначається як помилка, оскільки її ніколи не вдасться зібрати.

Це загальнокаталожний відповідник перевірки збірки для кожної сутності Release — місце, де має виявлятися зламана сутність каталогу, ще до того як її досягне будь-яка сутність Release. Команда явно зупиняється на документі Aggrega, який не вдається завантажити, і за будь-якого порушення опори схеми, нерозв’язної чи некоректної бібліотеки, збою розв’язання extends, оголошеного селектора, який відхиляє граматика, колізії розташувань або помилки можливості щодо типу входу. Висновки про перекриття опор схеми та звуження під час розширення, а також кожне ключове слово x-aggrega-*, яке сутність Component чи Feature пише безпосередньо у вмісті своєї схеми, — це рекомендаційні рядки notice:, які ніколи не змінюють код виходу.

Документ Aggrega, який не вдається завантажити, зупиняє запуск. YAML-файл у каталозі каталогу є документом Aggrega, якщо один із його рядків починається без відступу з apiVersion: і значення, що починається з aggrega.ai/, у лапках чи без. Такий файл, який не вдається прочитати, YAML якого не розбирається або чиї kind чи metadata не мають форми оболонки сутності — наприклад, metadata, записаний списком, — зупиняє запуск з E0175 після того, як каталоги прочитано, називаючи кожен такий файл і причину, яку дало читання або парсер; нічого не перевіряється, і рядок catalog validation passed не виводиться. Документ, який завантажується, але оголошує kind, якого не містить жоден каталог, — наприклад, Componnent із помилкою в написанні або взагалі без kind, — зупиняє той самий запуск з E0371 і називається поряд із ними разом із видом, який він оголошує; документи Manifest і Release, а також документ Workload, який сутність Recipe імпортує з власного каталогу, пропускаються. Будь-який інший YAML — шаблони Helm-чарту, які не розбираються до рендерингу, значення чарту, визначення робочих процесів — пропускається.

Які каталоги читаються, залежить від структури робочого простору:

  • Робочий простір, конфігурація якого не задає власних каталогів для сутностей Release, перевіряється один раз за своїм стеком пошуку: каталоги --catalog, потім workspace.catalog_dirs, потім каталог catalog у корені робочого простору, якщо він є.

  • Робочий простір, що називає сутності Releases у workspace.releases, може зберігати каталог у кількох варіантах поруч, кожен з яких читає власна сутність Release, і завантаження їх усіх одночасно звело б усі варіанти в один каталог, де сутність одного варіанта затіняла б сутність іншого. Тому він перевіряється один раз для кожної сутності Release у робочому просторі, за каталогами, які читає ця сутність Release, причому каталоги --catalog ідуть першими в кожному проході; сутність Release, яку конфігурація не називає, читає список робочого простору. Кожен прохід звітується під рядком, що називає його сутність Release і прочитані каталоги, після чого йде результат цього проходу:

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    Сутності Releases, які читають точно ті самі каталоги, мають спільний прохід, що називає кожну з них. Сутність Release, яка не читає жодного каталогу — її запис містить catalog_dirs: [], — звітується як така, що не має чого перевіряти, а інші проходи виконуються як зазвичай. Кожен прохід звітується незалежно від того, що знайшов попередній, адже зламана сутність в одному варіанті нічого не говорить про інший, і команда завершується невдачею, якщо невдалий будь-який прохід, називаючи сутності Releases, чиї каталоги не пройшли перевірку. Сутності Releases робочого простору — це його документи Release: файли YAML, у яких kind дорівнює Release, будь-де під коренем робочого простору поза прихованими каталогами та node_modules, vendor і dist.

Запуск, у якому жоден прохід не має чого читати, відхиляється, а не звітується як чистий каталог: розмістіть сутності в catalog/, передайте --catalog або задайте workspace.catalog_dirs — чи, у робочому просторі, що називає сутності Releases, власний catalog_dirs сутності Release у workspace.releases. Команда ніколи неявно не перелічує поточний робочий каталог, тож ніколи не захоплює сторонні дерева.

Інструмент validate у aggrega mcp, запитаний про весь каталог, перевіряє ті самі проходи; у робочому просторі, що називає сутності Releases, його відповідь містить кожен із них у passes — сутності Releases, прочитані каталоги та власний вердикт цього проходу — поруч із вердиктом щодо всіх них.

Бібліотека, яка є лише в кеші артефактів

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

  • Без аргументу, а також зі шляхом до сутності, незалежно від того, чи вказано --release, validate читає бібліотеки лише з директорій каталогу, ніколи через запис lock-файлу, тож зафіксований запис не змінив би його вердикту. Рядок повідомляє про це й указує на створення бібліотеки в директорії каталогу або на aggrega pull --release <release>, після якої виконується aggrega validate --release <release>, що перевіряє Release щодо бібліотек, які закріплює її lock-файл.
  • Лише з --release validate читає lock-файл сутності Release, тож рядок називає aggrega pull --release <release>, яка розв’язує бібліотеку і фіксує її запис, або створення бібліотеки в директорії каталогу.

Цей рядок не змінює ні вердикту, ні коду виходу.

Оголошені селектори

Сутність Component чи Feature обмежує селекторами міток, що можна під’єднати до її сокетів залежностей і що може заповнити її слоти вкладень, — це selector: кожного запису spec.usesSchema і кожного запису spec.featuresSchema, а для Component — selector: кожного слота, який сокет оголошує у власному featuresSchema. Збірка читає селектор лише там, де до нього щось доходить: ребро, прокладене через сокет, або вкладення, що заповнює слот. Тож область усього каталогу й область окремої сутності читають кожен селектор, який оголошує документ сутності Component чи Feature, незалежно від того, чи щось під’єднано до сокета або заповнює слот, і селектор, який відхиляє граматика, — список значень без закривної дужки, подвоєна кома, ключ, що містить = або !, — провалює перевірку. Це граматика, описана в розділі граматика рядків.

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

selector violation ("<selector>", declared on socket "<socket>", which could not be evaluated: "<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (порушення селектора: селектор, оголошений на сокеті, не вдалося обчислити. Виправте селектор в оголошенні сокета в usesSchema типу компонента.)

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

Область усього каталогу повідомляє кожен відхилений селектор в окремому рядку selector: і завершується невдачею з їхньою кількістю; область окремої сутності повідомляє їх як невдачу свого рівня форми — з --release поруч зі шляхом до сутності чи без нього, бо ця форма є областю окремої сутності, запущеною в термінах Release (див. перевірка сутності в термінах Release). Сам лише --release, який валідує замикання залежностей Release, і збірка читають селектор лише там, де до нього доходить ребро чи заповнення, і саме там на ньому зупиняються.

Коректність у межах сутності Release (--release)

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

  • розв’язує ланцюжки extends у межах замикання, завершуючись помилкою в разі помилки розв’язання;
  • перевіряє стовпи схеми кожної розв’язаної сутності (у межах замикання), завершуючись помилкою в разі помилки стовпа схеми;
  • виконує ту саму перевірку відповідності значень перед рендерингом, що й збірка: підставляє параметри сутності Release в авторські значення (тож значення {{ .parameters.* }} перевіряється як розв’язане, а не як шаблон) і перевіряє результат за складеними схемами замикання, зокрема відповідність складеній схемі батька й нащадка для сутності, що використовує extends. Значення, що порушує свою схему, призводить до ненульового коду виходу;
  • оцінює кожне твердження Recipe і FeatureRecipe щодо значень, до яких розв’язується сутність Release, так само як збірка оцінює їх перед рендерингом: сутність Recipe кожного компонента прив’язується так, як її відображає сутність Manifest, її locals і provides розв’язуються, і перше твердження, що не справджується, — яке викликає fail або шаблон якого зупиняється на ключі, якого не знаходить, — провалює валідацію з тією умовою та реченням, з якими зупиняється збірка. Шаблон locals чи provides, який не вдається обчислити, теж провалює валідацію, як провалює збірку. Провайдера, через якого рендерить кожна сутність Recipe, запитують про назву, яку він дає ресурсам цього компонента, так само як його запитує збірка, бо provides сутності Recipe може читати цю назву; нічого не рендериться. Ці твердження оцінюються лише тоді, коли ніщо вище ще не провалилося, тож сутність Release повідомляє найранішу помилку, на якій зупинилася б збірка;
  • виводить знахідки щодо перекриття стовпів схеми та звуження під час розширення як інформаційні рядки notice:, які ніколи не змінюють код виходу;
  • показує кожне ключове слово x-aggrega-*, яке прочитана нею сутність пише безпосередньо у вмісті своєї схеми, як рядок warning:, один раз на сутність, так само як його показує збірка, — і воно теж ніколи не змінює код виходу.

Завдяки цьому --release є справжньою перевіркою перед збіркою: він виявляє те, що збірка відхилила б, ще до збірки — перевірка залежностей збірки без рендерингу. Він не виконує рендерингу й не ініціює завантаження з мережі: замикання розв’язується з локального каталогу (і з фіксацій lock-файлу сутності Release, якщо він є); набір залежностей, зафіксованих у реєстрі, якому потрібен lock-файл, дає чесну помилку нерозв’язного посилання замість завантаження. Звуження повідомляється як порада і ніколи не примусово застосовується.

Lock-файл, який більше не відповідає тому, до чого розв’язується Release, відхиляє валідацію із зупинкою, яку виводить aggrega build. Якщо поруч із Release є lock-файл, --release звіряє його з тим, до чого розв’язується Release, за допомогою порівняння розбіжностей, яке збірка виконує перед рендерингом, щойно залежності Release розв’язано і до запуску будь-якої з перевірок вище. Lock-файл, від якого розійшлися закріплена сутність, бібліотека, плагін чи сам файл Release, зупиняє валідацію відмовою збірки E0130 — кожен запис, що розійшовся, а потім aggrega pull --release <release>, який це усуває, — і ненульовим кодом виходу, тож валідація ніколи не пропускає lock-файл, який збірка відхиляє через розбіжність. Без аргументу та зі шляхом до сутності validate не підпорядкована lock-файлу: перевірка всього каталогу читає закріплення lock-файлу лише для того, щоб знайти батька extends, а перевірка однієї сутності не читає lock-файлу.

Оскільки він виконує ті самі перевірки, що й збірка, він також запускає ті самі приєднані плагіни-шлюзи — тож до нього застосовується той самий запис довірених ідентичностей плагінів, що й до збірки. Робочий простір, який приєднує плагін із вердиктом «прийняти чи відхилити», має запис довіри до плагінів поруч зі своєю сутністю Release, і --release порівнює з ним конфігурацію до запуску будь-якого з цих плагінів: записаний шлюз, який конфігурація більше не приєднує, зупиняє перевірку, а плагін, розв’язаний із кешу, який заповнює aggrega pull, артефакт якого не збігається із записаним, відхиляється замість запуску. Робочий простір, який нічого не записав, не має запису, що нічого не змінює для цього порівняння. --release також називає кожне відкликання, записане щодо того, від чого залежить Release, у стандартному потоці помилок як рядок deprecation: у формулюванні, яке виводить aggrega build: як маркер, який lock-файл записує щодо закріпленого посилання, так і маркер, який запис довіри записує щодо плагіна, приєднаного в ролі вердикту. Відкликання не змінює ні вердикту, ні коду виходу, а запис довіри, який існує, але не може бути прочитаний, зупиняє перевірку, а не вважається записом, у якому нічого не записано.

Плагін, прочитаний із кешу, також перевіряється на відповідність підпису, який фіксує його запис, так само як і під час збірки, у момент завантаження. Якщо його запис фіксує перевірений підпис, матеріал підпису, на який вказує цей факт у кеші, перевіряється знову, і плагін, матеріал якого відсутній або відрізняється, відхиляється — так само як і плагін, матеріал якого створено для іншого плагіна, ніж прочитаний, що й видає signature, скопійований з іншого запису, незалежно від вимоги щодо підпису. Якщо конфігурація довіри робочого простору вимагає підпис, плагін, прочитаний із кешу, запис якого не фіксує жодного підпису — або для якого запис не містить жодного запису, зокрема видалений запис, — теж відхиляється за тих самих налаштувань, за яких aggrega pull відхилив би його як непідписаний, тож skip_signature_verification і реєстр advisory дозволяють йому запуститися. Відхилення призводить до невдачі перевірки й повідомляється серед її діагностик із назвою плагіна та aggrega pull --release <release> — командою, яка перевіряє його підпис у реєстрі, записує його й кешує пакет, на який він вказує, перезаписуючи кешовану копію, що більше не відповідає своєму дайджесту; плагін, що надається з одного з ваших каталогів або з копії всередині бінарного файлу компілятора, ніколи не підлягає цій вимозі. Два інші режими нічого з цього не застосовують: вони не читають приєднання плагінів робочого простору, тож у них такі плагіни не запускаються.

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

  • Приєднання плагіна-трансформації в .aggrega-config.yaml не змінює поведінку --release, доки ви не виконаєте pull. Це те саме правило, якого дотримується збірка, і з тієї самої причини: набір приєднань є вхідними даними, що визначають байти, тому він приймається під час pull, а не в момент редагування.
  • Кешований плагін, байти якого більше не відповідають дайджесту, записаному в lock-файлі, відхиляється, так само як це було б під час збірки.

Якщо сутність Release не має lock-файлу, --release однаково виконує перевірку — він попереджає, що не зміг перевірити ідентичність плагіна, і вказує, що запустити, замість відхилення. Див. попередження.

Повернення скомпільованого графа

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

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

Зверніть увагу на сусідній прапорець. --response-format задає, скільки власного звіту цієї команди записується (detailed або concise); --ir-graph запитує другий документ поруч із цим звітом. Один стосується обсягу, інший — предмета, і жоден не змінює вердикту.

Значення, які автор оголосив чутливими, приховуються в графі — зокрема values і infra з’єднання, коли сокет компонента-споживача оголошує лист чутливим, — у структурованій формі, описаній у aggrega inspect. --unredacted поруч із --ir-graph натомість виводить їх на умовах, які визначає aggrega inspect --unredacted: це стосується графа й нічого іншого, що записує ця команда, і все, куди потрапляє вивід, тоді містить ці значення у відкритому вигляді. Переданий без --ir-graph, він відхиляється, бо йому нічого було б розкривати.

Коректність окремої сутності (шлях до сутності)

aggrega validate <entity-path> перевіряє один файл сутності каталогу. Він застосовує багаторівневий набір перевірок і зупиняється на першій блокувальній помилці, тож порушення схеми виявляється явно ще до будь-якої роботи з каталогом:

  • Заповнювачі (будь-який вид) — значення, яке вимагає вид, але яке файл залишає порожнім рядком. Про всі такі значення повідомляється одразу, перед іншими перевірками, кожне — разом із тим, що воно приймає; див. заповнювачі, які ще треба заповнити.
  • Оболонка схеми (будь-який вид) — та сама перевірка JSON-Schema для кожної сутності, яку завантажувач каталогу виконує на кожній межі розбору.
  • Форма (будь-який тип) — структурна валідація, специфічна для типу. Для Component чи Feature вона включає читання за граматикою селекторів кожного селектора міток, який файл оголошує на сокеті залежності або на слоті вкладення; див. оголошені селектори.
  • Структура опор (Component і Feature) — перевірка опор spec.schema:, яка використовує SchemaLibraries каталогу для розгортання міждокументних $ref.

Для сутностей Component або Feature на цьому все: оболонка схеми, форма і структура опор. Окрема сутність Component не має авторських values чи infra, які можна було б рендерити ізольовано, тож рендерити нічого — її коректність повністю покривають рівні перевірки схеми та опор. Кожне ключове слово x-aggrega-*, яке вміст її схеми пише безпосередньо, повідомляється серед рекомендаційних приміток у стандартному потоці помилок як рядок warning:, що називає ключове слово, місце, де воно стоїть, і декларативну таблицю, яку слід написати натомість; воно ніколи не змінює вердикт чи код виходу.

Сутність Recipe додатково рендериться ізольовано. Це лише один аспект коректності окремої сутності, а не головний: після проходження рівнів схеми та форми validate знаходить у каталозі сутність Component, на яку вказує implements цієї Recipe, синтезує мінімальні Aggregate, Manifest і Release навколо одного екземпляра цієї сутності Component, прив’язаного до перевірюваної Recipe, і проганяє через них справжній конвеєр компіляції — спершу розв’язання та guard-перевірки (без рендерингу), потім справжній рендеринг ізольованого виводу. Кожне обов’язкове значення і кожне обов’язкове поле infra без значення за замовчуванням заповнюється заповнювачем оголошеного типу — значення в синтезованій Aggregate, infra в синтезованій Release, — а кожне інше значення та поле infra отримує значення за замовчуванням зі схеми через резолвер; Release спрямовує екземпляр у синтезовану межу за замовчуванням і не оголошує ні values:, ні обчислювальних ресурсів, яких не оголосила Aggregate. Заповнювач — це значення, яке приймають власні оголошені обмеження поля: константа або перше значення зі списку enum, число в межах діапазону, рядок потрібної довжини і у потрібному format, семантична версія там, де її вимагає pattern, стільки елементів списку, скільки потрібно, і кожна властивість, якої вимагає об’єкт. Будь-який інший pattern, умова validate: чи when:, композиція схем і обмеження на те, які елементи містить список, не враховуються, тож поле, яке на них покладається, все ще може відхилити свій заповнювач; тоді validate повідомляє про цю відмову словами самої схеми. Згенеровані артефакти виводяться, щоб автор побачив ізольований результат до того, як підключить сутність до повної Aggregate. Оскільки ізольоване середовище для однієї сутності заповнює лише ці обов’язкові поля, не створює жодних з’єднань і не приєднує жодної Feature, Recipe, шаблони якої читають значення, що його постачає лише з’єднання або приєднана Feature, не може рендеритися ізольовано; validate повідомляє про такий рендеринг як про неспробуваний, а не як про невдалий. Твердження, яке викликає fail, повідомляється як попередження, а не як провал перевірки — див. проваленне твердження є попередженням. Рендеринг, що зупинився з будь-якої іншої причини, не завершився, і validate повідомляє про нього з базовою діагностикою рендерингу аж до речення, яке називає причину зупинки.

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

Для FeatureRecipe перевіряються схема і форма; її рендеринг пропускається, оскільки FeatureRecipe рендериться лише тоді, коли приєднана до компонента-хоста, а синтез хоста, що проходить guard-перевірки, для довільної Feature не виконується.

Перевірка сутності в термінах Release

Робочий простір може надати кожній Release власні каталогові директорії — див. Надання Release власних каталогових директорій — і таким чином тримати поруч по одному варіанту каталогу на кожну Release. Шлях до сутності, переданий сам по собі, перевіряється за власними каталоговими директоріями робочого простору, де посилання на один із цих варіантів — сутність Component, яку реалізує Recipe, чи SchemaLibrary, на яку посилається опора, — не знаходиться. Передайте --release поруч зі шляхом до сутності, і ті самі перевірки виконаються в термінах цієї Release: посилання сутності розв’язуються через каталогові директорії, які конфігурація робочого простору надає цій Release, з додаванням на початок будь-якого --catalog, — тобто через ті директорії, які читає збірка цієї Release.

Приклад MariaDB + Adminer містить чотири такі варіанти. Сутність Component його варіанта synth бере налаштування сховища з SchemaLibrary, яку містять лише варіанти synth і chart, тож вона проходить валідацію в термінах тієї Release, яка з нею збирається:

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

і не проходить, називаючи бібліотеку, яку не вдалося розв’язати, у термінах Release, директорії якої її не містять, — --release release-compose.yaml або взагалі без --release у робочому просторі, що не має власних каталогових директорій.

Recipe перевіряється так само. Recipe варіанта synth реалізує core/datastore/mariadb, якого немає у власних каталогових директоріях робочого простору, тож без Release вона не проходить із повідомленням render: implements target "core/datastore/mariadb" not found in catalog. З Release, яка з нею збирається, вона розв’язує сутність Component цієї Release і рендериться ізольовано:

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: 3 artifact(s)

після чого виводяться три згенеровані артефакти. Кожен варіант цього прикладу оголошує core/datastore/mariadb, тож Recipe проходить валідацію в термінах кожної з чотирьох його Releases; у термінах Release, каталогові директорії якої не містять такої сутності Component, вона не проходить, називаючи ціль, як і без --release. Рядки Attachments: пояснено в розділі обов’язковий слот приєднання або вимога присутності.

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

Директорія, яку перелічує конфігурація робочого простору і яка не є директорією — наприклад, там нічого не існує, — для цієї сутності Release або для робочого простору, коли --release не задано, відхиляється ще до будь-якої перевірки, так само як її відхиляє кожна команда, що читає цей каталог (Звідки читаються локальні сутності): відмова називає запис, файл конфігурації та рядок, що його перелічують, і налаштування, а вердикт не виноситься. Перевірка сутності в редакторі через aggrega serve видає ту саму відмову як єдиний запис для файлу сутності, на рівні помилки, а інструмент validate у aggrega mcp відхиляє виклик із нею.

Заповнювачі, які ще слід заповнити

Значення, якого вимагає вид, але яке файл залишає порожнім рядком, є заповнювачем, і validate повідомляє про нього раніше за все інше. Документ, створений aggrega scaffold, містить заповнювач скрізь, де його виду потрібне значення, яке можете надати лише ви, тож саме тут ви дізнаєтеся, які з них залишилися. Ось створена сутність FeatureRecipe, у якій заповнено лише версію:

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates:
7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it.
8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).

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

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

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

Таке прочитання належить до перевірки однієї сутності, з --release поруч зі шляхом до сутності чи без нього. Запуск для всього каталогу, зустрівши той самий документ, повідомляє те, що повідомляє перевірка схеми, тож FeatureRecipe з порожнім implements у каталозі її проходить; область Release і aggrega build теж не застосовують цього прочитання.

Вид, якого ця область не приймає

Перевірка однієї сутності приймає Component, Feature, Recipe, FeatureRecipe, Workload і Plugin. Файл будь-якого іншого виду відхиляється, і повідомлення про відмову називає види, які вона приймає, а для виду сутності — область, яка перевіряє документ цього виду:

kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it

Область усього каталогу — це запуск без аргументу, а область Release — це --release без шляху до сутності:

ВидПеревіряється
Aggregateзапуском для всього каталогу, коли сутність лежить у каталозі; --release над сутністю Release, яка її розгортає
Manifest--release над сутністю Release, яка її називає
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryзапуском для всього каталогу, коли сутність лежить у каталозі

Запуск для всього каталогу читає лише те, що лежить у налаштованих каталогах, тож сутність Aggregate, яка зберігається в корені робочого простору поруч зі своєю сутністю Release, перевіряється через --release над цією сутністю Release.

Невдале твердження є попередженням

Твердження, яке викликає fail, — оголошене в Recipe або в сутності Component, на яку вказує її implements, — повідомляється як попередження, і перевірка через нього не завершується невдачею. Синтезована сутність Release містить заповнювачі та типові значення схеми замість значень, які задає справжня сутність Release, тож твердження щодо такого значення, образу чи наявності передумови тут не справджується незалежно від того, чи коректна Recipe, і validate не може відрізнити твердження, що чекає на Release, від хибного. Вердикт щодо твердження залишається за збиранням, у якого завжди є Release.

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

A Release must satisfy this assertion before a build of it can pass.

Звіт у стандартному виводі вказує, де зупинився запуск, і команда завершується з кодом 0. Власне твердження Recipe зупиняє рендеринг, тож після Resolution: valid звіт містить Render: stopped on a failed assertion, reported as a warning. Твердження Component обчислюється до будь-якого рендерингу, тож звіт містить Resolution: stopped on a failed assertion, reported as a warning, а за ним Render: not attempted (the run stopped on that assertion). В обох випадках нічого не рендериться, тож жоден артефакт не виводиться.

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

aggrega build для сутності Release, яка не задовольняє твердження, як завжди зупиняється на ньому з помилкою, називаючи твердження та наводячи речення його автора, а aggrega validate --release для цієї сутності Release завершується на ньому невдачею з тією самою помилкою. Перевірка сутності в редакторі через aggrega serve дає те саме попередження, позначене на власному ключі твердження, де його оголошує Recipe, а інструмент validate у aggrega mcp відповідає valid: true з попередженням серед своїх notices.

Чого не перевіряє коректність однієї сутності

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

Джерело, яке потрібно завантажити

Перевірка однієї сутності не читає lock-файл, не читає й не записує кеш і не робить мережевих запитів. Тому Recipe, чий source: називає щось, що отримується через транспорт, — репозиторій чартів OCI чи HTTPS, репозиторій Git, — не має коду інфраструктури для рендерингу: чарт чи модуль не існує ніде, куди може дістатися запуск, і файл, що перевіряється, тут ні до чого. Validate так і повідомляє, виводить це як окремий від рендерингу результат і завершується з кодом 0:

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: not attempted (this Recipe's source is fetched)
Validating one entity on its own reads no lockfile, reads and writes no
cache, and makes no network request, so the chart or module this Recipe
names is never retrieved and there is nothing to render from. To render
it, build a Release that deploys a component this Recipe implements.

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

Від джерела, яке вже є в робочому просторі, перевірка не відмовляється. Відносний source: ./module не потребує завантаження, тож його рендеринг виконується як будь-який інший, а невдача в ньому — справжня знахідка, яка повідомляється як Render: not completed in isolation з ненульовим кодом завершення. Рядок вище з’являється лише для джерела, яке потрібно отримати.

Щоб справді відрендерити Recipe із завантажуваним джерелом, запустіть aggrega build над сутністю Release, яка розгортає компонент, що його реалізує Recipe: збирання розв’язує джерело через lock-файл сутності Release і локальний кеш, і саме це надає байти, яких validate отримати ніяк не може.

Обов’язковий сокет uses

Друга — чи заповнено сокети uses з required: true у сутності Component з implements.

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

Sockets: required uses sockets not checked (backend, cache, registry)
Validating a Recipe on its own places its Component in a build of one,
so no other component exists for a required socket to be wired to. Whether
each of these sockets is populated is checked when the Component is deployed
in an Aggregate.

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

Саме правило не послаблюється й не дублюється; його перевіряють на тій області, яка може дати відповідь. aggrega build застосовує його повністю до поверхонь ребер сутностей Aggregate і Release разом і зупиняється на обов’язковому сокеті, який ніщо не підключає. Тож Recipe, що проходить валідацію окремої сутності, однаково має задовольнити правило обов’язкових сокетів, коли її Component розгортається, і звіт про це повідомляє, а не залишає непомітної різниці між тим, що перевірив validate, і тим, що перевірить збірка.

Обов’язковий слот приєднання або вимога присутності

Третя — чи заповнено слоти приєднання з required: true у сутності Component з implements — іменовані точки прив’язки, які оголошує її featuresSchema, — і чи присутнє приєднання кожного типу Feature, якого вимагають її вимоги присутності.

Обов’язковий слот заповнюється приєднанням Feature під цим іменем — в Aggregate або в Release, на компоненті чи на області над ним — там, де розгортається Component, а не в Recipe. Синтезований каркас не приєднує жодної Feature, тож ніщо, що він збирає, не може заповнити такий слот. Тому validate називає слоти, які не перевірив, і продовжує розв’язання та рендеринг, так само як для обов’язкових сокетів:

Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.

Цей рядок з’являється лише тоді, коли Component оголошує щонайменше один обов’язковий слот, і називає лише обов’язкові; Recipe, чий Component не оголошує жодного, такого рядка не створює. Відкладається лише сама обов’язковість: обмеження мітки слота та дозволені механізми доставки зберігаються так, як оголошено. Шаблон, що не розбирається, однаково провалює запуск, як і власна помилка Recipe, наприклад Workload, який provider не може синтезувати, — якщо тільки Recipe також не читає значення, яке постачає лише з’єднання або приєднана Feature, як описано в наступному розділі.

Вимога присутності — анотація features.aggrega.ai/requiredType.<label> на Component, яка вимагає, щоб якесь приєднання мало названий нею тип Feature, — відкладається з тієї самої причини: каркас нічого не приєднує, тож ніщо, що він збирає, не може мати цього типу. Validate називає кожну неперевірену вимогу за її міткою та типом, якого вона вимагає, і продовжує розв’язання та рендеринг. example/compute/service зі стандартної бібліотеки оголошує одну таку вимогу, тож її Recipe перед двома відрендереними артефактами повідомляє:

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: presence mandates not checked (monitoring: core/prometheus-exporter)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to carry a type the Component requires. Whether
an attachment of each of these types is present is checked when a Release
that deploys the Component is built.
Resolution: valid
Render: 2 artifact(s)

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

Кожне правило перевіряють там, де на нього можна відповісти. aggrega pull, aggrega build і aggrega validate --release обчислюють обидва правила над справжніми приєднаннями Release, і кожна з команд зупиняється на обов’язковому слоті, який ніщо не заповнює, і на вимаганому типі, якого не має жодне приєднання.

Значення, яке постачає лише з’єднання або приєднана Feature

Четверта — чи рендериться Recipe, коли її з’єднання та приєднані Features постачають те, що читають її шаблони.

Шаблони Recipe читають те, що доставляє з’єднання, у .context.inject і .context.uses, а те, що доставляє приєднана Feature, — у .features. Синтезований каркас не підключає жодного з’єднання й не приєднує жодної Feature, тож кожне таке читання нічого не знаходить: читання в .context.inject.env натрапляє на порожній канал доставки, а range по .context.uses не зустрічає жодного з’єднання. Validate спершу рендерить Recipe, і рендеринг, що завершився, звітується як зазвичай. Коли рендеринг зупиняється, а шаблони Recipe — разом з файлами й записами бібліотек, які вони імпортують, — читають щось у цих трьох місцях, validate повідомляє, що рендеринг не виконувався, називає значення, які Recipe там читає, виводить речення, на якому зупинився рендеринг, і завершується з кодом 0. Варіант чарту з прикладу MariaDB + Adminer читає облікові дані бази даних з каналу доставки, який заповнюють два приєднані секрети:

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: not attempted (this Recipe reads values a build of one cannot supply)
Validating a Recipe on its own places its Component in a build that wires
no connection and attaches no Feature, so nothing supplies what its
templates read under .context.inject, .context.uses or .features. Its
render stopped, and whether on one of those values or on a fault of its
own is not judged here. To render it, build a Release that deploys a
component this Recipe implements.
Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD
The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD

Читання, яке нічого не знаходить і нічого не зупиняє, не відкладається: range по .context.uses, що нічого не рендерить у рендерингу, який завершився, звітується як той рендеринг, яким він був.

Вирішує те, що читає Recipe, а не те, на чому зупинився рендеринг, і це має наслідок, про який варто знати заздалегідь: власна помилка Recipe, яка також читає таке значення, — скажімо, ключ з помилкою в написанні — звітується як невиконаний рендеринг разом з рештою, а не як збій. Рядок The render stopped: містить власне речення рендерингу, щоб ви могли побачити, що це було, а збірка Release, що розгортає Component, оцінює рендеринг повністю.

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

Інструмент validate з aggrega mcp дає той самий вердикт щодо тієї самої Recipe: рендеринг, відкладений у такий спосіб, повертається як валідний без нічого в діагностиці, а наведені вище рядки містяться в тексті, який він повертає поруч із нею.

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

Пропущений файл усе одно пояснює сутність Component, яка через нього зникла. Якщо ціль implements сутності Recipe не знайдено і рівно один пропущений файл оголошує цю сутність Component, звіт починається з власної відмови цього файлу — його шляху, обмеження, яке він порушує, і короткого коду умови в заголовку, — далі йде note:, що повідомляє: файл пропущено під час завантаження, тож каталог не містить нічого під ідентичністю, яку він оголошує, — а потім збій implements target … not found in catalog як причина, з якої цей файл був потрібен. Якщо жоден пропущений файл не оголошує цю сутність Component або її оголошує більше ніж один, першим іде збій «не знайдено», а кожен пропущений файл перелічено під ним у note: catalog files skipped at load. Саме таке пояснення дає aggrega build щодо пропущеного файлу, і його ж дають перевірка сутностей редактора через aggrega serve та інструмент validate з aggrega mcp. Каталог, з якого нічого не пропущено, звітує точно так, як і зазвичай.

Як validate співвідноситься з lint і build

Три команди відповідають на три різні запитання:

  • aggrega validate — чи це правильно? Схема, стовпи, посилання, extends, підтримка видів вхідних даних та ізольований рендеринг. Команда не читає стан середовища виконання і не створює артефактів.
  • aggrega lint — чи відповідає це домовленостям публікації каталогу? Іменування, відповідність каталогам категорій, префікси анотацій, розмір підвищення версії та решта необов’язкової дисципліни публікації. Lint повторює три області дії validate, але ніколи не перевіряє правильність.
  • aggrega build — скомпілювати повне розгортання. Build потребує повного замикання Aggregate + Manifest + Release і створює артефакти, рідні для провайдера. Під час компіляції команда перевіряє власне замикання залежностей, а потім виконує рендеринг. aggrega validate --release — це та сама перевірка залежностей окремо, без рендерингу; validate для однієї сутності ізолює рендеринг однієї сутності Recipe без повної сутності Aggregate.

Приклади

Перевірити весь каталог:

aggrega validate --catalog ./catalog

Перевірити саме те, від чого залежить одна сутність Release, перед її збиранням:

aggrega validate --release releases/production.yaml

Перевірити одну сутність і — для сутності Recipe — переглянути її ізольований відрендерений результат:

aggrega validate core/datastore/postgres/recipes/helm.yaml

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

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

Див. також

  • ./aggrega-lint.md — відповідник для домовленостей у тих самих трьох областях.
  • ./aggrega-build.md — компілює повну пару Aggregate + Release в артефакти; перевіряє її замикання залежностей у межах компіляції.
  • ./aggrega-inspect.md — запит до графа IR після розв’язання без переходу до рендерингу.
  • ../errors/warnings.md — рекомендаційні зауваження, які validate виводить як рядки notice:.

Синтаксис

aggrega validate [entity-path] [flags]

Опис

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass.
With --release, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; a whole-catalog run, a Release's closure and a build do not apply it.
Each kind then has its schema checked, then the checks its own kind carries:
pillar structure for a Component or Feature; shape for a Workload,
FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that has to be fetched, the render is reported as not attempted instead:
validating one entity on its own reads no lockfile, reads and writes no cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

Прапорці

ПрапорецьЗа замовчуваннямОпис
--catalog[]Каталог; можна повторювати. Кожен —catalog <dir> додається на початок стеку пошуку каталогів (перший збіг перемагає): catalog_dirs робочого простору або, для сутності Release, якій конфігурація робочого простору надає власні каталоги в workspace.releases, каталоги цієї Release; стек завершується каталогом з назвою catalog у корені робочого простору, якщо такий є. Порожній список catalog_dirs взагалі не читає жодного локального каталогу.
--ir-graphfalseТакож записати граф IR, обчислений під час цього запуску, у stdout як JSON, на додачу до всього, що ця команда вже виводить. Значення, які автор оголосив чутливими, у ньому приховано; передайте —unredacted, щоб натомість вивести їх. Застосовується до області —release — єдиної області, яка розв’язує сутність Release у граф. Цей прапорець вибирає ДОКУМЕНТ, тоді як —response-format задає, наскільки докладно записується власний звіт цієї команди; жоден із них не впливає на вердикт чи код виходу
--no-unsupported-field-warningsfalseПриглушити клас попереджень про непідтримувані поля: повідомлення, які ціль видає щодо написаного вами, але не підтримуваного нею, — поля Workload, яке вона не може виразити (як-от ціль нижчої точності, наприклад compose), або анотації aggrega.ai/, на яку вона не реагує для вхідного типу вузла. Інші попередження рендерингу й далі виводяться. Впливає лише на відображення; не змінює результат рендерингу. Застосовується до області сутності — єдиної області, яка виконує рендеринг
--plugin—Шлях до необробленого .wasm для перевірки на відповідність його самозвіту describe() — перевірка автора перед публікацією. Окремо потребує —type; з аргументом-сутністю Plugin звіряє бінарний файл із оголошеним у сутності типом, заявою про можливості, дзеркалом команд і записом функцій хоста.
--release—Шлях до YAML сутності Release. Окремо — перевірка всього розв’язаного замикання її залежностей; з аргументом-сутністю — перевірка цієї сутності в термінах Release, з розв’язанням її посилань через каталоги, які конфігурація робочого простору надає цій Release. Відносний шлях розв’язується відносно каталогу, у якому ви запускаєте команду, а не відносно кореня робочого простору. Якщо цей каталог не належить жодному робочому простору і корінь не вказано, абсолютний шлях знаходить робочий простір від власної теки Release
--response-formatdetailedОбсяг виводу для області —release, тобто замикання сутності Release без аргументу-сутності: detailed (за замовчуванням) повідомляє про кожну діагностику та рекомендаційні рядки; concise повідомляє лише кількість діагностик і першу діагностику. Вердикт і код виходу однакові для обох.
--type—Тип плагіна для перевірки —plugin лише бінарного файлу, що звіряється з типом, указаним у самозвіті бінарного файлу. Має сенс лише з —plugin; коли тип надає сутність Plugin, не вказуйте його (розбіжне значення зупиняє виконання).
--unredactedfalseВиводити значення, які автор оголосив чутливими, замість того щоб їх приховувати. Усе, куди потрапляє вивід, — термінал, конвеєр, файл, запис екрана — тоді містить ці значення у відкритому вигляді. Впливає лише на граф, який записує —ir-graph, і ні на що інше, тому потребує —ir-graph