Общая схема диагностики Wasm-плагинов Aggrega
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/wasm-diagnostic-v1beta1.schema.json
Единая форма диагностики, общая для всех сокетов Wasm. Плагин сообщает по одной записи на каждую выявленную проблему; хост выводит её. Форма является надмножеством: каждый сокет заполняет используемое им подмножество и опускает остальное, поэтому диагностика от любого сокета имеет одну единообразную структуру. severity принимает одно из трёх значений, общих для всех сокетов, — halt, warn или info, — поэтому диагностика несёт один и тот же смысл независимо от того, какой сокет её выдал.
Тип верхнего уровня: object
Определения
Diagnostic
Одна проблема, выявленная источником диагностики: уровень серьёзности, понятное человеку сообщение, необязательное местоположение и необязательные поля, специфичные для источника. Источником может быть сокет Wasm-плагина или сам компилятор — оба сообщают в этой одной форме, поэтому читатель интерпретирует запись одинаково независимо от того, кто её выдал. Каждый заполняет используемое им подмножество и опускает остальное: парсер задаёт диапазон location, импорт задаёт code и source_ref, линтер публикации задаёт rule_id и classification, вердикт governance задаёт severity и message, определяющие результат сборки, и может добавить любые из code, rule_id, classification, source_ref, location и suggest, а рекомендация рендеринга задаёт code, source_ref и структурированное location.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
severity | string (enum) | да | Уровень серьёзности диагностики из одного закрытого набора, общего для всех сокетов. halt останавливает сборку и указывает, что нужно исправить. warn выводится вместе со сборкой, которая всё же завершается. info фиксирует наблюдение и не меняет результат сборки. Все источники используют этот один набор, поэтому читатель интерпретирует уровень серьёзности одинаково независимо от того, кто его выдал. Допустимые значения: "halt", "warn", "info" |
message | string | да | Понятный человеку текст диагностики. |
code | string | нет | Необязательный стабильный, пригодный для машинного сопоставления код диагностики, не зависящий от понятного человеку сообщения. Отсутствует, если источник не назначает код. Код может исходить от сокета плагина или от собственных рекомендаций компилятора, которые задают его в каждой выдаваемой записи. |
rule_id | string | нет | Идентификатор правила, породившего диагностику, если источник основан на правилах (линтер публикации). В остальных случаях отсутствует. |
classification | string (enum) | нет | Классификация влияния на семантическую версию, которую несёт диагностика, если её назначает выдавшее правило (правило эволюции схемы). Отсутствует у диагностик без классификации. Допустимые значения: "PATCH", "MINOR", "MAJOR" |
source_ref | string | нет | Непрозрачная ссылка на элемент исходных данных, к которому относится диагностика (например, идентификатор исходного узла, который импорт не смог разрешить). Отсутствует, если диагностика не ссылается на конкретный элемент исходных данных. |
location | Location | нет | Место, на которое указывает диагностика, если источник может определить местоположение проблемы. Парсер заполняет диапазон байтов; рендерер заполняет структурированную позицию в исходном документе. Отсутствует, если у диагностики нет местоположения. |
suggest | string | нет | Необязательная подсказка по исправлению, которую источник предлагает вместе с диагностикой. Отсутствует, если подсказка не предлагается. |
Дополнительные свойства не допускаются.
Location
Место, на которое указывает диагностика. Содержит один унифицированный локатор, который служит как для точной до байта позиции в необработанном исходном тексте (парсер заполняет span), так и для структурированной позиции в исходном документе (рендерер заполняет key_path, uri, line и kind), и называет экземпляр сборки, к которому относится диагностика, если такой есть (instance). Все поля необязательны; сокет заполняет то представление, которое может сформировать, и опускает остальное.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
span | Span | нет | Диапазон необработанных исходных байтов, на который указывает диагностика, если источник разбирает исходные данные и может привязать проблему к диапазону байтов (парсер). В остальных случаях отсутствует. |
key_path | string | нет | Путь через точку к проблемному элементу в структурированном исходном документе, если источник определяет местоположение проблемы структурно (рендерер). В остальных случаях отсутствует. |
uri | string | нет | Идентификатор исходного артефакта, к которому относится диагностика, если источнику он известен (рендерер). В остальных случаях отсутствует. Он никогда не называет экземпляр сборки; это делает instance. |
line | integer | нет | Номер строки в структурированном исходном документе, отличный от строки и столбца необработанных байтов, которые несёт span. Присутствует, если источнику известна строка документа (рендерер). В остальных случаях отсутствует. |
kind | string | нет | Открытая строка, называющая поверхность исходных данных, к которой относится местоположение, если источник различает поверхности (рендерер). В остальных случаях отсутствует. |
instance | string | нет | Экземпляр сборки, к которому относится диагностика, по идентичности, которую ему даёт сборка: компонент — по имени, под которым его объявляет сущность Aggregate, компонент, добавленный модулем, — по его пути через модуль, записанному через точки, компонент, выводимый сборкой, — по идентичности, которую сборка для него составляет, а модуль — по его собственному пути. Присутствует, если диагностика относится к одному экземпляру; в остальных случаях отсутствует. |
Дополнительные свойства не допускаются.
Span
Диапазон исходных байтов: смещения в байтах — основное, точное местоположение, а номера строки и столбца сопровождают их для понятной человеку диагностики.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
start_offset | integer | да | Смещение первого байта диапазона в исходных данных в байтах, отсчёт с нуля. |
end_offset | integer | да | Смещение в байтах на единицу дальше последнего байта диапазона в исходных данных, так что end_offset минус start_offset — длина диапазона в байтах. |
start_line | integer | да | Номер строки начала диапазона, отсчёт с единицы, для понятной человеку диагностики. |
start_column | integer | да | Номер столбца начала диапазона, отсчёт с единицы, для понятной человеку диагностики. |
end_line | integer | да | Номер строки конца диапазона, отсчёт с единицы, для понятной человеку диагностики. |
end_column | integer | да | Номер столбца конца диапазона, отсчёт с единицы, для понятной человеку диагностики. |
Дополнительные свойства не допускаются.