@ultime/codecraft 1.4.0 → 1.6.0

package/docs/08-audit-contract.md

@@ -0,0 +1,141 @@
+# 审计输出契约 v1
+
+> 2026-10-27 · v1
+> 用途：约束 Audit 模式的判定、证据、局限与一致性，防止把“静态检查 0 findings”写成“全部通过”。
+> 范围：JS/TS 项目，默认前端；Node 后端只复用结构与安全类判定。
+> 关系：流程见 `docs/02-ai-contract.md`；格式见 `prompts/output.md`；规则正文见 `docs/00-constitution.md` 与 `docs/01-family-cards.md`。
+
+## 1. 必填结构
+
+Audit 报告必须包含：
+
+1. **范围与方法**：仓库 / 分支 / 目录、只读声明、执行的命令、未执行项与原因。
+2. **逐条判定**：A1–A21 全覆盖；不适用写 `na` 并说明原因。
+3. **差距 / 风险**：按优先级分组，每条带证据。
+4. **计划**：阶段、内容、可回滚、验收。
+5. **验证**：命令 + 结果；不能跑要写原因。
+6. **局限**：静态检查覆盖不到的部分，尤其是 A17 / A21。
+
+逐条判定表固定为：
+
+```md
+| ID | 判定 | 证据 | 局限 |
+|---|---|---|---|
+| A4 | warn | `useList.ts` 6 处、页面 20+ 处 `code === 200` | 未覆盖运行时错误分支 |
+```
+
+## 2. 判定口径
+
+| 判定 | 含义 |
+|---|---|
+| `pass` | 有证据覆盖该规则，且没有相反证据 |
+| `pass（静态）` | 只有静态检查通过；必须写清检查范围，不能替代人工抽样 |
+| `warn` | 存在相反证据、覆盖不完整，或只有部分满足 |
+| `fail` | 明确违反，且会造成安全、数据或契约风险；按 P0 处理 |
+| `na` | 该规则不适用；必须写原因 |
+
+证据要求：
+
+- 文件级：`path/to/file.ts:line`；不要只写目录。
+- 命令级：写出命令与结果；计数必须带可复现的检索式。
+- 禁止「看起来一致」「整体规范」这类无证据结论。
+- 一个规则有多个子项时，逐项给证据；不能用一个子项代表全部。
+
+## 3. 静态检查边界
+
+内置检查是**抽样工具**，不是审计结论：
+
+- **A17**：按三条线索识别生成类型：路径含 `external/` / `generated/`、文件头有只读声明（`本文件由…生成` / `勿手改` / `@generated`）、`boundaries.external` / `boundaries.generated` 配置。只解析相对路径与 `@/` `~/` `#/` 别名；解析不到或头部无标记时仍是盲区，必须人工检查。
+  - 生成的数据 / 资源模块（如图标表）不算类型契约，不触发 A17。
+  - 约定：生成 / 外部类型放在 `external/` 或 `generated/` 下；迁移前按人工检查，不能因 0 findings 判 `pass`。
+- **A2 / A11**：只覆盖包结构、生成物标记等文本模式；没有类型图、没有运行时验证。
+- **A21**：高置信 token 模式（私钥 / AWS / 阿里云 `LTAI` / GitHub / Slack / API key）+ 配置与 Java / Kotlin 源码中的明文强口令 / 密钥字段；跳过环境变量、占位符与测试目录。没有命中不等于不存在，必须写明扫描范围。
+- **A4 / A5 / A8 / A12 / A13 / A19**：靠人工阅读，不做静态扫描。A4 需要语义判断；A5 需要状态可达性、A8 需要数据流分析，文本级扫描实测误报高；不能因为 CLI 0 findings 就给 `pass`。
+
+因此：
+
+- 报告必须写「`codecraft check` 的结果与覆盖范围」。
+- 用了 `--exclude` 时必须列出排除路径；否则计数不可复现。
+- `0 findings` 只能写成「静态检查未命中」，不能写成「规则通过」。
+- 审计结论的置信度分为 High / Medium / Low：
+  - High：静态 + 人工抽样 + 关键路径验证
+  - Medium：静态 + 人工抽样
+  - Low：仅静态检查
+
+## 4. A1–A21 判定矩阵
+
+| ID | 判定方式 | `pass` 条件 | 常见误判 |
+|---|---|---|---|
+| A1 | 人工抽样（结构检索辅助） | 同族实例使用同一模板 / 插槽；抽样覆盖主要分支 | 只看到统一 Wrapper，忽略内部结构分叉 |
+| A2 | 静态依赖 + 人工 | 无反向依赖、无跨层 import | 只看 core 的 import，漏掉传输层 import 状态 |
+| A3 | 人工 | 传输层不解释业务 code、不承担 UI 反馈 | 401 收口一处就判通过 |
+| A4 | 人工 + 计数 | 每种关注点只有一个收口；无散落的同类判断 | 认证 / 提示各一处，但业务码判断散落 30+ 处 |
+| A5 | 静态 + 人工 | 非法状态不可表示；联合类型 / 穷尽分支 | 有类型但大量 `any` / 多布尔并存 |
+| A6 | 人工 + 静态（空 catch） | 错误是值；无静默失败；调用方必须处理 | 成功元组里 err 恒为 `undefined`，业务失败仍走成功分支 |
+| A7 | 人工 | 可枚举变化用表；加 case 只加一行 | 有表但仍有并行 if / switch |
+| A8 | 人工 | 派生状态不落库 / 不重复存储 | 有 computed，同时把结果再存一份 |
+| A9 | 人工 | 注释只写意图 / 契约 / 边界 / 反例 | 注释复述代码，或规范文档本身漂移 |
+| A10 | 人工 + 配置 | 例外有理由 / 主人 / 到期；安全不可豁免 | 只写“历史原因”，没有到期 |
+| A11 | 静态（标记）+ CI 比对 | 生成物有只读标记，且再生成 diff 为空 | 只有“勿手改”头，没有再生成比对 |
+| A12 | 人工 | 复制有母版、版本、分叉点、升级路径 | 多处副本，未指明母版 |
+| A13 | 人工 | 每一层都能一眼定位源头 | `utils/` 成为域名 / 传输 / 海报的混合桶 |
+| A14 | 人工 | 抽象有真实消费方与触发条件 | 以“以后可能用”为由提前抽象 |
+| A15 | 流程 / 输出检查 | 变更说明含改了什么 / 为什么 / 怎么验 / 风险 | 用 A15 去评价代码结构 |
+| A16 | 人工 + 搜索 | 命名标层、可搜索、组合可读 | 单项目内一致，但跨端 / 跨团队歧义 |
+| A17 | 静态（路径 / 文件头 / 配置）+ 人工 | 内部不 import 外部类型；外部契约在包装层转换 | 别名解析不到或头部无标记就判通过；把生成数据模块当成类型契约 |
+| A18 | 人工 | 有档位；默认 L0；按触发升级 | 所有能力默认开启 |
+| A19 | 人工 + 契约测试 | public contract 固定；有可替换性验证 | 边界口头清楚，但没有契约测试 |
+| A20 | 人工 | 记录环节 / 职责 / 契约，不把库当层 | 用框架名代替架构层 |
+| A21 | 静态扫描 + 人工 | 无密钥 / 内部路径外泄；交付白名单一致 | 模式扫描 0 命中就判全局通过；把运行时变量名当明文密钥 |
+
+## 5. 一致性检查
+
+出结论前，必须做一次交叉检查；发现矛盾就降级：
+
+| 场景 | 要求 |
+|---|---|
+| A4 判 `pass`，但存在多处 `code === 200` / 重复错误处理 | 改为 `warn`；单一收口未成立 |
+| A11 判 `pass`，但没有再生成比对 / CI diff | 最多 `warn`；只能写“生成物有只读标记” |
+| A8 判 `pass`，但派生状态被落库 / 重复存储 | 改为 `warn`，或写明可接受理由与主人 |
+| A21 判 `pass`，但只做了模式扫描 | 写 `pass（有限）` 或 `warn`；列扫描范围 |
+| A17 判 `pass`，但存在生成类型直用 | 改为 `warn`；路径不在 `external/` 也算 |
+| A12 判 `pass`，但同族存在多份副本 | 改为 `warn`；必须指明母版 |
+| A3 判 `pass`，但传输层直接弹 Toast / 跳转 | 改为 `warn`；传输层不应承担 UI 反馈 |
+
+## 6. 优先级
+
+| 级别 | 定义 | 例子 |
+|---|---|---|
+| P0 | 安全、数据丢失、不可回滚 | 密钥泄漏、越权、破坏性迁移 |
+| P1 | 架构 / 契约 / 文档真源错误 | 分层失效、规范写错事实、门禁缺失 |
+| P2 | 可维护性 / 重复实现 | 业务错误码散落、上传目录三份真源 |
+| P3 | 测试、清理、体验 | 纯函数无单测、命名不统一 |
+
+同一份报告里，P1 不能多于结论总数的一半而不说明取舍；否则先合并根因。
+
+## 7. 计划表
+
+```md
+| 阶段 | 内容 | 可回滚 | 验收 |
+|---|---|---|---|
+| 0 | 文档纠偏 | 纯文档，单 commit 可回退 | 描述与检索结果一致 |
+| 1 | 门禁补齐 | 移除 config / hook 即恢复 | 故意引入类型错误会被拦 |
+```
+
+要求：
+
+- 每阶段可独立回滚，不用“重来一遍”。
+- 验收必须是可执行命令或可检索结果，不写“感觉完成”。
+- 不写时间估算；写依赖与顺序。
+- 重构阶段先补基线（typecheck / 单测 / 契约测试），再改行为。
+
+## 8. 交付前自检
+
+- [ ] A1–A21 全部出现，或写明 `na`
+- [ ] 每条 `pass` / `warn` 都有文件行号或命令
+- [ ] 所有计数都能用文中命令复现
+- [ ] 已做一致性检查，A4 / A8 / A11 / A17 / A21 没有被高估
+- [ ] 已写明静态检查覆盖不到的部分
+- [ ] 没有密钥、内部路径、客户隐私
+- [ ] Audit 只读；未改代码、未起服务
+- [ ] 计划每阶段可回滚、有验收

