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

Схема Aggrega Core (Plugin)

Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.

Ідентифікатор схеми: https://aggrega.ai/schemas/plugin-v1beta1.schema.json

Wasm-плагін: модуль WebAssembly, опублікований в OCI-реєстрі та ідентифікований своїм metadata.pluginType — сокетом, який він реалізує, — разом із простим metadata.name; він оголошує версію ABI, на яку орієнтований, необов’язковий вказівник на підпис і необов’язковий блок середовища виконання. Сутність і її .wasm публікуються як один OCI-маніфест із тегом metadata.version — YAML сутності як config blob маніфесту, .wasm як вбудований шар, підписаний один раз. Ідентичність — це координата metadata.pluginType/metadata.name разом із metadata.version сутності; розташування .wasm виводиться з цієї координати та налаштованого реєстру, а розв’язаний дайджест вмісту зберігається у lock-файлі, а не в сутності. Lock-файл записує дайджест, а політика довіри кожного реєстру перевіряє підпис артефакту під час завантаження. Компілятор не інтерпретує поведінку плагіна — він маршрутизує посилання; середовище виконання WebAssembly виконує байти.

Див. довідник з написання Plugin, де описано, як створювати сутності Plugin; ця сторінка документує структурну схему, яку описує той довідник.

Тип верхнього рівня: object

Властивості

ВластивістьТипОбов’язковаОпис
apiVersionconst “aggrega.ai/v1beta1”такКонстанта: "aggrega.ai/v1beta1"
kindconst “Plugin”такКонстанта: "Plugin"
metadataobjectтак
specobjectтакВерсія ABI, на яку орієнтований плагін, необов’язковий вказівник на підпис і необов’язковий блок runtime. Розташування .wasm плагіна виводиться з ідентичності плагіна — його metadata.pluginType (сокет) разом із простим metadata.name — і налаштованого реєстру; у spec воно не зберігається.

Додаткові властивості не дозволені.

plugin.metadata

ВластивістьТипОбов’язковаОпис
namestringтакЩонайменше 1 символ.
versionstringтакВерсія сутності Plugin за суворим семантичним версіонуванням (наприклад, 1.0.0). Шаблон: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
pluginTypestring (enum)такТип сокета, який реалізує цей плагін. Плагін реалізує рівно один тип сокета з таксономії типів плагінів, яку розпізнає середовище виконання: provider (рендерить вузли IR в артефакти, рідні для провайдера), linter (перевіряє написаний вміст і видає діагностики), pipeline-step (крок у pipeline: сутності FeatureRecipe або Recipe, що застосовує патчі до набору відрендерених документів), governance (виконує ролі керування конвеєра збірки — перетворює мітки вузлів під час побудови топології або виносить вердикт прийняти/відхилити щодо графа IR під час статичного аналізу чи щодо відрендерених артефактів під час рендерингу; що він може видавати, визначає роль, до якої його підключено, а не його вид), cli (додає підкоманду середовища виконання aggrega <cmd>, яку оператор викликає в командному рядку — сокет середовища виконання, відмінний від сокетів рендерингу й конвеєра часу компіляції), parser (перетворює сторонній вихідний текст на канонічне структуроване дерево, щоб споживач читав дерево, не маючи власного парсера мови, і оголошує формати, які обробляє, як можливості parse:<format>), importer (перетворює стороннє джерело інфраструктури чи визначення агента на чернеткові авторські файли Aggrega і оголошує формати, які обробляє, як можливості import:<format>). Допустимі значення: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer"
descriptionstringніЩо це за сутність і для чого вона призначена — для того, хто вирішує, чи її використовувати. Почніть із речення, що називає її, а потім додайте те, що потрібно читачеві, щоб вибрати її та правильно використовувати: чого вона очікує від збірки, яка її запускає, та що в її поведінці може здивувати. Звичайна довжина — короткий абзац.
maintainersobject[]ніСписок супровідників, яким належить ця сутність.
licensestringніІдентифікатор SPDX ліцензії програмного забезпечення, яке описує ця сутність, наприклад MIT або AGPL-3.0. Він фіксує умови цього програмного забезпечення, а не умови цього файлу.
repositorystringніURL репозиторію Git, де зберігаються вихідні файли.
homestringніURL домашньої сторінки, вікі або документації цієї сутності.
keywordsstring[]ніСписок описових ключових слів для зручного пошуку в інтерфейсі.

Додаткові властивості не дозволені.

plugin.metadata.maintainers[]
ВластивістьТипОбов’язковаОпис
namestringтак
emailstringні
urlstringні

Додаткові властивості не дозволені.

plugin.spec

Версія ABI, на яку орієнтований плагін, необов’язковий вказівник на підпис і необов’язковий блок runtime. Розташування .wasm плагіна виводиться з ідентичності плагіна — його metadata.pluginType (сокет) разом із простим metadata.name — і налаштованого реєстру; у spec воно не зберігається.

