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

警告与 Linter 输出

编译器在编译期间发出的非致命警告。警告不会中止构建——它们揭示编写中的不良迹象、编译器所选择的确定性平局决胜结果,以及开发者的模板从未使用的资源。每条发现都会输出到 stderr,并带有一个指明其类型的前缀——warning:、lint: 或 notice:,取决于由哪个阶段产生——以便 CI 流水线捕获并重新呈现它们;无论如何,渲染产物都会生成。

关于致命的编译中止(即会停止构建的诊断),请参阅 fatal-halts.md。

按短代码列出的所有提示

编译器在不中止构建的情况下报告的内容中,有一部分本身就是一个条件:它带有一个短代码(与中止型诊断打印的四位数标识符相同),其消息以一个固定的句子开头。下表提供从短代码到该句子的查找,因此即使你正在阅读的那一行是警告而非中止,你手中的代码也能对应到该发现所涉及的内容。

能在此处占有一席之地的是声明,而非描述。 编译器评估的每条规则都会声明违反时的处理方式——中止构建,或报告该发现并让构建完成——下面各行属于第二种。因此,编译器新增的提示会出现在此处,无需手工编写一行;而变为中止条件的提示则会从此处移除。

该表的覆盖范围有两个界限,在断定某个代码缺失之前,两者都值得了解:

  • 本页的内容并非都属于此类。 下文讲解的若干发现由专门的处理阶段而非声明的规则产生,有些则根本不带条件——它们打印的行仍与各自小节中的描述完全一致,但没有可供查找的代码,因此也没有对应的行。unsupported-field 类别代码就是此类情形的典型形式:它命名的是一类发现,而不是一个条件。
  • 此处有一行并不意味着下文有对应的小节。 在渲染后期产生的提示只做编目而不做讲解,因此某个代码可能在此处对应一个句子,而其更完整的说明位于 fatal-halts.md 的“Conditions that do not halt a build”(不会中止构建的条件)下,该处编目了所有带代码但不中止构建的条件。

sentinels.md 可查找构建打印的任何短代码,无论是提示型还是中止型;当你还不知道手中的代码属于哪一类时,应从这里开始。

短代码开头句子
E0004annotation contribution overridden by an explicit value
E0037cross-boundary link between endpoints rendered by different providers is not supported
E0149attachment name is a near miss for a declared slot
E0167Recipe publishes a provides key its Component does not declare
E0173declared parameter is read by no reference in the Aggregate
E0174uses socket name is a near miss for a declared socket
E0256annotation binding declares one path in both pillar lists
E0297inherited boundary directory carries no template variable, so it resolves to the path the extended Release writes to

Schema 支柱重叠 lint

**触发条件:**某个 Component 或 Feature 在其 spec.schema: 块的 values: 和 infra: 两个支柱中,于同一嵌套深度声明了相同的属性名。在两个支柱中放入相同字段名的 schema 作者,通常本意是只放在其中一个;该 lint 标记这种重复,以便作者确定由哪个支柱拥有该字段。

**流水线位置。**该 lint 在 schema 合并之后、拓扑构建之前的验证阶段运行。它遍历紧凑形式展开之后的 schema,不跟随 $ref:(参见下文的软跳过规则),并将每个重叠属性作为单独的警告报告。

输出形式:

notice: LINT: Component "core/compute/web-server:1.0.0" at ./catalog/component/core/compute/web-server/1.0.0/component.yaml declares property "storage_size" in both values: and infra: pillars (path: storage_size)

对于嵌套属性,路径是从支柱根到该属性的点分路径:

notice: LINT: Feature "core/db-pool:1.0.0" at ./catalog/feature/core/db-pool/1.0.0/feature.yaml declares property "timeout" in both values: and infra: pillars (path: connection.timeout)

加载整个目录时(即不带参数的 aggrega validate),按名称和版本以及读取该实体的文件来命名每个实体,如上所示。构建或对单个 Release 的验证只读取该 Release 所触及的实体,并按名称和版本命名每个实体——at core/db-pool:1.0.0——每个实体只报告一次,无论 Release 中有多少引用触及它:一个 Aggregate 以裸名称引用某个 Feature,一个 Manifest 以名称和版本映射它,二者触及的是同一个 Feature,只报告一次。

**编辑器可见性。**该发现通过语言服务器以警告级别进入编辑器诊断,位于文件开头而非某个键上——它指向的是一个目录实体,而不是你正在编辑的文档中的某个位置,因此没有可放置标记的编写键。它在制品渲染阶段之前产生,因此无需任何开关:无论 serve.build_on_inspect 是否开启,编辑器会话都会显示它。

**软跳过规则。**当某个 schema 分支带有会阻止静态推导属性集的 JSON Schema 2020-12 逃生舱口之一时,遍历器会不发出警告地终止:$ref(跨文档或文档内引用)、patternProperties(基于键形态的属性声明)、设为 true 或某个 schema 的 additionalProperties(分支未逐一命名即接纳的属性),以及组合运算符 oneOf / anyOf / allOf(其分支可能声明不同属性集的析取与合取)。遍历这些分支要么需要在 lint 时求值被引用或被组合的 schema(lint 不执行此类工作),要么会在某个分支的 values: 属性名恰好与另一分支的 infra: 属性名冲突时产生误报。lint 对受影响的嵌套深度不发出警告;同一 schema 的更深层级仍会被遍历并可被 lint。

**编写说明。**编译器不会拒绝支柱名称重叠——该 lint 仅作提示。在两个支柱中都有 storage_size 的 Component 可以编译;开发者侧的 values.storage_size 和运维侧的 infra.storage_size 由各自的支柱 schema 独立验证,而 Recipe 的 valuesMapping: 模板决定哪个支柱的值流入渲染输出。该 lint 之所以存在,是因为这种编写模式几乎总是错误;有意的跨支柱重复非常罕见,真正需要它的作者可以忽略该警告。关于更广泛的跨支柱机制——包括有意跨支柱传递合理的少数情形——参见 vocabulary/data-pillars.md “Cross-pillar mechanics”。

Binding-map-overlap lint(绑定映射重叠检查)

**触发条件:**某个 Manifest 注解绑定在其 maps.infra 和 maps.values 列表中声明了同一个点分路径。该路径会同时经由两个支柱路由;编译器的确定性决胜规则将其经由 infra: 发送,这使得 values: 一侧无法从 Aggregate 到达。该检查会指出这一情况,以便作者将绑定收窄到单一支柱,或有意识地接受仅经由 infra 一侧的路由。

**在流水线中的位置。**该检查在 Manifest 解析之后、任何注解展开触发之前运行,因此无论是否有 Aggregate 注解到达该绑定,构建都会报告重叠的绑定。它按编写顺序遍历 mappings.features.annotations 下的绑定,对每个绑定的 maps.infra 和 maps.values 列表求交集,并为每个重叠路径报告一条结果。在同一个绑定内,重叠路径按该绑定的 maps.values 列表声明它们的顺序报告——也就是你编写它们的顺序——因此对相同输入的重复运行会报告相同的序列。

输出形式:

lint: annotation binding declares one path in both pillar lists (Manifest, at .spec.mappings.features.annotations, "compliance.aggrega.ai/data-class", on Feature "core/pii-redaction", at path "classifier_endpoint", which the routing tie-break sends through the pillar "infra", declare a second binding under another annotation key to route it through "values")
lint: annotation binding declares one path in both pillar lists (Manifest, at .spec.mappings.features.annotations.audit-scope, "audit-scope", on Feature "core/pii-redaction", at path "retention_endpoint", which the routing tie-break sends through the pillar "infra", declare a second binding under another annotation key to route it through "values")

