Aggrega Wasm 插件共享诊断 schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/wasm-diagnostic-v1beta1.schema.json
所有 Wasm 插槽共享的单一诊断结构。插件为其提出的每个问题报告一个条目;宿主负责呈现它。该结构是一个超集:每个插槽填写其使用的子集并省略其余部分,因此来自任何插槽的诊断都是同一种统一结构。severity 是所有插槽共享的三个值之一——halt、warn 或 info——因此无论由哪个插槽提出,诊断都具有相同的含义。
顶层类型: object
定义
Diagnostic
诊断发出方提出的一个问题:一个严重级别、一条人类可读的消息、一个可选的位置,以及可选的发出方特定字段。发出方是 Wasm 插件插槽或编译器本身——两者都基于这一种结构报告,因此无论由哪一方提出,读者都以相同方式解读条目。每一方填写其使用的子集并省略其余部分:解析器设置位置 span,导入设置 code 和 source_ref,发布 linter 设置 rule_id 和 classification,治理裁决设置决定构建结果的 severity 和 message,并可添加 code、rule_id、classification、source_ref、location 和 suggest 中的任意项,渲染建议设置 code、source_ref 和结构化位置。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
severity | string(枚举) | 是 | 诊断的严重级别,取自所有插槽共享的一个封闭集合。halt 会停止构建并指出需要修复的内容。warn 在构建仍能完成的情况下一并呈现。info 记录观察结果,不改变构建结果。每个发出方都从这一集合中报告,因此无论由哪一方提出,读者都以相同方式解读严重级别。允许的值:"halt"、"warn"、"info" |
message | string | 是 | 人类可读的诊断文本。 |
code | string | 否 | 诊断的可选代码,稳定且可供机器匹配,与人类可读的消息无关。发出方未分配代码时不存在。代码可来自插件插槽,也可来自编译器自身的建议,后者会在其提出的每个条目上设置代码。 |
rule_id | string | 否 | 生成该诊断的规则的标识符,在发出方基于规则(发布 linter)时提供。其他情况下不存在。 |
classification | string(枚举) | 否 | 诊断携带的语义版本影响分类,在发出规则分配分类(schema 演进规则)时提供。对于不携带分类的诊断不存在。允许的值:"PATCH"、"MINOR"、"MAJOR" |
source_ref | string | 否 | 对诊断所涉及源元素的不透明引用(例如导入无法解析的源节点的标识符)。诊断未引用特定源元素时不存在。 |
location | Location | 否 | 诊断所指向的位置,在发出方能够定位问题时提供。解析器填写字节 span;渲染器填写源文档中的结构化位置。诊断没有位置时不存在。 |
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 | 是 | span 第一个字节在原始源中的字节偏移量,从零开始。 |
end_offset | integer | 是 | span 最后一个字节之后一个位置在原始源中的字节偏移量,因此 end_offset 减去 start_offset 即为 span 的字节长度。 |
start_line | integer | 是 | span 起始处的行号,从一开始,用于人类可读的诊断。 |
start_column | integer | 是 | span 起始处的列号,从一开始,用于人类可读的诊断。 |
end_line | integer | 是 | span 结束处的行号,从一开始,用于人类可读的诊断。 |
end_column | integer | 是 | span 结束处的列号,从一开始,用于人类可读的诊断。 |
不允许其他属性。