package/docs/09-glossary.md

@@ -0,0 +1,22 @@
+# Glossary（术语表）
+
+> 写法：正文首次出现用 `English（中文）`；名字类不附中文。
+> 名字类 = 产品 / 文件 / 命令 / 语言 / 框架 / 标准名 / 代码标识（如 Codecraft、README.md、npm、JS/TS、JSON、A1–A21）。
+> 本表是术语写法的单一真源；`tests/docs.test.mjs` 检查正文首次出现。
+
+| English | 中文 |
+|---|---|
+| Audit | 审计 |
+| Plan | 计划 |
+| Apply | 执行 |
+| Wrapper | 包装层 |
+| Gate | 门禁 |
+| Gates | 门禁 |
+| Drift | 漂移 |
+| ADR | 架构决策记录 |
+| Canonical Link | 规范链接 |
+| canonical link | 规范链接 |
+| Context Engineering | 上下文工程 |
+| Progressive Disclosure | 渐进披露 |
+| Single Source of Truth | 单一真源 |
+| Design System | 设计系统 |

package/evals/cases.json

@@ -0,0 +1,110 @@
+[
+  {
+    "name": "a17-default",
+    "root": "a17-default",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A17": 1 } }
+  },
+  {
+    "name": "a17-boundaries",
+    "root": "a17-boundaries",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A17": 1 } }
+  },
+  {
+    "name": "a6-empty-catch",
+    "root": "a6-empty-catch",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A6": 1 } }
+  },
+  {
+    "name": "ignore-active",
+    "root": "ignore-active",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {}, "ignored": 1 }
+  },
+  {
+    "name": "ignore-expired",
+    "root": "ignore-expired",
+    "args": ["--pack", "app", "--format", "json", "--ci"],
+    "expect": { "exit": 1, "findings": { "A17": 1 }, "expired": 1 }
+  },
+  {
+    "name": "library-a11",
+    "root": "library-a11",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A11": 1 } }
+  },
+  {
+    "name": "zero-files",
+    "root": "zero-files",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 2, "findings": {}, "warnings": 1 }
+  },
+  {
+    "name": "a17-generated-header",
+    "root": "a17-generated-header",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A17": 1 } }
+  },
+  {
+    "name": "a21-plaintext",
+    "root": "a21-plaintext",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A21": 2 } }
+  },
+  {
+    "name": "a2-workspace",
+    "root": "a2-workspace",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A2": 1 } }
+  },
+  {
+    "name": "a2-declared",
+    "root": "a2-declared",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a6-clean",
+    "root": "a6-clean",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a11-marker",
+    "root": "a11-marker",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a17-local",
+    "root": "a17-local",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a17-generated-data",
+    "root": "a17-generated-data",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a21-placeholders",
+    "root": "a21-placeholders",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a21-doc-paths",
+    "root": "a21-doc-paths",
+    "args": ["--pack", "design-system", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A21": 2 } }
+  },
+  {
+    "name": "sarif",
+    "root": "a17-default",
+    "args": ["--pack", "app", "--format", "sarif"],
+    "expect": { "exit": 0, "sarif": { "version": "2.1.0", "rule": "A17" } }
+  }
+]

