component-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Validator

组件验证器

Audit a single Datex Studio component file against its type-specific authoring rules — the final read-only gate after a creator skill has finished writing or modifying a component, and before the change is upserted to the branch. This skill is a generic dispatcher: it reads the component file, picks the matching creator skill's reference document by file suffix, and runs the checklist from that document. It returns a structured punch-list (Blockers / Warnings / Nits) — never a rewrite.

See also:
grid-validator
— grid files (
*-grid.json
) carry several gotchas the generic dispatcher does not catch (envelope-vs-body shape, text-display coercion, five-location invariant). For grids, prefer
grid-validator
and treat this skill as a fall-back if
grid-validator
is unavailable.
See also:
component-wiring-check
— cross-component reference contracts (one component pointing at another). This validator only audits a single file in isolation; it flags obvious wiring drift it can see in that one file (e.g. a
configParameters
block that does not mirror the file's own
inParams
) but does not chase external references.
CAC note: a Custom Angular Component (
configurationTypeId: 36
, a
dxs ng
working folder —
manifest.json
+
app.<ref>.component.ts
with
//#region __COMPONENT_TYPES__
/
__COMPONENT_BODY__
) is not a single-file JSON body, so this skill's suffix dispatch doesn't apply. Audit it per
custom-angular-component-creator
's own Pre-Flight Checklist instead.

针对特定类型的创作规则审核单个Datex Studio组件文件——是creator skill完成组件编写或修改后、变更被更新到分支前的最终只读关卡。该skill是一个通用调度器：它读取组件文件，根据文件后缀选择匹配的creator skill参考文档，并执行该文档中的检查清单。它返回结构化的问题清单（Blockers / Warnings / Nits）——绝不进行重写。

另请参阅：
grid-validator
—— grid文件（
*-grid.json
）存在一些通用调度器无法检测到的特殊问题（信封格式与正文格式差异、文本显示强制转换、五位置不变性）。针对grid文件，优先使用
grid-validator
，仅在
grid-validator
不可用时将本skill作为备选。
另请参阅：
component-wiring-check
—— 跨组件引用约定（一个组件指向另一个组件）。本验证器仅独立审核单个文件；它会标记在该文件中可见的明显连接偏差（例如
configParameters
块与文件自身的
inParams
不匹配），但不会追踪外部引用。
CAC说明： 自定义Angular组件（
configurationTypeId: 36
，
dxs ng
工作目录——包含
manifest.json
+ 带有
//#region __COMPONENT_TYPES__
/
__COMPONENT_BODY__
的
app.<ref>.component.ts
）并非单文件JSON内容，因此本skill的后缀调度机制不适用。请按照
custom-angular-component-creator
自身的预检查清单进行审核。

References

参考资料

../datex-studio-conventions/file-format.md —
```
configurationTypeId
```
table, single-line minified JSON rule, TypeScript-expression encoding
../datex-studio-conventions/naming-conventions.md — Suffix table,
```
referenceName
```
↔ file-stem rule, snake_case vs camelCase guidance
../datex-studio-conventions/defaults.md — Default
```
accessModifier
```
,
```
description
```
length cap, default package rules
Creator-skill reference documents (the rulebook this validator dispatches into; see suffix table in the Sub-agent block below)

../datex-studio-conventions/file-format.md ——
```
configurationTypeId
```
表格、单行压缩JSON规则、TypeScript表达式编码规范
../datex-studio-conventions/naming-conventions.md —— 后缀表格、
```
referenceName
```
↔ 文件主干规则、snake_case与camelCase使用指南
../datex-studio-conventions/defaults.md —— 默认
```
accessModifier
```
、
```
description
```
长度限制、默认包规则
Creator skill参考文档（本验证器调度使用的规则手册；见下方子代理块中的后缀表格）

Dependencies

依赖项

Creator skills (

action-creator

function-creator

grid-creator

hub-creator

form-creator

editor-creator

selector-creator

storage-creator

type-definition-creator

backend-test-creator

datasource-creator

) — each one's

references/<type>.md

document is the rulebook this validator dispatches into by file suffix. Update them and this validator picks up the new rules automatically.