这两行来自对同一个 Manifest 的一次构建,它们的定位符之间的差异在于注解键的形式。定位符通过点分路径定位文档,因此它会在第一个自身带有句点的段处停止:audit-scope 不带句点,定位符可到达该绑定;而 compliance.aggrega.ai/data-class 带有句点,定位符改为指向包含它的 annotations 块。这就是为什么出问题的键也是每条结果中第一个带引号的值——它是定位符无法始终携带的那一部分。

**编辑器可见性。**该结果也会通过语言服务器以警告级别进入编辑器诊断,位置取决于其定位符所能到达之处——对于普通键,位于绑定本身;对于带句点的键,位于外层的 annotations 块。从不阅读终端输出的作者也能看到它。它在产物渲染阶段之前产生,因此不需要开关:无论 serve.build_on_inspect 是否开启,编辑器会话都会显示它。

**以编程方式匹配。**该结果携带来自 pkg/resolver 的 ErrAnnotationBindingPillarOverlap,因此使用方可以通过 errors.Is 识别该类别,而不必匹配消息文本。与所有建议性哨兵一样,它永远不会影响构建的结论——访问器和该条件的代码参见 sentinels.md。

**确定性决胜规则。**运行时通过将该路径仅经由 infra: 支柱路由来解决冲突。这一选择在各次构建之间保持一致,作者可以依赖它。values: 一侧会从该绑定的有效路由中移除——试图到达该路径的 Aggregate 侧注解得不到路由目标,构建会在展开时于 Aggregate 一侧中止,即 fatal-halts.md 中“An annotation routes through a pillar its authoring side may not use(注解经由其编写方不得使用的支柱路由)”所述的中止。该检查是早期警告层面;那个中止是强制执行层面。

**编写说明。**与 schema-pillar-overlap 检查一样,该检查是建议性的——绑定可以编译,运行时的决胜规则会产生确定性的输出。该检查之所以触发,是因为这种编写模式几乎总是无意为之;真正希望两个支柱路由同一路径的绑定作者,会编写两个使用不同注解键的独立绑定。

附件槽位近似名称 lint

触发条件:某个 component 实例以某个名称附加一个 Feature,该名称不是其 Component 类型所声明的 featuresSchema 槽位之一,但与其中某个槽位仅相差一次编辑(插入、删除或替换单个字符,或交换两个相邻字符),且所附加的 Feature 不满足该槽位的 selector。这正是槽位名称拼写错误的形态,lint 会同时给出两种拼写,以便作者看到这一对名称。

存在原因。 声明槽位并不会封闭附件面:以没有任何槽位声明的名称进行附加是合法的,因为正是这种开放性,使同一个目录实体既能用于填充槽位的附件,也能作为在更宽作用域共享的凭据。代价是,拼错的槽位名称会悄无声息地成为一个自由附件,而不是对作者本意槽位的填充:构建成功,而该槽位只是保持为空。此 lint 正是针对这种情况公开提供的缓解措施。

在流水线中的位置。 此 lint 在解析阶段运行,与感知目录的语义守卫处于同一轮处理,作用于已解析的 Aggregate。它将每个 component 实例的附件名称与该实例 Component 类型所声明的槽位名称逐一比对,并为每一对近似名称发出一条警告。

输出形式:

lint: attachment name is a near miss for a declared slot (Aggregate nearmiss, at .spec.components.db.features.app_user_passwrod, "app_user_passwrod", on component type "core/datastore/postgres", near the declared slot "app_user_password")

第一个带引号的值是附件所使用的名称,也就是警告开头一句所针对的内容。随后的两个值由说明其含义的文字引出:附件所在的 Component 类型,以及与该名称仅相差一次编辑的已声明槽位。

编辑器中的可见性。 该警告还会通过语言服务器以警告级别进入编辑器诊断,定位在出问题的附件键上。从不阅读终端输出的作者也能看到这一对名称。它在制品渲染阶段之前产生,因此无需任何开关:无论 serve.build_on_inspect 是否开启,编辑器会话都会显示它。

阈值及其权衡。 此 lint 只对相差一次编辑的名称进行配对,并且仅当两个名称都至少有四个字符时才配对。低于这一长度时,几乎每个短名称都与其他短名称相差不超过一次编辑,配对只会产生噪声而非有效信号;超过一次编辑时,这些配对就不再像拼写错误。交换相邻字符计为一次编辑而非两次,因为交换一对字符是最常见的失误,更严格的计数会漏掉它。

编写说明。 此 lint 仅为建议性质,从不改变构建结论:编译器不干预作者如何命名附件。有意以类似槽位的名称附加 Feature 的作者可以忽略该警告;附件的行为与编写的完全一致。

Feature 适配槽位时不触发。 若某名称与一个槽位相差一次编辑,且所附加的 Feature 满足该槽位的 selector,则不会产生警告。这种配对不是拼错的自由附件,而是以另一名称写下的填充;它是否有影响取决于该槽位最终是否为空,而这只有在所有作用域都折叠完成后才能知道。若槽位为空,构建会中止并指出该附件和槽位(参见 fatal-halts.md 中的 “An attachment written under another name fits a slot its component leaves empty(以另一名称写下的附件适配其 component 留空的槽位)”),因此中止是唯一报告的结果,绝不会同时附带警告。若有其他内容绑定了该槽位,该附件就只是一个普通的额外附件,不报告任何内容。未声明 selector 的槽位不被任何 Feature 适配,因此与此类槽位相近的名称总会产生警告。

不作用于连接。 此 lint 读取的是 component 自身的 features: 块,该块是开放的。连接所携带的附件仅以其 socket 声明的槽位为键,因此与这些槽位之一相差一次编辑的名称在那里是不合法的:构建会直接中止,并在同一句中指出该名称所接近的槽位。不会同时产生警告。参见 fatal-halts.md 中的 “A connection carries an attachment under a name its socket declares no slot for(连接以其 socket 未声明槽位的名称携带附件)”。

Uses-socket 近似拼写 lint

触发条件:某个 component 自身的 uses: 块命名了一个 socket,该 socket 不在其 Component 类型声明的 usesSchema sockets 之中,但与其中一个仅相差一次编辑——插入、删除或替换单个字符,或交换两个相邻字符。这正是 socket 名称拼写错误的形态,lint 会同时给出两种拼写,以便作者看清这一对名称。

**存在原因。**声明 socket 并不会封闭开发者自身 component 上的 uses: 接口:没有任何 usesSchema 条目声明的 socket 名称是合法的,因为目录对某个 socket 未作说明,意味着该连接未被预料到,而非被禁止,并且 Aggregate 的拓扑由开发者掌控。代价是,拼错的 socket 名称会自成一个临时连接,而不是连接作者原本想要的 socket——构建成功,预期的 socket 只是保持未连接,而该临时边不携带 selector,也没有逐边契约。该 lint 正是针对这种情况公开提供的缓解措施。关于临时 socket 失去什么、保留什么,请参阅 entities/component.md “Topology Sockets: usesSchema”。

**覆盖哪个接口。**仅覆盖 component 自身的 uses: 块——这是唯一接受未声明 socket 名称的接口。Feature 挂载的 uses: 只能命名所挂载 Feature 声明的 socket,Release 的逐边 uses: 只能命名消费方 Component 声明的 socket;这两处若名称有误,构建已经会中止,因此警告无可补充。

**在流水线中的位置。**该 lint 在解析阶段运行,与感知目录的语义检查处于同一轮,作用于解析后的 Aggregate。它将每个 component 实例自身的 socket 名称与该实例 Component 类型声明的 socket 名称逐一比对,每个近似拼写对发出一条警告。来自子 aggregate 的 component 不在覆盖范围内:其内部 components 在这一轮运行之后才被合并进图中。