ВластивістьТипОбов’язковаОпис
abiVersionstring (enum)такВерсія ABI хост/гість, на яку орієнтований плагін. v1beta1 — єдине прийнятне значення; сутність Plugin, що оголошує версію ABI, яку цей компілятор більше не підтримує, відхиляється з указанням версії, під яку слід перезібрати плагін. Допустимі значення: "v1beta1"
signatureobjectніНеобов’язковий описовий вказівник на прикріплений підпис плагіна. Цей блок є лише документацією — він фіксує для читачів каталогу, де зберігається підпис і як його створено; сам він не перевіряє й не допускає плагін. Обов’язкова перевірка — це політика довіри для кожного реєстру, що застосовується під час pull: підпис отримується як OCI referrer, перевіряється щодо довірених ідентичностей реєстру або закріпленого ключа і записується в lockfile як перевірений факт. Реєстр, що вимагає підписів, зупиняє pull, коли потрібний підпис відсутній, недовірений або недійсний.
runtimeobjectніНеобов’язкові обмеження виконання, які хост застосовує під час завантаження й запуску плагіна. Вихідний мережевий доступ не є авторським полем: плагін ніколи не звертається до мережі під час збірки (межа ahead-of-time), тому поля списку дозволених хостів тут немає.
exportsobject[]ніЕкспорти, які пропонує цей плагін, кожен з оголошеною можливістю. Експорт — це одна іменована точка входу, до якої звертається хост (наприклад, render_node, lint_naming, step); блок можливостей кожного експорту — це авторське твердження про те, що робить цей експорт, і хост звіряє його із самозвітом плагіна під час публікації та завантаження. Записи зберігають авторський порядок. Відсутність поля означає, що авторської поверхні експортів не оголошено.
commandsobject[]ніНалежить машині, не заповнюйте вручну: записується командою aggrega plugin sync (або aggrega plugin gen-catalog) із самозвіту плагіна. Команди верхнього рівня aggrega <command>, які додає CLI-плагін, зчитуються із самозвіту плагіна і записуються тут у порядку, оголошеному в самозвіті, тож набір команд, який установлює CLI-плагін, можна прочитати із сутності без завантаження плагіна. Плагін, що не є CLI, не додає команд і записує порожній список. Хост установлює рівно цей набір; записаний набір, що розходиться із самозвітом плагіна, зупиняє завантаження, а публікація відхиляє набір, не синхронізований із бінарним файлом, і пропонує авторові записати його повторно.
providerobjectніБлок сокета провайдера для плагіна pluginType: provider: можливості, які він обслуговує, як він транслює вид Workload aggrega.ai/v1beta1, які рідні для платформи анотації він читає, і його контракт поведінки рендерингу. Присутній лише в плагінах, що рендерять для провайдера; відсутній у плагінах усіх інших типів.
pipelineStepobjectніБлок pipeline-step для плагіна pluginType: pipeline-step: можливості провайдера, з якими сумісний його крок. Присутній лише в плагінах pipeline-step; відсутній у плагінах усіх інших типів.
parserobjectніБлок parser для плагіна pluginType: parser: вихідні формати, які він перетворює на канонічне структуроване дерево. Присутній лише в плагінах parser; відсутній у плагінах усіх інших типів.
importerobjectніБлок importer для плагіна pluginType: importer: сторонні вихідні формати, які він перетворює на чернеткові авторські файли Aggrega, і сигнатури, за якими розпізнається джерело цих форматів. Присутній лише в плагінах importer; відсутній у плагінах усіх інших типів.

Додаткові властивості не дозволені.

plugin.spec.signature

Необов’язковий описовий вказівник на прикріплений підпис плагіна. Цей блок є лише документацією — він фіксує для читачів каталогу, де зберігається підпис і як його створено; сам він не перевіряє й не допускає плагін. Обов’язкова перевірка — це політика довіри для кожного реєстру, що застосовується під час pull: підпис отримується як OCI referrer, перевіряється щодо довірених ідентичностей реєстру або закріпленого ключа і записується в lockfile як перевірений факт. Реєстр, що вимагає підписів, зупиняє pull, коли потрібний підпис відсутній, недовірений або недійсний.

ВластивістьТипОбов’язковаОпис
typeconst “sigstore-cosign”такСхема підпису. sigstore-cosign — підтримувана схема. Константа: "sigstore-cosign"
signatureRefstringніПосилання OCI referrer на прикріплений пакет підпису, для документації та виявлення. Відсутнє, коли підпис виявляється переліком referrer під час pull, а не закріплений тут.
publicKeyRefstringніВказівник на відкритий ключ, яким створено підпис, для підпису з ключем. Відсутність поля вказує на безключовий підпис (з ідентичністю OIDC), що перевіряється щодо довірених ідентичностей реєстру.

Додаткові властивості не дозволені.

plugin.spec.runtime

