@peterxiaoyang/superspec 0.1.37 → 0.1.39

package/dist/task.js

@@ -1,7 +1,7 @@
 // SuperSpec 流程引擎 — task：测试运行记录 + 任务结构指纹工具
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock, appendRawRecord } from "./store.js";
+import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock, appendRawRecord, readEvents } from "./store.js";
 import { tasksStructureDigest as formatDigest } from "./format.js";
 /** tasks.md 结构指纹（委托给 format.ts 统一实现） */
 export function tasksStructureDigestOf(changeRoot) {
@@ -19,30 +19,44 @@ function recordTestRunLoaded(projectRoot, change, content) {
     catch {
         return { accepted: false, message: "无效 JSON" };
     }
-    if (!tr.test_id || !tr.task_structure_digest) {
-        return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
+    const events = readEvents(projectRoot, change);
+    const attemptRecord = typeof tr.attempt_id === "string" ? attemptById(events, tr.attempt_id) : null;
+    const activeAttempt = attemptRecord?.state === "active" ? attemptRecord.attempt : null;
+    if (attemptRecord?.attempt.contract_mode === true && attemptRecord.state !== "active") {
+        return { accepted: false, message: "契约测试证据只能登记到当前活跃任务尝试（attempt_id）" };
+    }
+    if (!activeAttempt && activeContractAttemptExists(events)) {
+        return { accepted: false, message: "契约测试证据必须带当前活跃任务尝试 ID（attempt_id）" };
+    }
+    if (activeAttempt?.contract_mode === true) {
+        const contractCheck = validateContractTestRunInput(tr, activeAttempt);
+        if (!contractCheck.ok)
+            return { accepted: false, message: contractCheck.message };
+    }
+    else if (!tr.test_id || !tr.task_structure_digest) {
+        return { accepted: false, message: "缺少测试 ID（test_id）或历史任务结构指纹（task_structure_digest）" };
     }
     let coversTaskIds;
     if (tr.covers_task_ids !== undefined) {
         if (!Array.isArray(tr.covers_task_ids)) {
-            return { accepted: false, message: "covers_task_ids 必须是字符串数组" };
+            return { accepted: false, message: "回归覆盖任务列表（covers_task_ids）必须是字符串数组" };
         }
         if (tr.covers_task_ids.length === 0) {
-            return { accepted: false, message: "covers_task_ids 不能是空数组" };
+            return { accepted: false, message: "回归覆盖任务列表（covers_task_ids）不能是空数组" };
         }
         for (const raw of tr.covers_task_ids) {
             if (typeof raw !== "string")
-                return { accepted: false, message: "covers_task_ids 必须是字符串数组" };
+                return { accepted: false, message: "回归覆盖任务列表（covers_task_ids）必须是字符串数组" };
             const value = raw.trim();
             if (!value)
-                return { accepted: false, message: "covers_task_ids 不能包含空字符串" };
+                return { accepted: false, message: "回归覆盖任务列表（covers_task_ids）不能包含空字符串" };
             (coversTaskIds ??= []).push(value);
         }
         coversTaskIds = [...new Set(coversTaskIds)].sort();
     }
     const normalizedTestRun = {
         test_id: tr.test_id,
-        task_structure_digest: tr.task_structure_digest,
+        task_structure_digest: tr.task_structure_digest ?? activeAttempt?.task_structure_digest ?? "",
         attempt_id: tr.attempt_id ?? null,
         ...(coversTaskIds ? { covers_task_ids: coversTaskIds } : {}),
         command: tr.command ?? "",
@@ -58,7 +72,71 @@ function recordTestRunLoaded(projectRoot, change, content) {
         ...rawRef,
     });
     appendEvent(projectRoot, change, event);
-    return { accepted: true, message: `测试运行已登记：test_id=${tr.test_id}` };
+    return { accepted: true, message: `测试运行已登记：测试 ID（test_id）=${tr.test_id}` };
+}
+function attemptById(events, attemptId) {
+    const attempts = new Map();
+    for (const ev of events) {
+        if (ev.event_type === "task_started") {
+            const attempt = ev.payload;
+            if (typeof attempt.attempt_id === "string")
+                attempts.set(attempt.attempt_id, { attempt, state: "active" });
+        }
+        else if (ev.event_type === "task_completed") {
+            const payload = ev.payload;
+            const existing = typeof payload.attempt_id === "string" ? attempts.get(payload.attempt_id) : null;
+            if (existing)
+                existing.state = "completed";
+        }
+        else if (ev.event_type === "task_abandoned") {
+            const payload = ev.payload;
+            const existing = typeof payload.attempt_id === "string" ? attempts.get(payload.attempt_id) : null;
+            if (existing)
+                existing.state = "abandoned";
+        }
+    }
+    return attempts.get(attemptId) ?? null;
+}
+function activeContractAttemptExists(events) {
+    const attempts = new Map();
+    for (const ev of events) {
+        if (ev.event_type === "task_started") {
+            const attempt = ev.payload;
+            if (typeof attempt.attempt_id === "string")
+                attempts.set(attempt.attempt_id, attempt);
+        }
+        else if (ev.event_type === "task_completed" || ev.event_type === "task_abandoned") {
+            const payload = ev.payload;
+            if (typeof payload.attempt_id === "string")
+                attempts.delete(payload.attempt_id);
+        }
+    }
+    return [...attempts.values()].some(attempt => attempt.contract_mode === true);
+}
+function validateContractTestRunInput(tr, attempt) {
+    if (!tr.test_id || !tr.command || !tr.cwd || typeof tr.exit_code !== "number" || !tr.semantic_status) {
+        return { ok: false, message: "契约测试证据缺少测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）或语义状态（semantic_status）" };
+    }
+    if (typeof tr.attempt_id !== "string" || tr.attempt_id !== attempt.attempt_id) {
+        return { ok: false, message: "契约测试证据必须带当前活跃任务尝试 ID（attempt_id）" };
+    }
+    if (!["expected_failure", "expected_success", "characterization_pass"].includes(tr.semantic_status)) {
+        return { ok: false, message: "语义状态（semantic_status）必须是 expected_failure、expected_success 或 characterization_pass" };
+    }
+    if (tr.semantic_status === "expected_failure" && tr.exit_code === 0) {
+        return { ok: false, message: "RED 预期失败（expected_failure）要求退出码（exit_code）非 0" };
+    }
+    if ((tr.semantic_status === "expected_success" || tr.semantic_status === "characterization_pass") && tr.exit_code !== 0) {
+        return { ok: false, message: `语义状态（semantic_status=${tr.semantic_status}）要求退出码（exit_code）为 0` };
+    }
+    if (tr.semantic_status === "characterization_pass" && !(attempt.tdd_required === false && attempt.no_tdd_reason === "characterization")) {
+        return { ok: false, message: "特征化通过（characterization_pass）只适用于无需 TDD 的特征化任务（tdd_required:false，no_tdd_reason:characterization）" };
+    }
+    const declaredTests = attempt.contract?.tests ?? [];
+    if (declaredTests.length > 0 && !declaredTests.includes(tr.test_id)) {
+        return { ok: false, message: `测试 ID（test_id=${tr.test_id}）不属于当前任务契约声明的测试列表` };
+    }
+    return { ok: true };
 }
 /** record test-run：登记测试运行记录 */
 export function recordTestRun(projectRoot, change, inputFile) {

package/dist/task_evidence.d.ts

@@ -0,0 +1,10 @@
+import type { TaskAttempt } from "./types.ts";
+export type TaskEvidenceReadiness = {
+    ready: true;
+    missing: [];
+} | {
+    ready: false;
+    missing: string[];
+    reason: string;
+};
+export declare function taskEvidenceReadiness(projectRoot: string, change: string, changeRoot: string, attempt: TaskAttempt): TaskEvidenceReadiness;

package/dist/task_evidence.js

@@ -0,0 +1,126 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseTasksMd } from "./format.js";
+import { readEvents, sha256Text } from "./store.js";
+export function taskEvidenceReadiness(projectRoot, change, changeRoot, attempt) {
+    if (attempt.contract_mode === true) {
+        return contractTaskEvidenceReadiness(projectRoot, change, attempt);
+    }
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    const tasks = parseTasksMd(tasksContent);
+    const taskInfo = tasks.find(task => task.taskId === attempt.task_id);
+    const missing = [];
+    if (!taskInfo) {
+        missing.push(`任务 ${attempt.task_id} 不存在`);
+        return { ready: false, missing, reason: missing.join("、") };
+    }
+    const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
+    if (currentDigest !== attempt.task_structure_digest)
+        missing.push("任务结构指纹");
+    if (!taskInfo.tddRequired) {
+        if (!taskInfo.noTddReason)
+            missing.push("no_tdd_reason");
+        return missing.length === 0
+            ? { ready: true, missing: [] }
+            : { ready: false, missing, reason: missing.join("、") };
+    }
+    let hasRed = false;
+    let hasGreen = false;
+    for (const ev of readEvents(projectRoot, change)) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const tr = ev.payload;
+        const matches = tr.attempt_id === attempt.attempt_id ||
+            (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
+        if (!matches)
+            continue;
+        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
+            hasRed = true;
+        if (tr.semantic_status === "expected_success")
+            hasGreen = true;
+    }
+    if (!hasRed)
+        missing.push("RED 证据");
+    if (!hasGreen)
+        missing.push("GREEN 证据");
+    return missing.length === 0
+        ? { ready: true, missing: [] }
+        : { ready: false, missing, reason: missing.join("、") };
+}
+function contractTaskEvidenceReadiness(projectRoot, change, attempt) {
+    const missing = [];
+    const tddRequired = attempt.tdd_required !== false;
+    const characterization = attempt.tdd_required === false && attempt.no_tdd_reason === "characterization";
+    const declaredTests = attempt.contract?.tests ?? [];
+    if (!tddRequired && !attempt.no_tdd_reason) {
+        missing.push("no_tdd_reason");
+    }
+    if (declaredTests.length === 0) {
+        if (tddRequired) {
+            const hasAttemptEvidence = attemptLevelRedGreenEvidence(projectRoot, change, attempt.attempt_id);
+            if (!hasAttemptEvidence.hasRed)
+                missing.push("RED 证据");
+            if (!hasAttemptEvidence.hasGreen)
+                missing.push("GREEN 证据");
+        }
+        return missing.length === 0
+            ? { ready: true, missing: [] }
+            : { ready: false, missing, reason: missing.join("、") };
+    }
+    const perTest = new Map();
+    for (const testId of declaredTests) {
+        perTest.set(testId, { sawRed: false, sawGreen: false, paired: false });
+    }
+    for (const ev of readEvents(projectRoot, change)) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const tr = ev.payload;
+        if (tr.attempt_id !== attempt.attempt_id)
+            continue;
+        if (typeof tr.test_id !== "string")
+            continue;
+        const state = perTest.get(tr.test_id);
+        if (!state)
+            continue;
+        if (tr.semantic_status === "expected_failure" && typeof tr.exit_code === "number" && tr.exit_code !== 0) {
+            state.sawRed = true;
+        }
+        const isExpectedSuccess = tr.semantic_status === "expected_success" && tr.exit_code === 0;
+        const isCharacterizationPass = characterization && tr.semantic_status === "characterization_pass" && tr.exit_code === 0;
+        if (isExpectedSuccess || isCharacterizationPass) {
+            if (state.sawRed)
+                state.paired = true;
+            state.sawGreen = true;
+        }
+    }
+    for (const [testId, state] of perTest) {
+        if (!state.sawGreen)
+            missing.push(`${testId} GREEN 证据`);
+    }
+    if (tddRequired) {
+        const hasPairedTest = [...perTest.values()].some(state => state.paired);
+        if (!hasPairedTest)
+            missing.push("同一 TEST 的 RED/GREEN 配对");
+    }
+    return missing.length === 0
+        ? { ready: true, missing: [] }
+        : { ready: false, missing, reason: missing.join("、") };
+}
+function attemptLevelRedGreenEvidence(projectRoot, change, attemptId) {
+    let hasRed = false;
+    let hasGreen = false;
+    for (const ev of readEvents(projectRoot, change)) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const tr = ev.payload;
+        if (tr.attempt_id !== attemptId)
+            continue;
+        if (tr.semantic_status === "expected_failure" && typeof tr.exit_code === "number" && tr.exit_code !== 0) {
+            hasRed = true;
+        }
+        if (tr.semantic_status === "expected_success" && tr.exit_code === 0) {
+            hasGreen = true;
+        }
+    }
+    return { hasRed, hasGreen };
+}

package/dist/transition.d.ts

@@ -43,5 +43,5 @@ export declare function reopen(projectRoot: string, change: string, changeRoot:
 export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function accept(projectRoot: string, change: string, changeRoot: string): TransitionResult;
 export declare function archive(projectRoot: string, change: string, changeRoot: string): TransitionResult;
-export declare function taskComplete(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
+export declare function taskComplete(projectRoot: string, change: string, changeRoot: string, taskId: string, inputContent?: string | null): TransitionResult;
 export {};