docs: 添加 checker 内聚化重构方案及归档历史变更
新增 refactor-checker-cohesion 变更提案,包含 proposal、design、 specs 和 tasks,定义 checker 目录内聚结构规范。同时归档已完成的 历史变更记录。
This commit is contained in:
36
openspec/changes/refactor-checker-cohesion/proposal.md
Normal file
36
openspec/changes/refactor-checker-cohesion/proposal.md
Normal file
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
当前 checker 的类型定义、校验逻辑、共享工具分散在多个层级目录中,新增一个 checker 需要修改顶层 `types.ts`(联合类型)、`runner/shared/`(如果有新的 expect 模式)、`config-contract/`(如果有新的 schema 片段)等多处文件。项目的核心就是 checker,需要让每个 checker 的代码尽可能内聚——新增 checker 只需创建一个目录 + 在注册列表加一行,其他文件零修改。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 将 `ResolvedTarget` 和 `TargetConfig` 从硬编码联合类型改为 base interface,各 checker 内部自行 narrow
|
||||
- 将各 checker 专属类型(`HttpTargetConfig`、`ResolvedHttpTarget`、`CommandExpectConfig` 等)从顶层 `types.ts` 搬入各自 checker 目录的 `types.ts`
|
||||
- 将 `runner/shared/` 中仅单个 checker 使用的模块搬入对应 checker 目录(`body.ts` → `http/`,`text.ts` → `command/`)
|
||||
- 将 `runner/shared/` 中真正跨 checker 共享的断言基础设施(`operator.ts`、`duration.ts`、`failure.ts`)提升为 `checker/expect/` 目录
|
||||
- 将 `shared/validate.ts` 拆分:通用 operator 校验 → `expect/validate-operator.ts`,body 规则校验 → `http/validate.ts`,text 规则校验 → `command/validate.ts`
|
||||
- 将 `config-contract/` 重命名为 `schema/`,内部 `schema.ts` 重命名为 `builder.ts`
|
||||
- 将 `size.ts` 和 `config-loader.ts` 中的 `parseDuration` 合并到 `utils.ts`
|
||||
- 各 checker 的 `runner.ts` 重命名为 `execute.ts`,`contract.ts` 重命名为 `schema.ts`
|
||||
- 各 checker 新增 `index.ts` 作为统一出口(仅 re-export)
|
||||
- `runner/index.ts` 改为显式列表注册模式
|
||||
- 将 `DefaultsConfig` 从硬编码联合(`command?: CommandDefaultsConfig; http?: HttpDefaultsConfig`)改为宽松 base 形式(`Record<string, unknown>` + 公共字段),各 checker validate 时自行 narrow
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `checker-cohesion-structure`: 定义重构后 checker 目录的内聚结构规范,包括每个 checker 目录应包含的文件、职责划分、依赖方向约束,以及新增 checker 的最小改动清单
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `checker-runner-abstraction`: `CheckerDefinition` 接口的 `resolve`/`execute`/`serialize` 方法签名从具体联合类型改为 base interface;共享 expect 断言函数的物理位置从 `runner/shared/` 变更为 `checker/expect/`(仅路径变化,行为不变)
|
||||
|
||||
## Impact
|
||||
|
||||
- 影响 `src/server/checker/` 目录下几乎所有文件的 import 路径
|
||||
- `types.ts` 大幅瘦身,联合类型删除
|
||||
- `runner/shared/` 目录删除,内容分散到 `expect/` 和各 checker 目录
|
||||
- `config-contract/` 目录重命名为 `schema/`
|
||||
- 所有现有测试的 import 路径需要同步更新
|
||||
- 不影响外部 API、配置文件格式、运行时行为
|
||||
Reference in New Issue
Block a user