Необов’язкові обмеження виконання, які хост застосовує під час завантаження й запуску плагіна. Вихідний мережевий доступ не є авторським полем: плагін ніколи не звертається до мережі під час збірки (межа ahead-of-time), тому поля списку дозволених хостів тут немає.

ВластивістьТипОбов’язковаОпис
maxMemoryPagesintegerніОбмежує лінійну пам’ять плагіна в сторінках Wasm (64 KiB на сторінку). Нуль або відсутність поля застосовує типове обмеження платформи, тож завантаження ніколи не буває необмеженим; приєднання, якому потрібно більше, підвищує це значення. Мінімум: 0.
timeoutMsintegerніОбмежує, скільки часу власний код плагіна може виконуватися протягом одного виклику, у мілісекундах, не враховуючи часу, проведеного всередині функцій хоста, які він викликає. У Linux вимірюється процесорний час, тож час очікування процесора на завантаженій машині не враховується; в інших системах вимірюється час, що минув. Перший виклик щойно завантаженого плагіна також враховує власний запуск плагіна. Нуль або відсутність поля застосовує типове обмеження платформи, тож виклик ніколи не стає таким, що його неможливо скасувати; приєднання, яке виконується довше, підвищує це значення. Мінімум: 0.
hostFunctionsstring[]ніНалежить машині, не заповнюйте вручну: функції хоста, які імпортує плагін, зчитані з розділу імпорту .wasm командою aggrega plugin sync (або aggrega plugin gen-catalog) і записані тут у канонічній формі (відсортованій, без дублікатів). Публікація повторно виводить їх із бінарного файлу й відхиляє сутність, запис якої відрізняється; отримання знову виводить і перевіряє їх. Хост реєструє саме цей виведений набір і перевіряє кожен запис за кураторським списком дозволених.
configKVmap of stringніСпецифічна для Plugin конфігурація, яку середовище виконання передає плагіну під час запуску, у вигляді пар ключ/значення «рядок — рядок». Записи зберігають авторський порядок, тож згенерований запис є побайтово ідентичним між запусками. Якщо поле відсутнє, діє типова порожня конфігурація середовища виконання.

Додаткові властивості не дозволені.

plugin.spec.exports[]
ВластивістьТипОбов’язковаОпис
namestringтакABI-ім’я експорту — ім’я, до якого хост спрямовує виклики (наприклад, render_node, lint_naming, step). Довжина щонайменше 1 символ.
operatesstring (enum)ніОперація конвеєра, яку виконує цей експорт: patch (змінити наявний відрендерений документ) або emit (додати новий документ). Відсутність не заявляє жодної операції. Допустимі значення: "patch", "emit"
scopestring (enum)ніКорінь документів, з яким працює цей експорт: own (власні відрендерені документи вузла) або host (документи компонента, до якого підключено FeatureRecipe рівня компонента). Відсутність не заявляє жодної області дії. Допустимі значення: "own", "host"
selectorstringніДовільний, зрозумілий людині опис того, на що діє експорт (наприклад, workloads carrying a pod template). Документація для читачів каталогу; компілятор його не інтерпретує.

Додаткові властивості не дозволені.

plugin.spec.commands[]
ВластивістьТипОбов’язковаОпис
namestringтакДієслово команди, яке реєструє хост, — токен aggrega <name>, який викликає оператор, і дискримінатор, який хост передає плагіну під час виклику, щоб один плагін, що обслуговує кілька команд, міг маршрутизувати залежно від того, яку команду викликано. Довжина щонайменше 1 символ.
descriptionstringніОднорядковий короткий текст довідки команди, що показується у списку команд і у виводі довідки. Лише документація; хост на нього не реагує.
flagsobject[]ніПрапорці команди в оголошеному порядку. Кожен запис додає один прапорець, який хост реєструє для команди, щоб aggrega help відображав його як прапорець основної команди. Команда без прапорців залишає список порожнім. У межах команди кожне ім’я прапорця і кожне скорочення трапляється один раз, і жоден не повторює прапорець, який уже має кожна команда aggrega, — --help, -h і глобальні прапорці; хост перевіряє це, коли додає команди плагіна, і плагін, оголошення якого не проходять перевірку, не додається, з попередженням.

Додаткові властивості не дозволені.

plugin.spec.commands[].flags[]
ВластивістьТипОбов’язковаОпис
namestringтакДовге ім’я прапорця — токен —name, який оператор передає в командному рядку. Кожен оголошений прапорець має його вказати. Довжина щонайменше 1 символ.
shorthandstringніНеобов’язковий короткий псевдонім прапорця — форма -x, яку оператор може передати замість довгого імені, — у вигляді однієї літери або цифри ASCII. Відсутність означає, що прапорець не має короткого псевдоніма. Шаблон: ^[A-Za-z0-9]$.
descriptionstringніОднорядковий текст довідки прапорця, що показується у виводі довідки команди. Це необов’язкова документація; хост її не перевіряє і на неї не реагує.
typestring (enum)ніТип значення прапорця — string, bool або int — і вид прапорця, як який його відображає довідка. Відсутність відображає його як рядковий прапорець. Допустимі значення: "string", "bool", "int"
defaultstringніЗначення прапорця за замовчуванням, коли оператор його не передає, записане як рядок. Для прапорця bool або int це значення відповідного типу. Відсутність поля означає, що прапорець не оголошує значення за замовчуванням.

