# Checker 开发

Checker 是 DiAL 的核心扩展单元。每个 checker 是 `src/server/checker/runner/<type>/` 下的自包含目录，包含该 checker 所需的类型、schema、校验、执行逻辑和断言。

新增或修改 checker 前请同时阅读 [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)、[配置文件](../user/configuration.md)、[校验规则](../user/expectations.md) 和 [Checker 用户文档](../user/checkers/README.md)。

## 架构目标

```text
checkerRegistry
  ├── runner/index.ts
  ├── schema/builder.ts
  ├── schema/validate.ts
  ├── config-loader.ts
  ├── engine.ts
  └── store.ts
```

注册后，中间层通过 registry 自动委托 schema 生成、契约校验、配置 resolve、执行和序列化。新增 checker 不应在中间层新增 `switch/case` 或类型分支。

## 标准文件结构

| 文件          | 职责                                                  |
| ------------- | ----------------------------------------------------- |
| `index.ts`    | 模块入口，re-export Checker 类                        |
| `types.ts`    | Checker 专属类型                                      |
| `schema.ts`   | TypeBox 契约 schema，包含 config 和 expect            |
| `validate.ts` | 启动期语义校验                                        |
| `execute.ts`  | Checker 类，实现 resolve、execute、serialize          |
| `expect.ts`   | Checker 专用断言函数                                  |
| 其他文件      | 协议解析、编码、provider 适配、平台命令封装等专属逻辑 |

## 类型定义

在 `types.ts` 中定义：

- `RawXxxTargetConfig`
- `RawXxxExpectConfig`
- `ResolvedXxxExpectConfig`
- `ResolvedXxxTarget extends ResolvedTargetBase`

不需要修改顶层 `checker/types.ts`。base interface 使用 index signature 支持扩展。

## Schema

checker 必须提供 `CheckerSchemas`，包含 Authoring 和 Normalized 两套 config/expect 片段。Authoring 描述用户 YAML 可写 DSL，Normalized 描述 normalizer 输出。

常用 fragments：

| Fragment                            | 用途                      |
| ----------------------------------- | ------------------------- |
| `durationSchema`                    | 时长字符串                |
| `sizeSchema`                        | 大小单位                  |
| `statusCodePatternSchema`           | HTTP 状态码或范围         |
| `stringMapSchema`                   | headers、env 等字符串映射 |
| `createValueMatcherSchema()`        | ValueMatcher              |
| `createContentExpectationsSchema()` | ContentExpectations       |
| `createKeyedExpectationsSchema()`   | KeyedExpectations         |

默认对象策略为 `additionalProperties: false`。只有明确的动态键值表可以开放任意键名。

## 语义校验

在 `validate.ts` 中实现 JSON Schema 无法表达的规则，统一返回 `ConfigValidationIssue[]`，不要直接拼接最终错误字符串。

共享校验工具包括：

| 函数                             | 用途                         |
| -------------------------------- | ---------------------------- |
| `validateRawValueExpectation`    | 校验 Raw ValueExpectation    |
| `validateRawContentExpectations` | 校验 ContentExpectations     |
| `validateRawKeyedExpectations`   | 校验 KeyedExpectations       |
| `validateJsonPath`               | 校验项目支持的 JSONPath 子集 |
| `isJsonValue`                    | 判断合法 JSON value          |

## resolve 规范

`resolve()` 只做内置默认值填充、路径解析、单位转换，不执行校验。输入已经通过 Normalized schema 和语义校验，expect 已是 normalized 形态。

```typescript
const expect = target.expect as ResolvedXxxExpectConfig | undefined;
const resolvedExpect: ResolvedXxxExpectConfig = expect
  ? { ...expect, status: expect.status ?? [200] }
  : { status: [200] };
```

返回值使用 `satisfies ResolvedXxxTarget` 确保类型正确。

## execute 规范

- 始终记录 `timestamp` 和 `start = performance.now()`。
- 通过 `ctx.signal` 支持超时取消。
- 首个 expect 失败即停止，返回带 `failure` 的结果。
- 成功时 `failure: null, matched: true`。
- 异常时使用 `errorFailure()`。
- 不匹配时使用 `mismatchFailure()`。
- `expected` 参数应传用户可读值，必要时使用 `displayValueExpectation()`。

## expect 字段选择

| 场景                                 | 模型                |
| ------------------------------------ | ------------------- |
| 状态类结果且集合小而稳定             | enum 或 boolean     |
| 单值数字指标或字符串元数据           | ValueMatcher        |
| 文本、JSON、HTML、XML 或半结构化内容 | ContentExpectations |
| 动态键值表                           | KeyedExpectations   |

不要为了统一而把状态类字段改成 ValueMatcher。一个 expect 字段只能对应一种断言模型。

## 注册

1. 创建 `src/server/checker/runner/<type>/index.ts`。
2. 在 `src/server/checker/runner/index.ts` 添加导入。
3. 在 registry 初始化数组中添加 checker 实例。

注册后，schema builder、validate、config-loader、engine、store 会自动按 registry 分发。

## 测试要求

测试文件放在 `tests/server/checker/runner/<type>/`，结构镜像源文件。

| 测试类别     | 覆盖内容                                 |
| ------------ | ---------------------------------------- |
| 契约测试     | TypeBox schema 与 JSON Schema 导出一致性 |
| 语义校验测试 | 合法和非法配置                           |
| resolve 测试 | 默认值合并、路径解析、单位转换           |
| execute 测试 | 成功、失败、超时、expect 组合            |
| 注册测试     | registry 注册行为                        |
| 配置加载测试 | 含新 checker 的 YAML 完整加载流程        |

## 文档和 schema 更新

新增或修改 checker 时通常需要更新：

- `probes.example.yaml`
- `probe-config.schema.json`，通过 `bun run schema` 生成
- `docs/user/checkers/<type>.md`
- `docs/user/checkers/README.md`
- `docs/user/expectations.md`，仅当断言模型或通用规则变化
- `docs/development/checker-development.md`，仅当开发机制变化
- `CONTRIBUTING.md`，仅当贡献流程或 checklist 变化

## 完成检查清单

```text
□ src/server/checker/runner/<type>/types.ts
□ src/server/checker/runner/<type>/schema.ts
□ src/server/checker/runner/<type>/validate.ts
□ src/server/checker/runner/<type>/execute.ts
□ src/server/checker/runner/<type>/expect.ts
□ src/server/checker/runner/<type>/index.ts
□ src/server/checker/runner/index.ts
□ tests/server/checker/runner/<type>/
□ probes.example.yaml
□ probe-config.schema.json
□ docs/user/checkers/<type>.md
□ bun run schema
□ bun run schema:check
□ bun run check
□ bun run verify
```