package/evals/fixtures/a11-marker/packages/core/dist/tokens.css

@@ -0,0 +1,4 @@
+/* 生成物 · 勿手改：由 core build 产出 */
+:root {
+  --color-fg: #111;
+}

package/evals/fixtures/a11-marker/packages/core/package.json

@@ -0,0 +1 @@
+{ "name": "@x/core" }

package/evals/fixtures/a11-marker/packages/core/src/index.ts

@@ -0,0 +1 @@
+export const version = '1.0.0'

package/evals/fixtures/a17-boundaries/codecraft.config.json

@@ -0,0 +1,5 @@
+{
+  "boundaries": {
+    "generated": ["@/types/project"]
+  }
+}

package/evals/fixtures/a17-boundaries/src/pages/home.ts

@@ -0,0 +1 @@
+import type { Project } from '@/types/project'

package/evals/fixtures/a17-default/src/pages/home.ts

@@ -0,0 +1 @@
+import { User } from '@/external/user'

package/evals/fixtures/a17-generated-data/src/icons/icons.ts

@@ -0,0 +1,2 @@
+/* icons.ts — 本文件由脚本生成，勿手改 */
+export default { search: '<path />' }

package/evals/fixtures/a17-generated-data/src/pages/home.ts

@@ -0,0 +1,3 @@
+import icons from '@/icons/icons'
+
+export const searchIcon = icons.search

