@cyning/harness 2.9.0 → 2.10.0

package/lib/discipline-coverage.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { resolveHarnessRoot } from './paths.js';
+
+const STATUSES = new Set(['mechanical', 'partial', 'prompt-only']);
+const GAP_STATUSES = new Set(['open', 'closed', 'deferred']);
+
+/**
+ * 轻量结构校验（对齐 schema/discipline-coverage.v1.schema.json 必填约束）。
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateDisciplineCoverage(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    return { ok: false, errors: ['根须为 object'] };
+  }
+  if (typeof data.version !== 'string' || !data.version.trim()) {
+    errors.push('缺 version');
+  }
+  if (typeof data.as_of_package_version !== 'string' || !data.as_of_package_version.trim()) {
+    errors.push('缺 as_of_package_version');
+  }
+  if (typeof data.scope !== 'string' || !data.scope.trim()) {
+    errors.push('缺 scope');
+  }
+  if (!Array.isArray(data.statements) || data.statements.length === 0) {
+    errors.push('缺 statements[] 或为空');
+  } else {
+    data.statements.forEach((s, i) => {
+      if (!s || typeof s.id !== 'string' || !s.id.trim()) {
+        errors.push(`statements[${i}] 缺 id`);
+      }
+      if (!s || typeof s.source !== 'string') {
+        errors.push(`statements[${i}] 缺 source`);
+      }
+      if (!s || typeof s.summary !== 'string') {
+        errors.push(`statements[${i}] 缺 summary`);
+      }
+      if (!s || !STATUSES.has(s.status)) {
+        errors.push(`statements[${i}] status 非法: ${s?.status}`);
+      }
+    });
+  }
+  if (data.gaps != null) {
+    if (!Array.isArray(data.gaps)) {
+      errors.push('gaps 须为 array');
+    } else {
+      data.gaps.forEach((g, i) => {
+        if (!g || typeof g.id !== 'string') errors.push(`gaps[${i}] 缺 id`);
+        if (!g || typeof g.title !== 'string') errors.push(`gaps[${i}] 缺 title`);
+        if (!g || !GAP_STATUSES.has(g.status)) {
+          errors.push(`gaps[${i}] status 非法: ${g?.status}`);
+        }
+      });
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * 加载并校验 harness/discipline-coverage.yaml。
+ */
+export function loadDisciplineCoverage(options = {}) {
+  const harnessRoot = options.harnessRoot ?? resolveHarnessRoot();
+  const filePath =
+    options.filePath ??
+    path.join(harnessRoot, 'harness', 'discipline-coverage.yaml');
+
+  if (!fs.existsSync(filePath)) {
+    const e = new Error(`discipline-coverage.yaml 不存在: ${filePath}`);
+    e.exitCode = 1;
+    throw e;
+  }
+
+  let data;
+  try {
+    data = yaml.load(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    const e = new Error(`discipline-coverage.yaml 解析失败: ${err.message}`);
+    e.exitCode = 1;
+    throw e;
+  }
+
+  const v = validateDisciplineCoverage(data);
+  if (!v.ok) {
+    const e = new Error(
+      `discipline-coverage.yaml 校验失败:\n  - ${v.errors.join('\n  - ')}`,
+    );
+    e.exitCode = 1;
+    e.validationErrors = v.errors;
+    throw e;
+  }
+
+  return { data, filePath, harnessRoot };
+}

package/lib/lifecycle.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
 import { resolveHarnessRoot } from './paths.js';
+import { findReview, parseHumanGates } from './task-meta.js';
 
 const SEVERITIES = new Set(['block', 'warn']);
 
@@ -119,3 +120,224 @@ export function formatLifecycleShow(data) {
   }
   return lines.join('\n').trimEnd();
 }
