aggrega validate
aggrega validate 检查正确性——schema、支柱结构、跨文档引用解析、extends 链、provider 的输入种类能力,以及(对于渲染实体)它是否确实能够渲染。它有三种模式,由其参数选择,在三个范围内应用同样的正确性检查准则:整个目录(无参数)、单个 Release 的依赖闭包(--release),以及一个实体文件(实体路径)。每个范围回答同一个问题——“这些内容正确吗?”——只是针对目录的不同切片。
正确性不同于约定。aggrega validate 检查内容是否格式良好、能否编译;aggrega lint 检查内容是否遵循目录的发布准则(命名、类别目录对齐、版本号提升幅度等)。这两个命令的三个范围彼此对应,因此你可以按所需的任意粒度检查任一维度。
aggrega validate 不向磁盘写入任何内容,也不读取任何运行时状态。它运行与构建相同的解析和验证,在渲染之前停止(对于单个实体,则隔离渲染)。
实体路径可以作为位置参数给出。与实体路径一起给出的 --release 不会选择 Release 范围:该实体仍单独检查,只是按照该 Release 的条件进行——参见按照 Release 的条件检查实体。
整个目录的正确性(无参数)
不带参数的 aggrega validate 会加载所配置的 catalog 目录下的每个目录实体,并对其进行端到端检查。在加载任何内容之前,它会读取这些目录下的每个 YAML 文件;其中若有无法加载的 Aggrega 文档,运行就会中止,详见下文。然后:
- Schema 支柱结构:展开并验证每个 Component 和 Feature 的
spec.schema:块(与构建所做的 schema 支柱检查相同),包括紧凑形式的展开。 - 跨文档引用解析:指向 SchemaLibrary 条目的
$ref和$import引用能够解析;无法解析或因其他原因无效的 SchemaLibrary 会被拒绝。 extends链——每个声明了extends的实体都会依据其父实体进行解析,并检查合并后的父实体+子实体结构。catalog 目录中没有的父实体,会从构建读取它的位置读取:即从制品缓存中,按照 Release 的锁文件为其记录的固定版本读取——所用的是该轮检查所针对的各 Releases 的锁文件;若工作区在单轮中整体验证,则为工作区中每个 Release 的锁文件。因此,发布到 registry 的基础实体在aggrega pull获取并固定它之后即可通过验证,而两者中都没有的父实体会使运行停止,并提示aggrega pull --release <release>。不会获取任何内容。- 已声明的选择器——Component 或 Feature 文档在
spec.usesSchema下的依赖 socket 上,或在spec.featuresSchema下的挂载槽上声明的每个标签选择器——对 Component 而言,还包括 socket 所声明的槽——都会按选择器语法读取,无论是否有任何内容连接该 socket 或填充该槽。参见已声明的选择器。 - OCI 位置冲突:会发布到同一 registry 位置的两个不同目录标识会被明确拒绝,因此构建绝不会静默地用另一个实体的已发布字节覆盖某个实体的已发布字节。
- Provider 输入类型能力:声明了
workload:块、且该块绑定到无法进行合成的 provider 的 Recipe 或 FeatureRecipe 会被标记为错误,因为它永远无法构建。
这是构建中按 Release 进行的验证在整个目录范围内的对应检查:损坏的目录实体应当在这里暴露出来,早于任何 Release 用到它。遇到无法加载的 Aggrega 文档,以及任何 schema 支柱违规、无法解析或无效的库、extends 解析失败、语法拒绝的已声明选择器、位置冲突或输入类型能力错误时,它会明确地停止。Schema 支柱重叠和 extend 时收窄的发现,以及 Component 或 Feature 在其 schema 内容中内联编写的每个 x-aggrega-* 关键字,都是建议性的 notice: 行,从不改变退出码。
无法加载的 Aggrega 文档会中止运行。 catalog 目录下的 YAML 文件,若其某一行不带缩进地以 apiVersion: 开头,且其值以 aggrega.ai/ 开头(无论是否加引号),即为 Aggrega 文档。若此类文件无法读取、其 YAML 无法解析,或其 kind 或 metadata 不是实体信封应有的形状(例如写成列表的 metadata),则在各目录读取完毕后,运行会以 E0175 中止,列出每个此类文件以及读取或解析器给出的原因;不会检查任何内容,也不会打印 catalog validation passed 行。能够加载但声明了任何 catalog 都不包含的 kind 的文档(例如拼错的 Componnent,或者根本没有 kind)会以 E0371 中止同一次运行,并与上述文件一并列出,附上它所声明的种类;Manifest、Release,以及 Recipe 从其自身目录导入的 Workload 都会被略过。其他任何 YAML——Helm chart 的模板(它们在渲染之前无法解析)、chart values、工作流定义——都会被略过。
它读取哪些目录取决于工作区的形态:
-
配置中没有给出自己的 Release 目录的工作区会在其搜索栈上验证一次:先是
--catalog目录,然后是workspace.catalog_dirs,然后是工作区根目录下的catalog目录(如果存在)。 -
在
workspace.releases下列出了 Releases 的工作区可以并排保存一个目录的多个变体,每个变体由各自的 Release 读取;一次性加载所有变体会把每个变体放进同一个目录,导致一个变体的实体遮蔽另一个变体的实体。因此,会对工作区中的每个 Release 分别验证一次,范围是该 Release 读取的目录,每一轮都先读取--catalog目录;配置中未列出的 Release 读取工作区的列表。每一轮都在一行下报告,该行列出其 Release 和所读取的目录,随后是该轮的结果:Release release-compose.yaml reads catalog-composecatalog validation passed (schema-pillar + library + extends + oci-location)Release release-helm-synth.yaml reads catalog-helm-synthcatalog validation passed (schema-pillar + library + extends + oci-location)读取完全相同目录的 Releases 共享一轮,该轮会列出其中每一个。不读取任何目录的 Release(其条目写的是
catalog_dirs: [])会报告为没有可检查的内容,其他轮照常运行。无论前一轮发现了什么,每一轮都会被报告,因为一个变体中的损坏实体并不能说明另一个变体的情况;只要有任何一轮失败,命令就会失败,并列出目录验证失败的 Releases。工作区中的 Releases 是它的 Release 文档:位于工作区根目录下任意位置(隐藏目录以及node_modules、vendor和dist之外)、kind为Release的 YAML 文件。
如果所有轮都没有可读取的内容,运行会被拒绝,而不是报告为一个干净的目录:请把实体放在 catalog/ 下、传入 --catalog,或设置 workspace.catalog_dirs;在列出了 Releases 的工作区中,也可以在 workspace.releases 下设置某个 Release 自己的 catalog_dirs。它从不隐式枚举当前工作目录,因此绝不会引入无关的目录树。
aggrega mcp 的 validate 工具在被要求验证整个目录时,会执行相同的各轮验证;在列出了 Releases 的工作区中,其回答会在 passes 下给出每一轮(相关 Releases、所读取的目录以及该轮自己的结论),并附带针对所有轮的总体结论。
仅存在于制品缓存中的库
制品缓存保存的是获取操作放入其中的内容,而缓存中的 SchemaLibrary 只有在某个 Release 的锁文件中有条目为其摘要作保时,才算作目录内容——参见缓存是什么,不是什么。当某个 $ref: 解析不到任何内容,而缓存中又存放着一个既没有任何锁文件条目固定、也没有检查所读取的任何 catalog 目录提供的库时,报告之后会跟随一行 remediation:,列出每个这样的库,以及对失败的范围有效的操作:
- 不带参数时,以及带实体路径时(无论是否给出
--release),validate 只从 catalog 目录读取库,绝不通过锁文件条目读取,因此已记录的条目不会改变其结论。该行会说明这一点,并指引你在 catalog 目录下编写该库,或先运行aggrega pull --release <release>,再运行aggrega validate --release <release>,后者会依据 Release 的锁文件所固定的库来检查该 Release。 - 仅使用
--release时,validate 会读取该 Release 的锁文件,因此该行会指出aggrega pull --release <release>(它会解析该库并记录其条目),或者在 catalog 目录下编写该库。
该行既不改变结论,也不改变退出码。
已声明的选择器
Component 或 Feature 用标签选择器约束哪些内容可以连接到它的依赖 socket,以及哪些内容可以填充它的挂载槽——即每个 spec.usesSchema 条目和每个 spec.featuresSchema 条目的 selector:,以及在 Component 上,socket 在其自身 featuresSchema 下声明的每个槽的 selector:。构建只在有内容到达选择器时才读取它:一条经由该 socket 绘制的边,或一个填充该槽的挂载。因此,整个目录范围和单实体范围会读取 Component 或 Feature 文档声明的每个选择器,无论是否有任何内容连接该 socket 或填充该槽;语法拒绝的选择器——缺少右括号的值列表、重复的逗号、带有 = 或 ! 的键——会使检查失败。该语法即字符串语法中讲解的语法。
该拒绝与构建到达同一选择器时报告的拒绝相同,代码相同,措辞也相同:socket 的选择器为 E0007,槽的选择器为 E0008,并指出该选择器、声明它的 socket 或槽,以及语法无法读取它的原因。它作为目录错误记录在该实体的文件上:
selector violation (
"<selector>", declared on socket"<socket>", which could not be evaluated:"<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema.(选择器违规:在 socket 上声明的选择器无法求值。请在该组件类型的 usesSchema 中更正 socket 声明上的选择器。)
每个文档都按其作者所写的样子读取,因此基础实体声明的选择器只会针对该基础实体自身的文件报告一次,而不是对每个扩展它的实体各报告一次。Feature 的 appliesTo 和 appliesToAnyOf 不在这里读取:它们会在评估该 Feature 的挂载时读取。
整个目录范围会把每个被拒绝的选择器各自报告在一行 selector: 上,并以其数量失败;单实体范围则将它们报告为其形状层级的失败——无论实体路径旁是否带有 --release,因为那种形式就是按某个 Release 的条件运行的单实体范围(参见按 Release 的条件检查实体)。单独使用的 --release(它验证 Release 的依赖闭包)和构建只在有边或填充到达选择器时才读取它,并在那里因它而停止。
Release 范围的正确性(--release)
aggrega validate --release <release-path> 只验证单个 Release 的已解析依赖所能到达的实体,而不是整个目录或单个实体。它通过与构建相同的机制计算闭包,因此它检查的实体正是该 Release 的构建会解析的实体。在该闭包上,它会:
- 解析闭包范围内的
extends链,遇到解析错误即失败; - 验证每个已解析实体的 schema 支柱(限于闭包范围),遇到 schema 支柱错误即失败;
- 运行与构建相同的渲染前值一致性检查:它把 Release 的参数解析到编写的值中(因此
{{ .parameters.* }}值按解析后的结果检查,而不是作为模板检查),并根据闭包中组合后的 schema 验证结果,其中包括针对使用extends的实体,根据组合后的父级+子级 schema 检查一致性。违反其 schema 的值会以非零退出码失败; - 根据 Release 解析出的值评估每个 Recipe 和 FeatureRecipe 断言,就像构建在渲染之前评估它们一样:每个组件的 Recipe 按 Manifest 的映射进行绑定,其
locals和provides得到解析,第一个失败的断言——调用fail的断言,或其模板因找不到某个键而停止的断言——会使验证失败,并给出构建停止时的条件和句子。无法求值的locals或provides模板同样会使验证失败,正如它会使构建失败一样。会像构建那样询问每个 Recipe 所经由渲染的 provider 为该组件的资源所起的名称,因为 Recipe 的provides可能读取该名称;不会渲染任何内容。只有在上述各项都未失败时才会评估这些断言,因此 Release 报告的是构建会停止的最早故障; - 将 schema 支柱重叠和 extend 时收窄的发现以信息性的
notice:行呈现,这些行从不改变退出码; - 将其读取的实体在 schema 内容中内联编写的每个
x-aggrega-*关键字显示为一行warning:,每个实体一次,与构建的显示方式相同——它同样从不改变退出码。
这使 --release 成为真正的构建前检查:它在构建之前捕获构建会拒绝的内容——即不含渲染的构建依赖验证。它不运行渲染,也不触发任何网络拉取:闭包从本地目录解析(以及存在时 Release 的 lockfile 固定项);需要 lockfile 的 registry 固定依赖集会如实报告无法解析引用的错误,而不是去获取。收窄只作为建议呈现,从不强制执行。
如果 lockfile 已不再与该 Release 解析到的内容匹配,验证会以 aggrega build 打印的停止信息被拒绝。 当 Release 旁边有 lockfile 时,--release 会在 Release 的依赖解析完成后、上述任何检查运行之前,立即用构建在渲染前运行的漂移比较,核对该 lockfile 是否与 Release 解析到的内容一致。如果某个固定的实体、库、插件或 Release 文件本身已与 lockfile 发生漂移,验证会以构建的 E0130 拒绝停止——列出每个发生漂移的条目,随后给出可清除漂移的 aggrega pull --release <release>——并以非零状态退出,因此验证绝不会放过构建因漂移而拒绝的 lockfile。不带参数以及指定实体路径时,validate 不受 lockfile 约束:整个 catalog 的检查只为查找 extends 父实体而读取 lockfile 中的固定项,而单个实体的检查不读取任何 lockfile。
由于它运行与构建相同的检查,它也运行相同的已挂接 gate 插件——因此它同样受构建所遵循的可信插件身份记录的约束。挂接了返回接受或拒绝结论的插件的工作区,在其 Release 旁有一份插件信任记录,--release 会在任何这些插件运行之前将配置与该记录比较:配置不再挂接的已记录 gate 会中止验证;从 aggrega pull 填充的缓存中解析出、但其制品不是已记录制品的插件会被拒绝,而不是运行。未记录任何内容的工作区没有记录,这对该比较没有任何影响。--release 还会在标准错误上以 deprecation: 行、用 aggrega build 所打印的措辞,指出针对该 Release 所依赖内容记录的每一项撤回:锁文件针对某个固定引用记录的标记,以及信任记录针对以结论角色挂接的插件记录的标记,都同样如此。撤回既不改变结论,也不改变退出码;而存在但无法读取的信任记录会使验证停止,而不会被当作未记录任何内容的记录放行。
从缓存读取的插件在加载时也要接受其条目所记录签名的检查,与构建相同。若其条目记录了已验证的签名,则会再次检查该事实在缓存中指向的签名材料,材料缺失或不一致的插件会被拒绝;材料是为另一个插件而非所读取插件制作的插件同样会被拒绝——这正是从另一个条目复制来的 signature 的表现,无论签名要求如何规定。若工作区的信任配置要求签名,则从缓存读取、但其条目未记录签名的插件——或记录中根本没有其条目的插件,包括记录已被删除的情况——也会被拒绝,所依据的设置与使 aggrega pull 拒绝未签名插件的设置相同,因此 skip_signature_verification 和 advisory registry 允许其运行。拒绝会使验证失败,并在其诊断信息中报告,指明该插件以及 aggrega pull --release <release>:该命令会在插件的 registry 上验证其签名、记录签名并缓存其指向的 bundle,同时重写不再与其摘要匹配的缓存副本;从你的某个目录中提供的插件,或来自编译器二进制内副本的插件,从不受此要求约束。另外两种范围都不受上述任何约束:它们不读取工作区的插件挂接,因此其中不会运行此类插件。
对于改变图而非评判图的插件,同样如此。label-transform 或 annotation-transform 挂接会影响渲染输出,因此 lockfile 会固定其身份及其读取的源文件——而 --release 以构建运行它们的方式运行这些挂接:从 lockfile 重建,要求每个挂接符合其记录的摘要,并读取 lockfile 携带的源内容而不是磁盘上的文件。有两个后果值得你在遇到之前了解:
- **在
.aggrega-config.yaml中挂接 transform 插件,在你执行 pull 之前不会改变--release的行为。**这与构建遵循的规则相同,原因也相同:挂接集合是决定字节的输入,因此它在 pull 时被采用,而不是在编辑时。 - 字节不再与 lockfile 所记录摘要匹配的缓存插件会被拒绝,与构建期间完全相同。
如果 Release 没有 lockfile,--release 仍会验证——它会警告无法检查插件的身份并指明要运行的命令,而不是拒绝。参见警告。
交回编译后的图
--ir-graph 会将此次验证解析出的图以 JSON 形式写入标准输出,位于结论行之前。它是附加性的:运行相同的检查,写出相同的诊断信息,退出码与不使用它时相同。交回的图正是执行验证所基于的图,因此它不可能描述与结论所报告的不同的解析结果。
它仅适用于此范围——全目录和单实体范围驱动的是合成的测试框架而非 Release,不解析任何图——在其他范围中请求它会被拒绝,而不是被静默忽略。如果运行在图解析之前停止,则不会向标准输出写入任何内容,命令自身的诊断信息会说明停止的原因。
注意与它相邻的标志。--response-format 设置此命令自身报告写出的详细程度(detailed 或 concise);--ir-graph 则在该报告之外请求第二份文档。一个关乎篇幅,另一个关乎对象,两者都不改变结论。
作者声明为敏感的值会从图中隐去——在消费方组件的套接字将某个叶子声明为敏感时,连接的 values 和 infra 也包括在内——采用 aggrega inspect 中所述的结构化形式。在 --ir-graph 旁使用 --unredacted 则会改为输出这些值,条件与 aggrega inspect --unredacted 所述相同:它只作用于图,不影响此命令写出的其他任何内容,而输出所到之处都会以明文携带这些值。不带 --ir-graph 传入时它会被拒绝,因为没有可供它揭示的内容。
单实体正确性(实体路径)
aggrega validate <entity-path> 检查一个目录实体文件。它应用一组分层检查,在第一个阻断性失败处停止,使 schema 错误在任何目录工作之前就明确暴露:
- 占位符(所有类型)——该类型要求、但文件保留为空字符串的值。所有占位符会在其他检查之前一次性报告,每个都附带它需要什么;参见仍待填写的占位符。
- Schema 外壳(所有类型)——与目录加载器在每个解析边界运行的完全相同的逐实体 JSON-Schema 检查。
- 形状(所有类型)——特定于类型的结构验证。对于 Component 或 Feature,这包括按选择器语法读取文件在依赖 socket 或挂载槽上声明的每个标签选择器;参见已声明的选择器。
- 支柱结构(Component 和 Feature)——
spec.schema:支柱检查,使用目录中的 SchemaLibraries 展开跨文档的$ref。
Component 或 Feature 到此为止:schema 外壳、形状和支柱结构。单独的 Component 没有可独立渲染的已编写 values 或 infra,因此没有可渲染的内容——其正确性完全由 schema 和支柱这几层检查覆盖。其 schema 内容中内联编写的每个 x-aggrega-* 关键字,都会在标准错误的建议性说明中以一行 warning: 报告,指出该关键字、它所在的位置以及应改为编写的声明式表;它从不改变裁决或退出码。
Recipe 还会额外独立渲染。这是单实体正确性的一个方面,而非其核心:在 schema 和形状检查通过后,validate 从目录中解析该 Recipe 的 implements Component,围绕该 Component 的单个实例(绑定到被测 Recipe)合成一个最小的 Aggregate、Manifest 和 Release,并在其上驱动真实的编译流水线——先进行解析和守卫检查(跳过渲染),再对独立输出进行真实渲染。每个没有默认值的必需值和必需 infra 字段都用其声明类型的占位符填充——值放在合成的 Aggregate 中,infra 放在合成的 Release 中——其他所有值和 infra 字段通过解析器取其 schema 默认值;该 Release 将实例路由到一个合成的默认边界中,不声明任何 values:,也不声明 Aggregate 未声明的计算资源。占位符是字段自身声明的约束所接受的值:常量或 enum 列出的第一个值、在其范围内的数字、符合其长度和 format 的字符串、在其 pattern 要求时的语义版本、所要求数量的列表项,以及对象要求的每个属性。其他 pattern、validate: 或 when: 条件、schema 组合以及对列表所含项目的约束不会被参考,因此依赖这些的字段仍可能拒绝其占位符;此时 validate 以 schema 自身的措辞报告该拒绝。渲染产物会被打印出来,让作者在将实体接入完整 Aggregate 之前看到独立输出。由于单实体测试环境只填充这些必需字段,不连接任何连接,也不附加任何 Feature,因此模板读取只有连接或附加的 Feature 才提供的值的 Recipe 无法独立渲染;validate 将此类渲染报告为未尝试,而非失败。调用 fail 的断言会作为警告报告,而不会使检查失败——参见失败的断言是警告。因其他任何原因停止的渲染即为未完成,validate 会附带底层渲染诊断进行报告,直到指明停止原因的那句话。
source: 需要获取的 Recipe 根本不会被渲染;而在读取只有连接或附加的 Feature 才提供的值时渲染停止的 Recipe,其渲染会被搁置——参见下文单实体正确性不检查的内容。
FeatureRecipe 会进行 schema 和形状检查;其渲染被跳过,因为 FeatureRecipe 只有在附加到宿主组件时才会渲染,而为任意 Feature 合成一个能通过守卫的宿主不在尝试范围内。
按 Release 的条件检查实体
工作区可以为每个 Release 提供其自己的目录——参见为 Release 提供其自己的目录——从而为每个 Release 并列保留一个目录变体。单独给出的实体路径会基于工作区自身的目录进行检查,此时指向某个变体内部的引用——Recipe 所实现的 Component、支柱所引用的 SchemaLibrary——将无法找到。在实体路径旁给出 --release,同样的检查就会按该 Release 的条件运行:实体的引用通过工作区配置为该 Release 提供的目录解析,并在前面加上任何 --catalog,这些正是构建该 Release 时读取的目录。
MariaDB + Adminer 示例保留了四个这样的变体。其 synth 变体的 Component 从一个只有 synth 和 chart 变体才包含的 SchemaLibrary 中获取存储设置,因此它按使用它进行构建的 Release 的条件校验通过:
$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/component/mariadb.yamlKind: ComponentSchema: validPillars: valid而按目录中不包含该库的 Release 的条件则会失败,并指明无法解析的库——即 --release release-compose.yaml,或在未列出自身目录的工作区中完全不带 --release。
Recipe 也以同样方式检查。synth 变体的 Recipe 实现了 core/datastore/mariadb,而工作区自身的目录中没有它,因此单独给出时会失败并报告 render: implements target "core/datastore/mariadb" not found in catalog。给出使用它进行构建的 Release 后,它会解析该 Release 的 Component 并独立渲染:
$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Resolution: validRender: 3 artifact(s)随后是三个渲染产物。该示例的每个变体都声明了 core/datastore/mariadb,因此该 Recipe 按其四个 Releases 中每一个的条件都能校验通过;按目录中没有此 Component 的 Release 的条件,它会失败并指明目标,与不带 --release 时相同。Attachments: 行的含义见必需的附加槽位或存在性要求。
这仍属于单实体范围。检查、报告和退出码都是本节所述的那些——带有语法拒绝的 socket 或槽选择器的 Component 或 Feature 在这里的失败方式与不带 --release 时完全相同,参见已声明的选择器——且不会校验任何闭包:--release 指定的是用于读取实体引用的目录所属的 Release,而不是要检查的闭包,这也是 --ir-graph 在实体路径旁会被拒绝的原因。指向不存在的文件或指向目录的 --release 会在任何检查之前被拒绝。
工作区配置列出的目录如果不是目录(例如该处什么都不存在),无论是针对该 Release,还是在未给出 --release 时针对工作区,都会在检查任何内容之前被拒绝,正如读取这些目录的每个命令都会拒绝它(本地实体从何处读取):拒绝信息会指明该条目、列出它的配置文件和行以及相应设置,并且不给出结论。通过 aggrega serve 进行的编辑器实体检查会将同一拒绝作为该实体文件上的唯一条目给出,级别为错误,而 aggrega mcp 的 validate 工具会以此拒绝该调用。
仍待填写的占位符
类型要求但文件留为空字符串的值即为占位符,validate 会先于其他一切报告它。由 aggrega scaffold 起草的文档在其类型需要只有你才能提供的值的每一处都带有一个占位符,因此你可以在这里了解还剩哪些。下面是一个只填写了版本的已起草 FeatureRecipe:
Entity: my-feature-recipe.yamlKind: FeatureRecipe2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates: 7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it. 8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).文件中的每个占位符会一次性全部列出,按文档顺序,附带其行号、列号及其所需内容。所需内容读取自该类型自身的 schema:schema 列出可接受值时为这些值;schema 要求语义化版本时为诸如 1.0.0 的版本;否则为 schema 对该字段自身描述的第一句话。
哪些值算数同样从 schema 读取。当类型在文档顶层、或在类型同样要求的对象内部要求某个值,而文件将其设为空字符串时,该值即算数。文件完全省略的键由 schema 检查报告为缺失属性。留空的可选字段不是占位符,仅在你选择编写的列表或映射内部才被要求的字段也不是。若 schema 本身将空字符串列为字段可接受的值之一,则空值是一个值而非占位符。
即使 schema 接受空值,该值仍须填写。 schema 允许 Recipe 或 FeatureRecipe 的 capability 和 implements 为空字符串,但空值既不指明 provider 也不指明类型,因此 validate 会像其他占位符一样将两者报告为占位符。若 schema 检查同样拒绝该文件(例如版本为空、类型标签没有值),报告会带有该检查的代码 E0215,如 aggrega scaffold 上的示例所示;若 schema 检查接受该文件(如上例),报告不带代码。同一文件中与空值无关的发现仍会以 schema 检查自身的措辞报告,位于列表之前。
这种解读属于单实体验证,无论实体路径旁是否给出 --release。全目录运行遇到同一文档时,报告的是 schema 检查所报告的内容,因此目录中 implements 为空的 FeatureRecipe 能通过它;Release 范围和 aggrega build 也不采用这种解读。
此范围不接受的类型
单实体验证接受 Component、Feature、Recipe、FeatureRecipe、Workload 和 Plugin。其他任何类型的文件都会被拒绝,拒绝信息会列出可接受的类型,并且对于实体类型,会指出确实检查该类型文档的范围:
kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it全目录范围是不带参数的运行,Release 范围是不带实体路径的 --release:
| 类型 | 检查方式 |
|---|---|
| Aggregate | 全目录运行(当其位于目录文件夹中时);对部署它的 Release 使用 --release |
| Manifest | 对引用它的 Release 使用 --release |
| Release | --release <release-path> |
| SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | 全目录运行(当其位于目录文件夹中时) |
全目录运行只读取已配置目录文件夹中的内容,因此与其 Release 一同放在工作区根目录的 Aggregate 需通过对该 Release 使用 --release 来检查。
失败的断言是警告
调用 fail 的断言(无论是 Recipe 声明的,还是其 implements Component 声明的)会被报告为警告,检查不会因此失败。合成的 Release 以占位符和 schema 默认值代替真实 Release 设置的值,因此针对此类值(镜像或某个前置条件是否存在)的断言在此处无论 Recipe 是否正确都会失败,validate 无法区分等待 Release 的断言与本身有问题的断言。对断言的裁定留给构建,构建总有 Release。
警告写入标准错误,以 warning: 开头,位于所有建议性提示之后。它带有断言的完整消息(实体、实例、断言名称及其作者写的句子),并以另一句话结尾:
A Release must satisfy this assertion before a build of it can pass.标准输出上的报告说明运行停在何处,命令以 0 退出。Recipe 自身的断言会停止渲染,因此报告在 Resolution: valid 之后显示 Render: stopped on a failed assertion, reported as a warning。Component 的断言在任何渲染之前求值,因此报告显示 Resolution: stopped on a failed assertion, reported as a warning,随后是 Render: not attempted (the run stopped on that assertion)。无论哪种情况都不会渲染任何内容,因此不打印任何产物。
只有调用 fail 的断言才是警告。因读取的键找不到而停止、或无法解析的断言,是断言自身文本的错误而非失败的断言,按其他任何停止的方式裁定。其他所有错误仍作为检查的裁定结果。
对不满足该断言的 Release 执行 aggrega build 时,会一如既往地因其报错停止,指出该断言并带有其作者的句子;对该 Release 执行 aggrega validate --release 也会因其以相同的错误失败。通过 aggrega serve 进行的编辑器实体检查给出相同的警告,在 Recipe 声明断言时标在断言自身的键上;aggrega mcp 的 validate 工具返回 valid: true,并将警告列在其 notices 中。
单实体正确性不检查的内容
真实构建的四项检查超出了单实体构建的能力范围,validate 对每一项都选择不做,而不是报告一个它无法确保的发现。
需要获取的来源
验证单个实体不读取锁文件,不读写缓存,也不发起网络请求。因此,source: 指向需通过传输方式获取之物(OCI 或 HTTPS chart 仓库、Git 仓库)的 Recipe 没有可用于渲染的基础设施代码:chart 或模块不存在于运行可访问的任何位置,而被检查的文件本身并无过错。Validate 会说明这一点,将其作为不同于渲染的结果打印,并以 0 退出:
Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validResolution: validRender: not attempted (this Recipe's source is fetched) Validating one entity on its own reads no lockfile, reads and writes no cache, and makes no network request, so the chart or module this Recipe names is never retrieved and there is nothing to render from. To render it, build a Release that deploys a component this Recipe implements.该行之上的所有内容都已检查并报告为有效。因此,对于此类 Recipe,退出码的含义比已渲染的 Recipe 更窄:schema、结构和解析成立,渲染未经验证。报告会说明你看到的是两者中的哪一种。
工作区已有的来源不会被跳过。 相对路径 source: ./module 无需获取,因此其渲染与其他渲染一样会被尝试,其中的失败是真实的发现,报告为 Render: not completed in isolation 并以非零退出。上面那一行仅针对需要获取的来源出现。
要真正渲染来源需获取的 Recipe,请对部署该 Recipe 所实现组件的 Release 运行 aggrega build:构建通过 Release 的锁文件和本地缓存解析来源,从而提供 validate 无从获得的字节。
必需的 uses 插槽
第二项是 implements Component 中 required: true 的 uses 插槽是否已被填充。
必需的插槽通过将一条边连接到另一个组件来填充——来自 Aggregate 自身的 uses 块,或来自为该 Component 所声明插槽接线的 Release。合成的测试框架只包含单个实例,因此其中没有可供这样一条边指向的第二个组件,而且无论如何编写合成文档都无法产生一个:虚构一个对等组件就意味着虚构测试框架从未声明过的计算资源。因此,validate 会列出它未检查的插槽,并继续执行解析和渲染:
Sockets: required uses sockets not checked (backend, cache, registry) Validating a Recipe on its own places its Component in a build of one, so no other component exists for a required socket to be wired to. Whether each of these sockets is populated is checked when the Component is deployed in an Aggregate.仅当该 Component 声明了至少一个必需插槽时才会出现这一行,并且只列出必需的插槽——可选插槽从不列出,因为在任何范围内不为其接线都不算问题。如果 Recipe 的 Component 未声明任何必需插槽,则不会产生这样的行,其报告保持不变。
该规则本身既没有放宽,也没有重复执行;它在能够给出答案的范围内被检查。aggrega build 会在 Aggregate 和 Release 的边界面上完整地应用它,并在必需插槽没有任何接线时停止。因此,通过单实体校验的 Recipe 在其 Component 被部署时仍须满足必需插槽规则,而报告会明确说明这一点,而不是让 validate 所检查的内容与构建将检查的内容之间存在无声的差异。
必需的挂载槽或存在性强制要求
第三项是 implements Component 中 required: true 的挂载槽(即其 featuresSchema 所声明的具名绑定点)是否已被填充,以及其存在性强制要求所要求的每种 Feature 类型是否都存在相应的挂载。
必需的挂载槽通过在该名称处挂载一个 Feature 来填充,可在 Aggregate 或 Release 中进行,可挂在组件上或其上层范围——即在部署该 Component 的地方,而不是在 Recipe 中。合成的测试框架不挂载任何 Feature,因此它构建的任何内容都无法填充这样的挂载槽。因此,validate 会列出它未检查的挂载槽,并继续执行解析和渲染,与处理必需插槽的方式完全相同:
Attachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.仅当该 Component 声明了至少一个必需挂载槽时才会出现这一行,并且只列出必需的挂载槽;如果 Recipe 的 Component 未声明任何必需挂载槽,则不会产生这样的行。被搁置的只是“必需”这一要求:挂载槽的标签约束及其允许的交付机制仍按声明保留。无法解析的模板仍会使运行失败,Recipe 自身的错误(例如 provider 无法合成的 Workload)也同样如此——除非该 Recipe 还读取了只有连接或已挂载的 Feature 才能提供的值,如下一节所述。
存在性强制要求——即 Component 上的 features.aggrega.ai/requiredType.<label> 注解,要求某个挂载携带其所指定的 Feature 类型——出于同样的原因被搁置:测试框架不挂载任何内容,因此它构建的任何内容都无法携带该类型。validate 会按标签及其要求的类型列出每个未检查的强制要求,并继续执行解析和渲染。标准库中的 example/compute/service 声明了一个这样的要求,因此其 Recipe 会在两个渲染产物之前报告:
$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalogEntity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: presence mandates not checked (monitoring: core/prometheus-exporter) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to carry a type the Component requires. Whether an attachment of each of these types is present is checked when a Release that deploys the Component is built.Resolution: validRender: 2 artifact(s)如果强制要求的声明无法求值——注解前缀后面没有标签,或者值不是 Feature 类型——则不会被搁置:这是 Component 自身的错误,任何挂载都无法修复,validate 会像构建一样因此使运行失败。
每条规则都在能够给出答案的地方被检查。aggrega pull、aggrega build 和 aggrega validate --release 会基于 Release 的实际挂载对两者求值,并在必需挂载槽无任何填充、或强制要求的类型无任何挂载携带时停止。
只有连接或已挂载的 Feature 才能提供的值
第四项是,当 Recipe 的连接和已挂载的 Features 提供了其模板读取的内容后,该 Recipe 能否渲染。
Recipe 的模板会在 .context.inject 和 .context.uses 下读取连接交付的内容,在 .features 下读取已挂载的 Feature 交付的内容。合成的测试框架不接线任何连接,也不挂载任何 Feature,因此所有此类读取都找不到内容:在 .context.inject.env 下的读取会遇到空的交付管道,对 .context.uses 的 range 不会遇到任何连接。validate 会先渲染该 Recipe,渲染完成则照常报告。当渲染停止,且 Recipe 的模板(包括它们导入的文件和库条目)读取了这三者之下的任何内容时,validate 会将渲染报告为未尝试,列出 Recipe 在那里读取的值,打印渲染停止时的语句,并以 0 退出。MariaDB + Adminer 示例的 chart 变体从其两个已挂载密钥所填充的交付管道中读取数据库凭据:
$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yamlEntity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Resolution: validRender: not attempted (this Recipe reads values a build of one cannot supply) Validating a Recipe on its own places its Component in a build that wires no connection and attaches no Feature, so nothing supplies what its templates read under .context.inject, .context.uses or .features. Its render stopped, and whether on one of those values or on a fault of its own is not judged here. To render it, build a Release that deploys a component this Recipe implements. Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD没有找到内容但也没有导致停止的读取不会被搁置:在一次完成的渲染中,对 .context.uses 的 range 什么也没渲染,会按其实际渲染结果报告。
决定结果的是 Recipe 读取了什么,而不是渲染停在了哪里,这带来一个值得你提前了解的后果:在一个同样读取此类值的 Recipe 中,Recipe 自身的错误(例如拼错的键)会与其余内容一起被报告为未尝试,而不是失败。The render stopped: 行包含渲染自身的语句,便于你看出是哪种情况,而对部署该 Component 的 Release 进行构建会完整地评判渲染。
无论 Recipe 读取什么,有两种错误仍会使运行失败,因为任何连接或 Feature 都无法改变它们:无法解析的模板,以及渲染拒绝的引用——渲染上下文未定义的根,或在结构固定的根下拼错的键,例如 .context.instance_idd。无论 Recipe 读取什么,Recipe 声明的调用 fail 的断言既不会被搁置,也不算失败:它会像失败的断言一向那样被报告为警告。如果 Recipe 的模板不读取这三者中的任何一个,其渲染将被完整评判,停止的渲染会以说明原因的语句失败。
validate 工具(属于 aggrega mcp)对同一 Recipe 给出相同的裁定:以这种方式被搁置的渲染会返回有效,其诊断信息中不含任何内容,而上述各行则出现在它与诊断信息一同返回的文本中。
单实体模式的目录加载是容错的:目录中其他位置不相关的损坏实体会被跳过,而不会中止检查,因此它永远不会妨碍对目标进行隔离校验。
被跳过的文件仍会解释因它而缺失的 Component。当某个 Recipe 的 implements 目标未找到,且恰好有一个被跳过的文件声明了该 Component 时,报告会以该文件自身的拒绝开头——其路径、它违反的约束,以及头部中该条件的短代码——随后是一条 note:,说明该文件在加载时被跳过,因此目录中在它所声明的标识下不包含任何内容,再之后是 implements target … not found in catalog 失败,作为需要该文件的原因。当没有被跳过的文件声明该 Component,或有不止一个文件声明它时,未找到失败排在最前,每个被跳过的文件都列在其下方的 note: catalog files skipped at load 之下。这就是 aggrega build 对它所跳过文件给出的说明,编辑器通过 aggrega serve 进行的实体检查以及 aggrega mcp 的 validate 工具也给出同样的说明。没有跳过任何文件的目录,其报告与平常完全相同。
validate 与 lint 和 build 的关系
这三个命令回答三个不同的问题:
aggrega validate— 这是否正确? 检查 Schema、支柱、引用、extends、输入种类能力以及隔离渲染。它不读取任何运行时状态,也不输出任何制品。aggrega lint— 这是否遵循目录发布约定? 检查命名、类别目录对齐、注解前缀、版本递增幅度,以及其余可选启用的发布规范。Lint 与 validate 的三种范围一一对应,但从不检查正确性。aggrega build— 编译一个完整的部署。 Build 需要完整的 Aggregate + Manifest + Release 闭包,并输出提供方原生的制品。它在编译过程中验证自身的依赖闭包,然后进行渲染。aggrega validate --release就是单独执行的这一依赖验证,不进行渲染;单实体 validate 则无需完整的 Aggregate,即可隔离渲染单个 Recipe。
示例
验证整个目录:
aggrega validate --catalog ./catalog在构建某个 Release 之前,准确验证它所依赖的内容:
aggrega validate --release releases/production.yaml验证单个实体,并且(对于 Recipe)查看其隔离渲染的输出:
aggrega validate core/datastore/postgres/recipes/helm.yaml按照工作区配置为其单独指定目录的某个 Release 的条件,验证单个实体:
aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml另请参阅
- ./aggrega-lint.md — 在相同三种范围内对应的约定检查命令。
- ./aggrega-build.md — 将完整的 Aggregate + Release 编译为制品;编译过程中会验证其依赖闭包。
- ./aggrega-inspect.md — 在解析之后查询 IR 图,而不继续进行渲染。
- ../errors/warnings.md — validate 以
notice:行形式呈现的建议性发现。
概要
aggrega validate [entity-path] [flags]说明
Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillarstructure, cross-document library resolution, extends chains, and providerinput-kind capabilities, over every catalog entity. Where the workspaceconfiguration gives its Releases catalog directories of their own underworkspace.releases, it checks the catalog once for each Release, over thedirectories that Release reads, and reports each pass under a line namingits Releases and those directories; Releases reading the same directoriesshare one pass.
With --release, validate checks the entities a Release's dependency closurereaches: closure-scoped pillars, extends, and pre-render authored-valueconformance — the same correctness a build applies, scoped to that Release.It then evaluates the Recipe and FeatureRecipe assertions against the valuesthat Release resolves to, as a build does before it renders, and reports afailing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it acceptsas a single-entity target are Component, Feature, Recipe, FeatureRecipe,Workload and Plugin. A value the kind requires that the file leaves empty isreported first, as a placeholder still owed: every one is named at once, withwhat it takes, read from the kind's own schema. That reading is this scope'salone; a whole-catalog run, a Release's closure and a build do not apply it.Each kind then has its schema checked, then the checks its own kind carries:pillar structure for a Component or Feature; shape for a Workload,FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compileagainst a minimal generated harness, so its resolution, its guards and arender of its output are all exercised. Where that Recipe's source is onethat has to be fetched, the render is reported as not attempted instead:validating one entity on its own reads no lockfile, reads and writes no cacheand makes no network request, so the chart or module it names is neverretrieved and there is nothing to render from. A render that stops while theRecipe's templates read what only a connection or an attached Featuresupplies — anything under .context.inject, .context.uses or .features — isreported as not attempted too: the generated harness wires no connection andattaches no Feature, so that render cannot be judged there, and a fault ofthe Recipe's own beside such a read is set aside with it. A template thatdoes not parse and a reference the render refuses still fail. An assertionthat calls fail, the Recipe's own or one its Component declares, is printedas a warning closed by a sentence saying a Release must satisfy it before abuild can pass, and does not fail the check: the generated harness sets noneof a real Release's values, so it cannot tell an assertion waiting on one fromone that is broken, and a build still halts on it. Any other kind is refused heretoday, and the refusal names the scope that checks it instead: a whole-catalogrun reaches an Aggregate and the library kinds when they sit in a catalogdirectory, and --release reaches a Release, the Manifest it names and theAggregate it deploys.
With an entity path and --release together, the entity is checked in thatRelease's terms: its references — the Component a Recipe implements, alibrary a pillar refers to — resolve through the catalog directories theworkspace configuration gives that Release rather than the workspace's own,so a workspace keeping one catalog variant per Release checks an entityagainst the variant that Release builds with. The checks are the entitypath's; no closure is validated.
The command writes nothing to disk.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--catalog | [] | 目录路径;可重复指定。每个 —catalog <dir> 都会被添加到目录搜索栈的最前面(首个匹配者胜出):该栈为工作区的 catalog_dirs,或者,对于工作区配置在 workspace.releases 下为其单独指定目录的 Release,则为该 Release 的目录;如果工作区根目录下存在名为 catalog 的目录,该栈以它结尾。写为空列表的 catalog_dirs 完全不读取任何本地目录。 |
--ir-graph | false | 除本命令已生成的所有内容外,还将本次运行计算出的 IR 图以 JSON 格式写入 stdout。作者声明为敏感的值会从中隐去;传入 —unredacted 可改为打印这些值。适用于 —release 范围,即唯一将 Release 解析为图的范围。它选择的是一份文档,而 —response-format 设置的是本命令自身报告的写入详略程度;两者都不影响结论或退出码 |
--no-unsupported-field-warnings | false | 屏蔽不支持字段这一类警告:即目标针对你编写的、它无法遵从的内容所发出的通知——它无法表达的 Workload 字段(如 compose 这类低保真目标),或它针对该节点的输入类型不予处理的 aggrega.ai/ 注解。其他渲染警告仍会显示。仅影响显示;不改变渲染输出。适用于实体范围,即唯一进行渲染的范围 |
--plugin | — | 原始 .wasm 文件的路径,用于依据其 describe() 自报信息进行验证——即发布前的编写检查。单独使用时需要 —type;与 Plugin 实体参数一起使用时,会将二进制文件与该实体声明的类型、能力声明、命令镜像和宿主函数记录进行交叉检查。 |
--release | — | Release YAML 的路径。单独使用时,对其解析后的依赖闭包进行验证;与实体参数一起使用时,按该 Release 的条件检查该实体,其引用通过工作区配置为该 Release 指定的目录进行解析。相对路径相对于你运行命令时所在的目录解析,而不是相对于工作区根目录。如果该目录不在任何工作区中且未指定根目录,绝对路径会从该 Release 自身所在的文件夹查找工作区 |
--response-format | detailed | —release 范围(即不带实体参数的 Release 闭包)的输出详略程度:detailed(默认)报告所有诊断以及建议性信息行;concise 仅报告诊断数量和第一条诊断。两者的结论和退出码完全相同。 |
--type | — | 仅针对二进制文件的 —plugin 检查所用的插件类型,会与二进制文件自报的类型进行核对。仅在与 —plugin 一起使用时有意义;当 Plugin 实体提供了类型时,请省略此项(值不一致会导致中止)。 |
--unredacted | false | 打印作者声明为敏感的值,而不是将其隐去。此后输出所到达的任何地方——终端、管道、文件、屏幕录像——都会以明文形式携带这些值。仅作用于 —ir-graph 写出的图,不影响其他任何内容,因此需要配合 —ir-graph 使用 |