aggrega lint
aggrega lint 检查发布约定:命名、类别目录对齐、注解前缀、schema 编写规范以及版本号升级幅度。它有三种模式,由参数选择,在三个范围内应用同一套约定规范:整个目录(不带参数)、单个 Release 的依赖闭包(--release),以及单个实体文件(一个实体路径,可选 --pre-publish 发布关卡)。每个范围回答的是同一个问题——“这些内容是否遵循目录的发布规范?”——只是作用于目录的不同部分。
约定不同于正确性。aggrega lint 从不检查内容是否格式良好或能否编译——那是 aggrega validate 的职责,它以相同的三个范围检查 schema、支柱、引用解析、extends、输入类型能力和渲染。选择器语法无法读取的 socket 或槽选择器属于正确性错误,因此 lint 对它不作任何报告:validate 会拒绝它,无论是针对整个目录还是针对单个 Component 或 Feature——参见已声明的选择器。这两个命令相辅相成:validate 告诉你内容是否正确;lint 告诉你内容按目录的约定是否可以发布。
aggrega lint 需主动选用。编译器本身对目录规范不预设立场;这些规则位于一个由你选择运行的独立插件中。从不运行 aggrega lint 的工作区照样可以构建和发布。
实体路径可以作为位置参数给出,也可以用 --entity <path> 给出。--release 与实体参数互斥——它们选择不同的范围;同时传入两者会停止执行。
整个目录的约定(无参数)
不带参数的 aggrega lint 会对在所配置的目录(catalog)目录下找到的每个目录实体运行结构性的发布规范规则。检查结果仅供参考:它们以 warn 严重级别报告,绝不会仅因一条约定检查结果而停止。可以用它扫描整个目录,找出命名、类别目录和注解前缀方面的偏差。位于目录(catalog)目录中的 Aggregate、Manifest、Release 或 Workload 会被跳过而不检查:该检查会在其摘要之后的 not checked: 行中统计每种这样的类型,并引导你使用实体模式,实体模式可检查任意类型的文档。
catalog 目录下的 YAML 文件,如果其某一行以未缩进的 apiVersion: 开头,且其值以 aggrega.ai/ 开头(无论是否带引号),则为 Aggrega 文档。无法读取、YAML 无法解析,或者其 kind、metadata 或 spec 不符合实体信封形状的 Aggrega 文档——例如写成列表的 metadata——会在读取完各目录后以 E0175 停止运行,列出每个此类文件以及读取或解析器给出的原因;不会检查任何内容,也不会打印 conventions checked 行。能够加载但声明了任何 catalog 都不包含的 kind 的文档——例如拼错的 Componnent,或者根本没有 kind——会以 E0371 停止同一次运行,并与上述文件一并列出,附上它所声明的种类;Manifest、Release,以及 Recipe 从其自身目录导入的 Workload 都会被跳过。其他任何 YAML——Helm chart 的模板(它们在渲染之前无法解析)、chart 的值、工作流定义——都会被跳过。--release 在其 catalog 目录下遇到此类文档时也会以同样方式停止。
它读取哪些目录取决于工作区的形态:
-
配置中没有为 Release 单独指定目录(catalog)目录的工作区只检查一次,范围是它的搜索栈:先是
--catalog目录,然后是workspace.catalog_dirs,最后是工作区根目录下的catalog目录(如果存在)。 -
在
workspace.releases下列出 Releases 的工作区可能并排保存同一目录的多个变体,每个变体由各自的 Release 读取;若对所有目录只做一遍检查,就会同时读取所有变体——一个变体的实体会遮蔽另一个变体的实体。因此,会对工作区中的每个 Release 各检查一次,范围是该 Release 读取的目录,并且每一遍都先读取--catalog目录;配置中未列出的 Release 读取工作区的目录列表。每一遍都在一行标题下报告,该行列出其 Release 及所读取的目录,后面是这一遍的检查结果及其自身的汇总:Release release-compose.yaml reads catalog-composeconventions checked: 7 entities, 0 advisory finding(s)Release release-helm-synth.yaml reads catalog-helm-synthconventions checked: 8 entities, 0 advisory finding(s)读取完全相同目录的 Releases 共用一遍检查,该遍会列出其中每一个,因此其中的检查结果只报告一次。不读取任何目录的 Release(其条目写为
catalog_dirs: [])会被报告为没有可检查的内容,其他各遍照常运行。使用-o json时,文档还包含passes:每一遍的releases、catalogDirs、findings和summary,而顶层的findings和summary涵盖所有遍的合计。工作区中的 Releases 就是它的 Release 文档,即kind为Release的 YAML 文件,可位于工作区根目录下除隐藏目录以及node_modules、vendor和dist之外的任何位置。
如果每一遍都没有可读取的内容,这次运行会被拒绝,而不是报告为干净的目录:请将实体放在 catalog/ 下、传入 --catalog,或设置 workspace.catalog_dirs;在列出 Releases 的工作区中,也可以在 workspace.releases 下设置某个 Release 自己的 catalog_dirs。它绝不会隐式枚举当前工作目录。
目录(catalog)目录下指向工作区之外(或指向你在工作区外指定的目录之外)的链接不会被读取,运行会在此停止并指出该链接,而不是把一个有文档无法读取的目录报告为干净的目录;对相同目录进行的构建也会在同一链接处停止。工作区边界阐述了该规则及其补救方法。
跨 Release 的约定(--release)
aggrega lint --release <release-path> 对单个 Release 的解析闭包所触及的目录实体文件运行相同的结构性规则,而不是针对整个目录或单个实体。它通过构建所用的同一套机制计算闭包,然后对每个实体由作者拥有的目录文件进行 lint。位于缓存槽中、由 registry 固定版本的实体没有可供 lint 的本地文件,因此会被跳过——发布规则只适用于本地编写的文件。与整个目录模式一样,检查结果仅供参考,绝不会仅因一条约定检查结果而停止。
这也是唯一一个掌握完整 Release 的范围,因此读取单次运行的规则——即 The discipline rules 中描述的连接凭据规则——在此运行。此类规则在每次检查中运行一次,在逐实体规则之后,作用于三份文档:该 Release 部署的 Aggregate,按其作者编写的原样;该 Release,并合入其 extends 链,使子 Release 带有其继承的内容;以及对于 Aggregate 声明的每个 component,该 component 作为其实例的 Component,按目录解析的结果。其中不包含任何参数值,在每个范围中都是如此:Release 传入时不带其 parameters 块,包括从基础继承的值;Aggregate 传入时不带其默认值,也不带它传给每个所导入模块的值——参见 What a linter plugin is handed。其检查结果报告在 Release 文件之下。
这是 aggrega validate --release 在约定方面的对应命令,后者检查同一闭包的正确性。
此范围运行的 linter 受 Release 旁边的受信任插件身份记录约束,与构建对其的约束相同。在任何 linter 运行之前,--release 会将配置的 plugins.linter 挂载与插件信任记录进行比较:配置不再挂载的已记录插件——无论是 linter 还是 gate——会使该轮停止;从缓存读取、但其制品不是已记录制品的 linter 会被拒绝,而不会运行。从缓存读取的 linter 在加载时还受其已记录签名的约束:如果其条目记录了已验证的签名,则会再次检查该事实在缓存中指向的签名材料;若缺失或不一致,该轮以 E0144 停止;若签名是为与所读取 linter 不同的插件生成的——即从另一个条目复制的 signature——则以 E0332 停止,无论签名要求如何规定;如果工作区的信任配置要求签名,则未记录签名的条目——或该 linter 没有条目,包括记录已被删除的情况——会使该轮以 E0331 停止,条件与会使 aggrega pull 以未签名为由拒绝它的设置相同。这三种情况都会给出补救方法 aggrega pull --release <release>,它会在 registry 处验证 linter 的签名、记录该签名并缓存其指向的包,同时重写不再与其摘要匹配的缓存副本。由编译器二进制文件内副本提供的 linter 永远不受该要求约束。这些是该轮的失败,而不是约定检查结果,因此在检查结果不会停止的地方,它们会停止。整个目录范围和单实体范围不指定 Release,也不读取记录,因此它们从缓存读取的 linter 只对照其缓存的 manifest 进行检查。在这一切之前,--release 会以 aggrega build 打印的措辞,将针对该 Release 所依赖内容记录的每一项撤回列为一行 deprecation:——锁文件针对已固定引用记录的标记和信任记录针对 linter 或 gate 记录的标记都是如此——因此即使上述某项拒绝使该轮停止,该轮也会说明这一点。撤回不会改变任何检查结果,也不会改变退出码;存在但无法读取的信任记录会使该轮停止,而不会被当作未记录任何内容的记录放行。
实体规范:本地与发布关卡
实体路径模式以两种严重级别之一运行:
- 默认(本地)。 以
warn严重级别对本地实体内容运行规范规则。不访问注册表;跳过版本递增检查。在编写期间使用。 --pre-publish(发布关卡)。 从注册表获取该实体最新发布的非预发布版本,以halt严重级别运行相同的规则,并额外将变更归类为PATCH/MINOR/MAJOR;如果提议的metadata.version递增小于该变更所要求的幅度,则中止。在发布流程中、aggrega push之前使用。--pre-publish仅适用于单实体形式。
过度递增始终允许;递增不足则中止。实体的首次发布(注册表中没有先前版本)会跳过递增检查,并给出一条警告,说明未执行任何验证。
实体模式检查哪些类型
实体模式会对你指定的文档执行 lint,无论其类型如何,并把它交给每一条读取单个实体的规则。每条规则自行决定它描述哪些类型,收到它不描述的类型的规则不报告任何内容。因此,指定 Aggregate、Manifest、Release 或 Workload——整个目录的检查会跳过这些类型,并在其 not checked: 行中列出——同样会对它运行这些规则,而只有描述该类型的规则才可能报告:
| 规则 | 在实体模式下报告的类型 |
|---|---|
| 注解前缀 | 任意类型:无论文档是什么类型,它都会读取 metadata.annotations。 |
直接使用的 x-aggrega-* 扩展 | 任意类型:无论文档是什么类型,它都会读取 spec.schema。 |
| 名称形式 | Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、WorkloadLibrary 和 ArtifactLibrary。 |
| 类别与目录匹配 | Component。 |
| 密钥槽声明 sensitive | Component 和 Feature。 |
| 指标凭据注解与 provides 匹配 | Component。 |
| Provides 由 Component 声明 | Recipe。 |
| 动态引用、Id 覆盖 | SchemaLibrary。 |
| Plugin 默认限制 | Plugin。 |
版本号提升比较(--pre-publish) | Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、Aggregate 和 Plugin(不比较编译器内置的插件);对其他任何类型的更改都归类为 MAJOR。 |
| 连接凭据与目标键匹配 | 无:它读取整个 Release,因此仅在 --release 下运行。 |
Aggregate、Manifest、Release 和 Workload 的 schema 都不声明 metadata.annotations 或 spec.schema,因此这些类型中与其类型的 schema 相符的文档不会从那两条读取任意类型的规则得到任何结果;只有当文档仍然带有其中某个键时,这两条规则才会对它报告,而该键会被其类型的 schema 当作意外属性拒绝。指定 Aggregate 所增加的是 --pre-publish 下的版本号提升比较,它按照下文的评判准则所述,将其与已发布的版本进行比较。
版本升级评判标准
在 --pre-publish 模式下,变更会与上一个已发布版本进行比较并分类:
PATCH— 仅涉及文档或注释的变更。MINOR— 严格的增量变更(新的可选字段、新的条目)。MAJOR— 删除、类型收窄,或原先可选的字段变为必填。
比较按实体类型进行:Component、Feature 和 SchemaLibrary 在比较时会考虑其承载 schema 的字段;MappingLibrary 在条目键层面进行比较(条目内容是不透明的,因此内容发生变化时会保守地视为 MAJOR);Recipe 和 FeatureRecipe 按其承载关键作用的字段进行比较。Aggregate 按其参数声明、组件和子系统进行比较;参数的默认值与其他参数值一样不会进入比较(参见链接器插件会收到什么),因此仅限于默认值的变更(添加、修改或删除默认值)不属于比较范围,对参数槽词汇表之外的键的变更也不属于比较范围。版本升级不足时会中止,并给出指明所需升级级别的诊断信息。
规范规则
大多数规则在 .aggrega-config.yaml 的 lint.publishing_discipline 下有一个按工作区生效的设置,并有对应的 CLI 覆盖选项,每个覆盖选项都带有一个 --no- 对应形式。优先级为 --no-<flag> 高于 --<flag>,后者又高于工作区配置值,在每个作用域都是如此:整个目录、一个 Release 和单个实体。每条规则默认开启,且每个默认值要么基于平台机制,要么基于有文档记载的目录约定;这些设置是供有理由放宽某条规则的工作区选择退出的。
没有设置的规则会在下文各自的条目中说明,原因在每种情况下都相同:它们报告关于实体的一个事实,并把决定留给作者,因此没有需要放宽的判断。上文描述的版本升级准则同样没有设置——它将拟议内容与已发布版本进行比较,并报告该变更所要求的升级,这是变更本身的属性,而不是工作区偏好。
- 注解前缀 —— 保留命名空间(
aggrega.ai/,以及在 Feature 之外的feature.aggrega.ai/)归平台所有,在其他键上会被拒绝。默认开启;使用allow_aggrega_ai_prefix选择退出。 - 名称形式 —— 每种实体类型都有名称形式约定(云原生类型为段数;库类型为 PascalCase)。默认开启;使用
allow_nonstandard_names选择退出。 - 动态引用 —— SchemaLibrary 条目不得使用
$dynamicAnchor/$dynamicRef(平台在编译时进行的$ref展开无法解析它们)。默认开启;使用allow_dynamic_refs选择退出。 - Id 覆盖 —— SchemaLibrary 条目不得声明自己的
$id(平台会派生规范的$id)。默认开启;使用allow_id_overrides选择退出。 - 类别与目录匹配 —— Component 的
component.aggrega.ai/category标签必须与core/下的第一个目录段匹配,取值来自封闭的类别集合(ai-agent、ai-model、ai-tool、ai-pipeline、datastore、gateway、mesh、network、messaging、storage、compute、observability、security、bigdata、devtool)。对core/路径下的实体默认开启;使用allow_category_mismatches选择退出。 - 直接使用
x-aggrega-*扩展 —— 不建议在 Component 或 Feature 的 schema 中直接编写x-aggrega-*键,而应使用一等的编写途径。默认开启;使用allow_direct_x_aggrega_extensions选择退出。 - provides 由 Component 声明 —— Recipe 的
spec.provides每个条目发布一个键,而该 Recipe 所实现的 Component 在其spec.schema的provides支柱中声明该类型公开哪些键。injectfrom:引用所校验的正是这一声明,因此 Recipe 发布了但 Component 未声明的键虽会被产出,却会在消费方连接它时被拒绝。超出已声明契约的发布在构建时是被接受的,因此该发现是建议性的,而非拒绝。对 Recipes 默认开启;使用allow_undeclared_recipe_provides选择退出。 - Plugin 默认限制 —— Plugin 的
spec.runtime包含maxMemoryPages和timeoutMs,即宿主在加载和运行插件时应用的两个上限。两者都未固定的 Plugin 会在平台默认值下运行,这是安全的结果而非错误,因此该规则报告默认值正在生效,并且可以固定显式上限。对 Plugin 实体默认开启;它没有设置。 - secret 槽位声明 sensitive —— 附件槽位可以通过其标签选择器,将填充它的 Feature 的类型固定为
secret,并可另外声明sensitive: true,以记录填充它的任何内容都会处理机密材料。选择器说明哪些填充是可接受的;标记说明处理方式。固定了类型却未声明标记的槽位,会让这种处理方式只能从选择器重新推导,而不能直接读取。该规则读取实体声明的每个槽位:其自身位于spec.featuresSchema下的附件块中的槽位,以及在 Component 上,每个依赖插座在spec.usesSchema.<socket>.featuresSchema下为经由它连接的连接所声明的槽位——关于插座槽位的发现会同时指明该插座和该槽位。对 Components 和 Features 默认开启;它没有设置。 - 连接凭据与目标密钥匹配(
connection-credential-matches-target-key)——校验密钥的服务器把它所验证的密钥保存在其自身 Component 的一个插槽中,而调用方在其访问该服务器所经由的连接上出示密钥。两端都看不到对方的附件,因此两者持有同一个密钥,仅仅是因为它们的作者在两端都写了它——通常是让两个附件读取同一个参数——而构建从不比较它们。本规则会比较,并且它是唯一读取整个 Release 的规则,因此它只在--release下运行,不在其他任何范围运行。它按标准目录为两端赋予的名称找到两端:目标的密钥是其 Component 在spec.featuresSchema中声明的插槽api_key,调用方的密钥是连接上的插槽credential,写在 Aggregate 中的uses.<socket>.<alias>.features.credential处,或写在 Release 所连接的连接上。对于目标声明了api_key且未标记为托管的每个连接,它会报告:连接携带凭据而目标的密钥插槽未填充;密钥插槽已填充而连接上没有凭据;以及两端对其密钥的命名不同。它比较的是每一端的定位符——附件所写的origin,在 Aggregate 中写在values里,在 Release 中写在infra里——按作者所写的原样比较,因此读取同一参数的两端比较结果相等,两个字面量则按其文本比较;不做任何解析,发现项会指明 component、连接、目标和两个插槽,但从不引用任何一个定位符,因为那里写的文本可能就是密钥本身。未声明api_key插槽的目标不会产生任何发现项,而不是调用方密钥的插槽,例如模型服务器的镜像仓库拉取令牌,永远不会被读取。Component 标记为component.aggrega.ai/hosting: managed的目标也不受评判,无论其api_key插槽持有什么:这样的 Component 代表由其供应商运行的服务,因此 Release 运行的任何内容都不会在它上面校验密钥;如果它声明了api_key——例如以供应商产品所用的名称表示的托管模型 API 的密钥——该插槽持有的是 Release 向该供应商出示的密钥,而绝不是其调用方出示的密钥。标记为self-hosted、external或mixed,或没有托管标签的目标会受到评判。套接字scrape_target上的连接——标准目录为指标抓取器访问其目标所经由的套接字所起的名称——是一次抓取,而抓取的凭据是否应为目标的调用方密钥取决于目标的产品:有些产品无需凭据即可提供指标,有些将指标置于每个调用方都要出示的密钥之后,还有些使用自己的令牌。因此,对于抓取,规则会读取目标的 Component 在其注解observability.aggrega.ai/metrics-credential中声明的内容:在none下,该抓取完全不受评判;在separate-token下,其凭据从不与目标的api_key比较,因此三种发现项都不会对其报告;在target-key下,它与其他任何连接一样受到评判。规则只读取这三个值,因此对没有该注解或带有任何其他值的目标的抓取,与其他任何连接一样受到评判——而其他套接字上的每个连接,包括模型、工具或数据存储连接,无论目标的注解如何,都同样受到评判。它读取写在目标和连接上的附件:从子系统或边界到达目标的api_key附件会使该连接不受评判;由注解添加的附件不在其中,因此仅以这种方式填充的密钥插槽会被视为未填充;附件未写定位符的一端只比较是否已填充;由导入模块提供的 component 不会被读取。由于插槽名称、托管标签、抓取套接字的名称和指标注解都是没有任何 schema 关键字标记的目录约定,以不同方式命名插槽的目录不会产生任何发现项,以不同方式命名的抓取套接字与其他任何套接字一样受到评判,而在名为api_key的插槽中持有供应商密钥却没有托管标签的 Component 会被视为校验该密钥的目标,因为插槽名称、标签和注解就是规则从目标的 Component 中读取的全部内容。默认开启;可通过allow_connection_credential_mismatches选择退出。 - 指标凭据注解与 provides 匹配(
metrics-credential-annotation-matches-provides)——一个 Component 可以声明关于其指标的两项事实。其注解observability.aggrega.ai/metrics-credential声明产品指标的认证方式:none,指标无需凭据即可提供;target-key,指标使用该 Component 要求每个调用方出示的密钥,即其api_key插槽所持有的密钥;separate-token,指标使用自己的令牌。在其spec.schema的provides支柱中声明的 provides 键metrics_credential_required,是其每个 Recipes 发布的内容,用于说明某个实例的指标是否需要凭据——这可能取决于实例的配置方式,因为置于调用方密钥之后的指标只有在附加了密钥时才需要凭据,所以注解无法替代它。两者声明的是关于产品的同一项事实,因此本规则要求两者一致:注解为none却声明了该键的 Component,以及注解为target-key或separate-token却未声明该键的 Component,都会被报告,发现项会指明该 Component、注解的值以及多余或缺失的键。没有该注解或带有任何其他值的 Component 不会产生任何发现项。它按原样读取 Component,因此扩展另一个 Component 的 Component——其 schema 即其基础的 schema——不会产生任何发现项,其基础会在声明之处被读取;而以引用、组合或以文本形式写的转义主体写成的provides支柱无法被它枚举,因此该 Component 同样不会产生任何发现项。对 Components 默认开启;它没有设置项。
制品不可变性不属于这些规则,也没有设置项。 已发布的 name:version 是最终的:aggrega push 会将该标签下已发布的摘要与即将推送的内容所产生的摘要进行比较,并拒绝用不同的内容覆盖它。重新推送逐字节相同的内容不会上传任何内容,只会附加该发布仍缺少的部分——其发布日期,以及在推送进行签名时的签名。没有任何标志或工作区配置设置可以放宽这一点,因为镜像仓库没有提供可供操作者选择启用的覆盖途径。更改后的内容以新版本发布;--pre-publish 用于对照上一个版本验证该版本升级。
按规则的覆盖标志是针对单次调用的开关,并且有意没有环境变量——它们已在 .aggrega-config.yaml 的 lint.publishing_discipline 下由配置支持。通用的 AGGREGA_* 优先级模型见 environment-variables.md。
构建时与发布时
x-aggrega-* 劝阻规则也会在 aggrega build 期间运行,此时以警告的形式呈现;aggrega lint --pre-publish 会将同一发现提升为错误。本地构建只给出建议;发布关卡则强制执行它。
在编辑器中编写时
编辑器会就一个目录实体提出两个不同的问题,也正是本页开头提出的两个问题。该实体是否正确——能否解析,各支柱能否解析出结果,能否渲染?这由 aggrega validate 回答,编辑器会话始终会回答这个问题。该实体是否可发布——名称是否遵循约定,文件是否位于其类别所期望的目录中,注解前缀是否正确?这由本页的这些规则回答,编辑器会话只有在你要求时才会回答。
除非你开启,否则它处于关闭状态。 在你希望获得其实体建议的工作区的 .aggrega-config.yaml 中,通过 serve.lint_on_validate 开启它:
serve: lint_on_validate: true它没有对应的命令行标志,这是有意为之:这个问题关乎某个特定工作区自身的内容,而你是编写该工作区的人,而不是启动语言服务器的人——启动语言服务器的是你的编辑器。
开启后,你验证的每个实体除了正确性方面的发现之外,还会附带这些发现,每条都会注明产生它的规则。由此带来三点,正是它们让该功能在输入时可用:
- 这些发现仅作为建议。 违反约定的实体仍然能通过验证,其 Release 仍然能解析和渲染。开启该设置只是增加一层建议;它绝不会让你的编辑器拒绝工作。
- 你可以区分这两者。 每个发布的问题都会注明引发它的层,因此同一文件上的命名问题和解析失败会显示为两件不同的事,而不是同一个问题被报告两次。
- 检查的是你输入的内容。 这些规则读取的是缓冲区,而不是磁盘上的文件,因此你修正的名称在保存之前就不再被报告。
在这一层上只运行本地内容模式:不查询任何注册表,不获取任何内容,也不写入任何内容。--pre-publish 比较只有在你请求时才会进行——你的编辑器会为此发送一个请求,就像你在终端中输入 --pre-publish 一样——而绝不会通过修改上述设置来触发。每次触碰文档都会运行的检查恰恰是绝不能访问注册表的地方,因此该模式始终是你主动调用的,而不是随之自动运行的。
无论该设置如何,直接请求检查都有效,并适用于上述全部三种范围。因此,一个从未开启逐次编辑层的工作区,仍然可以让其编辑器扫描整个目录、某个 Release 的闭包或单个实体——并得到与本命令输出相同的发现。该设置只决定检查是否也会在你未明确请求的地方运行。
协议细节分布在两个页面中:该请求的含义以及何时发送它,参见 aggrega serve 参考;其参数以及应答的逐字段结构,参见线路结构参考。
选择 linter
这些规则以一个标准的发布 linter Wasm 插件的形式提供。由于规则位于插件中而不是编译器中,企业可以让 aggrega lint 指向另一个插件,以执行自己的目录规范,而无需更改编译器。
一个工作区可以在 plugins.linter 下挂载多个 linter,每个挂载都会运行:按挂载的书写顺序,各自从自己的入口函数运行,所有发现结果一并报告。正因如此,目录可以保留标准规则,并在其旁边添加自己的规则,而不必二选一。--plugin 是例外——它从文件系统路径运行恰好一个构件,以取代已配置的挂载,这正是它在开发规则时有用的原因。
挂接项用 uri: 指明其插件,function: 指明该插件上的一个入口函数。指明了 function: 却没有 uri: 的条目所指的是不属于任何插件的函数,因此配置在读取时即被拒绝,归入 E0224,并指出该文件以及该条目在其列表中的位置——请添加导出该函数的插件的 uri。两者都未指明的条目不挂接任何内容,会被跳过;若它是唯一的条目,标准 linter 会以其自身的默认入口函数运行,与完全没有 plugins.linter 时一样。
linter 插件收到的内容
任何参数值都不会传给 linter 插件,无论处于哪个作用域。参数的值本身可能就是凭据——secret 挂载的 origin 可以是一个读取 Release 所满足的参数的模板,此时该 secret 就是这个参数的值——而工作区挂载的插件可能并非由它自己编写,因此每个文档在交出时都会扣留其参数值:
- Aggregate 保留每个参数声明,但只保留声明所用的键——即参数槽词汇:其类型、描述和约束——嵌套在其
properties、items和valuesType下的每个声明也同样处理。声明的default在每一层都会被扣留,方式是删除该键而不是将其置空,因此插件无法判断某个声明是否给出了默认值。该词汇之外的键会连同其内容一起在每一层被扣留:构建不赋予这样的键任何含义,而拼错键名的草稿可能在其下携带 secret。parameters下不是声明的条目会被整体扣留。 - Aggregate 的
aggregates下列出的每个模块都会失去其parameters块,该块保存传给该模块的值。 - Release 会失去其
parameters块,无论它是内联写出这些值,还是通过$import导入它们。 - 任何其他文档如果在
spec下带有parameters块,该块会被整体删除;没有其他类型会声明这样的块。
这适用于命令行上指定的实体、--pre-publish 用来与之比较的已发布版本、整个目录和 --release 检查所遍历的每个实体,以及读取整个 Release 的规则所收到的文档。读取参数的模板不是值,会保留其文本,因此规则仍能看到编写的值读取的是哪个参数。
示例
扫描整个目录,检查约定偏移:
aggrega lint --catalog ./catalog在编写时于本地检查一个实体:
aggrega lint core/datastore/postgres/component.yaml在发布新版本之前运行发布关卡:
aggrega lint core/datastore/postgres/component.yaml --pre-publish在单次运行中放宽一条规则:
aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names另请参阅
- ./aggrega-validate.md — 在相同三个范围内对应的正确性检查。
- ./aggrega-build.md — 在编译过程中进行验证;以
warn严重级别报告x-aggrega-*建议。 - ./aggrega-push.md — 将实体发布到注册表;
aggrega lint --pre-publish是其之前的关卡。 - ./aggrega-pull.md — 解析并锁定依赖。
- ./aggrega-serve.md — 在编辑器中报告这些发现的语言服务器,以及开启逐次编辑检查层的设置。
- ../errors/warnings.md — 非致命警告,包括本地模式的 lint 发现。
概要
aggrega lint [entity-path] [flags]说明
aggrega lint checks publishing CONVENTIONS — naming, category-directoryalignment, annotation prefixes, and the rest of the publishing-linterdiscipline. It does not check correctness (schema, pillars, resolution,render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity aggrega lint --release <path> conventions across a Release's dependency closure aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rulesover every catalog entity found under the catalog directories. Where theworkspace configuration gives its Releases catalog directories of their ownunder workspace.releases, it runs them 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 it runs them over the entities thatRelease's closure reaches, and also runs the rules that read a wholeRelease: once, over the Aggregate it deploys, the Release and theComponents the Aggregate's components are instances of, with everyparameter value removed. In both, findings are advisory (warn severity)and never halt.
With an entity path, lint runs the publishing-linter rule set againstthat one entity. In default mode the rules run at warn severity overlocal content without consulting any registry. With --pre-publish theprevious registry version is fetched and the schema-evolutionclassification is compared against the proposed version bump; mismatcheshalt. --pre-publish applies to the single-entity shape only. Per-workspacepolicy flags from .aggrega-config.yaml's lint.publishing_discipline blockcan be overridden per invocation via the --allow-*/--no-allow-* flag pairs,in all three shapes.
All three shapes accept -o json, which replaces the human report on standardoutput with one structured document: every finding with its severity, the rulethat produced it, its short code (the code printed at the head of its row inthe human report, which aggrega explain expands), its message, and the entityfile it concerns, plus counts by severity. A finding from a rule Aggrega doesnot declare, one a linter of your own adds, carries no short code, as its rowprints none. A finding carries a line and column only when the rule thatproduced it located the issue that precisely; otherwise the file alone locatesit. The message is the rule's own text, carried through unchanged, so thestructured and human renderings never word a finding differently. The exitstatus is the same under either format.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--allow-aggrega-ai-prefix | false | 强制 allow_aggrega_ai_prefix=true |
--allow-category-mismatches | false | 强制 allow_category_mismatches=true |
--allow-connection-credential-mismatches | false | 强制 allow_connection_credential_mismatches=true |
--allow-direct-x-aggrega-extensions | false | 强制 allow_direct_x_aggrega_extensions=true |
--allow-dynamic-refs | false | 在本次调用中强制 allow_dynamic_refs=true |
--allow-id-overrides | false | 在本次调用中强制 allow_id_overrides=true |
--allow-nonstandard-names | false | 强制 allow_nonstandard_names=true |
--allow-undeclared-recipe-provides | false | 强制 allow_undeclared_recipe_provides=true |
--baseline | — | 将发布前演进检查与这个指定的已发布版本进行比较,而不是与自动选择的、低于待发布版本的最高版本比较;必须是注册表中存在的严格 SemVer 标签(需要 —pre-publish) |
--catalog | [] | 目录目录;可重复。每个 —catalog <dir> 都会添加到目录搜索栈的最前面(首个匹配生效):即工作区的 catalog_dirs,或者,对于工作区配置在 workspace.releases 下为其单独指定了目录的 Release,则为该 Release 的目录;若工作区根目录下存在名为 catalog 的目录,栈以该目录结尾。显式写为空的 catalog_dirs 列表表示完全不读取本地目录。由整个目录和 —release 约定检查使用。 |
--entity | — | 要 lint 的实体 YAML 路径(也可作为位置参数传入) |
--no-allow-aggrega-ai-prefix | false | 强制 allow_aggrega_ai_prefix=false |
--no-allow-category-mismatches | false | 强制 allow_category_mismatches=false |
--no-allow-connection-credential-mismatches | false | 强制 allow_connection_credential_mismatches=false |
--no-allow-direct-x-aggrega-extensions | false | 强制 allow_direct_x_aggrega_extensions=false |
--no-allow-dynamic-refs | false | 在本次调用中强制 allow_dynamic_refs=false |
--no-allow-id-overrides | false | 在本次调用中强制 allow_id_overrides=false |
--no-allow-nonstandard-names | false | 强制 allow_nonstandard_names=false |
--no-allow-undeclared-recipe-provides | false | 强制 allow_undeclared_recipe_provides=false |
--output, -o | text | 输出格式:text|json。 |
--plugin | — | 发布 linter .wasm 制品的文件系统路径(运行此制品,而不是工作区 plugins.linter 中挂载的插件) |
--pre-publish | false | 获取注册表中的上一个版本,并根据 schema 演进分类验证拟定的版本升级 |
--release | — | Release YAML 的路径,用于在其解析后的依赖闭包上检查约定(与实体参数互斥)。相对路径相对于运行命令所在的目录解析,而不是相对于工作区根目录。若该目录不在任何工作区中且未指定根目录,则绝对路径会从该 Release 自身所在的文件夹查找工作区 |