dsh-card-dispatch 0.0.0-stage → 0.1.0

package/src/verdict.js

@@ -0,0 +1,133 @@
+/**
+ * verdict.js：验收结论的**文件契约**。
+ *
+ * ## 为什么是文件，不是看板状态
+ *
+ * 「打回之后谁重跑」原本看起来只能靠读看板状态，但两条路都不通：
+ *
+ * 1. 插件读不到看板：`GET /api/task-board/state` 走的是看板自己的信任栅栏，
+ *    插件进程没有那张 cookie，实测 403；
+ * 2. 就算读到了也没用：`ExecutionRecord.result` 只记「这次执行成没成」，
+ *    不记「验收判 PASS 还是 REJECT」——验收结论只活在会话记录里。
+ *
+ * 所以把结论**写进文件**：验收卡产出 `out/<根卡 id>/verdict.json`。
+ * 文件的好处是三方都能读：人、看板里的下一次执行、以及插件（人点一下时）。
+ * 这也顺带满足基线 P3——会话状态不可重建即不存在，落盘的才存在。
+ *
+ * 这个模块只做解析与判定，不读盘、不联网，所以能逐条单测。
+ */
+
+/** verdict.json 里 REJECT 的每一项必须带齐这四个字段。 */
+const ITEM_KEYS = ['criteriaId', 'expected', 'actual', 'evidencePath']
+
+/**
+ * 解析 verdict.json。
+ *
+ * 故意严格：REJECT 不给定位信息 = 开发只能瞎改，所以「缺字段」本身就是错误，
+ * 而不是一条可以忽略的警告。
+ *
+ * @param {string|object} raw 文件内容或已解析对象
+ * @returns {{ok:boolean, verdict:string|null, items:Array, problems:Array<string>, summary:string, error:string|null}}
+ */
+export function parseVerdict(raw) {
+  const empty = { ok: false, verdict: null, items: [], problems: [], summary: '', error: null }
+  let data = raw
+  if (typeof raw === 'string') {
+    const text = raw.trim()
+    if (text === '') return { ...empty, error: 'verdict.json 是空文件' }
+    try {
+      data = JSON.parse(text)
+    } catch (error) {
+      return { ...empty, error: `verdict.json 不是合法 JSON：${error.message}` }
+    }
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return { ...empty, error: 'verdict.json 的顶层必须是对象' }
+  }
+
+  const verdict = String(data.verdict ?? '').toUpperCase()
+  if (verdict !== 'PASS' && verdict !== 'REJECT') {
+    return { ...empty, error: `verdict 只能是 PASS 或 REJECT，收到 ${JSON.stringify(data.verdict)}` }
+  }
+
+  const items = Array.isArray(data.items) ? data.items : []
+  const problems = []
+  if (verdict === 'REJECT') {
+    if (items.length === 0) {
+      problems.push('REJECT 必须逐条列出 items：没有定位的「不行」等于没验收')
+    }
+    items.forEach((item, index) => {
+      const missing = ITEM_KEYS.filter((key) => String(item?.[key] ?? '').trim() === '')
+      if (missing.length > 0) problems.push(`items[${index}] 缺 ${missing.join('、')}`)
+    })
+  }
+
+  return {
+    ok: problems.length === 0,
+    verdict,
+    items,
+    problems,
+    summary: String(data.summary ?? '').trim(),
+    error: null,
+  }
+}
+
+/**
+ * 拿到 verdict 之后，下一步该干什么。
+ *
+ * 三种结局，正好对应基线的三条线：
+ *   - `pass`：验收通过 → 父卡可以收尾；
+ *   - `rework`：打回，且还没到上限 → 重跑开发卡（**这才是真正花钱的那一步**）；
+ *   - `escalate`：到上限 → 停下来交给人（基线 R3），不再让开发瞎改；
+ *   - `invalid`：verdict 本身不合格 → 让验收卡重做，不要拿它当依据。
+ *
+ * @param {object} input
+ * @param {object} input.parsed parseVerdict 的结果
+ * @param {object} input.config 归一化配置（用 gates.maxReworkRounds）
+ * @param {number} [input.rejectedCount] 这一批已经打回过的次数
+ * @returns {{action:'pass'|'rework'|'escalate'|'invalid', rejectedCount:number, message:string, items:Array}}
+ */
+export function decideNext({ parsed, config, rejectedCount = 0 } = {}) {
+  const previous = Math.max(0, Math.trunc(Number(rejectedCount) || 0))
+  if (parsed === undefined || parsed === null || parsed.error !== null || parsed.verdict === null) {
+    return {
+      action: 'invalid',
+      rejectedCount: previous,
+      message: `验收结论不可用：${parsed?.error ?? '没有读到结论'}；让验收卡重做一次，别拿它当依据`,
+      items: [],
+    }
+  }
+  if (!parsed.ok) {
+    return {
+      action: 'invalid',
+      rejectedCount: previous,
+      message: `验收结论不合格：${parsed.problems.join('；')}`,
+      items: parsed.items,
+    }
+  }
+  if (parsed.verdict === 'PASS') {
+    return { action: 'pass', rejectedCount: previous, message: '验收通过，这批可以收尾', items: [] }
+  }
+
+  const limit = config.gates.maxReworkRounds
+  const next = previous + 1
+  if (previous >= limit) {
+    return {
+      action: 'escalate',
+      rejectedCount: previous,
+      message: `这将是第 ${next} 次打回，超过上限 ${limit}：停下来交给人（基线 R3），不要再让开发改`,
+      items: parsed.items,
+    }
+  }
+  return {
+    action: 'rework',
+    rejectedCount: next,
+    message: `第 ${next} 次打回（上限 ${limit}）：把这几条带着证据退回开发`,
+    items: parsed.items,
+  }
+}
+
+/** 验收卡该把结论写到哪里（相对工作区根目录）。 */
+export function verdictPath(rootId) {
+  return `out/${rootId}/verdict.json`
+}