Додаткові властивості не дозволені.

plugin.spec.provider

Блок сокета провайдера для плагіна pluginType: provider: можливості, які він обслуговує, як він транслює вид Workload aggrega.ai/v1beta1, які рідні для платформи анотації він читає, і його контракт поведінки рендерингу. Присутній лише в плагінах, що рендерять для провайдера; відсутній у плагінах усіх інших типів.

ВластивістьТипОбов’язковаОпис
capabilitiesstring[]ніЗаписується із самозвіту .wasm плагіна командою aggrega plugin gen-catalog, тож джерелом цього списку є плагін. Автор може звузити його перед публікацією, вилучивши запис, який ця сутність не повинна пропонувати, але не може додати жодного, якого не називає самозвіт: публікація, а також aggrega validate з .wasm плагіна, переданим через --plugin, відхиляють список, що називає можливість, якої немає в самозвіті. Публікація надсилає сутність так, як її написано, ніколи не переписуючи цей список, і зазначає кожну можливість із самозвіту, яку список пропускає. Можливості, які обслуговує цей провайдер, — назви можливостей, як-от helm або compose, форму виводу яких він рендерить. Провайдер є універсальним для артефактів, що мають спільну форму виводу однієї можливості, а не для всіх можливостей, тому список є явним твердженням про перевірену сумісність, а не побажанням. Записи зберігають порядок автора. Запитана в Recipe ціль провайдера визначається як плагін провайдера, список якого містить цю ціль; ціль, указана більш ніж одним плагіном провайдера, зупиняє збірку як неоднозначна, якщо вибір plugins.providers у конфігурації робочого простору не вказує, який плагін використати. Порожній або відсутній список не оголошує жодної можливості, тож плагін не обслуговує жодної цілі.
workloadSchemastringніJSON Schema 2020-12, що документує, як цей провайдер перетворює тип Workload з aggrega.ai/v1beta1 на нативні маніфести провайдера. Якщо поле присутнє, провайдер підтримує Recipes, які оголошують блок workload: (синтезований режим), — провайдер перетворює Workload на нативні маніфести провайдера, керуючись цією схемою як документацією/контрактом. Чи підтримується Recipe з workload:, визначається здатністю до синтезу прив’язаного провайдера, а не наявністю цього поля: Recipe у синтезованому режимі, прив’язаний до провайдера, який не вміє синтезувати, явно зупиняє збірку під час рендерингу. Каталог стандартної бібліотеки оголошує workloadSchema на синтезувальних провайдерах як задокументований контракт, синхронізований із цією здатністю. Це поле є задокументованим контрактом: під час завантаження тіло компілюється в JSON Schema 2020-12 для перевірки коректності, і більше ніщо його не читає.
wellKnownAnnotationsobject[]ніТвердження провайдера про підтримку: нативні для платформи загальновідомі ключі анотацій (простір імен aggrega.ai/), які читає цей провайдер, кожен з областю, у якій він читається, і поведінкою, що застосовується за його відсутності. Оголошуйте ключ лише там, де провайдер його читає, — опублікована матриця підтримки рендериться з цих оголошень, тож ключ, указаний тут, — це ключ, від якого автор може очікувати зміни рендереного виводу в названій ним області. Компілятор читає оголошення двома способами: scope, що називає тип входу, якого не заявляє власне contract.inputKinds провайдера, суперечить суміжному твердженню в тій самій сутності, і збірка зупиняється, називаючи ключ і суперечність; а збірка попереджає про анотацію aggrega.ai/, що доходить до рендеру через цей провайдер, коли жоден запис не охоплює її в жодному типі входу, який оголошує цей рендер. Поле відрізняється від правила, що регулює прив’язування значення під зарезервованим префіксом aggrega.ai/. Відсутність поля не оголошує жодної підтримки, і для цього провайдера таке попередження не видається; провайдер, який не читає жодного з цих ключів, оголошує readsNoWellKnownAnnotations замість цього списку. Записи є впорядкованим списком і зберігають порядок автора.
readsNoWellKnownAnnotationsконстанта trueніОголошує, що цей провайдер не читає жодного з нативних для платформи ключів анотацій у просторі імен aggrega.ai/, тобто ключів, які інакше було б перелічено в wellKnownAnnotations: це твердження про підтримку, що не охоплює жодного ключа, — явна заява там, де пропуск і цього поля, і wellKnownAnnotations є мовчанням. Тоді збірка попереджає про кожну анотацію aggrega.ai/, що доходить до рендеру через цей провайдер, називаючи ключ, провайдер і типи входу, які оголошує цей рендер; значення все одно проходить без змін, і збірка не зупиняється. Можна записати лише true, тож пропуск поля залишається єдиним способом нічого не сказати. Поле не можна записати разом із wellKnownAnnotations: провайдер, який читає деякі з ключів, натомість перелічує їх там. Константа: true
contractobjectніСамостійно оголошений провайдером контракт поведінки рендерингу: типи входу, які він рендерить, як він збирає повузловий вивід групи диспетчеризації і в яких каталогах цей вивід розміщується, пара розділювачів шаблонів, яку він застосовує до імпортованих файлів артефактів, чи може один завантажений екземпляр обслуговувати кожен перехід, чи з’єднує він ребра між межами, чи враховує записи omit, чи приймає файли, які Recipe додає до спільного виводу своєї межі, і які файли його екосистема ніколи не постачає поруч із джерелом. Це запис самозвіту плагіна провайдера на момент публікації, який хост звіряє з цим самозвітом під час публікації та завантаження. Відсутність поля не оголошує жодного контракту поведінки рендерингу, і звіряння порівнює лише твердження окремих експортів.