输出形式:

lint: uses socket name is a near miss for a declared socket (Aggregate aggregate, at .spec.components.web, "databses", on component type "core/devtool/adminer", near the declared socket "databases")

第一个带引号的值是作者所写的 socket 名称,也是警告开头一句所针对的内容。随后两个值由说明其含义的词语引出:命名该 socket 的 Component 类型,以及与其相差一次编辑的已声明 socket。警告没有明说的后果即上文所述:拼错的名称是一个临时连接,因此不携带 selector,也没有逐边契约,而作者原本想要的 socket 保持未连接。

**编辑器可见性。**该警告还会通过语言服务器进入编辑器诊断,严重级别为 warning,定位在其 uses: 块包含问题名称的 component 上。从不阅读终端输出的作者同样能看到这一对名称。它在制品渲染阶段之前产生,因此无需任何开关:无论 serve.build_on_inspect 是否开启,编辑器会话都会显示它。

**阈值及其权衡。**该 lint 仅配对编辑距离为一的名称,且仅当两个名称都至少有四个字符时——与 attachment-slot 近似拼写 lint 使用相同的界限,理由也相同。低于该长度时,几乎每个短名称都与其他短名称相差一次编辑,配对只会产生噪声而非信号;超过一次编辑,配对就不再像拼写错误。交换相邻字符算作一次编辑而非两次,因为交换一对字符是最常见的笔误,更严格的计数会漏掉它。

**编写说明。**该 lint 仅作提示,从不改变构建结论——编译器不干预作者如何命名 socket。作者若有意以类似已声明 socket 的名称建立临时连接(例如在已声明的 caches socket 旁另建一个用于其他用途的 cache 连接),可以忽略该警告;该边的行为与所写完全一致。没有用于屏蔽它的标志,也不需要:它对构建结论没有任何影响。

未声明 provides 键 lint

**触发条件:**绑定到某个组件实例的 Recipe 在其 provides: 下发布了一个键,而该实例的 Component 类型未在其 spec.schema.provides: 契约中声明该键。

存在原因。发布多于 Component 所声明的内容是合法的,并将一直合法:provides 契约要求子集、允许超集,因此一个覆盖了其 Component 契约并额外输出其他键的 Recipe,就是履行了该契约的 Recipe。该 lint 指出的是一个从任何一方都无法察觉的后果。通过 uses: 边读取的消费者看到的是目标的已声明契约,而不是目标的 Recipe 碰巧输出的任何内容——正是这一点让 Recipes 可以互换,因为实现同一个 Component 的两个 Recipes 会向消费者呈现相同的接口,替换它们不会悄无声息地撤回消费者已经依赖的键。因此,未声明的键不会跨边传递,读取它的消费方模板会渲染出空值,而不会失败。

该发现在其成因处——即发布该键的 Recipe 上——报告,因为只有在那里才能指明它。在消费者处,该键只是一个编译器无法归属到特定目标的模板引用,而靠猜测给出的诊断比没有诊断更糟。因此两者被有意地分开:空值出现在消费者处,解释出现在这里,而两者都出现在同一次构建输出中。

**比较哪一对。**将所绑定 Recipe 编写的 provides: 键与 Component 类型声明的 spec.schema.provides: 键进行比较。该声明集合与 inject: 块中 from: 键所对照检查的集合相同,因此两者对 Component 声明了什么的认定一致。该比较是精确比较而非相似度测试,因此与上文两个近似匹配 lint 不同,它没有阈值,也不配对名称。

所比较的 Recipe 是该实例实际绑定的那个,按照渲染时绑定所用的相同实例名称和目录类型进行匹配,因此 Manifest 中按实例的 Recipe 覆盖会得到遵从,而不会被平均掉。类型解析不到任何目录 Component 的组件实例会被跳过:没有读取到任何声明,这与声明为空并不相同。

**流水线位置。**该 lint 在解析阶段运行,与感知目录的语义守卫在同一轮中,作用于已解析的 Aggregate——在渲染之前,因此它既会出现在 aggrega validate --release 中,也会出现在 aggrega build 中。在 Aggregate 根部声明的 Components 和嵌套在子系统中的组件都会覆盖。来自子 aggregate 的组件不在覆盖范围内:其内部组件在这一轮运行之后才被合并进图中,因此这类组件的未声明键仍会对消费者隐藏,但没有任何提示会指出它。

**输出形式。**每个组件实例和键一行,指明发布该键的 Recipe 以及未声明该键的 Component:

lint: Recipe publishes a provides key its Component does not declare (Recipe broker-with-region, at .spec.provides.region, "region", on component type "core/ai-model/openai-compatible", bound to component instance "gateway")

该发现属于携带它的实例,因此同一 Component 类型的十个实例发布同一个未声明键时,会产生十行而不是一行,每行指明各自的实例。每一行都归属于发布该键的 Recipe,因为那正是你为解决它而需要编辑的文档。遍历是确定性的,因此相同的输入在每次运行时都会产生相同的提示序列。

**编辑器可见性。**该提示还会通过语言服务器以 warning 级别进入编辑器诊断,定位在其 type: 绑定该 Recipe 的组件实例上。从不阅读终端输出的作者也能看到它。它在制品渲染阶段之前产生,因此无需任何开关:无论 serve.build_on_inspect 是否开启,编辑器会话都会显示它。

**编写说明。**该 lint 仅作提示,从不改变构建的结论——发布多于其 Component 所声明内容的 Recipe 仍能构建。修复方式有两种,哪一种正确由作者决定:当消费者需要读取该键时,在 Component 上声明它;当它是 Recipe 自身的工作状态时,保持不声明,此时这类状态应放在 locals: 中。相反的情况则不是提示:Component 声明了其 Recipe 未发布的键,会使契约无法履行并中止构建。

Ghost Infrastructure Tracker 警告

触发条件:作者声明的某个键到达了某个节点,而所绑定的 Recipe 声明的任何模板都从未引用它。这些未被读取的键会成为静默的基础设施:开发者或运维人员要求的配置,Recipe 却从未将其接入渲染输出。追踪器将它们呈现出来,使编写内容与输出内容之间的差异变得可见,而不是保持静默。

比较哪些编写的键。 每个节点三组:

  • .values:节点自身的开发者侧支柱。
  • .infra:节点自身的运维侧支柱。
  • .context.uses.<alias>.values:节点所消费的每条 uses: 边上携带的逐连接值。这一组天然按消费者划分作用域:节点的 uses 映射只包含以它为源的边,因此未被读取的逐连接值总是归属于编写它的节点,而绝不归属于该边的目标。

收集哪些引用。 所绑定的 Recipe 声明的每个模板。该警告表示某个键没有任何地方读取,这是关于整个 Recipe 的论断,因此任何比整个 Recipe 更窄的范围都会使其变为错误而非近似——被 source: 坐标消费的键,会被恰好拉取了它所指定版本的那次运行报告为未读取。读取的块包括:

  • valuesMapping:,交给 provider 的 values 覆盖层。
  • source::以单个字符串编写时为整个字段,以对象编写时为其中每个字符串值字段。source 坐标是按每个消费实例求值的模板,因此从 .values 或 .infra 中选取的版本、chart 名称、git 引用或模块子目录会读取这些键。
  • locals: 和 provides:,每个条目。
  • assertions:,每个条目。
  • workload:,合成的 Workload 主体。
  • artifacts:,每个条目的内容。
  • pipeline:,每个步骤的 with: 输入及其 when: 门控。