package/evals/fixtures/a17-generated-header/src/pages/home.ts

@@ -0,0 +1,5 @@
+import type { Project } from '@/types/project'
+
+export function nameOf(project: Project) {
+  return project.id
+}

package/evals/fixtures/a17-generated-header/src/types/project.ts

@@ -0,0 +1,4 @@
+/** 本文件由脚本生成，勿手改 */
+export interface Project {
+  id: string
+}

package/evals/fixtures/a17-local/src/pages/home.ts

@@ -0,0 +1,4 @@
+import type { Local } from '@/types/local'
+import { format } from '@/utils/format'
+
+export const label = (value: Local) => format(value.id)

package/evals/fixtures/a17-local/src/types/local.ts

@@ -0,0 +1,3 @@
+export interface Local {
+  id: string
+}

package/evals/fixtures/a17-local/src/utils/format.ts

@@ -0,0 +1,3 @@
+export function format(value: string): string {
+  return value.trim()
+}

package/evals/fixtures/a2-declared/packages/core/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@x/core",
+  "dependencies": {
+    "@x/kit": "workspace:*"
+  }
+}

package/evals/fixtures/a2-declared/packages/core/src/index.ts

@@ -0,0 +1,3 @@
+import { token } from '@x/kit'
+
+export const value = token

