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

aggrega lint

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

Домовленості відрізняються від коректності. aggrega lint ніколи не перевіряє, чи вміст правильно сформований і чи він скомпілюється, — це робить aggrega validate, яка повторює ті самі три межі для схеми, стовпів, розв’язання посилань, extends, можливостей типів вхідних даних і рендерингу. Селектор сокета чи слота, який граматика селекторів не може прочитати, — це помилка коректності, тож lint нічого про нього не повідомляє: його відхиляє validate, як для всього каталогу, так і для однієї сутності Component чи Feature, — див. оголошені селектори. Дві команди доповнюють одна одну: validate повідомляє, чи коректний вміст; lint повідомляє, чи його можна опублікувати згідно з домовленостями каталогу.

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

Шлях до сутності можна вказати позиційно або через --entity <path>. --release не можна поєднувати з аргументом сутності — вони вибирають різні межі; якщо передати обидва, виконання зупиняється.

Домовленості для всього каталогу (без аргументу)

aggrega lint без аргументу запускає структурні правила дисципліни публікації для кожної сутності каталогу, знайденої в налаштованих каталогах. Результати мають рекомендаційний характер: вони повідомляються з рівнем серйозності warn і ніколи не зупиняють роботу лише через порушення домовленості. Використовуйте цей режим, щоб перевірити каталог на відхилення в іменуванні, відповідності категорій каталогам і префіксах анотацій. Сутність Aggregate, Manifest, Release чи Workload у директорії каталогу пропускається, а не перевіряється: прохід підраховує кожен такий тип у рядку not checked: після свого підсумку й відсилає вас до режиму сутності, який перевіряє документ будь-якого типу.

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

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

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

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

    Release release-compose.yaml reads catalog-compose
    conventions checked: 7 entities, 0 advisory finding(s)
    Release release-helm-synth.yaml reads catalog-helm-synth
    conventions checked: 8 entities, 0 advisory finding(s)

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

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

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

Домовленості в межах сутності Release (--release)

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

Це також єдина область, у якій доступна ціла сутність Release, тож саме тут виконуються правила, що читають один запуск, — правило облікових даних підключення, описане в розділі Правила дисципліни. Таке правило виконується один раз на перевірку, після правил для окремих сутностей, над трьома документами: сутністю Aggregate, яку розгортає Release, у тому вигляді, як її написав автор; сутністю Release з уже згорнутим ланцюжком extends, тож дочірня Release містить те, що успадковує; і, для кожного компонента, який оголошує Aggregate, сутністю Component, екземпляром якої є цей компонент, у тому вигляді, як її розв’язує каталог. Жодного значення параметра серед них немає, як і в кожній області: Release надходить без свого блоку parameters, зокрема без значень, успадкованих від базової, а Aggregate — без своїх типових значень і без значень, які вона передає кожному імпортованому модулю, — див. Що отримує плагін-лінтер. Знахідки цього правила повідомляються для файлу Release.

Це відповідник для домовленостей до aggrega validate --release, яка перевіряє те саме замикання на коректність.