由此有三个边界,三者都是对能如实论断之内容的限制,而非选择。每一个都使读取静默而非扩大读取范围,这是代价最小的方向:未报告的键只让读者错过一条他们仍可通过阅读 Recipe 找到的提示,而错误报告的键则会告诉他们一个有效的设置被忽略了。

  • 没有内联 valuesMapping: 的 Recipe 完全不被读取。无论其其他模板如何,其键都会被跳过而不报告。
  • Recipe 从文件或库引用导入的块在此时尚不可用,因此无法收集其引用。该节点的键会被完全跳过而不报告——这对导入的 valuesMapping:、导入的 workload: 和导入的 artifacts: 条目同样适用。
  • 解析失败的模板不产生任何引用集。将每个键都报告为未读取,会淹没求值过程针对同一模板产生的解析诊断,因此改为不报告任何内容。artifacts: 条目使用标准的 {{ }} 定界符读取,而这并非每个 provider 为该字段声明的定界符对;用错误的定界符对读取时,这样的主体会产生其作者从未编写的引用,或者无法解析,而这两种结果都只会使警告静默。

socket 的 valueSchema 永远不会被标记。 usesSchema.<socket>.valueSchema 声明了逐连接值必须满足的契约。它是 schema,而非编写的实例,也不在被比较的输入之列——因此永远不会被报告。socket 声明的默认值所产生的内容与其他实例一样,是否被读取各自独立判断。

指向整个支柱的引用会将其下的每个键都计为已读取。 {{ .infra.port }} 将 port 标记为已读取,该支柱的其他键仍可能触发警告。{{ optional .infra `port` 8080 }} 将整个 .infra 映射交给一个函数,因此收集到的引用指向该支柱而非其下的某个键,该支柱中的每个键都计为已读取,该支柱不会产生任何警告。对支柱进行 range 遍历,以及通过 index 访问某个 uses 条目,情况相同。希望按键覆盖的 Recipe 作者应编写按键的引用。

这会影响上述每个块,在把一个安静的支柱当作漏报警告之前值得了解:若 Recipe 的 source: 版本写为 {{ optional .infra `source_version` "1.2.3" }},就已将整个 .infra 映射交给了函数,因此该 Recipe 在其渲染的任何节点上都不会报告任何 .infra 键。.values 支柱不受影响——两者分别计数。

流水线位置。 追踪器在基础渲染阶段运行,与模板求值并行。Recipe 的每个模板都会被解析并遍历,以收集其引用的点号限定字段路径(.values.port、.infra.replicas、.context.uses.<alias>.values.retry_budget);每组解析后的键集与这些引用的并集比较,差集即为未读取集。遍历的是编写时的 Recipe:source: 坐标按其模板文本读取,而非按该模板为此实例产生的值读取。

输出形式。 每个未读取的键一行,指明节点、该组的路径、键,以及没有任何模板读取它的 Recipe:

warning: node "data.main-db": .values key "database_name" is read by no template in recipe "helm-postgres-sourced-with-artifacts" — correct the spelling, or remove the key
warning: node "data.main-db": .infra key "storage_class" is read by no template in recipe "helm-postgres-sourced-with-artifacts" — correct the spelling, or remove the key
warning: node "frontend": .context.uses.my-api.values key "retry_budget" is read by no template in recipe "helm-web-ui-sourced-with-artifacts" — correct the spelling, or remove the key

该行不指明 Recipe 的任何字段,这是有意为之:编写该键的人是开发者、运维人员或其所依附的 uses: 边的作者,他们都不会编辑 Recipe。指明查找引用的块,会给读者一个位于他们不会打开的文档中的坐标。该行提供的两种补救措施正是他们可以采取的——拼写错误的键是常见原因,而一个本就不会被读取的键值得删除。

顺序是固定的:先是节点的 .values,然后是其 .infra,再按边的输出顺序依次是每个 uses 别名,每组内的键按顺序排序。因此相同的输入在每次运行时都会产生相同的警告序列。

编辑器可见性。 仅当语言服务器在检查 IR 图时运行制品渲染阶段,该警告才会进入编辑器诊断——即 aggrega serve --build-on-inspect,或它所覆盖的 serve.build_on_inspect 配置键,后者默认关闭。该开关会添加构建在渲染时产生的提示,但不包括构建会因之中止的任何检查。该条目指向节点而非编写键,因此会绘制在 Aggregate 的 kind: 键上。

为何是警告而非致命中止。 开发者可能在条件模板逻辑中合理地消费不同的 .values 子集——模板依据 .values.mode 分支的 Recipe 会读取 mode,但仅在 mode == "replication" 时才有条件地读取 .values.replication_password。静态遍历无法判断未被引用的键是无关紧要还是缺陷。追踪器的目的是让差异可见,而不是去监管它;静默遗漏才是追踪器所防止的失败模式。

Recipe 作者的应对。 当 Recipe 作者看到某个他们期望 Recipe 消费的键出现 Ghost Infrastructure 警告时,修复方法是将该键接入模板。当未读取的键是有意遗漏时(chart 不支持的功能、Recipe 有意忽略的编写便利),作者可以在 Recipe 的头部注释中记录该遗漏,让后来的读者知道这一差异是有意为之。

未读取的已声明参数警告

**触发条件:**某个 Aggregate 在 spec.parameters: 下声明了一个条目,而该 Aggregate 自身文本中没有任何 {{ .parameters.<key> }} 引用读取它。

已声明的参数是为每个 Release 改变某一个值的编写接口:Release 满足该声明,再由引用把满足后的值带入它所属的 component 值中。没有任何内容读取的声明会让这种变化无处落地——无论 Release 为它提供什么,渲染输出都相同。这是在参数范围内的同一种隐患,与一个无人使用的已编写 values 键相同。

**默认值不构成豁免。**没有引用读取的默认值和 Release 提供的值一样不会进入输出,因此带默认值的声明与不带默认值的声明会以完全相同的方式被报告。

**收集哪些引用。**仅收集该 Aggregate 自身的文本,不收集其他内容。由此有三个推论:

  • 仅由 Component schema 的 validate: 谓词读取的参数在此不可见。这类谓词通过解析后的参数映射来指名参数,而不是通过 Aggregate 中的点号引用,因此即使谓词读取了该参数,该声明仍会被报告为未读取。
  • 无法作为模板解析的文本不会产生引用集。若将每个声明都报告为未读取,就会淹没插值过程针对同一文本产生的诊断,因此改为不报告任何内容。
  • 指名整个 parameters 映射的引用——遍历它,或通过 index 访问其中一个条目——会将每个声明都视为已读取,因为此时收集到的引用指名的是该映射,而不是其下的某个键,无法做出逐键的判断。

**在流水线中的位置。**该读取在解析阶段运行,作用于 Aggregate 的原始文本及其声明的参数契约——在渲染之前。因此它既会出现在 aggrega validate 中,也会出现在 aggrega build 中。

**输出形式。**每个未读取的声明输出一行,指明 Aggregate 和该声明的定位符:

lint: declared parameter is read by no reference in the Aggregate (Aggregate fullstack-app, at .spec.parameters.unread_probe, "unread_probe")

结果按 Aggregate 声明其参数的顺序给出,因此同一个 Aggregate 每次运行都会产生相同的序列。每条结果都带有声明的定位符,其中指明了出问题的键。消息中也会指明该键,所以在同时打印定位符的终端行中该键会出现两次:编辑器只在其定位的位置显示消息,从不显示定位符文本,因此如果消息省略了键,每个未读取声明的消息读起来都会完全相同。