package/evals/fixtures/a2-declared/packages/kit/package.json

@@ -0,0 +1 @@
+{ "name": "@x/kit" }

package/evals/fixtures/a2-workspace/packages/core/package.json

@@ -0,0 +1 @@
+{ "name": "@x/core" }

package/evals/fixtures/a2-workspace/packages/core/src/index.ts

@@ -0,0 +1,3 @@
+import { token } from '@x/kit'
+
+export const value = token

package/evals/fixtures/a2-workspace/packages/kit/package.json

@@ -0,0 +1 @@
+{ "name": "@x/kit" }

package/evals/fixtures/a21-doc-paths/packages/ui/README.md

@@ -0,0 +1,5 @@
+# UI
+
+实现说明见 `docs/开发计划/components/README.md`。
+上游约定见 `../docs/guide.md`。
+自带文档：`docs/guide.md`。

package/evals/fixtures/a21-doc-paths/packages/ui/package.json

@@ -0,0 +1 @@
+{ "name": "@x/ui" }

package/evals/fixtures/a21-doc-paths/packages/ui/src/index.ts

@@ -0,0 +1 @@
+export { Button } from './button'

package/evals/fixtures/a21-placeholders/.env

@@ -0,0 +1,2 @@
+APP_SECRET=${APP_SECRET}
+PASSWORD=

package/evals/fixtures/a21-placeholders/server/application.yml

@@ -0,0 +1,9 @@
+spring:
+  datasource:
+    password: ${DB_PASSWORD}
+  redis:
+    password: ${REDIS_PASSWORD}
+jwt:
+  secret: change-me
+  apiKey: your-key-here
+  accessKey: <ACCESS_KEY>

package/evals/fixtures/a21-placeholders/src/pages/home.ts

@@ -0,0 +1 @@
+export const ready = true

package/evals/fixtures/a21-plaintext/application.yml

@@ -0,0 +1,5 @@
+spring:
+  datasource:
+    password: demo-pass-123
+  redis:
+    password: ${REDIS_PASSWORD}

package/evals/fixtures/a21-plaintext/src/main/java/Ali.java

@@ -0,0 +1,3 @@
+class Ali {
+  private static final String ACCESS_KEY_ID = "LTAI5tAbCdEfGhIjKl";
+}

package/evals/fixtures/a21-plaintext/src/pages/home.ts

@@ -0,0 +1 @@
+export const ready = true

package/evals/fixtures/a6-clean/src/pages/handled.ts

@@ -0,0 +1,8 @@
+export function load(): string {
+  try {
+    return read()
+  } catch (error) {
+    report(error)
+    return ''
+  }
+}

package/evals/fixtures/a6-empty-catch/src/pages/empty.ts

@@ -0,0 +1,3 @@
+try {
+  run()
+} catch {}

package/evals/fixtures/ignore-active/codecraft.config.json

@@ -0,0 +1,5 @@
+{
+  "ignore": [
+    { "rule": "A17", "file": "src/pages/**", "reason": "eval fixture", "expires": "2099-12-31" }
+  ]
+}

package/evals/fixtures/ignore-active/src/pages/home.ts

@@ -0,0 +1 @@
+import { User } from '@/external/user'

package/evals/fixtures/ignore-expired/codecraft.config.json

@@ -0,0 +1,5 @@
+{
+  "ignore": [
+    { "rule": "A17", "file": "src/pages/**", "reason": "eval fixture", "expires": "2000-01-01" }
+  ]
+}

package/evals/fixtures/ignore-expired/src/pages/home.ts

@@ -0,0 +1 @@
+import { User } from '@/external/user'

package/evals/fixtures/library-a11/dist/tokens.css