Додаткові властивості не дозволені.

plugin.spec.provider.wellKnownAnnotations[]
ВластивістьТипОбов’язковаОпис
keystringтакНативний для платформи загальновідомий ключ анотації, який читає провайдер (наприклад, aggrega.ai/namespace). Розміщується в зарезервованому платформою просторі імен анотацій aggrega.ai/ — директиви платформи, які читає провайдер. Шаблон: ^aggrega\.ai/.+.
purposestringтакЩо контролює анотація — поведінка рендерингу, на яку вона впливає, коли присутня.
defaultBehaviorstringніПоведінка, яку провайдер застосовує, коли ця анотація відсутня.
scopestring (enum)[]ніДе цей провайдер читає ключ. Перші три значення — це типи входу Recipe, і вони називають шлях рендерингу, на якому читається ключ: sourced — вендорований набір файлів, synthesized — Workload, який матеріалізує провайдер, artifactsStandalone — вузол, увесь вивід якого складається з імпортованих документів артефактів. Кожне з них має бути типом входу, який заявляє contract.inputKinds цього провайдера; якщо назвати тип, якого він не заявляє, збірка зупиняється. boundary призначене для ключа, що визначається один раз на межу, а не на вузол, — назва зібраного артефакту або контекст розміщення, з якого формується посилання між межами, — де тип входу не є змістовною віссю, тому воно не зіставляється з contract.inputKinds. Ключ, що читається на кількох шляхах, перелічує їх усі. Відсутність поля не робить тверджень щодо шляхів: нічого не перевіряється, і ключ лише вказує, що провайдер десь його читає. Щонайменше 1 запис. Жоден запис не може повторюватися. Допустимі значення для кожного запису: "sourced", "synthesized", "artifactsStandalone", "boundary".

Додаткові властивості не дозволені.

plugin.spec.provider.contract

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