custom-angular-component-creator
skill — CAC (
```
configurationTypeId: 36
```
) working folders don't dispatch by suffix (see the CAC row in the Sub-agent table below); this validator instead points at that skill's own Pre-Flight Checklist as the rulebook.
datex-studio-conventions
skill — generic cross-cutting rules (file format, naming, defaults) that apply to every component regardless of suffix.
datex-studio-shared
/ datex-studio-runtime
skills — branch-setup primitives and platform-runtime globals referenced by the per-type rule docs.
tailoring-overlay
skill — overlay-specific shadow-marker rules invoked when the file is a tailored overlay variant rather than a base component.
component-wiring-check
skill — cross-component audit invoked when the punch-list surfaces wiring drift the parent wants to chase further.

Creator skills（
```
action-creator
```
、
```
function-creator
```
、
```
grid-creator
```
、
```
hub-creator
```
、
```
form-creator
```
、
```
editor-creator
```
、
```
selector-creator
```
、
```
storage-creator
```
、
```
type-definition-creator
```
、
```
backend-test-creator
```
、
```
datasource-creator
```
）—— 每个skill的
```
references/<type>.md
```
文档是本验证器根据文件后缀调度使用的规则手册。更新这些文档后，本验证器会自动应用新规则。
custom-angular-component-creator
skill —— CAC（
```
configurationTypeId: 36
```
）工作目录不支持后缀调度（见下方子代理表格中的CAC行）；本验证器会指向该skill自身的预检查清单作为规则手册。
datex-studio-conventions
skill —— 适用于所有组件的通用跨领域规则（文件格式、命名、默认值），与后缀无关。
datex-studio-shared
/ datex-studio-runtime
skills —— 分支设置基础组件和平台运行时全局变量，被特定类型规则文档引用。
tailoring-overlay
skill —— 当文件为定制覆盖变体而非基础组件时，会调用覆盖特定的阴影标记规则。
component-wiring-check
skill —— 当问题清单显示出需要进一步追踪的连接偏差时，会调用跨组件审核。

Workflow

工作流程

This skill is typically invoked by a creator skill at the end of its authoring loop, or by the user directly with "audit this file before merge". The invocation pattern is a Task-tool sub-agent dispatch — give the prompt template in the

## Sub-agent

section below to the sub-agent along with the target file path.

本skill通常由creator skill在创作循环结束时调用，或由用户直接通过“合并前审核此文件”调用。调用模式为任务工具子代理调度——将下方

## 子代理

部分的提示模板与目标文件路径一起传递给子代理。

Invocation (orchestrator side)

调用（编排器端）

Identify the target body — the component the parent has just authored or modified. The branch is the source of truth, so the target is one of: (a) the staged scratch
```
body.json
```
the creator skill is about to
```
dxs configuration upsert
```
(audit it pre-push), or (b) a fresh fetch from the branch —
```
dxs source explore config <referenceName> --branch <id>
```
, or
```
dxs configuration get <type> <id> -b <id> -O envelope.json && jq .json envelope.json > body.json
```
. Never audit a persistent local
```
src/
```
copy as if it were authoritative. Pass the sub-agent the path to that single scratch/fetched JSON file.
Dispatch the sub-agent — use the Task tool with the prompt template from the
```
## Sub-agent
```
section. The sub-agent has
```
Read
```
,
```
Grep
```
,
```
Glob
```
access; it does not edit.
Apply the punch-list — the sub-agent returns a markdown punch-list grouped by severity. Treat each finding as follows:
- Blockers — must be fixed before upserting. Route the fix back to the matching creator skill.
- Warnings — review and decide. May be deliberate; the sub-agent never assumes intent.
- Nits — optional cleanup. Defer unless the parent is already touching that area.
Re-validate after fixes — if Blockers were fixed, run the validator again. The validator is cheap (one Read + one Grep through the rule doc) and should be the last step before the push.