@@ -0,0 +1,3 @@
+:root {
+  --color-text: #000;
+}

package/evals/fixtures/library-a11/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "eval-library-a11",
+  "version": "0.0.0"
+}

package/evals/fixtures/library-a11/src/index.ts

@@ -0,0 +1 @@
+export const value = 1

package/evals/fixtures/zero-files/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "eval-zero-files",
+  "version": "0.0.0"
+}

package/evals/golden-tasks.md

@@ -85,7 +85,7 @@
 
 - 输入：一个单团队、单产品的多页应用，后端契约未知。
 - 模式：Plan（只读）。
-- 期望：先定档位 L0/L1；列变化轴；切边界并给依赖规则；两张图（Context / Container）；ADR 只记难逆转项；不改文件。
+- 期望：先定档位 L0/L1；列变化轴；切边界并给依赖规则；Context / Container 用表格描述（本阶段不要求画图）；ADR 只记难逆转项；不改文件。
 - 失败信号：直接上微服务 / 微前端；只画图不给依赖规则；没有退出条件。
 
 ## 13. 架构评审
@@ -114,6 +114,19 @@
 - 安装由 `skills` CLI 负责：`npx skills add ultime-space/skills --skill codecraft`。
 - 不在 Codecraft 规则评估范围内；本文件不再评估安装器行为。
 
+## 17. 审计结论一致性
+
+- 输入：一个项目同时存在「多处 `code === 200`」「生成物无再生成 diff」「CLI `0 findings`」。
+- 期望：A4 判 `warn`；A11 判 `warn`；报告写明 `0 findings` 只是静态未命中；计数带检索命令。
+- 失败信号：A4 / A11 判 `pass`；把静态检查当全通过；结论没有文件行号或命令。
+
+## 18. 代码架构分析报告
+
+- 输入：一个三端项目（client / admin / server），已有 README 与部分 `rules/`。
+- 模式：Audit（只读）。
+- 期望：按 `templates/architecture-report.md` 出文档；结构 / 依赖 / 关键链路 / A1–A21 / 风险 / 演进 / 未知项齐全；每条有证据；明确写「不含业务架构」「本阶段不画图」；不改文件。
+- 失败信号：写成业务能力 / 角色 / 业务流程；没有证据；只给结论；用图代替结构表；改文件。
+
 ## 评分
 
 - 每条任务：pass / fail。

package/evals/run.mjs