**编辑器中的可见性。**该提示也会通过语言服务器以警告级别进入编辑器诊断,定位在其定位符所指明的声明上,而不是整个 Aggregate 上。它在制品渲染阶段之前产生,因此不需要任何开关:无论 serve.build_on_inspect 是否开启,编辑器会话都会显示它。

**为什么是警告而不是致命中止。**参数可能先于将要读取它的引用被声明,而静态遍历无法将这种情况与错误区分开——这与已编写键的读取只给出提示的原因相同。编译器不干预作者公开哪些配置项。

Provider 绑定未服务能力警告

**触发条件:**工作区配置中 plugins.providers 下的某个条目指定了 capability 但没有 uri,并且构建读取的所有 provider 插件都不提供该能力。构建读取的插件包括其目录(catalog)中的插件、编译器内置的 provider,以及其 lockfile 记录的插件。

**存在原因:**只有当某个 Recipe 的 capability: 请求某项能力时,对应的绑定才会被读取;而一个未指定插件的条目,所选中的内容与没有它时该能力的解析结果完全相同。因此,能力名拼写错误的条目(例如把 helm 写成 hlem)不会被任何地方查阅,也不会改变任何东西;如果没有这条警告,就不会有任何提示。

为什么是警告而不是致命中止。 绑定针对整个工作区只编写一次,而一次构建只针对一个 Release。提供该能力的插件可能只有工作区中的另一个 Release 会读取,而本次构建看不到它,因此在这里中止会凭猜测拒绝一个合法的工作区。同时指定了插件的条目则是另一种情况:无论是否有 Recipe 使用它,pull 都会解析每个这样的条目,因此构建持有该插件并知道它提供什么,而该插件不提供的能力会导致中止——参见 fatal-halts.md 中的“A plugins.providers binding names a plugin that does not serve the capability(该绑定指定的插件不提供该能力)”。对于构建所读取的某个插件确实提供的能力,其条目不会被报告,无论本 Release 中是否有 Recipe 使用它。

**在流水线中的位置:**每次对 Release 的构建和验证,都会在分析该 Release 的图之前读取组合后工作区配置中的每个条目(包括各层及其 providers_append 配套项),因此该警告既会出现在 aggrega validate --release 中,也会出现在 aggrega build 中,还会出现在 aggrega pull 中——后者会基于即将写入的 lockfile 渲染一次该 Release,以发现其构建所获取的外部输入。该判断不会改变由哪个插件渲染 Recipe;这一点从 lockfile 中读取。

**输出形式:**每个条目一行,按组合后列表中的顺序排列,列出该能力名称,以及在存在时与其相差一次编辑的已提供能力:

warning: plugins.providers entry names a capability no provider-rendering plugin the build reads serves: capability "hlem", which is one edit from "helm"; the entry names no plugin, so it selects nothing a Recipe would not resolve without it, and none of the plugins this build reads — in the catalog directories, inside the compiler, or among those the lockfile records — serves the capability: correct its spelling, or keep it where the plugin serving it is one only another Release reads

**阈值:**只有在编辑距离为 1 且两个名称都至少有 4 个字符时才会给出拼写建议,这与上文近似匹配 lint 使用的界限相同,原因也相同。

**编辑器可见性:**该警告通过语言服务器以警告级别进入编辑器诊断。由于该条目位于配置文件中,而不在正在编辑的文档中,因此它被放置在该文档的开头,而不是某个键上。

按实体划分的元数据覆盖情况

哪些实体信封携带 metadata.labels 和 metadata.annotations 因类型而异。Component、Feature 以及各库类型两者都携带;Aggregate 只携带 labels;Recipe、FeatureRecipe、Manifest、Release 和 Plugin 在信封层级不接受这两个键中的任何一个。语言状态记录了每个实体的情况,是应当查阅的地方。

编辑器可见性。 无论采用何种设置,都没有任何提示涵盖这一点:没有可报告的内容,因为一个实体要么携带这些键,要么不接受它们;而某个类型不接受的键,是由其 schema 在文档加载时回答的问题,而不是渲染阶段事后报告的内容。作者应查阅状态页面,而不是等待警告。

不支持字段警告

一个类别涵盖你编写的、目标无法遵从的所有内容。它有两个成员——目标无法表达的 Workload 字段,以及目标不会据以执行的 aggrega.ai/ 注解——二者共用一个类别代码和一个抑制标志,因为想让“该目标忽略的内容”静默的作者,希望它们一起静默,而不是逐个开关地处理。

目标无法表达的 Workload 字段

各目标的保真度不同。一个目标原生表达的 Workload 字段,在另一个目标上可能没有对应项——例如,Docker Compose 没有调度约束、服务账号或优先级类的概念。当 Workload 声明了这样的字段而目标无法表达时,该字段会被省略并给出警告,每个编写的字段一条警告。它既不会被静默丢弃,也不会被视为致命错误。

它与致命中止的区别在于粒度。不受支持的形式会明确地中止构建——目标根本无法生成那种形态的工作负载。受支持的形式若带有无法表达的字段,则会去掉该字段后渲染,并给出说明。

在 compose 目标上,该类目前涵盖 scheduling、serviceAccount、replicas、runtimeClassName、priorityClassName、imagePullSecrets、dnsPolicy、dnsConfig.options、容器的 runAsNonRoot,以及除 nvidia.com/gpu 之外的所有扩展资源键(例如 amd.com/gpu),因为该键被保留用于 NVIDIA GPU。下列情况会发出同一类的部分变体,此时字段被缩减而不是被移除:

  • persistentTemplate——按副本的卷模板不可用,因此该卷会合并为单个共享持久卷,而不是消失。
  • 带有 as: env 的容器 attachments 条目——compose 无法从附件获取环境变量,因此该变量以空值输出。警告会以条目的编写坐标(containers.<name>.attachments.<KEY>,位置式 init 条目则为 initContainers[<i>].attachments.<KEY>)指明该条目,从而清楚哪个变量为空、属于哪个容器。带有 as: file 的条目会正常进行绑定挂载,不会引发任何警告。
  • 没有任何容器挂载的 volumes 条目——警告会以该卷的编写坐标(volumes.<name>)指明它。输出中出现什么取决于变体:persistent 或 persistentTemplate 卷仍会声明为命名卷,随后被创建但不被使用;而 configmap、secret 或 ephemeral 卷只能通过容器的挂载点进入输出,因此没有挂载时该声明不会产生任何输出。无论哪种情况,你编写的卷都不起作用:请从容器挂载它,或将其删除。工作负载的每个容器都算作挂载方,包括 init 容器,因此仅由 init 容器挂载的卷不会引发任何警告。
  • 声明了多个探针槽位的 health 块——compose 服务只有一个 healthcheck,因此按优先级顺序 live > ready > startup 保留一个槽位,其他声明的槽位都不会进入输出。警告会以该块的编写坐标(containers.<name>.health,位置式 init 条目则为 initContainers[<i>].health)指明它,并同时列出被转换的槽位和被丢弃的槽位,从而清楚输出中哪个探针生效、哪些编写意图不起作用。只声明一个槽位的块可无损转换,不会引发任何警告。
  • 同时声明了 initContainers 的工作负载上的 hostNetwork——工作负载自身的服务运行在节点网络上,但每个 init 容器会成为各自独立的服务,自行加入边界网络,因为共享主服务的命名空间会使主服务对它的等待形成循环。这比所建模的 pod 形态更窄(在 pod 中所有容器共享一个命名空间),因此该差异会被明确指出,而不是留到运行时才被发现。声明了 hostNetwork 但没有 init 容器的工作负载可无损转换,不会引发任何警告。

