Esquema del diagnóstico compartido de los plugins Wasm de Aggrega
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/wasm-diagnostic-v1beta1.schema.json
La única forma de diagnóstico que comparten todos los sockets Wasm. Un plugin informa una entrada por cada problema que plantea; el host la presenta. La forma es un superconjunto: cada socket rellena el subconjunto que usa y omite el resto, de modo que un diagnóstico de cualquier socket es una única estructura uniforme. severity es uno de tres valores que comparten todos los sockets — halt, warn o info —, de modo que un diagnóstico lleva el mismo significado sea cual sea el socket que lo planteó.
Tipo de nivel superior: object
Definiciones
Diagnostic
Un problema que planteó un emisor de diagnósticos: una severidad, un mensaje legible por una persona, una ubicación opcional y campos opcionales propios del emisor. Un emisor es un socket de plugin Wasm o el propio compilador — ambos informan sobre esta única forma, de modo que quien lee interpreta una entrada de la misma manera sea quien sea quien la planteó. Cada uno rellena el subconjunto que usa y omite el resto: un parser establece un span de location, una importación establece code y source_ref, un linter de publicación establece rule_id y classification, un veredicto de gobernanza establece la severity y el message del resultado del build y puede añadir cualquiera de code, rule_id, classification, source_ref, location y suggest, y un aviso de renderizado establece code, source_ref y una location estructurada.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
severity | string (enum) | sí | La severidad del diagnóstico, tomada de un único conjunto cerrado que comparten todos los sockets. halt detiene el build e indica qué corregir. warn se presenta junto a un build que aun así se completa. info registra la observación y deja sin cambios el resultado del build. Cada emisor informa a partir de este único conjunto, de modo que quien lee interpreta una severidad de la misma manera sea quien sea quien la planteó. Valores permitidos: "halt", "warn", "info" |
message | string | sí | El texto del diagnóstico legible por una persona. |
code | string | no | Un código opcional, estable y comparable por una máquina para el diagnóstico, independiente del mensaje legible por una persona. Ausente cuando el emisor no asigna ningún código. Un código puede provenir de un socket de plugin o de los propios avisos del compilador, que establecen uno en cada entrada que plantean. |
rule_id | string | no | El identificador de la regla que produjo el diagnóstico, cuando el emisor se basa en reglas (un linter de publicación). Ausente en caso contrario. |
classification | string (enum) | no | Una clasificación del impacto en la versión semántica que lleva el diagnóstico, cuando la regla emisora asigna una (una regla de evolución del esquema). Ausente para los diagnósticos que no llevan ninguna clasificación. Valores permitidos: "PATCH", "MINOR", "MAJOR" |
source_ref | string | no | Una referencia opaca al elemento de origen al que se refiere el diagnóstico (por ejemplo, el identificador de un nodo de origen que una importación no pudo resolver). Ausente cuando el diagnóstico no hace referencia a ningún elemento de origen concreto. |
location | Location | no | Adónde apunta el diagnóstico, cuando el emisor puede localizar el problema. Un parser rellena el intervalo de bytes; un renderizador rellena la posición estructurada dentro de un documento de origen. Ausente cuando el diagnóstico no tiene ubicación. |
suggest | string | no | Una sugerencia de corrección opcional que el emisor ofrece junto al diagnóstico. Ausente cuando no se ofrece ninguna sugerencia. |
No se permiten propiedades adicionales.
Location
Adónde apunta un diagnóstico. Lleva un único localizador unificado que sirve tanto para una posición precisa al byte en el texto de origen sin procesar (un parser rellena span) como para una posición estructurada dentro de un documento de origen (un renderizador rellena key_path, uri, line y kind), y nombra la instancia de la compilación a la que se refiere el diagnóstico cuando la hay (instance). Cada campo es opcional; un socket rellena la representación que puede producir y omite el resto.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
span | Span | no | El intervalo de bytes de origen sin procesar que localiza el diagnóstico, cuando el emisor analiza el origen y puede fijar el problema en un intervalo de bytes (un parser). Ausente en caso contrario. |
key_path | string | no | Una ruta con puntos hasta el elemento problemático dentro de un documento de origen estructurado, cuando el emisor localiza el problema estructuralmente (un renderizador). Ausente en caso contrario. |
uri | string | no | Un identificador del artefacto de origen al que se refiere el diagnóstico, cuando el emisor lo conoce (un renderizador). Ausente en caso contrario. Nunca nombra una instancia de la compilación; eso lo lleva instance. |
line | integer | no | Un número de línea dentro del documento de origen estructurado, distinto de la línea y la columna de bytes sin procesar que lleva span. Presente cuando el emisor conoce una línea del documento (un renderizador). Ausente en caso contrario. |
kind | string | no | Una cadena abierta que nombra la superficie de origen a la que se refiere la ubicación, cuando el emisor distingue superficies (un renderizador). Ausente en caso contrario. |
instance | string | no | La instancia de la compilación a la que se refiere el diagnóstico, por la identidad que le da la compilación: un componente por el nombre con el que lo declara el Aggregate, un componente que aporta un módulo por su ruta con puntos a través del módulo, un componente que deriva la compilación por la identidad que la compilación compone para él, y un módulo por su propia ruta. Presente cuando el diagnóstico trata de una instancia; ausente en caso contrario. |
No se permiten propiedades adicionales.
Span
Un intervalo de los bytes de la fuente original: los desplazamientos en bytes son la ubicación principal y exacta, y los números de línea y columna los acompañan para diagnósticos legibles por una persona.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
start_offset | integer | sí | El desplazamiento en bytes del primer byte del intervalo en la fuente original, contado desde cero. |
end_offset | integer | sí | El desplazamiento en bytes situado uno después del último byte del intervalo en la fuente original, de modo que end_offset menos start_offset es la longitud del intervalo en bytes. |
start_line | integer | sí | El número de línea del inicio del intervalo, contado desde uno, para diagnósticos legibles por una persona. |
start_column | integer | sí | El número de columna del inicio del intervalo, contado desde uno, para diagnósticos legibles por una persona. |
end_line | integer | sí | El número de línea del final del intervalo, contado desde uno, para diagnósticos legibles por una persona. |
end_column | integer | sí | El número de columna del final del intervalo, contado desde uno, para diagnósticos legibles por una persona. |
No se permiten propiedades adicionales.