跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

Aggrega Wasm Linter Socket schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/wasm-linter-v1beta1.schema.json

linter socket 所消费(LinterInput)和输出(LinterOutput)的线上数据形态。该 linter 在发布时针对“上一版本 + 提议版本”的实体对运行(schema 演进规则),在工作区 lint 时针对单个实体运行(按规则划分的结构性规则)。一个发布的 Wasm 插件承载多条规则;插件通过 LinterInput.rule_id 选择要运行的规则。本 schema 是这两种线上数据形态的唯一来源:Go、Rust 和 TypeScript 的载荷类型均由它生成到共享的 plugin-ABI 包中,每个插件工具包重新导出这些生成的类型,而不是声明自己的副本。

以下形态之一

  • LinterInput
  • LinterOutput

定义

LinterInput

宿主在每次调用时传给发布 linter 插件的载荷。rule_id 选择插件分派到的规则。entity_kind 标识正在检查的实体种类(Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、Aggregate)。proposed 携带正在分类的实体经解析后的结构(宿主在发送前将 YAML 解析为 JSON;插件从不接触原始字节)。previous 携带供 schema 演进规则使用的、经解析的上一版本实体;不适用时省略。implemented_component 携带一个不同种类的相关实体——被检查的 Recipe 所实现的 Component——供将某实体与另一实体声明的契约进行比较的规则使用;不适用时省略。release 和 components 携带一个 Release 的其余部分,供读取整个 Release 的规则使用——此时 proposed 是该 Release 部署的 Aggregate,release 是该 Release,components 是该 Aggregate 每个组件实例所属的 Component;在其他所有输入中两者均省略。policies 携带规则参考的按工作区划分的发布规范配置。

属性类型必需描述
rule_idstring是插件应分派到的规则,以其规则 id 命名——与生成的 finding 在 rule_id 中携带的 kebab-case 标识符相同,因此被抑制或被报告的规则在每个界面上都以相同方式命名。可识别的集合即随附插件所分派的规则;插件无法识别的规则 id 会产生一个 ‘unknown_rule’ finding,而不是静默通过。
entity_kindstring(枚举)是proposed/previous 值所编码的实体种类。schema 演进规则的分类因种类而异;结构性规则限定于特定种类。允许的值:"Component"、"Feature"、"Recipe"、"FeatureRecipe"、"SchemaLibrary"、"MappingLibrary"、"Aggregate"
proposedobject是正在分类的实体经解析后的结构。宿主在发送前将 YAML 转换为 JSON,因此插件接收的是已结构化的值,从不接触原始字节。在读取整个 Release 的规则的输入中,它是该 Release 部署的 Aggregate。在每个输入中,实体交出之前都会移除每个参数值,因为参数的值可能就是凭据本身,所以没有任何参数值会通过此字段到达 linter 插件。Aggregate 保留其 spec.parameters 声明,每个声明只保留 Aggregate schema 在参数声明上允许的、除 default 之外的键,嵌套在 properties、items 和 valuesType 下的每个声明也遵循同样处理:default 被移除而不是被替换,因此插件无法判断声明是否给出了默认值;schema 在该处不允许的键连同其内容一并移除。spec.aggregates 下每个模块的 parameters 块(携带传给该模块的值)被整体移除,其他任何种类实体上的 spec.parameters 也同样整体移除。读取参数的模板文本按原样保留。
previousobject否上一版本实体经解析后的结构,供执行成对比较的规则(schema 演进)使用,其参数值的移除方式与 proposed 完全相同。当规则不需要上一版本引用时省略(例如首次发布、仅结构性规则)。
implemented_componentobject否被检查的 Recipe 在 spec.implements 中指定的 Component 经解析后的结构,由宿主解析。它是与被检查实体种类不同的相关实体,这正是它与 previous 的区别:previous 携带同一实体的另一个版本,而此字段携带的是该 Recipe 所实现的、声明了输出契约的 Component。宿主通过构建所用的同一目录查找来解析它,以 Component 的名称为键,因此 spec.implements 接受的三种固定形式(无版本、精确版本、主版本兼容范围)都会到达同一条目。当被检查实体不是 Recipe、未指定 Component,或在工作区的目录中找不到该名称的 Component 时省略。缺失值表示无法进行比较,而不表示契约为空:读取此字段的规则在该字段缺失时不发出 finding。
releaseobject否release 范围的检查所指定的 Release 经解析后的结构,其 extends 链已合并,因此子 Release 携带其从基础继承的内容。宿主像处理 proposed 一样将其从 YAML 转换为 JSON。它的 spec.parameters 块保存满足 Aggregate 参数的值,因此在交出 Release 之前被整体移除:参数的值可能就是凭据本身,没有规则读取该块,因此没有任何参数值会通过此字段到达 linter 插件。仅出现在读取整个 Release 的规则的输入中,此时 proposed 是该 Release 部署的 Aggregate,其参数值按 proposed 所述方式移除;在其他所有输入中省略。
componentsmap of object否Aggregate 的每个组件实例所属的 Component,以 Aggregate 赋予该实例的实例名为键,这与 Aggregate 和 Release 自身的 components 映射使用的键相同。每个值是该实例的 type 所解析到的 Component,已合并任何 extends 链,并像 implemented_component 一样转换为 JSON。若实例的 Component 在工作区的目录中不可达,则该实例缺失,规则将这种缺失视为不可用,而不是视为一个什么都不声明的 Component。仅与 release 一同出现在读取整个 Release 的规则的输入中;在其他所有输入中省略。
source_pathstring否加载实体的文件系统路径。由遍历目录文件系统的宿主调用方填充;由感知路径的规则使用(例如 category-matches-directory)。当调用方没有路径上下文时省略。
policiesPolicies否规则参考的按工作区划分的发布规范配置,以宿主根据工作区配置和任何命令行覆盖项组装的 Policies 对象形式携带。