确定目标文件内容 —— 父级刚创作或修改的组件。分支是可信来源，因此目标文件为以下之一：(a) creator skill即将执行
```
dxs configuration upsert
```
的暂存临时
```
body.json
```
（推送前审核），或(b) 从分支新获取的文件——
```
dxs source explore config <referenceName> --branch <id>
```
，或
```
dxs configuration get <type> <id> -b <id> -O envelope.json && jq .json envelope.json > body.json
```
。切勿将本地持久化的
```
src/
```
副本作为可信来源进行审核。将该临时/获取的单个JSON文件的路径传递给子代理。
调度子代理 —— 使用任务工具并传入
```
## 子代理
```
部分的提示模板。子代理拥有
```
Read
```
、
```
Grep
```
、
```
Glob
```
权限；不具备编辑权限。
应用问题清单 —— 子代理返回按严重程度分组的Markdown问题清单。按以下方式处理每个发现：
- Blockers —— 必须在更新前修复。将修复任务路由到匹配的creator skill。
- Warnings —— 需审核并决策。可能是故意设置的；子代理不会假设意图。
- Nits —— 可选的清理工作。除非父级已在修改该区域，否则可推迟处理。
修复后重新验证 —— 若Blockers已修复，再次运行验证器。验证器成本低（仅需一次Read + 一次对规则文档的Grep），应作为推送前的最后一步。