ВластивістьТипОбов’язковаОпис
inputKindsobjectніЯкі з трьох видів вхідних даних Recipe цей плагін рендерить: набір файлів із джерела, синтезоване робоче навантаження та автономний вузол лише з артефактів. Кожне поле є незалежним твердженням.
boundaryAssemblystring (enum)ніЯк плагін об’єднує результат рендерингу кожного вузла групи диспетчеризації: none записує результат кожного вузла безпосередньо за шляхом диспетчеризації; merge згортає фрагменти окремих вузлів в один документ; nest розміщує результат кожного вузла на його власній позиції в об’єднавчій структурі. Відсутність поля не містить жодного твердження щодо збирання. Допустимі значення: "none", "merge", "nest"
artifactDelimitersobjectніПара розділювачів шаблонів Go, яку плагін застосовує до імпортованих файлів артефактів. Відсутність поля означає стандартну пару {{/}}; плагін, цільовий синтаксис якого конфліктує з цією парою, оголошує тут альтернативну пару.
assemblyNameAnnotationobjectніАнотація межі, розв’язане значення якої називає артефакт, що плагін збирає з групи диспетчеризації. Плагін, який згортає межі-учасники групи в одну іменовану збірку, оголошує ключ анотації, який він читає, і те, чи мають усі межі-учасники узгоджуватися щодо розв’язаного значення цієї анотації. Відсутність поля означає, що плагін називає свою збірку лише за шляхом диспетчеризації.
reusableInstanceбулеваніЧи може один завантажений екземпляр плагіна обслуговувати всі переходи рендерингу, збирання та валідації збірки замість нового екземпляра для кожного переходу. Оголошується як true лише тоді, коли плагін не зберігає стану між переходами — є чистою функцією вхідних даних кожного переходу, — тож єдиний екземпляр видає побайтово ідентичний результат незалежно від того, чи використовується повторно, чи завантажений заново. Відсутність поля (false) завантажує новий екземпляр для кожного переходу, ізолюючи плагін, який за своєю будовою має стан.
crossBoundaryLinkingбулеваніЧи з’єднує плагін міжмежове ребро uses — ребро uses, споживчий і споживаний кінці якого збираються в різні групи диспетчеризації, — генеруючи нативні для провайдера перехресні посилання через парний контракт експорту link_publish/link_resolve. Оголошується як true лише тоді, коли плагін експортує обидва; твердження, яке не відповідає парі експортів, зупиняє завантаження. Відсутність поля (false) не оголошує міжмежового зв’язування, тож хост не спрямовує до плагіна жодного переходу зв’язування.
omitsбулеваніЧи враховує провайдер записи omit — записи, що називають відрендерені одиниці, які слід вилучити з результату вузла: він вилучає з того, що рендерить, кожну одиницю, якій відповідає запис, і повідомляє, скільки одиниць відповіло кожному запису. Це зафіксоване під час публікації твердження omits, яке робить самозвіт провайдера, і значення, що відрізняється від цього звіту, зупиняє завантаження. Відсутність поля (false) не оголошує такої підтримки.
boundaryArtifactsбулеваніЧи приймає провайдер файли, які Recipe додає до спільного результату межі, у якій він рендерить, у spec.boundary.artifacts цього Recipe: компілятор записує кожен такий файл один раз, у каталог, що містить зібраний результат межі, а ціль провайдера вважає його частиною цього результату. Це зафіксоване під час публікації твердження boundary_artifacts, яке робить самозвіт провайдера, і значення, що відрізняється від цього звіту, зупиняє завантаження. Відсутність поля (false) не оголошує такої підтримки, і Recipe, що оголошує цей блок для цього провайдера, відхиляється ще до будь-якого рендерингу.
nestSegmentstringніКаталог, у який ціль цього провайдера розміщує власний підкаталог кожного учасника, для провайдера, чий boundaryAssembly має значення nest, — charts для об’єднавчого чарту, modules для кореневого модуля. Компілятор поєднує цей каталог, ім’я учасника та власний шлях кожного файлу. Читається лише для вкладального провайдера. Відсутність поля розміщує підкаталог кожного учасника безпосередньо у власному каталозі межі. Значення називає один каталог і ніколи не шлях.
sourceIgnoreobjectніФайли, які екосистема цього провайдера ніколи не постачає поряд із джерелом, що він рендерить, у вигляді правил ігнорування в синтаксисі gitignore — зафіксовані під час публікації правила source_ignore, які оголошує його самозвіт. Коли автор закріплює Recipe або FeatureRecipe, можливість якого обслуговує для нього цей провайдер, ці правила поєднуються з власним .aggregaignore автора й записуються в entity.lock поряд із сутністю разом з ім’ям цього плагіна, і кожна подальша публікація, порівняння та рендеринг локального джерела сутності застосовує записані правила. Якщо поле присутнє, воно має дорівнювати тому, що оголошує самозвіт, і завантаження відхиляє плагін, звіт якого відрізняється; відсутність поля не містить твердження й не порівнюється.

Додаткові властивості не дозволені.

plugin.spec.provider.contract.inputKinds

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

ВластивістьТипОбов’язковаОпис
sourcedбулеваніРендерить підключений набір файлів (chart, модуль, compose-файл).
synthesizedбулеваніРендерить синтезоване робоче навантаження в нативні артефакти провайдера.
artifactsStandaloneбулеваніРендерить автономний вузол лише з артефактами — що містить імпортовані документи артефактів і не має ні джерела, ні робочого навантаження.

Додаткові властивості не дозволені.

plugin.spec.provider.contract.artifactDelimiters

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

ВластивістьТипОбов’язковаОпис
leftstringтакВідкривальний роздільник.
rightstringтакЗакривальний роздільник.

Додаткові властивості не дозволені.

plugin.spec.provider.contract.assemblyNameAnnotation

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

ВластивістьТипОбов’язковаОпис
annotationstringтакКлюч анотації межі, з якого плагін зчитує ім’я зібраного артефакту.
requireUniqueбулеваніЧи мають усі межі, що беруть участь в одній групі диспетчеризації, погоджуватися щодо розв’язаного значення анотації. Якщо true, група, межі якої розв’язують анотацію в різні значення, зупиняє збірку; якщо false, плагін приймає перше розв’язане значення.

Додаткові властивості не дозволені.

plugin.spec.provider.contract.sourceIgnore

Файли, які екосистема цього провайдера ніколи не постачає поряд із джерелом, що він рендерить, у вигляді правил ігнорування в синтаксисі gitignore — зафіксовані під час публікації правила source_ignore, які оголошує його самозвіт. Коли автор закріплює Recipe або FeatureRecipe, можливість якого обслуговує для нього цей провайдер, ці правила поєднуються з власним .aggregaignore автора й записуються в entity.lock поряд із сутністю разом з ім’ям цього плагіна, і кожна подальша публікація, порівняння та рендеринг локального джерела сутності застосовує записані правила. Якщо поле присутнє, воно має дорівнювати тому, що оголошує самозвіт, і завантаження відхиляє плагін, звіт якого відрізняється; відсутність поля не містить твердження й не порівнюється.