目标不会据以执行的注解

aggrega.ai/ 注解是 provider 读取并应用于其渲染内容的平台指令——命名空间、镜像仓库前缀、服务账号。provider 读取其中哪些,由该 provider 按输入类型自行声明,因为一个对自己合成的部署单元拥有全部字段的 provider,在渲染外部引入的制品时,往往没有地方放置同一个值。Well-Known Annotations 是对应的矩阵。

节点自身的 Recipe 与附加到该节点的每个 feature 分别渲染,各自通过其自身 capability: 指定的目标,并按其自身 source:、workload: 和 artifacts: 声明的输入类型进行。当此类注解到达其中某次渲染,而解析出的目标的声明在该次渲染所声明的任何输入类型上都不涵盖该键时,目标对该键不应用任何内容,构建会给出警告说明,指明该键、目标以及该次渲染声明的每种输入类型:

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

以下结果源于注解到达渲染的方式,每一项都是有意为之:

  • 一行编写内容可能产生多条警告。 边界注解会级联到其下的每个 component,而这些 component 可能通过不同的目标和不同的输入类型渲染。每条警告都是对某一次渲染的真实陈述,因此每个无法据该键执行的渲染都会产生一条警告——这也正是告诉你输出中哪些部分受到影响的方式。
  • 附加到节点的 feature 依据其自身的 FeatureRecipe 判断,而不是依据节点的 Recipe。 自行生成资源的附件会通过其 FeatureRecipe 指定的目标、按该 FeatureRecipe 声明的输入类型渲染这些资源——因此节点自身目标应用的注解可能在附件的文件中不起作用,反之亦然。你会分别收到关于每一方的提示,因为它们是不同的文件。附加到边界而非具名 component 的 feature 同样如此。如果附件的 FeatureRecipe 未声明 source:、workload: 和 artifacts: 中的任何一个,它就不渲染自己的文件——它通过注入值、通过其 Feature 携带的 uses 边,或通过作用于其他内容所输出文档的流水线发挥作用——因此不存在注解可能缺失的自身输出,也不会为它发出任何警告。
  • 声明了多种输入类型的渲染会依据所有类型判断。 其声明的类型以相加方式组合,输出也相加,因此只要目标在其中任一类型上读取该键,就会应用它,值也会出现在渲染输出中。这种情况下不会发出警告,因为没有需要报告的内容。只有当每种声明的类型都未涵盖该键时才会出现警告,并列出所有类型——on sourced or synthesized input。
  • 只检查不带子前缀的 aggrega.ai/ 键。 带子前缀的键——compliance.aggrega.ai/data-class,或你自己的 acme.aggrega.ai/team——属于你的词汇,编译器原样传递而不加解释。对这类键永远不会发出警告。
  • 完全未声明任何支持声明的目标不会引发任何警告。 该警告将你编写的内容与 provider 声明会读取的内容进行比较;未作任何声明的 provider 不提供可比较的依据,而从沉默中推断出拒绝,将会报告一个 provider 作者从未作出的声明。不读取任何这些键的 provider 会用 readsNoWellKnownAnnotations: true 表明这一点,terraform 就是如此;此后,到达其任一渲染的每个裸键都会引发警告。

为什么是警告而不是中止。 一个合理地跨越异构目标上多个 component 的边界,总会有某个节点无法据给定键执行——这是跨越多个目标的 Release 的正常形态,而不是错误——因此拒绝构建会否定正确的 Releases。值会原样传递,警告会告诉你这一点。

类代码与带外保证

每条警告都带有稳定的、可供机器匹配的类代码 unsupported-field,因此工具可以匹配该类,而无需解析消息文本。该类的每个成员(被完整省略的字段、被缩减形式的字段,以及未被处理的注解)都带有这同一个代码,正因如此,一个过滤器就能抑制整个类。这些警告在渲染产物之外以带外方式传递,这意味着无论警告是否显示,渲染出的字节都完全相同:抑制它们不会改变你的输出。

编辑器可见性。 只有当语言服务器在检查 IR 图时运行产物渲染阶段,该类的每个成员才会进入编辑器诊断:即 aggrega serve --build-on-inspect,或它所覆盖的 serve.build_on_inspect 配置键,该键默认关闭。这一开关会加入构建在渲染时产生的建议性提示,但不会加入任何使构建中止的检查。上述类代码在发布的诊断中与在终端输出行中一样随之传递,因此编辑器客户端匹配的是作者读到的同一个类。每个条目指明的是一个节点和一个目标,而不是某个编写键,因此它显示在 Aggregate 的 kind: 键上。

抑制该类

两个执行渲染的命令都接受 --no-unsupported-field-warnings,它只屏蔽这一类,其他所有渲染警告仍会显示:

Terminal window
aggrega build --release release.yaml --no-unsupported-field-warnings
aggrega validate ./catalog/recipe/compose/mariadb/1.0.0/recipe.yaml --no-unsupported-field-warnings

该标志只影响显示,不会改变渲染输出。aggrega lint 没有对应的标志,因为它不执行渲染过程:它只检查发布约定,因此不会产生任何渲染警告。

当你有意接受降低的保真度时,可以使用该标志,例如用于本地开发的 compose 目标,此时生产 Workload 的调度字段和服务账号字段本就预期不起作用。其他情况下请不要启用:这条警告正是你得知自己编写的某个字段未到达目标的途径。

声明为敏感的值以字面量形式传递

触发条件:某个 attachment 填充 slot 时,将其 schema 声明为敏感的数据作为字面量值传入某个交付键,而不是作为目标在部署时解析的引用。

**输出形式。**每个交付键一行,列出 attachment 实例、该键所在的交付机制以及该键本身,并归属到渲染它的节点和目标:

warning: node "db" (provider "compose"): attachment "user_password" delivers a value declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the target supports it, fill the slot with an attachment that delivers a reference instead

**类别代码。**该提示带有稳定、可供机器匹配的类别代码 sensitive-by-value,因此工具可以匹配类别,而无需解析消息文本。该代码既出现在终端输出行上,也出现在语言服务器发布的结构化诊断中,因此作者和编辑器客户端读到的是同一类别——但须满足下文的编辑器可见性条件,该条件决定语言服务器是否发布此提示。

**编辑器可见性。**只有当语言服务器在检查 IR 图时运行制品渲染阶段,该提示才会进入编辑器诊断——即 aggrega serve --build-on-inspect,或它所覆盖的 serve.build_on_inspect 配置键,该配置键默认关闭。这一开关会加入构建在渲染时产生的提示,但不会加入任何使构建中止的检查。该条目指向的是节点和目标,而不是某个编写键,因此它显示在该 Aggregate 的 kind: 键上。

**它自成一类,--no-unsupported-field-warnings 不涵盖它。**该标志屏蔽的是上文的 unsupported-field 类别;此提示仍会与之一同出现。没有任何标志可以屏蔽此提示。

**构建成功,渲染出的字节不变。**与 unsupported-field 类别一样,该提示在渲染制品之外的带外通道传递,因此无论该行是否出现,到达你输出中的内容都相同。

声明为敏感的值通过 values 映射到达目标

**触发条件:**来自 source: 的渲染把 valuesMapping: 的输出交给其目标,而该映射所读取 values 的实体将某个 values 叶子声明为敏感:即 Recipe 对其 Component 所声明叶子的映射,或附加到组件上的 Feature 的 FeatureRecipe 对该 Feature 所声明叶子的映射。映射是一个模板,其输出键由它自行定义,因此没有任何声明命名这些键,目标也不会收到该叶子的逐键敏感标记。这是唯一一种声明无法到达任何渲染键、而作者仍对其握有调节手段的渲染形态。