Scope discipline (validator's contract)

范围约束（验证器约定）

The validator reads; it does not edit. The parent owns the fix.
The validator returns a punch-list; it does not return a rewrite.
The validator audits one file; it does not chase cross-component references (that is
```
component-wiring-check
```
's territory).
The validator does not load raw OData schema documents. If the file is a datasource that needs entity / property validation against the live schema, the validator recommends the parent invoke
```
schema-explorer
```
separately.
The validator does not speculate about intent. If a rule violation could be deliberate, it is flagged as a Warning with a note, not as a Blocker.

验证器仅读取；不进行编辑。修复工作由父级负责。
验证器返回问题清单；不返回重写后的内容。
验证器仅审核单个文件；不追踪跨组件引用（这是
```
component-wiring-check
```
的职责范围）。
验证器不加载原始OData模式文档。若文件为需要针对实时模式验证实体/属性的datasource，验证器会建议父级单独调用
```
schema-explorer
```
。
验证器不会推测意图。若规则违规可能是故意的，会标记为Warning并附带说明，而非Blocker。

Sub-agent

子代理

The prompt template below is what the orchestrator passes to the Task-tool sub-agent dispatch. The sub-agent is read-only (

Read

Grep

Glob

You validate a single Datex Studio component file against its type's authoring rules. You do not edit files. You return a punch list.

以下提示模板是编排器传递给任务工具子代理调度的内容。子代理为只读模式（

Read

、

Grep

、

Glob

）。

你需根据组件类型的创作规则验证单个Datex Studio组件文件。你不得编辑文件。你需返回问题清单。

Workflow

工作流程

Identify the component type from the file's suffix and load the matching rule document. The creator skill's

references/<type>.md

is the primary source; the cross-cutting conventions docs are always also in scope.

Suffix	Primary rule source (creator skill)
`*-footprintFlow.json` (action)	`../action-creator/references/actions.md`
`*-flow.json` (function)	`../function-creator/references/functions.md`
`*-grid.json`	Use `grid-validator` instead — it carries grid-specific gotchas this generic dispatcher does not. Fall back to `../grid-creator/references/grids.md` only if `grid-validator` is unavailable.
`*-form.json`	`../form-creator/references/forms.md`
`*-editor.json`	`../editor-creator/references/editors.md`
`*-hub.json`	`../hub-creator/references/hubs.md`
`*-storage.json`	`../storage-creator/references/storage.md`
`*-selector.json`	`../selector-creator/references/selectors.md`
`*-customType.json`	`../type-definition-creator/references/type-definitions.md`
`*-backendTest.json`	`../backend-test-creator/references/backend-tests.md`
`*-datasource.json`	`../datasource-creator/references/odata-datasources.md` (and `flow-datasources.md` if the body shape is flow-backed)
`*-footprintDatasource.json`	`../datasource-creator/references/odata-datasources.md` , `../datasource-creator/references/flow-datasources.md`
CAC working folder ( `manifest.json` + `app.<ref>.component.ts` with `//#region __COMPONENT_TYPES__` / `__COMPONENT_BODY__` ), `configurationTypeId: 36`	This file-suffix dispatch does not apply — a CAC is not a single JSON body. Audit per `../custom-angular-component-creator/SKILL.md` 's Pre-Flight Checklist and `../custom-angular-component-creator/references/custom-angular-components.md` instead of a suffix-matched rule doc.

If the suffix does not match anything in the table, reply

Cannot validate: unknown component suffix '<suffix>'. Supported: <list>.

and stop. If the file is recognized as a tailored overlay, also load

../tailoring-overlay/

rules.

Read the target body in full. Single file, one
```
Read
```
. This is the scratch JSON the parent staged for upsert (or just fetched from the branch with
```
jq .json
```
) — a throwaway temp file, not a persistent source-of-truth copy. The minified JSON envelope is the surface you will audit against the checklist.
Read the matching rule document's Pre-Flight Checklist section. That is your rulebook. Do not re-derive rules from memory — apply what is documented.
Walk the checklist item-by-item. For each issue, record:
- Severity —
```
blocker
```
  (silent runtime failure, import error, clear rule violation),
```
warning
```
  (drift or inconsistency that may or may not bite),
```
nit
```
  (style / naming / optional cleanup).
- Rule — which checklist item it maps to.
- Location —
```
<filename>:<line>
```
  or JSON path (e.g.
```
inParams[0].objectTypeDef
```
  ).
- Evidence — short quote or description.
Always probe the universal cross-cutting failure modes even if the type-specific checklist does not restate them. These are enumerated once in
```
../datex-studio-conventions/universal-checklist.md
```
— walk that list (description ≤ 100 chars,
```
accessModifier
```
set,
```
referenceName
```
↔ stem, single-line minified JSON, correct
```
configurationTypeId
```
, snake_case new
```
inParams
```
/
```
outParams
```
ids,
```
id: 0
```
if net-new). For tailored overlay files, the shadow-marker rules in
```
../tailoring-overlay/
```
apply on top.
Report. Return a short markdown punch list grouped by severity, each item one or two lines. No preamble, no rewrites, no code suggestions beyond one-line pointers. If nothing is wrong, say
```
No issues found.
```

根据文件后缀确定组件类型并加载匹配的规则文档。 creator skill的

references/<type>.md

是主要来源；跨领域约定文档始终也在审核范围内。

后缀	主要规则来源（creator skill）
`*-footprintFlow.json` （action）	`../action-creator/references/actions.md`
`*-flow.json` （function）	`../function-creator/references/functions.md`
`*-grid.json`	请改用 `grid-validator` —— 它包含本通用调度器无法检测到的grid特定问题。仅在 `grid-validator` 不可用时，才回退到 `../grid-creator/references/grids.md` 。
`*-form.json`	`../form-creator/references/forms.md`
`*-editor.json`	`../editor-creator/references/editors.md`
`*-hub.json`	`../hub-creator/references/hubs.md`
`*-storage.json`	`../storage-creator/references/storage.md`
`*-selector.json`	`../selector-creator/references/selectors.md`
`*-customType.json`	`../type-definition-creator/references/type-definitions.md`
`*-backendTest.json`	`../backend-test-creator/references/backend-tests.md`
`*-datasource.json`	`../datasource-creator/references/odata-datasources.md` （若内容格式为flow驱动，还需参考 `flow-datasources.md` ）
`*-footprintDatasource.json`	`../datasource-creator/references/odata-datasources.md` , `../datasource-creator/references/flow-datasources.md`
CAC工作目录（ `manifest.json` + 带有 `//#region __COMPONENT_TYPES__` / `__COMPONENT_BODY__` 的 `app.<ref>.component.ts` ）， `configurationTypeId: 36`	本文件后缀调度机制不适用——CAC并非单JSON文件。请按照 `../custom-angular-component-creator/SKILL.md` 中的预检查清单和 `../custom-angular-component-creator/references/custom-angular-components.md` 进行审核，而非使用后缀匹配的规则文档。

若后缀与表格中的任何项不匹配，请回复

Cannot validate: unknown component suffix '<suffix>'. Supported: <list>.

并停止。若文件被识别为定制覆盖变体，还需加载

../tailoring-overlay/

规则。

完整读取目标文件内容。 单个文件，一次
```
Read
```
操作。这是父级为更新暂存的临时JSON文件（或刚通过
```
jq .json
```
从分支获取的文件）——是一次性临时文件，而非持久化的可信来源副本。需针对检查清单审核压缩后的JSON信封内容。
读取匹配规则文档中的预检查清单部分。 这是你的规则手册。请勿凭记忆推导规则——仅应用文档中记录的规则。
逐项检查清单。 针对每个问题，记录：
- 严重程度 ——
```
blocker
```
  （静默运行时故障、导入错误、明确的规则违规）、
```
warning
```
  （可能会引发问题的偏差或不一致）、
```
nit
```
  （样式/命名/可选清理）。
- 规则 —— 对应检查清单中的哪一项。
- 位置 ——
```
<文件名>:<行号>
```
  或JSON路径（例如
```
inParams[0].objectTypeDef
```
  ）。
- 证据 —— 简短引用或描述。
始终检查通用跨领域故障模式，即使特定类型的检查清单未重述这些模式。这些模式在
```
../datex-studio-conventions/universal-checklist.md
```
中统一列举——需检查该清单（描述≤100字符、设置
```
accessModifier
```
、
```
referenceName
```
与文件主干匹配、单行压缩JSON、正确的
```
configurationTypeId
```
、新
```
inParams
```
/
```
outParams
```
的id使用snake_case、全新组件的
```
id: 0
```
）。对于定制覆盖文件，还需额外应用
```
../tailoring-overlay/
```
中的阴影标记规则。
报告。 返回按严重程度分组的简短Markdown问题清单，每项1-2行。无需前言，无需重写，除了单行提示外无需代码建议。若无问题，请回复
```
No issues found.
```

Scope Discipline

范围约束

You read. You do not edit.
You return a punch list. You do not rewrite.
You do not chase cross-component references — that is
```
component-wiring-check
```
's territory. If a wiring issue is obvious from the single file (e.g. a
```
configParameters
```
block that does not match the file's own
```
inParams
```
), flag it as a warning and let the parent decide whether to delegate further.
You do not load raw OData schema documents. If the component is a datasource that needs entity / property validation, recommend the parent invoke the
```
schema-explorer
```
skill separately.
You do not speculate about intent. If a rule violation could be deliberate, flag as a warning with a note rather than a blocker.

仅读取，不编辑。
返回问题清单，不返回重写内容。
不追踪跨组件引用——这是
```
component-wiring-check
```
的职责范围。若单个文件中存在明显的连接问题（例如
```
configParameters
```
块与文件自身的
```
inParams
```
不匹配），标记为warning并让父级决定是否进一步委托处理。
不加载原始OData模式文档。若组件为需要验证实体/属性的datasource，建议父级单独调用
```
schema-explorer
```
skill。
不推测意图。若规则违规可能是故意的，标记为warning并附带说明，而非blocker。

Output Format

输出格式

undefined

undefined

Blockers

[
```
description
```
] is
```
null
```
(defaults.md requires non-empty).
[
```
inParams[3].objectType
```
] references
```
Allocations.i_unknown_type
```
— type file not present in the package.

[
```
description
```
] 为
```
null
```
（defaults.md要求非空）。
[
```
inParams[3].objectType
```
] 引用
```
Allocations.i_unknown_type
```
—— 包中不存在该类型文件。

Warnings

[
```
outParams[0].id
```
= "alertList"] camelCase; new params should be snake_case.

[
```
outParams[0].id
```
= "alertList"] 使用camelCase；新参数应使用snake_case。

Nits

[
```
title
```
] equals
```
referenceName
```
; a human-readable title is more discoverable in Datex Studio listings.


Omit any bucket that is empty. If all three buckets are empty, return `No issues found.`

[
```
title
```
] 与
```
referenceName
```
相同；在Datex Studio列表中，可读的标题更易于查找。


省略所有为空的分组。若三个分组均为空，返回`No issues found.`

Bundled Save-Gate Hook (optional)

内置保存关卡钩子（可选）

scripts/validate-component.py

is a Claude Code PostToolUse hook enforcing the two cheapest floor checks (valid JSON, description present and ≤100 chars) at the harness level, blocking bad saves before any skill runs. Install per

scripts/INSTALL.md

. The hook is a floor, not a replacement for this skill's audit.

scripts/validate-component.py

是一个Claude Code PostToolUse钩子，在工具层面强制执行两项最基础的检查（有效的JSON、描述存在且≤100字符），在任何skill运行前阻止无效保存。请按照

scripts/INSTALL.md

进行安装。该钩子仅为基础检查，不能替代本skill的完整审计。