ВластивістьТипОбов’язковаОпис
patternsstring[]ніВласні шаблони ігнорування екосистеми, кожен з яких відраховується від кореня локального каталогу джерела, у порядку їх застосування.
filesstring[]ніІмена файлів ігнорування, які екосистема враховує всередині джерела, — .helmignore для chart. Рядки кожного такого файлу є додатковими шаблонами, що відраховуються від каталогу, який його містить.

Додаткові властивості не дозволені.

plugin.spec.pipelineStep

Блок pipeline-step для плагіна pluginType: pipeline-step: можливості провайдера, з якими сумісний його крок. Присутній лише в плагінах pipeline-step; відсутній у плагінах усіх інших типів.

ВластивістьТипОбов’язковаОпис
capabilitiesstring[]ніЗаписується із самозвіту .wasm плагіна командою aggrega plugin gen-catalog, тож джерелом цього списку є плагін. Автор може звузити його перед публікацією, вилучивши запис, якого ця сутність не повинна пропонувати, але не може додати жодного, якого немає в самозвіті: публікація, а також aggrega validate з .wasm плагіна, переданим через --plugin, відхиляють список, що називає можливість, якої немає в самозвіті. Публікація надсилає сутність у тому вигляді, у якому її написано, ніколи не переписуючи цей список, і зазначає кожну можливість із самозвіту, яку список пропускає. Можливості провайдерів, з якими сумісний крок конвеєра цього плагіна, — назви можливостей провайдерів, як-от helm або compose, відрендерений результат яких крок уміє перетворювати. Крок пишеться під форму результату одного провайдера за раз, тож список є явним твердженням про перевірену сумісність, а не побажанням. Записи зберігають авторський порядок. Це доступний для каталогу запис цього твердження; збірка читає те саме твердження з плагіна, коли крок торкається області, і зупиняється, якщо провайдера, що рендерить документи цієї області, немає серед них. Порожній або відсутній список не оголошує твердження про сумісність, тож жодна область не допускає цей крок.

Додаткові властивості не дозволені.

plugin.spec.parser

Блок parser для плагіна pluginType: parser: вихідні формати, які він перетворює на канонічне структуроване дерево. Присутній лише в плагінах parser; відсутній у плагінах усіх інших типів.

ВластивістьТипОбов’язковаОпис
capabilitiesstring[]ніЗаписується із самозвіту .wasm плагіна командою aggrega plugin gen-catalog, тож джерелом цього списку є плагін. Автор може звузити його перед публікацією, вилучивши запис, якого ця сутність не повинна пропонувати, але не може додати жодного, якого немає в самозвіті: публікація, а також aggrega validate з .wasm плагіна, переданим через --plugin, відхиляють список, що називає можливість, якої немає в самозвіті. Публікація надсилає сутність у тому вигляді, у якому її написано, ніколи не переписуючи цей список, і зазначає кожну можливість із самозвіту, яку список пропускає. Формати джерел, які цей парсер перетворює на канонічне структуроване дерево, кожен записаний як parse:<format> — наприклад, parse:yaml. Префікс є частиною запису, тож плагін, що оголошує кілька форматів, містить по одному запису на формат. Записи зберігають авторський порядок. Запитаний формат розв’язується до парсера, список якого містить відповідний запис; формат, який не оголошує жоден парсер, зупиняє збірку, а формат, оголошений кількома плагінами-парсерами, зупиняє її як неоднозначний. Порожній або відсутній список не оголошує твердження щодо форматів, тож плагін нічого не парсить.

Додаткові властивості не дозволені.

plugin.spec.importer

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