@@ -0,0 +1,75 @@
+import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const BIN = fileURLToPath(new URL('../bin/codecraft.mjs', import.meta.url))
+const CASES = JSON.parse(fs.readFileSync(new URL('./cases.json', import.meta.url), 'utf8'))
+
+let failed = 0
+
+for (const testCase of CASES) {
+  const root = fileURLToPath(new URL(`./fixtures/${testCase.root}/`, import.meta.url))
+  const args = ['check', '--root', root, ...(testCase.args ?? [])]
+  const result = spawnSync(process.execPath, [BIN, ...args], { encoding: 'utf8' })
+  const problems = []
+
+  if (result.status !== testCase.expect.exit) {
+    problems.push(`exit ${result.status}, expected ${testCase.expect.exit}`)
+  }
+
+  if (testCase.expect.sarif) {
+    try {
+      const report = JSON.parse(result.stdout)
+      if (report.version !== testCase.expect.sarif.version) {
+        problems.push(`sarif version ${report.version}, expected ${testCase.expect.sarif.version}`)
+      }
+      if (report.runs?.[0]?.results?.[0]?.ruleId !== testCase.expect.sarif.rule) {
+        problems.push(`sarif result ${report.runs?.[0]?.results?.[0]?.ruleId}, expected ${testCase.expect.sarif.rule}`)
+      }
+    } catch (error) {
+      problems.push(`invalid sarif: ${error.message}`)
+    }
+  } else {
+    let report
+    try {
+      report = JSON.parse(result.stdout)
+    } catch (error) {
+      problems.push(`invalid json: ${error.message}`)
+    }
+    if (report) {
+      const expected = testCase.expect.findings ?? {}
+      const total = Object.values(expected).reduce((sum, count) => sum + count, 0)
+      if (report.findings.length !== total) {
+        problems.push(`findings ${report.findings.length}, expected ${total}`)
+      }
+      const counts = {}
+      for (const finding of report.findings) counts[finding.rule] = (counts[finding.rule] ?? 0) + 1
+      for (const [rule, count] of Object.entries(expected)) {
+        if ((counts[rule] ?? 0) !== count) problems.push(`${rule} ${counts[rule] ?? 0}, expected ${count}`)
+      }
+      for (const key of ['ignored', 'expired']) {
+        const actual = Array.isArray(report[key]) ? report[key].length : report[key]
+        if (testCase.expect[key] != null && actual !== testCase.expect[key]) {
+          problems.push(`${key} ${actual}, expected ${testCase.expect[key]}`)
+        }
+      }
+      if (testCase.expect.warnings != null && report.warnings?.length !== testCase.expect.warnings) {
+        problems.push(`warnings ${report.warnings?.length ?? 0}, expected ${testCase.expect.warnings}`)
+      }
+    }
+  }
+
+  if (problems.length) {
+    failed += 1
+    console.error(`✗ ${testCase.name}: ${problems.join('; ')}`)
+    if (result.stderr.trim()) console.error(result.stderr.trim().split('\n').slice(0, 4).join('\n'))
+  } else {
+    console.log(`✓ ${testCase.name}`)
+  }
+}
+
+if (failed) {
+  console.error(`\n${failed}/${CASES.length} eval cases failed`)
+  process.exit(1)
+}
+console.log(`\n${CASES.length}/${CASES.length} eval cases passed`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",
@@ -50,7 +50,9 @@
   "type": "module",
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "prepublishOnly": "npm test"
+    "eval": "node evals/run.mjs",
+    "self-check": "node bin/codecraft.mjs check --root . --pack design-system --exclude \"evals/fixtures/**\" --ci",
+    "prepublishOnly": "npm test && npm run self-check"
   },
   "engines": {
     "node": ">=20"

package/prompts/output.md

@@ -1,13 +1,19 @@
 # Output Format（输出格式）
 
-默认 Markdown；JSON 仅用于 CLI / CI。
+默认 Markdown；JSON 仅用于 CLI / CI。Audit 还必须满足 `docs/08-audit-contract.md`。
 
 ## Markdown
 
 ```md
 ## 结论
 
-## 证据
+## 范围与方法
+
+## 逐条判定（A1–A21）
+
+| ID | 判定 | 证据 | 局限 |
+|---|---|---|---|
+| A1 | pass | `src/pages/home/index.vue:1` | 仅抽样 |
 
 ## 差距 / 风险
 
@@ -18,10 +24,19 @@
 ## 下一步
 ```
 
-规则：
+## 架构报告
+
+代码架构分析报告按 [`../templates/architecture-report.md`](../templates/architecture-report.md) 输出；默认不画图，用表格 / 列表表达结构；证据、局限与 `0 findings` 口径同 Audit。
+
+## 规则
 
-- 每条结论引用 A-ID 或文件路径。
+- A1–A21 全部出现；不适用写 `na` 并说明原因。
+- 每条结论引用 A-ID，并给文件行号或可复现命令；计数必须带检索式。
+- `pass` 必须有证据；只有静态检查通过时写 `pass（静态）`，不能替代人工抽样。
+- `codecraft check` 的 0 findings 只能写「静态检查未命中」；同时写明 A17 / A21 的覆盖盲区。
+- 出结论前做一致性检查：A4 / A8 / A11 / A17 / A21 与证据矛盾时必须降级。
 - 不写敏感信息；示例用占位符。
 - 英文术语首次出现用 `English（中文）`。
 - 不把“计划”写成“已完成”。
 - Audit / Plan 模式只输出报告，不改文件。
+- 计划每阶段可回滚，验收用命令或检索结果，不写时间估算。