aggrega inspect
aggrega inspect выводит удобочитаемое представление любой сущности Aggrega — сущности Component из каталога, файла авторской сущности, сущности, опубликованной в реестре, или полностью разрешённой сущности Release. Это основной инструмент отладки, позволяющий понять, что создаст компилятор: какие Components расширяют какие базовые сущности, какой Recipe сопоставлен каждому типу, какие Features подключаются к каждому узлу и откуда именно взялся каждый вклад каждой сущности Feature.
У каждого вида сущностей есть естественное представление его «контракта». inspect показывает этот контракт — схему, которую публикует Component, сопоставления, которые объявляет Manifest, топологию, которую строит Aggregate, подключения Feature к каждому узлу, к которым разрешается Release. Учебные и концептуальные материалы находятся в других разделах; inspect отвечает на вопрос «к чему на самом деле разрешается эта сущность?»
Единственный позиционный аргумент направляется по форме содержимого; подкоманда не нужна. Команда выбирает ветвь по следующей эвристике:
| Форма идентификатора | Ветвь | Вывод |
|---|---|---|
Начинается с ./, ../ или / либо заканчивается на .yaml / .yml | Файловая ветвь | Инспекция файла по его заголовку kind:. |
Начинается с oci:// | Ветвь реестра | Сущность, опубликованная по этой координате, считанная из её реестра и выведенная в том представлении, которое получает файл её вида. См. Чтение опубликованной сущности. |
| Всё остальное | Ветвь каталога | Поиск идентификатора в стеке поиска каталогов по всем видам сущностей; разрешение цепочек extends:; вывод собственного представления найденного вида. |
Три уровня детализации
--list, режим по умолчанию и --detail образуют единую трёхуровневую систему детализации, которую соблюдает каждый вид сущности. --list и --detail взаимоисключающие: если передать оба флага, команда откажется выполняться, а не разрешит конфликт молча.
--list— только идентификаторы. Сущность Component выводит своё имя и имена своих сокетов uses; сущность MappingLibrary выводит имена своих сопоставлений; сущность Aggregate выводит имена своих компонентов с их типами.- по умолчанию — структурированный обзор, рассчитанный на интерактивное использование. Он начинается с идентификации сущности и — для всех видов, кроме сущностей Manifest и Release, — с её описания, если у сущности оно задано; для сущности без описания ничего не выводится, а не пустая строка. Остальная структура зависит от вида: сущность Component показывает свою схему и сокеты; сущность Aggregate показывает компоненты, их значения и рёбра с вложениями, которые несёт каждое соединение, а также граф зависимостей; сущность Release показывает дерево узлов по границам с вложениями Feature, причём каждое вложение, записанное на соединении, выводится под этим соединением.
--detail— полные тела полей. Всё, что содержит вид: сущность Component добавляет свои механизмы self-inject, обязательные Features и метки; сущность MappingLibrary раскрывает полное тело шаблона каждого сопоставления; сущность Recipe добавляет тело рабочей нагрузки, provides и утверждения.
Некоторые виды используют уровни, чтобы постепенно раскрывать всё больше авторского тела. Сущность MappingLibrary на уровне --list показывает имена сопоставлений; на уровне по умолчанию добавляет для каждого сопоставления синтезированный пример использования; на уровне --detail раскрывает полное тело шаблона.
Разрешение: --raw и --resolved
У каждого вида есть естественная глубина разрешения по умолчанию (см. таблицу ниже). --raw и --resolved — всегда доступные переопределения, и они взаимоисключающие: передача обоих флагов отклоняется, а не разрешается молча:
--rawотключает любое разрешение — сущность выводится в авторском виде, прямо из файла.--resolvedвключает полную глубину разрешения для данного вида.
Для видов, которые по умолчанию выводятся в авторском виде, --raw ничего не меняет, а --resolved запускает то разрешение, которое поддерживает вид. Для видов, которые по умолчанию выводятся разрешёнными, --raw — это обход в авторский вид.
--raw воспроизводит файл, поэтому значение, которое автор объявил чувствительным, выводится в нём ровно так, как написано. Это контракт, а не пробел: авторское представление, которое втихую скрывало бы часть себя, не было бы авторским. Обращайтесь с выводом --raw так же, как с файлом сущности, из которого он получен. --output yaml воспроизводит файл точно так же, для любого вида, включая Release.
Сущность Release отвечает ещё на два вопроса, и каждый из ответов — отдельный документ со своим флагом. Скомпилированный граф, в который разрешается Release, — это --ir-graph; его замыкание зависимостей — --closure. См. разделы Машиночитаемый вывод и Замыкание зависимостей: --closure ниже.
Значения по умолчанию для каждого вида
inspect знает виды сущностей, которые можно просматривать по отдельности и которые перечислены в таблице ниже. Виды каталога по умолчанию выводятся в авторском виде — их файлы являются самодостаточными контрактами. Виды экземпляров по умолчанию выводятся в разрешённом виде, потому что их авторский YAML — лишь отправная точка для каскада или конвейера.
| Вид | По умолчанию | Что означает «разрешённый» |
|---|---|---|
| Component | в авторском виде | Файл является самодостаточным контрактом; разрешение выполняется относительно привязки в сущности Manifest и выводится через --show-implements. |
| Feature | в авторском виде | Так же, как для сущности Component. |
| Recipe | в авторском виде | --show-implements разрешает ссылку spec.implements на сущность Component. |
| FeatureRecipe | в авторском виде | --show-implements разрешает ссылку spec.implements на сущность Feature. |
| MappingLibrary | в авторском виде | Записи — непрозрачные строки шаблонов Go; рендеринг происходит в момент использования. |
| SchemaLibrary | в авторском виде | Записи — переиспользуемые определения схем и шаблонов, разрешаемые в момент использования. |
| WorkloadLibrary | в авторском виде | Записи — это повторно используемые тела Workload, которые импортирует сущность Recipe; они вычисляются в момент использования. |
| ArtifactLibrary | в авторском виде | Записи — это повторно используемые наборы артефактов, которые импортирует сущность Recipe; они рендерятся в момент использования. |
| Plugin | в авторском виде | Файл является самодостаточным контрактом плагина: типы сокетов, возможности каждого экспорта, ограничения среды выполнения и указатель на подпись. Адресуется по пути к файлу или по координате <pluginType>/<name> в каталоге. |
| Manifest | в разрешённом виде | Применяется цепочка extends:; выводятся разрешённые сопоставления компонентов и функций. |
| Aggregate | в разрешённом виде | Строится топология — вычисляются граф uses и порядок. |
| Release | в разрешённом виде | Выполняется полный конвейер: разрешение, раскрытие аннотаций, запуск guard-проверок, построение топологии, построение IR. |
Файл, у которого kind: равен Workload, отклоняется: сущность Workload существует только внутри сущности Recipe и не является отдельно просматриваемой сущностью. Чтобы увидеть её Workload, просмотрите сущность Recipe.
Глубина разрешения для каждого вида
У большинства видов нет конвейера — inspect читает файл и отображает его. Содержательно разрешаются три вида экземпляров:
- Manifest применяет свою цепочку
extends:— следуя импортам файлов — и отображает объединённые сопоставления компонентов и функций.--rawпоказывает файл в авторском виде. - Aggregate строит свою топологию: создаётся граф использования и вычисляется порядок зависимостей. Представление по умолчанию показывает компоненты с их значениями и рёбрами, а за ними — граф зависимостей.
--rawпоказывает авторское дерево подсистем. - Release выполняет весь конвейер компиляции вплоть до IR — разрешение, раскрытие аннотаций, запуск проверок, построение топологии, построение IR — и отображает дерево узлов по границам с подключениями сущностей Feature каждого узла и их происхождением. Подключения управления, формирующие граф, выполняются в этом конвейере, а не пропускаются ради представления, поэтому то, что вы видите, отражает их решения: метки подключения
label-transformуже на месте до того, как с ними что-либо сопоставляется, а внедрённые подключениемannotation-transformаннотации раскрываются в подключения сущностей Feature точно так же, как написанная вами аннотация. Подключение, плагин которого эта команда не может разрешить, останавливает её, а не оставляет вам граф, построенный без решений этого плагина. Сущность Release, расширяющая другую, отображается — в этом представлении и в--ir-graph— как Release, в который складывается её цепочкаextends:, то есть тот, который читает её сборка, поэтому Release, указывающий только своего родителя, показывает Aggregate, Manifest и границы этого родителя под собственным именем. Manifest, на который указывает сущность Release, тоже составляется через собственную цепочкуextends:— независимо от того, расширяет ли Release что-либо, — поэтому подключение, сопоставление которого наследует этот Manifest, показывает реализацию, которую использует сборка.--rawвыводит файл сущности Release дословно, без конвейера.--closureзадаёт другой вопрос о той же сущности Release и не запускает конвейер вовсе; см. Замыкание зависимостей:--closure.
Отдельного флага глубины нет; переключатель --raw / --resolved — единственное средство управления разрешением, накладываемое на естественное значение по умолчанию каждого вида.
Поведение при ошибках
Если упомянутый соседний файл не удаётся загрузить, команда сразу останавливается — например, когда Release указывает на отсутствующий Aggregate или в стеке поиска есть повреждённая сущность каталога. Она останавливается с понятным сообщением, а не выводит частичный результат, и режима продолжения после ошибки загрузки нет: если документ, нужный для разрешения, не читается, разрешать дальше нечего. Если разрешение имени останавливается на одном документе каталога, который загрузка отклоняет, сообщение указывает это отклонение один раз: заголовок с категорией и, если отклонение называет условие, его кратким кодом, затем документ, затем что в нём не так — для документа, который отклоняет схема его вида, строка и нарушенное ограничение. Сообщение не предлагает переместить файл — каталог его прочитал, именно поэтому он и был отклонён.
Сущность Release, композицию которой отклоняют проверки компилятора, отклоняется, а не отображается. Разрешение Release строит граф, и проверки, которые сборка выполняет над готовым графом, — ребро uses:, цель которого не удовлетворяет selector: его сокета, Feature, присоединённая к компоненту, который её appliesTo: не допускает, и прочие — выполняются и здесь, с той же диагностикой, что выводит сборка тех же документов. Отклонение перечисляет все находки за один запуск, а не останавливается на первой, так что за один проход вы видите весь список исправлений, а не только его первый пункт. Именно это сохраняет честность команды в отношении развёртывания: представление, отобразившее композицию, которую сборка отклоняет, сообщало бы, что рабочее пространство в порядке, хотя это не так. Выборки, которые ничего не разрешают, не затрагиваются — --raw, --output yaml и --closure воспроизводят или разрешают написанное вами без построения графа.
Release, чей файл блокировки больше не соответствует тому, во что он разрешается, отклоняется с остановкой, которую выводит aggrega build. Если рядом с сущностью Release лежит файл блокировки, каждый вариант выбора, который разрешает Release, — представление по умолчанию, --resolved, --ir-graph и --closure — сверяет этот файл с тем, во что разрешается Release, с помощью сравнения дрейфа, которое сборка выполняет перед рендерингом. Файл блокировки, который больше не соответствует, останавливает команду отказом сборки E0130: каждая запись, подвергшаяся дрейфу, а затем aggrega pull --release <release>, который это устраняет. В стандартный вывод ничего не записывается, и команда завершается с ненулевым кодом, потому что картина, построенная по каталогу в его текущем состоянии, показала бы то, чего не рендерит ни одна сборка этой сущности Release. --raw и --output yaml сами по себе не читают ни файл блокировки, ни каталог и не сверяются с ним. Release без файла блокировки рядом разрешается по каталогу в его текущем состоянии.
Для файла с нераспознанным kind: сообщается неизвестный вид и файл, из которого он взят. Для файла Workload сообщается, что этот вид только встраиваемый, и называется сущность, в которую он встраивается. Идентификатор oci://, который не удаётся прочитать, отклоняется с условием, указывающим причину; они перечислены в разделе Чтение опубликованной сущности.
Разрешение по каталогу
Стек поиска по каталогу собирается с многоуровневым приоритетом: сначала идут флаги --catalog (добавляются в начало, по порядку), затем catalog_dirs рабочего пространства из .aggrega-config.yaml (для сущности Release, которой конфигурация задаёт собственные каталоги в workspace.releases, на их месте стоят каталоги этой сущности Release), затем каталог catalog в корне рабочего пространства, который читается независимо от того, указывает ли на него что-либо. Рабочее пространство, в котором catalog_dirs записан как пустой список, не читает локальный каталог вовсе. Стек работает по принципу «первый побеждает»: идентичностью сущности владеет самый ранний каталог, который её объявляет, а копия из более позднего каталога затеняется. Ветвь каталога разрешает идентификатор по этому стеку среди всех видов сущностей в фиксированном порядке приоритета и отображает первое совпадение через собственное представление этого вида; ветви файла и релиза загружают из него упоминаемые сущности каталога, когда нужно разрешить сопоставление сущности Manifest или родителя extends:. Родитель extends:, которого нет в стеке, читается там же, где его читает сборка: из кэша артефактов, под закреплением, которое lockfile сущности Release записывает для него, — названной сущности Release или, если ни одна не названа, каждой сущности Release в рабочем пространстве. Поэтому базу, опубликованную в реестре, здесь можно разрешить, как только aggrega pull загрузит и закрепит её, а до этого команда отклоняется с указанием aggrega pull --release <release>. Ничего не загружается.
Поиск имени в терминах сущности Release
Имя, указанное само по себе, ищется в собственном стеке рабочего пространства. Если рядом с ним указать --release <release-path>, имя будет искаться в стеке этой сущности Release: в каталогах, которые конфигурация рабочего пространства задаёт этой сущности Release, с добавленными в начало --catalog. Именно это читает сборка этой сущности Release. Поэтому рабочее пространство, в котором хранится по одному варианту каталога на каждую сущность Release и каждый объявляет одну и ту же сущность, отвечает на имя тем вариантом, с которым собирается эта сущность Release:
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlИмя, которое стек этой сущности Release не разрешает, отклоняется, и в пояснении о том, откуда читаются локальные сущности, указывается запись этой сущности Release в workspace.releases, поскольку именно эту запись прочитал поиск. --release выбирает стек, в котором ищется имя, поэтому применяется только к имени, указанному само по себе: путь к файлу и ссылка на реестр читаются как есть и отклоняют этот флаг. --release, указывающий на несуществующий файл или на каталог, отклоняется до начала какого-либо поиска.
Чтение опубликованной сущности
aggrega inspect oci://<host>/<repository>:<tag> читает сущность, опубликованную по этой координате; @<digest> вместо :<tag> точно указывает один манифест. Так можно посмотреть на сущность, которая существует только в реестре: репозиторий — это сегмент вида, за которым следует идентичность сущности, как описано в §6 главы Каталог и реестр, а aggrega push выводит ссылку, по которой выполнена публикация; здесь она читается с префиксом oci://.
Вы видите сущность в том виде, в каком она была опубликована. Сущность, опубликованная вместе с объявленными в ней файлами — сущность Recipe со своим локальным чартом или lock-файлом, сущность Component с импортируемой схемой, — поставляется в виде архива, и сущность извлекается из него: это документ в корне архива, объявляющий публикуемый вид, поэтому шаблон чарта или фрагмент compose, поставляемый рядом, не принимается за неё. Сущность, не объявляющая файлов, поставляется как неизменённый документ, а сущность Plugin читается из её манифеста, а не из исполняемого файла, опубликованного вместе с ней. Затем документ отображается тем же представлением, что и файл этого вида, с теми же уровнями детализации и теми же --raw и --output yaml. Наследование не применяется: показывается то, что издатель поместил по этой координате. Удобочитаемые форматы завершаются сведениями о прочитанном: координата, хранилась ли сущность в виде архива или самого документа, тип носителя, объявленный её манифестом, и дайджест этого манифеста, который при записи как @<digest> вместо :<tag> читает те же байты снова; --output yaml выводит документ и ничего после него.
Что проверяется, а что нет. Полученные байты сверяются с дайджестом, который записан для них в собственном манифесте артефакта; это подтверждает, что это именно те байты, которые указывает манифест. Эта проверка выполняется относительно того, что отдал реестр, а не относительно чего-либо записанного заранее: подпись, прикреплённая к артефакту, не проверяется, а отзыв, записанный для него, не сообщается. Ничего не записывается — ни запись в кэше, ни lock-файл, — поэтому чтение координаты не меняет ничего из того, что разрешит последующая сборка.
Команда обращается к сети. Обращение к реестру выполняется с учётными данными, которые хранятся для него на этой машине, из того же хранилища, которое читают aggrega push и aggrega pull; к реестру на этой машине обращение идёт по обычному HTTP. Рабочее пространство в автономном режиме отклоняет чтение до установки любого соединения.
Чтение, которое не может дать ответ, завершается с ненулевым кодом и ничего не выводит в стандартный вывод. Для каждого сбоя ниже указаны его условие и способ устранения; о полной недоступности реестра сообщается с сетевой ошибкой, прервавшей чтение:
| Что произошло | Условие |
|---|---|
| По ссылке ничего не опубликовано | E0137 |
| Реестр отклонил учётные данные, или для него они не сохранены | E0138 |
| Рабочее пространство в автономном режиме | E0125 |
| Артефакт — архив, который невозможно распаковать | E0300 |
| В корне архива нет документа сущности | E0298 |
| В корне архива более одного документа сущности | E0299 |
| Документ не является сущностью вида, публикуемого реестром | E0301 |
Каждый код перечислен в справочнике ошибок. Ссылка, в которой не указан репозиторий или не указаны ни тег, ни дайджест, отклоняется с указанием правильной формы записи. --ir-graph и --closure отклоняются до какой-либо загрузки, поскольку ни один вид, публикуемый реестром, не является сущностью Release.
Уведомления об устаревании и отзыве
После публикации артефакта издатель может записать для него маркер, указывающий, что опубликованная версия устарела или отозвана. Когда ветвь каталога разрешает сущность, inspect сообщает о любом таком маркере под собственным представлением сущности — для каждого вида, который она разрешает по имени, а не только для сущности Component.
Уведомление называет уровень серьёзности, записанный издателем, — warning, error или retracted, — а также версию, для которой был записан маркер, причину, замену, если она указана, и дату выпуска. Сообщается обо всех трёх уровнях. Это шире, чем набор, который меняет результат разрешения сборки: версия с пометкой retracted исключается из выбора версий, тогда как warning и error носят рекомендательный характер и по-прежнему выбираются. inspect показывает вам, что сказал издатель; он не решает, что вы получите.
Уведомление читается из локального индекса реестра, из которого разрешается сущность; этот индекс строит aggrega registry update, поэтому сеть не нужна и всё работает в автономном рабочем пространстве. Поскольку индекс — это снимок, в конце уведомления указывается, когда был сделан этот снимок, и называется команда, которая его обновляет. Рабочее пространство без построенного индекса ничего не сообщает, поэтому отсутствие уведомления означает «в этом снимке ничего не записано», а не «ничего не записано».
О маркере сообщается, только если его собственная подпись проходит проверку относительно подписантов, которых признаёт политика доверия реестра. О неподписанном маркере или маркере, подпись которого не проходит проверку, не сообщается: утверждение, которое нельзя аутентифицировать, не выдаётся за факт.
Уведомление сопровождает представления для чтения человеком. Ни --output yaml, ни --ir-graph его не добавляют, поэтому потребитель, разбирающий любой из этих выводов, получает документ и ничего больше.
Разобранные примеры
Поиск сущности Component в каталоге
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"Представление по умолчанию показывает описание сущности Component, если оно задано, затем разрешённую схему (после слияния extends:) и объявленные uses-сокеты. У Component выше описание не задано, поэтому вывод сразу начинается со схемы. --detail добавляет механизмы самовнедрения, обязательные Features и метки; --list показывает только идентификатор Component и имена его сокетов.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observabilityRecipe с --show-implements
Представление сущности Recipe по умолчанию показывает по одному разделу на каждый объявленный в ней режим ввода, её возможность и сопоставление значений. --show-implements разрешает ссылку spec.implements по каталогу и отображает связанную сущность Component вместе с вложениями, которые этот Component требует:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metricsRecipe с несколькими режимами ввода
Режимы ввода сущности Recipe складываются: source: для рендеринга, workload: для синтеза и карта artifacts: — каждый вносит свой вывод, и Recipe может объявить любую их комбинацию. inspect сообщает о каждом объявленном в Recipe режиме, а не выбирает один, поэтому вы видите именно тот набор, который написали:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlРазделы упорядочены как source: → workload: → artifacts: — в том же порядке, который применяет сборка, когда сводит Recipe к одному имени режима и когда сообщает, какой объявленный режим связанный provider не может поддержать, — поэтому это представление и диагностика сборки называют режимы в одном порядке. Recipe, не объявляющий ни source:, ни workload:, отображается как artifacts-only: это единственный случай, когда представление называет один режим.
Manifest (разрешается по умолчанию)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)Представление по умолчанию применяет цепочку extends: сущности Manifest и выводит разрешённые сопоставления компонентов и функций, а также привязки аннотаций. --raw показывает файл в написанном виде, до разрешения extends.
Aggregate (разрешается по умолчанию)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontendПредставление по умолчанию строит топологию и показывает каждый компонент с его значениями и uses-рёбрами, а затем вычисленный граф зависимостей. Дерево подсистем отображается с вложенностью; --flat выводит по одному разделу на узел, каждый с ключом в виде полного пути через точку.
За соединением, записанным в длинной форме, следуют переносимые им вложения, каждое под именем, которое оно получает в потребляющем компоненте, — псевдоним соединения и слот через точку, — с указанным типом Feature и пояснением, какой слот оно заполняет и обрабатывает ли оно материал, объявленный чувствительным:
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]Слот и отметка — это факты, которые сборка сущности Release, развёртывающей этот Aggregate, записывает для вложения; они читаются так же, как в представлении Release (см. Соединение, слот и пояснение о чувствительности вложения). Они берутся из объявления слота в сокете и из объявления самой Feature, поэтому не зависят от того, какая Release развёртывает Aggregate. Aggregate не указывает Manifest, поэтому реализация, которую Manifest сущности Release выбирает для вложения, здесь не показывается. Это представление перечисляет соединения компонента и то, что они переносят; вложения собственного блока компонента отображаются в представлении Release.
Release (разрешается по умолчанию)
Представление Release — самая ответственная проверка. Оно запускает весь конвейер и отображает для каждой границы каждый узел Component, его uses-рёбра и каждую Feature, прикреплённую к этому узлу (записанную на соединении — под ребром этого соединения), каждую со слотом вложения, который она заполняет, с указанием, обрабатывает ли она объявленный чувствительным материал, и с FeatureRecipe, которая её реализует, а также со скобкой происхождения, показывающей, откуда взялось вложение:
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)Каждая граница содержит свой выходной каталог и аннотации, потребляемые provider; каждый компонент под границей содержит свой тип компонента Aggregate, свои uses-рёбра (межграничные рёбра помечены), за каждым из которых следуют переносимые этим соединением вложения, и собственные вложения Feature; каждое вложение — с пояснением фактов и скобкой происхождения. --flat сворачивает дерево границ в один раздел на границу с ключом в виде её полного пути. --raw выводит файл Release дословно, без конвейера.
Вывод в YAML
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}Сущность Component, названная из каталога, выводится как сущность, в которую её разрешил каталог, поэтому после слияния extends: вы видите объединённую сущность, а не написанный файл; файл сущности Component выводится в том виде, в каком он написан.
Машиночитаемый вывод
Машиночитаемый вывод дают два флага, и они отвечают на разные вопросы. --output выбирает формат документа, который эта команда и так выводит; --ir-graph запрашивает другой документ — скомпилированный граф, в который разрешается сущность Release, — в дополнение к нему. Они независимы: если передать оба, вы получите граф и YAML в авторском виде, каждый по одному разу.
--output yaml выводит сущность в авторском виде, пригодном для передачи по конвейеру и сравнения. Этот вывод дословный, и он включает значения, которые автор объявил чувствительными: вывод, претендующий на воспроизведение входных данных, не может скрыть их часть и при этом оставаться воспроизведением. Передавайте, храните и распространяйте его так же, как файл сущности, из которого он получен.
Скомпилированный граф: --ir-graph
aggrega inspect <release> --ir-graph записывает граф, в который разрешился запуск, в стандартный вывод в формате JSON перед представлением, которое команда выводит в любом случае. Один документ JSON и один завершающий перевод строки, поэтому потребитель, декодирующий поток, читает граф и останавливается.
Флаг применяется к сущности Release — единственному виду, который разрешается в граф. Если запросить его для любого другого вида или для сущности каталога по имени, команда отказывает и сообщает об этом, а не выводит собственное представление этой сущности, молча отбросив запрос.
Композиция, которую отклоняют проверки компилятора, не даёт графа. Отказ, описанный в разделе Поведение при ошибках, происходит до того, как что-либо записано в этот поток, поэтому конвейер, читающий его, никогда не получит граф, от которого отказалась бы сборка тех же документов: он получит те же замечания, которые сообщила бы сборка, и ненулевой код выхода.
Тот же флаг с тем же значением есть у aggrega build и aggrega validate: каждая возвращает граф, вычисленный этим запуском, в дополнение ко всему, что ещё выдаёт команда. Интеграция с редактором читает тот же граф по протоколу демона.
--output yaml не выводит граф. Он воспроизводит сущность Release в авторском виде — точно так же, как для любого другого вида. Конвейер, которому нужен граф, читает его через --ir-graph и получает JSON, а не YAML.
Граф скрывает значения. Это не файл, который кто-то написал, — это то, что компиляция вычислила из сущностей Aggregate, Release и каталога, — поэтому нет обязательства сохранять авторский вид, и им управляют те же объявления, что и читаемыми представлениями. Везде, где граф содержит лист, который автор объявил чувствительным, значение заменяется объектом с одним ключом, помечающим его как скрытое:
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}Ключ сохраняется, поэтому граф по-прежнему показывает, какие листья несут узел и его присоединения; исчезает только значение. Необъявленный соседний элемент в той же полезной нагрузке выводится в авторском виде: secretName выше — публичный указатель, который автор оставил необъявленным, и он печатается. Причина, сопровождающая маркер, объясняет отсутствие значения: declared — для листа, на который распространяется объявление, и unreadable — когда полезная нагрузка пришла в форме, которую эта команда не смогла прочитать; в этом случае скрывается вся полезная нагрузка, а не угадывается какая-либо её часть.
Собственная конфигурация соединения скрывается так же. values конкретного соединения, которые Aggregate записывает в элементе uses, и infra конкретного соединения, которые записывает в нём Release, регулируются сокетом потребляющего компонента — объявленными им valueSchema и infraSchema, контрактами, по которым проверяется эта конфигурация, — и никогда объявлениями цели. Лист, который любой из контрактов объявляет как sensitive: true, заменяется маркером в values и infra ребра, а также в элементе uses потребляющего узла, который содержит значения в том виде, в каком их написал автор; каждое ребро перечисляет скрываемые им листья в sensitive_payload_leaves — поле, которое узел использует для своих собственных. Лист с тем же именем на соединении, сокет которого объявляет его читаемым, выводится так, как написан.
Передавайте --unredacted, когда конвейеру действительно нужны значения, и обращайтесь с результатом так же, как с самими файлами сущностей. aggrega build и aggrega validate принимают тот же флаг рядом с --ir-graph на тех же условиях: возвращаемый ими граф скрывает значения, если флаг не передан.
Протокол демона выдаёт тот же граф по тому же правилу. aggrega/irGraph отвечает со скрытыми значениями и возвращает их в открытом виде только на запрос, в котором задано поле unredacted — так в протоколе записывается этот флаг. Поэтому то, что рисует панель редактора, следует тем же объявлениям, а клиент, показывающий значения, делает это потому, что запросил их.
Замыкание зависимостей: --closure
aggrega inspect <release> --closure выводит замыкание зависимостей сущности Release: каждую сущность каталога, которой она достигает, в той версии, в которую разрешилась каждая из них, вместе с идентификаторами сущностей Aggregate и Manifest, в которые разрешились два её указателя, и общими документами, на которые опираются эти сущности. Ничего не отрисовывается и никакой артефакт не создаётся — замыкание разрешается, а не собирается, поэтому для ответа не загружается ни один провайдер.
Замыкание и разрешённое представление — разные документы, и ни одно не восстанавливается из другого. Разрешённое представление — то, что эта команда по умолчанию отрисовывает для сущности Release, — говорит, как выглядит развёртывание: его границы, его узлы компонентов, что с чем связано и что прикреплено к каждому узлу. Замыкание говорит, что было подтянуто для его сборки и в каких версиях. Сущность может быть достигнута, ни разу не появившись в виде узла, — сущность Recipe, на которую Manifest отображает тип компонента, достигается каждой сборкой и не является узлом ни в одной из них, — а узел записывает тип компонента, которым он был объявлен, а не версию, в которую этот тип разрешился. Поэтому читатель, спрашивающий «почему сдвинулась эта версия?», «на что повлияет изменение этого общего документа?» или «от чего на самом деле зависит это развёртывание?», спрашивает о замыкании, и читатель, у которого есть разрешённое представление, не получит его, читая внимательнее.
Одно и то же слово запрашивает один и тот же документ на любой поверхности. --closure здесь, aggrega/releaseClosure через протокол демона (см. aggrega serve, «Замыкание — это не граф») и режим release инструмента describe через протокол инструментов ассистента — все отвечают на этот вопрос о сущности Release; имя Release через любой из них приводит к одному и тому же разрешению, поэтому все три не могут разойтись в том, от чего зависит Release. Если lock-файл больше не соответствует тому, во что разрешается Release, эта команда и инструмент describe отказывают с той же остановкой по расхождению, что и сборка; демон, обслуживающий редактор по ходу редактирования, отвечает.
Это один документ, поэтому он запрашивается отдельно. --closure выбирает замыкание вместо разрешённого представления и не может сочетаться с --raw, --resolved, --output или --ir-graph — каждый из них запрашивает другой документ о той же сущности Release, и команде, принявшей два запроса, пришлось бы молча ответить на один из них. Их сочетание отклоняется с указанием этой пары.
Он применим к сущности Release и ни к чему больше. Сущность каталога, файл Aggregate, Manifest — ни у одного из них нет замыкания, поэтому запрос отклоняется, а не обрабатывается отрисовкой собственного представления этого объекта с отбрасыванием запроса. Отброшенный запрос выглядит для вызывающей стороны точно так же, как объект с пустым замыканием.
Каждый исход отличим от остальных. На сущность Release, которая разрешается, отвечает перечень. Путь к Release, не указывающий ни на какой файл, отклоняется с сообщением, что файла нет. Release, который существует, но чьё замыкание не удаётся разрешить, отклоняется с указанием того, что не удалось разрешить и откуда пришла ссылка, а затем всех файлов, отклонённых при загрузке каталога, — потому что отклонённый файл обычно и является причиной, по которой пропала сущность, достигаемая сущностью Release. Запись доверия к плагинам рядом с Release, которая существует, но не может быть прочитана, отклоняется с указанием того, что не удалось прочитать, потому что перечень, пропустивший её, сообщил бы об отсутствии отозванных плагинов там, где ни один не удалось проверить. Release, lock-файл которого больше не соответствует тому, во что он разрешается, отклоняется с остановкой по расхождению, которую выводит сборка, как описано в разделе Поведение при ошибках, потому что перечисленные версии были бы такими, которые не использует ни одна сборка этого Release. Пустой перечень никогда не является ответом ни в одном из этих случаев: он представил бы опечатку в пути или сломанное рабочее пространство как Release, который ни от чего не зависит.
Три уровня подробности применяются так же, как для любого вида. --list выводит только ссылки, по одной на строку, для передачи по конвейеру. Уровень по умолчанию добавляет разрешённые идентификаторы, версию, в которую разрешилась каждая ссылка, использованные общие документы, все отображения Manifest, чья цель не реализует тип, на который она отображена, и все уведомления об устаревании или отзыве, записанные для того, от чего зависит Release, — в его lock-файле для закреплённой ссылки и в записи доверия к плагинам рядом с ним для плагина, подключённого в роли, которая возвращает вердикт «принять или отклонить», — теми же словами, которыми aggrega build выводит ту же отметку. --detail добавляет вид каждой ссылки там, где место ссылки его записало: одни позиции в документе говорят, на какой вид они указывают, а другие нет, поэтому вид сообщается там, где он известен, а не угадывается по форме имени.
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)Если рабочее пространство записало, в какие версии разрешается Release, эта запись служит отправной точкой разрешения, поэтому сообщаемые версии — это те, из которых собирается данное развёртывание, а не те, что каталог содержит сегодня. Рабочее пространство без такой записи разрешается по каталогу в его текущем состоянии.
Соединение, слот и признак чувствительности вложения
Каждое вложение Feature в представлении Release содержит пояснение с фактами, которые компилятор фиксирует о самом вложении: какой слот вложения оно заполняет, работает ли оно с материалом, объявленным чувствительным, и какая сущность FeatureRecipe его реализует, а для вложения, записанного на одном из соединений компонента, — на каком соединении оно записано. Пояснение стоит между именем вложения и его скобкой происхождения и выглядит одинаково в обеих формах происхождения, описанных ниже.
Вложение, записанное на соединении, выводится под строкой этого соединения в Uses:, а не в Features:, поэтому Features: содержит только собственные вложения компонента. Строка над ним называет соединение по его псевдониму и компоненту, к которому оно ведёт, а остальное сообщает собственное пояснение вложения:
[socket: <socket>]— сокет, через который подключено соединение; строка соединения его не называет. Эта часть идёт в пояснении первой, потому что меняет смысл остального: следующая за ней часть о слоте называет слот, объявленный сокетом соединения, а не слот, который компонент объявляет для собственных вложений.[connection: <alias> through socket <socket>]— тот же факт для вложения, соединению которого в блокеUses:не соответствует ни одна строка; такое вложение выводится вFeatures:и называет своё соединение здесь. В любом случае соединение называется один раз на вложение, а не дважды.[slot: <name>]— вложение заполняет слот с именем<name>. Слот заполняется присоединением Feature под собственным именем слота, поэтому<name>— это имя, под которым записано вложение, сопоставленное с объявленными слотами: сfeaturesSchemaсущности Component, на которой оно размещено, для её собственных вложений и сfeaturesSchema, объявленной сокетом соединения, для вложения, записанного на соединении.[free]— вложение не заполняет ни одного объявленного слота: разрешённая сущность Component не объявляет слотfeaturesSchemaс таким именем. Это наблюдение, а не диагностика. Вложение свободной формы принимается, и оператор, который хочет его запретить, выражает это политикой управления, а не полагается на то, что инструмент его отклонит.[sensitive]— вложение работает с материалом, который автор объявил чувствительным: потому что присоединённая Feature объявляет чувствительный лист, потому что заполняемый им слот объявляетsensitive: true, или по обеим причинам.[realization: <name>:<version>]— сущность FeatureRecipe, которую Manifest этого Release связывает с вложением: по собственному имени вложения, если Manifest сопоставляет это имя (для вложения, записанного на соединении, — псевдоним и слот, соединённые точкой), иначе по типу его Feature. Это реализация, с которой сборка тех же документов отрисовывает вложение, и то же значение, которое скомпилированный граф несёт на вложении какrealization(см.--ir-graph), поэтому это представление и граф не могут назвать разные реализации. Эта часть идёт в пояснении последней.
Если применимо несколько фактов, они объединяются в одном пояснении. core/storage/s3-object-store объявляет слот secret_access_key, помеченный sensitive: true, поэтому учётные данные, присоединённые под этим именем, сообщают оба факта, а Feature, присоединённая под именем, для которого Component не объявляет слота, не сообщает ни слота, ни чувствительности. С сущностью Manifest, которая сопоставляет каждому типу Feature сущность FeatureRecipe, каждая строка также называет свою реализацию:
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]Компонент, сокет models которого объявляет слот credential, помеченный sensitive: true, и который подключает соединение под псевдонимом gpt, заполняющим этот слот, выводит это вложение под соединением — рядом с собственными учётными данными, которые остаются в Features::
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]Вложение, записанное на соединении, никогда не сообщает [free]: сокет допускает только объявленные им слоты, а соединение с любым другим именем отклоняется при загрузке сборки.
Пояснение полностью опускается, если ни один из фактов не применим, а каждая часть опускается независимо:
- Отсутствие части о сокете или соединении означает, что вложение записано в собственном блоке компонента либо попало в него из более широкой области или в результате расширения по аннотациям.
- Отсутствие части о слоте означает, что набор объявленных слотов сущности Component, на которой размещено вложение, не удалось разрешить — например, её тип не совпадает ни с одной сущностью каталога. Это намеренно отличается от
[free]:[free]отвечает «слот с таким именем не объявлен», а отсутствующая часть означает, что на этот вопрос вообще не удалось ответить. - Отсутствие
sensitiveфиксирует, что ни одно объявление не пометило вложение. Это уже, чем заключение, что вложение не несёт ничего секретного: эта ось сообщает об объявлениях, и ничего не выводится из имени поля или его значения. - Отсутствие части о реализации означает, что Manifest не связывает вложение ни с одной сущностью FeatureRecipe, имеющейся в каталоге.
Слот, объявленное имя которого буквально free, тоже отображается как [free] и неотличим от вложения свободной формы — ничто не резервирует это слово в пространстве имён слотов.
Грамматика скобок происхождения в IR
Каждое подключение Feature в представлении Release несёт скобку происхождения. Скобка может иметь компактную форму (одна скобка на Feature, когда происхождение подключения одинаково для всех листьев) или полистовую форму (одна скобка на лист, когда листья подключения поступают из разнородных источников). Существует три вида тела скобки; они одинаково применяются в обеих формах.
Три вида тела скобки
-
[explicit]— подключение Feature объявлено автором. Сущность Aggregate или Release явно назвала Feature на затронутом узле. Явные подключения — источник с наивысшим приоритетом; они всегда побеждают вклады, порождённые аннотациями, в том же листе. -
[annotation: <key> from <source>]— подключение Feature порождено аннотацией. Компилятор синтезировал его, потому что аннотация на<source>совпала с привязкой Manifest, объявляющей этот Feature.<key>— ключ аннотации, сработавший для привязки (например,business.aggrega.ai/team);<source>— сущность, которая несла аннотацию (aggregate,release,componentилиmanifest). Синтезированное подключение структурно идентично явному — последующий рендеринг обрабатывает оба одинаково, — но скобка происхождения различает их, чтобы отладка оставалась разрешимой. -
[explicit; overrides annotation: <key> from <source>]— полистовая форма, которая срабатывает, когда явное объявление автора в одном листе подавляет вклад аннотации, который иначе задал бы тот же лист. Этот случай возникает при межсторонней композиции: аннотация Aggregate может поставлять столпvalues:для Feature, аннотация Release — его столпinfra:, а явное объявление в Release на том же Feature переопределяет один лист infra. Скобка листа записывает и явного автора, и подавленную аннотацию; подавленная аннотация не вносит вклада в отрендеренный результат, но её присутствие видно в представлении inspect, чтобы оператор мог увидеть, какая аннотация была переопределена и где.
Компактная форма и полистовая форма
Компилятор выбирает между компактным и полистовым рендерингом, обходя полистовое происхождение подключения и проверяя его однородность. Происхождение подключения однородно, когда каждый заполненный лист (в столпах values: и infra: сущности Feature) имеет одно и то же начало (явное или аннотация), один и тот же ключ аннотации, если оно порождено аннотацией, одну и ту же исходную сущность, и ни один лист не несёт маркер «overrides annotation». Когда происхождение однородно, компилятор выводит одну скобку на подключение:
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]Когда происхождение расходится — типичный случай — межсторонняя композиция, где аннотация Aggregate поставляет values:, а аннотация Release поставляет infra: для того же Feature, — компилятор выводит одну скобку на каждый заполненный лист:
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]Порядок обхода: сначала столп values (в авторском порядке), затем столп infra (по тому же принципу). Префикс столпа (values. / infra.) и путь через точку внутри столпа точно указывают, какой лист аннотирует каждая скобка.
Значения, объявленные чувствительными
Лист, схема которого объявляет sensitive: true, выводит вместо своего значения фиксированный текст <redacted>. Ключ, префикс столпа и скобка происхождения сохраняются — заменяется только значение, — поэтому структура вывода по-прежнему показывает, какие листья несёт сущность и откуда взялся каждый из них. Затрагиваются две читаемые поверхности: поузловой блок Values: сущности Aggregate и полистовой блок привязок разрешённой сущности Release — включая привязку, записанную на соединении и выводимую под строкой этого соединения, которая скрывает ровно те листья, которые скрывает та же сущность Feature, когда компонент держит её сам. Скомпилированный граф сущности Release под --ir-graph скрывает те же листья в структурированной форме, описанной в разделе Машиночитаемый вывод.
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>Скрывается только объявленный лист, а условие [sensitive] на уровне привязки не является указанием скрыть значение: оно говорит, что привязка работает с секретными данными, но не говорит, какие из её листьев их несут. Опубликованные локаторы сущности Feature для учётных данных — имя ресурса и ключ данных — публичны и намеренно оставлены необъявленными в каталоге стандартной библиотеки, поэтому они выводятся открытым текстом рядом с данными, которые скрываются:
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]Ничего не выводится из имени поля: поле с именем password без объявления выводит своё значение, а объявленное поле с именем key — нет. Сокрытие касается того, что выводит инструмент; оно никогда не затрагивает отрисованный артефакт, и dist/ выдаётся ровно в том виде, в каком его создала отрисовка. Ключевое слово и полный предел того, чего позволяет добиться его объявление, описаны в vocabulary/compact-form-authoring.md, раздел «Declaring a leaf sensitive».
Отображение скрытых значений
--unredacted выводит значения, объявленные чувствительными, вместо того чтобы скрывать их, сразу на всех поверхностях inspect — как в читаемых представлениях выше, так и в скомпилированном графе сущности Release. Флаг существует потому, что иногда расследуется именно скрытое значение: учётные данные, пришедшие не из той привязки, выглядят так же, как правильные, когда оба значения скрыты.
Его действие ограничено командой, которой он передан. aggrega build и aggrega validate тоже принимают его, где он затрагивает только граф, возвращаемый --ir-graph, и ничего больше, и отклоняют его, если граф не запрошен. aggrega build --trace-unredacted — та же идея для файлов трассировки сборки, и ни один из двух флагов сборки не затрагивает вывод другого; отрисованный артефакт в dist/ не затрагивается ни одним из них, потому что он выдаётся ровно в том виде, в каком его создала отрисовка, что бы ни было передано.
Всё, куда затем попадает вывод, содержит эти значения открытым текстом — терминал, конвейер, файл, запись экрана, вставленный отчёт об ошибке. В отличие от файлов трассировки, каждый из которых начинается с заголовка, сообщающего, что они записаны без сокрытия, вывод в терминале никакой такой пометки не несёт: о том, что флаг передан, говорит только командная строка.
Когда стоит использовать inspect
- Отладка вопроса «почему здесь эта Feature?» — подключения, порождённые аннотациями, не видны в YAML-файлах сущностей Aggregate и Release (аннотации там есть, но подключения Feature, которые они синтезируют, существуют только в IR). Inspect показывает их вместе с происхождением.
- Проверка наследования схем —
aggrega inspect <ComponentName>показывает объединённую схему после разрешения цепочкиextends:; сам исходный файл показывает только локальную разницу. - Диагностика неожиданностей при композиции с разных сторон — когда аннотация сущности Aggregate и аннотация сущности Release обе передают данные столпов в одну и ту же Feature, мысленно восстановить разрешённые листья бывает непросто. Форма скобок для каждого листа делает разрешение явным.
- Проверка перед развёртыванием —
aggrega inspect ./prod-release.yamlперечисляет каждую Feature на каждом Component до того, какaggrega buildсоздаст артефакты; оператор может убедиться, что топология соответствует замыслу, прежде чем фиксировать отрендеренные манифесты в GitOps.
О базовых механизмах — как аннотации каскадируются, как разделение «сторона — столп» направляет значения аннотаций в столпы Feature и как принцип приоритета явного подключения взаимодействует с вкладами из аннотаций — см. providers/well-known-annotations.md и раздел «Annotation-Driven Feature Bindings» в entities/manifest.md.
Синтаксис
aggrega inspect [identifier] [flags]Описание
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.Флаги
| Флаг | По умолчанию | Описание |
|---|---|---|
--catalog | [] | Каталог; можно указывать несколько раз. Каждый —catalog <dir> добавляется в начало стека поиска каталогов (побеждает первое совпадение): catalog_dirs рабочего пространства либо, для сущности Release, которой конфигурация рабочего пространства задаёт собственные каталоги в workspace.releases, каталоги этой сущности Release; стек завершается каталогом с именем catalog в корне рабочего пространства, если он есть. Список catalog_dirs, записанный пустым, означает, что локальный каталог не читается вовсе. |
--closure | false | Вывести замыкание зависимостей сущности Release — каждую сущность каталога, которой она достигает, в той версии, до которой та разрешилась, — вместо представления разрешённых узлов. Применяется к Release — единственному виду, который разрешает замыкание; любой другой вид отклоняет запрос, а не молча его игнорирует. |
--color | auto | Цветной вывод: auto|always|never. |
--detail | false | Выводить полные тела полей. |
--flat | false | Выводить древовидную сущность (Aggregate, Release) плоским списком, где перед каждым узлом стоит его полный путь через точки. Не влияет на табличные виды. |
--ir-graph | false | Дополнительно записать граф IR, вычисленный при этом запуске, в stdout в формате JSON, помимо всего, что уже выводит эта команда. Значения, которые автор объявил чувствительными, в нём скрываются; передайте —unredacted, чтобы вывести их. Применяется к Release — единственному виду, который разрешается в граф; любой другой вид отклоняет запрос, а не молча его игнорирует |
--list | false | Выводить только идентификаторы. |
--no-color | false | Отключить цветной вывод (псевдоним для —color=never). |
--output, -o | text | Формат вывода: text|yaml. |
--plugin | — | Путь в файловой системе к необработанному артефакту <file.wasm>; определяет и выводит импортируемые им функции хоста до того, как aggrega plugin sync запишет их в сущность Plugin. Аргумент-идентификатор не принимается. |
--raw | false | Выводить сущность в исходном виде, без разрешения. |
--release | — | Искать имя в каталоге в терминах этого файла Release: по каталогам, которые конфигурация рабочего пространства задаёт этой сущности Release, с добавленными в начало —catalog. Применяется к имени; файл или ссылка на реестр проверяются как есть и отклоняют этот флаг. Относительный путь разрешается относительно каталога, в котором запускается команда, а не корня рабочего пространства. Если этот каталог не входит ни в одно рабочее пространство и корень не указан, абсолютный путь находит рабочее пространство по собственной папке сущности Release |
--resolved | false | Выводить сущность полностью разрешённой. |
--show-implements | false | Для Recipe или FeatureRecipe разрешить spec.implements по каталогу и вывести связанный Component или Feature. |
--unredacted | false | Выводить значения, которые автор объявил чувствительными, вместо того чтобы скрывать их. Всё, куда попадает вывод, — терминал, конвейер, файл, запись экрана — тогда содержит эти значения в открытом виде. |