ВластивістьТипОбов’язковаОпис
capabilitiesstring[]ніЗаписується із самозвіту .wasm плагіна командою aggrega plugin gen-catalog, тож джерелом цього списку є плагін. Автор може звузити його перед публікацією, вилучивши запис, якого ця сутність не повинна пропонувати, але не може додати жодного, якого немає в самозвіті: публікація, а також aggrega validate з .wasm плагіна, переданим через --plugin, відхиляють список, що називає можливість, якої немає в самозвіті. Публікація надсилає сутність у тому вигляді, у якому її написано, ніколи не переписуючи цей список, і зазначає кожну можливість із самозвіту, яку список пропускає. Зовнішні формати джерел, які цей імпортер перетворює на чернеткові файли Aggrega для авторингу, кожен записаний як import:<format> — наприклад, import:terraform. Префікс є частиною запису, тож плагін, що оголошує кілька форматів, містить по одному запису на формат. Записи зберігають порядок автора. Запитаний формат імпорту розв’язується в імпортер, список якого містить відповідний запис; формат, який не оголошує жоден імпортер, зупиняє імпорт, а формат, оголошений кількома плагінами-імпортерами, зупиняє його як неоднозначний, якщо запис plugins.importer у конфігурації робочого простору не під’єднує один із них, який тоді й виконується. Порожній або відсутній список не оголошує жодного формату, тож плагін нічого не імпортує.
detectobject[]ніНалежить машині, не заповнюйте вручну: виводиться із самозвіту .wasm плагіна, коли з нього генерується сутність, і записується тут у порядку, оголошеному самозвітом. Сигнатури, за якими розпізнається джерело форматів цього імпортера, коли імпорт не називає формату. aggrega import читає сигнатури кожного імпортера, що міститься в каталозі робочого простору, включно з усіма версіями, а також вбудованих імпортерів компілятора, зіставляє їх із джерелом, не знаючи, що являє собою будь-який формат, і читає джерело як формат того єдиного імпортера, чия сигнатура збігається; джерело, з яким не збігається жодна сигнатура, відхиляється із запитом формату, а джерело, з яким збігаються сигнатури кількох форматів, відхиляється з їх переліком. Імпортер, що розпізнає джерело, розпізнає його як кожен оголошений ним формат, тож для імпортера, що оголошує кілька форматів, кожен збіг відхиляється як неоднозначний. Якщо список присутній, він має дорівнювати тому, що оголошує самозвіт плагіна, запис за записом і в тому ж порядку, а завантаження й публікація відхиляють плагін, звіт якого відрізняється, із зазначенням цього поля. Відсутність не робить жодного твердження й не порівнюється, і тоді до форматів імпортера можна дістатися лише назвавши їх.

Додаткові властивості не дозволені.

plugin.spec.importer.detect[]
ВластивістьТипОбов’язковаОпис
syntaxstringтакСинтаксичний формат, у якому розбирається джерело — наприклад, json або yaml, — тобто формат, який плагін-парсер оголошує як parse:<syntax>. Джерело розбирається парсером, який каталог робочого простору надає для цього синтаксису, або, для синтаксису, для якого каталог парсера не надає, — вбудованим у компілятор, щонайбільше один раз, незалежно від кількості сигнатур, що називають цей синтаксис, а джерело, яке в ньому не розбирається, не збігається з жодною сигнатурою, що його називає. Синтаксис, для якого парсера не надає ні каталог, ні компілятор, зупиняє розпізнавання із зазначенням відсутності цього парсера. Довжина щонайменше 1 символ.
filesstring[]ніШаблони імен файлів, до яких застосовується сигнатура, що зіставляються з кінцем імені джерела, роздільники в якому читаються як прямі скісні риски: шаблон з одного сегмента — з власним іменем файлу, а шаблон із кількох сегментів, розділених скісними рисками, — з такою ж кількістю кінцевих сегментів його шляху, тож .vscode/mcp.json збігається з файлом mcp.json у каталозі .vscode. У межах сегмента * відповідає будь-якій послідовності символів, ? — одному символу, а [...] — одному символу з класу. Сигнатура застосовується, коли збігається будь-який шаблон. Відсутність або порожнє значення застосовує її до джерела, що є одним файлом, хоч би як він називався, і до жодного файлу каталогу. Шаблони сигнатур імпортера також визначають, які файли каталогу передає йому aggrega import.
matchobject[]ніПредикати, яким має задовольняти розібране дерево, усі без винятку, в оголошеному порядку. Відсутність або порожнє значення не вимагає від дерева нічого, крім розбору в цьому синтаксисі.

Додаткові властивості не дозволені.

plugin.spec.importer.detect[].match[]
ВластивістьТипОбов’язковаОпис
pathstringтакМісце в дереві, куди дивиться предикат, записане як ключі, з’єднані крапками від вершини дерева: data.nodes позначає член nodes об’єкта data верхнього рівня. Сегмент, записаний як ціле число 0 або більше, вибирає цю позицію масиву з відліком від нуля, тож nodes.0.type позначає type першого вузла; кожен інший сегмент вибирає член об’єкта. Довжина щонайменше 1 символ.
isstring (enum)такЧого має досягти шлях: present виконується, коли шлях досягає значення будь-якого виду, зокрема null; absent виконується, коли шлях нічого не досягає; object, array, string, number і boolean виконуються, коли шлях досягає значення відповідного виду. Допустимі значення: "present", "absent", "object", "array", "string", "number", "boolean"
equalsstringніРядок, якому має точно дорівнювати значення, якого досягає шлях; значення, що не є рядком, ніколи йому не дорівнює. В одному предикаті оголошується не більше одного з equals і prefix. Довжина щонайменше 1 символ.
prefixstringніРядок, з якого має починатися значення, якого досягає шлях; значення, що не є рядком, ніколи з нього не починається. В одному предикаті оголошується не більше одного з equals і prefix. Довжина щонайменше 1 символ.

Додаткові властивості не дозволені.