**输出形态。**每个已声明的叶子一行,给出该叶子的编写坐标,以及其映射决定这一关联的 Recipe 或 FeatureRecipe,并归属于渲染它的节点和目标。附加 Feature 的行以其附加时使用的名称开头,因为一个组件可以承载同一个 Feature 的多个附加,否则它们的行会完全相同——下面第二行是以 token 名称附加到组件 api 上的 Feature:

warning: node "api" (provider "terraform"): "values.token" is declared sensitive, but recipe "terraform/api" maps its values through a valuesMapping whose output keys no declaration names, so the target receives no per-key sensitivity marking for it; where the mapping reads it, the mapping's whole output is marked as carrying a value declared sensitive instead; a recipe declaring no valuesMapping renders the declared leaf paths as its own keys, and the per-key marking travels with them
warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping whose output keys no declaration names, so the target receives no per-key sensitivity marking for it; where the mapping reads it, the mapping's whole output is marked as carrying a value declared sensitive instead; a FeatureRecipe declaring no valuesMapping renders the declared leaf paths as its own keys, and the per-key marking travels with them

**调节手段是什么。**没有映射时,源渲染收到的 values 直接以声明的叶子路径为键,因此声明与其渲染键精确对应,标记随之传递——在 Terraform 目标上,这就是 Declared-sensitive module inputs(声明为敏感的模块输入)中描述的生成覆盖文件。有映射时,确实到达的标记覆盖映射的整体输出,且仅在映射读取了所声明的值时才如此:它决定插件在拒绝或警告时所撰写的文本,而不改变任何渲染字节。

**有三种形态保持静默,而且是有意为之。**仅制品的渲染和仅 workload 的渲染根本不向目标传递 values 映射,因此无论如何编写,values 叶子在那里都没有可标记的渲染键。附加到边界上的 Feature 同样不会触发,无论其 FeatureRecipe 映射什么:边界不带 values: 块,因此这样的附加针对空的 values 支柱渲染,其 Feature 的任何 values 叶子在那里都无法承载数据,移除映射也不会标记任何内容。每一种都是该形态的固有属性,而非作者可以改变的东西,因此对其发出警告会在每次构建时触发且无可操作之处;这一上限改为在声明叶子为敏感中讲解。来自 source: 且没有 valuesMapping: 的渲染也保持静默,因为在那里标记能够到达。

**类别代码。**该提示带有稳定、可供机器匹配的类别代码 sensitivity-not-conveyed,因此工具匹配类别而不必解析消息文本:助手的 build 工具在 advisories 下列出每条结果时附带该代码。它命名的是一类结果而非已注册的条件,因此在本页顶部的表格中没有对应行。

**编辑器可见性。**每当语言服务器渲染 Release 时——被请求的构建或构建预览,或使用 aggrega serve --build-on-inspect 进行的 IR 图检查,或它所覆盖的 serve.build_on_inspect 配置键(默认关闭)——该提示都会以警告级别进入编辑器诊断,并带有与终端构建打印的相同行。该条目命名的是节点和目标而非编写键,因此它显示在 Aggregate 的 kind: 键上。

**它自成一类,--no-unsupported-field-warnings 不覆盖它。**该标志屏蔽的是目标的保真度提示,那是出于不同原因作出的不同判断;本提示仍会与之一同出现。没有任何标志可以屏蔽本提示。

**构建成功,渲染字节不变。**该提示报告的是一种缺失——没有任何渲染键带有标记——而映射是一种普通的、受支持的形态,因此没有理由中止,无论该行是否出现,你的输出都不会有任何变化。

引擎在初始化时获取的 Terraform 模块调用

**触发条件:**构建所 vendor 的某个 Terraform 模块,或某个 Recipe 编写的 Terraform 主体,声明了一个 module 块,而其 source 是 Terraform 在初始化配置时下载的,而非从构建放置的文件中读取:registry 地址,git、Mercurial 或 HTTP 归档 URL,S3 或 GCS 存储桶,或绝对路径——或者是跳出所 vendor 模块的本地路径,它指向构建未 vendor 的文件。锁文件固定了所 vendor 模块的提交和归档摘要,而 Terraform 自身的依赖锁文件只记录 provider,因此此类调用所指向的模块会以引擎当时选择的任意版本获取,本次构建记录的任何内容都不覆盖它。

**读取范围。**模块被调用时引擎加载的配置文件——即直接位于模块自身目录中的文件,以及从该目录出发经本地 source 到达的每个目录中的文件——而不读取任何没有被调用的目录,因此写在模块 examples/ 或 tests/ 目录中的调用不会被报告。它读取 source 所写的内容,从不读取该 source 所指向的模块。Recipe 的 spec.boundary.artifacts 下的文件由编译器自身求值并写出,不交给任何 provider,因此写在其中的 module 块不会被读取,也不会产生警告。provider 页面上的结构化输入校验完整说明了该规则。

**输出形式。**每个调用一行,依次给出节点和 provider,然后是块、其所在的文件和行,以及按原样写出的 source;跳出模块的 source 会说明这一点,而不是给出下载地址:

warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that module
warning: node "app" (provider "terraform"): module "shared" (main.tf, line 2) has the local source "../shared", which resolves outside the module this build placed, so Terraform reads whatever sits at that path when the configuration is initialised rather than files this build vendored

调用按引擎到达它们的顺序列出——先是模块自身的目录,然后按本地 source 首次到达各目录的顺序,在同一文件内则按块的书写顺序——因此相同的输入在每次运行时产生相同的序列。每次进行渲染的运行都会产生它们:aggrega build;aggrega pull,它会渲染一次 Release 以发现其构建要获取的内容;以及对工作区中持有其模块的 Recipe 运行的 aggrega validate,它会单独渲染该 Recipe。

**类别代码。**每条警告都带有稳定、可供机器匹配的类别代码 module-fetched-at-init,因此工具可以匹配类别,而无需解析消息文本。该代码随结构化诊断一起传递:助手的 build 工具在 advisories 下列出每项发现及其代码,语言服务器也会在每个条目上发布它。它命名的是一类发现,而不是一个已注册的条件,因此在本页顶部的表格中没有对应的行。

**编辑器中的可见性。**每当语言服务器渲染 Release 时——无论是被请求的构建或构建预览,还是使用 aggrega serve --build-on-inspect 进行的 IR 图检查,或者它所覆盖的、默认关闭的 serve.build_on_inspect 配置键——该警告都会以警告级别出现在编辑器诊断的 aggrega-build 层上。该条目指向的是节点而非编写键,因此标注在 Aggregate 的 kind: 键上。

它自成一类,且没有标志可以屏蔽它。--no-unsupported-field-warnings 屏蔽的是 unsupported-field 类别,并不涵盖这一类。

**构建成功,渲染出的字节保持不变。**该警告在渲染产物之外单独传递,因此无论它是否出现,所 vendor 的模块、编写的主体和根配置都逐字节相同。

**为什么是警告而不是中止。**调用另一个模块的模块是合法的输入:Terraform 会获取被调用的模块,配置也能正常工作。作者放弃的是构建对该模块的固定,这是一个需要报告的事实,而不是需要拒绝的错误;获取是否可接受由作者决定。

A plugin ran with no recorded digest to check it against(插件运行时没有可供校验的已记录摘要)

触发条件: 编译器即将运行一个插件,该插件的字节本应受已记录摘要的约束,而工作区没有为它记录任何摘要。插件照常运行;这条警告让你得知:没有任何东西将它运行的字节与任何人审查过的字节进行过比对。