Лінтери, які запускає ця область, звіряються із записом довірених ідентичностей плагінів поруч із Release, так само як під час збірки. Перш ніж запустити будь-який із них, --release порівнює налаштовані підключення plugins.linter із записом довіри плагінів: записаний плагін, який конфігурація більше не підключає, — лінтер чи шлюз — зупиняє прохід, а лінтер, прочитаний із кешу, артефакт якого не збігається із записаним, відхиляється замість запуску. Лінтер, прочитаний із кешу, під час завантаження також звіряється зі своїм записаним підписом: якщо його запис фіксує перевірений підпис, матеріал підпису, на який цей факт указує в кеші, перевіряється знову, і прохід зупиняється з E0144, якщо його немає або він відрізняється, та з E0332, якщо його створено для іншого плагіна, ніж прочитаний лінтер, — signature, скопійований з іншого запису, — незалежно від вимоги щодо підпису; якщо конфігурація довіри робочого простору вимагає підпису, запис без підпису — або відсутність запису для лінтера, зокрема видалений запис, — зупиняє прохід з E0331 за тих самих налаштувань, за яких aggrega pull відхилила б його як непідписаний. Кожна з трьох помилок називає свій спосіб виправлення — aggrega pull --release <release>, яка перевіряє підпис лінтера в його реєстрі, записує його й кешує пакет, на який він указує, перезаписуючи кешовану копію, що більше не відповідає своєму дайджесту. Лінтер, що надається з копії всередині бінарного файлу компілятора, ніколи не підлягає цій вимозі. Це збої проходу, а не знахідки щодо домовленостей, тож вони зупиняють виконання там, де знахідка цього не зробила б. Області всього каталогу й однієї сутності не називають жодної Release і не читають жодного запису, тож лінтер, який вони читають із кешу, перевіряється лише за його кешованим маніфестом. Ще до всього цього --release називає кожне відкликання, записане щодо того, від чого залежить Release, як рядок deprecation: у формулюванні, яке виводить aggrega build, — як маркер, який lock-файл записує щодо закріпленого посилання, так і маркер, який запис довіри записує щодо лінтера чи шлюзу, — тож прохід повідомляє про це, навіть коли його зупиняє одна з описаних вище відмов. Відкликання не змінює жодної знахідки й жодного коду виходу, а запис довіри, який існує, але не може бути прочитаний, зупиняє прохід, а не вважається записом, у якому нічого не записано.

Дисципліна сутностей: локальна перевірка та шлюз публікації

Режим шляху до сутності працює з одним із двох рівнів серйозності:

  • Типовий (локальний). Запускає правила дисципліни над локальним вмістом сутності з рівнем серйозності warn. Доступу до реєстру немає; перевірку підвищення версії пропущено. Використовуйте його під час написання.
  • --pre-publish (шлюз публікації). Отримує з реєстру останню опубліковану версію сутності, що не є попереднім випуском, запускає ті самі правила з рівнем серйозності halt, а також класифікує зміну як PATCH / MINOR / MAJOR і зупиняється, якщо запропоноване підвищення metadata.version менше, ніж вимагає зміна. Використовуйте його в процесі публікації, перед aggrega push. --pre-publish застосовується лише до форми з однією сутністю.

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

Які типи перевіряє режим сутності

Режим сутності перевіряє lint-правилами вказаний вами документ, незалежно від його типу, і передає його кожному правилу, що читає одну сутність. Кожне правило саме вирішує, які типи воно описує, а правило, якому передано тип, якого воно не описує, нічого не повідомляє. Тож вказання сутності Aggregate, Manifest, Release чи Workload — типів, які прохід усього каталогу пропускає й перелічує у своєму рядку not checked:, — так само запускає над нею правила, і повідомляти можуть лише правила, що описують цей тип:

ПравилоТипи, про які воно повідомляє в режимі сутності
Префікс анотаціїБудь-який тип: правило читає metadata.annotations незалежно від типу документа.
Прямі розширення x-aggrega-*Будь-який тип: правило читає spec.schema незалежно від типу документа.
Форма іменіComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary і ArtifactLibrary.
Категорія відповідає директоріїComponent.
Слот секрету оголошує sensitiveComponent і Feature.
Анотація облікових даних метрик відповідає providesComponent.
Provides, оголошені сутністю ComponentRecipe.
Динамічні посилання, перевизначення IdSchemaLibrary.
Типові обмеження сутності PluginPlugin.
Порівняння підвищення версії (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate і Plugin (плагін, вбудований у компілятор, не порівнюється); зміна будь-якого іншого типу класифікується як MAJOR.
Облікові дані з’єднання відповідають ключу ціліЖодного: правило читає всю сутність Release, тож запускається лише з --release.

Сутності Aggregate, Manifest, Release і Workload не оголошують у своїх схемах ні metadata.annotations, ні spec.schema, тож документ одного з цих типів, що відповідає схемі свого типу, не отримує нічого від двох правил, які читають будь-який тип; ці два правила повідомляють про нього лише тоді, коли він усе ж містить один із цих ключів, який схема його типу відхиляє як неочікувану властивість. Вказання сутності Aggregate додає порівняння підвищення версії в режимі --pre-publish, яке порівнює її з опублікованою версією, як описують критерії нижче.

Рубрика підвищення версії

У режимі --pre-publish зміну порівнюють із попередньою опублікованою версією та класифікують:

  • PATCH — зміни лише в документації або коментарях.
  • MINOR — суто адитивні зміни (нове необов’язкове поле, новий запис).
  • MAJOR — вилучення, звуження типу або перетворення раніше необов’язкового поля на обов’язкове.

Порівняння залежить від виду сутності: сутності Component, Feature і SchemaLibrary порівнюються з урахуванням їхніх полів, що містять схему; сутність MappingLibrary порівнюється на рівні ключів записів (тіла записів непрозорі, тож змінене тіло консервативно вважається MAJOR); сутності Recipe і FeatureRecipe порівнюються за їхніми несучими полями. Сутність Aggregate порівнюється за її оголошеннями параметрів, її компонентами та її підсистемами; значення параметра за замовчуванням потрапляє до порівняння не більше, ніж будь-яке інше значення параметра (див. Що отримує плагін лінтера), тож зміна, обмежена значенням за замовчуванням, — його додавання, зміна чи вилучення, — до порівняння не входить, як і зміна ключа поза словником слотів параметрів. Недостатнє підвищення версії зупиняє виконання з діагностикою, яка називає потрібне підвищення.

Правила дисципліни

Більшість правил мають налаштування на рівні робочого простору в lint.publishing_discipline у файлі .aggrega-config.yaml і відповідне перевизначення в CLI, причому кожне перевизначення має відповідник --no-. Пріоритет такий: --no-<flag> переважає --<flag>, а той переважає значення з конфігурації робочого простору, на кожному рівні: весь каталог, сутність Release та окрема сутність. Усі правила типово ввімкнено, і кожне типове значення ґрунтується або на механізмах платформи, або на задокументованій домовленості каталогу; налаштування дають змогу відмовитися від правила робочому простору, який має причину його послабити.

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

  • Префікс анотацій — зарезервовані простори імен (aggrega.ai/, а також feature.aggrega.ai/ поза сутністю Feature) належать платформі й відхиляються в інших ключах. Типово ввімкнено; вимкнути можна через allow_aggrega_ai_prefix.
  • Форма імені — кожен вид сутності має домовленість щодо форми імені (кількість сегментів для cloud-native видів; PascalCase для видів бібліотек). Типово ввімкнено; вимкнути можна через allow_nonstandard_names.
  • Динамічні посилання — записи SchemaLibrary не можуть використовувати $dynamicAnchor / $dynamicRef (розгортання $ref платформою під час компіляції не здатне їх розв’язати). Типово ввімкнено; вимкнути можна через allow_dynamic_refs.
  • Перевизначення id — записи SchemaLibrary не можуть оголошувати власний $id (платформа сама виводить канонічний $id). Типово ввімкнено; вимкнути можна через allow_id_overrides.
  • Категорія відповідає каталогу — мітка component.aggrega.ai/category сутності Component має збігатися з першим сегментом каталогу під core/, узятим із закритого набору категорій (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Типово ввімкнено для сутностей за шляхом core/; вимкнути можна через allow_category_mismatches.
  • Прямі розширення x-aggrega-* — безпосередньо писати ключі x-aggrega-* у схемі сутності Component або Feature не рекомендується: натомість слід користуватися штатним шляхом написання. Типово ввімкнено; вимкнути можна через allow_direct_x_aggrega_extensions.
  • Provides, оголошені в Component — spec.provides сутності Recipe публікує по одному ключу на запис, а сутність Component, яку реалізує Recipe, оголошує в стовпі provides свого spec.schema, які ключі надає тип. Саме з цим оголошенням звіряється посилання inject from:, тож ключ, який Recipe публікує без оголошення в Component, створюється, а потім відхиляється там, де споживач його підключає. Публікація поза оголошеним контрактом приймається під час збирання, тому знахідка є рекомендаційною, а не відхиленням. Типово ввімкнено для Recipes; вимкнути можна через allow_undeclared_recipe_provides.
  • Типові обмеження Plugin — spec.runtime сутності Plugin містить maxMemoryPages і timeoutMs, два обмеження, які хост застосовує, коли завантажує й запускає плагін. Plugin, що не фіксує жодного з них, працює з типовими значеннями платформи, а це безпечний результат, а не помилка, тож правило повідомляє, що діють типові значення і що можна явно зафіксувати обмеження. Типово ввімкнено для сутностей Plugin; налаштування не має.
  • Слот секрету оголошує sensitive — слот вкладення може через свій селектор міток зафіксувати вид сутності Feature, що його заповнює, як secret, а також окремо оголосити sensitive: true, щоб зазначити, що будь-що, яке його заповнює, працює із секретними даними. Селектор визначає, які заповнення допустимі; маркер визначає поводження. Слот, який фіксує вид, але не оголошує маркер, змушує виводити це поводження із селектора замість прямого прочитання. Правило читає кожен слот, який оголошує сутність: слоти її власного блоку вкладень у spec.featuresSchema, а для сутності Component — також слоти, які кожен сокет залежності оголошує в spec.usesSchema.<socket>.featuresSchema для з’єднань, підключених через нього, — знахідка щодо слота сокета називає і сокет, і слот. Типово ввімкнено для Components і Features; налаштування не має.
  • Облікові дані з’єднання відповідають ключу цілі (connection-credential-matches-target-key) — сервер, що перевіряє ключ, зберігає ключ, який він верифікує, у слоті власної сутності Component, а викликач пред’являє ключ на з’єднанні, через яке він досягає сервера. Жоден кінець не бачить вкладень іншого, тож обидва мають один ключ лише тому, що їхні автори записують його на обох кінцях — зазвичай так, що обидва вкладення читають один параметр, — і збірка ніколи їх не порівнює. Це правило порівнює, і це єдине правило, що читає цілу сутність Release, тому воно виконується з --release і в жодній іншій області. Воно знаходить обидва кінці за іменами, які їм дає стандартний каталог: ключ цілі — це слот api_key, який її сутність Component оголошує в spec.featuresSchema, а ключ викликача — слот credential на з’єднанні, записаний за адресою uses.<socket>.<alias>.features.credential у сутності Aggregate або на з’єднанні, яке підключає сутність Release. Для кожного з’єднання, ціль якого оголошує api_key і не позначена як керована, правило повідомляє про з’єднання, що несе облікові дані до цілі з незаповненим слотом ключа, про заповнений слот ключа без облікових даних на з’єднанні та про два кінці, що називають свій секрет по-різному. Порівнюється локатор кожного кінця — origin, який записує вкладення, у values в сутності Aggregate або в infra в сутності Release, — так, як його написав автор, тож два кінці, що читають один параметр, вважаються рівними, а два літерали порівнюються за текстом; нічого не розв’язується, і повідомлення називає компонент, з’єднання, ціль і обидва слоти, але ніколи не цитує жодного локатора, оскільки записаний там текст може бути самим секретом. Ціль, що не оголошує слота api_key, не дає жодних зауважень, а слот, який не є ключем викликача, як-от токен завантаження з реєстру сервера моделей, ніколи не читається. Так само не оцінюється ціль, сутність Component якої позначена component.aggrega.ai/hosting: managed, хоч би що містив її слот api_key: така сутність Component представляє сервіс, який запускає її постачальник, тож ніщо з того, що запускає сутність Release, не перевіряє на ній ключ, і якщо вона оголошує api_key — ключ до розміщеного API моделі, скажімо, під іменем, яке йому дає продукт постачальника, — слот містить ключ, який сутність Release пред’являє цьому постачальнику, а не ключ, який пред’являють її викликачі. Ціль, позначена self-hosted, external або mixed чи без мітки розміщення, оцінюється. З’єднання на сокеті scrape_target — імені, яке стандартний каталог дає сокету, через який збирач метрик досягає своїх цілей, — є збиранням, і чи мають облікові дані збирання бути ключем викликача цілі, залежить від продукту цілі: одні віддають метрики без облікових даних, інші ховають їх за ключем, який пред’являє кожен викликач, а ще інші приймають власний токен. Тож для збирання правило читає, що зазначає сутність Component цілі в анотації observability.aggrega.ai/metrics-credential: за none збирання не оцінюється взагалі; за separate-token його облікові дані ніколи не порівнюються з api_key цілі, тож про нього не повідомляється жодне з трьох зауважень; за target-key воно оцінюється як будь-яке інше з’єднання. Правило читає лише ці три значення, тож збирання з ціллю без анотації або з будь-яким іншим значенням оцінюється як будь-яке інше з’єднання, — і кожне з’єднання на іншому сокеті, зокрема з’єднання з моделлю, інструментом чи сховищем даних, оцінюється однаково, хоч би що казала анотація цілі. Правило читає вкладення, записані на цілі та на з’єднанні: вкладення api_key, що досягає цілі з підсистеми чи межі, натомість залишає це з’єднання неоціненим, вкладення, додане анотацією, до них не належить, тож слот ключа, заповнений лише так, читається як незаповнений, кінець, вкладення якого не записує локатора, порівнюється лише за тим, чи він заповнений, а компонент, який додає імпортований модуль, не читається. Оскільки імена слотів, мітка розміщення, ім’я сокета збирання та анотація метрик є домовленостями каталогу, яких не позначає жодне ключове слово схеми, каталог, що називає слоти інакше, не дає зауважень, сокет збирання з іншим іменем оцінюється як будь-який інший сокет, а сутність Component, що зберігає ключ постачальника в слоті з іменем api_key без мітки керованості, читається як ціль, що перевіряє цей ключ, оскільки ім’я слота, мітка й анотація — це все, що правило читає в сутності Component цілі. Типово ввімкнене; вимкнути можна через allow_connection_credential_mismatches.
  • Анотація облікових даних метрик відповідає provides (metrics-credential-annotation-matches-provides) — сутність Component може зазначати два факти про свої метрики. Її анотація observability.aggrega.ai/metrics-credential зазначає, як автентифікуються метрики продукту: none — вони віддаються без облікових даних; target-key — вони приймають ключ, який сутність Component вимагає від кожного викликача, той, що зберігається в її слоті api_key; separate-token — вони приймають власний токен. Ключ provides metrics_credential_required, оголошений у стовпі provides її spec.schema, — це те, що публікує кожна з її сутностей Recipes, щоб сказати, чи потребують метрики одного екземпляра облікових даних, — а це може залежати від конфігурації екземпляра, оскільки метрики за ключем викликача потребують їх лише доти, доки ключ вкладено, тож анотація не може його замінити. Обидва зазначають один факт про продукт, тому це правило вимагає їхньої узгодженості: про сутність Component з анотацією none, що оголошує ключ, і про сутність з анотацією target-key або separate-token, що його не оголошує, повідомляється, і зауваження називає сутність Component, значення анотації та ключ, який зайвий або відсутній. Сутність Component без анотації або з будь-яким іншим значенням не дає зауважень. Правило читає сутність Component так, як її написано, тож сутність Component, що розширює іншу — схема якої є схемою її бази, — не дає зауважень, а її база читається там, де її оголошено; стовп provides, записаний як посилання, композиція або екранованим тілом у вигляді тексту, не є тим, що правило може перелічити, тож і така сутність Component не дає зауважень. Типово ввімкнене для сутностей Components; не має налаштування.

Незмінність артефактів не належить до цих правил і не має налаштування. Опублікована name:version остаточна: aggrega push порівнює дайджест, уже опублікований за цим тегом, із дайджестом, який дав би вміст, що має бути надісланий, і відмовляється перезаписати його іншим вмістом. Повторне надсилання побайтово ідентичного вмісту нічого не вивантажує і додає лише те, чого цій публікації ще бракує, — дату публікації та підпис, якщо надсилання підписує. Жоден прапорець і жодне налаштування конфігурації робочого простору цього не послаблює, бо реєстр не надає шляху перезапису, який оператор міг би ввімкнути. Змінений вміст публікується під новою версією; --pre-publish — це те, що перевіряє таке підвищення відносно попереднього релізу.

Прапорці перевизначення окремих правил є шлюзами для одного виклику і навмисно не мають змінної середовища — вони вже підкріплені конфігурацією в .aggrega-config.yaml у lint.publishing_discipline. Загальну модель пріоритетів AGGREGA_* описано в environment-variables.md.

Під час збирання і під час публікації

Правило, що не рекомендує x-aggrega-*, також виконується під час aggrega build, де воно проявляється як попередження; aggrega lint --pre-publish підвищує цю саму знахідку до помилки. Локальні збирання містять пораду; шлюз публікації примусово її застосовує.

Під час написання, у вашому редакторі

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

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

serve:
lint_on_validate: true

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

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

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

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

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

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

Вибір лінтера

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

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

Підключення називає свій плагін через uri:, а function: називає функцію входу цього плагіна. Запис, що називає function:, але не uri:, називає функцію, яка не належить жодному плагіну, тож конфігурація відхиляється вже під час читання з кодом E0224 із зазначенням файлу та місця запису в його списку — додайте uri плагіна, який експортує цю функцію. Запис, що не називає жодного з них, нічого не підключає й пропускається; якщо він єдиний, стандартний лінтер запускається зі своєю типовою функцією входу, так само як і за повної відсутності plugins.linter.

Що отримує плагін-лінтер

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

  • Сутність Aggregate зберігає кожне оголошення параметра, залишаючи лише ключі, якими записують оголошення, — словник слотів параметрів: його тип, опис і обмеження, — і так само обробляється кожне оголошення, вкладене в його properties, items і valuesType. Ключ default оголошення вилучається на кожному рівні шляхом видалення ключа, а не його спорожнення, тож плагін не може визначити, чи задає його оголошення. Ключ поза цим словником вилучається разом з усім його вмістом на кожному рівні: збірка не надає такому ключу жодного значення, а чернетка з помилкою в назві ключа може містити під ним секрет. Запис у parameters, що не є оголошенням, вилучається повністю.
  • Кожен модуль, перелічений у aggregates сутності Aggregate, втрачає свій блок parameters, що містить значення, передані цьому модулю.
  • Сутність Release втрачає свій блок parameters — незалежно від того, чи записує вона значення безпосередньо, чи імпортує їх через $import.
  • Будь-який інший документ, що містить блок parameters у spec, втрачає його повністю; жоден інший вид його не оголошує.

Це стосується сутності, названої в командному рядку, опублікованої версії, з якою її порівнює --pre-publish, кожної сутності, яку обходять перевірка всього каталогу та прохід --release, а також документів, які отримує правило, що читає всю сутність Release. Шаблон, що читає параметр, не є значенням і зберігає свій текст, тож правило все одно бачить, який параметр читає записане значення.

Приклади

Перевірити весь каталог на відхилення від домовленостей:

aggrega lint --catalog ./catalog

Локально перевірити сутність під час написання:

aggrega lint core/datastore/postgres/component.yaml

Запустити перевірку перед публікацією нової версії:

aggrega lint core/datastore/postgres/component.yaml --pre-publish

Послабити одне правило для одного запуску:

aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names

Див. також

  • ./aggrega-validate.md — відповідник для перевірки коректності в тих самих трьох областях.
  • ./aggrega-build.md — виконує валідацію в межах компіляції; показує рекомендаційне попередження x-aggrega-* з рівнем серйозності warn.
  • ./aggrega-push.md — публікує сутність у реєстрі; aggrega lint --pre-publish — це перевірка, що передує публікації.
  • ./aggrega-pull.md — розв’язує та фіксує залежності.
  • ./aggrega-serve.md — мовний сервер, який повідомляє про ці знахідки у вашому редакторі, і параметр, що вмикає рівень перевірки під час кожного редагування.
  • ../errors/warnings.md — нефатальні попередження, зокрема знахідки лінтера в локальному режимі.

Синтаксис

aggrega lint [entity-path] [flags]

Опис

aggrega lint checks publishing CONVENTIONS — naming, category-directory
alignment, annotation prefixes, and the rest of the publishing-linter
discipline. It does not check correctness (schema, pillars, resolution,
render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity
aggrega lint --release <path> conventions across a Release's dependency closure
aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rules
over every catalog entity found under the catalog directories. Where the
workspace configuration gives its Releases catalog directories of their own
under workspace.releases, it runs them 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 it runs them over the entities that
Release's closure reaches, and also runs the rules that read a whole
Release: once, over the Aggregate it deploys, the Release and the
Components the Aggregate's components are instances of, with every
parameter value removed. In both, findings are advisory (warn severity)
and never halt.
With an entity path, lint runs the publishing-linter rule set against
that one entity. In default mode the rules run at warn severity over
local content without consulting any registry. With --pre-publish the
previous registry version is fetched and the schema-evolution
classification is compared against the proposed version bump; mismatches
halt. --pre-publish applies to the single-entity shape only. Per-workspace
policy flags from .aggrega-config.yaml's lint.publishing_discipline block
can be overridden per invocation via the --allow-*/--no-allow-* flag pairs,
in all three shapes.
All three shapes accept -o json, which replaces the human report on standard
output with one structured document: every finding with its severity, the rule
that produced it, its short code (the code printed at the head of its row in
the human report, which aggrega explain expands), its message, and the entity
file it concerns, plus counts by severity. A finding from a rule Aggrega does
not declare, one a linter of your own adds, carries no short code, as its row
prints none. A finding carries a line and column only when the rule that
produced it located the issue that precisely; otherwise the file alone locates
it. The message is the rule's own text, carried through unchanged, so the
structured and human renderings never word a finding differently. The exit
status is the same under either format.

Прапорці

ПрапорецьЗа замовчуваннямОпис
--allow-aggrega-ai-prefixfalseПримусово встановити allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseПримусово встановити allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseПримусово встановити allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseПримусово встановити allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseПримусово встановити allow_dynamic_refs=true для цього виклику
--allow-id-overridesfalseПримусово встановити allow_id_overrides=true для цього виклику
--allow-nonstandard-namesfalseПримусово встановити allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseПримусово встановити allow_undeclared_recipe_provides=true
--baseline—Порівнювати під час перевірки еволюції перед публікацією з цією конкретною вже опублікованою версією замість автоматично вибраної найвищої версії, нижчої за ту, що публікується; має бути тегом у форматі строгого SemVer, наявним у реєстрі (потребує —pre-publish)
--catalog[]Каталог; можна повторювати. Кожен —catalog <dir> додається на початок стека пошуку каталогів (перемагає перший збіг): catalog_dirs робочого простору або, для сутності Release, якій конфігурація робочого простору задає власні каталоги в workspace.releases, каталоги цієї сутності Release; стек завершується каталогом з назвою catalog у корені робочого простору, якщо він є. Порожній список catalog_dirs означає, що жоден локальний каталог не читається. Використовується проходами перевірки домовленостей для всього каталогу та для —release.
--entity—Шлях до YAML сутності, яку слід перевірити лінтером (або передайте його як позиційний аргумент)
--no-allow-aggrega-ai-prefixfalseПримусово встановити allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseПримусово встановити allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseПримусово встановити allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseПримусово встановити allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseПримусово встановити allow_dynamic_refs=false для цього виклику
--no-allow-id-overridesfalseПримусово встановити allow_id_overrides=false для цього виклику
--no-allow-nonstandard-namesfalseПримусово встановити allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseПримусово встановити allow_undeclared_recipe_provides=false
--output, -otextФормат виводу: text|json.
--plugin—Шлях у файловій системі до артефакту .wasm лінтера публікації (запускає цей артефакт замість підключень plugins.linter робочого простору)
--pre-publishfalseОтримати попередню версію з реєстру та перевірити запропоноване підвищення версії за класифікацією еволюції схеми
--release—Шлях до YAML сутності Release для перевірки домовленостей у її розв’язаному замиканні залежностей (взаємовиключний з аргументом сутності). Відносний шлях розв’язується відносно каталогу, у якому ви запускаєте команду, а не відносно кореня робочого простору. Якщо цей каталог не належить жодному робочому простору і корінь не вказано, абсолютний шлях знаходить робочий простір за власною текою сутності Release