feat: release Dever 0.1.4 with enforceable project guidance
This commit is contained in:
Antigravity committed
1 parent
201bdee372
commit
89629c2197
86 files changed
+2798
-338
No files matched your search
@@ -14,7 +14,9 @@ dever build my_app --output my_app/program
|
||||
|
||||
创建 Markdown 项目用 `dever new my_app --markdown`。两种模板使用相同代码和行为，Markdown 另加编译器校验的说明。目标目录必须不存在，父目录必须已存在；不接受向现有项目合并或覆盖。build 输出也必须不存在。
|
||||
|
||||
模板只包含 CMD、App、配置、一个测试和开发指引，无需数据库或 HTTP 服务。实际项目在它的目录合同上扩展，替换演示领域，删除不再使用的示例与测试。添加 HTTP 时须完成 [站点与身份配置](application.md)，不能只把 cmd 换成 get。
|
||||
模板包含 CMD、App、配置、一个测试和开发指引，无需数据库或 HTTP 服务。`dever new` 已生成 `AGENTS.md`；已有项目在根目录运行 `dever skill install` 即可写入同一份规则，保留文件中其他内容。
|
||||
|
||||
按需要替换模板的演示领域，删除不再使用的示例与测试。添加 HTTP 时须完成 [站点与身份配置](application.md)，不能只把 cmd 换成 get。
|
||||
|
||||
```text
|
||||
my_app/
|
||||
@@ -48,6 +50,14 @@ my_app/
|
||||
| Job | 持久任务声明，绑定同领域 App |
|
||||
| Test | 文件同名、零输入零输出的唯一测试入口 |
|
||||
|
||||
## 不擅自保留旧实现
|
||||
|
||||
默认只实现当前接口和语法。用户没有明确要求兼容时，不保留旧参数、旧配置读取、旧接口、别名或备用实现，不用“以后可能用到”作为保留理由。
|
||||
|
||||
改接口时，查清本项目调用方，一起修改实现和必要测试，删除本次废弃路径。外部调用方无法一起修改时，说明影响，由用户决定迁移安排；不能擅自加一套兼容流程。
|
||||
|
||||
项目通过 `dever.version` 使用某个编译器版本，是正常的版本选择，不要求业务代码同时支持新旧两套行为。业务明确要求的失败恢复也不是旧版本兼容，但必须有真实依据、明确结果和相应验证。
|
||||
|
||||
## 文件与函数组织
|
||||
|
||||
简单领域保留角色单文件；复杂角色可以拆为 `app/publish.dever`、`app/search.dever` 等内聚主题，调用名不带文件名。非 API topic 目录不递归。App/Domain/Port/Adapter/Job 单文件与同名目录二选一，选择目录时至少有两个内聚主题文件；Model/API 主文件与 topic 目录可按编译器合同共存，不受这个最少文件数限制。只有 `api/` 可按站点和资源继续嵌套，目录会影响 URL。
|
||||
@@ -93,31 +103,57 @@ my_app/
|
||||
|
||||
`test/hello/greeting/greet.dever`：
|
||||
|
||||
源码：[模板测试](../assets/template/test/hello/greeting/greet.dever)
|
||||
|
||||
```dever
|
||||
greet() () {
|
||||
assert_eq(hello.greeting.greet("Dever"), "Hello, Dever")
|
||||
message = app.greet("Dever")
|
||||
assert_eq(message, "Hello, Dever")
|
||||
}
|
||||
```
|
||||
|
||||
模板中的实际字符串以生成文件为准。测试只执行文件同名函数，不需要 main 或注解。`assert` 接受 Bool，`assert_eq` 要求同类型。测试可访问同领域 App/Domain，跨领域仅 App，不能直接写 Model CRUD。使用 Model 时运行器使用临时 SQLite；不使用 Model 时不需要数据库。它不会读取生产 setting.json 或生产 data。对业务失败使用 `result(call)` 配合 choice 分句验证。
|
||||
测试只执行文件同名函数，不需要 main 或注解。`assert` 接受 Bool，`assert_eq` 要求同类型。业务失败用 `result(call)` 和 choice 分句断言。模板中的字符串以生成文件为准。
|
||||
|
||||
常用命令：`fmt --check` 查格式，`check` 查语法/类型/目录/分句/配置，`api` 输出 API 合同，`test` 运行应用套件，`run` 开发执行，`build` 生成独立程序。不要发明 `test --filter`、`run api` 或 `dever init`。
|
||||
测试可调用同领域 App/Domain，跨领域只调用 App，不能直接写 Model CRUD。涉及 Model 时使用临时 SQLite，否则不需要数据库。命令会读取 setting.json 和锁中的依赖信息，但测试不连接部署数据库，也不使用项目 data。
|
||||
|
||||
常用命令：`fmt --check` 查格式，`check` 查语法/类型/目录/分句/配置，`api` 输出 API 合同，`test` 运行应用套件，`run` 开发执行，`build` 生成独立程序。不要发明 `run api` 或 `dever init`。
|
||||
|
||||
选一个测试运行：
|
||||
|
||||
```sh
|
||||
dever test my_app --filter hello.greeting.greet --timeout-ms 5000
|
||||
```
|
||||
|
||||
`--filter` 可以写组件、组件.领域或组件.领域.用例。`news.article` 不会选中 `news.article_extra`，不支持子串或通配符。筛选后仍检查全部源码；没有匹配项就报错，未执行用例显示 `not run`。
|
||||
|
||||
每例默认限时 60 秒，不含编译时间。`--timeout-ms` 必须是正整数毫秒；选项不能重复。超时后回收本例进程及后代，记录失败并继续下一例，最终命令返回失败。
|
||||
|
||||
### 验证范围
|
||||
|
||||
| 检查 | 能证明的范围 |
|
||||
| --- | --- |
|
||||
| `dever fmt <root> --check` | 源码格式；不证明类型或业务正确 |
|
||||
| `dever check <root>` | 静态语法、类型、目录、命名、分句、相关配置、已有 API 基线，以及应用入口可达性和冗余硬检查；不执行应用 |
|
||||
| `dever test <root>` | 当前项目全部应用测试的实际断言；没有筛选参数，不证明生产入口完整 |
|
||||
| `dever check <root>` | 检查语法、类型、目录、配置和已有 API 基线；也检查业务入口无法调用到的代码及确定的冗余。不运行应用 |
|
||||
| `dever test <root> [--filter ...] [--timeout-ms ...]` | 检查全部源码，实际执行所选测试断言（默认全部）；不证明生产入口完整 |
|
||||
| `dever run/build` | 通过与 check 相同的应用硬检查，再准备本地编译资源并执行或编译；成功不等于部署或性能验收 |
|
||||
| AI 审查 | 业务含义、职责拆分、复用、硬编码与验证范围，不能替代程序检查 |
|
||||
|
||||
`check/run/build` 共用 C016，拒绝生产入口不可达的 App/Domain，以及符合现有判定条件的私有空转发和 Model CRUD 包装；并非任意角色、所有函数或全部 CRUD 包装都能检出。`check` 不准备 Worker 或 runtime pack，不进行原生编译，不启动应用、服务或数据库。`test` 保持独立的测试入口与 Port fake 检查，不执行生产入口可达性检查；不能用测试调用掩盖生产死代码，也不能把静态检查当作运行验收。
|
||||
`check/run/build` 会拒绝这些 App/Domain 问题（C016）：
|
||||
|
||||
W001–W005 等诊断包含未使用赋值、部分冗余条件、相同私有实现、重复纯调用和空转发建议，警告本身不会使命令失败。审查本次引入的诊断，修正有证据的问题；不能声称编译器能判定全部硬编码或业务价值。skill 中的开发要求不自动变成编译器硬错误。
|
||||
- 接口、命令和后台任务等生产入口都调用不到的函数。
|
||||
- 符合现有判定条件的私有空转发和 Model CRUD 包装。
|
||||
- 生产入口可达、同一源码文件内契约和实现完全相同、没有副作用的私有函数。
|
||||
- 生产入口可达的函数内，参数未变且前一次结果仍可复用的重复纯调用。直接复用已有结果；参数或结果被修改时不按这条拒绝。
|
||||
|
||||
选择与改动相符且已获授权的检查。新模板的小套件可以完整运行；已有大项目不默认运行全量 `dever test`，也不默认启动服务、连接真实数据库或压测。需要但尚未运行的检查要说明原因和剩余证据，不能伪报通过。已有 `dever.api` 时保留基线约束；`dever api <root> --output <新文件>` 可以导出待比较合同，不覆盖原文件。
|
||||
这些规则不强迫合并有副作用、契约不同或跨文件的私有实现，也不能识别所有无用代码。
|
||||
|
||||
`check` 不准备 Worker 或运行资源，不生成原生程序，也不启动服务或数据库。`test` 只检查自己的入口和 Port fake，不套用生产应用硬检查；测试调用不能证明函数被实际业务使用，因此还要运行 `check`。
|
||||
|
||||
未使用赋值、部分多余条件、重复私有实现、重复纯调用和空转发还可能产生警告（W001–W005）。普通库和测试保留这些警告；应用满足上述条件时报 C016，同一源码证据的对应警告不重复显示。其他警告仍会显示，警告本身不使命令失败，但必须审查并处理本次引入的问题。编译器不能判断所有业务硬编码；skill 和 AGENTS 的要求也不自动变成编译错误。
|
||||
|
||||
按改动范围和用户授权选择检查。新模板可运行全部测试；已有大项目优先定向测试，不默认启动服务、接真实数据库或压测。未运行的必要检查应说明原因，不能报成通过。
|
||||
|
||||
已有 `dever.api` 时保留接口基线。需要比较新接口时，用 `dever api <root> --output <新文件>` 导出，不直接覆盖原文件。
|
||||
|
||||
源码放 module/，测试放 test/，部署配置放 config/，运行数据放 data/。生成程序从二进制同级 config/setting.json 读取配置。应用无需打包编译器；使用外部 Lib 时相关 runtime/依赖由 build 嵌入。只读 check 不证明真实数据库或部署验收。
|
||||
|
||||
|
||||
Reference in new issue
Block a user