aggrega serve
aggrega serve запускает Aggrega как долгоживущий демон «компилятор как сервис» для интеграции с IDE. Он работает по протоколу JSON-RPC 2.0 через stdin/stdout и сохраняет между запросами состояние резолвера каталогов, кэша разбора и диагностики, поэтому операции редактора получают отклик менее чем за секунду, а не платят полную стоимость загрузки каталога при каждом нажатии клавиши.
Обычно демон запускается как подпроцесс расширением редактора, а не вручную. Эталонным клиентом служит расширение VS Code; другие редакторы могут интегрироваться, используя тот же протокол.
Протокол
Протокол передачи — JSON-RPC 2.0 с кадрированием по Content-Length в пространстве имён методов aggrega/. Это намеренно не Language Server Protocol: у Aggrega есть доменные операции (запрос графа IR, сигнал инвалидации кэша), у которых нет аналога в LSP. Расширение редактора переводит запросы LSP редактора в эти методы aggrega/* и обратно; значения позиции, диапазона и местоположения в форме LSP используются повторно там, где они подходят.
Два метода сохраняют стандартные для протокола имена $/, а не переименовываются в пространство имён aggrega/, поскольку оба относятся к транспорту, не несут смысла, специфичного для Aggrega, и клиент, уже говорящий на этом протоколе, обрабатывает их без каких-либо добавлений: $/cancelRequest, который останавливает запрос, ответ на который клиенту больше не нужен, и $/progress, с помощью которого демон сообщает о ходе длительной операции. Оба описаны ниже.
🔴 Каждый запрос ниже содержит workspaceRoot — абсолютный путь к рабочему пространству, с которым он работает, и для каждого метода это не повторяется. Исключение составляют три запроса, предмет которых не рабочее пространство: aggrega/initialize, aggrega/getSchema и aggrega/scaffoldEntity, — хотя aggrega/scaffoldEntity, записывающий или перечисляющий готовые к запуску примеры, всё же указывает рабочее пространство. О том, что получает запрос, не указавший рабочее пространство, см. Каждый запрос указывает рабочее пространство, к которому он относится, а о том, куда отправляется push-диагностика, — Объявление рабочего пространства, для которого нужна push-диагностика.
Структуры по полям опубликованы в виде схемы, и читать их следует в справочнике по формату передачи. На той странице описаны объект параметров каждого метода, каждый результат и полезная нагрузка каждого уведомления — каждое поле с типом, признаком обязательности и содержимым — а также три свойства, действующие для всего интерфейса, а не для отдельного метода: два поля, которые допускает любой запрос сверх объявленных его методом, — это workspaceRoot выше и workDoneToken из раздела Наблюдение за длительной операцией; то, что объект params с ключом, который его метод не принимает, отклоняется, а в отказе перечисляется допустимый набор; и то, где отсутствующая коллекция передаётся как null, а не как пустая. Страница генерируется из этой схемы, поэтому меняется вместе с контрактом.
Эта страница описывает протокол, та — структуры, и читать их следует вместе. Здесь: кадрирование, назначение каждого метода, его охват, что он записывает, какие отказы выдаёт и почему, коды ошибок и что делать с каждой. Там: что передавать, ключ за ключом. Поэтому в списке ниже названы методы и сказано, что означает их вызов, а список полей для составляемого запроса находится в соседнем справочнике.
Запросы:
aggrega/initialize— рукопожатие. Согласует кодировку позиций (сервер предпочитает UTF-8, затем UTF-16, затем UTF-32, а по умолчанию использует UTF-16), получает рабочее пространство, которое вы объявляете для push-диагностики, и сообщает корень этого рабочего пространства, слой конфигурации, из которого разрешены его настройки, и маркер, по которому он разрешён. Ответ также содержитversion— версию отвечающего двоичного файла: то же значение, которое сообщает для негоaggrega version. Оно описывает запущенный процесс, поэтому после замены файла, из которого был запущен демон, — например, пересборки по тому же пути —versionпо-прежнему называет работающий демон, тогда как запрос к файлу называет его замену; смотрите значение здесь, когда вопрос в том, с какой версией вы общаетесь.workspaceRootнеобязателен и объявляет рабочее пространство, а не работает с ним — см. Объявление рабочего пространства, для которого нужна push-диагностика. Отправьтеcapabilities.window.workDoneProgress: true, чтобы сообщить, что клиент умеет обрабатывать уведомления о ходе выполнения;capabilities.workDoneProgressв ответе повторяет это, а для клиента, ничего не объявившего, поле отсутствует. См. Наблюдение за длительной операцией.aggrega/validate— проверить содержимое файла; возвращает диагностику.release— путь относительно корня рабочего пространства, указывающий сущность Release, относительно которой выполняется проверка, — то же значение, что принимаетaggrega/irGraph, и то же, что принимаетaggrega build --releaseпри запуске из корня. Он необязателен и определяет охват ответа: если указать сущность Release, проверки, которым она нужна, выполняются относительно неё — сущность каталога проверяется как отдельная сущность в терминах этой сущности Release, а любой другой документ — относительно её замыкания зависимостей; если его опустить, ответ охватывает то, чему документ должен соответствовать сам по себе, и содержитchecked, сообщающее об этом. Значение, которое присутствует, но имеет неверный формат, отклоняется в любом случае: абсолютный путь или путь, разрешающийся за пределами корня рабочего пространства, отвергается, а не разрешается. См. Проверка в реальном времени.aggrega/diagnostics— вернуть результаты, хранящиеся для файла. Если в момент поступления запроса выполняется проверка того же файла, ответ дожидается её и сообщает найденное, поэтому ответ никогда не объявляет чистым файл, в котором демон как раз ищет проблемы. См. Запрос диагностики во время выполнения проверки.aggrega/hover— содержимое всплывающей подсказки для сущности в позиции.releaseнеобязателен и даёт ответ в терминах этой сущности Release — см. Ответ в терминах одной сущности Release.aggrega/completion— варианты автодополнения в позиции. Там, где курсор указывает сущность по виду —typeкомпонента,typeприсоединения сущности Feature, значениеextends:,implements:сущности Recipe или FeatureRecipe, — вариантами являются имена этого вида, объявленные в собственных документах рабочего пространства, а для сущности Component или Feature — также имена, объявленные в настроенныхcatalog_dirs; каждое предлагается один раз, в порядке имён. Поэтому рабочему пространству, которое берёт Components и Features из каталога, они предлагаются, а не только то, что создано в нём самом. Recipes и FeatureRecipes, предлагаемые в значении сопоставления сущности Manifest, берутся из собственных документов рабочего пространства. Сущность, которая есть только в кэше артефактов или в реестре, не предлагается: ответ на автодополнение никогда ничего не загружает.releaseнеобязателен и даёт ответ в терминах этой сущности Release — см. Ответ в терминах одной сущности Release.aggrega/resolve— разрешить сущность, на которую ссылается позиция (переход к определению).releaseнеобязателен и даёт ответ в терминах этой сущности Release — см. Ответ в терминах одной сущности Release.aggrega/findReferences/aggrega/findImplementations. Каждый принимает необязательныйreleaseи даёт ответ в терминах этой сущности Release — см. Ответ в терминах одной сущности Release.aggrega/irGraph— скомпилированный граф IR для сущности Release, для интроспекции в редакторе.release— путь относительно корня рабочего пространства, указывающий на Release внутри него, — то же значение, которое принимаетaggrega build --releaseпри запуске из корня. Любая другая форма отклоняется стандартной ошибкой invalid-params с указанием того, что следует отправить вместо неё: абсолютный путь, путь, разрешающийся за пределы корня рабочего пространства, — выходит ли он наружу в записанном виде или через ссылку, на файл или на каталог по пути, — и пустое значение отклоняются, а не разрешаются, поэтому запрос никогда не сообщает о файле, которого нет в рабочем пространстве. Release, который называет конфигурация рабочего пространства — какbuild.authoring_releaseили как ключworkspace.releases, — принадлежит рабочему пространству, где бы ни лежал его файл, поэтому ссылка внутри рабочего пространства, ведущая к нему, принимается, так же как его перечисляетaggrega/releaseCandidates. Каталог каталога сущностей, который читает Release и который невозможно обойти, — например, существующий, но недоступный для чтения, — отклоняется так же, как его отклоняетaggrega inspect, прежде чем читается что-либо ещё: ошибка —1004entity-not-resolvable, её сообщение — отчёт, который командная строка печатает для этого каталога, в одну строку ([CATALOG_ERROR] <directory>: catalog load: …), и граф по оставшимся каталогам не строится. Каталог, указанный в конфигурации рабочего пространства, который не является каталогом, — например, на его месте ничего нет, — отклоняется тем же образом и в тот же момент,1004entity-not-resolvable, а его сообщение — это отказ, который даёт ему любая команда, с указанием записи, файла конфигурации и строки, где она указана, и параметра (Откуда читаются локальные сущности). Каталог каталога сущностей со ссылкой, ведущей за пределы каталога, внутри которого должны оставаться его чтения, — документ или каталог, связанный ссылкой извне, внутри каталога сущностей в рабочем пространстве или внутри названного конфигурацией каталога вне его, — отклоняется тем же образом и в тот же момент, с1004и собственной фразой условия, называющей ссылку и место, куда она ведёт: через такую ссылку ничего не читается, а граф, построенный без неё, мог бы разрешить на её месте другую сущность с тем же именем. Так же отклоняется ссылка, ведущая наружу из документов рядом с Release, когда Release называет свой Aggregate или свой Manifest по идентичности. Файл, который Release, его Manifest или Release, который он расширяет, называет по пути —aggregate:,manifest:,extends:или$import:в parameters, — и который ведёт за пределы рабочего пространства, в записанном виде или через ссылку, отклоняется с собственной фразой условия (fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Ссылка на другой файл ведёт за пределы каталога, внутри которого она должна оставаться)»), причём data ошибки указывает на ключ в Release, который привёл к файлу, и из этого файла ничего не читается; Release, названный конфигурацией вне рабочего пространства, точно так же ограничен содержащим его каталогом, поэтому путь, выходящий из этого каталога, в нём или в Release, к которому ведёт его цепочка, тоже отклоняется. Обратите внимание:aggrega/releaseCandidatesотвечает абсолютными путями, поэтому клиент, передающий данные из одного интерфейса в другой, выполняет преобразование между ними. То, что этот параметр отклоняет написание, которое принимают параметры документаfileиuri, сделано намеренно, и раздел Какие написания принимает отправляемый параметр объясняет, что это определяет. Граф скрывает каждое значение, которое автор объявил чувствительным, точно так же, как его скрывает--ir-graphв командной строке: каждое заменяется маркером, описанным вaggrega-inspect«Machine-readable output», а всё остальное передаётся так, как записал компилятор.unredacted: trueзапрашивает эти значения в открытом виде — это написание в протоколе для--unredactedкомандной строки и единственный способ их запросить; при отсутствии или значенииfalseответ их скрывает. Всё, куда затем попадает ответ, получает значения в открытом виде, поэтому клиент запрашивает их только там, где это сделал использующий его человек.aggrega/build— компилирует Release и записывает его артефакты в выходной каталог рабочего пространства — тот же каталог, в который пишетaggrega buildпри запуске из корня рабочего пространства. Наreleaseраспространяется тот же контракт, что описан выше. Рендеринг выполняется со всеми включёнными проверками, поэтому расхождение, на котором остановилась бы сборка из командной строки, останавливает и эту. Каталог каталога, который читает Release и который невозможно обойти — например, существующий, но недоступный для чтения, — отклоняется так же, как его отклоняетaggrega build, до какой-либо записи: ни артефактов, ни lockfile, если заданautoPull. Так же отклоняется каталог, указанный в конфигурации рабочего пространства, который не является каталогом, — теми словами, которыми его отклоняетaggrega build(Where local entities are read from). Отказ совпадает с тем, которыйaggrega/irGraphвыдаёт для того же каталога:1004entity-not-resolvable с отчётом командной строки в одну строку; ссылка, ведущая за пределы области чтения каталога каталога или за пределы документов рядом с Release, отклоняется так же, как её отклоняетaggrega/irGraph, и ничего не записывается. Ответ называетoutputDirectory, в который выполнялась запись, и записанныеfiles— каждый относительно этого каталога, в отсортированном виде, — вместе с любымиnotices, возникшими при запуске; находки с позицией в документе передаются вместо этого черезaggrega/publishDiagnostics. На Release, отказывающий во время рендеринга, отвечают этим отказом словами компилятора, со всеми причинами, и отказ публикуется там, куда он указывает, — см. A refusal raised while rendering. Если был заданautoPull, ответ также содержитdependencyResolution— тот же отчёт, которым отвечаетaggrega/resolveDependencies, поэтому клиент, заполнивший зависимости в ходе сборки, читает закреплённое без повторного запроса, — а также то, откуда разрешение этой сборки взяло каждую ссылку: это факт о данном запуске, который lockfile не записывает. Каждое уведомление несётclassповерхности, которая его создала, —deprecation,catalog,catalog-lint,extends,release-compositionилиdependency-resolutionдля строки, созданной описанным ниже разрешением зависимостей, — и пустойclass, если у демона нет имени для этой поверхности; такое уведомление клиент отображает как голыйtext, не пытаясь угадать ближайшее соответствие. Файлы, которые запись находит в выходном каталоге или в каталоге под ним, в который она записала файл или через который прошла, и которые эта сборка не записывала, остаются на месте и называются в одном уведомлении после собственных уведомлений запуска, с пустымclass, той фразой, которойaggrega buildпечатает своё предупреждение, — см. Файлы, которые сборка не записывала;filesих никогда не называет.outputParentуказывает, где внутри рабочего пространства размещаются артефакты, и его имя полностью передаёт его смысл: это каталог, внутри которого создаётся выходной каталог, поэтому значениеdocsзаписывает артефакты вdocs/dist, а не в самdocs, — ровно то, что даёт сборка, запущенная вdocsиз терминала. Если его опустить, сборка пишет туда же, куда и запущенная из корня рабочего пространства. Он читается иначе, чемoutputDir, который принимают другие запросы на запись, и это сделано намеренно: те называют каталог, в который пишут, а этот — родителя этого каталога, и у них разные имена, потому что это разные вещи. Это всё равно место назначения внутри рабочего пространства, поэтому абсолютное значение, значение, выходящее за пределы корня, и значение, ведущее за его пределы через ссылку, — связанный каталог вне корня или ещё не созданный каталог под таким, — отклоняются, а не разрешаются. Создаваемый внутри него выходной каталог и каждый файл, который туда записывает сборка, также ограничены рабочим пространством: если один из них ведёт за его пределы через ссылку, сборка отклоняется с1004и собственной формулировкой условия, называющей ссылку и то, куда она ведёт, и ничего не очищается и не записывается.autoPullразрешает зависимости Release перед рендерингом — то же разрешение, которое выполняетaggrega/resolveDependencies, — и выключен, если запрос не требует его явно, что совпадает с умолчанием командной строки; без него Release, у которого нет lockfile, отклоняется с ошибкой об отсутствии lockfile, называющей, что нужно запустить. С заданнымautoPullэтот запрос обращается к реестрам и записывает lockfile — см. Reaching a registry, and writing. Запрос, который сначала выполняет разрешение, всё равно рендерит Release один раз: выяснение того, какие удалённые ссылки потребляет Release, само по себе является рендерингом, поэтому разрешение уже отрендерило то, что собирается, и сборка обслуживается из этого рендеринга, а не повторяет его.policyInputназывает каталог внутри рабочего пространства, относительно его корня, в который сборка также записывает полезную нагрузку, передаваемую каждой ролью управления подключённому там плагину, — файлы, которые записываетaggrega build --policy-input, под теми же именами, — независимо от того, завершилась сборка или остановилась; затемnoticesответа сообщают, сколько файлов записано, и называют каждую роль, для которой не записано ни одного файла, с пустымclass. При неудачном запросе записанные файлы остаются на диске, а этого отчёта в ответе нет: конверт ошибки содержит только отказ. Это место назначения, поэтому абсолютное значение или значение, выходящее за пределы рабочего пространства, отклоняется до того, как что-либо запускается.aggrega/buildPreview— сообщает, что записала бы сборка Release, ничего не записывая. Наreleaseраспространяется тот же контракт, что описан выше. Выполняется то же вычисление, что и вaggrega/build, с теми же проверками, поэтому Release либо был бы отклонён обоими, либо обоими описан, — именно поэтому выбор между ними касается вывода, а не строгости. Каталог каталога, который читает Release и который невозможно обойти или который содержит ссылку, ведущую за пределы каталога, внутри которого должно оставаться его чтение, отклоняется так же, до какого-либо рендеринга, как и каталог, указанный в конфигурации рабочего пространства, который не является каталогом, — как вaggrega/build. Ответ содержитfiles— отсортированные имена относительно выходного каталога, которые создала бы сборка, — вместе с любымиnotices;outputDirectoryнет, потому что ничего никуда не записывалось. На Release, отказывающий во время рендеринга, отвечают и публикуют отказ ровно так же, как это делаетaggrega/build. Запрос отклоняетautoPullс ошибкой invalid-params, называющей, что следует отправить вместо этого: заполнение зависимостей записывает lockfile, а этот запрос lockfile не записывает. Он не обращается ни к одному реестру.policyInput— единственная запись, которую он выполняет, и только если параметр передан: он записывает полезные нагрузки управления в этот каталог ровно так же, какaggrega/build, — файлы, которые записываетaggrega build --dry-run --policy-input, — не трогая выходной каталог и lockfile, с тем же отчётом вnoticesи с тем же ограничением: при неудачном запросе записанные файлы остаются на диске, а отчёта в ответе нет.aggrega/resolveDependencies— разрешает зависимости каталога и исходного кода для Release в кэш, закрепляет внешние входные данные, которые потребляет его рендеринг, в хранилище с адресацией по содержимому и записывает его lockfile.release— путь относительно корня рабочего пространства, то же значение, что принимаетaggrega/irGraph, и отклоняется в тех же формах.upgradeотбрасывает записанные закрепления и разрешает заново, поднимая каждую зависимость до наивысшей доступной версии;targetsсужает это до указанных в нём ссылок на сущности, сохраняя все прочие закрепления.verifyсверяет записанное разрешение с тем, которое этот запрос выполнил бы без него, соблюдая записанные закрепления так же, и не записывает ни lockfile, ни запись о доверии к плагинам, ниentity.lock— кэш читается и заполняется так же, как и без него, — отвечаяverified: trueиtoolchain, который записан в lockfile.verifyотклоняется как недопустимые параметры рядом сupgrade, рядом сtargetsи рядом сpinSourcesпри любом его значении — до того как что-либо разрешено или сообщено о ходе выполнения: обновление отбрасывает закрепления, ради соблюдения которых существует проверка, указанные цели разрешаются заново только при обновлении, аpinSourcesопределяет, записывает ли разрешение закрепления, недостающие вentity.lock, или отклоняется из-за них, — ни того, ни другого не делает сравнение, которое не записываетentity.lock. Командная строка и инструмент ассистента отклоняют те же пары. Ответ называетlockfile, который был записан или с которым выполнялось сравнение, и каждую закреплённую ссылку вentities,librariesиplugins; каждая запись содержитversion, до которой она разрешена, и свойsource— откуда этот запуск взял ссылку, тем словом, котороеaggrega pull --detailвыводит для того же разрешения:fetched-fresh,cache-reuse,local,in-binaryилиexternal, — а такжеsourceArtifacts,trustedPlugins,externalInputs— сколько внешних входных данных закрепляет lockfile по завершении запуска, считая и перенесённые, и обнаруженные этим запуском, — и всеnotices, выданные разрешением. 🔴 Успешный ответ сам по себе не означает, что закрепление внешних входных данных завершено. Если запуск закрепил все зависимости, но не смог до конца выяснить, какие внешние входные данные потребляет Release, он возвращаетincompleteExternalInputsс указанием того, что остановило обнаружение, и всё равно отвечает успехом: закрепления зависимостей полны и записаны на диск, так что сообщение о неудаче всего запроса побудило бы вас переделывать уже корректную работу. Прочитайте это поле, прежде чем считать lockfile полностью закреплённым: оно отсутствует, когда ничего не осталось необнаруженным, поэтому сигналом служит само его наличие. Параметра каталога нет: стек поиска — тот, что настроен в рабочем пространстве. Это единственный в сеансе запрос закрепления для Release, и именно здесь закрепляются также внешние входные данные: какие URL потребляет рендеринг, следует из того, что он рендерит, поэтому этот запрос рендерит Release, чтобы это выяснить, а запрос сборки затем обслуживается из записанного им. Если Recipe или FeatureRecipe, которую собирает Release, имеетentity.lockбез закрепления для входных данных, читаемых сущностью, запрос отклоняется с указаниемaggrega pinи каждого незаписанного входа;pinSources: trueвместо этого выполняет этот шаг закрепления для таких сущностей, записываяentity.lockрядом с каждой, — тот же шаг, что выполняетaggrega/pin, записывающий те же байты. При отсутствииpinSourcesследует настройке рабочего пространстваpin_sources_at_pull; если он передан, он переопределяет эту настройку в обе стороны, так чтоfalseотклоняет даже в рабочем пространстве, настроенном на закрепление. Этот запрос обращается к реестрам и выполняет запись — см. Обращение к реестру и запись.aggrega/pin— записывает вentity.lockрядом с Recipe или FeatureRecipe закрепление содержимого для всех входных данных, которые сущность читает вне собственного документа: удалённого источника, координаты которого записаны полностью, файла, импортируемого записью artifacts, и каждого файла, который локальный источник вносит в то, что содержит публикация сущности. Это тот же шаг, чтоaggrega pinвыполняет в терминале, и он записывает те же байты.entityобязателен и представляет собой путь относительно корня рабочего пространства, указывающий на документ сущности; он отклоняется в тех же трёх формах, что иrelease. Release не указывается: удалённый источник, координаты которого не содержат шаблона, указывает на один артефакт для каждого Release, использующего сущность, поэтому для его закрепления ничего из предоставляемого Release не требуется, тогда как удалённый источник, координаты которого берутся из шаблона, закрепляется для каждого Release запросомaggrega/resolveDependencies; локальный источник, записанный как шаблон, вносит каждый файл в каталоге сущности, и каждый из них закрепляется здесь.dryRunразрешает входные данные и возвращает lock, который записал бы шаг, в видеcontent, ничего не записывая рядом с сущностью; кэш содержимого всё равно заполняется. Ответ содержитentity,kind,nameиpinnable— false для вида, который не читает ничего, что записывает lock; в этом случае рядом с сущностью ничего не затрагивается, а все остальные поля отсутствуют, — а в противном случае записанныйlock,changed(false, если lock уже содержал все закрепления и остался побайтово идентичным),removed, если сущность больше не читает ничего, что записывает lock, и её lock был удалён, иpins— по одной записи на класс закреплений с количеством, которое содержит lock. Сам файл сущности никогда не записывается. Этот запрос выполняет запись рядом с сущностью внутри рабочего пространства и обращается к хостам, указанным в источниках сущности — см. Обращение к реестру и запись.aggrega/cacheStatus— что содержат кэши на диске: по одной записи на каждый кэшированный элемент с его размером и, если он есть, дайджестом содержимого, сгруппированные по классам. Принимает рабочее пространство и ничего больше. Каждый класс содержитreach—workspaceдля кэша артефактов в собственном каталоге кэша этого рабочего пространства,machineдля хранилищ скомпилированных модулей, описаний плагинов и пакетов документации, общих для всех проектов на машине, — аscopeпрямо называет классы уровня машины. Ничего не записывает. Почему охват указан в ответе, который ничего не меняет, см. в разделе Обращение к реестру и запись.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— освобождают кэшированное содержимое. Очистка (prune) удаляет то, на что не ссылается ни один lockfile рабочего пространства; вытеснение (eviction) сокращает хранилище скомпилированных модулей доmaxSize— объёма в байтах, записанного так же, как в командной строке (5GiB,512MiBили число байтов); полная очистка (clear) стирает все кэши, к которым обращается этот сеанс. Каждый ответ называет удалённое, причём каждое удаление содержитreachкласса, из которого оно взято, и каждый ответ содержитscope. Каждый ответ также называет то, что осталось на месте, потому что было открыто другим процессом: Windows отказывается удалять открытый файл, и операция продолжается с остальным, а не завершается ошибкой; prune или eviction перечисляют такие записи вheldOpen, а clear для каждого опустошённого кэша подсчитывает оставленные файлы вheldOpenFilesи их размер вheldOpenBytes. На других системах список пуст, а счётчики равны нулю, и оставшееся можно освободить при последующем запуске. Эти запросы выходят за пределы рабочего пространства — см. Обращение к реестру и запись.aggrega/registryList— реестры, к которым настроено обращаться это рабочее пространство: для каждой записи хост, необязательный псевдоним, является ли реестр реестром по умолчанию, его политика доверия в виде отдельных полей и наличие учётных данных для этого хоста. Принимает рабочее пространство и ничего больше. Ни к какому реестру не обращается. Состояние учётных данных сообщает только о наличии — никогда не сами учётные данные, никогда их форму и никогда то, примет ли их реестр, поскольку для этого потребовался бы сетевой обмен, которого перечисление не выполняет, — и считывается из общемашинного хранилища учётных данных, о чём прямо сообщаетcredentialStateIsMachineWide.aggrega/search— поиск по локальному индексу настроенных реестров. Каждое поле сужает поиск, и все поля необязательны, поэтому пустой объект параметров запрашивает всё, что содержит индекс. Запрос не обращается к сети: индекс — это офлайн-снимок, записанный в собственный каталог кэша этого рабочего пространства. Сообщаемая версия — та, которую выбрало бы разрешение зависимостей: версия, чей отзыв несёт подпись, которой доверяет это рабочее пространство, исключается и указывается вretracted, — а ответ несёт сведения о собственном происхождении:indexesсообщает возраст снимка каждого просмотренного реестра,staleпомечает снимок, который стоит обновить, аmissingIndexHostsназывает настроенные реестры без локального индекса, содержимое которых поэтому отсутствует в ответе.aggrega/registryAdd— регистрирует реестр и его политику доверия подписям. Полеhostобязательно; всё остальное определяет политику или цель записи.keyPathиtrustedRootназывают файлы: абсолютное значение — например, файл, выбранный в диалоге, — читается там, куда указывает; относительное называет файл внутри рабочего пространства и разрешается относительно корня рабочего пространства, а не каталога, в котором запущен демон, а значение, выходящее за пределы корня или ведущее из него через ссылку, отклоняется с ошибкой недопустимых параметров до того, как что-либо будет прочитано или записано. ОтносительныйtrustedRootзаписывается как файл, который он называет в рабочем пространстве, поэтому запись указывает на этот файл, в каком бы каталоге ни выполнялась последующая проверка.fetchTrustпо умолчанию равен true, если ключ отсутствует, как и в командной строке, и при первом обращении принимает политику, объявленную самим реестром;trustв ответе сообщает, что произошло: политика закреплена, реестр не объявил никакой политики (а при наличии рядомunreachable— вообще оказался недоступен), вместо неё закреплён встроенный базовый уровень официального хаба либо получение политики не предпринималось. Регистрация та же, что выполняетaggrega registry add: то же получение при той же сетевой политике, с записью той же записи байт в байт. В офлайн-рабочем пространстве получение отклоняется до какого-либо соединения, поэтому к реестру не обращаются, и реестр, отличный от официального хаба, отклоняется, если запрос не передаётidentitiesилиkeyPath, которые регистрируют ровно то, что было отправлено, без получения: сообщение ошибки — это предложение, которое печатает командная строка, с предшествующим ему кратким кодом условияE0310(сообщение каждого отказа этого запроса, называющего условие, начинается с его краткого кода), и ничего не записывается. Официальный хаб по-прежнему записывается на своём встроенном базовом уровне, а ответ содержитtrust.baselineсо значением true иtrust.reason, сообщающий, что политику доверия у хаба не запрашивали, поскольку рабочее пространство в офлайн-режиме (этой причиной начинается уведомление командной строки), и не содержитnotAdvertised, так как к хабу не обращались. По умолчанию это записывает глобальную конфигурацию — см. Обращение к реестру и запись.aggrega/registryRemove— удаляет запись реестра, указанного по хосту или понятному псевдониму. Токен, которому ничего не соответствует, отклоняется, а не возвращается как успех при неизменённой конфигурации. По умолчанию это записывает глобальную конфигурацию — см. Обращение к реестру и запись.aggrega/logout— удаляет сохранённые учётные данные для реестра; это то же удаление, котороеaggrega logoutвыполняет в терминале. Полеregistryобязательно и называет хост реестра так, как вы проходили на нём аутентификацию; здесь нет понятного псевдонима для разрешения, поскольку хранилище учётных данных индексируется адресом, на котором клиент проходит аутентификацию, а не чем-либо, что называет конфигурация, поэтому у хоста, не настроенного ни в одном рабочем пространстве, всё равно могут быть учётные данные, которые можно удалить. Хост, для которого в хранилище нет учётных данных, удаляется успешно, и ничего не перезаписывается: вызывающая сторона, которая просила, чтобы у хоста не было учётных данных, получила то, что просила, поэтому это ответ, а не ошибка, и так же поступает команда терминала. Ответ содержитregistryиscope. Он не содержит никакой части учётных данных ни в какой форме и ничего не сообщает о том, были ли они там: чтобы это установить, потребовалось бы повторное чтение хранилища, которого никто не просил, поэтому, когда вопрос в наличии, используйтеaggrega/registryList. Запрос не обращается ни к одному реестру: удаление сохранённых учётных данных — локальное действие, и вопрос о том, принял бы реестр эти учётные данные, не задаётся. Это изменяет хранилище учётных данных, общее для всех проектов на машине — см. Обращение к реестру и запись.aggrega/registryUpdate— обновляет локальный индекс для поиска, который читаетaggrega/search. Еслиregistryотсутствует, обновляются все настроенные реестры; если реестр указан, обновляется только он.upgradeзаново читает каждый репозиторий целиком, ничего не сравнивая с уже записанным индексом; обновление без него и так заново читает всё, что изменилось. Ответ содержит число записей для каждого хоста, репозитории, которые не удалось прочитать (каждый сreason, начинающимся с вида последнего сбоя чтения, если он есть),readsRetried— сколько его чтений реестр по ходу отклонил или оборвал, после чего они были запрошены снова, каждое учтено один раз, включая ноль, — встреченные маркеры устаревания,errorхоста, на котором произошёл сбой (сunreachableрядом, если этот реестр оказался недоступен), иindexRoot— каталог в собственном кэше этого рабочего пространства, в который записаны индексы. Это обращается к каждому обновляемому реестру — см. Обращение к реестру и запись.aggrega/publishEntity— упаковать сущность каталога и опубликовать её в реестре.entity— путь относительно корня рабочего пространства, указывающий на публикуемый документ; он отклоняется в тех же трёх случаях, что иrelease: если отсутствует, является абсолютным или разрешается за пределы корня. Сущности Plugin также нуженplugin— путь того же вида, указывающий на исполняемый файл, публикуемый внутри собственного манифеста сущности.registry— место назначения; по умолчанию это реестр, настроенный в рабочем пространстве.dryRunвычисляет пакет и дайджест, который получила бы его публикация, и не обращается ни к одному реестру. Еслиsignопущен, действует собственная политика реестра назначения — так поступает и командная строка, когда её флаг не указан, — а если он передан, решение принимает вызывающая сторона; ни то, ни другое не ослабляет отказ, потому что политика реестра или рабочего пространства, требующая подписи, отклоняет неподписанную публикацию, что бы ни говорило это поле.pinSources: trueвыполняет шаг закрепления автора сущности над сущностью до её упаковки, так чтоentity.lock, который этот шаг записывает рядом с ней, входит в публикуемое, — это тот же шаг, что выполняетaggrega/pin. Он выполняется до любого отказа, оценивающего содержимое сущности, — политики подписи, защиты неизменяемости, — поэтому публикация, отклонённая на этом этапе, всё равно оставляет записанный lock-файл; отказ, касающийся самого запроса, например офлайн-режим рабочего пространства или отсутствие места назначения, наступает раньше и ничего не закрепляет, как и отказ для сущности, делящей свой каталог с другой сущностью, в который шаг не должен записывать lock-файл. Если поле отсутствует, действует параметрpin_sources_at_pushрабочего пространства; если передано, оно переопределяет этот параметр в обе стороны. ПриdryRunшаг сообщает, какой lock-файл он записал бы, и ничего не записывает. Публикация, не выполняющая этот шаг, отклоняет Recipe или FeatureRecipe, чейentity.lockне содержит закрепления для читаемого ими входа или содержит закрепление, которому вход больше не соответствует, до какой-либо упаковки — в том числе приdryRun, — называяaggrega pin,pinSourcesиpin_sources_at_push; это тот же отказ, которыйaggrega/resolveDependenciesвыдаёт по тому же lock-файлу. Ответ содержитreference,tag,kind,mediaType, паруsize, опубликованныйdigest— приdryRunдайджест, который получила бы эта публикация, тот, что выводитaggrega push --dry-run, —signed,alreadyPublished,dryRunиreach;pin— тот же ответ, что даётaggrega/pin, — если шаг выполнялся; иwholeDirectorySource, если локальный источник сущности записан как шаблон, — с указанием этого источника в авторском виде. Такой источник выбирает свой каталог только после того, как Release заполнит шаблон, поэтому публикация переносит все файлы из каталога сущности, а не только названные сущностью, и именно по этому полю вызывающая сторона узнаёт об этом — в том числе при пробном запуске. Ответ также содержитwindowsUnusableEntries, если переносимый публикацией архив содержит записи, которые Windows не может хранить в записанном виде, — путь с частью, названной по имени устройства, напримерCON,AUXилиNUL, в любом регистре букв и с любым расширением, или часть, оканчивающуюся точкой или пробелом, — с перечислением каждой: сначала собственное имя файла документа сущности, затем переносимые им файлы; поле отсутствует, если таких записей нет, в том числе для сущности, опубликованной только в виде своего документа.aggrega, работающий в Windows, отказывается распаковывать такую запись, поэтому рабочее пространство в Windows не может использовать эту версию. Это те же записи, о которых предупреждаетaggrega push, и запрос, попросивший сообщать о ходе выполнения, получает те же строки предупреждений среди хода публикации; ни то, ни другое ничего не отклоняет, поэтому публикация выполняется или отклоняется ровно так же, как без них, в том числе приdryRun. Это записывает в реестр и выходит за пределы этой машины, а с шагом закрепления также записывает рядом с сущностью — см. Обращение к реестру и запись.aggrega/publishArtifact— опубликовать самостоятельный артефакт данных, например пакет документации.file— путь относительно корня рабочего пространства с тем же контрактом; его байты публикуются дословно: никакая оболочка сущности не разбирается и никакой диспетчеризации по виду не выполняется.nameиtagзадают, под каким именем он публикуется, и оба обязательны.mediaTypeпо умолчанию — тип пакета документации. Ответ содержитreference,tag,mediaType, паруsize, опубликованныйdigest,alreadyPublished,dryRunиreach. Ничего не подписывается — опубликованный артефакт подписывается позже по ссылке с помощьюaggrega/signArtifacts, которому нужна только ссылка из этого ответа. Это записывает в реестр и выходит за пределы этой машины — см. Обращение к реестру и запись.aggrega/signArtifacts— подписать уже опубликованные артефакты и прикрепить каждую подпись.referencesсодержит один или несколько адресов в реестре, а не пути, поэтому контракт относительных путей рабочего пространства к ним не применяется; пустой список или пустой элемент в нём отклоняется. Весь пакет обслуживает одна идентичность, и она определяется до подписания любой ссылки, поэтому пакет, для которого нет вообще никаких учётных данных, отклоняется в самом начале, а не на полпути. Так же отклоняется пакет, ссылкам которого потребовались бы разные учётные данные: запрос не называет ключа, поэтому это означает, что конфигурация рабочего пространства называет имеющийся ключ для реестра одной ссылки и никакого или другой ключ для реестра второй — ничего не подписывается, и отказ называет реестры с каждой стороны, как описано в References signed together need different signing credentials (Ссылкам, подписываемым вместе, нужны разные учётные данные для подписи). Подписание ссылки, по которой ничего не опубликовано, отклоняется, а не прикрепляется к пустоте, а ссылка, уже несущая подпись, которую проверяет политика доверия её реестра, остаётся как есть и считается подписанной, как описано вaggrega sign.jobs, необязательный параметр, задаёт, сколько ссылок подписывается одновременно: если он не указан, ссылки подписываются одна за другой, а значение меньше 1 отклоняется ошибкой invalid-params до чтения какой-либо ссылки. Каждая ссылка по-прежнему подписывается ровно так, как если бы она была одна, как описано вaggrega sign, а сообщаемый запросом ход выполнения и ответ сохраняют порядок, в котором были переданы ссылки. Ответ содержитsigned, каждый элемент которого называетreferenceи опубликованныйdigest, к которому привязана его подпись, наряду сreach; пакет, в котором хоть одна ссылка не удалась, возвращается как сбой с указанием каждой такой ссылки, а не как результат с неполным списком. Это записывает в реестр и выходит за пределы этой машины — см. Обращение к реестру и запись.aggrega/deprecateArtifact— прикрепить подписанный маркер устаревания к уже опубликованному артефакту. Передайте либо однуreferenceс еёseverityиreason, либоfromс указанием пакетного файла относительно корня рабочего пространства — передача обоих отклоняется. Поля содержимого обязательны, а не запрашиваются интерактивно: за этим потоком никто не следит, поэтому запрос без одного из них отклоняется с указанием того, что нужно передать. Они относятся только к однойreference: пакетный файл несёт содержимое каждого маркера в собственных элементах, поэтомуseverity,reason,replacementилиmessage, переданные вместе сfrom, отклоняются как недопустимый параметр с указанием каждого переданного поля, а не игнорируются. Здесь применяются те же бесключевые входные данные, что принимают два запроса подписания, потому что маркер подписывается по собственному дайджесту, а элементы пакетного файла привязываются к одним учётным данным точно так же, как ссылки пакета подписания. Ответ содержитmarked, каждый элемент которого называет отзываемуюreference, еёseverity, отметкуissuedOnи собственныйdigestманифеста маркера — маркер прикрепляется как нетегированный referrer артефакта, который он отзывает, поэтому ничто другое к нему не адресуется, — наряду сreach. Это записывает в реестр и выходит за пределы этой машины — см. Обращение к реестру и запись.aggrega/catalogIndex— индекс сущностей:kind,name,apiVersion,description,labels, исходный файл иoriginкаждой сущности в рабочем пространстве, названном в запросе. Принимает рабочее пространство и, необязательно,release: набор является свойством этого корня рабочего пространства и настроенных в нём каталожных директорий либо, сrelease, директорий, которые конфигурация задаёт для этой сущности Release, — см. Ответ в терминах одной сущности Release. Он охватывает оба места, откуда берётся сущность, — документы Aggrega под корнем рабочего пространства и сущности Features, которые содержат настроенные каталожные директории, — потому что именно с этой поверхностью клиент соединяет данные, когда ему нужны описательные поля сущности, а индекс, знающий только одно из двух, оставил бы часть каждого списка кандидатов неразрешимой. Документ рабочего пространства считается сущностью, если он объявляет иkind:, иmetadata.nameи не объявляетapiVersion, принадлежащий группе другого проекта, поэтому YAML, который просто лежит в дереве, — файл values чарта, конфигурация CI, отрендеренный манифест Kubernetes, — пропускается, а не попадает в список. Документ, не объявляющийapiVersionвообще, включается в ответ: это документ Aggrega с отсутствующим полем, и увидев его в списке, вы узнаёте, что его нужно исправить. Что означаютoriginи пустойfile, см. в разделе Как адресуется сущность. Ни один документ за ссылкой, ведущей за пределы корня рабочего пространства, не читается: директория вне корня не просматривается, а файл вне его не читается, что бы он ни объявлял, поэтому сущность, которую ваш редактор показывает под такой ссылкой, не включается в список как собственная сущность рабочего пространства — и не предлагается запросамиaggrega/attachCandidatesилиaggrega/connectionCandidates, которые читают те же документы, даже если этот документ открыт в вашем редакторе. Это верно, что бы документ ни объявлял. Единственное исключение — сущность Release, которую называет конфигурация вашего рабочего пространства, — какbuild.authoring_releaseили как ключworkspace.releases, причём оценивается файл, к которому ведёт ссылка, так что указание ссылки или этого файла равнозначно, — она читается из файла, к которому ведёт ссылка, включается в список на месте самой ссылки, так же как её перечисляетaggrega/releaseCandidates, и не называется; файл, названный одной из этих настроек, который объявляет что-либо кроме Release, в список не включается, а его ссылка называется. Настроенные каталожные директории — это способ, которым рабочее пространство читает другие сущности, хранящиеся в другом месте, поэтому ссылка на директорию, которую конфигурация перечисляет вcatalog_dirs, — для рабочего пространства или для сущности Release, — не просматривается так, как собственные документы рабочего пространства, и тоже не называется: конфигурация до неё дотянулась, и её сущности Features перечисляются из каталога, как и у каждой настроенной каталожной директории. Сущности Features, перечисленные из каталожных директорий, никогда не включают сущность за ссылкой, ведущей за пределы директории, внутри которой должно оставаться чтение каталожной директории, — рабочего пространства для каталожной директории внутри него или самой директории для той, которую конфигурация называет вне его, — поэтому сущность, которую ответ называет находящейся за непрочитанной ссылкой, никогда не перечисляется ещё и рядом с этим именем. Ответ называет каждую такую ссылку вunreadLinkedDirs— для ссылки на директорию — и вunreadLinkedFiles— для ссылки, собственное имя которой оканчивается на.yamlили.ymlи которая ведёт к файлу, — относительно корня, там, где находится ссылка, в порядке просмотра рабочего пространства, чтобы клиент мог объяснить причину. Ссылка, которую поиск исключает по её имени, по её расположению или по.gitignore, не называется, а в ответе в терминах сущности Release не называется и ссылка под каталожной директорией, которую читают только другие сущности Releases. Ссылка внутри каталожной директории вне рабочего пространства не имеет места относительно корня, по которому её можно назвать, и не называется. Оба поля присутствуют всегда и пусты, если таких ссылок нет. Если собственный файл конфигурации рабочего пространства или оверлей CI рядом с ним сам является ссылкой, ведущей за пределы рабочего пространства, этот файл называется вunreadLinkedFilesнезависимо от того, как его обрабатывает поиск, а индекс представляет собой собственное чтение рабочего пространства без какой-либо конфигурации — ни одна каталожная директория для него не читается, а индекс в терминах сущности Release отклоняется; см. Корень рабочего пространства и активная сущность Release.aggrega/entityDefinition— во что разрешается названная сущность: еёkind, её собственныеnameиversion, еёdescriptionиpublishScope, если они есть,file, в котором она объявлена,authoredLengthавторского текста за ней и еёdefinitionв виде документа YAML с уже применённым наследованием.fileсообщается для каждого вида как путь, который можно открыть, — относительно корня рабочего пространства для документа внутри него и абсолютный для документа вне его, согласно разделу Как записывается сообщаемый путь. Он пуст в одном случае: у сущности, разрешённой из реестра, нет авторского документа на этой машине, который можно назвать.authoredLengthотвечает на другой вопрос — сколько авторского текста сохранило разрешение, — и он присутствует только у сущности Aggregate, поэтому читайте эти два поля по отдельности, а не как пару.name— идентификатор сущности, записанный так, как одна сущность ссылается на другую, и он может содержать суффикс версии. Это единственный запрос здесь, который начинается с имени, а не с позиции курсора, поэтому его следует использовать, когда вы уже знаете, какую сущность имеете в виду.releaseнеобязателен и разрешает имя в терминах этой сущности Release — см. Ответ в терминах одной сущности Release. Имя, которое ни во что не разрешается, отклоняется, а не получает в ответ пустой документ; см. Как различить два отказа по имени. Вместо этогоnameможет быть ссылкой на реестр —oci://<host>/<repository>:<tag>или@<digest>вместо:<tag>, — и тогда ответом является сущность, опубликованная по этой координате и прочитанная из её реестра, аpublishedназывает, что было прочитано; см. Запрос о координате.aggrega/releaseClosure— замыкание зависимостей сущности Release: какие сущности она достигает и в каких разрешённых версиях, вentities,librariesиplugins, вместе с идентификаторамиaggregateиmanifest, в которые разрешились два её указателя, любымиmappingDiagnostics, выданными при разрешении, иdeprecations, записанными для достигнутого, — в её lockfile и в записи доверия плагинов рядом с ним, так что отозванный плагин, подключённый в роли вердикта, называется так же, как отозванная закреплённая ссылка.release— путь относительно корня рабочего пространства, называющий сущность Release внутри него, то же значение, что принимаетaggrega/irGraph, отклоняемое в тех же случаях, и по той же причине он требует lockfile. Ничего не рендерится. Её записи не называютsource: они говорят, от чего зависит сущность Release, а не что сделал один запуск, — об этом сообщаетaggrega/resolveDependencies. См. Замыкание — это не граф, потому что у клиента, уже получающего граф, этих данных нет.aggrega/attachCandidates— какие сущности Features могут быть присоединены к узлу: те, чью объявленную применимость удовлетворяют метки узла. Передайте ровно одну координату.nodeназывает документ рабочего пространства по егоmetadata.name;graphNodeназывает узел скомпилированного графаreleaseпо идентификатору, под которым этот граф его хранит;labelsпередаёт набор меток напрямую и ничего не называет — для клиента, у которого такой набор уже есть. Ответ повторяет координату, для которой он дан (пустую, если повторять нечего), содержитnodeLabels— пары меток, по которым вычислялось сопоставление,labelSource, указывающий, какого рода этот набор меток, и каждого кандидата в видеkind,name, исходного файла иorigin, которые его адресуют. Возврат меток делает ответ проверяемым сам по себе: клиент может объяснить, почему была предложена сущность Feature, не составляя собственного представления о метках узла, — а именно так ответ клиента и ответ компилятора расходятся. Для узла графа предлагаются те Features, которых достигает сущность Release этого узла. Рядом сgraphNodeпараметрconnectionназывает одно соединение, которое рисует компонент этого узла, — егоsocketиalias, и тогда ответ также содержитslots— каждый слот, объявленный сокетом этого соединения, с Features, которые могут его заполнить, — илиnoSlotReason, если ни один слот заполнить нельзя. См. Что сообщает ответ о кандидатах на присоединение.aggrega/connectionCandidates— с чем может соединяться названная сущность.node— этоmetadata.nameсущности, та же координата, которуюaggrega/attachCandidatesпринимает под этим именем. См. Что сообщает ответ о кандидатах на соединение ниже: две половины ответа неодинаково полны, и ответ указывает, какая из них какая.aggrega/insertionPoint— где в авторском документе должна располагаться новая запись внутри названного контейнера, в форме, позволяющей клиенту применить её, не разбирая документ самостоятельно.fileназывает документ, который содержит рабочее пространство, — относительно корня рабочего пространства, абсолютным путём или в виде адресаfile://; документ вне корня — как указано или через ссылку, ведущую за его пределы (на файл или на каталог по пути), — отклоняется, каким бы написанием он ни был назван и независимо от того, есть ли у вас его копия;container— структурный путь от корня документа к контейнеру, в который помещается запись, где каждый элемент — ключ отображения или позиция в последовательности, записанная в десятичном виде. Этот путь задаёте вы — демон читает собственную структуру документа и никогда не определяет, где что-то должно находиться, по тому, как оно называется. См. Что сообщает ответ о точке вставки: одной позиции недостаточно, чтобы применить правку.aggrega/attachmentContainer— в каком документе должно находиться присоединение сущности Feature к узлу и в каком контейнере внутри него.graphNodeназывает узел скомпилированного графаreleaseпо идентификатору, под которым этот граф его хранит, и оба параметра обязательны: идентификатор узла — это ключ графа одной сущности Release и без неё ничего не значит. Ответ содержитnode,fileиcontainer— список сегментов ровно в той форме, которую принимаетaggrega/insertionPoint, так что эти два запроса стыкуются без промежуточных вычислений. Для присоединения к одному соединению, которое рисует компонент узла, добавьтеconnectionс егоsocket,aliasиdocument—aggregateилиrelease, и ответ назовёт собственный контейнерfeaturesэтого соединения в указанном документе. См. Что сообщает ответ о контейнере присоединения:file— часть ответа, а не то, что вам уже известно.aggrega/connectionAtPosition— внутрь записи какого соединения попадает позиция в сущности Aggregate или Release; ответ даётся в тех терминах, в которых два запроса выше принимают соединение.fileназывает документ так же, как его называетaggrega/insertionPoint, и читается в первую очередь из того, что сессия хранит для него;position— место в нём,lineиcharacter, отсчитываемые от нуля в кодировке сессии;releaseназывает сущность Release, скомпилированный граф которой записывает соединения, и он обязателен и для позиции в сущности Aggregate, поскольку узел графа и соединение существуют только в скомпилированном графе. Ответ содержитgraphNodeиconnection— егоsocket, егоaliasиdocument, в котором была прочитана позиция, — для передачи вaggrega/attachCandidatesиaggrega/attachmentContainerбез изменений, либоnoConnectionReason, если в этом месте не записано ни одного соединения. См. Что сообщает ответ о соединении в позиции.aggrega/editDocument— применяет одну ограниченную структурированную правку к авторскому документу, сохраняя каждый байт, которого она не касается. Это вторая половина двух методов определения места выше: они говорят, где должна располагаться запись, и оставляют составление и применение вам, а этот метод сам составляет и применяет одну правку.editуказывает, какую из четырёх —add-component,attach-feature,wire-edge,set-value, — а значение вне этого списка отклоняется, а не интерпретируется;node— структурный путь от корня документа, список сегментов ровно в той форме, которую принимаетaggrega/insertionPoint;name— ключ, под которым записывается запись, аvalue— то, что она содержит, и их смысл определяетсяedit;socketчитается дляwire-edgeи в остальных случаях игнорируется.dryRunделает всё то же, что и обычный запрос, кроме записи, и возвращает отредактированный документ какcontent— для клиента, который сначала показывает результат автору; при этом ничего не создаётся, аwrittenпуст.fileназывает документ относительно корня рабочего пространства или абсолютным путём, а документ вне корня — как указано или через ссылку, ведущую за его пределы, на файл или на каталог по пути, — отклоняется, и ничего не читается и не записывается. Этот метод записывает названный вами документ внутри рабочего пространства — он не разрешает зависимостей, не обращается к реестру и не использует сеть ни при одном способе доставки, а запись выполняется только при условии, что составленный документ проходит проверку по схеме своего вида. См. Что сообщает ответ о правке документа: по умолчанию выполняется запись, а отказ оставляет файл побайтно таким, каким он был.aggrega/releaseCandidates— документы Release рабочего пространства, названного в запросе, в виде абсолютных путей. Принимает рабочее пространство и ничего больше: этот набор — свойство корня данного рабочего пространства. Принадлежность определяется видом документа —kind:файла равенRelease, — а не именем файла, поэтому сущность Release, названная без условного префикса, предлагается, а файл, лишь названный похоже, — нет. Именно этот список должен показывать выбор «какой Release?» в редакторе, поскольку это тот же набор, из которого выбирает описанный ниже каскад активного Release. Ответ также содержитlockfiles, сопоставляющий каждому перечисленному Release — по ключу, в точности равному строке, под которой его перечисляетreleases, — абсолютный путь к его lock-файлу; поле присутствует всегда и является пустым объектом, когда в рабочем пространстве нет ни одного Release. Он содержит иunreadLinkedDirs, называющий — относительно корня, где находится ссылка, — каждую ссылку, которая стоит там, где при перечислении читался бы каталог, и ведёт в каталог вне корня рабочего пространства: ни один каталог вне корня не просматривается, поэтому Release, который ваш редактор показывает в таком каталоге, не перечисляется, и именно это поле позволяет окну выбора объяснить причину. Ссылка на каталог, который конфигурация вашего рабочего пространства перечисляет вcatalog_dirs, не называется: конфигурация уже достигла его — как каталога каталогов, а не как места хранения Releases. Поле присутствует всегда и пусто, когда таких ссылок нет. Рядом с нимunreadLinkedFilesтем же способом называет каждую ссылку, собственное имя которой оканчивается на.yamlили.ymlи которая ведёт к файлу вне корня рабочего пространства: такой файл не читается, что бы он ни содержал, поэтому Release, доступный только через одну из этих ссылок, не перечисляется, и шаг каскада «единственный Release», описанный ниже, его не учитывает. Исключение — файл, который конфигурация вашего рабочего пространства называет как Release — вbuild.authoring_releaseили как ключworkspace.releases, с оценкой по файлу, к которому ведёт ссылка, так что указание ссылки или этого файла засчитывается одинаково, — он читается и перечисляется на собственном месте ссылки и не называется, при условии что объявляет Release; файл, объявляющий что-либо иное, не перечисляется, а его ссылка называется. Поле присутствует всегда и пусто, когда таких ссылок нет. Если собственный файл конфигурации рабочего пространства или принадлежащий CI оверлей рядом с ним сам является ссылкой, ведущей за пределы рабочего пространства, этот файл называется здесь независимо от того, как с ним обходится поиск, а перечисление читается без какой-либо конфигурации, поэтому Release, который конфигурация назвала бы через ссылку, не перечисляется; см. Корень рабочего пространства и активный Release. См. Где находится lock-файл Release.aggrega/activeRelease— на какой Release указывает рабочее пространство, названное в запросе, в виде абсолютного пути в полеrelease, для клиента, решающего, что выбрать по умолчанию. Принимает рабочее пространство и ничего больше. Поле присутствует всегда, а пустое значение означает, что рабочее пространство ни на что не указывает, — это успешный ответ, а не ошибка, поэтому клиент, обновляющий его при каждом перезапуске демона, не вынужден считать обычное рабочее пространство сбоем. Когда значение пусто, ответ также содержитreason— однострочную сводку того, что искал каскад, — иtrace— пошаговый отчёт об этом; оба опускаются, если Release разрешился. Когда Release разрешился, ответ вместо них содержитlockfile— абсолютный путь к lock-файлу этого Release, — который опускается, если разрешения не было. Названный Release не обязан входить в списокaggrega/releaseCandidates: маркер может назвать Release в каталоге, который этот список пропускает, напримерvendor/, или Release без расширения YAML, — поэтому именно из этого ответа клиент читает lock-файл Release по умолчанию. См. Где находится lock-файл Release. Запрашивайте его, а не выводите ответ из одного из входов каскада: вход, который каскад в итоге не использовал, называет иной Release, чем выбранный. Ответ вычисляется в момент запроса, поэтому повторный запрос после записи маркера, правки конфигурации или добавления файла Release сообщает новый ответ, а не состояние рабочего пространства на момент запуска демона.aggrega/setActiveRelease— записывает Release как значение по умолчанию для рабочего пространства, названного в запросе, создавая маркер.aggrega/active-releaseэтого рабочего пространства, и отвечает в точности так, какaggrega/activeReleaseотвечает после записи маркера. Принимает рабочее пространство иrelease: путь относительно корня рабочего пространства, называющий Release внутри него и подчиняющийся тому же контракту, что иreleaseвaggrega/irGraph, — абсолютный путь, путь, выходящий за пределы рабочего пространства, и пустое значение отклоняются, как и путь, выводящий наружу через ссылку, если только конфигурация вашего рабочего пространства не называет этот Release. Маркер — одна строка, называющая Release относительно корня, в форме, которую читает описанный ниже каскад. Он записывается внутри рабочего пространства и больше нигде: если.aggregaили сам маркер — ссылка, ведущая за пределы рабочего пространства, — независимо от того, существует ли уже место назначения, — запрос отклоняется с ошибкой invalid-params, сообщение которой — собственное предложение условия с предшествующим коротким кодом,E0320: …(fatal-halts.md §«A path the operation writes leads through a link out of the directory it must stay inside (Путь, по которому записывает операция, ведёт через ссылку за пределы каталога, в котором он должен оставаться)»), с указанием ссылки и того, куда она ведёт, и ничего не записывается; запись через ссылку, остающуюся внутри рабочего пространства, выполняется. Ответ называет то, на чём останавливается каскад, а не повторяет отправленное вами, и они различаются, когдаbuild.authoring_releaseназывает Release, поскольку конфигурация приоритетнее маркера. Задавайте значение по умолчанию этим способом, а не записывайте файл сами, чтобы место маркера оценивалось по правилу, которому подчиняется каждый файл, записываемый продуктом в рабочем пространстве, — см. Граница рабочего пространства.aggrega/effectiveConfiguration— конфигурация, действующая для рабочего пространства, названного в запросе, и слой, из которого пришёл каждый параметр. Принимает рабочее пространство и ничего больше: ответ — свойство этого рабочего пространства.layersперечисляет файлы конфигурации и переопределения окружения, внёсшие вклад, начиная с самого низкого приоритета;settingsсодержит каждый атрибутированный параметр в виде его имени через точку, действующего значения иsource, который его определил.sourceзаписывается в точности как соответствующая запись вlayers, поэтому они соединяются напрямую. См. Что охватывает ответ о действующей конфигурации о том, какой слой называетsource, и о границах смысла строки.aggrega/configInit— создаёт рабочую конфигурацию, регистрируя реестр и его политику доверия подписям, чтобы на новой машине можно было получать и проверять подписанные артефакты без ручной правки YAML.registryнеобязателен, и при его отсутствии создаётся запись для официального хаба — то же значение по умолчанию, что уaggrega config init; поле ответаhostназывает тот реестр, который был использован.globalиworkspace— переопределения цели записи, и отправка обоих отклоняется. Запрос отказывает, а не перезаписывает существующий файл конфигурации, называя этот файл, — отправьтеforce, чтобы всё же продолжить: тогда запись реестра объединяется с уже имеющимся содержимым, а остальные параметры сохраняются.dryRunделает всё то же, что и обычный запрос, кроме записи, и отвечает созданной конфигурацией вcontent— для клиента, который показывает документ автору до сохранения; при этом ничего не создаётся, аwrittenравно false. Отказ при существующем файле действует и приdryRun, поэтому отправьте вместе с нимforce, чтобы получить в ответ результат объединения, который дала бы перезаписывающая запись. В офлайн-рабочем пространстве можно создать запись только для официального хаба: этот запрос не принимает ни идентичностей, ни ключа, поэтому любой другой реестр отклоняется в точности так, как его отклоняетaggrega/registryAdd, включая короткий код и предложение, и добавляется вместо этого через тот запрос с политикой, заданной вручную. Ответ содержитhost,scope,trustиwritten, а такжеexisted— true, если файл конфигурации уже существовал (и запись реестра объединяется с ним, а не создаётся новый файл), и отсутствует, если файл создаётся. По умолчанию этот запрос записывает глобальную конфигурацию — см. Доступ к реестру и запись.aggrega/configCapture— фиксирует действующую критичную для сборки конфигурацию в собственном файле конфигурации этого рабочего пространства, чтобы рабочее пространство собиралось так же без глобальной конфигурации машины под ним. Не принимает цели записи: фиксация существует, чтобы сделать одно рабочее пространство самодостаточным, поэтому всегда записывает файл этого рабочего пространства.allPluginsрасширяет фиксируемый набор от сокетов, определяющих отрисованный вывод, — привязок провайдеров и подключений governance с ролью label-transform — до всех сокетов плагинов, добавляя шлюзы вердиктов governance и линтеров, а также сокет импорта. Ответ содержитconfigFile,workspaceRoot,captured,socketsиcatalogDirs. См. Что оставляет после себя запись конфигурации, поскольку ответ называет документ, который теперь существует, и следующее действие клиента — его открытие.aggrega/skillsInstall— записывает встроенный в этот исполняемый файл навык Aggrega в папку навыков каждого ассистента, названного в запросе, — это та же установка, которую выполняетaggrega skills installв терминале.agentsперечисляет ассистентов по идентификаторам — тем, которые сообщаетaggrega/skillsList; идентификатор, указанный дважды, устанавливается один раз, а если несколько названных ассистентов читают одну общую папку, навык записывается туда один раз. Для установки в проект он обязателен. Запросglobal, не называющий ни одного ассистента, устанавливает навык для ассистентов, найденных на этой машине, как это делаетaggrega skills install --globalбез--agent, — для каждого, чья папка конфигурации находится в домашнем каталоге или чья команда есть вPATHокружения демона, — и отклоняется без какой-либо записи, если ни один не найден; ничего не запрашивается у пользователя, аinstalledназывает ассистентов, для которых записан навык. Безglobalнавык попадает в папку проекта каждого ассистента внутри рабочего пространства, названного в запросе, и никогда — в каталог, в котором был запущен демон; сglobal: trueон попадает в пользовательскую папку каждого ассистента в домашнем каталоге, который указывает окружение демона (HOME, илиUSERPROFILEв Windows). Каждое место назначения проверяется до какой-либо записи, поэтому при отказе все папки остаются такими, какими были: идентификатор, для которого неизвестна папка навыков, отклоняется с указанием его самого и существующих идентификаторов, а файл в месте назначения без строки комментария, которую несёт каждая записанная копия навыка, отклоняется с указанием его пути. Копия с этой строкой — записанная предыдущей установкой или взятая из опубликованного репозитория навыков — заменяется; так более новая версияaggregaобновляет навык до своей версии. Папка проекта, достигаемая через ссылку, ведущую за пределы рабочего пространства, отклоняется, и ничего не записывается, как и при любой записи демона в рабочем пространстве, — см. Граница рабочего пространства. Ответ содержитskill,installed— по одному элементу на каждую записанную папку в том порядке, в котором были названы ассистенты, каждый сagents, которые её читают, абсолютным путёмfolderиreplaced, — иscope. Сglobalэто записывает папки, которые читает каждый проект на машине, — см. Обращение к реестру и запись.aggrega/skillsList— навыки, поставляемые с этим исполняемым файлом, и каждый ассистент, для которогоaggrega/skillsInstallможет их записать, — список, который выводитaggrega skills list. Принимает только рабочее пространство и ничего из него не читает.skillsсодержитnameиdescriptionкаждого навыка;agentsсодержит для каждого ассистентаid,name,projectFolder— относительно корня проекта, которым на этой поверхности является рабочее пространство, названное в запросе, — иuserFolder— относительно домашнего каталога; оба пути разделены слешами, а ассистенты упорядочены по идентификатору. Ничего не записывает и ни к чему не обращается.aggrega/pluginAdd— ищет в настроенном реестре плагин указанного типа и добавляет его в конфигурацию.typeиqueryобязательны:type— одно изprovider,governance,linter,importerиcli, аqueryсопоставляется с именами плагинов этого типа и должен разрешаться ровно в один, поэтому запрос, совпадающий с несколькими, отклоняется с перечнем кандидатов, а не разрешается произвольно.capabilityназывает возможность, которую обслуживает привязкаprovider, и для неё обязателен;roleназывает роль подключенияgovernance—label-transform,ir-verdictилиrender-verdict— и для него обязателен; каждое поле читается только для своего типа и отклоняется для любого другого, поскольку поле, молча ничего не делающее, выглядело бы так, будто оно сработало.acceptCapabilitiesобязателен дляcliи подтверждает объявленные возможности этого плагина: терминальная команда получает это решение, спрашивая пользователя, а у этого интерфейса спросить некого, поэтому решение получает и отправляет вызывающая сторона.globalиworkspace— переопределения цели записи, и отправка обоих отклоняется.dryRunделает всё то же, что и обычный запрос, кроме записи, и отвечает итоговой конфигурацией вcontent; ничего не создаётся и не изменяется, аwrittenравно false. Реестр всё равно просматривается, и версия всё равно разрешается, поскольку идентичность в этом содержимом — та, которую закрепила бы запись.dryRunдля типаcliотклоняется, а не игнорируется: добавление расширения команд записывает дайджест содержимого проверенных байтов — запись, которую ведёт компилятор, а не содержимое, которое кто-либо правит, — и по ходу добавления эти байты кэшируются, поэтому оно записывается, а не возвращается. Версия закрепляется за вас: запрос разрешается в один плагин, и в запись вносится версия, которую запрос называет в виде<name>:<version>, а если версия не названа — наибольшая опубликованная версия плагина; названная версия, отозванная объявлением об отзыве, которому доверяет это рабочее пространство, всё равно закрепляется, и ответ содержитwithdrawn: true. Этот запрос обращается к реестру, а добавление типаcliбез указания области записывает глобальную конфигурацию — см. Доступ к реестру и запись. См. Что сообщает изменение плагина.aggrega/pluginRemove— удаляет запись настроенного плагина, чтобы он больше не участвовал.typeпринимает тот же набор, что и при добавлении, аqueryопределяет запись: короткое имя плагина, его закреплённую ссылку или — дляprovider— возможность, которую обслуживает привязка. Оба обязательны.globalиworkspace— те же переопределения цели записи, отклоняемые вместе тем же образом. Запрос, не совпадающий ни с одной записью, отклоняется, а не возвращается как успех над неизменённой конфигурацией, поэтому вызывающей стороне никогда не сообщают, что плагин перестал участвовать, если это не так, и опечатка никогда не удалит другой плагин. Запрос не обращается ни к какому реестру: удаление работает только с текстом конфигурации. Удаление типаcliбез указания области записывает глобальную конфигурацию — см. Доступ к реестру и запись. См. Что сообщает изменение плагина.aggrega/pluginSync— согласует принадлежащие машине записи сущности Plugin с её модулем: набор функций хоста, выведенный из собственных импортов модуля, и зеркало команд, прочитанное из самоотчёта модуля. Ни одна из записей не пишется вручную, поскольку обе являются истиной, заложенной в модуле. Оба поля обязательны, и ни у одного нет значения по умолчанию — записи выводятся из модуля, поэтому согласованию, не называющему ни одного, не с чем согласовываться, — и оба являются путями относительно корня рабочего пространства, отклоняемыми, если они абсолютны или разрешаются за его пределы — как записаны или через ссылку. Меняются только эти два блока: каждый прочий байт сохраняется дословно, включая комментарии, пустые строки и стиль кавычек, а файл, уже содержащий то, что следует из модуля, остаётся побайтово идентичным и сообщается как неизменённый. Этот запрос записывает названный вами файл сущности внутри рабочего пространства и не обращается ни к какому реестру. См. Что сообщает изменение плагина.aggrega/pluginGenCatalog— генерирует по одной сущности Plugin на каждый выбранный гостевой модуль, объединяя поля контракта, выведенные из самоотчёта модуля, с написанным вручную оверлеем для каждого плагина.fromEmbeddedиplugin— два режима выбора, и применяется ровно один: все гостевые модули, которые несёт этот бинарный файл, или один модуль по указанному вами пути; указание обоих или ни одного отклоняется, а не разрешается.overlayобязателен: приfromEmbeddedэто каталог оверлеев, приplugin— один файл оверлея; когда модулей несколько, оверлей сопоставляется с модулем по идентичности, а когда модуль один, сопоставлять нечего.outputDirобязателен при обоих способах выдачи, иdryRunот него не освобождает: пробный запуск меняет то, куда попадает содержимое, но не то, для какого файла оно предназначено, поэтому каждый возвращаемый документ по-прежнему указывает свой путь, а этот путь составляется из данного каталога. Три пути здесь оцениваются по-разному, и это разделение следует из того, что генерация делает с каждым.pluginиoverlayчитаются, и оба — выбранные вами файлы: модуль оказывается в том каталоге, куда собирает его инструментарий, а его оверлей пишется рядом с ним, — поэтому каждый из них может быть абсолютным и читается там, где он фактически находится. ВoutputDirвыполняется запись, поэтому он задаётся относительно корня рабочего пространства и отклоняется, если он абсолютный или разрешается за пределы корня — как записан или через ссылку; ещё не созданный каталог внутри связанного каталога, ведущего наружу, отклоняется так же, как этот каталог. Повторный запуск на неизменных входных данных даёт побайтово идентичные сущности. Запрос записывает сгенерированные сущности вoutputDirвнутри рабочего пространства, если толькоdryRunне запрашивает их в виде содержимого. См. Что сообщает изменение плагина.aggrega/getSchema— JSON Schema для вида сущности или контракта, прочитанная из копии, вкомпилированной в запущенный бинарный файл.kind— токен схемы в нижнем регистре через дефис (component,aggregate,release,recipe,ir,wasm-providerи так далее), и он необязателен, поскольку определяет, какой из двух вопросов вы задаёте. Если указать вид, ответ содержитkindиschema— схему как JSON-документ, а не как строку, содержащую его. Если не указать, ответ вместо этого содержитkindsиentityKinds: какие виды можно указывать, в двух объёмах.kinds— все токены, которые можно запросить у этого бинарного файла, в том же порядке, в каком их выводитaggrega get-schema --list.entityKinds— более узкий набор видов, документы которых пишет автор; каждая запись содержит токенkindдля отправки обратно, значениеdocumentKind, которое ставится в собственное полеkind:документа, иacceptedBy, сообщающее, принимают ли документ этого вида проверка отдельной сущности, публикация и просмотр по имени. Прежде чем строить на основе любого из них элемент выбора, см. Какие виды можно предлагать автору. Ответ со схемой и перечисление никогда не объединяются, поэтому по ответу видно, на какой вопрос он дан. Токен, которому не соответствует ни одна схема, отклоняется с полным допустимым набором в сообщении, так что опечатку можно исправить без второго вызова. Запрос ничего не берёт из рабочего пространства, не обращается к реестру и ничего не записывает, поэтому отвечает даже в пустом рабочем пространстве — именно это позволяет использовать его для привязки схем в редакторе к тому бинарному файлу, которым редактор фактически управляет, а не к какой-либо копии схем, установленной в другом месте.aggrega/scaffoldEntity— начальный документ для вида сущности: ровно те поля, которых требует схема этого вида, с заполненными фиксированнымиapiVersionиkindи заполнителем везде, где нужно значение.kindобязателен и является токеном схемы в нижнем регистре через дефис (component,aggregate,release,recipe,manifest,featureи так далее);aggrega/getSchemaбезkindсообщает, какие токены можно отправлять, а токен, которому не соответствует ни одна схема, отклоняется с этим набором в сообщении, так что опечатку можно исправить без второго вызова. Клиент, предлагающий автору выбрать вид, читаетentityKindsэтого метода — набор видов, документы которых можно написать.nameнеобязателен и задаётmetadata.nameдля видов, схема которых его требует. Ответ содержитkindиskeleton. См. Что даёт ответ на запрос заготовки, поскольку ответ — это документ, который нужно записать, а не уже записанный документ. Заготовка выводится из той же схемы, которую сообщаетaggrega/getSchema, поэтому оба отвечают из одного источника. Если вместоkindотправленexample, он записывает один из готовых к запуску примеров документации в новый каталог рабочего пространства, как это делаетaggrega scaffold --exampleв терминале; если отправлено толькоlist: true, он отвечает всеми имеющимися примерами и ничего не записывает. Обеим формам нужно рабочее пространство, поэтому запрос любой из них указывает его вworkspaceRoot, а запрос без него отклоняется.dirзадаёт новый каталог относительно корня рабочего пространства, а по умолчанию это имя примера; абсолютное значение или такое, которое разрешается за пределы корня, — как записано или через ссылку, — отклоняется, прежде чем что-либо будет прочитано, а каталог, содержащий что-либо, отклоняется и остаётся как есть. Ответ на список содержитexamples, каждый сname,levelиsummary; ответ на запись содержитexample,dir,files(каждый записанный файл относительноdir),next(команды, которые страница примера приводит для его сборки; отсутствует, если она их не приводит) иversion(версия документации, из которой прочитан пример). Поля двух форм, отправленные вместе, —kindсexample,listсexampleилиkind,nameсexampleилиlistлибоdirбезexample, — отклоняются, прежде чем что-либо будет прочитано, теми же словами, которыми их отклоняет инструмент ассистента. Запись получает пакет документации, если на машине нет копии, которую допускает собственная проверка подписи рабочего пространства, и записывает внутри рабочего пространства — см. Обращение к реестру и запись.aggrega/import— преобразует внешнее описание источника в черновые файлы для Aggrega, выполняя то же преобразование, чтоaggrega importв терминале.sourceобязателен и указывает преобразуемый файл или каталог — абсолютным путём или относительно корня рабочего пространства: описание, экспортированное другим инструментом, находится там, где вы его сохранили, поэтому оно читается там, где фактически находится, а не только внутри рабочего пространства. Каталог читается так же, как его читаетaggrega import: те его файлы, которые выбирают объявленные импортёром шаблоны файлов, за исключением папки результатов сборки рабочего пространстваdist/, и в пределах самого каталога, где бы он ни находился, так что ни одна ссылка внутри него не ведёт за его пределы.outputDirнеобязателен и указывает каталог для черновиков, и на него это соглашение не распространяется: в него выполняется запись, поэтому это путь внутри рабочего пространства, а абсолютное значение или значение, разрешающееся за пределы корня — как записано или через ссылку, включая ещё не созданный каталог внутри такой ссылки, — отклоняется. Если его опустить, черновики помещаются в корень рабочего пространства, куда их пишетaggrega import, когда назначение не указано, — в том числе приdryRun.formatявно указывает формат источника; если его опустить, формат распознаётся по сигнатурам, которые объявляют импортёры, — как из каталога рабочего пространства, так и основные импортёры компилятора, — а источник, который не распознаёт ни один из них или распознают импортёры более чем одного формата, отклоняется с просьбой указатьformat, а не угадывается.targetуказывает возможность провайдера, напримерcomposeилиhelm(слово, к которому привязываетсяspec.capabilityсущности Recipe), и в дополнение к черновикам импортёра создаёт черновик Manifest, на основе которого собирается черновой Release для этого провайдера, в точности какaggrega import --target:manifest.yaml, сопоставляющий каждый тип компонента и каждый тип функции, нужные черновикам, — включая типы сущности Aggregate из каталога, которую черновой Aggregate включает в свой состав, — с сущностью Recipe или рецептом функции этой возможности, которые каталог рабочего пространства предлагает для него, по имени с указанием возможности и без версии: с единственным имеющимся или, среди нескольких, с названным по типу.spec.manifestсущности Release указывает на него; тип без такого или с несколькими, ни один из которых так не назван, остаётся несопоставленным с находкойwarn, называющей его, а сопоставление, которое импортёр создал сам, сохраняется там, где каталог предлагает его для этого типа и возможности, а иначе отбрасывается с находкойwarn.target, к которому не привязана ни одна сущность Recipe в каталоге, отклоняется до запуска импортёра с указанием его и возможностей, к которым привязаны Recipes каталога, и ничего не записывается; если его опустить, Manifest не создаётся — кроме случаяsync, который создаёт черновик для цели, указанной в записи предыдущего импорта. Основной импортёр, которого ещё нет на машине, загружается первым импортом, которому он нужен, — см. Что сообщает ответ на импорт.dryRunвыполняет всё то же, что и обычный запрос, кроме записи, и возвращает черновики в виде содержимого — для клиента, который сначала показывает их автору; при этом ничего не создаётся, аwrittenпуст.syncприводит то, что предыдущий импорт создал вoutputDir, в соответствие с источником, изменяя только записанное импортом, как это делаетaggrega import --sync; без него запрос, черновики которого перезаписали бы уже существующий Aggregate, отклоняется. Ответ содержитformat,outputDir,written,files,drift,diagnostics,decisionsиhalted. См. Что сообщает ответ на импорт, поскольку источник, который импортёр не смог полностью преобразовать, — это успешный ответ, а не ошибка.aggrega/explainError— то, что компилятор объявляет об условии, которое называет код, и опубликованные статьи, объясняющие, как исправить исходные файлы.codeобязателен и принимает любой из идентификаторов условия: короткий код, который диагностика передаёт вshortCode, или описательный код изcode. Это расшифровка кода, который диагностические сообщения в этом протоколе уже содержат, и тот же ответ, которыйaggrega explainвыводит в терминале. Ответ всегда содержит условие —shortCode,codeиmessage, — потому что эти сведения объявлены внутри исполняемого файла и не требуют сети;entriesсодержит опубликованное пошаговое описание, аnoteобъясняет, почему его нет, если оно отсутствует. Этот метод получает пакет документации, если на машине нет копии, которую допускает собственная проверка подписи рабочего пространства, — см. Обращение к реестру и запись. См. Расшифровка кода из диагностики.aggrega/invalidate— сигнал инвалидации кэша от средства отслеживания файлов редактора.
Уведомления:
$/cancelRequest— от клиента к серверу: остановить выполняющийся запрос, отправленный под этим id. Демон отменяет работу этого запроса; операция замечает отмену на ближайшей границе шага, а не мгновенно, поэтому уже начатая работа продолжается ещё некоторое время. Отмена id, по которому ничего не выполняется, безопасна и ничего не делает.$/progress— от сервера к клиенту: что делает длительная операция по ходу выполнения, с токеном, по которому запрос просил сообщать. Отправляется только для запроса, который передал такой токен. См. Наблюдение за длительной операцией.aggrega/shutdown— начать согласованное завершение: выполняющиеся запросы завершаются, новые запросы отклоняются, затем демон завершает работу.aggrega/publishDiagnostics— набор диагностик, отправляемый сервером (используется для предупреждений о расхождении с lockfile и для состояния при запуске). Каждая запись содержитsource, указывающий, какой из диагностических уровней демона её создал:aggrega— для замечания об исходных документах,aggrega-build— для рекомендации, выданной сборкой (всех выданных ею рекомендаций, то есть того же набора, который выводитaggrega build), иaggrega-lint— для замечания о соглашениях публикации, тех же замечаний, которые выводитaggrega lint. Это поле всегда присутствует в каждой записи, поэтому клиент может группировать записи, а не показывать один общий список, и ему никогда не нужно отличать отсутствующий источник от одного из уровней. Кадр для файла отправляется только тогда, когда его набор отличается от того, о котором этому клиенту сообщили в последний раз, поэтому запрос, повторно вычисляющий те же замечания, ничего не отправляет; первый кадр файла и кадр, опустошающий набор файла, считаются отличиями и отправляются всегда.
Просьба остановиться, обращённая к самому процессу, действует на демон на тех же условиях. Прерывание из терминала или запрос на завершение от супервизора или среды выполнения контейнеров начинает то же завершение, что и aggrega/shutdown: выполняющиеся запросы завершаются, новые запросы отклоняются, затем демон завершает работу. Второй такой запрос немедленно завершает процесс. Клиент, запускающий демон, может остановить его любым из способов, и клиент, останавливающий его по протоколу, и клиент, посылающий ему сигнал, получают одно и то же завершение.
Проверка в реальном времени
При каждом aggrega/validate демон проверяет буфер редактора по схеме документа и возвращает диагностику, указывающую на ошибочный ключ, — тот же вердикт, который дала бы сборка, но для несохранённого содержимого. Запрос без content спрашивает о файле в том виде, в каком он лежит на диске; пустой content — это пустой буфер, а не запрос файла. Файл, отправленный без содержимого, должен входить в рабочее пространство и быть доступным для чтения: файл вне рабочего пространства, файл, достигнутый по ссылке, ведущей за его пределы, или отсутствующий файл отклоняется с кодом invalid-params. Сущности каталога, Aggregates, Manifests и Releases распознаются по apiVersion и kind. Два документа, у которых такого заголовка нет, — конфигурация рабочего пространства .aggrega-config.yaml и lockfile сущности Release, названной в запросе, — распознаются вместо этого по имени файла, поэтому мусорный или искажённый ключ в любом из них тоже подчёркивается в реальном времени. Файлы, не являющиеся документами Aggrega, — шаблоны чартов Helm, файлы Compose, манифесты Kubernetes и файлы .lock других экосистем, например Cargo.lock или flake.lock, — диагностики не получают: демон никогда не сообщает о чужих файлах.
Ещё не заполненный заполнитель называется на своём ключе вместе с тем, что он принимает. Сущность каталога того вида, который aggrega validate проверяет как отдельную сущность, также читается на предмет обязательных значений, оставленных пустой строкой, тем же способом чтения, что применяет эта команда, поэтому демон называет каждый заполнитель, который команда называет для тех же байтов. Каждый заполнитель — одна запись: её message сообщает, что ключ — ещё не заполненный заполнитель, её suggest сообщает, что принимает значение, а её keyPath содержит путь ключа через точки. Запись заменяет собственную находку схемы для этого пустого значения, а все прочие находки по документу сообщаются так, как их сообщает проверка схемы. Заполнитель, который схема допускает пустым, тоже называется, хотя проверка схемы ничего о нём не сообщает, — вам встретятся capability и implements черновой сущности Recipe или FeatureRecipe. Если проверка схемы тоже отклоняет документ, каждая запись несёт код этой проверки, E0215, а если принимает — записи кода не несут: те же идентификаторы, что несёт отчёт команды для этих байтов. Запись рисуется на ключе, содержащем пустое значение, в строке, где её называет команда, — даже для ключа, собственное имя которого содержит точку, например метки component.aggrega.ai/type, где находка проверки схемы по этому ключу рисуется на объемлющем ключе, — а keyPath называет ключ полностью. Это верно независимо от того, называет ли запрос Release, поскольку на этот вопрос документ отвечает сам, а документ, которому ещё недостаёт значения, пока не тот, о котором спрашивают соглашения о публикации: этот слой для него очищается, как и для документа, форму которого отвергает схема.
Каждый запрос называет Release, о которой он, и демон не хранит собственной. Семантические проверки разрешают замыкание зависимостей этой Release и читают её lockfile ради закреплённых версий — или, для сущности каталога, читают каталоги, с которыми собирается эта Release, как описывает следующий абзац, — поэтому два запроса, называющие две Releases, получают ответ о той Release, которую назвал каждый. Между ними ничего не переносится: нет выбранной Release, которую нужно менять, и смена Release, по которой вы проверяете, — это другое значение в следующем запросе, а не то, что демону нужно велеть забыть.
Сущность каталога, названная вместе с Release, проверяется как отдельная сущность в терминах этой Release. file с сущностью Component, Feature, Recipe, FeatureRecipe или Plugin, отправленный с release, получает проверку, которую выполняет aggrega validate <path> --release <release>, над несохранённым буфером редактора: её ссылки — Component, который реализует Recipe, библиотека, на которую ссылается опора, — разрешаются через каталоги, которые конфигурация рабочего пространства задаёт этой Release, поэтому один файл может быть чистым в терминах Release, которая с ним собирается, и не пройти в терминах Release, каталоги которой не содержат того, на что он ссылается. Это тот же вердикт, который дают командная строка и инструмент validate в aggrega mcp для той же сущности при той же Release, и, как и они, проверка не обходит замыкание и не читает lockfile. Блокирующая находка — одна запись об ошибке в собственных словах проверки и с её кодами, нарисованная на ключе, который она называет в сущности, а если не называет никакого — на ключе kind: сущности, как описывает Что содержит запись диагностики, — если только сборка уже не сообщает об этой ошибке в файле: тогда единственным сообщением будет запись сборки; предупреждение, которое проверка выдаёт при чтении каталога, — запись-предупреждение перед ней; чистая проверка над каталогами, которые все существуют, не даёт ни одной записи. Нарушенное утверждение — вызывающее fail в Recipe или в реализуемом ею Component — здесь не блокирующая находка, а запись-предупреждение в словах проверки и с её кодами, завершённая фразой A Release must satisfy this assertion before a build of it can pass. и нарисованная там, где была бы блокирующая находка: утверждение Recipe — на собственном ключе этого утверждения под assertions, утверждение Component — на ключе kind: сущности Recipe. Как и блокирующая находка, она уступает записи сборки, сообщающей о той же ошибке в файле. Проверка строит сущность на заполнителях и значениях схемы по умолчанию, а не на значениях, которые задаёт Release, поэтому не может отличить утверждение, ждущее Release, от сломанного и оставляет вердикт сборке, которая сообщает о том же утверждении как об ошибке (нарушенное утверждение — предупреждение). Каталог, который конфигурация рабочего пространства перечисляет для Release и который не является каталогом — например, там ничего не существует, — останавливает проверку: файл получает одну запись об ошибке вместо вердикта проверки — отказ, который любая команда даёт этому каталогу, с указанием записи, файла конфигурации и строки, где она перечислена, и настройки (Откуда читаются локальные сущности). На release, не называющий никакого файла или называющий каталог, ответ даётся в файле фразой, с которой его отклоняет командная строка, а не проверкой в терминах рабочего пространства. То, чего не может заменить сборка одной сущности, оценивается так же, как в командной строке, а то, что командная строка откладывает или не проверяет, здесь не даёт записи — см. что не проверяет корректность отдельной сущности и, для Recipe, шаблон которой читает значение, доставляемое только ребром топологии или прикреплёнными учётными данными, корректность отдельной сущности. Собственная Aggregate сущности Release, Manifest, Release и библиотека по одной не проверяются, поскольку проверка отдельной сущности не принимает эти виды; для них остаются описанные выше проверки замыкания. Буфер с содержимым Workload читается как YAML, не являющийся документом Aggrega, поскольку это содержимое пишется внутри поля workload: сущности Recipe или FeatureRecipe и проверяется там, где находится; командная строка и инструмент validate, получив файл Workload по пути, проверяют его форму самостоятельно.
Указывать сущность Release необязательно, и ответ сообщает, какой из двух вариантов вы запросили. Укажите её — и получите всё описанное выше. Не указывайте — и получите проверки, на которые документ отвечает сам: разбирается ли он, допустима ли его собственная форма и, для сущности каталога того вида, который проверяется как одиночная сущность, какие заполнители он ещё должен заполнить, — без разрешения Release, без обхода замыкания и без чтения lock-файла; в этом случае ответ содержит checked: "document". Если сущность Release указана, этот ключ отсутствует, потому что такой ответ является полным вердиктом метода и уточнять в нём нечего.
Читайте этот ключ, а не делайте выводы по диагностикам, потому что два ответа могут выглядеть одинаково. Корректно сформированный документ, проверенный без Release, возвращает пустой список диагностик — ровно то же, что возвращает чистый полный вердикт, поэтому checked — единственное, что отличает «ничего не так» от «ничего, для чего нужен Release, не проверялось». Из того же правила следует одно следствие: lock-файл распознаётся по его соответствию сущности Release, указанной в запросе, поэтому запрос без Release не распознаёт ни одного lock-файла и ничего о нём не сообщает.
На рабочее пространство, не содержащее ни одной сущности Release, даётся ответ, а не отказ, и именно это сохраняет работоспособность остальной части демона в нём. Именно проверка заполняет кэш разбора, который читают все остальные файловые операции, поэтому репозиторий, содержащий только каталог, заготовка с единственной сущностью Aggregate или временный каталог всё равно получают подсказки при наведении, автодополнение, переход к определению, ссылки, реализации и кэшированные диагностики. Отказ лишил бы их всего этого — именно в тех рабочих пространствах, где клиенту нечего указать в качестве Release.
Что содержит запись диагностики
Каждая запись указывает свою позицию с помощью line и column, обе отсчитываются с 1 в кодировке позиций, согласованной при рукопожатии, и добавляет end_line и end_column, когда охватывает целый токен. message — текст, который клиент показывает пользователю, severity задаёт его уровень, а source называет слой демона, который его выдал, как описано выше.
Слои отвечают на разные вопросы об одном файле, поэтому записи от каждого из них могут стоять на одной строке, не дублируя друг друга: одна говорит, что развёртывание некорректно, другая — что сущность непригодна для публикации. Клиент, показывающий их одним списком, сообщил бы об одной проблеме дважды, и разделяет их именно чтение source.
Расположение записи зависит от того, о чём она, а не от того, какой слой её выдал. Замечание о том, что написал автор, располагается на ключе, под которым он это написал, поэтому редактор отображает его там, где нужна правка. Замечание о форме развёрнутой топологии называет компонент и ключ доставки, а не строку — это координаты в развёрнутой топологии, а не в документе, — поэтому оно отображается на ключе kind: документа и называет свои координаты в сообщении. Оба вида попадают в слой aggrega-build, потому что сборка выдаёт оба. Отказ, выданный сборкой во время рендеринга, тоже попадает в этот слой — на документ, на который указывает сам отказ: Workload, не удовлетворяющий своим проверкам, — на ключ workload его сущности Recipe, неудачное утверждение сущности Recipe — на собственный ключ этого утверждения, запись, которую отвергает композиция графа, — на ключ, под которым её написала сущность Release или Aggregate, а каждое замечание отказа, объединяющего несколько замечаний, — на свой документ и ключ; а если отказ не указывает ни на какой документ — на ключ kind: сущности Aggregate; это описано в разделе Отказ, выданный во время рендеринга. Поэтому клиент размещает каждую запись по её собственным line и column и никогда не выводит позицию из слоя.
Замечание, не называющее ни одного ключа, который есть в документе, отображается на ключе, называющем документ. Замечание, которое собственные проверки документа выдают о его содержимом, замечание проверки одиночной сущности, а также предупреждение или отказ, выданные сборкой, отображаются на ключе, который они называют; если они не называют ни одного ключа или называют ключ, которого нет в документе, они отображаются на ключе kind: документа или на его metadata.name, если kind: не объявлен, и в начале файла — только если документ не объявляет ни того, ни другого или не разбирается. Документ часто начинается с комментария — каждый файл каталога содержит заголовок с лицензией, — и запись, отображённая на его первой строке, оказалась бы на этом комментарии и читалась бы как ошибка в нём, тогда как идентичность документа — это строка, которую написал его автор. Запись о чём-то, кроме содержимого документа, размещается в начале файла: запись Dependencies: о зависимостях Release, этап, остановившийся, ничего не назвав в документе, рассогласованный lock-файл, ссылка, от которой рендеринг вынужден был отказаться, Release, который не загрузился, — а также запись aggrega-lint, правило которой не вычислило строку. Там, где позиция указывается, а не отображается, у замечания без ключа её по-прежнему нет: ответ с ошибкой для отказа, не называющего ключа, содержит в своём data только документ.
На каком документе публикуется запись, следует из того же правила. Проверка с указанием Release отвечает о сущности Aggregate этого Release, о самой сущности Release, о документе каждого модуля, который импортирует Aggregate, и о сущности Manifest, которую называет Release. Замечание, расположенное в Release, — отказ записи, которую Release пишет на одном из соединений компонента, задаваемого им размера этого соединения, вложения, которое он там заполняет или задаёт по размеру, соединения, которое он связывает, сущности Feature, которую только Release присоединяет к компоненту или к границе, или infra, которую он задаёт вложению, — публикуется при проверке документа Release, на ключе в Release, который его написал, и на Aggregate не публикуется вовсе. Замечание, расположенное в собственном документе модуля, — отказ того, что объявляет один из компонентов модуля, сокета, который связывают его вложения, его значений или значений на его собственных соединениях, — публикуется при проверке документа этого модуля, на ключе в нём, который его написал, и на Aggregate не публикуется вовсе. Замечание о таблице сопоставлений сущности Manifest — запись, сопоставляющая тип с сущностью Recipe или FeatureRecipe, которая его не реализует, запись, закрепление версии в которой не удаётся разобрать, или сопоставленный тип, цепочку extends которого невозможно проследить, — публикуется при проверке этого Manifest, на ключе записи сопоставления, к которой оно относится, и на Aggregate не публикуется вовсе; если открытый текст Manifest не содержит этой записи — записи, унаследованной через его собственный extends, или записи, удалённой несохранённой правкой, — замечание публикуется в первой строке Manifest. Все остальные замечания, выданные проверкой этого Release, публикуются на Aggregate, в том числе замечания уровня зависимостей, не называющие ни одного документа вашего рабочего пространства: отозванная ссылка или плагин, сущность Component или Feature из каталога, цепочка extends которой не разрешается или схема которой некорректна, плагин-шлюз, не совпадающий с записью доверия, экземпляр компонента, который не разрешается ни одним сопоставлением, сущность Recipe или FeatureRecipe, провайдер которой не может отрисовать объявленный ею вид входных данных, а также рекомендации о перекрытии опор схемы и сужении при расширении. Поэтому замечание о том, что написал оператор, появляется, пока открыт Release, замечание о том, что объявляет модуль, — пока открыт этот модуль, а замечание о сопоставлении — пока открыт Manifest, каким бы этапом сборки оно ни было выдано; редактор, проверяющий каждый открытый документ относительно Release, показывает там каждое из них. Release, зависимости которого вообще не удаётся разрешить, не выдаёт ни одного из этих замечаний, а неудача их разрешения — это одна запись в начале собственного документа Release и каждого другого проверяемого относительно него документа, который демон распознаёт, как описано в разделе Проверка в реальном времени, и не проверяет как одиночную сущность, — его Aggregate, его Manifest, библиотеки, другого Release, конфигурации рабочего пространства, — с префиксом Dependencies: и с собственным описанием того, что остановило разрешение. На собственном документе Release запись представляет собой только это описание. На каждом другом документе она сначала сообщает, что документ проверяется относительно этого Release, и называет Release так, как его называет запрос, — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved:, после чего следует описание, — потому что ничто в этом документе не говорит, относительно какого Release он проверялся: редактор, проверяющий каждый открытый документ относительно одного выбранного Release, ставит эту запись на документы, не имеющие к этому Release никакого отношения, и именно имя сообщает вам, что причина в выборе. Файл, который демон не распознаёт, такой записи не содержит, какой бы Release с ним ни был указан.
Ответ содержит все слои, относящиеся к файлу, независимо от того, как далеко продвинулась проверка. Ответ aggrega/validate — это всё текущее состояние файла: то, что нашла эта проверка, записи aggrega-build, опубликованные на файле сборкой, предпросмотром или запросом графа, и замечания соглашений о публикации, каждое под своим source. Проверка, остановившаяся на буфере, — который не разбирается, или документ, оболочку которого отвергает схема, — отвечает так же: она сообщает собственное замечание и оставляет все записи сборки на файле, потому что ничего не узнала о сборке. Поэтому клиент может заменять то, что хранит для файла, слой за слоем, по любому ответу.
Об одной ошибке сообщается один раз. Собственная проверка документа и сборка могут найти в нём одну и ту же ошибку: проверка отдельной сущности отрисовывает сущность Recipe, которую отрисовывает и сборка, проверка компонует граф, который компонует сборка, а сущность Release, зависимости которой не разрешаются, не проходит ни то, ни другое. Пока сборка сообщает о такой ошибке в документе, проверка этого документа не сообщает о ней повторно: запись aggrega, называющая то же условие (тот же code), что и отказ сборки в том же документе, и расположенная в том же диапазоне или ни на каком собственном ключе (там, где отображается запись, не называющая ключа, или в начале файла), исключается из каждого ответа и каждой публикации для этого документа, и отчёт сборки остаётся единственным. Отчёт сборки — это запись отказа на слое aggrega-build; либо, для запросов aggrega/build, aggrega/buildPreview или aggrega/irGraph, отклонённых с кодом 1004 из-за того, что зависимость не разрешается, сам этот ответ (который ничем не публикуется) в документе, указанном в его поле data.file, иначе в его поле data.lockfile, иначе в сущности Release, названной в запросе; при этом учитывается последний такой ответ для данной сущности Release. Проверка сохраняет то, что обнаружила: как только ни одна сборка больше не сообщает об ошибке (следующий запуск публикует слой без неё, следующий ответ сборки, предпросмотра или графа для этой сущности Release оказывается любым другим или подключается клиент, которому не отвечали таким кодом 1004), о собственной записи документа снова сообщается, а там, где сборка не запускалась, ничего не исключается. Запись aggrega, расположенная на ключе, на котором нет ни одного отказа сборки, остаётся, даже если называет то же условие, потому что она может быть второй ошибкой того же рода, о которой сборка не сообщила.
code — стабильный, пригодный для машинного сопоставления код того, о чём сообщает запись, так что клиент может ветвиться по нему, не сопоставляя текст сообщения. Один ключ несёт код, кто бы его ни присвоил, а source сообщает, какого рода код у вас в руках, потому что слои называют вещи из разных словарей.
- В записи
aggrega— находке об авторских документах — код представляет собой строку, под которой зарегистрировано условие: объявляющий пакет, а затем правило в kebab-case. Это то же значение, которое потребитель на Go читает с помощьюCodeOf; его форма и сопоставляемая поверхность описаны в справочнике по сигнальным ошибкам. - В записи
aggrega-build— предупреждении, выданном сборкой, — код таков, какой присвоило место его выдачи, и этот слой несёт предупреждения из двух разных словарей, потому что сборка выдаёт предупреждения о двух разных родах вещей. Предупреждение о форме развёрнутой топологии несёт код класса, напримерunsupported-field, присвоенный там, где оно выдано, будь то плагин отрисовки или сама отрисовка; код класса называет класс предупреждений, а не зарегистрированное условие, поэтому строки в справочнике сигнальных ошибок у него нет, а справочник по предупреждениям описывает классunsupported-fieldи флаг, который его заглушает. Предупреждение об авторских документах — имя, отличающееся одной правкой от объявленного, параметр, который ничто не читает, — несёт строку, под которой зарегистрировано его условие, в той же форме, что и записьaggrega, и со строкой в справочнике сигнальных ошибок. В любом случае код называет, что представляет собой находка, а не кто её обнаружил, так что один класс доходит до вас под одним кодом, сколько бы мест его ни выдавали, и именно чтение кода, а не слоя, говорит вам, какой из двух родов у вас в руках. Отказ, на котором сборка остановилась при отрисовке, — единственная запись здесь, которая не является предупреждением, и она тем же образом несёт строку, под которой зарегистрировано её условие. - В записи
aggrega-lint— находке, связанной с соглашениями о публикации, — код является идентичностью находки: идентичностью правила, которое её породило, либо, для находки, не называющей правила (её может сообщить ваш собственный линтер под собственным кодом), этим кодом. Это идентификатор, которыйaggrega lintвыводит в строке находки после короткого кода, если он есть, и значение, котороеaggrega lint --output jsonпередаёт для той же находки какruleIdили какcodeдля находки, не называющей правила. Одна находка сохраняет одну идентичность на всех поверхностях, поэтому клиент, который группирует или подавляет правило в редакторе, группирует и подавляет то же правило в терминале. Каждое правило набора правил линтера публикации, объявленного Aggrega, зарегистрировано как условие под этой идентичностью, поэтому оно указано в таблице всех условий под коротким кодом, которыйaggrega lintвыводит в начале строки той же находки и которыйaggrega lint --output jsonпередаёт в ней какshortCode. Правило вашего собственного линтера, которое Aggrega не объявляет, не называет зарегистрированного условия, как и находка, не называющая правила, даже если её собственный код совпадает с идентичностью правила, объявленного Aggrega, поэтому ни то, ни другое там не указано. Правила описаны в описании командыaggrega lintв справочнике.
Каким бы ни был слой, ключ отвечает на один вопрос — что это такое, в терминах, которые может сопоставить машина, — так что расширение редактора, которое подсвечивает, группирует или подавляет один класс находок, опирается на код и продолжает работать, когда меняется формулировка сообщения.
Обратите внимание, какой объект что несёт: в записи диагностики это строка, отличная от числового code в конверте ошибки JSON-RPC, описанного ниже в разделе Коды ошибок. Ответ несёт одно или другое, но никогда оба в одном месте.
Ключ опускается, когда ничто из породившего запись не присвоило кода, и такой случай есть у каждого рода. Буфер, который не прочитает ни один парсер YAML, сообщает собственный текст парсера без кода, потому что за ним не стоит ни одно собственное условие Aggrega; стадия, которая сообщает о сбое, не называя условия, также не имеет кода; а предупреждение, выдавший которое не присвоил кода, приходит без него. Поэтому считайте code необязательным, так же как end_line и end_column, и ветвитесь по нему, только когда он присутствует. Код — это то, что сообщает диагностика, и никогда не то, что её выбирает: ни один запрос не принимает код, и записав его обратно в собственный код, вы получите строку, а не способ сопоставления.
Идентификатор, по которому сопоставляет программа, и тот, который называет человек
Условие несёт два идентификатора, и они предназначены для двух разных читателей. code — тот, что описан выше: квалифицированный и через дефисы, так что программа, ветвящаяся по нему, читается по смыслу. shortCode — это буква E и четыре цифры, например E0164, и именно его человек может произнести вслух, ввести в поле поиска или вставить в issue. Оба называют одно и то же условие, и ни один не является сокращением другого.
Какой из них использовать, зависит от того, кто читает. Сопоставляйте по code в своём расширении; показывайте автору shortCode. Расширение, показывающее только code, оставляет читателя с идентификатором, предназначенным для программы, а расширение, сопоставляющее по shortCode, сопоставляет по номеру, который ничего не говорит об условии. Именно поэтому передаются оба, а не один.
codeDescription — это место, где опубликовано условие; он передаётся как { "href": … } — собственная структура протокола для ссылки, которую можно открыть, чтобы узнать больше о диагностике. Редактор, поддерживающий протокол, превращает её в элемент «подробнее», не зная ничего об Aggrega, и ни одному клиенту не нужна копия пояснений. Адрес ведёт к опубликованному списку всех условий, где запись для shortCode называет условие и ведёт дальше к пошаговому описанию исправления в документе.
Самого текста пояснения в записи нет, и это сделано намеренно. Диагностика выдаётся при каждой правке, поэтому пояснение, передаваемое с каждой, публиковало бы одни и те же абзацы при каждом нажатии клавиши читателю, который обычно их уже прочитал. Клиент, которому нужен текст, запрашивает его один раз с помощью aggrega/explainError ниже; клиенту, который может перейти по ссылке, не нужно ни то ни другое.
Оба ключа присутствуют ровно тогда, когда запись называет зарегистрированное условие, и в остальных случаях отсутствуют вместе. Это определяется тем, что стоит за записью, а не тем, какой слой её опубликовал, поэтому смотрите на ключи, а не на слой:
- Запись, называющая зарегистрированное условие, несёт все три.
shortCodeразрешается, и ссылка ведёт к списку, в котором он разрешается. - Запись, код которой называет класс, несёт только
code. Класс предупреждения рендеринга и идентичность находки о соглашениях от вашего собственного линтера — правила, которое Aggrega не объявляет, или кода, который несёт находка, не называющая правила, — это настоящие идентификаторы, по которым можно группировать и подавлять, но ни один из них не является зарегистрированным условием, поэтому нет номера, который можно назвать, и по адресу нет ничего, что бы их описывало. Ссылка, отправленная всё равно, открывала бы страницу не о проблеме читателя, поэтому она не отправляется. Это обычная форма на слоеaggrega-build, хотя предупреждение сборки, которое всё же называет зарегистрированное условие, несёт все три, как и любое другое. На слоеaggrega-lintобычная форма — полный набор: правило из набора правил линтера публикации, который объявляет Aggrega, является зарегистрированным условием, поэтому его находка несёт тот жеshortCode, которыйaggrega lintвыводит в начале строки находки, и ссылку рядом с ним. - Запись, которая ничего не называет, не несёт никакого идентификатора.
Таким образом, три случая различимы по одним только ключам: отсутствие code означает, что называть нечего; code без shortCode рядом означает идентификатор, который дальше не разрешается; а полный набор означает идентификатор, о котором есть где прочитать. Считайте два новых ключа необязательными так же, как code, и предлагайте читателю что-либо открыть только там, где пришёл codeDescription.
Раскрытие кода, переданного в диагностике
aggrega/explainError превращает любой из двух идентификаторов условия в то, что компилятор объявляет о нём, и в опубликованные записи, объясняющие исправление в документе. Это то же раскрытие, которое aggrega explain выполняет в терминале, а инструмент explain-error — для ассистента, и все три отвечают из одного места, поэтому код, раскрытый здесь, и тот же код, раскрытый там, дают один ответ, а не три, которые случайно совпадают.
code обязателен и принимает любой из идентификаторов — shortCode, переданный в диагностике, или code рядом с ним, — поскольку клиент, у которого есть один из них, не может получить другой, не спросив. Пустое значение отклоняется с указанием того, что следует отправить.
Ответ всегда содержит shortCode, code и message: два идентификатора условия и предложение, с которого начинается каждая диагностика, называющая его. Они объявлены внутри двоичного файла, поэтому поступают без сети и без кеша, что и позволяет ответить даже для рабочего пространства без документации. reference — тот же адрес, который передаёт codeDescription диагностики, для клиента, который предпочитает отправить читателя к документации, а не отображать текст.
entries содержит опубликованное пошаговое описание: каждая запись — это открывающий её heading и body под ним, в том порядке, в каком сама документация связывает их с условием. Ключ опускается, если пошаговое описание добавить не удалось, и тогда note объясняет причину: опубликованная страница пока не документирует запись для этого условия, или это рабочее пространство не может прочитать документацию — на машине нет её копии или есть только та, которую отклоняет проверка подписи рабочего пространства. В любом случае условие над ним остаётся в силе — ответ не является сбоем, и клиент показывает то, что пришло, и примечание рядом. entries и note никогда не приходят вместе.
Код, который ничем не разрешается, отклоняется, а не получает в ответ условие со всеми пустыми полями, и каждый отказ говорит, какой это случай: код, под которым не зарегистрировано ни одно условие; номер, который когда-то называл условие и больше никогда не назовёт другое; или код, который этот двоичный файл не объявляет, когда опубликованный список вообще не удалось прочитать, — последний случай оставляет открытыми оба способа исправления, поскольку список, опубликованный для другой версии, может называть условие, которое этот двоичный файл не объявляет.
Документация читается из пакета, закешированного для рабочего пространства, указанного в запросе, и загружается при первом использовании, если отсутствует — это единственное, ради чего этот запрос обращается к реестру; см. Обращение к реестру и запись. В рабочее пространство ничего не записывается. Никакая валидация его не запускает: раскрытие происходит потому, что его запросили, поэтому к реестру никогда не обращаются во время валидации или просмотра документа.
Соглашения публикации: по запросу и при каждом изменении
Демон отвечает на два разных вопроса о сущности каталога, и это те же вопросы, на которые в терминале отвечают aggrega validate и aggrega lint: корректно ли развёртывание и пригодна ли к публикации сущность по соглашениям каталога. Валидация всегда отвечает на первый вопрос. На второй она отвечает, только когда вы об этом просите.
aggrega/lint запрашивает это напрямую. Передайте entity для одной сущности каталога, release для каждой сущности, которой достигает замыкание зависимостей этой сущности Release, или ни то ни другое, чтобы проверить все сущности в настроенных каталоговых директориях, — это три области действия команды. Передача одновременно entity и release называет два разных предмета и отклоняется. Ответ содержит checked — число документов сущностей, охваченных запуском, и files — находки, сгруппированные по документу, к которому они относятся, и упорядоченные по пути; записи каждого файла имеют форму диагностики, описанную выше. halted сообщает, отказывает ли собственный вердикт запуска в публикации.
Если не передать ни то ни другое, весь каталог проверяется так же, как это делает aggrega lint без аргумента. Рабочее пространство, конфигурация которого не задаёт собственных каталоговых директорий для Release, проверяется один раз по его собственным директориям, и ответ имеет описанный выше вид. Рабочее пространство, которое называет Releases в workspace.releases, проверяется один раз для каждой сущности Release в нём — по директориям, которые читает эта сущность Release, и никогда по всем сразу, — так что варианты каталога, хранящиеся рядом, по одному на Release, проверяются каждый в терминах той сущности Release, которая их читает. Тогда ответ также содержит passes, по одной записи на проход: releases — Releases, для которых он выполнялся, каждая относительно корня рабочего пространства, причём Releases, читающие одни и те же директории, делят одну запись; catalogDirs — прочитанные директории, записанные так же, как files записывает путь, и пустые для сущности Release, которая ничего не читает, о чём сообщается, а не приводит к сбою остальных; а также собственные счётчики прохода и его files, которые и сообщают, для какой сущности Release найдена находка. checked, счётчики и files вокруг них охватывают все проходы вместе, так что клиент, не читающий passes, всё равно получает весь запуск. Запуск, в котором ни у одного прохода нет директории для чтения, отклоняется, а не выдаётся за чистый каталог.
Задайте prePublish вместе с entity, чтобы сравнить эту сущность с её ранее опубликованной версией и классифицировать предлагаемое повышение версии относительно неё. Это единственный режим здесь, который обращается к реестру, и он выполняется потому, что запрос его назвал: операцию, обращающуюся вовне, допускает то, что её запросил вызывающий. Он имеет смысл только с entity, поэтому prePublish без сущности отклоняется.
aggrega/lint ничего не публикует в сеанс. Он отвечает о переданном ему предмете, а запись его находок в список проблем редактора заменила бы то, что валидация опубликовала для файлов, которые запрос не охватывал. Ни в одном режиме ничего не записывается на диск.
serve.lint_on_validate применяет те же правила при каждой валидации и выключен, пока вы его не включите. Включите его в .aggrega-config.yaml в том рабочем пространстве, о сущностях которого вы хотите получать рекомендации:
serve: lint_on_validate: trueФлага для него нет, потому что вопрос, на который он отвечает, касается собственного содержимого рабочего пространства, а задаёт этот вопрос тот, кто создаёт рабочее пространство, а не тот, кто запустил демон. Когда он включён, валидация сущности каталога также публикует находки по соглашениям под источником aggrega-lint; когда выключен — по умолчанию, — валидация сообщает только о слоях корректности, и ни одна находка по соглашениям до вас не доходит. Сеанс редактора ничего не говорит о том, пригодна ли сущность к публикации, пока вы не запросите этот слой.
На этом слое три вещи верны при любом значении ключа. Выполняется только режим, читающий локальное содержимое, поэтому реестр не опрашивается, ничего не загружается и ничего не записывается; сравнение перед публикацией достигается отправкой aggrega/lint с prePublish, но никогда валидацией, потому что проверка, выполняемая при каждом изменении, — это именно то место, где к реестру обращаться нельзя. Правила вычисляются по буферу, переданному в запросе, а не по файлу на диске, так что исправленное вами имя перестаёт попадать в отчёт ещё до сохранения. И находки носят рекомендательный характер: документ, к которому они относятся, всё равно проходит валидацию, а его Release по-прежнему разрешается и рендерится, — так что слой добавляется, но никогда не приводит к отказу.
Ключ управляет этим слоем и ничем другим. aggrega/lint отвечает на любой запрос при любом значении, потому что вызывающий, отправивший его, запросил проверку по имени.
Проверяются только виды сущностей, которые публикуются в каталог, потому что именно о них соглашения. Документы, не являющиеся содержимым каталога, — среди них Aggregate и Release, — пропускаются, как и YAML, который вовсе не является документом Aggrega. Именно это не даёт сеансу шуметь о документах, в которых автор проводит большую часть времени.
Как записывается путь в ответе
Когда ответ называет документ, который демон нашёл для вас, способ записи этого пути определяет одно правило: относительно корня рабочего пространства, если документ находится внутри него, и абсолютный путь, если нет. Это касается file в идентификаторе сущности, file в определении сущности и file, по которому сгруппирована каждая группа в ответе lint. Обе записи — пути, которые можно открыть: первую относительно указанного вами корня, вторую как есть, — и ни одна из них никогда не остаётся пустой из-за того, где лежит документ.
Вторая половина правила нужна для настроенного каталога. Рабочее пространство может указывать на каталоги в любом месте машины, и документ в одном из них так же реален, как документ под корнем. Его называет абсолютный путь, и это та же запись, которую aggrega lint и останавливающая диагностика выводят для этого файла в терминале, — так что у одного файла одно имя, к какой бы поверхности вы ни обратились. Чего вы не получите, так это пути, поднимающегося выше корня: он называл бы разные файлы в зависимости от того, откуда его читают.
Какую запись вы получили, видно по значению: всё, что ваша платформа считает абсолютным путём, — вторая форма, а всё остальное задано относительно корня рабочего пространства. Проверять это, чтобы открыть файл, не нужно: работает и присоединение относительного пути к корню, и открытие абсолютного как есть, — но клиент, группирующий по документам рабочего пространства, может различить их, не спрашивая.
Чего это правило не касается. Путь, который вы отправляете, подчиняется контракту самого запроса, изложенному выше вместе с запросом и обычно более строгому: место назначения отклоняется, если оно не задано относительно корня рабочего пространства и не разрешается внутри него, включая ссылки. Уведомление aggrega/publishDiagnostics всегда передаёт свой file в абсолютном виде, внутри корня и вне его, потому что это значение — идентификатор, который вы сопоставляете со своими открытыми документами, а не координата в рабочем пространстве: редактор разрешает его как путь файловой системы. aggrega/releaseCandidates и aggrega/activeRelease называют каждый Release и lock-файл по абсолютному пути, как сказано в их описаниях выше. А aggrega/irGraph передаёт скомпилированный граф в том виде, в каком его записал компилятор, — скрывая только значения, объявленные автором конфиденциальными, — поэтому любой путь внутри него — тот, что записал компилятор, в форме, которую задаёт контракт самого графа, а не составленный для вас этим протоколом.
Какие записи принимает отправляемый вами параметр
Какие записи принимает параметр, определяет то, что называет путь, а не то, какой метод его передаёт. Описание каждого запроса выше излагает контракт для его параметров; далее показано различие между ними и почему это различие, а не несогласованность, которую нужно запоминать для каждого метода.
Параметр, называющий документ, который у вас уже есть, можно записать тремя способами: относительно корня рабочего пространства, абсолютно или как адрес file://, который клиент языкового сервера отправляет для открытого документа. Это file или uri в aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint и aggrega/connectionAtPosition. Все три называют один документ, и ответ на них одинаков, потому что каждая запись приводится к одной канонической на границе запроса, прежде чем её что-либо прочитает, — так что документ, проверенный по пути, находится и по адресу, и наоборот, и выбор записи ничего не меняет в ответе. Адрес читается как путь, который он называет, с декодированными процентными экранированиями, если его authority пуст или равен localhost; адрес, называющий другую машину, читается как сетевой ресурс этой машины в системе, которая так открывает там документ, а в остальных случаях не называет ничего, что демон может открыть. Адрес, содержащий также query, fragment, учётные данные или порт, тоже не называет ничего, что демон может открыть. Значение, не начинающееся с file:// в любом регистре букв, никогда не читается как адрес, а отказ «файл не проверен» называет отправленное вами значение, какой бы ни была запись. Из них aggrega/insertionPoint и aggrega/connectionAtPosition — два запроса, которые читают документ с диска, если у вас нет его копии, и отвечают только для документа внутри рабочего пространства: документ вне корня — как записано или через ссылку, ведущую наружу, к файлу или к каталогу по пути, — отклоняется, какой бы из трёх записей он ни был назван, а документ внутри корня обслуживается во всех трёх. Остальные восемь ничего не читают с диска по названному пути — aggrega/validate берёт байты документа из content, а остальные отвечают на основе проверенного, — поэтому они отвечают для документа, где бы он у вас ни был, внутри рабочего пространства или нет, и ни одна названная ими ссылка не разыменовывается для чтения файла. Параметр, называющий документ, выбранный вами вне рабочего пространства, — тот же случай по той же причине: source в aggrega/import читается там, где он действительно находится, как сказано в его описании. Оба — исключения из границы рабочего пространства по классу: документ, который держит открытым клиент, и файл, выбранный человеком, — и в разделе Граница рабочего пространства объяснено, почему каждое из них является исключением.
Параметр, по которому демон должен найти документ внутри рабочего пространства, принимает только путь относительно рабочего пространства. Главный из них — release: в aggrega/irGraph и по тому же контракту везде, где он встречается; абсолютное значение отклоняется ошибкой invalid-params, которая излагает контракт и затем называет конкретную неисправность. Запросы, записывающие внутрь рабочего пространства, подчиняют свои места назначения тому же контракту, как сказано в описании каждого. Затем каждый такой путь оценивается по тому, куда он ведёт, по одному правилу, читает его запрос или записывает — по определению «внутри», данному в разделе Граница рабочего пространства, — и путь, ведущий наружу, отклоняется собственной ошибкой запроса, цитирующей значение в том виде, в каком вы его отправили, без чтения и записи: одинаково ссылка на файл снаружи и ссылка на каталог по пути, а также ещё не созданный путь под связанным каталогом, ведущим наружу, который отклоняется из-за ссылки, а не записывается или ищется снаружи и объявляется отсутствующим. Это касается каждого пути, который запрос называет для чтения демоном, — release везде, где он встречается, entity в aggrega/lint, а также entity, plugin, file и from в запросах публикации, — так что запрос не может прочитать через ссылку файл, который собственные списки рабочего пространства не включают, и каждого места назначения: каталогов, в которые пишут генерация, импорт и сборка, сущности, рядом с которой aggrega/pin пишет свою блокировку, файла сущности и модуля, которые читает и перезаписывает aggrega/pluginSync, и документа, который редактирует aggrega/editDocument. Единственное исключение — release, называющий Release, указанный в конфигурации вашего рабочего пространства, как сказано в описании aggrega/irGraph.
Они различаются, потому что различаются ошибки. Параметр, называющий документ, который у вас уже есть, оставляет лишь один вопрос — какой документ, — поэтому приведение вашей записи к канонической ничего не теряет, и принятие любой из них вам тоже ничего не стоит. Параметр, выбирающий документ из рабочего пространства, в другом положении: в библиотеках путей, которые, вероятно, использует клиент, присоединение абсолютного значения к корню даёт это абсолютное значение, а не ошибку. Поэтому молча исправленное значение заставило бы демон читать — и сообщать о находках — путь, которого в рабочем пространстве никогда не было, и вам сообщили бы о несуществующем файле. Ответ — отказ, а не исправление, потому что демон, исправляющий такое значение, внушил бы каждому отправляющему его клиенту, что контракт необязателен.
Как адресуется сущность
Каждая сущность, которую называет ответ, адресуется одинаково: kind, name и file. Для всего, что нужно отобразить, выполняйте соединение по этим трём ключам с aggrega/catalogIndex: именно эта поверхность несёт полный описательный набор сущности — apiVersion, description и labels, — поэтому ответ, которому нужно лишь назвать сущность, сообщает три адресующих ключа и оставляет описание одному месту. Поиск по имени, такой как aggrega/entityDefinition, повторяет те немногие описательные поля, о которых его собственный ответ; индекс остаётся поверхностью для соединения, когда вам нужен весь набор.
Там, где ответ может называть сущности из нескольких мест, каждая идентичность несёт origin рядом с этими тремя ключами. Так делают и aggrega/catalogIndex, и aggrega/attachCandidates, потому что их сущности берутся из документов рабочего пространства и из настроенных каталогов. Ответ, опирающийся только на одно место, сообщает три ключа без origin, поскольку ключ с единственным возможным значением ничего не сообщает: каждая сущность, которую называет такой ответ, — документ рабочего пространства, а его file — путь относительно рабочего пространства, который можно открыть. Поэтому читайте origin там, где он присутствует, а не требуйте его везде; соединение в любом случае выполняется по трём ключам.
origin относится к ответу, который перечисляет сущности, где различать совокупности — задача читателя. Ответ по имени, такой как aggrega/entityDefinition, его не несёт: он называет ту единственную сущность, в которую разрешилось имя, так что разделять нечего. Его собственный пункт выше говорит, когда его file пуст; не толкуйте эту пустоту через значения origin ниже, которые описывают перечисление.
origin говорит, откуда демон прочитал сущность, и именно он делает file читаемым.
workspace— документ Aggrega в корне рабочего пространства.file— его путь относительно этого корня, который ваш клиент может открыть.catalog— сущность, разрешённая из настроенных каталогов.fileв этом перечислении пуст, аnameи есть весь адрес. Он пуст потому, что перечисление сообщает то, что перебрал поиск по каталогу, а это идентичность, а не документ, так что у записи нет пути для сообщения — а не путь, скрытый из-за того, где он расположен. Запроситеaggrega/entityDefinitionдля того же имени, когда вам нужен документ: этот запрос разрешает сущность и сообщает еёfileпо правилу выше, так что каталог вне корня рабочего пространства назван там своим абсолютным путём.name— координата, которую в любом случае используют сущность Aggregate, сущность Recipe и поиск по каталогу.
Читайте оба поля вместе, а не проверяйте только file. Пустой file сам по себе не скажет, нет ли у сущности пути в рабочем пространстве или путь просто не был сообщён; origin отвечает на это напрямую.
Если сущность Feature достижима обоими путями — корень рабочего пространства сам является одним из настроенных каталогов, что распространено, — она сообщается один раз, как документ рабочего пространства, потому что это та копия, файл которой можно открыть.
Что сообщает ответ о кандидатах на прикрепление
aggrega/attachCandidates отвечает на один вопрос — какие Features допускает данный набор меток — и предлагает три способа указать, какой набор меток имеется в виду. Передайте ровно одну координату; запрос с двумя координатами или без них отклоняется, а не ранжируется.
{node} адресует документ рабочего пространства по его metadata.name и больше ничего не требует. Сопоставление выполняется по меткам, которые документ объявляет в metadata.labels, и ответ сообщает labelSource: "declared".
{graphNode, release} адресует узел скомпилированного графа. graphNode — это идентификатор, под которым граф хранит узел, тот же, что вы читаете из aggrega/irGraph, включая квалифицированную форму, которую имеет узел, внесённый вложенным агрегатом. release — путь относительно корня рабочего пространства, называющий сущность Release, граф которой нужно построить, — то же значение, что принимает aggrega/irGraph. Сопоставление выполняется по окончательным меткам узла, и ответ сообщает labelSource: "resolved".
{labels} несёт сам набор меток и ничего не адресует. Это форма, лежащая в основе двух других: сопоставление является функцией набора меток и предлагаемых Features, поэтому клиенту, у которого уже есть набор меток, нечего называть и нечего ждать. Передайте JSON-объект пар меток; ответ сообщает labelSource: "supplied" и пустой node, поскольку этот запрос ничего не адресовал. Пустой объект является координатой — он спрашивает об узле без меток, — тогда как полное отсутствие ключа или передача null ничего не адресует и отклоняется.
Две именные координаты разделены, потому что их пространства идентификаторов пересекаются. Идентификатор узла графа и metadata.name документа могут быть одной и той же строкой, называя разные вещи, поэтому один параметр, несущий и то и другое, был бы неоднозначен, а демон, угадывающий, какое пространство вы имели в виду, иногда уверенно отвечал бы не о том объекте. Неоднозначность устраняет именно указание того, какой вопрос вы задаёте.
labelSource сообщает, насколько далеко простирается ответ, и три значения не взаимозаменяемы. declared — сопоставление по тому, что один документ сообщает о себе, то есть то, что видно при чтении исходного кода. resolved — сопоставление по меткам, которые узел фактически получает в итоге и по которым сборка оценивает применимость, поэтому ответ resolved является утверждением о том, что решила бы сборка, а ответ declared — нет. supplied означает, что демон вообще не читал меток и сопоставил то, что вы передали; насколько надёжен такой ответ, целиком зависит от того, откуда взят ваш набор меток.
Поэтому клиенту, у которого есть граф, следует передавать {labels}, а не имя. Окончательные метки узла — это метки типа компонента, к которому он разрешается, а не документа, который случайно имеет тот же идентификатор, и прикрепление label-transform может затем дополнить, изменить или удалить их, — поэтому метки, определяющие применимость узла, не обязательно совпадают с метками, объявленными каким-либо одним документом. Клиент, отрисовывающий граф, уже получил этот набор из aggrega/irGraph; передав его обратно, он получит тот же ответ, что даёт координата {graphNode, release}, без повторного построения графа. Передавайте обратно набор, который сообщил сам демон, — метки узла из aggrega/irGraph, метки сущности из aggrega/catalogIndex, — и ваше представление о метках узла не разойдётся с представлением демона, поскольку набор не покидал его собственного ответа. Если же вы составите набор сами, вы задаёте гипотетический вопрос: на него даётся честный ответ, но он не является утверждением о каком-либо узле рабочего пространства.
Кандидаты берутся из рабочего пространства и из каталога. В рабочем пространстве, которое хранит свои Features в каталоге, а не в собственном дереве, локальных сущностей Feature нет вовсе, и все его кандидаты имеют origin: "catalog". Для узла графа оба источника читаются в терминах сущности Release этого узла: Features из каталога — это те, что объявлены в каталожных директориях, которые конфигурация рабочего пространства задаёт для этой сущности Release, а собственные документы рабочего пространства предлагаются за вычетом тех, что лежат в каталожной директории, читаемой только другими Releases. Поэтому рабочее пространство, хранящее вариант сущности Feature для каждой сущности Release, предлагает графу каждой сущности Release её собственный вариант и никогда чужой, а сущность Feature, записанная рядом с каталогами, вне какой-либо каталожной директории, предлагается для любой сущности Release. {node} и {labels} не называют сущность Release, поэтому они используют все документы рабочего пространства и собственные catalog_dirs рабочего пространства. Сущность Feature, которая вовсе не объявляет применимости, является кандидатом для любого узла — отсутствующее объявление не выдвигает требований, — а сущность, объявление которой невозможно прочитать, не является кандидатом ни для одного узла, поскольку считать нечитаемый селектор выполненным означало бы позволить опечатке расширить то, что вы предлагаете.
Неразрешаемое имя — это ошибка, а не пустой список. Эти два ответа означают разное: пустой массив candidates говорит, что к узлу нечего прикрепить, и сообщать так об опечатке в имени означало бы выдавать опечатку за окончательный ответ. В отказе называется пространство, в котором шёл поиск, поэтому вы знаете, что искать — документ рабочего пространства или узел графа. У {labels} такой опасности нет — здесь нет имени, в котором можно ошибиться, — поэтому набор меток, который ничто не допускает, возвращается успешным ответом с пустым массивом, а запрос, который демон не может прочитать, по-прежнему отклоняется до начала сопоставления.
Координате узла графа нужен lock-файл; двум другим — нет. Построение графа означает разрешение всего, что достигает сущность Release, поэтому этот путь отклоняется с ошибкой об отсутствии lock-файла, если он не был сгенерирован, и называет команду, которую нужно выполнить, — то же предварительное условие, что и у aggrega/irGraph, по той же причине. Адресация документа рабочего пространства не строит граф, а передача набора меток вообще ничего не строит, поэтому оба способа отвечают и в рабочем пространстве, которое ещё никто не подготовил.
Метод сообщает и никогда не создаёт. Метод ничего не изменяет, ничего не записывает и не создаёт прикреплений. Составление и применение любой правки — дело редактора, где находятся буфер и история отмены.
Что разрешается, зависит от координаты, и три координаты здесь не одинаковы. {node} ничего не разрешает и не обращается ни к реестру, ни к сети — кандидаты берутся из рабочего пространства и из каталожных директорий, которые уже находятся на диске. {labels} разрешает ещё меньше: он ничего не ищет, потому что искать нечего. {graphNode, release} строит граф сущности Release, поэтому разрешает замыкание зависимостей этой сущности Release так же, как aggrega/irGraph: сначала из локальных каталожных директорий и кэша артефактов, а из настроенного реестра — для сущности, которой нет ни там, ни там. Все три отвечают без сети для рабочего пространства, все сущности которого локальны; искать дальше может только координата узла графа.
Запрос о соединении
Соединение, которое проводит компонент, может нести собственные присоединения, заполняющие слоты, которые его сокет объявляет у потребляющей сущности Component, — например, учётные данные, которые компонент предъявляет тому, к чему ведёт соединение. Передайте connection вместе с {graphNode, release}, чтобы узнать, что может туда попасть: socket — это сокет зависимости, через который проведено соединение, а alias — имя, которое оно носит внутри этого сокета, оба точно так, как их написал автор. Соединение существует только в скомпилированном графе, поэтому connection вместе с node или labels отклоняется, как и соединение без сокета или без псевдонима, либо соединение, которое узел не проводит.
Ответ — это ответ для узла графа плюс слоты соединения. candidates сохраняет своё значение — сущности Features, которые могут присоединиться к самому узлу, — и добавляется slots, по одной записи на каждый слот, объявленный сокетом, в том порядке, в каком их объявляет сущность Component:
slot— имя, под которым заполняющее его присоединение записывается вfeaturesсоединения.selector,required,inject,sensitiveиdescription— слот точно в том виде, в каком сущность Component объявляет его на сокете; пусто или false там, где ничего не объявлено.selector— ограничение, по которому были сужены кандидаты, поэтому объяснить кандидата или его отсутствие можно по одному лишь ответу.candidates— сущности Features, которые могут заполнить этот слот в этом соединении. Сборка проверяет такое присоединение по двум правилам, и применяются оба: объявленная применимость сущности Feature относительно финализированных меток узла, по которой проверяется каждое присоединение узла, иselectorслота относительно собственных меток сущности Feature. Поэтому кандидаты слота всегда входят в число кандидатов узла, суженных селектором. Сущность Feature, относительно меток которой селектор не удаётся вычислить, не предлагается, потому что сборка её отклоняет, а не допускает.
Если ни один слот заполнить нельзя, slots — пустой список, а noSlotReason объясняет причину. Читайте причину, а не принимайте пустой список за «ни одна сущность Feature не подошла» — это был бы другой ответ, и именно причина позволяет их различить:
feature-created-connection— соединение провела сущность Feature из собственного блока зависимостей. Присоединение записывается только на соединении, которое проводит компонент или сущность Release, поэтому сюда ничего не попадает, что бы ни объявлял сокет.ad-hoc-socket— сокет не объявлен сущностью Component. Автор назвал его, что допустимо, а необъявленный сокет не объявляет слотов.no-slot-declared— сущность Component объявляет сокет без слотов.
noSlotReason отсутствует везде, где слот существует, а slots и noSlotReason оба отсутствуют в ответе на запрос, не называющий соединения, — поэтому запрос, не называющий соединения, получает ответ без обоих этих полей.
document принимается и здесь ничего не меняет. Слоты принадлежат сокету, а кандидаты — сущностям Features, и они одинаковы, в каком бы документе ни было записано присоединение; куда оно попадает — это ответ aggrega/attachmentContainer. Значение, отличное от aggregate или release, по-прежнему отклоняется, потому что принятое и проигнорированное значение выглядит для отправителя как учтённое.
Что сообщает ответ о кандидатах для соединения
aggrega/connectionCandidates отвечает сразу на два вопроса, и полный ответ есть только на один из них. Если читать ответ как единый отфильтрованный список, второй будет понят неверно.
Каждый сообщаемый сокет содержит targets — сущности Components рабочего пространства, объявленные метки которых удовлетворяют ограничению на метки, объявленному этим сокетом для того, что может его удовлетворить, — а также selector, по которому вычислены эти цели, флаг required, объявленный сокетом, и declaration. targets всегда является массивом, пустым, а не отсутствующим, поэтому сокет, которому ничто не удовлетворяет, всё равно сообщается как сокет, объявленный сущностью.
Половина о целях полна. Множество определяется вычислением объявленного ограничения сокета по объявленным меткам кандидата — тем же вычислением, которое выполняет сборка, поэтому то, что вы предлагаете, — это то, что то же ограничение допускает при сборке. Сокет без объявленного ограничения оставляет свои цели неограниченными и сообщает каждую сущность Component — таково значение пустого селектора в языке ограничений, а не ошибка.
Половина о сокетах открыта, и различить это позволяют declaration и adHocSocketsAccepted. Автор сущности Aggregate владеет её топологией и может подключить сокет, который каталожная сущность компонента никогда не объявляла, поэтому сокеты, объявленные сущностью, — полезный начальный набор, а не множество допустимых имён сокетов. Показывайте их как подсказки, а не как единственные варианты: средство выбора, предлагающее только объявленные сокеты, сообщало бы автору, что его свобода уже, чем на самом деле.
declarationравноdeclared, если адресуемая сущность перечисляет сокет в своёмusesSchema, иad-hoc, если нет. Это те же два значения, которые несёт ребро в графе IR, поэтому один словарь отвечает на вопрос «откуда взялся этот сокет», где бы он ни возник.adHocSocketsAcceptedсообщает, принимает ли поверхность адресуемой сущности сокет, которого нет в её собственном объявлении. Это не всегда так: собственная поверхность зависимостей сущности Component такой сокет принимает, а поверхность присоединения сущности Feature — нет, потому что присоединение участвует в топологии, объявленной присоединённой сущностью Feature, а не создаёт собственную. Нерегламентированный сокет на поверхности, которая его не принимает, сообщается без целей, потому что ни одно соединение через него не соберётся.
Указание socket в запросе ограничивает ответ этим одним сокетом, и это единственный способ спросить о сокете, который сущность не объявляет: необъявленный сокет не встречается ни в одном объявлении, которое можно перечислить. Опустите его, чтобы получить все сокеты, объявленные сущностью, в порядке их написания.
Сообщается совпадение по объявленным меткам. Сборка вычисляет ограничение сокета по финализированным меткам узла на дальнем конце ребра, а это метки типа компонента, в который разрешается этот узел, после того как своё слово скажет любое вложение label-transform, — не обязательно метки названного вами документа. Поэтому положительный ответ здесь не является обещанием того, что решит сборка, — это та же оговорка, которую aggrega/attachCandidates несёт для источника меток declared.
Метод сообщает и никогда не создаёт. Он ничего не разрешает, не обращается ни к реестру, ни к сети и ничего не записывает: он не создаёт ребро и не предлагает текст. Составление и применение правки — дело редактора, где находятся буфер и история отмены.
Для идентификаторов сущностей в targets — kind, name и file — выполняйте соединение с aggrega/catalogIndex, как описано в разделе Как адресуется сущность. Описательные поля сообщаются там и намеренно не повторяются здесь, поэтому этот ответ не содержит их второй копии, которая могла бы рассинхронизироваться. Цели — это сущности Components рабочего пространства, поэтому у каждой есть file, который можно открыть, и ни одна не несёт origin: этот ответ опирается на одно место, и соединение выполняется по трём ключам.
Что сообщает ответ attachment-container
aggrega/attachmentContainer находится между запросами кандидатов выше и точкой вставки ниже. Те говорят, что может присоединяться к узлу; этот говорит, в каком контейнере должно находиться присоединение для него и в каком документе; следующий говорит, куда в байтах этого документа помещается текст.
Запрашивайте контейнер, а не составляйте его сами. Идентификатор узла и путь объемлющей подсистемы записываются с точками между частями, а точка — допустимый символ в имени, которое вводит автор, поэтому снаружи документа невозможно отличить структурную точку от точки внутри имени. Клиент, собравший путь самостоятельно, получил бы нечто, что выглядит правильно, но адресует ключ, которого никто не писал, и последующая правка создала бы этот ключ, а не была бы отклонена. Оба пути составил компилятор, поэтому и разбирает их компилятор.
Идентификатор узла вообще не содержит следов объемлющей подсистемы. Компонент, описанный внутри subsystems.billing.subsystems.payments, имеет в графе ключ ledger — точно так же, как компонент верхнего уровня, поэтому в идентификаторе нет ничего, от чего клиент мог бы оттолкнуться, как бы аккуратно он его ни разбивал.
Ответ состоит из трёх полей.
nodeповторяет узел, к которому относится ответ, поэтому клиент с несколькими незавершёнными запросами сопоставляет каждый ответ с его вопросом, не отслеживая порядок самостоятельно.file— документ, в котором описан узел, относительно рабочего пространства. Он входит в ответ, а не является тем, что вы уже знаете: узел, добавленный импортированным модулем, описан в собственном документе этого модуля под именем, которое дал ему модуль, поэтому и файл, и последний сегмент контейнера отличаются от всего, что было названо в запросе.container— структурный путь от корня этого документа в виде списка сегментов:["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Каждый уровень объемлющей подсистемы снова находится под ключомsubsystems— именно так это записано в документе. Для компонента, который автор написал на верхнем уровне, путь будет["spec", "components", "checkout", "features"], поскольку область, в которую компилируется такой компонент, не содержится ни в одном файле.
Это список сегментов, а не склеенная строка, и в этом смысл такой формы. Склеенный путь пришлось бы снова разбивать получателю, а это та же неоднозначность, вернувшаяся одним вызовом позже. Передавайте список в aggrega/insertionPoint как его container без изменений.
Он читает структуру, а не смысл. Ответ выводится из документа, в котором описан узел, области, в которой он находится, и имени, введённого автором. Ничего не извлекается из того, как называется компонент, какой у него тип или что говорит какая-либо метка.
Он сообщает и никогда не записывает. Метод ничего не изменяет и ничего не записывает ни в один документ. Он не создаёт присоединений, не составляет текст и не применяет правки; он не решает, что может присоединяться, — это делает aggrega/attachCandidates.
Запрос, называющий узел, которого нет в графе, отклоняется, а не получает ответ. Идентификаторы узлов — это собственные ключи графа; берите их из графа, который возвращает aggrega/irGraph. Узел, добавленный импортированным модулем, имеет квалифицированный идентификатор. Узел, для которого граф не записывает документа, тоже отклоняется: место присоединения — это факт о документе, поэтому у узла без документа нет ответа, а не пустой ответ.
Он требует lock-файл по той же причине, что и aggrega/irGraph: чтобы назвать контейнер, нужно построить граф сущности Release, а граф, построенный из байтов, за которые ничто не ручается, был бы представлен точно так же, как проверенный.
Присоединение на соединении
Передайте connection рядом с {graphNode, release} — его socket, его alias и его document, — и ответ назовёт контейнер features в собственной записи этого соединения, а не узла. Здесь document обязателен, поскольку присоединение на соединении, которое провела сущность Aggregate, может находиться в любом из документов: разработчик пишет его в записи соединения в Aggregate, оператор — в записи сущности Release для этого ребра.
aggregateназывает запись соединения в документе, в котором описан узел:["spec", "components", "gateway", "uses", "models", "gpt", "features"]для компонента верхнего уровня, причём каждая объемлющая подсистема записывается уровень за уровнем, как показано выше. У соединения, проведённого сущностью Release, нет записи в Aggregate, поэтому там оно отклоняется.releaseназывает запись для ребра внутри собственной записи сущности Release для узла —["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"], — независимо от того, записывает ли Release эту запись для ребра уже сейчас. Если нет,aggrega/insertionPointсообщает ключи, которые ещё нужно записать, вmissingContainerKeys. В этом случаеfile— документ Release. Сущность Release, которая вообще не записывает запись для узла, отклоняется: размещение узла записывает оператор, и ответ этого не решает.
Соединение, проведённое сущностью Feature, отклоняется в любом документе по причине, которую выше указывает feature-created-connection. Узел, сокет и псевдоним сопоставляются точно так, как записаны, а соединение, которого узел не проводит, отклоняется, а не получает ответ с путём. Все остальные свойства, описанные выше, сохраняются без изменений: ответ — список сегментов, он читает структуру, а не смысл, и ничего не записывает.
Что сообщает ответ connection-at-position
aggrega/connectionAtPosition — шаг, предшествующий двум запросам о соединениях выше, для клиента, у которого есть место в документе, а не узел графа, — например, курсор на записи соединения. Он отвечает, какое соединение записано в этом месте, в координатах, которые принимают эти запросы, и на этом останавливается.
Ответ — одна из двух половин, но никогда не обе.
graphNodeиconnection— узел, компонент которого проводит соединение, по идентификатору, под которым он хранится в скомпилированном графе, и соединение по егоsocketиalias; при этомdocumentназывает документ, в котором была прочитана позиция:aggregateдля Aggregate или импортируемого им модуля,releaseдля Release. ПередайтеgraphNode, тот жеreleaseиconnectionвaggrega/attachCandidates, чтобы получить слоты, объявленные сокетом соединения, и вaggrega/attachmentContainer, чтобы узнать, куда помещается прикрепление к нему; названный им контейнер находится внутри той самой записи, на которую пришлась позиция.noConnectionReason— почему соединение не сообщается. Набор значений закрыт:no-connection-entry— позиция не находится ни на одной записи, в которой пишется прикрепление. Соединение, записанное как список целей (db: [store]), и соединение, проводимое собственным блоком зависимостей сущности Feature, не имеют такой записи, поэтому позиция на любом из них также даёт этот ответ.feature-created-connection— позиция находится на записи Release для соединения, проведённого сущностью Feature, которое не несёт прикреплений по причине, приведённой выше в ответе о слотах. Release пишет такую запись, когда блок зависимостей сущности Feature проводит соединение через сокет, который объявляет и потребляющая сущность Component; запись собирается, ничего не настраивая или задавая для соединенияinfraна уровне ребра.unknown-connection— позиция находится на записи, которую Release пишет для соединения, отсутствующего в скомпилированном графе. Собираемый Release может содержать такую запись — например, запись под псевдонимом, который ничто не проводит, и которая ничего не настраивает (нетtarget, нетinfra, нетfeatures), или запись для компонента, отключённого переключателемactive:, соединения которого покидают сборку вместе с ним.
Какие записи учитываются. В Aggregate — каждое соединение, проводимое компонентом, в его записи под псевдонимом соединения в документе, где компонент был написан, а для компонента, предоставленного импортированным модулем, — в собственном документе этого модуля. В Release — каждая запись на уровне ребра, которую он пишет, независимо от того, проводит ли запись своё соединение или настраивает соединение, проведённое Aggregate. Где находится каждая запись, фиксирует скомпилированный граф, поэтому то, является ли ключ соединением, никогда не выводится из его имени. Компонент, отключённый переключателем active:, отсутствует в скомпилированном графе, поэтому его собственные записи в Aggregate дают ответ no-connection-entry, а запись Release для одного из его соединений — unknown-connection.
Позиция в любом месте записи находится внутри неё. Запись простирается от ключа псевдонима до последней строки с отступом под ним, поэтому позиция на псевдониме, на его target или внутри его features получает ответ для этого соединения, а при вложенных записях побеждает самая внутренняя. Позиция на собственном ключе сокета, над записанными под ним псевдонимами, не находится ни в одном из них — содержит ли сокет один псевдоним или несколько, — как и позиция в отступе перед ключом псевдонима.
Какой документ какой, следует из Release. Собственный файл Release читается на предмет записей, которые он пишет; любой другой файл читается на предмет записей, в которых, согласно графу, были написаны компоненты. Документ, из которого граф Release ничего не читает, в любой позиции даёт ответ no-connection-entry.
Он сообщает и никогда не пишет, а документ читает так же, как aggrega/insertionPoint: сначала из копии сеанса, иначе с диска, внутри рабочего пространства, с теми же отказами для документа, который находится вне его, не читается или не является корректным YAML. Он требует lockfile по той же причине, что и aggrega/attachmentContainer, и строит граф, ничего не отрисовывая.
Что сообщает ответ insertion-point
aggrega/insertionPoint — пара к двум запросам кандидатов выше. Те говорят, что может присоединяться или подключаться; этот говорит, где в одном конкретном документе должен находиться текст для этого. Он отвечает и на этом останавливается.
Контейнер называете вы; демон его находит. container — структурный путь от корня документа, ["spec", "components", "web", "features"], и это ваше утверждение о том, где в документе такого вида должна находиться запись такого вида. Демон не выводит этот путь из того, как называется сущность, какой у неё тип или что она, по-видимому, означает. Он читает байты, написанные автором, и сообщает, какие сегменты пути в этом документе уже есть, в каких столбцах стоят его записи и до какой последней строки доходит самый внутренний блок. Таким образом, знание того, какой ключ, остаётся за вызывающей стороной, а знание того, куда в этом файле идут записи этого ключа, даёт этот запрос.
Для присоединения сущности Feature к узлу скомпилированного графа вызывающей стороне не нужно знать этот ключ самой: запросите у aggrega/attachmentContainer документ и контейнер и передайте оба сюда без изменений.
Ответ — это позиция нулевой ширины плюс то, что нужно написать вокруг неё. file — документ, путь относительно рабочей области. container повторяет путь, о котором вы спросили, поэтому клиент с несколькими незавершёнными запросами сопоставляет каждый ответ с его вопросом, не отслеживая порядок самостоятельно. position вставляет, а не заменяет: ничто уже имеющееся в документе не перезаписывается и не сдвигается.
precededByLineBreak— начните записываемый текст с переноса строки. Позиция стоит в конце строки, за которой следует новая запись; она допустима независимо от того, заканчивается ли файл переводом строки, и не затрагивает ни одного уже записанного байта. Значение ложно только для документа, в котором нет ничего, после чего можно встать; тогда запись идёт с начала файла.missingContainerKeys— сегменты пути контейнера, которых в этом документе ещё нет, начиная с внешнего. Каждый нужно записать как отдельный ключ, прежде чем запись можно будет поместить внутрь самого внутреннего. Список пуст, если весь путь уже есть.entryIndent— столбец, с которого начинается первая строка самой записи, в пробелах от начала строки.indentStep— на сколько дальше отступает каждый уровень вложенности.indentStepMeasured— был ли этот шаг измерен по собственной вложенности документа. Если значение ложно, в документе нет вложенности для измерения и шаг — значение по умолчанию, так что клиент, предпочитающий задать собственный, знает, что может это сделать.entryShape—mappingилиsequence, определяется по тому, что уже содержит контейнер, иunknown, если контейнера ещё нет или он пуст.unknown— не ошибка: документ не указал, какую форму принимают его записи, поэтому выбор за вами.
Применение. Если задан precededByLineBreak, запишите перенос строки. Затем по одной строке на каждый элемент missingContainerKeys, начиная с внешнего, каждая — ключ с двоеточием; первая с отступом entryIndent минус indentStep, умноженный на число отсутствующих ключей, а каждая следующая на indentStep дальше. Затем саму запись с отступом entryIndent. Если missingContainerKeys пуст, запись — единственная строка, которую вы пишете.
Читайте missingContainerKeys, даже если ожидаете, что контейнер есть. Позиция, применённая без ключей, которые должны ей предшествовать, даёт документ, который больше не разбирается, — это единственная ошибка, которую этот ответ не должен воспринимать как отсутствие.
position отсчитывается от нуля, в отличие от позиции диагностики. И line, и character начинаются с 0, как значения позиций в стиле LSP, которые повторно использует этот протокол, тогда как line и column в записи диагностики начинаются с 1, как описано в разделе What a diagnostic entry carries. Клиент, передающий данные из одного интерфейса в другой, выполняет преобразование.
positionEncoding указывает единицы, в которых измеряется character, и это кодировка, согласованная при рукопожатии. Она сообщается в ответе, а не подразумевается, потому что позицию, единицы которой вызывающей стороне приходится угадывать, применить нельзя: смещения, измеренные одним способом и применённые к буферу, измеряемому иначе, портят документ на первом символе вне ASCII.
Запрос, не указывающий место, куда может пойти запись, отклоняется, а не получает ответ. Каждый из этих случаев — состояние запроса, а не рабочей области, поэтому он возвращается со стандартным кодом invalid-params, и повтор ничего не меняет, пока не изменятся file или container.
- Документ не указан, находится вне рабочей области, не может быть прочитан или не является корректным YAML: у документа без структуры нет позиции, которую можно сообщить.
- Путь контейнера ничего не указывает: в нём нет сегментов или один из сегментов пуст.
- Путь проходит через значение, которое в документе является скаляром. Внутрь скаляра ничего нельзя добавить, а его замена была бы переписыванием, а не вставкой.
- Путь доходит до коллекции, которую автор записал в потоковом стиле. Добавление в неё записи переписывает уже написанные автором байты, а не добавляет строку, — это правка, а не позиция.
- Путь обращается к блочной последовательности через то, что не является одним из её индексов. Записи последовательности адресуются по позиции, поэтому имя в ней ничего не находит, и создать запись с таким именем нельзя.
Он читает буфер, открытый в редакторе, а не только файл на диске. Сначала проверяется кэш разбора демона, поэтому позиция сообщается относительно несохранённого содержимого, если оно есть, и относительно самого файла, если в кэше для него ничего нет.
Он только сообщает и никогда не пишет. Метод ничего не изменяет, ничего не разрешает, не обращается ни к реестру, ни к сети и ничего не записывает ни в один документ. Он не составляет текст записи и не применяет её. Составление и применение правки — задача редактора, где находятся буфер и история отмены.
Что сообщает ответ на запрос редактирования документа
aggrega/editDocument — вторая половина описанной выше пары: те запросы сообщают, куда относится запись, и оставляют вам её составление и применение; этот запрос составляет и применяет запись сам, и он выполняет запись. Доступны оба, потому что клиенту с несохранённым буфером и клиенту, редактирующему содержимое на диске, нужны разные половины: редактор с собственной историей отмены вставляет текст сам, а клиент, которому удобнее, чтобы файл отредактировали, чем сообщили, где его редактировать, отправляет этот запрос.
Один вызов применяет одну правку, и набор правок закрыт. edit указывает, какую именно: add-component добавляет экземпляр компонента в контейнер компонентов, attach-feature присоединяет Feature к узлу, wire-edge прокладывает соединение внутри одного из сокетов зависимостей узла, а set-value задаёт одно значение на узле. Нет правки, которая удаляет, заменяет уже написанный вами блок, что-либо переупорядочивает или записывает переданные вами байты дословно, — так что это не средство записи файлов под более узким названием, а значение вне этих четырёх отклоняется, а не интерпретируется. В отказе перечислено, что можно указать.
Узел указывается структурным путём, точно так же, как в двух запросах выше. node — это цепочка от корня документа, ["spec", "components", "web"], а контейнер, в который попадает запись, определяется по edit. Для add-component путь указывает сам контейнер компонентов, потому что добавляемая запись и есть узел. name — ключ, под которым пишется запись: имя экземпляра, имя присоединения, псевдоним соединения или ключ значения. value — то, что несёт запись, а его смысл определяется по edit: запрашиваемая записью сущность, узел, на который указывает соединение, или скалярное значение, которое задаётся. socket читается для wire-edge и в остальных случаях игнорируется.
Путь, а не имя, — по той же причине, по которой его принимает запрос определения позиции: имя пришлось бы искать, а имя, встречающееся на двух уровнях, оставило бы компилятору решать, какое из них имелось в виду. Поэтому клиент, знающий, какой узел он редактирует, так и говорит, а клиент, который этого не знает, понимает, что до любого редактирования ему нужно ответить на вопрос.
Каждый байт, которого правка не касается, сохраняется. Документ разбирается только для того, чтобы найти контейнер и строку, на которой заканчивается его блок; запись формируется и вставляется на уровне строк. Комментарии, пустые строки, стиль кавычек, свёрнутые и буквальные скаляры, шаблонные выражения и наличие завершающего перевода строки переносятся без изменений, а шаг вложенности измеряется по собственным отступам документа, а не навязывается, — так что запись получает тот стиль, в котором вы уже пишете. Один и тот же запрос к одному и тому же документу даёт одни и те же байты, поэтому клиент может сравнить два запуска, а при ревью одна правка выглядит как один diff.
Результатом должен быть документ, который вы могли бы набрать вручную, и именно от этого зависит запись. Составленный документ проверяется по схеме его собственного вида и попадает на диск, только если проверка пройдена. Запрос, который дал бы что-то, отвергаемое схемой авторинга, возвращается как E0275 — the edit was refused because the resulting document would not be valid, and nothing was written (правка отклонена, потому что итоговый документ был бы недопустимым, и ничего не записано) — с указанием свойства, которое схема не допустила, и места. Файл остаётся байт в байт таким, каким был, поэтому отклонённая правка неотличима от никогда не предпринятой, и вы можете повторить исправленный запрос к исходному документу. По этой же причине здесь не повторяется ни одно правило: требование, чтобы документ Release нёс значение разработчика, отклоняется той же схемой, которая отклонила бы документ, набранный вручную.
Что допустимо семантически, здесь не решается. Объявляет ли производитель данный сокет зависимости и выполнено ли условие применимости Feature, относится к разрешению, которое выполняет сборка, и у каждого из них своя отчётность. Поэтому можно указать соединение, о котором этот запрос никогда не слышал, а Aggregate может задать сокет, который его сущность каталога не объявляет заранее; что может быть потреблено через сокет, по-прежнему объявляет производитель. Если вопрос именно в этом, выполните aggrega/validate с указанием Release или запросите граф.
Ответ сообщает, что было вставлено и что попало на диск, и это разные вопросы. content содержит документ, полученный в результате правки, при обоих способах доставки. written указывает файл, попавший на диск, и пуст при dryRun. container — структурный путь контейнера, в который попала запись, так что добавленное можно найти, не выводя это правило заново. createdContainers перечисляет сегменты, которые эта правка записала, потому что их не было в документе, начиная с внешнего; в обычном случае, когда весь путь уже существовал, он пуст, и по нему можно отличить запись, добавленную внутрь существующего блока, от записи, создавшей собственный блок. file и edit повторяют отправленное вами, так что клиент с несколькими незавершёнными запросами сопоставляет каждый ответ со своим вопросом. written, container и createdContainers всегда являются массивами — пустыми, а не отсутствующими.
При dryRun ничего не создаётся. written пуст, content содержит документ, который дала бы запись, а файл не затрагивается, — так редактор может показать результат автору, чтобы тот сохранил, изменил или отбросил его. По умолчанию выполняется запись, потому что продукт операции — отредактированный документ, и интерфейс, который его создаёт, обязан его выдать: запрос, ничего не говорящий о доставке, редактирует файл.
Всё остальное, что делает запись, делает и пробный запуск. Составленный документ в любом случае проверяется по схеме его собственного вида, поэтому правка, которую отклонила бы запись, отклоняется и при dryRun с указанием того же свойства, — то есть ошибка пробного запуска совпадает с ошибкой, которую дала бы запись.
Запись, которая уже существует и содержит то, что вы запросили, не вызывает никаких действий: документ возвращается без изменений, и ничего не записывается. Запись с тем же именем, но с другим содержимым, отклоняется, а не заменяется, потому что замена написанного автором не входит в четыре правки.
После записи демон перечитывает документ. Всё, что он хранил для этого файла, отбрасывается, а его представление на уровне рабочего пространства сбрасывается, поэтому следующий запрос проверки, подсказки, автодополнения или графа обрабатывается по байтам, полученным в результате правки, а не по заменённой версии. Сама правка читает файл на диске, а не буфер, который у вас открыт, — в отличие от запроса определения позиции выше, который сначала обращается к несохранённому содержимому. Это сделано намеренно: запись из несохранённого буфера под видом применения одной записи перенесла бы в файл содержимое, которое автор не сохранял. Сохраните буфер, затем редактируйте.
Запрос, который не указывает место, куда может попасть запись, отклоняется, а не обрабатывается, со стандартным кодом invalid-params, и повтор ничего не меняет, пока не изменится запрос. Документ не указан, находится вне рабочего пространства, не может быть прочитан, не является корректным YAML или не объявляет вид, по схеме которого можно проверить результат; edit не указан или не является одной из четырёх правок; node ничего не указывает или один из его сегментов пуст; не задан name; для wire-edge не указан socket; для set-value передано отображение или последовательность там, где ожидается скаляр; путь узла доходит до скаляра, последовательности или коллекции в потоковом стиле, где добавление строки переписало бы уже существующие байты; или путь узла не указывает ни на что в документе.
Ни при одном способе доставки он не разрешает зависимости, не обращается к реестру и не использует сеть.
Что охватывает ответ effective-configuration
aggrega/effectiveConfiguration отвечает на два вопроса: какая конфигурация действует в этом сеансе и какой слой определил каждый параметр. Это тот же ответ, который выводит aggrega config show --origin: он вычисляется один раз и сообщается на обеих поверхностях, поэтому они не могут расходиться в том, откуда взялся параметр.
source имеет одну из четырёх форм. Абсолютный путь к файлу конфигурации — включая глобальный файл, который читает демон, запущенный как aggrega --config <file> serve, указанный по переданному пути; переменная окружения с префиксом env:, например env:AGGREGA_SIGNING_REQUIRED; глобальный флаг, указанный в командной строке, которой был запущен демон, названный по имени флага, например --offline для демона, запущенного как aggrega --offline serve; или (built-in defaults) для параметра, который не задаёт ни один слой. Первые три формы дословно присутствуют в layers. Значения по умолчанию — нет, потому что они не являются слоем, внёсшим вклад: это то, что действует там, где ни один слой ничего не задал.
Параметр приписывается слою с наивысшим приоритетом, который его задаёт, каким бы ни было записанное этим слоем значение. Если файл конфигурации записывает встроенное значение по умолчанию или повторяет значение, уже заданное файлом ниже, указывается именно этот файл: именно он удерживает значение. Файл задаёт параметр, содержа его ключ (включая сопутствующий ключ _append для списка), а переменная окружения — будучи экспортированной с непустым значением. Файл конфигурации, принадлежащий вашему конвейеру, никогда не указывается для ключа, который он игнорирует. aggrega config show --origin сообщает по тому же правилу.
Учитывается каждый параметр, объявленный схемой конфигурации, хотя и не каждый в отдельной строке. Дополняющий ключ _append списка сообщается в строке того списка, который он дополняет, поэтому слой, внёсший вклад только через этот ключ, указывается в строке списка, а у самого ключа строки нет. Параметр внутри элементов списка — политика доверия реестра, входные данные подключения плагина — покрывается строкой этого списка.
Ещё два ограничения, каждое из которых делает ответ грубее, чем кажется.
- Параметр-список или параметр-словарь приписывается целиком слою с наивысшим приоритетом, который его задаёт. Атрибуция по отдельным элементам не отслеживается, поэтому для списка, собранного из двух слоёв, сообщается только слой с более высоким приоритетом, а элемент, внесённый нижним слоем, неотличим от записанного верхним.
- Требование подписи приписывается первому слою, который его включил, а не последнему, который его упомянул. Этот параметр комбинируется так, что побеждает любой слой, включивший его, и ни один последующий слой не может его выключить, поэтому именно первый включивший слой сделал действующее значение таким, какое оно есть. Слой, записывающий
required: false, ничего не включает, поэтому, если каждый упоминающий его слой записываетfalse, параметр сообщается как(built-in defaults).
Каждое сообщаемое значение — это результат разрешения, полученный, когда рабочее пространство было названо впервые. Правка файла конфигурации не меняет здесь значение; перезапуск демона — меняет. Так задумано: эти значения — конфигурация, под которой отвечается на все остальные запросы об этом рабочем пространстве, и именно это делает их сопоставимыми с корнем и слоем конфигурации, которые сообщило для него рукопожатие. Клиент, показывающий конфигурацию рядом с файлом, который редактирует пользователь, должен указывать, что из двух он показывает.
Атрибуция по слоям вычисляется в момент запроса, по файлам в их текущем состоянии. Поэтому отредактированный позже файл конфигурации может изменить source, тогда как значение рядом остаётся таким, каким было разрешено. Две половины отвечают на разные вопросы — что действует и какой слой это определил, — и зафиксирована только первая. Перезапустите демон, чтобы снова согласовать их.
Он только сообщает и никогда не записывает. Метод не меняет конфигурацию, не создаёт файлов и ничего не разрешает из реестра или сети.
Содержимое отдельного файла-слоя здесь не выдаётся. Командная строка может дословно вывести байты одного слоя с сохранением комментариев и форматирования; этот метод сообщает результат разрешения, а не байты. Клиенту, которому нужен текст слоя, доступен путь в layers, и он может открыть файл.
Что оставляет после себя запись конфигурации
aggrega/configInit и aggrega/configCapture оба создают документ конфигурации и оба записывают его. Ответ называет файл; открыть его — ваш следующий шаг, а не замена записи. Ни один из них не передаёт вам содержимое, чтобы вы разместили его сами, если вы прямо об этом не попросите, потому что возможность, результатом которой является так и не записанный документ, — это другая возможность под тем же именем.
Они различаются тем, насколько далеко распространяется их действие, и каждый ответ сообщает, насколько. Прочитайте это, прежде чем показывать результат.
- Начальное заполнение по умолчанию записывает конфигурацию, общую для всех рабочих пространств на машине. Реестр и идентичности, которым вы в нём доверяете, обычно одни и те же, где бы вы ни работали, поэтому запись попадает именно туда, если запрос не отправляет
workspace: true.scopeсодержитconfigFile, который был записан, иmachineWide, сообщающий, является ли он общим, — это значение выводится из файла, в который фактически разрешилась запись, а не из того, что запрашивалось, поэтому ответ не может описать изменение на уровне всей машины как локальное. - Заморозка никогда не выходит за пределы рабочего пространства. Она не принимает ни цели записи, ни переопределения: её единственное назначение — сделать один проект самодостаточным, поэтому она всегда записывает собственный
.aggrega-config.yamlэтого проекта. Именно поэтому её ответ содержитconfigFileиworkspaceRootи не заявляет никакой области действия — сообщать о ней нечего.
Начальное заполнение отказывает, а не перезаписывает. Уже существующий файл конфигурации остаётся нетронутым, и отказ называет его, потому что начальное заполнение предназначено для ещё не существующей конфигурации, тогда как общая запись, которой оно делегирует работу, по замыслу выполняет слияние. Отправьте force, чтобы записать всё равно; запись реестра сливается с тем, что уже есть, а остальные настройки сохраняются. Отклонённый запрос ничего не меняет.
trust сообщает, что произошло с объявленной политикой реестра, в виде отдельных исходов, а не текста. pinned означает, что реестр объявил политику и она была принята; identities указывает число идентичностей. notAdvertised означает, что реестр был опрошен и не объявил никакой политики, что не является ошибкой — начальное заполнение продолжается, а reason сообщает, что сделала конечная точка. Недоступный реестр тоже сообщается так, поскольку политика не получена и заполнение так же продолжается, и рядом указывается unreachable, если сам сбой показывает, что до реестра так и не удалось достучаться: его имя не разрешилось, соединение с ним было отклонено или не открылось, либо не удалось установить защищённое соединение. Реестр, который ответил — «не найдено» или статусом ошибки, — никогда не получает unreachable, поэтому, чтобы отличить реестр, не публикующий политику, от реестра, который так и не был опрошен, читайте этот ключ, а не формулировку reason. baseline означает, что была закреплена встроенная базовая политика официального хаба, потому что никакая объявленная политика не была принята, а reason объясняет почему; запись содержит политику, так что закреплять что-либо вручную не нужно. Эти два ключа отвечают на разные вопросы, поэтому хаб, который был опрошен и ничего не объявил, содержит оба, а хаб в офлайн-рабочем пространстве — не опрошенный — содержит только baseline, и reason сообщает, что рабочее пространство в офлайн-режиме. Любой другой реестр, ничего не объявляющий, содержит только notAdvertised, заполняется без политики, и далее рекомендуется закрепить идентичности вручную; в офлайн-режиме такой запрос отклоняется, а не выполняется. skipped означает, что получение не предпринималось. Клиент, считающий ошибкой всё, кроме pinned, сообщил бы о рабочей конфигурации как о сломанной.
При dryRun ничего не создаётся. written равно false, content содержит документ, который создала бы запись, а файл, для которого предназначено это содержимое, — scope.configFile. Никакой каталог не создаётся и ни один файл не затрагивается, поэтому редактор может показать текст автору и позволить ему сохранить, изменить или отбросить его.
Пробный запуск отличается от записи ровно в одном — он не записывает, — поэтому каждый отказ, который выполняет запись, выполняет и он. Здесь важен отказ из-за существующего файла: dryRun поверх уже существующего файла конфигурации отклоняется с указанием файла точно так же, как запись. Именно это делает ответ пригодным в качестве предиката: если пробный запуск отказывает, отказала бы и запись, по той же причине и с тем же сообщением. Отправьте force вместе с dryRun, чтобы вместо этого получить слияние, которое произвела бы перезаписывающая запись, по-прежнему ничего не записывая. В обоих режимах выдачи реестр опрашивается на предмет объявленной политики доверия, потому что политика в этом содержимом — та, которую закрепила бы запись.
Заморозка сообщает то, что она записала, а не описание этого. sockets перечисляет каждый замороженный сокет плагина вместе с замороженными в нём подключениями; catalogDirs содержит каталоги каталогов сущностей. Оба всегда являются массивами — пустыми, а не отсутствующими.
socketиfield— не одна и та же строка, и разница не косметическая.socketназывает сокет, к которому привязаны подключения;field— ключ, под которым они записаны в файле. Они различаются только для сокета провайдера, который записывается под ключом во множественном числе, — поэтому используйтеfield, когда указываете читателю на строку в документе, иsocket, когда называете сам сокет.- Каждое подключение содержит
uri,capability,functionиrole— только те, что у подключения есть. Они называют подключение, а не воспроизводят его целиком: необязательные входные данные подключения, задаваемые при подключении, замораживаются в файл дословно и в ответе не повторяются. Авторитетной копией является файл. captured: false— это успех. У проекта, в конфигурации которого сборка не участвует, нет ничего критичного для сборки, что можно заморозить, поэтому файл остаётся как есть, а оба списка возвращаются пустыми. Если считать это ошибкой, исправное рабочее пространство будет показано как сломанное.
По умолчанию замораживается только то, что определяет выходные байты, — привязки провайдеров и подключения управления, преобразующие метки. Шлюзы управления с вердиктом и линтеров, а также сокет импорта не включаются, потому что они должны различаться между окружениями, и их заморозка перенесла бы шлюзы одного окружения в каждую рабочую копию. allPlugins: true расширяет набор до всех сокетов плагинов. Включение определяется для каждого подключения, а не для каждого сокета, поэтому сокет управления с одним подключением преобразования меток и одним подключением вердикта по умолчанию вносит только первое.
Каждое значение замораживается в своём действующем значении — том, что получается при слиянии конфигурации машины и собственной конфигурации проекта, — поэтому привязка, которая сегодня задаётся только конфигурацией машины, записывается в проект и переносится вместе с ним. Общемашинные настройки инструментов, в том числе политика доверия реестра, не критичны для сборки и остаются на месте. Повторная заморозка неизменной конфигурации записывает те же самые байты, поэтому клиент может свободно предлагать её: второй вызов оставляет документ, который держит открытым читатель, в точности таким, каким он был.
Что сообщает изменение плагина
Все четыре запроса к плагинам по умолчанию выполняют запись, и они различаются тем, что записывают: два изменяют файл конфигурации, а два создают документы в рабочем пространстве. Два из них — добавление и генерация — принимают dryRun, при котором выполняется всё остальное, что делает запрос, но ничего не записывается. Читайте собственное описание ответа о том, куда попало изменение, а не выводите его из запроса: для одного из них отсутствие в запросе указания области означает самый широкий охват.
И добавление, и удаление содержат scope, и он выводится из файла, к которому разрешилась запись. configFile — это этот файл, machineWide сообщает, является ли он тем файлом, через который разрешается каждое рабочее пространство на этой машине, а workspaceRoot называет рабочее пространство, над которым открыт этот сеанс, так что ответ с областью рабочего пространства сообщает, какое это было пространство. machineWide считывается с разрешённого файла, а не с того, что запросил запрос, и именно это не позволяет ответу описать изменение на уровне машины как локальное.
🔴 Добавление типа cli, в котором не указаны ни global, ни workspace, регистрирует команду на уровне всей машины. Расширение команд — это инструментарий уровня машины, поэтому без переопределения оно записывается в глобальный файл конфигурации, через который разрешается каждое рабочее пространство на этой машине, — и регистрируемая им команда становится команды верхнего уровня aggrega для каждого проекта на этой машине, включая проекты, которые никто в этом сеансе не называл. Добавление provider, governance, linter или importer устроено наоборот: они определяют сборку одного проекта, поэтому без переопределения попадают в собственный .aggrega-config.yaml этого проекта. Удаление следует тому же правилу для тех же типов. Отправьте workspace: true, чтобы оставить расширение команд локальным, или global: true, чтобы вынести любой из остальных в общий файл; отправка обоих отклоняется. В любом случае авторитетным утверждением является scope в ответе, и клиенту следует показать его, прежде чем действовать по результату.
Добавление называет то, что было добавлено, и ровно одно из трёх полей сообщает, что это было. type повторяет тип, для которого добавлена запись, а затем: identity содержит голую идентичность сущности с закреплённой версией для подключения governance, linter или importer; uri содержит адрес артефакта плагина oci:// вместе с capability, которую он теперь обслуживает, для привязки provider; а reference содержит закреплённую ссылку, команды которой были зарегистрированы, для установки cli. Таким образом, вызывающая сторона считывает, какое подключение добавлено, из ответа, а не выводит это заново из отправленного типа. Удаление повторяет type и query рядом со своим scope и ничего больше — о записи, которой больше нет, сообщать нечего.
Добавление также содержит written, а при dryRun — content. По written клиент выбирает ветвь: true указывает на файл конфигурации, который теперь есть на диске и который клиент может открыть, а при dryRun значение равно false, и content содержит вместо этого документ конфигурации, который создала бы запись. Оба никогда не значимы одновременно, а файл, для которого предназначен content, — это scope.configFile, поэтому ничто в ответе не содержит второй копии этого пути, — что здесь важно, потому что файл подключения global — это тот, через который разрешается каждое рабочее пространство на этой машине.
Плагин без опубликованной версии отклоняется, а не подключается без закрепления. Добавление разрешает запрос до одного плагина и закрепляет его наивысшую опубликованную версию, поэтому записываемая запись содержит версию. Плагин, репозиторий которого не публикует ни одной соответствующей версии, отклоняется с указанием его имени, а версия, отозванная отзывом, которому доверяет это рабочее пространство, пропускается в пользу следующей более низкой.
Версия, названная в запросе, закрепляется, даже если она отозвана, и withdrawn сообщает об этом. query, записанный как <name>:<version>, закрепляет эту версию, а не последнюю, — для всех типов, кроме provider, который привязывается только по имени и отклоняет версию, — и указание версии и есть переопределение: если объявление об отзыве, которому доверяет это рабочее пространство, отозвало её, она всё равно закрепляется, и ответ содержит withdrawn: true — факт, который aggrega plugin add сообщает в терминале строкой retraction:. В любом другом ответе withdrawn отсутствует, поэтому его наличие и есть весь сигнал, — а его отсутствие не является утверждением, что версия не отозвана. Если метки отзыва названной версии не удалось прочитать, withdrawn отсутствует, а retraction содержит unscreened с указанием причины, как и для добавления без названной версии, столкнувшегося с той же ошибкой; добавление без названной версии вместо этого сообщает в retraction, к какому выводу пришла проверка отзыва относительно выбранной им версии.
Выравнивание сообщает, изменило ли оно что-либо, и именно по этому полю следует действовать. changed отличает запись от выравнивания, которое обнаружило, что записи уже верны: неизменённый файл остаётся побайтно идентичным, поэтому клиенту, держащему этот документ, нечего перезагружать, а повторный запуск запроса во второй раз не сообщает об изменениях. entity называет файл, hostFunctions содержит выведенный набор, а commands содержит зеркало в виде значений, а не строки, которую печатает терминал, — каждая запись это name, необязательный description и flags, причём каждый флаг содержит свой name и необязательные shorthand, description, type и default. Запись атомарна, поэтому клиент, читающий этот файл во время выравнивания, никогда не увидит частичный документ.
Генерация заполняет ровно одну половину своего ответа, и собственный dryRun ответа сообщает, какую. По умолчанию сущности записываются, а notices содержит то, что генерация сообщила о выполненных ею записях. При dryRun ничего не создаётся и не изменяется: documents содержит каждую сгенерированную сущность в виде path, для которого она предназначена, и её content, так что клиент может поместить их в свою модель документов, где они видны до сохранения и могут быть изменены или отброшены. Обе половины никогда не заполняются одновременно, поэтому то, какой способ доставки был выполнен, читается из ответа, а не из того, что было запрошено.
То, куда запрос к плагину ЗАПИСЫВАЕТ, всегда находится внутри рабочего пространства, названного этим запросом; то, что он ЧИТАЕТ, решается для каждого поля отдельно. Абсолютный путь назначения, путь, выходящий за пределы корня, и путь, выводящий из него через ссылку, отклоняются, а не разрешаются, — поэтому генерация не может создать сущности в дереве, над которым ваш сеанс никогда не открывался, что бы она ни отправила. Путь, который запрос только читает, — отдельный вопрос, на который отвечают для каждого поля, а не одним правилом для всех: aggrega/pluginGenCatalog читает модуль и его оверлей оттуда, где вы их выбрали, потому что собранный вами модуль находится в выходном каталоге вашего инструментария, и отказ читать его там означал бы отказ от операции, в которой весь её смысл. aggrega/pluginSync читает свои два пути внутри рабочего пространства, потому что этот запрос касается файла, который рабочее пространство уже содержит. Описанные выше запросы поиска принимают абсолютный путь по ещё одной причине — это документ, который клиент уже держит открытым, названный в том написании, в каком он его держит.
Запрос, в котором отсутствует что-то необходимое операции, отклоняется с указанием поля, которое нужно отправить. Добавление или удаление без type или query; добавление provider без capability или добавление governance без role; добавление cli без acceptCapabilities; выравнивание без entity или plugin; генерация, в которой указаны оба режима выбора или ни одного, либо отсутствует overlay или outputDir. Каждый такой случай возвращается со стандартным кодом invalid-params, и повторная попытка ничего не меняет, пока не изменится запрос. Удаление, запрос которого не совпадает ни с одной записью, тоже отклоняется с указанием типа, запроса и файла, в котором выполнялся поиск, — это состояние конфигурации, а не запроса, поэтому исправлять может потребоваться и то, и другое.
Ничего не запрашивается интерактивно, и единственное решение, о котором спросили бы человека, поступает вместо этого в виде поля. Терминальная команда спрашивает того, кто за ней наблюдает, принимает ли он объявленные возможности плагина расширения команд. За этим потоком никто не наблюдает, поэтому acceptCapabilities вызывающая сторона должна получить и отправить сама, а запрос без него отклоняется с указанием того, что нужно отправить, вместо установки на основании согласия, которого никто не давал. Демон, запущенный без средств для установки расширения команд, сразу отклоняет добавление cli, а не сообщает об успехе, который ничего не установил.
Какие виды можно предлагать автору
aggrega/getSchema без kind отвечает, какие виды можно указывать, и отвечает в двух вариантах ширины, потому что клиенту для разных задач нужны разные. Читайте тот, о котором спрашиваете.
kinds — это каждый токен, на который отвечает бинарный файл. entityKinds — набор видов, документы которых пишет автор. Широкий список наряду с авторскими видами содержит промежуточное представление, lockfile, конфигурацию рабочего пространства и контракты сокетов плагинов — каждый из них настоящая схема, но не документ, файл которого кто-либо пишет. Поэтому широкий список служит для настройки сопоставления схем в редакторе, а узкий — для построения элемента выбора. Элемент выбора, построенный по широкому списку, предлагает значения, которые не принимает ни одна авторская схема, и автор сталкивается с отказом лишь после выбора.
Узкий набор уже и самих видов сущностей, и ни одна схема не сообщает, каких именно. Принадлежащий платформе вид, содержимое которого пишется внутри документа другого вида, не является документом, с которого стоит предлагать автору начинать. Workload — такой вид: содержимое workload пишется в поле workload: сущности Recipe или FeatureRecipe — либо встроенно, либо из файла, который это поле импортирует, поэтому отдельного документа workload, к которому можно обратиться, нет — см. поверхность авторинга Workload, где описано, куда помещается это содержимое. Его схема фиксирует apiVersion и kind точно так же, как схема авторского вида, потому что именно это позволяет проверять содержимое там, где оно находится; фиксированные значения идентифицируют содержимое, но не делают его адресуемым. Поэтому они не сигнализируют, что вид предназначен для создания черновика. Ответ несёт entityKinds, а байты схемы — нет.
Каждая запись entityKinds содержит оба написания, нужные клиенту, и ни одно не выводится из другого. kind — токен в нижнем регистре через дефис: отправляйте его обратно как kind этому методу или aggrega/scaffoldEntity. documentKind — значение, которое сам документ содержит в поле верхнего уровня kind:. Для вида, имя которого состоит из нескольких слов, они различаются не только регистром: никакие преобразования featurerecipe не дадут FeatureRecipe. Берите каждое из записи, а не выводите одно из другого, и клиенту не придётся хранить никакого сопоставления.
Каждая запись также сообщает, какие операции принимают документ её вида, чтобы элемент управления, предлагающий эти операции над документом, предлагал только те, которые не отказывают ему из-за вида. acceptedBy содержит три булевых значения, каждое присутствует в каждой записи и относится к документу названного вида, указанному самостоятельно — по пути или, для инспекции, по имени — без чего-либо ещё, отправленного рядом. singleEntityValidation — проверяет ли aggrega validate <path> документ этого вида, а не отказывает, называя область всего каталога или Release, которая проверяет его вместо этого. publication — публикует ли aggrega/publishEntity, указывающий только документ, этот документ: для Plugin это false, потому что его публикация также привязывает исполняемый файл, указанный запросом в plugin, поэтому запрос, указывающий только документ, отклоняется; для Manifest и Release это false, потому что ни один из этих видов не публикуется. inspectionByName — разрешает ли aggrega/entityDefinition имя в сущность этого вида, причём имя отправляется так, как оно пишется там, где одна сущность ссылается на другую: Plugin как <pluginType>/<name>, а Recipe или FeatureRecipe как <capability>/<name> либо только по имени, если это имя объявляет лишь одна capability. Значение true говорит, что операция не отказывает документу из-за его вида; она всё ещё может отказать конкретному документу из-за того, что в нём написано.
Не храните собственный список. Какие виды существуют — свойство бинарного файла, с которым вы общаетесь, поэтому список, записанный в клиент, совпадает в день написания и перестаёт совпадать в день добавления вида — и тогда автор видит, что его вида нет в том самом элементе управления, который должен был его предлагать. Спрашивайте, и ответ будет следовать бинарному файлу.
Обе половины приходят вместе и только тогда, когда вы не указываете вид. Запрос, указывающий вид, получает в ответ схему этого вида без обоих списков, так что по ответу видно, какой вопрос был задан. Токен, которому не соответствует ни одна схема, отклоняется со всем допустимым набором в сообщении и со стандартным кодом invalid-params, так что опечатка — это запрос, который нужно исправить, а не вопрос к человеку.
Он отвечает и в пустом рабочем пространстве. Словарь скомпилирован в бинарный файл, поэтому не нужны ни документ, ни lockfile, ни каталог — а именно в таком рабочем пространстве находится автор, начинающий свой первый документ.
Что даёт ответ на запрос заготовки
Этот раздел посвящён созданию черновика. Другая форма метода записывает готовый к запуску пример, и её ответ описан вместе с методом выше.
aggrega/scaffoldEntity возвращает текст. skeleton — это YAML для указанного вами вида: каждое поле, которое требует схема этого вида, в том порядке, в котором схема их объявляет. Поле, которое схема закрепляет за единственным фиксированным значением, приходит заполненным — заметнее всего это для apiVersion и kind, — metadata.name содержит отправленное вами name, а каждое другое обязательное значение приходит как заполнитель того типа, который схема объявляет в этом месте: пустая строка, ноль, false, пустой список, пустое отображение. kind повторяет токен, для которого был построен документ, поэтому клиент с несколькими незавершёнными запросами сопоставляет ответ по самому ответу, а не по собственной таблице соответствий.
Метод ничего не записывает, и именно это следует учитывать при проектировании. Метод не создаёт файл, не выбирает путь и не затрагивает каталоги. Вы получаете документ, который нужно записать, а не документ, который был записан, — поэтому редактор помещает текст в новый несохранённый буфер, который автор может прочитать, изменить или отбросить, а момент появления нового файла на диске остаётся там же, где буфер и история отмены. Никакой другой запрос не берёт этот документ и не размещает его где-либо за вас: решать, где будет находиться новый документ, — дело редактора.
Метод ничего не разрешает и ничего не требует от рабочего пространства. Документ строится из схем, встроенных в исполняемый файл, поэтому метод не обращается ни к реестру, ни к сети, не обращается к каталогу и не читает файлы. Он отвечает одинаково в любом рабочем пространстве, включая пустой каталог, в котором ещё нет ни одного документа Aggrega, — а это именно то рабочее пространство, в котором находится автор, начинающий свой первый документ, и где большинству других описанных здесь методов сначала нужен документ или lockfile.
Один и тот же запрос даёт одни и те же байты, где бы его ни задали. Документ создаётся одним вычислением, общим с другими интерфейсами, предоставляющими эту возможность, поэтому редактор и ассистент, получившие запрос на один и тот же вид и одно и то же имя, показывают автору один и тот же исходный текст.
Заготовка содержит поля, которые требует её вид, и не является готовым документом. Она содержит обязательные поля и ничего больше: нужное вам необязательное поле вы добавляете сами, а каждый заполнитель — это значение, которое ещё предстоит указать. Заполните заполнители, затем выполните aggrega/validate для буфера. Для сущности каталога того вида, который aggrega validate проверяет как отдельную сущность, этот метод называет каждый ещё не заполненный заполнитель — у его ключа и с указанием того, что он принимает, — по тому же прочтению, которое команда применяет к сохранённому файлу, включая заполнитель, который схема допускает пустым; чаще всего вы встретите capability и implements в заготовке сущности Recipe или FeatureRecipe. Для любого другого вида метод проверяет буфер по схеме его вида, поэтому заполнитель, который схема не допускает пустым, — например, версия, — возвращается как находка этой схемы, а заполнитель, который схема допускает пустым, находки не вызывает. В разделе Проверка в реальном времени описано, в виде какой записи приходит каждый заполнитель.
Что сообщает ответ на импорт
aggrega/import преобразует исходный файл, написанный для другого инструмента, в черновые документы Aggrega, и записывает их — в отличие от описанного выше скаффолда, который возвращает текст. written называет каждый файл, попавший на диск, относительно outputDir; files содержит каждый файл, который записывает запрос, с его content, независимо от того, был ли он записан, — каждый черновик, созданный импортёром, а затем запись о том, что записал импорт, или, при sync, что изменяет синхронизация. Эти два поля отвечают на разные вопросы, поэтому читайте то, которое соответствует вашему вопросу: что теперь на диске или что было создано.
Вы выбираете, куда попадут черновики, или оставляете это корню рабочего пространства. outputDir необязателен, как и aggrega import --output-dir и output_dir инструмента import ассистента: запрос, не указывающий его, создаёт черновики в корне рабочего пространства — там, куда пишет aggrega import, если ему не задано место назначения, где бы он ни запускался, — а запрос, указывающий его, создаёт черновики там. Указанный каталог — это путь внутри рабочего пространства, и относительное значение разрешается относительно корня рабочего пространства, а не каталога, в котором случайно находится демон. Преобразуемый source — другой случай, и такое ограничение на него не распространяется: этот файл или каталог выбрали вы, поэтому он читается там, где находится, и его чтение там не меняет того, куда попадут черновики. Если каталог не существует, он создаётся. При dryRun ничего не записывается, и каждый черновик по-прежнему называет путь, для которого он предназначен, относительно outputDir, указанного в ответе, — отправленного вами каталога или корня рабочего пространства.
Запрос никогда не перезаписывает сущность Aggregate, уже находящуюся в outputDir. Aggregate — это документ, который автор продолжает редактировать после того, как он создан черновиком, поэтому запрос, один из черновиков которого попал бы на файл, читаемый как Aggregate, отклоняется с указанием черновика и места, где находится Aggregate, и ничего не записывается — в том числе под dryRun, поскольку пробный запуск отклоняет то, что отклоняет запись. Вместо этого отправьте sync, чтобы привести его в соответствие с источником, или укажите другой outputDir, чтобы создать черновик рядом с ним. Любой другой файл, уже находящийся по пути черновика, перезаписывается, а файл, созданный более ранним импортом и не создаваемый этим, остаётся на месте. Каждый запрос, создающий хоть какой-то черновик, также записывает .aggrega-import.json в outputDir — запись о том, что записал импорт: target, с которым он был отправлен, если был, снимок каталога, который он прочитал, если прочитал, и каждый созданный файл, а в созданной сущности Aggregate или Release — каждый ключ на любой глубине с дайджестом записанного туда текста; любой другой созданный файл записывается целиком. files и written содержат её после черновиков. Это JSON, поэтому ничто, читающее YAML-документы рабочего пространства, её не читает; sync, как и aggrega import --sync, читает её, чтобы привести черновики в соответствие с их источником. Запрос sync, отправленный без target, создаёт черновики для цели, указанной в записи, то есть сущность Manifest, созданную более ранним импортом; запрос, отправленный с target, создаёт черновики для неё, и запись затем указывает её. Записанная цель, к которой не привязывается ни одна сущность Recipe в каталоге, отклоняется так же, как отправленная, причём в отказе говорится, что цель — записанная. Поскольку созданная сущность Release записывается по ключам, окружение, которое её автор пишет там, где импорт оставил для него комментарий, является ключом, написанным автором, и синхронизация оставляет его байт в байт.
Отправьте sync, чтобы привести то, что более ранний импорт создал в outputDir, в соответствие с исходником, изменяя только то, что записал импорт. Каждая часть оценивается тремя способами: что, согласно записи, импорт записал туда в последний раз, что находится на диске и что исходник создаёт сейчас. Часть, которую исходник оставил такой, какой её в последний раз записал импорт, остаётся точно такой, как на диске, независимо от того, редактировал ли её автор. Часть, изменённая исходником, записывается заново, удалённая им часть удаляется — созданный файл удаляется целиком, — а добавленная часть добавляется рядом с частями, которые черновик называет вокруг неё; всё это — только там, где на диске находится то, что в последний раз записал импорт, и нет ничего, добавленного автором. Всё остальное остаётся байт в байт: ключ, добавленный автором где угодно, — параметр, Feature, в том числе внутри созданного экземпляра Component, другой Component, — комментарий, написанный не непосредственно над созданным ключом, и каждый файл, которого нет в записи. Синхронизация в каталог, где нет записи и нет ничего по путям черновика, записывает весь черновик, как это делает запрос без sync.
drift — это то, что синхронизация привела в актуальное состояние, и это ответ на вопрос «изменился ли исходник». В нём перечислена каждая часть, изменённая синхронизацией, — или, при dryRun, каждая часть, которую она изменила бы, — в том порядке, в котором их называет черновик, каждая в виде change (added, removed или changed), file — созданного файла, в котором она находится, относительно outputDir, — и key — ключей, ведущих к ней в созданной сущности Aggregate или Release, в виде списка, так что ключ, содержащий точку, остаётся одним элементом; key пуст, если часть — это весь файл, и именно так называется созданный файл, который синхронизация удаляет. aggrega import выводит те же записи в стандартный поток ошибок в виде <change> <key> in <file> или <change> <file>, а его код завершения при --sync --dry-run сообщает, изменился ли исходник; у этого интерфейса нет кода завершения, поэтому отправьте sync с dryRun и проверьте, пуст ли drift. drift — пустой список для запроса, не являющегося синхронизацией, для синхронизации, соответствующей исходнику, и для синхронизации, импортёр которой не смог завершить работу. При sync files содержит каждый созданный файл, изменяемый синхронизацией, с содержимым, которое она ему даёт, а затем запись, если она тоже изменяется, а written называет те, что попали на диск, — поэтому синхронизация, соответствующая исходнику, возвращает оба поля пустыми списками. Созданный файл, удаляемый синхронизацией, назван в drift и ни в одном из этих списков: его запись removed с пустым key — единственное упоминание о нём в ответе, причём при dryRun она называет файл, который удалила бы запись.
Синхронизация никогда не переписывает написанное автором и вместо этого отклоняется. Синхронизация, которая изменила бы или удалила часть, отредактированную автором, добавила бы часть там, где автор уже её написал, или удалила бы часть, содержащую что-то добавленное автором, отклоняется с указанием каждой такой части и причины на отдельной строке, теми же словами, что использует aggrega import --sync, — <file> <key>: <why> или <file>: <why> для целого файла, — и ничего не записывается; комментарий, написанный непосредственно над созданным ключом, считается правкой этого ключа. Синхронизация поверх сущности Aggregate, которой нет ни в одной записи, отклоняется с указанием Aggregate и записи, как и синхронизация, запись которой не удаётся прочитать, поскольку без записи её части невозможно отличить от авторских. Оба отказа возвращаются как ошибка invalid-params, в том числе при dryRun, и называют sync. Согласуйте каждую названную часть вручную или верните то, что туда записал импорт, и отправьте запрос снова.
🔴 halted: true — не ошибка, и обработка его как ошибки — это та ошибка, от которой следует защититься при проектировании. Импортёр, который не смог преобразовать всё, всё равно создаёт черновики того, что смог: ответ содержит эти черновики, written называет их, а diagnostics сообщает, что было пропущено. Это самый полезный ответ, который даёт операция, и он приходит как результат, а не как сбой, именно для того, чтобы вы могли показать автору обе половины. При sync тот же ответ ничего не записывает — files, written и drift пусты, — потому что частичный черновик выглядел бы как исходник, из которого удалены все части, до которых не дошёл импортёр. Исходник, который импортёр вообще не смог прочитать, — другой случай, и он действительно возвращается как ошибка.
Каждая диагностика содержит severity и message, а также code, если импортёр его назначил. Ветвитесь по code, когда нужно отреагировать на конкретное условие, и показывайте читателю message; severity берётся из того же набора, в котором сообщает каждый сокет плагина, — halt, warn, info, — поэтому halted — это сводка по записям, а не отдельное суждение. files, written, drift, diagnostics и decisions всегда являются массивами — пустыми, а не отсутствующими.
decisions показывает, где импорт угадывал. Он содержит по одной записи на каждый исходный узел, который сопоставил импортёр, в порядке импортёра и ровно так, как импортёр о нём сообщил: sourceNode — id, type и paramsSummary узла; candidates — каждая сущность Component из каталога, которую импортёр рассматривал для него, в виде componentName, score, tier и signals — вклад каждого из его сигналов в разделах table, category, domainLabels, shape и name; chosen — выбранный target, mode, в котором он записан, — reference на существующую сущность Component или draft, — и tier этого выбора; rationale — почему; и swapHint — как выбрать иначе. candidates отсутствует, если импортёр не рассматривал ни одного кандидата, chosen — если он не сделал выбора, а rationale и swapHint — если он их не написал. Каждое значение принадлежит самому импортёру — как он оценивает кандидата и где проходят границы его уровней, решает он, — поэтому показывайте запись как его отчёт о сопоставлении, а не как вердикт. Решения приходят и при dryRun, и при halted, равном true: догадки частичного импорта — именно то, что нужно автору, который его проверяет, а импортёр, не сообщивший ни одного решения, отвечает пустым списком. Если вы показываете их текстом, aggrega import уже формулирует одно решение как mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, где оценка принадлежит лучшему кандидату.
Формат распознаётся по источнику, если вы его не назвали. Распознавание использует сигнатуры, которые объявляют импортёры — как импортёры каталога рабочего пространства, так и базовые импортёры компилятора, — и которые записывает сущность Plugin каждого импортёра: синтаксис, в котором читается источник, имена файлов, к которым применяется сигнатура, и пути, которые разобранное дерево должно или не должно содержать, — поэтому сам демон не знает ни одного формата, а формат нового импортёра распознаётся без каких-либо других изменений. Обнаружение читает только присланный вами источник — для каталога только файлы, отобранные шаблонами файлов сигнатуры, — и не обращается к сети, разбирая каждый читаемый файл парсером, который каталог рабочего пространства предоставляет для синтаксиса, — или, для синтаксиса, для которого каталог парсера не предоставляет, тем, что есть в самом компиляторе, — по одному разу для каждого синтаксиса, в котором его читает сигнатура, применимая к его имени; затем импортёр читает источник тем же парсером. Сигнатура, не объявляющая шаблонов файлов, применяется к присланному вами файлу с любым именем и ни к одному файлу каталога; сигнатуры импортёров Langflow, Flowise и n8n именно такие и читают JSON, а сигнатура импортёра Dify читает YAML, поэтому распознавание отдельно присланного файла читает его как JSON и как YAML, для чего парсер в каталоге рабочего пространства не нужен: в компиляторе есть парсеры JSON и YAML, а парсер, предоставленный каталогом, используется вместо них. Источник, которому не соответствует ни одна сигнатура, отклоняется с запросом format и перечислением форматов, которые объявляют импортёры, — или, для каталога, с запросом одного из его файлов, присланного отдельно, либо format, импортёр которого объявляет шаблоны файлов, с перечислением только таких форматов, — с условием No importer recognises the source (Ни один импортёр не распознаёт источник); источник, которому соответствуют сигнатуры более чем одного формата, отклоняется с их перечислением, с условием More than one importer recognises the source (Источник распознаёт более одного импортёра). data каждого отказа содержит code и shortCode его условия, поэтому клиент запрашивает формат по коду, а не по словам. Ни в одном из случаев формат не угадывается, потому что угаданный формат разрешается в не тот импортёр и даёт уверенную бессмыслицу. format в ответе — тот, что был использован, обнаруженный или названный, поэтому клиент, не указавший его, узнаёт, что получил.
Присланный вами каталог читается в файлы, которые называет его импортёр, а каталог, который невозможно прочитать, — ошибка. Если source указывает каталог, импортёр получает те его файлы, которые отбирают шаблоны файлов, объявленные его сигнатурами, за исключением каталога результатов сборки рабочей области dist/, каждый под своим путём внутри каталога, в отсортированном порядке, наряду с файлами, которые его запись plugins.importer называет в with.sources. Импортёр, не объявляющий шаблонов файлов, каталог, не содержащий ни одного отбираемого ими файла, файл каталога и файл из with.sources с одинаковым именем, а также ссылка среди файлов, которые прочитал бы импорт, или ссылка на каталог, ведущая за пределы каталога, — каждый из этих случаев возвращается ошибкой с кодом условия, и ничего не записывается.
Какой импортёр запускается, решает рабочее пространство, а не запрос. Формат разрешается в импортёр, который объявляет его среди плагинов каталога рабочего пространства и базовых импортёров компилятора, — в тот, который подключает запись plugins.importer в конфигурации рабочего пространства, если она подключает один из них, — поэтому запрос не может выбрать модуль или указать на модуль на диске. Формат, который не объявляет ни один импортёр, отклоняется с указанием формата, а формат, который объявляют два импортёра, ни один из которых не подключён, — в том числе базовый импортёр и импортёр с другим именем, который каталог содержит для того же формата, — отклоняется как неоднозначный, а не разрешается произвольно.
Базовый импортёр, которого ещё нет на машине, загружается один раз — первым импортом, которому он нужен. Он берётся из реестра по умолчанию рабочего пространства, должен совпадать с модулем, который публикует release компилятора, и проверяется так же, как pull проверяет загружаемый плагин, — его подпись по политике доверия этого реестра и используемые им функции хоста, — и сохраняется в кеше содержимого рабочего пространства; больше ради него ничего не записывается: ни lockfile, ни запись о доверенных плагинах. Каждый последующий импорт читает его оттуда и не обращается ни к какому реестру. Модуль, не прошедший проверку, — это ошибка с кодом её условия, и ничего не сохраняется; модуль, который не удаётся загрузить — рабочее пространство работает офлайн, его реестр недоступен или реестр его не содержит, — это ошибка под условием A plugin’s .wasm is not on this machine (Модуль плагина отсутствует на этой машине), в которой названы импортёр, его версия и то, что помещает его модуль на машину. Сам запрос не называет реестр, а импорт, все нужные импортёры и читаемый каталог которого уже есть на машине, вообще не обращается к сети.
Если рабочее пространство не называет ни одной папки каталога, импорт читает каталог, который публикует его реестр по умолчанию. Рабочее пространство, в котором ни workspace.catalog_dirs, ни AGGREGA_CATALOG_DIRS, ни корень не называют папку каталога, читает каталог стандартной библиотеки как один подписанный снимок по адресу catalog/snapshot в своём реестре по умолчанию. Снимок загружается один раз: его подпись проверяется по политике доверия этого реестра, после чего он сохраняется в кэше содержимого рабочего пространства и читается оттуда как папка каталога, привязанная к своему дайджесту, и ни один реестр больше о нём не запрашивается. Какой снимок читает запрос: с upgrade — самый новый; иначе тот, который называет запись в outputDir, загруженный по дайджесту, если его нет на машине; иначе тот, который рабочее пространство в последний раз загрузило как самый новый; иначе самый новый. Запись, которую создаёт импорт, называет прочитанный снимок по его дайджесту, поэтому последующий запрос в тот же outputDir читает тот же каталог. В офлайн-режиме запрос, которому пришлось бы загрузить снимок, — это ошибка под условием The workspace is offline and the step needs the network (Рабочее пространство в офлайн-режиме, а шагу нужна сеть), в которой названо, что нужно запустить, а upgrade отклоняется независимо от того, что есть на машине, поскольку только реестр может сказать, какой снимок самый новый. Реестр, который не публикует ни одного снимка, оставляет импорт без каталога, и запись warn в diagnostics сообщает об этом. Рабочее пространство, которое называет папку каталога, импортирует относительно неё и не загружает ни одного снимка, и upgrade там ничего не меняет.
При dryRun ничего не создаётся. written пуст, files содержит те же файлы, что дала бы запись, — с sync это файлы, которые записала бы синхронизация, наряду с drift, который она привела бы в актуальное состояние, — и ни один каталог не создаётся, поэтому редактор может показать их автору, чтобы тот сохранил, изменил или отбросил их. Всё остальное, что делает запись, выполняется: тот же импортёр обрабатывает тот же источник и сообщает те же диагностики, поэтому источник, который отклонила бы запись, отклоняется и здесь. Базовый импортёр или снимок каталога, загруженные при dryRun, сохраняются в кэше содержимого так же, как при записи, потому что получение того, на чём работает импорт, — часть его запуска, а не размещения черновиков.
Путь, который возвращает импортёр, удерживается внутри outputDir. Пути черновиков задаёт импортёр, а не вы, поэтому путь, выходящий за пределы выходного каталога, отклоняется и не записывается вообще ничего — даже черновики с корректными путями. Отказ называет нарушающий путь, и именно это говорит вам, что исправлять нужно импортёр, а не ваш запрос.
На какой вопрос отвечает каждый запрос о сущности
О сущности здесь могут рассказать четыре запроса, и они не взаимозаменяемы. Выбор между ними зависит от того, что у вас на руках в момент запроса.
У вас на руках позиция курсора. aggrega/hover и aggrega/resolve принимают файл и позицию и по написанному там определяют, какая сущность имеется в виду. Они охватывают те формы ссылок, которые действительно встречаются в документе: значение extends, тип компонента или функции, implements сущности Recipe, ссылки на рецепты в сущности Manifest, два указателя путей сущности Release, цель uses и собственное metadata.name сущности. Используйте их, когда координатой служит курсор пользователя: пользователь читает документ и хочет узнать, на что указывает ссылка.
У вас на руках имя. aggrega/entityDefinition принимает идентичность напрямую. Ничего не нужно открывать, позиция не участвует, и сущность не обязана упоминаться там, где клиент может её найти. Используйте его, когда пользователь ввёл имя, выбрал его из списка или перешёл к чему-то, идентичность чего ваш клиент уже знает: hover требует сначала найти место, где записано имя, а этой работы можно не делать.
У вас пока ничего нет. aggrega/catalogIndex перечисляет содержимое рабочего пространства с описательными полями каждой сущности. Используйте его, чтобы заполнить список выбора, а затем передайте выбранное имя в aggrega/entityDefinition.
У вас на руках сущность Release. aggrega/releaseClosure отвечает о сущности Release, а не об отдельной сущности; ему посвящён раздел ниже.
Определение, которое возвращает запрос по имени, — это сущность в разрешённом виде, а не такая, какой её объявляет какой-либо один файл. Сущность Component или Feature, расширяющая базовую, возвращается с контрактом базовой сущности, которого нет в документе, объявляющем её имя, — поэтому ответ описывает, чем сущность является, и чтение файла самостоятельно не дало бы того же.
Оно приходит как документ YAML, а не как структура внутри ответа, и это сделано намеренно: у столпа схемы есть несколько форм записи — содержимое, написанное целиком, ссылка на общий документ или маркер, указывающий, что содержимое берётся из базовой сущности, — и документ воспроизводит ту форму, к которой пришло разрешение, в собственном порядке ключей автора. Разбирайте его как документ, если вам нужны его поля; показывайте как есть, если выводите его на панель.
Как различить два отказа по имени
Имя, которое ни во что не разрешается, получает отказ, а не ответ с пустым документом, потому что пустой ответ выдал бы опечатку за сущность, которой нечего о себе сказать. Имя может не разрешиться двумя способами, они требуют от читателя разного, и различать их следует по содержимому data ошибки, а не по тексту сообщения:
- В
dataнетfile. Ничто в рабочем пространстве не объявляет это имя, и ни один уровень каталога его не разрешает. Почти всегда исправлять нужно запрос: это опечатка или имя из каталога, которого нет в пути поиска этого рабочего пространства. - В
dataестьfile. Документ рабочего пространства действительно объявляет это имя, но каталог всё равно ничего для него не разрешил. Сущность записана, но что-то её отвергло — это состояние рабочего пространства, которое исправляет человек. Если ровно один документ, прочитанный и отвергнутый каталогом, объявляет это имя — обычная причина, — сообщение начинается с этого отказа, изложенного один раз: его категория и короткий код, документ по пути, под которым он указан, и что с ним не так, например строка и нарушаемое ограничение; затем отмечается, что файл был пропущен при загрузке, и перечисляются остальные файлы, отвергнутые загрузкой. В противном случае сообщение называет объявляющий документ, перечисляет отвергнутые загрузкой файлы и говорит, откуда это рабочее пространство читает локальные сущности и что изменить, чтобы документ был прочитан, — пояснение, которое опускается, когда имя объявляет отвергнутый документ, ведь тот уже лежит там, откуда читает каталог.
Оба несут код entity-not-resolvable, поэтому ветвитесь по наличию file, а не по коду.
Запрос о координате
У вас на руках ссылка на реестр. Передайте её как name в aggrega/entityDefinition, и ответом будет сущность, опубликованная по этой координате, в той же форме результата, что и для имени, плюс published; поля заполняются из опубликованного, а не из того, что разрешил каталог:
definition— документ сущности ровно в том виде, в каком он был опубликован. Координата, сущность которой опубликована вместе с объявленными в ней файлами, содержит архив, и документ распаковывается из него; координата, сущность которой не объявляет файлов, содержит документ без изменений, а сущность Plugin читается из её манифеста, а не из опубликованного с ней исполняемого файла. Наследование не применяется.authoredLength— длина этого документа, поскольку определение здесь является написанным автором документом, а не представлением разрешённого.fileпуст, потому что у сущности, прочитанной из реестра, нет документа на этой машине, который можно назвать.publishScopeопускается: координата, по которой сущность опубликована, у вас уже есть.published— то, что было прочитано; оно присутствует в этом ответе и ни в одном ответе по имени:reference;archive— были ли байты архивом, из которого распакован документ (false, если координата содержала сам документ);mediaType, объявленный манифестом; иmanifestDigestэтого манифеста, который можно передать после@вместо тега, чтобы снова прочитать в точности те же байты.
Запрос обращается к реестру, который называет ссылка, с учётными данными пользователя, от имени которого запущен демон, и с сетевой политикой этого рабочего пространства, поэтому автономное рабочее пространство его отклоняет. Полученные байты проверяются по дайджесту, который записан для них в собственном манифесте артефакта, и ни по чему другому — подпись не проверяется, об отзыве не сообщается, — и ничего не записывается. Ссылка, которую не удаётся прочитать, отклоняется с entity-not-resolvable, и сообщение начинается с короткого кода условия, объясняющего причину, — тех же условий, о которых сообщает aggrega inspect, — и заканчивается тем, что с этим делать. Ссылка, не называющая репозиторий или не содержащая ни тега, ни дайджеста, является некорректным запросом и отклоняется как invalid params.
Замыкание — это не граф
aggrega/irGraph и aggrega/releaseClosure получаются из одного и того же разрешения одной и той же сущности Release, но отвечают на разные вопросы. Клиент, который уже получает граф, может вполне резонно предположить, что у него есть и это, но это не так.
Граф показывает, что развёртывает Release: его узлы, границы, в которых они находятся, что с чем связано, а также значения и вложения каждого узла. Это картина.
Замыкание показывает, что было подтянуто для его сборки и в каких версиях. Каждая сущность, до которой доходит Release, независимо от того, стала ли она узлом; общие документы, на которые опираются эти сущности; и плагины, формирующие вывод. Это спецификация материалов.
Ни одно из них нельзя восстановить из другого. До сущности можно дойти, так и не увидев её в виде узла: Recipe, на которую Manifest отображает тип компонента, достигается каждой сборкой и не является узлом ни в одной из них, а узел не несёт версию, в которую разрешился его тип. Поэтому читатель, спрашивающий «почему изменилась эта версия?», «на что повлияет изменение этого общего документа?» или «от чего на самом деле зависит эта сущность Release?», запрашивает замыкание, а читатель, спрашивающий «что развёртывает эта сущность Release?», запрашивает граф.
Чего не делает запрос замыкания. Он ничего не рендерит и не публикует ничего из того, что находит. В частности, он не выдаёт ни предупреждения о дрейфе, ни рекомендации рендеринга: они принадлежат запросу, который их запросил, а публикация заменяет целый слой диагностики, так что список, который что-то публикует, стёр бы то, что запрос графа уже показал пользователю. Запрашивайте граф, если вам нужен вердикт о дрейфе. Единственное, что он всё же публикует, — не его собственная находка: запрос, обнаруживший, что lockfile пропал, снимает основанное на нём предупреждение о дрейфе, какой бы это ни был запрос, — см. Отслеживание lockfile.
Ему нужен lockfile, как и графу. Версии, которые сообщает список, — это те, в которые разрешилась данная сущность Release, а в рабочем пространстве, которое никто не подготовил, они ещё не разрешены. Список, полученный без lockfile, сообщал бы то, что каталогу довелось содержать сегодня, а это другой вопрос, нежели то, от чего зависит данная сущность Release. В отказе указываются lockfile и сущность Release, так что клиент может сразу предложить aggrega pull --release <release>.
kind в элементе замыкания присутствует, только если он известен. Ссылка собирается из позиции в документе, и одни позиции указывают, на какой вид они ссылаются, а другие нет. Поле сообщается там, где место ссылки записало вид, и опускается там, где не записало, а не угадывается по форме имени. Оно сообщается в виде слова, которое автор пишет в начале документа, — того же слова, которое для того же элемента использует любая поверхность, сообщающая замыкание.
То же слово запрашивает тот же документ и в других местах. aggrega inspect <release> --closure отвечает на этот вопрос в командной строке, а режим release инструмента describe — по протоколу инструментов ассистента. Все три выполняют одно разрешение для сущности Release, поэтому не могут разойтись в том, от чего зависит Release. См. aggrega inspect, раздел «The dependency closure» («Замыкание зависимостей»).
Модель кэша
Операции опираются на кэш: вызовите aggrega/validate для файла перед hover / completion / resolve / diagnostics по нему. Этому начальному вызову не нужен Release — валидация без указания релиза всё равно разбирает буфер и заполняет кэш, — поэтому эти операции работают и в рабочем пространстве, где нет Release, который можно было бы указать. При каждом чтении кэш разбора сверяется со временем изменения каждого файла на диске, поэтому внешние правки (сохранение в редакторе, git checkout) подхватываются автоматически — вызов aggrega/invalidate из редактора является оптимизацией, а не условием корректности.
Кэш принадлежит рабочему пространству, которое его заполнило. Файл, прошедший валидацию в одном рабочем пространстве, кэшируется для этого рабочего пространства, поэтому о том же пути, запрошенном в другом, сообщается как о ещё не прошедшем валидацию, а не даётся ответ из записи первого. Именно это не позволяет вопросу о втором рабочем пространстве ни дать неверный ответ, ни лишить первое его прогретого состояния — и aggrega/invalidate точно так же очищает только указанное в нём рабочее пространство.
Запрос диагностики во время выполнения валидации
Валидация заполняет для файла две вещи — разбор, который она передаёт другим операциям, и найденные проблемы, о которых она сообщает, — и заполняет их с небольшим промежутком. aggrega/diagnostics — единственный запрос, который читает и то и другое: разбор нужен ему, чтобы знать, что о файле можно отвечать, а отвечает он на основе найденных проблем. Поэтому запрос, пришедший между этими двумя моментами, решил бы, что может ответить, когда отвечать ещё нечем.
Вместо этого он ждёт. Если отправить aggrega/diagnostics для файла, который проходит валидацию прямо сейчас, ответ придёт, когда эта валидация завершится, и будет содержать то, что она нашла. При любом порядке событий для файла есть один правильный ответ, и именно его вы получаете — это никогда не пустой список для файла, валидация которого вот-вот сообщит об ошибках; это единственный неверный ответ, после которого клиент не может восстановиться, потому что ничто не побуждает вас снова спросить о файле, про который вам сказали, что он чист. Остальные позиционные операции — hover, completion, resolve, findReferences, findImplementations — читают разбор и отвечают на его основе, поэтому им нечего ждать и они никогда не ждут.
Ожидание досрочно прекращают две вещи, и обе у вас уже есть. Его останавливает $/cancelRequest с идентификатором этого запроса, и его останавливает кооперативный aggrega/shutdown. Ни то ни другое не требует ничего дополнительного в запросе.
И ожидание ограничено. Если валидация не завершилась в пределах отведённого ей демоном времени, запрос отклоняется с кодом «валидация выполняется», а не получает пустой ответ — см. Коды ошибок. Такой отказ означает, что работа, которую вы ждёте, действительно идёт, поэтому следует вскоре спросить снова; это не сигнал отправить ещё одну валидацию, которая добавила бы работы и ничего не дала бы в ответ.
Демон, выполняющий запросы по одному, отвечает на них в порядке поступления, поэтому ничего не перекрывается и ожидания не возникает. Демон, выполняющий их параллельно, отвечает на те же вопросы так же, и именно ожидание обеспечивает это: вы получаете тот ответ, который дал бы вам последовательный порядок.
Размеры в ответе
Ответ, сообщающий количество байтов, сообщает его дважды: числом и той же величиной,
записанной текстом. Имя текстового поля — это имя числового поля с добавленным Text — size и
sizeText, totalSize и totalSizeText, reclaimedBytes и reclaimedBytesText и так далее
во всех ответах, содержащих размер.
Показывайте текстовую форму, а вычисления выполняйте с числом. Смысл отправки обеих в том, что клиенту
никогда не нужно самому записывать размер: демон записывает его тем же форматтером, что и командная строка,
поэтому aggrega cache status и aggrega/cacheStatus показывают данный кэш одинаково, вплоть до
округления. Клиент, составляющий собственный текст, разошёлся бы с этим при первом же расхождении
на границе.
Текстовая форма использует двоичные единицы — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB, — то есть тот же
словарь, который aggrega/cacheEvict принимает в maxSize, поэтому размер, прочитанный из одного ответа, можно отправить
обратно в следующем запросе, не переписывая его. Для величин больше байтов текст содержит один знак после запятой, поэтому
он называет величину так, как её хочет видеть читатель, а не с точностью до байта; когда нужно точное
значение, для этого и служит числовое поле.
Там, где число необязательно, вместе с ним необязателен и текст, и они никогда не присутствуют наполовину:
размер плагина в ответе на публикацию содержит pluginSize и pluginSizeText вместе либо не содержит
ни того ни другого.
Каждый запрос называет рабочее пространство, к которому относится
Передавайте workspaceRoot в каждом запросе: абсолютный путь к корню рабочего пространства, с которым
работает этот запрос. У демона нет собственного рабочего пространства, и между запросами он ничего не запоминает, поэтому
ответ на запрос касается только названного в нём рабочего пространства и ничего другого. Два запроса с двумя рабочими пространствами получают
два ответа, и ни один не видит чужих сущностей, Releases, кешированных результатов разбора или диагностик.
Запрос, не называющий рабочего пространства, отклоняется стандартной ошибкой invalid-params с именем параметра, как и пустое значение, которое не указывает рабочего пространства и обрабатывается как отсутствующее. По той же причине отклоняются ещё два варианта, каждый из которых назван в сообщении: относительный путь, поскольку корню рабочего пространства не от чего отсчитываться; и путь, не являющийся существующим каталогом, поскольку рабочее пространство — это дерево.
Трём запросам не нужен workspaceRoot, и у каждого причина в том, что его предмет — не рабочее пространство. aggrega/getSchema и aggrega/scaffoldEntity отвечают по схемам, скомпилированным в запущенный исполняемый файл, поэтому рабочее пространство ничего не добавляет ни к одному из них — именно это позволяет обоим отвечать в каталоге, который никто не подготовил. Третий — aggrega/initialize: в нём рабочее пространство объявляют, а не работают с ним. Другая форма aggrega/scaffoldEntity — запись или вывод списка готовых к запуску примеров документации — всё же работает с рабочим пространством, и запрос к ней указывает его, как и любой другой.
Кешированное состояние каждого рабочего пространства хранится отдельно, и упоминание второго ничего не стоит
первому. Индекс каталога, кеш разбора и диагностики рабочего пространства принадлежат этому
рабочему пространству, поэтому вопрос о другом месте не вытесняет то, что редактор
накопил для открытой у кого-то папки. Два написания одного корня — это одно рабочее пространство, поэтому
путь с внутренним . или удвоенным разделителем приводит к тому же прогретому состоянию, что и его обычная форма.
Объявление рабочего пространства, для которого нужно отправлять диагностики
Диагностики доставляются двумя способами: вы запрашиваете их, или демон отправляет их сам. Демон отправляет их только для рабочего пространства, объявленного вами при рукопожатии. Любой другой запрос возвращает свои результаты в собственном ответе и ничего не отправляет.
Чтобы объявить его, передайте workspaceRoot в aggrega/initialize. Больше это
объявление ничего не делает — оно ничего не привязывает, и ни один последующий запрос не обрабатывается относительно него.
Причина такого ограничения — в назначении отправляемой диагностики. Отправка поддерживает список проблем редактора в актуальном состоянии, пока человек печатает, и это совершенно неуместно для ответа, который никто не просил показать: без этого правила вопрос о втором рабочем пространстве — например, от другого инструмента, использующего тот же демон, — заполнил бы список проблем читателя результатами о файлах, которые он никогда не открывал. Ограничение отправки не пускает вопрос одного вызывающего в список проблем другого.
Поле необязательно, и три смысла, которые можно в него вложить, различимы:
| что вы передаёте | куда отправляются диагностики | что сообщает рукопожатие |
|---|---|---|
| ничего | рабочее пространство, над которым запущен процесс | это рабочее пространство |
| корень рабочего пространства | это рабочее пространство | это рабочее пространство |
| пустую строку | никуда — диагностики никогда не отправляются | пустой корень |
Если ничего не передать, отправка остаётся направленной на рабочее пространство, над которым запущен процесс, поэтому клиент, ничего не объявляющий, получает диагностики этого рабочего пространства. Пустая строка — честное объявление для вызывающего, который не является редактором и не поддерживает синхронизированный список проблем: каждый результат по-прежнему доходит до него — в ответе на запрос, который его породил.
Объявленное рабочее пространство разрешается точно так же, как названное в запросе, поэтому объявление с относительным путём или путём, не являющимся каталогом, отклоняется при рукопожатии, а не оставляет отправку диагностик направленной в неожиданное место.
Корень рабочего пространства и активный Release
Демон определяет каждое рабочее пространство, названное в запросе, так же, как его определяет любая команда aggrega, а в разделе Конфигурация описано, что закрепляет корень и в каком порядке. Для клиента важны два следствия. Файл .aggrega-config.yaml без блока workspace: корень не закрепляет: он по-прежнему вносит свои настройки, но одиночный файл настроек не может превратить каждый родительский каталог в корень рабочего пространства. А если ничто корень не закрепляет, используется рабочий каталог — демон запускается, и операции просто ничего не находят, а не отказываются выполняться.
Процесс также запускается над рабочим пространством — из --workspace-root или путём подъёма от своего рабочего каталога, — и это определение делает две вещи и ничего больше: задаёт размер пула рабочих потоков, который является свойством процесса, а не какого-либо запроса, и служит объявлением по умолчанию для отправляемой диагностики. Ни на один запрос не даётся ответ относительно него.
Конфигурация — это тот же каскад, который читает любая команда, и описан он в разделе Конфигурация. Демон добавляет лишь то, что прочтение каскада для каждого рабочего пространства выполняется один раз, когда это пространство впервые названо, и повторно используется для всех последующих запросов о нём. Файл конфигурации, который прочитал бы этот каскад и который является ссылкой, ведущей за пределы рабочего пространства, — собственный .aggrega-config.yaml рабочего пространства или принадлежащий CI оверлей рядом с ним, — не читается, как и в терминале, и ничто другое из того, что настраивал бы этот файл, не читается вместо него. От терминала отличается то, что всё же отвечает. Демон, запущенный над таким рабочим пространством, запускается и однократно сообщает об этом в свой поток ошибок; на запрос, называющий такое пространство, в любом случае даётся ответ следующим образом. aggrega/releaseCandidates и aggrega/catalogIndex — два запроса, перечисляющие содержимое рабочего пространства, — отвечают на него, читая его без какой-либо конфигурации: перечисляются собственные документы рабочего пространства, ни один каталог каталогов не читается, а задержанный файл указывается в unreadLinkedFiles независимо от того, встретился ли он при поиске. По этому имени клиент узнаёт, что конфигурация рабочего пространства ведёт за его пределы. Любой другой запрос, называющий это рабочее пространство, — сборка, граф, валидация, Release по умолчанию, действующая конфигурация, запись, а также aggrega/catalogIndex в терминах Release — определяется этой конфигурацией, поэтому отклоняется с ошибкой invalid-params, содержащей E0321 — read-leads-out-of-workspace в поле data ошибки, — и предложением, называющим ссылку и место, куда она ведёт. Рукопожатие также отвечает для такого рабочего пространства, сообщая defaults в качестве его configSource, поскольку ни один файл конфигурации не внёс ничего в то, чем отвечают перечисления. Удалите ссылку или сделайте так, чтобы она вела к файлу внутри рабочего пространства, и следующий запрос прочитает конфигурацию. Под файлами проекта находится глобальный уровень: файл, который указывает --config в командной строке, запустившей демон, — для каждого обслуживаемого им рабочего пространства; иначе файл, который указывает переменная окружения AGGREGA_CONFIG, если она задана; иначе расположение по умолчанию — в Windows aggrega\config.yaml внутри каталога, указанного переменной окружения APPDATA, а в остальных системах aggrega/config.yaml внутри каталога, указанного XDG_CONFIG_HOME, с откатом к ~/.config/aggrega/config.yaml, — загружаемое при наличии. Ниже находятся встроенные значения по умолчанию.
Операции, действующие над Release, принимают его как параметр; демон сам ничего не выбирает. Рабочее пространство по-прежнему объявляет, на какой Release оно указывает, и это объявление читает каскад из четырёх шагов: поле конфигурации build.authoring_release, затем файл-маркер .aggrega/active-release, затем эвристика «единственный Release в рабочем пространстве», затем откат только к Aggregate. Поэтому записанный вами маркер имеет приоритет над эвристикой, а маркер, называющий Release, который не удаётся загрузить, переходит к эвристике, а не к откату. Маркер, называющий Release за пределами рабочего пространства — по абсолютному пути, по пути, выходящему за корень, или через ссылку, ведущую за его пределы, — не читается, если только конфигурация вашего рабочего пространства не называет этот Release как build.authoring_release или как ключ workspace.releases: конфигурация — это способ добраться до Release, хранящегося вне рабочего пространства, а маркер — нет. Затем каскад продолжает работу точно так же, как для маркера, который не удаётся загрузить, и если он ни на чём не останавливается, trace объясняет причину в строке маркера, а reason — в своём предложении о маркере.
aggrega/activeRelease сообщает, что выбирает этот каскад, и это подсказка для клиента, а не настройка, по которой действует демон. Спрашивайте демон, а не читайте входные данные каскада самостоятельно: поле конфигурации и файл-маркер — два из четырёх входов, поэтому любой из них, который вы прочтёте, называет выбор рабочего пространства, только если именно он оказался победившим. Маркер, называющий Release, который не удаётся загрузить, — самый наглядный случай: каскад выбирает совсем другой Release, а читающий маркер сообщил бы тот, что не загрузился.
Каскад выполняется, когда вы спрашиваете, и не раньше, и из этого следуют два следствия, на которые можно полагаться. Рукопожатие остаётся быстрым при любом размере дерева, поскольку не ждёт обхода рабочего пространства. А ответ следует за рабочим пространством: запишите маркер — с помощью aggrega/setActiveRelease, который сам отвечает новым выбором, — измените конфигурацию, добавьте или удалите файл Release, затем спросите снова, и вы получите новый ответ от того же демона. Смена Release, с которым вы работаете, никогда не требует перезапуска демона — клиент отправляет другой release в следующем запросе.
Операции, которые ищут по всему рабочему пространству, а не в одном буфере, — completion, hover, resolve, findReferences и findImplementations, — перебирают YAML под корнем рабочего пространства, и этот перебор учитывает .gitignore. Вклад вносит каждый .gitignore от корня рабочего пространства до собственного каталога файла, причём побеждает ближайший, поэтому YAML-файл, игнорируемый вашим репозиторием, не предлагается как кандидат автодополнения и не сообщается как определение или ссылка. .gitignore, являющийся ссылкой, ведущей за пределы рабочего пространства, не читается, поэтому файл где-то ещё на машине никогда не решает, какие документы рабочего пространства участвуют в поиске. Поэтому вендорные деревья и сгенерированный вывод не попадают в межфайловые результаты без какой-либо отдельной настройки исключений, которую нужно поддерживать, — а документ, который вы ожидаете найти, но проигнорировали, не появится; это единственный случай, который стоит проверить, когда ссылка кажется пропавшей. Components и Features, которые completion также предлагает из ваших настроенных catalog_dirs, — это другое чтение: они берутся из этих каталогов в том виде, как они настроены, — тех же каталогов, которые читает сборка Release, когда конфигурация не задаёт этому Release собственных, или, для запроса, называющего Release, собственных каталогов этого Release, — поэтому сущности каталога каталогов предлагаются независимо от того, покрывает ли его .gitignore, — за исключением сущности за ссылкой, ведущей за пределы каталога, внутри которого должны оставаться чтения каталога каталогов: она не читается и не предлагается.
Запрос, называющий Release, читает каталоговые директории этого Release — те же, что читает его сборка в терминале: собственные, если конфигурация рабочего пространства задаёт их в workspace.releases, а иначе — catalog_dirs рабочего пространства. Это касается aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate и aggrega/lint, называющих Release, aggrega/attachCandidates и aggrega/attachmentContainer, адресованных узлу графа Release, и aggrega/connectionAtPosition, а также запросов из следующего раздела, когда они называют Release. Поэтому один сеанс отвечает для каждого Release в рабочем пространстве, где для каждого Release хранится свой вариант каталога, — каждому из его собственного варианта, и сверх пути к Release ничего передавать не нужно. Запрос, не относящийся к одному Release, — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover и resolve без указания Release, а также aggrega/attachCandidates, адресованный сущности или набору меток, — читает catalog_dirs рабочего пространства. Исключение — aggrega/lint, не называющий ни сущность, ни Release, в рабочем пространстве, которое называет Releases в workspace.releases: там он проверяет весь каталог по одному разу для каждого Release, и каждый проход идёт по директориям этого Release, как описано в разделе Публикация соглашений по запросу и при каждой правке. См. Собственные каталоговые директории для Release.
Ответ в терминах одного Release
aggrega/catalogIndex, aggrega/entityDefinition и пять запросов, начинающихся от курсора, — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences и aggrega/findImplementations — не относятся к одному Release, и каждый принимает необязательный параметр release, который привязывает его к одному. Это путь относительно корня рабочего пространства, к которому применяется тот же контракт, что и в других запросах, принимающих Release; значение, не указывающее на файл Release или указывающее на директорию, отклоняется, а не получает ответ в терминах рабочего пространства, который выглядел бы как ответ для Release.
Что достижимо для Release — для каждого запроса здесь: документы рабочего пространства в каталоговых директориях, которые читает его стек, и все документы рабочего пространства, не лежащие ни в одной каталоговой директории, — например, Release, его Aggregate и его Manifest, написанные рядом с каталогами. Документ рабочего пространства в каталоговой директории, которую читают только другие Releases, в ответ не входит: он не перечисляется, не разрешается и не предлагается. Именно это не даёт смешивать варианты одной сущности, хранящиеся рядом для разных Releases.
- Перечень. Если указан Release, перечисляются сущности, которые видит этот Release. Перечисляются Features, объявленные в каталоговых директориях этого Release, а документ рабочего пространства в каталоговой директории, которую читают только другие Releases, опускается, — поэтому рабочее пространство, хранящее вариант одной сущности для каждого Release, перечисляет тот единственный вариант, с которым собирается этот Release, а не все варианты рядом. Документ, не лежащий ни в одной каталоговой директории, — например, Release, его Aggregate и его Manifest, написанные рядом с каталогами, — входит в перечень каждого Release.
- Поиск по имени. Если указан Release, имя разрешается через каталоговые директории этого Release, поэтому имя, объявленное несколькими вариантами, разрешается в тот вариант, с которым собирается этот Release. Имя, которое его директории не разрешают, отклоняется с пояснением, называющим запись этого Release в
workspace.releases, поскольку поиск читал именно эту запись. Ссылка на реестр не принимает Release и при его указании отклоняется: она читается из реестра, который её публикует, какой бы Release ни был указан. - Hover и переход к определению. Если указан Release, ссылка под курсором сначала разрешается через каталоговые директории этого Release в порядке, заданном конфигурацией рабочего пространства, — так же, как при поиске по имени в терминах этого Release, — поэтому показанная сущность и открытый документ — это вариант, в который её разрешают эти директории, даже если документ рабочего пространства в другом месте объявляет то же имя. Только если ни один документ в этих директориях не отвечает на неё, просматриваются документы рабочего пространства, достижимые для этого Release. Если Release не указан, порядок обратный: сначала просматриваются документы рабочего пространства, так что ссылка, на которую отвечает документ рабочего пространства, сохраняет этот ответ, а собственные
catalog_dirsрабочего пространства используются, только если ни один документ не объявляет имя, — так находится сущность, которая есть только в настроенной каталоговой директории, в том числе вне дерева рабочего пространства. Если в редакторе открыта несохранённая копия документа, в который разрешают директории Release, и эта копия по-прежнему объявляет имя, ответ читается из копии, чтобы позиция попадала на строку, которую показывает редактор. - Автодополнение. Если указан Release, предлагаются имена, объявленные в документах рабочего пространства, достижимых для этого Release, вместе с Components и Features, объявленными в каталоговых директориях этого Release.
- Ссылки и реализации. Если указан Release, место в документе рабочего пространства, недостижимом для этого Release, не сообщается, поэтому вариант, хранящийся для другого Release, никогда не выводится как ссылка или реализация этого.
- Что можно присоединить к узлу графа.
aggrega/attachCandidates, адресованный узлу графа Release, всегда работает в терминах этого Release — см. What an attach-candidate response tells you (Что сообщает ответ о кандидатах на присоединение).
Если Release не указан, ответ даётся по собственным каталоговым директориям рабочего пространства, как описано в абзаце выше.
Обращение к реестру и запись
Большинство запросов здесь отвечают на основе рабочего пространства и уже закэшированных данных и ничего не записывают. Несколько названных запросов делают больше, и они делятся по двум независимым осям: к чему запрос обращается и как далеко распространяется то, что он изменяет.
Запросы, которые обращаются к реестру, делятся на читающие и публикующие. aggrega/resolveDependencies загружает то, что нужно сущности Release, а aggrega/build присоединяется к нему, когда — и только когда — его поле autoPull требует сначала разрешить зависимости; в этом случае он обращается к реестру и записывает lock-файл перед рендерингом; aggrega/registryUpdate обходит каждый настроенный реестр, чтобы перестроить локальный поисковый индекс; aggrega/pluginAdd ищет в настроенном реестре плагин, названный в запросе, и читает его опубликованные версии, чтобы закрепить одну; aggrega/registryAdd запрашивает у регистрируемого реестра политику доверия, которую тот объявляет, если только запрос не отказывается от загрузки или не передаёт собственную политику, а aggrega/configInit запрашивает то же у реестра, который он инициализирует; aggrega/explainError один раз получает пакет документации, из которого он читает разбор условия, если кэш, общий для всех проектов на машине, не содержит копии, которую допускает собственная проверка подписи рабочего пространства, — см. aggrega explain; aggrega/scaffoldEntity, которому отправлены example или list, получает тот же пакет на тех же условиях, а при записи затем помещает пример в новый каталог рабочего пространства; aggrega/import один раз загружает базовый импортёр из реестра рабочего пространства по умолчанию, если его ещё нет на машине, а в рабочем пространстве, не называющем ни одной папки каталога, также опубликованный снимок каталога, который он читает, — см. Что сообщает ответ на импорт; а aggrega/entityDefinition читает сущность, названную ссылкой на реестр, когда такая ссылка передана в его name, ничего не записывая. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts и aggrega/deprecateArtifact записывают в реестр — байты, подпись или маркер отзыва. Запрос обращается к реестру, только когда его отправили для этого: список сообщает то, что закреплено в конфигурации, поиск читает офлайн-снимок, а публикация, запрошенная с dryRun, вычисляет то, что она отправила бы, и ни к кому не обращается.
Правило касается того, когда выполняется операция, а не того, какая поверхность её выполняет. Операция, которая
загружает или записывает, выполняется потому, что её назвал запрос, и никогда не является побочным эффектом проверки
документа, просмотра графа или получения списка сущностей рабочего пространства. Поэтому редактор, проверяющий документ при каждом
нажатии клавиши, не обращается к сети и не переписывает lock-файл, а действие «разрешить зависимости», по которому
щёлкает пользователь, делает ровно то же, что aggrega pull, — то же разрешение за обеими поверхностями, записывая
побайтно идентичный lock-файл и заполняя тот же кэш артефактов.
Ничего не запрашивается интерактивно. За этим потоком никто не наблюдает, поэтому идентичность определяется из переданного или окружающего источника учётных данных и никогда — путём вопроса. Там, где команда терминала задала бы вопрос человеку — реестр, которому нужны учётные данные, возможность, которую обслуживают несколько плагинов-провайдеров, текст, который должен нести отзыв, — запрос завершается ошибкой с сообщением о том, что нужно передать, вместо ожидания ответа, который никогда не придёт. Отказ оставляет рабочее пространство в точности таким, каким оно было: lock-файл не записывается, частичных записей не остаётся, а публикация, которой не удалось получить учётные данные, отказывает до того, как какие-либо байты достигнут реестра.
Некоторые изменения выходят за пределы этого рабочего пространства, и ответ сообщает, какие
Запрос называет одно рабочее пространство, поэтому ответ, которому нечего сказать о собственном охвате, воспринимается как относящийся к этому рабочему пространству. Для ряда этих запросов такое прочтение было бы ошибочным, поэтому каждый из них содержит свою область действия, и клиенту следует показать её, прежде чем действовать на основе результата.
Публикация, подписание и отзыв полностью выходят за пределы машины — это самый широкий охват из всего, что здесь есть. Остальные операции записи ниже меняют то, что разрешает эта машина; эти же меняют то, что разрешают все, кто разрешает из этого реестра. Опубликованные байты — это то, что получает каждый потребитель этого реестра, а повторная публикация другого содержимого под тем же тегом отклоняется, а не предлагается, поэтому ни один запрос здесь не отменяет публикацию — решение состоит в публикации новой версии. Подпись и маркер отзыва прикрепляются как соседние объекты артефакта, а не заменяют его, поэтому сами байты остаются нетронутыми; но каждый, кто загрузит артефакт после этого, загрузит и их, и ни то ни другое нельзя отозвать у того, у кого они уже есть. Отзыв легче всего из трёх истолковать неверно: версия остаётся доступной для загрузки, тогда как отзыв, которому доверяет рабочее пространство, исключает её из того, что выберет разрешение в нём.
Подписание использует учётные данные, и откуда они берутся, стоит знать до подключения клиента.
Подписание без ключа получает токен идентичности по порядку: из identityToken в запросе, затем из
AGGREGA_IDENTITY_TOKEN в окружении демона, затем из окружающей конечной точки OIDC GitHub Actions,
если она доступна, затем из SIGSTORE_ID_TOKEN. Если ни один из этих источников не даёт токена, операция
отказывает и сообщает, что нужно передать; она никогда не открывает браузер, потому что смотреть в него некому.
Подписание с ключом — офлайн-альтернатива, и запрос не называет путь к ключу: то, что читает запрос,
находится внутри названного им рабочего пространства, а закрытый ключ никогда не хранится внутри рабочего пространства, поэтому
ключ берётся из блока signing: собственной конфигурации этого рабочего пространства. См.
aggrega sign о двух режимах подписания и о том, к чему обращается каждый.
Каждый из четырёх ответов содержит reach с полем registries — каждым хостом реестра, к которому
обращался вызов, по одному разу, в порядке первого обращения, так что пакет подписания или пакетный
файл, ссылки которого охватывают несколько реестров, называет каждый из них, — и полем beyondThisMachine, которое выводится
из того, что вызов фактически прикрепил, а не из того, что он запрашивал: true ровно тогда, когда он загрузил
содержимое или прикрепил подпись, дату публикации или маркер устаревания, и false для пробного запуска
и для вызова, который обнаружил, что всё, что он прикрепил бы, уже на месте, — повторная публикация
уже полной версии или пакет подписания, каждая ссылка которого уже имела
проходящую проверку подпись. Пробный запуск всё равно называет место назначения, к которому обратился бы. Показывайте его,
прежде чем действовать на основе результата.
Регистрация или удаление реестра по умолчанию записывает конфигурацию, общую для всех рабочих пространств на
машине. Реестр и идентичности, которым вы в нём доверяете, обычно одинаковы, где бы
вы ни работали, поэтому запись попадает именно туда, если запрос не передаёт workspace: true. Последствие
стоит сформулировать прямо: aggrega/registryAdd и aggrega/registryRemove меняют то, через что разрешает каждый
проект на этой машине, включая проекты, которые никто в этом сеансе не называл. Оба
ответа содержат scope с записанным файлом configFile и полем machineWide, сообщающим, является ли он
общим. Удаление — более серьёзное из двух, потому что повторное добавление — не то же самое действие: закреплённая политика
доверия утрачена, и последующая регистрация закрепит то, что реестр объявит в тот момент.
Инициализация конфигурации по умолчанию записывает тот же общий файл, и по той же причине. aggrega/configInit регистрирует реестр и его политику доверия, а это инструментарий уровня машины, поэтому без переопределения он записывает конфигурацию, через которую разрешает каждый проект на машине, — и один раз обращается к этому реестру, чтобы прочитать объявляемую им политику. Его ответ содержит ту же пару scope, что и два метода реестра. От них он отличается в одном, на что можно полагаться: он отказывает, а не перезаписывает существующий файл конфигурации, поэтому не может заменить конфигурацию, с которой кто-то работает, если запрос не передаёт force. Фиксация — противоположный случай: aggrega/configCapture вообще не принимает переопределения, всегда записывает собственный файл конфигурации проекта и не обращается ни к какому реестру, поэтому ничто из сделанного им не видно другому проекту. См. Что оставляет после себя запись конфигурации.
🔴 Добавление или удаление плагина-расширения команд по умолчанию записывает тот же общий файл, и именно этот случай следует прочитать внимательно. aggrega/pluginAdd и aggrega/pluginRemove принимают type, и тип решает, куда идёт запись, если переопределение не отправлено. Запись provider, governance, linter или importer влияет на сборку одного проекта, поэтому она попадает в собственную конфигурацию этого проекта. Запись cli — это инструментарий уровня машины, поэтому добавление типа cli, не указывающее ни global, ни workspace, регистрирует команду в глобальном файле конфигурации, через который выполняют разрешение все рабочие пространства на этой машине: команда становится командой верхнего уровня aggrega для каждого проекта на этой машине, включая проекты, которые никто в этом сеансе не называл, а отменить это можно только отдельным удалением, а не откатом. Отправьте workspace: true, чтобы оставить её локальной. Оба ответа содержат scope с записанным configFile и machineWide, сообщающим, общий ли это файл; значение выводится из файла, к которому была разрешена запись. Добавление также обращается к реестру, в котором выполняло поиск, поэтому оно находится сразу на обеих осях. См. Что сообщает изменение плагина.
Два других запроса к плагинам записывают только внутри рабочего пространства. aggrega/pluginSync записывает файл сущности Plugin, указанный в запросе, а aggrega/pluginGenCatalog записывает сгенерированные сущности в каталог outputDir, указанный в запросе, — оба внутри рабочего пространства, названного запросом, оба отклоняют абсолютный путь назначения или путь, разрешающийся за его пределы, и ни один не виден другому проекту. aggrega/pluginGenCatalog читает свой модуль и оверлей оттуда, где вы их выбрали, и это не расширяет область записи: они разрешаются по разным правилам, поэтому генерация может прочитать модуль, собранный где угодно, а создаваемые ею сущности всё равно окажутся внутри рабочего пространства. aggrega/pluginGenCatalog с dryRun вообще ничего не записывает и вместо этого возвращает содержимое.
Закрепление сущности тоже записывает только внутри рабочего пространства и обращается к хостам, которые называют её источники. aggrega/pin записывает entity.lock рядом с сущностью, указанной в запросе, — это путь внутри рабочего пространства, — и заполняет кэш содержимого рабочего пространства загруженными источниками; ничто из записанного не видно другому проекту. Он обращается наружу, чтобы разрешить каждый удалённый источник, названный сущностью, — репозиторий чартов, Git-хост, URL, — то есть с тем же охватом, что и aggrega/resolveDependencies для источников, которые потребляет сущность Release. aggrega/resolveDependencies и aggrega/publishEntity с pinSources выполняют этот же шаг, поэтому каждый из них тоже записывает рядом с закрепляемыми сущностями; публикация с закреплением, следовательно, затрагивает и рабочее пространство, и реестр. Публикация без закрепления ничего не записывает рядом с сущностью, но всё равно обращается к этим хостам: сравнение lock-файла с тем, что записал бы этот шаг, требует полной загрузки каждого удалённого источника, который указывает сущность.
Установка навыка ассистента остаётся внутри рабочего пространства, если запрос не передаёт global. aggrega/skillsInstall записывает папку навыков проекта каждого названного ассистента внутри рабочего пространства, названного в запросе, и ничто из записанного там не видно другому проекту; scope в его ответе содержит machineWide со значением false. С global: true он вместо этого записывает пользовательскую папку каждого ассистента в домашнем каталоге, которую этот ассистент читает в каждом проекте на машине, и machineWide равно true. В обоих случаях он не обращается ни к реестру, ни к сети.
Удаление сохранённых учётных данных затрагивает больше, чем что-либо ещё здесь, что не выходит за пределы этой машины. aggrega/logout изменяет хранилище учётных данных, а оно общее не только для всех проектов на машине, но и для всех других инструментов, аутентифицирующихся в тех же реестрах, — поэтому учётные данные, удалённые через сеанс, пропадают для всех них, и aggrega/registryList сообщит об их отсутствии и в любом другом рабочем пространстве. Ответ содержит scope с machineWide, которое всегда истинно: у этого хранилища нет формы уровня рабочего пространства, поэтому нет переопределения для отправки и нечего выбирать запросу. scope намеренно не называет файл, в отличие от записей конфигурации выше. Хранилище делегирует работу тому помощнику учётных данных или связке ключей ОС, которые настроены на машине, поэтому удаление часто обслуживается чем-то, что вовсе не является файлом, и указание пути направило бы вас к месту, которого удаление не обязательно касалось.
Удаление не является обратной операцией к аутентификации, и клиенту не следует предлагать его как таковую. Этот интерфейс удаляет учётные данные и не получает их: чтобы вернуть учётные данные, нужно снова аутентифицироваться с помощью aggrega login в терминале, потому что их сохранение требует секрета, введённого человеком, а за этим потоком никто не следит. Поэтому предлагаемый клиентом «выход» отсюда односторонний. Две операции разделяет то, должна ли операция получить что-то от того, кто ею управляет, — удаление несёт своё единственное значение в запросе, а получение учётных данных — нет, — а не то, участвует ли человек, ведь человек выбрал обе.
Освобождение содержимого кэша тоже выходит за пределы рабочего пространства. Хранилища скомпилированных модулей и описаний плагинов общие для всех проектов на машине, поэтому aggrega/cachePrune, aggrega/cacheEvict и
aggrega/cacheClear могут удалить содержимое, от которого зависит другой проект. Каждое удаление несёт reach
класса, из которого оно взято, а каждый ответ содержит scope.machineWideClasses. aggrega/cacheStatus
несёт тот же охват для каждого класса, хотя ничего не изменяет, потому что клиенту, решающему,
освобождать ли кэш, он нужен до действия.
Обновление поискового индекса устроено наоборот. aggrega/registryUpdate обращается к каждому
настроенному реестру, а то, что он записывает, попадает в собственный настроенный каталог кэша этого рабочего пространства, —
поэтому он не изменяет ничего, через что выполняет разрешение другой проект. indexRoot в ответе называет этот
каталог.
Частичное обновление отвечает, а не завершается ошибкой. Запрос, называющий один реестр, обновление которого не удалось,
является ошибкой, потому что ответить нечем. Запрос, обновляющий все настроенные реестры,
завершается успешно, даже если некоторые из них или все не обновились: обновлённые проиндексированы и записаны,
failed называет остальные, и каждый хост несёт свою ошибку. Читайте failed, а не наличие
ошибки.
Была ли достигнута связь с реестром, определяется ключом, а не чтением сообщения. Хост, обращение к которому не удалось,
несёт unreachable: true, если реестр так и не был достигнут — его имя не разрешилось, соединение
с ним было отклонено или не могло быть открыто, либо не удалось установить защищённое соединение, —
и отказ запроса, называющего один реестр, несёт тот же ключ в своём data.
Реестр, который был достигнут и ответил сбоем — повторяющимся списком или статусом ошибки, —
не несёт ни того ни другого, и его error или сообщение отказа говорит, что он ответил. Ключ определяется
по самому сбою, поэтому он не зависит от того, как резолвер этой машины формулирует сбой, и
устанавливается только там, где сбой показывает, что реестр не был достигнут: сбой, который ничего
не показывает ни в ту, ни в другую сторону, например истёкший лимит времени без записи о том, какой шаг он прервал,
сообщается без ключа. Называйте реестр недостигнутым по ключу, а ошибку показывайте как причину.
Командная строка сообщает об этом же обходе ненулевым кодом выхода, и от того, кто вы как читатель, зависит,
чего этот код стоит. Для человека в терминале это не весь отчёт: aggrega registry update
выводит, сколько выбранных реестров проиндексировано, что нашёл каждый, какие не
проиндексированы и куда записан индекс, — поэтому сводка говорит, что произошло, а код выхода говорит
лишь, всё ли прошло успешно. Для скрипта это весь отчёт, потому что команда не предлагает
режима структурированного вывода, и её код выхода — единственный доступный машиночитаемый вердикт. Поэтому
два интерфейса по-разному отвечают на один и тот же частичный обход и оба правы: этот передаёт
структурированному вызывающему failed и завершается успешно, а у командной строки есть один бит, и она тратит его на
вопрос «был ли пропущен какой-либо реестр».
Наблюдение за долгой операцией
Большинство запросов здесь отвечают на основе того, что уже есть на диске, и отвечают сразу. Некоторые сначала выполняют реальную работу — разрешают зависимости сущности Release, закрепляют её внешние входные данные, публикуют, подписывают, отзывают, — и вызывающая сторона ждёт. Такие запросы сообщают о том, что делают, по ходу работы, и это включается отдельно для каждого запроса.
Включение выполняется в два шага, в таком порядке.
- Объявите возможность при рукопожатии и дождитесь ответа. Отправьте
capabilities.window.workDoneProgress: trueвaggrega/initialize. Ничего больше не отправляйте, пока не придёт ответ: запросы обслуживаются параллельно, поэтому запрос, записанный до ответа на рукопожатие, может выполняться одновременно с рукопожатием, которое должно было согласовать параметры для него. Каждый клиент и так обязан протоколу соблюдать этот порядок; здесь от него зависит ещё одна вещь. - Поместите токен в параметры запроса. Добавьте
workDoneTokenв параметры запроса, о ходе которого хотите получать сведения. Значение выбираете вы — строку или число, — и именно оно связывает уведомления с этим вызовом. Создавайте новый токен для каждого вызова.
Уведомление. Каждое уведомление — это $/progress, где params.token равно вашему токену, а params.value несёт одну полезную нагрузку:
value.kind | содержит | когда |
|---|---|---|
begin | title — что происходит, фразой, которую можно показать читателю | один раз, когда работа начинается |
report | message — одна строка собственного отчёта операции о себе | любое число раз, по мере того как операция их пишет |
end | ничего, кроме вида | один раз, когда работа завершена |
Сопоставляйте по токену, а не по идентификатору запроса. Уведомление не содержит идентификатора — оно ни на что не отвечает, — и токен — единственное в нём, что указывает на ваш вызов. Так сделано намеренно: во многих клиентах идентификатор запроса принадлежит транспорту и не доходит до кода, выполнившего вызов, тогда как токен — значение, которое этот код уже хранит.
report несёт собственный текст компилятора. Сообщение — это одна строка, которую операция записала во время работы, переданная с удалёнными окружающими пробелами и без иных изменений — не переформулированная, не сокращённая, не пересобранная, — а строка, записанная операцией пустой, отбрасывается, а не передаётся как пустое сообщение. Поэтому клиент показывает полученное как есть. Это то же свойство, что и у собственной диагностики ответа: одно условие сохраняет одну формулировку, сколько бы поверхностей о нём ни сообщали.
Шаг, которого ждёт операция, — это тоже report. Когда операция входит в шаг, которого она ждёт, — чтение реестра, получение артефакта, компиляцию плагина, — report передаёт имя шага теми же словами, которые командная строка показывает для этого шага рядом со своим индикатором ожидания. Сообщается только о шагах, начатых между begin и end.
Одна строка вывода — один report. Операция, записывающая несколько строк сразу, порождает по уведомлению на строку, а строка, которую операция пишет по частям, передаётся после завершения — поэтому сообщение никогда не бывает половиной предложения.
Доли и процентов нет, и это не упущение, ожидающее доработки. Операции, которые здесь сообщают о ходе работы, обрабатывают набор, размер которого неизвестен в начале работы — сколько ссылок обходит разрешение, сколько слоёв загружает публикация, — поэтому любая доля была бы выдуманной. Показывайте неопределённый индикатор и последнее message.
Кадры приходят до ответа и никогда после него. begin приходит, когда работа действительно началась, поэтому запрос, отклонённый из-за параметров — абсолютного пути, отсутствующего обязательного поля, — не порождает ни одного уведомления, только свою ошибку. end приходит до ответа, а успешность операции указывается в ответе, а не повторяется в end.
Остановка работы — отдельное уведомление. Отправьте $/cancelRequest с идентификатором, под которым вы отправили запрос. Токен в отмене не участвует, и отмена не отменяет уже отправленные кадры.
Какие запросы сообщают о ходе работы и чего ждать от остальных
Сообщают ровно эти: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Для каждого из них верны две вещи, и обе — причина, по которой он в списке: он обращается к реестру или удалённому URL от вашего имени, поэтому его длительность определяется чем-то вне машины; и он уже пишет собственный отчёт о себе по ходу работы — тот отчёт, который читает человек у терминала. Поэтому сообщения о ходе работы передают вам этот же отчёт, а не второй, составленный для передачи, и ничего в работе операции не пришлось менять ради этого.
Любой другой запрос принимает токен и ничего не отправляет. Отправка токена безвредна, а не ошибочна: он принимается, уведомлений не приходит, а ответ в точности такой, какой был бы без него. Поэтому клиент может прикреплять токен к чему угодно и просто ничего не показывать, когда ничего не приходит.
🔴 Не считайте молчание признаком «этот запрос мгновенный». Большинство остальных действительно отвечают на основе того, что уже есть на диске — проверка, подсказка при наведении, автодополнение, граф, список кэша, чтение конфигурации, — но не все: обновление индекса реестра, добавление плагина, проверка перед публикацией и первое раскрытие кода на машине, где нет документации, доступной рабочему пространству, обращаются к реестру, а компиляция сущности Release — реальная работа. Они длятся сколько длятся и сегодня ни о чём не сообщают. Показывайте неопределённый индикатор для любого запроса, ответа на который вы готовы ждать, и считайте уведомления подробностями, которые вы получаете, когда они доступны, а не признаком того, что работа идёт.
Два отказа
Оба — ошибки invalid-params, и оба указывают, что делать, потому что токен, молча ничего не делающий, заставил бы вас ждать поток, который никогда не придёт.
- Токен из сеанса, который не объявил возможность
window.workDoneProgress, отклоняется с указанием возможности, которую нужно объявить. Объявите её при рукопожатии или не передавайте токен. - Токен, который не является ни строкой, ни числом, отклоняется с указанием двух допустимых форм. Отсутствующий токен и явный
nullне отклоняются — оба означают, что вы не запрашивали сведений о ходе работы.
Учёт lock-файла
Демон проверяет lock-файл на расхождение при каждом aggrega/irGraph относительно сущности Release, названной в этом запросе, и сообщает о расхождении неблокирующим предупреждением. Предупреждение называет команду, которая перезаписывает этот lock-файл с данной сущностью Release, в том написании, в каком её отправил запрос: aggrega pull --release, за которой следует отправленный вами release, — именно так её пишут в терминале в корне рабочего пространства. aggrega/irGraph требует наличия lock-файла. Отдельной проверки при запуске нет: запрос сообщает, к какой сущности Release он относится, поэтому вердикт вычисляется для этой сущности Release в момент запроса, а не один раз для одной заранее выбранной сущности Release.
Предупреждение о расхождении исчезает вместе с его lock-файлом. Предупреждение публикуется для lock-файла, по которому оно было выдано, а у lock-файла, которого больше нет, не осталось закреплений, которые могли бы разойтись: команда, названная в предупреждении, записала бы новый файл, а не исправила старый. Поэтому каждый запрос, обнаруживший отсутствие lock-файла, отзывает предупреждение, прежде чем отказать с ошибкой об отсутствии lock-файла: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates и aggrega/attachmentContainer с запросом об узле графа, а также aggrega/connectionAtPosition. Отзыв приходит уведомлением aggrega/publishDiagnostics для lock-файла с пустым списком перед отказом. Его отправляет тот из этих запросов, который первым узнаёт об удалении, поэтому у клиента, который сообщает об удалении, а затем запрашивает что угодно об этой сущности Release, предупреждение снимается без отдельного запроса графа. Lock-файл, который по-прежнему существует и по-прежнему расходится, сохраняет своё предупреждение при каждом из этих запросов. aggrega/invalidate с указанием lock-файла сбрасывает то, что демон хранит для него, но ничего не отправляет; клиенту об этом сообщает следующий запрос. А lock-файл, который демон не может даже проверить — например, потому что ему не разрешено читать его каталог, — ничего не отзывает, поскольку файл может всё ещё существовать, а предупреждение может быть всё ещё верным.
aggrega/build и aggrega/buildPreview тоже требуют lock-файл и не предупреждают, а требуют от сущности Release соответствия ему — они выполняют рендеринг в режиме поверхности, которая выпускает артефакт, поэтому lock-файл, больше не соответствующий тому, во что разрешается сущность Release, останавливает их там, где при инспекции было бы лишь предупреждение. Сущность Release без lock-файла отклоняется с ошибкой об отсутствии lock-файла. Исключение — сборка, поле autoPull которой требует сначала разрешить зависимости: такая сборка записывает lock-файл, а затем выполняет рендеринг по записанному, и lock-файл, полученный таким образом, повторно на расхождение не проверяется, поскольку разрешение, записавшее его, выполнило ту же проверку перед записью и не записывает lock-файл, который эта проверка отклоняет.
Lock-файл, который существует, но не содержит дайджеста для плагина, граф не останавливает — останавливает отсутствующий lock-файл. Это два разных условия, и отказ вызывает только второе. aggrega/irGraph не сверяет разрешаемые байты с записанными дайджестами: закрепление, которое нельзя проверить, сообщается, а не отклоняется, и граф отрисовывается с этой находкой на панели Problems, поскольку редактор, отказавшийся рисовать граф, оставляет читателя ни с чем, тогда как сообщение даёт ему, с чем работать. В остальных местах плагин тоже запускается — с предупреждением о том, что его байты никто не проверял. aggrega/irGraph отклоняет именно отсутствующий lock-файл: он останавливается, ничего не разрешив, и отвечает ошибкой об отсутствии lock-файла, называя искомый lock-файл и сущность Release, чтобы клиент мог сразу предложить aggrega pull --release <release> — или отправить aggrega/resolveDependencies для этой сущности Release и записать lock-файл, не покидая сеанса. Разделять эти два случая важно, потому что отрисованный граф — это картина, на основе которой читатель затем рассуждает, а граф, построенный из непроверенных байтов, выглядит точно так же, как проверенный, и находка при этом находится там, куда читатель не смотрит. Поэтому граф — не вердикт о стоящих за ним байтах: aggrega/build и aggrega/buildPreview — это поверхности, которые требуют от сущности Release соответствия записанным дайджестам и останавливаются там, где инспекция лишь сообщает.
aggrega/validate, когда запрос называет сущность Release, читает lock-файл этой сущности Release только ради закреплений и уведомлений об устаревании — и не читает никакого lock-файла для сущности каталога, которую проверяет как отдельную сущность, так же как командная строка. Он не сверяет запускаемые плагины с записанными дайджестами и не восстанавливает набор подключений transform-плагинов из lock-файла — он выполняет проверку по конфигурации рабочего пространства в её текущем виде, как и должен делать редактор, пока вы эту конфигурацию правите. aggrega validate и aggrega build делают и то и другое и остаются авторитетными поверхностями для вердикта о зафиксированном рабочем пространстве.
Его уведомления об устаревании охватывают оба места, где записывается отзыв. Маркер на закреплённой ссылке находится в lock-файле; маркер на плагине, подключённом в роли, которая возвращает вердикт «принять или отклонить», — подключении plugins.governance в ir-verdict или render-verdict либо подключении plugins.linter, — находится в записи доверия плагинов рядом с ним, поэтому проверка читает оба и называет каждую отозванную ссылку и каждый отозванный плагин предупреждением в начале Aggregate, в той формулировке, которую выводит aggrega build. Уведомление не меняет ни одного вердикта. Запись доверия, которая существует, но не может быть прочитана, сообщается как ошибка вместо проверки, а не читается как запись, в которой ничего не записано. aggrega/releaseClosure сообщает тот же набор в своём deprecations.
Где находится lock-файл сущности Release
Каждый ответ, называющий сущность Release, называет и её lock-файл, поэтому клиенту никогда не нужно вычислять путь. aggrega/activeRelease передаёт его как lockfile рядом с release, aggrega/releaseCandidates — как словарь lockfiles рядом с releases, а ошибка об отсутствии lock-файла — как lockfile в своём data. Каждый из них — это файл, который записывает aggrega pull --release <release> и читает aggrega build, и файл, наличие которого проверяет каждый из перечисленных выше запросов, — поэтому клиент, отслеживающий lock-файл сущности Release, чтобы заметить его запись, перезапись или удаление, отслеживает именно тот файл, который имеет в виду демон. Lock-файл лежит рядом со своей сущностью Release и получает её имя, в котором расширение .yaml или .yml заменено на .lock; сущность Release с любым другим расширением сохраняет имя целиком, так что lock-файл для release.rel — это release.rel.lock. Берите путь из ответа, а не составляйте его по этому описанию, и тогда они не разойдутся.
Внешние ссылки, запрашиваемые рендерингом
Рендеринг может запросить содержимое по удалённому URL — например, схему values чарта с удалённой ссылкой. Внешние входные данные заморожены для каждого рендеринга, который этот демон выполняет в ответ на запрос, лишь просивший о чём-то сообщить. Ссылка, закреплённая в lockfile сущности Release, обслуживается из хранилища с адресацией по содержимому — это чтение содержимого, уже находящегося на диске, а не загрузка, — и перед выдачей её байтов она сверяется с тем, что записано в lockfile, так что рендеринг здесь видит то же, что видит сборка, и выдаёт те же предупреждения, что выдаёт сборка. Ссылка, не закреплённая в lockfile, отклоняется, а не загружается: её получение потребовало бы обращения к сети и записи blob в хранилище, а сеанс не делает ни того, ни другого в ответ на запрос, лишь просивший о чём-то сообщить. Это правило из раздела Обращение к реестру и запись, прочитанное со стороны рендеринга, и оно действует независимо от того, каким путём был вызван такой рендеринг.
Исключение составляет запрос, существующий ради закрепления, и это то же исключение, которое уже содержит правило о реестре. aggrega/resolveDependencies просят получить содержимое, поэтому рендеринг, который он выполняет, чтобы выяснить, какие ссылки потребляет этот Release, обращается к сети и записывает то, что закрепляет, — именно поэтому его результатом является lockfile, а не отчёт. Ни один рендеринг, выполняемый запросом графа или сборки для себя, ничего из этого не делает.
Сборке, которую попросили сначала разрешить зависимости, отвечают из того же самого рендеринга, поэтому она рендерит Release один раз. Разрешение уже отрендерило то, о чём идёт речь в сборке, с только что записанными закреплениями и под теми же проверками, что выполняет сборка, поэтому сборка представляет этот рендеринг, а не выполняет второй, — и получение содержимого по-прежнему относится к разрешению, а не к сборке. Так используется только завершившийся рендеринг: если разрешение закрепило зависимости, но не смогло до конца выявить внешние ссылки, сборка рендерит сама с теми закреплениями, которые были записаны, а незакреплённая ссылка отклоняется и сообщается там точно так же, как в сборке, которая ничего не разрешала.
Об отклонении сообщается, а не умалчивается, потому что по результату никак нельзя понять, какой ссылки в нём не хватило. С провайдерами, входящими в этот бинарный файл, провайдер, запросивший ссылку, возвращает отказ, поэтому рендеринг, дошедший до отклонённой ссылки, не завершается. Поэтому каждая отклонённая ссылка приходит отдельной записью на слое aggrega-build, с указанием ссылки и команды, которая её закрепляет: aggrega pull --release <release> или aggrega/resolveDependencies — та же работа без выхода из сеанса. Эти записи являются предупреждениями, а не отказом — граф всё равно возвращается, с тем же статусом, что и у предупреждения о расхождении выше, — и они относятся к Aggregate в начале файла, потому что ссылка, запрошенная рендерингом, не указывает ни на один ключ, написанный автором. Они передаются в той же публикации, что и собственные предупреждения рендеринга, которая заменяет этот слой целиком, поэтому ссылка, которую вы затем закрепите, перестаёт сообщаться без какой-либо очистки. Полностью закреплённый рендеринг ничего из этого не сообщает. Форма каждой записи описана в разделе Что содержит запись диагностики.
Для aggrega/irGraph это зависит от того, выполняется ли этап рендеринга вообще. Запрос графа пропускает рендеринг, если его не включает --build-on-inspect или ключ serve.build_on_inspect, который этот флаг переопределяет; при выключенном переключателе ничто не запрашивает внешнюю ссылку и отклонять нечего. Именно его включение приносит в сеанс редактора и собственные предупреждения рендеринга, и эти.
Чем сеанс отличается от той же заморозки в командной строке. aggrega build также замораживает внешние входные данные при пробном запуске, и незакреплённая ссылка ведёт себя одинаково в обоих случаях: о ней сообщается как о находке с указанием ссылки, после чего рендеринг останавливается, потому что запросивший её провайдер возвращает отказ. Отличается повторная загрузка. В командной строке закреплённая ссылка, сохранённая копия которой пропала, загружается заново по записанному дайджесту; рендеринг, отвечающий на запрос графа или сборки, ничего не загружает повторно, потому что не обращается к сети, и поэтому не может вернуть закреплённую ссылку, которой больше нет в хранилище, — и такая ссылка не входит в описанные выше отклонения, которые указывают на то, что lockfile не закрепляет. Восстанавливает её запрос к сеансу на закрепление: названные выше запросы обращаются к сети и возвращают недостающие байты. О том, что загружает и записывает закрепление, см. aggrega pull.
Что сообщает отклонённый запуск
Запрос, завершившийся отказом, отвечает конвертом ошибки, и находки, уже сделанные запуском, не передаются внутри этого конверта — конверт вообще не содержит тела результата. Они доходят до вас так же, как при завершённом запуске: в виде публикации диагностики на слое aggrega-build, описанной в разделе Что содержит диагностическая запись. Поэтому клиент, обрабатывающий отказ, читает конверт, чтобы понять, что изменить, а свою панель проблем — чтобы увидеть, что нашёл запуск, и одно не заменяет другое. Отказ, возникший при рендеринге, — единственный отказ, который одновременно является находкой о том, что написал автор, поэтому он попадает в оба места, как описано в следующем разделе.
Эта публикация происходит независимо от того, дошёл ли запуск до конца. Запуск, остановившийся на полпути, всё равно нашёл всё, что предшествовало точке остановки, и читателю, потерявшему эти находки, пришлось бы запускать снова, чтобы их увидеть, — поэтому предупреждения публикуются по тому, до чего дошёл запуск, а отказ возвращается после этого. Это тот же набор с той же точностью, привязанный к тем же ключам авторского текста: отказ не низводит находку до фразы. Отклонённые внешние ссылки передаются в той же публикации, по той же причине и тем же путём.
Её ограничивает то, насколько далеко продвинулся запуск, а не то, что способен нести слой. Отказ одной из проверок, выполняемых до запуска компилятора, — замыкание сущности Release не удалось разрешить, Manifest сопоставляет тип с рецептом, который его не реализует, lockfile больше не соответствует тому, во что разрешается Release, закреплённая запись в кэше больше не соответствует записанному для неё дайджесту, и ни один каталог не содержит закреплённых байтов, — не имеет предупреждений для публикации, потому что ни одно ещё не было выдано. Тогда слой не несёт ничего, а не что-то устаревшее; а запуск, не дошедший до того, чтобы назвать документ, не публикует вообще ничего, оставляя то, что уже есть на вашей панели проблем, ровно в прежнем виде, а не очищая записи, о которых он ничего не узнал.
Отказ, возникший при рендеринге
О сущности Release, которую компилятор отклоняет во время рендеринга, — Workload, называющий слот, который его Component не объявляет, не выполненное утверждение, шаблон, который нельзя вычислить, реализация, не обеспечивающая того, что должна предоставить, — сообщается там, куда указывает отказ, и словами компилятора, в каждом запросе, который её рендерит: aggrega/build, aggrega/buildPreview и aggrega/irGraph с включённым этапом рендеринга. Ответом служит конверт ошибки с кодом -32603, чей message — это отказ со всеми причинами под ним, в тех же словах, что выводит командная строка для той же сборки: рендерящийся узел, затем то, что в нём отказало, каждая причина после той, которую она объясняет, — с коротким кодом условия в начале, если отказ называет зарегистрированное условие, как и любой отказ, называющий его. Его data называет документ, на который указывает отказ, как file, а диапазон ключа в нём — как line, column, end_line и end_column, рядом с code и shortCode условия; отказ, не называющий ключа или называющий ключ, которого нет в документе, несёт только file, а отказ, не указывающий ни на какой документ, называет Aggregate этой сущности Release.
Тот же отказ публикуется на слое aggrega-build, в этом документе, на этом ключе, как запись с серьёзностью error, несущая собственный keyPath отказа и message конверта без короткого кода перед ним, а также — если отказ называет зарегистрированное условие — code, shortCode и codeDescription этого условия, причём короткий код передаётся там в собственном поле. Он передаётся в той единственной публикации, которая несёт предупреждения, выданные запуском до остановки, поэтому заменяет слой так же, как они: следующий запуск этой сущности Release, выполняющий рендеринг, публикует слой без него, а документ, на котором он находился, публикуется пустым, что и удаляет его с вашей панели проблем.
Куда указывает отказ — это то, что называет сам отказ, и не точнее. Проверки сущности Workload оценивают документ, созданный её шаблоном, а шаблон может написать строки, которых не писал ни один автор, — цикл, условие, текст, импортированный из файла или библиотеки, — поэтому строка отрендеренной сущности Workload не соответствует строке сущности Recipe. Поэтому отказ, касающийся Workload, помещается на ключ workload сущности Recipe, а пути, которые он называет внутри отрендеренного документа, остаются в его сообщении. Не выполненное утверждение помещается на собственный ключ в assertions сущности Recipe или FeatureRecipe, которая его объявляет; утверждение, объявленное сущностью Component или Feature, выдаётся до того, как появляется документ, который можно назвать, и помещается на ключ kind: сущности Aggregate. Отказ на шаге, который называет документ, но не ключ, помещается на ключ kind: этого документа.
Отказ, объединяющий несколько находок, публикуется по одной находке. Композиция графа, на основе которого работает рендеринг, отказывает со всеми найденными нарушениями в одном отказе — запись, называющая цель, которой ничто не соответствует, два соединения одного компонента с одним псевдонимом, — и командная строка выводит каждое как отдельную диагностику под собственным заголовком. Здесь каждая — отдельная запись на слое aggrega-build, в документе и на ключе, которые называет эта находка, — в сущности Release, если её написала Release, в сущности Aggregate, если её написала Aggregate, — собственными словами и с собственными кодами. message ответа несёт все находки, а его data называет, куда указывает первая.
Значение, которое автор объявил конфиденциальным, здесь скрывается точно так же, как его скрывает командная строка. Текст отказа — это текст, выданный компилятором, ничто на этой поверхности его не переформулирует, а компилятор скрывает объявленное значение там, где выдаётся отказ, — на его месте <redacted>, — поэтому этот ответ, эта запись и терминал передают его одними и теми же словами; в разделе что отказ сообщает об объявленном значении описано, как именно, и какие отказы находятся вне этого.
Отказ проверки, выполняемой до рендеринга, — это не то же самое. Перечисленные выше проверки отвечают так, как описано в Что всё же сообщает отклонённый запуск. Утверждение, объявленное сущностью Component или Feature, и отказ по скомпонованному графу находятся между ними: каждый выдаётся до рендеринга каждым запросом, который разрешает граф сущности Release, поэтому aggrega/irGraph отвечает им и публикует его, как описано выше, и при выключенном этапе рендеринга; aggrega/releaseClosure, aggrega/attachCandidates и aggrega/attachmentContainer, запрошенные об узле графа, а также aggrega/connectionAtPosition отвечают тем же конвертом и ничего не публикуют, потому что у них нет панели проблем.
Коды ошибок
Ответы используют стандартные коды ошибок JSON-RPC, а также диапазон кодов уровня приложения 1xxx. Клиент-редактор может ветвиться по коду, не разбирая сообщение.
1001file-not-validated — у демона нет для файла в его текущем состоянии ничего, на основе чего запрос мог бы получить ответ: нет результата разбора файла или, дляaggrega/diagnostics, нет результата разбора файла либо ничего хранимого для файла, что было бы ответом проверки для текста, который сейчас хранит демон. Отправьте для негоaggrega/validateи повторите запрос.1003lockfile-absent — у сущности Release, указанной в запросе, нет lockfile, а запрошенной операции он нужен.1004entity-not-resolvable — имя не совпало ни с одной сущностью ни в одном уровне каталога, ни в сущности Release, указанной в запросе; или ссылку на реестр, переданную в качестве имени, не удалось прочитать как сущность, и сообщение называет условие, объясняющее причину; или lockfile сущности Release является ссылкой, ведущей за пределы рабочего пространства, что отклоняется до того, как что-либо его прочитает, при этомdataназывает lockfile и Release, а сообщение начинается с короткого кода условия,E0321— см. границу рабочего пространства.1005shutting-down — демон завершает работу после уведомления о завершении и отклоняет новые запросы. Не повторяйте запрос к тому же подпроцессу.1006validation-in-flight — проверка файла выполняется и не завершилась в пределах времени, которое ей отвёл ожидающий запрос. Вскоре повторите запрос и ничего не отправляйте.
1002 не выделен и доступен для следующего условия, которому понадобится код.
File-not-validated и validation-in-flight сообщают о противоположных состояниях, и действия, которых они требуют, тоже противоположны. File-not-validated означает, что у демона нет для файла в его текущем состоянии ничего, на основе чего запрос мог бы получить ответ, — нет результата разбора файла или, для aggrega/diagnostics, нет результата разбора файла либо ничего хранимого для файла, что было бы ответом проверки для текста, который сейчас хранит демон: отправьте aggrega/validate и повторите запрос. Проверка, отменённая на полпути, оставляет файл в этом состоянии, потому что она ничего не сохраняет, а то, что более ранняя проверка нашла в другом тексте, не является ответом для текста, который сейчас хранит демон; более ранний ответ остаётся в силе, пока текст остаётся тем, который этот ответ проверил. Результаты, которые демон отправляет о файле, прочитанном им самим с диска, — lockfile, разошедшийся с ожидаемым состоянием, сущность Release, которая не загружается, — не являются проверкой текста, который есть у вас, поэтому на этот запрос они тоже не отвечают. В это состояние могут привести и две проверки разных текстов, отправленные с небольшим интервалом, когда первой завершилась та, чей текст сохранил демон: запрос отклоняется, хотя этот текст был проверен, а повторная проверка даёт на него ответ. Это сформулировано в терминах разбора, а не файла, потому что буфер, который не прочитает ни один парсер, находится именно в таком положении: проверка выполнилась и сообщила, что нашла, а результата разбора, на основе которого можно ответить, по-прежнему нет. Validation-in-flight означает, что проверка файла выполняется и не завершилась в пределах времени, которое ей отвёл ожидающий запрос: вскоре повторите запрос и ничего не отправляйте, потому что нужное состояние уже на подходе, а вторая проверка лишь добавит работы. Если считать их одним условием, клиент будет отправлять проверку именно тогда, когда это неверный шаг. Два диапазона значат для клиента разное: код 1xxx называет состояние рабочего пространства, которое пользователь может исправить, — проверить файл, сгенерировать lockfile, — а стандартный код, например invalid-params, называет некорректный запрос, который исправляет клиент, а не пользователь. Значение release, которое присутствует, но некорректно — абсолютное или указывающее за пределы корня рабочего пространства, — попадает во второй диапазон: исправлять нужно не рабочее пространство, а запрос. Отсутствие release не относится ни к одному диапазону, потому что это вовсе не ошибка; оно выбирает более узкий из двух ответов, описанных в разделе Проверка в реальном времени.
Ошибка может содержать объект data, и каждый ключ в нём называет одну вещь и только её. file — исходный документ, к которому относится сбой: проверяемый документ, сущность Release, загрузка которой не удалась, документ рабочего пространства, объявляющий имя, которое ничем не разрешилось, или документ, на который указывает отказ, возникший при рендеринге, — и именно в нём сопутствующие line и column указывают позицию. Эти два ключа сами необязательны: сбой, относящийся к документу целиком, содержит только file. lockfile — это lockfile. release — сущность Release, к которой относится ошибка, записанная так, как её назвал запрос, чтобы клиент мог составить aggrega pull --release <release>, не извлекая её из сообщения. unreachable сообщает, что реестр, указанный в отклонённом запросе, недоступен: его содержит отклонённое обновление индекса с указанием одного реестра, причём значение берётся из самого сбоя, а если реестр ответил, ключ отсутствует. Каждый ключ необязателен и присутствует, только когда у демона есть это значение; ни один не заменяет другой, поэтому то, на что указывает ключ, никогда не зависит от кода рядом с ним.
code и shortCode в data называют условие, о котором сообщает отказ, — в каждом отказе, сообщающем о зарегистрированном условии, каким бы ни был его числовой код: описательный код, по которому ветвится программа, и короткий код, который цитирует человек, — те же два идентификатора под теми же именами, что содержит диагностическая запись для того же условия, и они перечислены в таблице всех условий. Ветвитесь по code. Числовой код называет состояние запроса и остаётся одним и тем же для многих условий: сборка, отклонённая из-за того, что ссылка каталога ведёт наружу, и сборка, отклонённая из-за того, что имя ничем не разрешается, обе дают 1004, — а сообщение представляет собой текст, который может быть переформулирован, поэтому ни то ни другое не отличает одно условие от другого. Invalid-params — один из таких общих кодов: его получает и запрос, указывающий рабочее пространство, файл конфигурации которого ведёт за его пределы, и там read-leads-out-of-workspace сообщает, что ошибка в структуре рабочего пространства, которую исправляет человек, а не в запросе. Отказ, не сообщающий о зарегистрированном условии, не содержит ни одного из этих ключей, и они присутствуют либо вместе, либо не присутствуют вовсе. Сообщение отказа, называющего условие, начинается с его короткого кода, E0321: …, один раз — в такой форме человек встречает его в каждом таком отказе; отказу, сообщение которого уже начинается с заголовка в квадратных скобках с кодом (однострочный отчёт о документе каталога, отклонённом при загрузке), код повторно не добавляется.
Отчёт о том, как выполнялся каскад выбора Release рабочего пространства, передаётся в ответе aggrega/activeRelease, в поле trace, а не в ошибке: рабочее пространство, не указывающее ни на одну сущность Release, — обычное состояние, а не неудавшийся запрос. Это диагностический текст, написанный для чтения человеком, а не структура для разбора. Показывайте его как есть — записывайте в журнал или в панель, которую может открыть пользователь, — и не сопоставляйте его с шаблонами, не извлекайте из него значения и не ветвитесь по используемым в нём меткам: его формулировки, структура и эти метки следуют за самим каскадом и меняются всякий раз, когда меняется каскад. Клиент, который просто передаёт текст, продолжает работать после такого изменения; клиент, который заучил его форму, на нём ломается.
См. также
- ../schema/other/serve-wire.md — формы сообщений, которыми обменивается этот протокол, сгенерированные из опубликованной схемы: объект параметров каждого метода, каждый результат и полезная нагрузка каждого уведомления, поле за полем.
- ./aggrega-build.md — команда сборки, конвейер компилятора, проверки и разрешение зависимостей которой выполняет и
aggrega/build, так что обе поверхности записывают одно дерево вывода, а не два. - ./aggrega-version.md — команда версии, с помощью которой расширение редактора проверяет совместимость с демоном.
- ./aggrega-pull.md — lockfile, который читает поверхность расхождений демона.
- ./aggrega-lint.md — соглашения о публикации, о которых демон сообщает по запросу, а также при каждой валидации, если включён
serve.lint_on_validate.
Синтаксис
aggrega serve [flags]Описание
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.Флаги
| Флаг | По умолчанию | Описание |
|---|---|---|
--build-on-inspect | false | Выполнять этап рендеринга артефактов при инспекции графа IR, чтобы предупреждения, которые aggrega build выдаёт во время рендеринга, также отображались как проблемы в редакторе. Не добавляет ни одной из проверок, на которых сборка останавливается. На диск ничего не записывается: ни отрендеренных артефактов, ни каталога вывода, ни lockfile. По умолчанию выключено, как и в aggrega inspect, которая тоже не выдаёт таких предупреждений. Если задан, переопределяет ключ конфигурации serve.build_on_inspect. |