不允许其他属性。

LinterOutput

发布 linter 插件发出的响应形态。findings 为每次产生结果的规则调用携带一个条目。schema 演进规则恰好发出一个 finding(分类结论);结构性规则可能发出零个(无违规)或多个(每处违规一个)。

属性类型必需描述
findingsDiagnostic[]是插件调用产生的按规则划分的 findings,按插件发出的顺序排列。
errorstring否当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它与输出携带的任何诊断信息不同:诊断信息报告的是仍产生了结果的运行中发现的问题,而 error 报告的是操作本身未能完成。宿主将存在的 error 呈现为一次失败的插件调用。

不允许其他属性。

Policies

规则集所参考的按工作区划分的发布规范配置,由宿主根据工作区配置中的发布规范设置以及任何命令行覆盖项组装而成。此 schema 是该形状的契约。省略字段时,每个标志默认为 false,宿主只写入值不是默认值的字段。

属性类型必需描述
allow_dynamic_refs布尔值否为 true 时,允许在 SchemaLibrary 条目中使用 $dynamicAnchor / $dynamicRef(抑制 dynamic-refs 规则)。默认为 false。
allow_id_overrides布尔值否为 true 时,允许在 SchemaLibrary 条目中覆盖 $id(抑制 id-overrides 规则)。默认为 false。
allow_direct_x_aggrega_extensions布尔值否为 true 时,允许直接编写 x-aggrega-selector / x-aggrega-inject(抑制 x-aggrega-discouragement 规则)。默认为 false。
allow_aggrega_ai_prefix布尔值否为 true 时,完全抑制 annotation-prefix 规则(包括单独的 aggrega.ai/ 检查和按类型条件进行的 feature.aggrega.ai/ 检查)。默认为 false。
allow_nonstandard_names布尔值否为 true 时,允许违反名称形状(抑制 name-shape 规则)。默认为 false。
allow_category_mismatches布尔值否为 true 时,抑制 category-matches-directory 规则的发现结果。标准目录的约定要求 core// 下的 Components 声明与目录段匹配的 component.aggrega.ai/category={category},其中 {category} 是 15 个封闭集合值之一。存在合理的持久例外的工作区可在此处选择退出。默认为 false。
allow_undeclared_recipe_provides布尔值否为 true 时,抑制 provides-declared-by-component 规则的发现结果。该规则报告 Recipe 在 spec.provides 中发布、但其 spec.implements 所指定的 Component 未在其 spec.schema 的 provides 支柱中声明的每个键。超出所声明契约的发布在构建时是被接受的,因此该发现结果仅供参考;如果工作区中的 Recipes 有意发布其 Component 未声明的键,可在此处选择退出。默认为 false。
allow_connection_credential_mismatches布尔值否为 true 时,抑制 connection-credential-matches-target-key 规则的发现结果。该规则读取整个 Release,并针对每个其目标声明了要求调用方提供的键的连接,将该连接出示的凭据与目标持有的键进行比较:它会报告两端指定了不同 secret 的情况,以及仅在一端声明了键的情况。两端之间的一致是一项目录约定,而非构建会检查的内容,因此该发现结果仅供参考;两端有意不同的工作区可在此处选择退出。默认为 false。

不允许其他属性。