Перейти к содержимому
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 применим только к форме с одной сущностью.

Избыточное повышение версии всегда допускается; недостаточное приводит к остановке. При первой публикации сущности (в реестре нет предыдущей версии) проверка повышения пропускается и выводится предупреждение о том, что проверка не выполнялась.

Какие виды проверяет режим сущности

Режим сущности проверяет линтером указанный вами документ, каким бы ни был его вид, и передаёт его каждому правилу, читающему одну сущность. Каждое правило само решает, какие виды оно описывает, и правило, получившее вид, который оно не описывает, ничего не сообщает. Поэтому указание сущности 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.
  • Форма имени — для каждого вида сущностей есть соглашение о форме имени (число сегментов для облачно-нативных видов; 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 без метки managed, читается как цель, проверяющая этот ключ, поскольку имя слота, метка и аннотация — это всё, что правило читает в сущности 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