+
+/** 本波已接线的守卫（其余 unevaluated） */
+const GUARD_ADAPTERS = {
+  'HG-AUDIT-R1': evaluateHgAuditR1,
+  reviews_retention: evaluateReviewsRetention,
+};
+
+function findRepoRootFromTask(absTask) {
+  let cur = path.dirname(absTask);
+  while (true) {
+    if (path.basename(cur) === 'docs') return path.dirname(cur);
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+function flagsAllow(flags, allowFlag) {
+  if (allowFlag === '--allow-no-review') return Boolean(flags.allowNoReview);
+  if (allowFlag === '--allow-lint-fail') return Boolean(flags.allowLintFail);
+  if (allowFlag === '--allow-no-spec-review') return Boolean(flags.allowNoSpecReview);
+  return false;
+}
+
+function evaluateHgAuditR1({ taskPath }) {
+  const content = fs.readFileSync(taskPath, 'utf8');
+  const gates = parseHumanGates(content);
+  const audit = gates.find((g) => g.id === 'HG-AUDIT-R1');
+  if (!audit) {
+    return { status: 'fail', detail: '闸表无 HG-AUDIT-R1 行' };
+  }
+  if (audit.status === 'approved') {
+    return { status: 'pass', detail: 'HG-AUDIT-R1=approved' };
+  }
+  return {
+    status: 'fail',
+    detail: `HG-AUDIT-R1=${audit.status}（须 approved）`,
+  };
+}
+
+function evaluateReviewsRetention({ taskPath, target, flags }) {
+  const review = findReview(target, taskPath);
+  if (review.found) {
+    return { status: 'pass', detail: review.latest };
+  }
+  if (flags.allowNoReview) {
+    return {
+      status: 'warn',
+      detail: 'missing R<n> review（--allow-no-review）',
+    };
+  }
+  return { status: 'fail', detail: 'missing R<n> review' };
+}
+
+/**
+ * 转移 dry-run（引擎最小骨架 · v2.10+）。
+ * 默认不写盘；无 --apply。
+ *
+ * @param {{
+ *   transitionId: string,
+ *   fromState: string,
+ *   taskPath?: string,
+ *   harnessRoot?: string,
+ *   flags?: { allowNoReview?: boolean, allowLintFail?: boolean, allowNoSpecReview?: boolean },
+ *   cwd?: string,
+ * }} options
+ */
+export function dryRunTransition(options = {}) {
+  const {
+    transitionId,
+    fromState,
+    taskPath,
+    harnessRoot,
+    flags = {},
+    cwd = process.cwd(),
+  } = options;
+
+  const { data } = loadLifecycle({ harnessRoot });
+  const knownIds = data.transitions.map((t) => t.id);
+  const transition = data.transitions.find((t) => t.id === transitionId);
+
+  if (!transition) {
+    return {
+      engine: 'lifecycle-dry-run',
+      lifecycle_doc_version: data.version,
+      transition_id: transitionId ?? null,
+      from: fromState ?? null,
+      to: null,
+      hat: null,
+      structure_ok: false,
+      guards: [],
+      blocked: true,
+      unevaluated_count: 0,
+      detail: `未知 transition: ${transitionId}（已知: ${knownIds.join(', ')}）`,
+      exitCode: 2,
+    };
+  }
+
+  if (!fromState || !transition.from.includes(fromState)) {
+    return {
+      engine: 'lifecycle-dry-run',
+      lifecycle_doc_version: data.version,
+      transition_id: transition.id,
+      from: fromState ?? null,
+      to: transition.to,
+      hat: transition.hat ?? null,
+      structure_ok: false,
+      guards: [],
+      blocked: true,
+      unevaluated_count: 0,
+      detail: `from "${fromState}" ∉ ${JSON.stringify(transition.from)}`,
+      exitCode: 2,
+    };
+  }
+
+  const absTask = taskPath
+    ? path.isAbsolute(taskPath)
+      ? taskPath
+      : path.resolve(cwd, taskPath)
+    : null;
+
+  if (taskPath && absTask && !fs.existsSync(absTask)) {
+    const e = new Error(`--task 不可读: ${taskPath}`);
+    e.exitCode = 1;
+    throw e;
+  }
+
+  const canEval = Boolean(absTask);
+  const target = absTask ? findRepoRootFromTask(absTask) ?? cwd : cwd;
+  const guards = [];
+
+  for (const g of transition.guards) {
+    const adapter = GUARD_ADAPTERS[g.id];
+    if (!canEval || !adapter) {
+      guards.push({
+        id: g.id,
+        severity: g.severity,
+        status: 'unevaluated',
+        detail: !canEval ? '无 --task · 未求值' : '本波未接线 adapter',
+        allow_flag: g.allow_flag ?? null,
+      });
+      continue;
+    }
+
+    const evaluated = adapter({
+      taskPath: absTask,
+      target,
+      flags,
+      guard: g,
+      cwd,
+    });
+
+    let status = evaluated.status;
+    let detail = evaluated.detail ?? null;
+
+    if (
+      status === 'fail' &&
+      g.allow_flag &&
+      flagsAllow(flags, g.allow_flag)
+    ) {
+      status = 'warn';
+      detail = `${detail ?? 'fail'}（${g.allow_flag} 豁免）`;
+    }
+
+    guards.push({
+      id: g.id,
+      severity: g.severity,
+      status,
+      detail,
+      allow_flag: g.allow_flag ?? null,
+    });
+  }
+
+  const unevaluated_count = guards.filter((g) => g.status === 'unevaluated').length;
+  const blocked = guards.some(
+    (g) => g.severity === 'block' && g.status === 'fail',
+  );
+
+  return {
+    engine: 'lifecycle-dry-run',
+    lifecycle_doc_version: data.version,
+    transition_id: transition.id,
+    from: fromState,
+    to: transition.to,
+    hat: transition.hat ?? null,
+    structure_ok: true,
+    guards,
+    blocked,
+    unevaluated_count,
+    exitCode: blocked ? 2 : 0,
+  };
+}
+
+/**
+ * 人读 dry-run 报告。
+ */
+export function formatLifecycleDryRun(report) {
+  const lines = [
+    '=== Harness lifecycle dry-run ===',
+    `engine: ${report.engine}`,
+    `lifecycle: v${report.lifecycle_doc_version}`,
+    `transition: ${report.transition_id} · ${report.from} → ${report.to}${report.hat ? ` · hat=${report.hat}` : ''}`,
+    `structure_ok: ${report.structure_ok}`,
+    `blocked: ${report.blocked}`,
+    `unevaluated_count: ${report.unevaluated_count}`,
+  ];
+  if (report.detail) lines.push(`detail: ${report.detail}`);
+  if (report.unevaluated_count > 0) {
+    lines.push('WARN: 存在未求值守卫 · unevaluated ≠ pass（勿当作已通过）');
+  }
+  lines.push('', '## guards');
+  for (const g of report.guards ?? []) {
+    const d = g.detail ? ` · ${g.detail}` : '';
+    lines.push(`- [${g.severity}] ${g.id}: ${g.status}${d}`);
+  }
+  lines.push('');
+  lines.push(
+    '注: dry-run 为旁路资格报告 · 不替代 verify / gate-check 作为 30 硬闸 · 非 G7 runner',
+  );
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",

package/schema/discipline-coverage.v1.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cyning.dev/schemas/cyning-harness/discipline-coverage.v1.json",
+  "title": "cyning-harness Discipline Coverage (mechanization matrix)",
+  "description": "Starter 子集机械化率资产 · 随包版本维护 · 非 audit UI（v2.10+）",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "as_of_package_version", "scope", "statements"],
+  "properties": {
+    "version": { "type": "string", "minLength": 1 },
+    "as_of_package_version": { "type": "string", "minLength": 1 },
+    "scope": { "type": "string", "minLength": 1 },
+    "source_audit": { "type": "string" },
+    "statements": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "source", "summary", "status"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "source": { "type": "string", "minLength": 1 },
+          "summary": { "type": "string", "minLength": 1 },
+          "status": {
+            "type": "string",
+            "enum": ["mechanical", "partial", "prompt-only"]
+          },
+          "mechanism": { "type": ["string", "null"] },
+          "gap": { "type": ["string", "null"] },
+          "notes": { "type": ["string", "null"] },
+          "mechanism_quality": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "status"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "title": { "type": "string", "minLength": 1 },
+          "status": {
+            "type": "string",
+            "enum": ["open", "closed", "deferred"]
+          },
+          "closed_in": { "type": ["string", "null"] },
+          "note": { "type": ["string", "null"] }
+        }
+      }
+    }
+  }
+}

package/schema/lifecycle.v1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://cyning.dev/schemas/cyning-harness/lifecycle.v1.json",
   "title": "cyning-harness Task Lifecycle (minimal)",
-  "description": "状态/转移/守卫登记 · 只读真值 · 非引擎（v2.7+）",
+  "description": "状态/转移/守卫登记真值 · 由 lifecycle dry-run 引擎消费（yaml ≠ 引擎 · v2.7+ 登记 · v2.10+ dry-run）",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "states", "transitions"],