aggrega pull 会将它获取的每个插件的摘要写入该 Release 的锁文件,之后的每次解析都会将找到的字节与该摘要比对。尚未执行过 pull 的工作区,或者锁文件早于配置后来挂接的某个插件的工作区,都没有该插件的摘要——因此比对无从进行,若没有这一行,它会静默通过。

流水线步骤、provider,或挂接在裁决角色上的插件,如果其 Plugin 实体编写在你的某个目录目录中,同样没有摘要,而且 pull 也不会为其提供摘要:pull 从不固定此类实体,构建每次都会重新读取其 .wasm——通常情况下从实体旁边读取——而不是依据 pull 记录的任何内容。挂接在转换角色上且编写在那里的插件是例外:它的字节会影响渲染输出,因此 pull 会记录为它找到的 .wasm 的摘要;一旦记录,构建就会依据该摘要检查该插件,也不会再为它发出这一行。

warning: plugin "governance/label-injector:1.0.0" resolved from cache with no recorded digest to check it against, so it runs unverified; run `aggrega pull --release <release>` to record it
warning: plugin "pipeline-step/patch" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded

这就是构建、拉取或验证在其他警告中显示的那一行。在此类运行之外解析插件的命令——安装、列出或运行工作区自己的命令行插件,或者 aggrega lint 解析它用于 lint 的插件——会在单独的一行上打印同一句话,不缩进。

该行会指明字节的来源——与 aggrega pull 和 aggrega plugin list 对它使用的词相同——并以适用于该来源的说明结尾。对于来自内容缓存的字节,修复方法是 pull 该 Release,这会记录摘要,使该插件之后的每次运行都经过校验。对于从目录目录中 Plugin 实体旁边读取的字节,pull 只为挂接在转换角色上的插件记录摘要,该行也会如此说明:对于编写在那里的其他任何插件,任何 pull 都改变不了这一点,要让它受已记录摘要约束,办法是发布它并引用已发布的实体。

对于每个命令,每个插件只显示一次,无论该命令解析该插件多少次。 一次渲染会为每个节点解析一次其 provider,而填充自身锁文件的构建可能会多次渲染该 Release;每次都重复这一行会将其淹没。编辑器服务在其运行期间只在自己的错误流上显示一次,而它回答的每个请求都会重新向编辑器报告——因此无论编辑器采用哪个回答,该回答都会告诉你那次运行在未经验证的情况下使用了哪些插件。

编辑器可见性。 该警告会与本次运行的其他建议一起进入编辑器诊断,严重级别为警告:对 Release 的验证会将其发布在该 Release 的 Aggregate 上,编辑器请求的构建或构建预览则会将其发布在 aggrega-build 层上。它指出的是一个插件,而不是你编写的某个键,因此会放在文件开头。由于每次运行都会报告其解析的内容,只要某次运行在未经验证的情况下解析该插件,该条目就会保留,并在第一次不再如此的运行时清除。它不改变任何裁决,也不会使任何解析失败,因此无论是否显示它,会话给出的回答都相同。

有两种解析不会发出任何警告,且都不是疏漏:

  • 编译器内置的插件。 aggrega pull 记录它获取的内容,而随二进制文件发布的字节无需获取——因此从不为其记录摘要,你也无法运行任何命令来改变这一点。二进制文件本身就是这些字节的身份。编译器自带的插件及其版本由 aggrega plugin list 列出,并写入锁文件的 toolchain 部分。
  • 本就不应适用摘要的解析。 aggrega validate --plugin ./some.wasm 指向你在命令行上指定的文件,aggrega lint 检查的正是它所校验的制品;在这两种情况下,插件是被检查的对象,而不是被信任的工具,因此不存在可用来约束它的记录。

为什么是警告而不是中止。 在尚无人准备过的工作区上读取文档是有价值的——在有人运行 aggrega pull 之前拒绝 validate 或 lint,会让这些报告命令恰恰在最有用的时候无法使用。aggrega build 在完全没有锁文件时不会生成制品,因此构建只会对锁文件未记录摘要的插件遇到这条警告——通常情况是从目录目录中其实体旁边读取的插件。

缺少锁文件时反而会拒绝的情形。 当编辑器向编译器服务请求某个 Release 的图而工作区完全没有锁文件时,服务会停止并要求提供锁文件,而不是绘制图。锁文件存在、只是没有为某个插件记录摘要,则属于上述情形:插件照常运行,你通过这条警告得知此事。读者随后会依据绘制出的图进行推理,而由未经校验的字节构建的图看起来与经过校验的图完全一样。参见 aggrega serve。

A published archive carries an entry Windows cannot use(发布的归档包含 Windows 无法使用的条目)

触发条件: aggrega push(或其 --dry-run)发布的归档中,某个条目包含 Windows 无法按原样容纳的部分:Windows 为设备保留的名称,例如 CON、PRN、AUX、NUL、COM1 或 LPT1,不论字母大小写、后跟何种扩展名;或以句点或空格结尾的部分。aux/x.yaml 的目录中含有这样的部分;report. 和 COM1.yaml 的文件名中含有这样的部分。在 Windows 上,aggrega 拒绝解包此类条目,因此 Windows 工作区完全无法使用该版本。该警告在所有平台上都会触发,因为发布内容面向任何拉取它的人,作者借此能在 Windows 用户发现之前得知这一问题。

读取内容: 归档将包含的名称:实体文档自身的文件名,然后是实体在其旁边指定的每个文件,即 Bundling 列出的文件。因此,一个名为 con.yaml 且导入了 schema 文件的文档,会因其自身名称而引发该警告。不指定任何文件的实体仅以其文档发布,使用方会将其放在由产品选择的名称下,而不是你编写时的名称,因此无论其文件叫什么,都不会收到警告。Plugin 不发布归档,同样不会收到警告。

输出形式: 每个条目一行,输出到标准错误,按名称组成的顺序排列(先是文档,然后是它携带的文件,按字典序),位于试运行或发布本身在标准输出上的说明之前:

warning: an entry this publication carries cannot be used on Windows (the entry "aux/x.yaml", its segment "aux"). Windows reserves device names such as CON, PRN, AUX, NUL, COM1 and LPT1, in any letter case and whatever extension follows, and does not hold a segment ending in a full stop or a space as written, so a workspace on Windows refuses to unpack the entry. This warning does not stop the publication; rename that segment to publish a version Windows can use

第一个带引号的值是归档中命名的条目。第二个是其各段(由斜杠分隔的部分)中第一个 Windows 无法容纳的段,也就是需要重命名的部分。该行以该条件的固定语句开头。它由发布引发,而不是由构建求值的规则引发,因此在本页顶部的表格中没有对应行;所有条件的表格将其列在 E0344 下。

它不拒绝任何操作。 推送或其试运行的继续或被拒绝,与没有该警告时完全相同,退出方式也相同。

其他可见之处: 助手的 publish-entity 工具以 windows_unusable_entries 返回相同的条目,aggrega serve 以 windowsUnusableEntries 在 aggrega/publishEntity 的响应中返回它们;没有此类条目时,这两个字段均不存在。参见 aggrega mcp 和 aggrega serve。对于请求报告的请求,服务还会在发布的其余说明中传递该警告行本身。

编辑器可见性: 不作为诊断显示:发布不是构建,因此这里的内容不会进入问题列表。通过服务发布的编辑器会读取响应中的 windowsUnusableEntries。

为什么是警告而不是中止: 这样的名称是合法的,Linux 和 macOS 会按其名称使用该文件,因此拒绝发布就等于基于对谁会拉取它的猜测而拒绝一个可用的实体。是否重命名由作者决定。