Esquema do diagnóstico partilhado dos plugins Wasm do Aggrega
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/wasm-diagnostic-v1beta1.schema.json
A única forma de diagnóstico que todos os sockets Wasm partilham. Um plugin reporta uma entrada por cada problema que levanta; o host apresenta-a. A forma é um superconjunto: cada socket preenche o subconjunto que usa e omite o resto, pelo que um diagnóstico de qualquer socket é uma única estrutura uniforme. severity é um de três valores que todos os sockets partilham — halt, warn ou info —, pelo que um diagnóstico transporta o mesmo significado seja qual for o socket que o levantou.
Tipo de nível superior: object
Definições
Diagnostic
Um problema que um emissor de diagnósticos levantou: uma severidade, uma mensagem legível por uma pessoa, uma localização opcional e campos opcionais próprios do emissor. Um emissor é um socket de plugin Wasm ou o próprio compilador — ambos reportam nesta única forma, pelo que quem lê interpreta uma entrada da mesma maneira, seja quem for que a levantou. Cada um preenche o subconjunto que usa e omite o resto: um parser define um span de location, uma importação define code e source_ref, um linter de publicação define rule_id e classification, um veredicto de governação define a severity e a message do resultado do build e pode acrescentar qualquer um de code, rule_id, classification, source_ref, location e suggest, e um aviso de renderização define code, source_ref e uma location estruturada.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
severity | string (enum) | sim | A severidade do diagnóstico, retirada de um único conjunto fechado que todos os sockets partilham. halt para o build e indica o que corrigir. warn é apresentado ao lado de um build que ainda assim é concluído. info regista a observação e deixa o resultado do build inalterado. Todos os emissores reportam a partir deste único conjunto, pelo que quem lê interpreta uma severidade da mesma maneira, seja quem for que a levantou. Valores permitidos: "halt", "warn", "info" |
message | string | sim | O texto do diagnóstico legível por uma pessoa. |
code | string | não | Um código opcional, estável e comparável por máquina para o diagnóstico, independente da mensagem legível por uma pessoa. Ausente quando o emissor não atribui nenhum código. Um código pode vir de um socket de plugin ou dos próprios avisos do compilador, que definem um em cada entrada que levantam. |
rule_id | string | não | O identificador da regra que produziu o diagnóstico, quando o emissor é baseado em regras (um linter de publicação). Ausente caso contrário. |
classification | string (enum) | não | Uma classificação do impacto na versão semântica que o diagnóstico transporta, quando a regra emissora atribui uma (uma regra de evolução de esquema). Ausente para diagnósticos que não transportam nenhuma classificação. Valores permitidos: "PATCH", "MINOR", "MAJOR" |
source_ref | string | não | Uma referência opaca ao elemento de origem a que o diagnóstico diz respeito (por exemplo, o identificador de um nó de origem que uma importação não conseguiu resolver). Ausente quando o diagnóstico não faz referência a nenhum elemento de origem específico. |
location | Location | não | Para onde o diagnóstico aponta, quando o emissor consegue localizar o problema. Um parser preenche o intervalo de bytes; um renderizador preenche a posição estruturada dentro de um documento de origem. Ausente quando o diagnóstico não tem localização. |
suggest | string | não | Uma sugestão de correção opcional que o emissor oferece juntamente com o diagnóstico. Ausente quando não é oferecida nenhuma sugestão. |
Não são permitidas propriedades adicionais.
Location
Para onde um diagnóstico aponta. Transporta um único localizador unificado que serve tanto uma posição precisa ao byte no texto de origem em bruto (um parser preenche span) como uma posição estruturada dentro de um documento de origem (um renderizador preenche key_path, uri, line e kind), e indica a instância da compilação a que o diagnóstico diz respeito, quando existe uma (instance). Todos os campos são opcionais; um socket preenche a representação que consegue produzir e omite o resto.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
span | Span | não | O intervalo de bytes de origem em bruto que o diagnóstico localiza, quando o emissor analisa a origem e consegue fixar o problema num intervalo de bytes (um parser). Ausente caso contrário. |
key_path | string | não | Um caminho com pontos até ao elemento problemático dentro de um documento de origem estruturado, quando o emissor localiza o problema estruturalmente (um renderizador). Ausente caso contrário. |
uri | string | não | Um identificador do artefacto de origem a que o diagnóstico diz respeito, quando o emissor o conhece (um renderizador). Ausente caso contrário. Nunca indica uma instância da compilação; é instance que a contém. |
line | integer | não | Um número de linha dentro do documento de origem estruturado, distinto da linha e da coluna de bytes em bruto transportadas por span. Presente quando o emissor conhece uma linha do documento (um renderizador). Ausente caso contrário. |
kind | string | não | Uma string aberta que indica a superfície de origem a que a localização se refere, quando o emissor distingue superfícies (um renderizador). Ausente caso contrário. |
instance | string | não | A instância da compilação a que o diagnóstico diz respeito, pela identidade que a compilação lhe atribui: um componente pelo nome sob o qual o Aggregate o declara, um componente que um módulo contribui pelo seu caminho separado por pontos através do módulo, um componente que a compilação deriva pela identidade que a compilação compõe para ele, e um módulo pelo seu próprio caminho. Presente quando o diagnóstico diz respeito a uma instância; ausente caso contrário. |
Não são permitidas propriedades adicionais.
Span
Um intervalo dos bytes da fonte original: os deslocamentos em bytes são a localização primária e exata, e os números de linha e de coluna acompanham-nos para diagnósticos legíveis por uma pessoa.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
start_offset | integer | sim | O deslocamento em bytes do primeiro byte do intervalo na fonte original, a partir de zero. |
end_offset | integer | sim | O deslocamento em bytes uma posição após o último byte do intervalo na fonte original, pelo que end_offset menos start_offset é o comprimento do intervalo em bytes. |
start_line | integer | sim | O número da linha do início do intervalo, a partir de um, para diagnósticos legíveis por uma pessoa. |
start_column | integer | sim | O número da coluna do início do intervalo, a partir de um, para diagnósticos legíveis por uma pessoa. |
end_line | integer | sim | O número da linha do fim do intervalo, a partir de um, para diagnósticos legíveis por uma pessoa. |
end_column | integer | sim | O número da coluna do fim do intervalo, a partir de um, para diagnósticos legíveis por uma pessoa. |
Não são permitidas propriedades adicionais.