Esquema do diagnóstico compartilhado dos plugins Wasm do Aggrega
Referência gerada. Não edite à mão — gere 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 compartilham. Um plugin informa uma entrada por problema que levanta; o host a apresenta. A forma é um superconjunto: cada socket preenche o subconjunto que usa e omite o restante, de modo que um diagnóstico de qualquer socket é uma única estrutura uniforme. severity é um de três valores que todos os sockets compartilham — halt, warn ou info —, de modo que um diagnóstico carrega o mesmo significado qualquer que seja 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 informam nesta única forma, de modo 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 restante: 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 veredito de governança define a severity e a message do resultado do build e pode adicionar 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, tirada de um único conjunto fechado que todos os sockets compartilham. halt interrompe o build e nomeia o que corrigir. warn é apresentado ao lado de um build que ainda assim é concluído. info registra a observação e deixa o resultado do build inalterado. Todo emissor informa a partir deste único conjunto, de modo 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 carrega, quando a regra emissora atribui uma (uma regra de evolução de esquema). Ausente para diagnósticos que não carregam 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 se refere (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 dica de correção opcional que o emissor oferece junto com o diagnóstico. Ausente quando nenhuma dica é oferecida. |
Não são permitidas propriedades adicionais.
Location
Para onde um diagnóstico aponta. Ele carrega um único localizador unificado que serve tanto a uma posição precisa ao byte no texto de origem bruto (um parser preenche span) quanto a uma posição estruturada dentro de um documento de origem (um renderizador preenche key_path, uri, line e kind), e nomeia a instância do build a que o diagnóstico se refere, quando houver uma (instance). Todo campo é opcional; um socket preenche a representação que consegue produzir e omite o restante.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
span | Span | não | O intervalo de bytes de origem brutos que o diagnóstico localiza, quando o emissor analisa a origem e consegue fixar o problema em um intervalo de bytes (um parser). Ausente caso contrário. |
key_path | string | não | Um caminho com pontos até o 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 artefato de origem a que o diagnóstico se refere, quando o emissor o conhece (um renderizador). Ausente caso contrário. Ele nunca nomeia uma instância do build; quem a carrega é instance. |
line | integer | não | Um número de linha dentro do documento de origem estruturado, distinto da linha e da coluna de bytes brutos carregadas 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 nomeia 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 do build a que o diagnóstico se refere, pela identidade que o build lhe dá: 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 o build deriva pela identidade que o build compõe para ele, e um módulo pelo seu próprio caminho. Presente quando o diagnóstico trata de 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 os acompanham 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, de modo 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.