@longzai-intelligence-issues/ledger 0.0.1

package/src/close/verify-close.commands.ts

@@ -0,0 +1,676 @@
+/**
+ * verify-close 收口编排（两模式）
+ *
+ * 缺省=证据收口（零执行）：冻结守卫→挂起词拦截→锚点判读→阻塞全绿判定→
+ * 概要合成→green-flip 幂等回填；批量串行一案失败不阻断。
+ * --rerun=证书化真跑：判据解析→两级门禁（禁用级全量 exit 2、确认级重度
+ * exit 2）→run.lock→逐判据经 vault 执行/复用→全绿才回填。
+ */
+
+import type { LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { findPendingWord, readEvidence } from '@/close/evidence-reader.utils';
+import {
+  applyGreenFlip,
+  renderEvidenceCloseBlock,
+  renderRerunEvidenceBlock,
+} from '@/close/green-flip.commands';
+import { parseIssueDoc, scanRegistryDir } from '@/parser/registry.parser';
+import {
+  acquireRunLock,
+  computeCriterionFingerprint,
+  type Criterion,
+  runCriterionViaVault,
+} from '@/vault/vault.commands';
+
+/**
+ * 证据收口入参
+ */
+export type EvidenceCloseInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * issue 文件仓库相对路径列表
+   */
+  files: readonly string[];
+
+  /**
+   * 显式概要（批量禁用）
+   */
+  summaryOverride?: string;
+
+  /**
+   * 只呈现不落盘
+   */
+  dryRun?: boolean;
+};
+
+/**
+ * 单案收口结果
+ */
+export type CloseCaseResult = {
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 是否翻绿成功
+   */
+  ok: boolean;
+
+  /**
+   * 结果说明（失败原因 / 概要）
+   */
+  message: string;
+
+  /**
+   * 幂等标记（已绿且概要一致零变更）
+   */
+  idempotent: boolean;
+};
+
+/**
+ * 批次收口结果
+ */
+export type CloseBatchResult = {
+  /**
+   * 逐案结果
+   */
+  cases: CloseCaseResult[];
+
+  /**
+   * 成功案数
+   */
+  succeeded: number;
+
+  /**
+   * 门禁拦截标记（exit 2 语义；真跑模式未过两级门禁时为真，零执行）
+   */
+  gateBlocked: boolean;
+
+  /**
+   * 门禁拦截说明
+   */
+  gateMessage: string;
+};
+
+/**
+ * 阻塞全绿判定（blockingMustBeGreen 门禁）
+ *
+ * @param root - 仓库根绝对路径
+ * @param registryDir - 注册表目录
+ * @param blockedByNumbers - 阻塞引用编号列表
+ * @returns 未全绿编号列表（空 = 通过）
+ */
+function findUnGreenBlockers(
+  root: string,
+  registryDir: string,
+  blockedByNumbers: readonly string[],
+): string[] {
+  if (blockedByNumbers.length === 0) {
+    return [];
+  }
+
+  /**
+   * 注册表全部解析产物
+   */
+  const records = scanRegistryDir(join(root, registryDir));
+
+  return blockedByNumbers.filter((number) => {
+    /**
+     * 被阻塞 issue 解析产物
+     */
+    const blocker = records.find((record) => record.id === number);
+
+    return (
+      blocker === undefined || (blocker.status !== 'green' && blocker.status !== 'legacy-green')
+    );
+  });
+}
+
+/**
+ * 证据收口批（缺省模式，零执行）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.config - 解析后配置
+ * @param input.files - issue 文件仓库相对路径列表
+ * @param input.summaryOverride - 显式概要（批量禁用）
+ * @param input.dryRun - 只呈现不落盘
+ * @returns 批次结果
+ */
+export function evidenceCloseFlow(input: EvidenceCloseInput): CloseBatchResult {
+  /**
+   * 逐案结果收集器
+   */
+  const cases: CloseCaseResult[] = [];
+
+  for (const file of input.files) {
+    cases.push(
+      evidenceCloseCase(
+        input.root,
+        input.config,
+        file,
+        input.summaryOverride,
+        input.dryRun === true,
+      ),
+    );
+  }
+
+  return {
+    cases,
+    succeeded: cases.filter((entry) => entry.ok).length,
+    gateBlocked: false,
+    gateMessage: '',
+  };
+}
+
+/**
+ * 单案证据收口
+ *
+ * @param root - 仓库根绝对路径
+ * @param config - 解析后配置
+ * @param file - issue 文件仓库相对路径
+ * @param summaryOverride - 显式概要
+ * @param dryRun - 只呈现不落盘
+ * @returns 单案结果
+ */
+function evidenceCloseCase(
+  root: string,
+  config: LziIssuesConfig,
+  file: string,
+  summaryOverride: string | undefined,
+  dryRun: boolean,
+): CloseCaseResult {
+  /**
+   * issue 文件绝对路径
+   */
+  const filePath = join(root, file);
+
+  /**
+   * 文档全文
+   */
+  let raw = '';
+
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return { file, ok: false, message: '读档失败（文件不存在或不可读）', idempotent: false };
+  }
+
+  /**
+   * 解析产物
+   */
+  const record = parseIssueDoc(file.split('/').pop() ?? '', raw, 0);
+
+  if (record === null) {
+    return { file, ok: false, message: '文件名不符合注册表口径', idempotent: false };
+  }
+
+  /**
+   * 冻结守卫
+   */
+  if (record.status === 'frozen') {
+    return {
+      file,
+      ok: false,
+      message: '冻结案拒收（不翻绿、不回填证据——须先经 unfreeze 裁定）',
+      idempotent: false,
+    };
+  }
+
+  /**
+   * 挂起词拦截
+   */
+  const pendingWord = findPendingWord(record.statusLine, config.close.pendingWords);
+
+  if (pendingWord !== null) {
+    return {
+      file,
+      ok: false,
+      message: `状态行含挂起词「${pendingWord}」——诚实黄灯维持，不得收口`,
+      idempotent: false,
+    };
+  }
+
+  /**
+   * 阻塞全绿判定
+   */
+  if (config.close.blockingMustBeGreen) {
+    /**
+     * 注册表目录（文件路径首段）
+     */
+    const registryDir = file.split('/').slice(0, -1).join('/');
+
+    /**
+     * 未全绿阻塞列表
+     */
+    const unGreen = findUnGreenBlockers(
+      root,
+      registryDir,
+      record.blockedByRefs.map((ref) => ref.number),
+    );
+
+    if (unGreen.length > 0) {
+      return {
+        file,
+        ok: false,
+        message: `「阻塞」引用未全 🟢：${unGreen.join('、')}——阻塞收口门禁拒收`,
+        idempotent: false,
+      };
+    }
+  }
+
+  /**
+   * 锚点判读
+   */
+  const evidence = readEvidence(raw);
+
+  if (evidence.anchors.length === 0) {
+    return {
+      file,
+      ok: false,
+      message: '处置段围栏外零绿证据锚点——不核验即翻绿红线维持（补证据或走 --rerun 真跑）',
+      idempotent: false,
+    };
+  }
+
+  /**
+   * 概要合成（--summary > criteria.summary > 自动）
+   */
+  const summary =
+    summaryOverride ??
+    record.criteria?.summary ??
+    `末次通过证据收口（${record.id}）：${evidence.anchors.length} 条绿证据锚点`;
+
+  /**
+   * 证据锚点块
+   */
+  const evidenceBlock = renderEvidenceCloseBlock(
+    evidence.anchors.map((anchor) => anchor.line),
+    '末次通过即收口',
+  );
+
+  /**
+   * 翻绿回填
+   */
+  let flip;
+
+  try {
+    flip = applyGreenFlip({ raw, summary, evidenceBlock });
+  } catch (error) {
+    return {
+      file,
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+      idempotent: false,
+    };
+  }
+
+  if (!dryRun && !flip.idempotent) {
+    writeFileSync(filePath, flip.content);
+  }
+
+  return {
+    file,
+    ok: true,
+    message: flip.idempotent
+      ? '已 🟢 且概要一致——幂等零变更'
+      : `翻绿完成（${evidence.anchors.length} 条锚点，零执行）`,
+    idempotent: flip.idempotent,
+  };
+}
+
+/**
+ * 两级门禁判定结果
+ */
+export type CloseGateResult = {
+  /**
+   * 是否拦截
+   */
+  blocked: boolean;
+
+  /**
+   * 拦截级（full 禁用级 / heavy 确认级 / none 通过）
+   */
+  kind: 'full' | 'heavy' | 'none';
+
+  /**
+   * 拦截说明
+   */
+  message: string;
+};
+
+/**
+ * 真跑两级门禁判定
+ *
+ * @param config - 解析后配置
+ * @param criteria - 判据列表
+ * @param allowFullCriterion - --allow-full-criterion 豁免
+ * @param confirmHeavy - --confirm-heavy 确认
+ * @returns 拦截结果（blocked=false 通过）
+ */
+export function resolveCloseGates(
+  config: LziIssuesConfig,
+  criteria: readonly Criterion[],
+  allowFullCriterion: boolean,
+  confirmHeavy: boolean,
+): CloseGateResult {
+  /**
+   * 禁用级：全量判据（fullPattern 命中）
+   */
+  if (!allowFullCriterion && config.close.fullPattern !== undefined) {
+    /**
+     * 全量命中判据列表
+     */
+    const fullHits = criteria.filter((criterion) =>
+      new RegExp(config.close.fullPattern ?? '').test(criterion.command),
+    );
+
+    if (fullHits.length > 0) {
+      return {
+        blocked: true,
+        kind: 'full',
+        message: `禁用级门禁：判据须 scope 定向，禁止全量（命中 ${fullHits.length} 条：${fullHits.map((c) => c.label).join('、')}）——确需全量须 --allow-full-criterion 且留痕`,
+      };
+    }
+  }
+
+  /**
+   * 确认级：重度命令（heavyPattern 命中）
+   */
+  if (!confirmHeavy && config.close.heavyPattern !== undefined) {
+    /**
+     * 重度命中判据列表
+     */
+    const heavyHits = criteria.filter((criterion) =>
+      new RegExp(config.close.heavyPattern ?? '').test(criterion.command),
+    );
+
+    if (heavyHits.length > 0) {
+      return {
+        blocked: true,
+        kind: 'heavy',
+        message: `确认级门禁：判据含重度命令（命中 ${heavyHits.length} 条：${heavyHits.map((c) => c.label).join('、')}）——预览未执行，确认执行须 --confirm-heavy（仅人类明令环节）`,
+      };
+    }
+  }
+
+  return { blocked: false, kind: 'none', message: '' };
+}
+
+/**
+ * 证书化真跑入参
+ */
+export type RerunCloseInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * issue 文件仓库相对路径列表
+   */
+  files: readonly string[];
+
+  /**
+   * 显式判据（四段字符串列表，公共判据垫后）
+   */
+  explicitCriteria?: readonly string[];
+
+  /**
+   * 从各案 criteria 块取判据
+   */
+  criteriaFromIssue?: boolean;
+
+  /**
+   * 显式概要（批量禁用）
+   */
+  summaryOverride?: string;
+
+  /**
+   * 只呈现不执行不落盘
+   */
+  dryRun?: boolean;
+
+  /**
+   * 全量判据豁免（须留痕）
+   */
+  allowFullCriterion?: boolean;
+
+  /**
+   * 重度命令确认（仅人类明令）
+   */
+  confirmHeavy?: boolean;
+};
+
+/**
+ * 证书化真跑批（--rerun）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.config - 解析后配置
+ * @param input.files - issue 文件仓库相对路径列表
+ * @param input.explicitCriteria - 显式判据（四段字符串列表，公共判据垫后）
+ * @param input.criteriaFromIssue - 从各案 criteria 块取判据
+ * @param input.summaryOverride - 显式概要（批量禁用）
+ * @param input.dryRun - 只呈现不执行不落盘（门禁拦截外的干跑）
+ * @param input.allowFullCriterion - 全量豁免
+ * @param input.confirmHeavy - 重度确认
+ * @returns 批次结果（gateBlocked=true 时零执行，exit 2 语义）
+ */
+export function rerunCloseFlow(input: RerunCloseInput): CloseBatchResult {
+  /**
+   * 逐案判据计划
+   */
+  const plans: Array<{ file: string; raw: string; criteria: Criterion[] }> = [];
+
+  for (const file of input.files) {
+    /**
+     * 文档全文
+     */
+    let raw = '';
+
+    try {
+      raw = readFileSync(join(input.root, file), 'utf8');
+    } catch {
+      continue;
+    }
+
+    /**
+     * 解析产物
+     */
+    const record = parseIssueDoc(file.split('/').pop() ?? '', raw, 0);
+
+    if (record === null || record.status === 'frozen') {
+      continue;
+    }
+
+    /**
+     * 本案判据集（块内在前 + 显式垫后）
+     */
+    const criteria: Criterion[] = [];
+
+    if (input.criteriaFromIssue === true && record.criteria !== null) {
+      criteria.push(...record.criteria.criteria);
+    }
+
+    for (const line of input.explicitCriteria ?? []) {
+      /**
+       * 四段切分
+       */
+      const segments = line.split('|');
+
+      if (segments.length === 4) {
+        criteria.push({
+          label: segments[0]?.trim() ?? '',
+          channel: segments[1]?.trim() ?? '',
+          cwd: segments[2]?.trim() ?? '',
+          command: segments[3]?.trim() ?? '',
+        });
+      }
+    }
+
+    if (criteria.length === 0) {
+      continue;
+    }
+
+    plans.push({ file, raw, criteria });
+  }
+
+  /**
+   * 全案判据并集（两级门禁整批判定）
+   */
+  const allCriteria = plans.flatMap((plan) => plan.criteria);
+
+  /**
+   * 两级门禁
+   */
+  const gate = resolveCloseGates(
+    input.config,
+    allCriteria,
+    input.allowFullCriterion === true,
+    input.confirmHeavy === true,
+  );
+
+  if (gate.blocked) {
+    return {
+      cases: plans.map((plan) => ({
+        file: plan.file,
+        ok: false,
+        message: `门禁拦截（${gate.kind}），零执行`,
+        idempotent: false,
+      })),
+      succeeded: 0,
+      gateBlocked: true,
+      gateMessage: gate.message,
+    };
+  }
+
+  if (input.dryRun === true) {
+    return {
+      cases: plans.map((plan) => ({
+        file: plan.file,
+        ok: true,
+        message: `干跑预览（${plan.criteria.length} 条判据，未执行）`,
+        idempotent: false,
+      })),
+      succeeded: plans.length,
+      gateBlocked: false,
+      gateMessage: '',
+    };
+  }
+
+  /**
+   * 运行锁（防并行互踩）
+   */
+  const lock = acquireRunLock(input.root);
+
+  /**
+   * 逐案结果收集器
+   */
+  const cases: CloseCaseResult[] = [];
+
+  try {
+    for (const plan of plans) {
+      /**
+       * 逐判据执行结果
+       */
+      const runs = plan.criteria.map((criterion) => {
+        /**
+         * 预计算指纹
+         */
+        const fingerprint = computeCriterionFingerprint(input.root, criterion);
+
+        return {
+          criterion,
+          fingerprint,
+          run: runCriterionViaVault({ root: input.root, criterion, fingerprint }),
+        };
+      });
+
+      /**
+       * 未绿判据
+       */
+      const redCriterions = runs.filter((entry) => !entry.run.green);
+
+      if (redCriterions.length > 0) {
+        cases.push({
+          file: plan.file,
+          ok: false,
+          message: `判据未全绿（${redCriterions.map((e) => `${e.criterion.label} 退出码 ${e.run.certificate.exitCode}`).join('、')}）——跳过翻绿`,
+          idempotent: false,
+        });
+
+        continue;
+      }
+
+      /**
+       * 解析产物（概要合成）
+       */
+      const record = parseIssueDoc(plan.file.split('/').pop() ?? '', plan.raw, 0);
+
+      /**
+       * 概要
+       */
+      const summary =
+        input.summaryOverride ??
+        record?.criteria?.summary ??
+        `批量证书化收口（${record?.id ?? ''}）：${runs.length} 条判据全绿`;
+
+      /**
+       * 证据行（逐判据证书指纹）
+       */
+      const evidenceLines = runs.map(
+        (entry) =>
+          `${entry.criterion.label}：证书指纹 ${entry.run.certificate.fingerprint}（${entry.run.reused ? '复用' : '真实执行'}，退出码 ${entry.run.certificate.exitCode}）`,
+      );
+
+      /**
+       * 翻绿回填
+       */
+      const flip = applyGreenFlip({
+        raw: plan.raw,
+        summary,
+        evidenceBlock: renderRerunEvidenceBlock(summary, evidenceLines, 'issues:verify-close'),
+      });
+
+      if (!flip.idempotent) {
+        writeFileSync(join(input.root, plan.file), flip.content);
+      }
+
+      cases.push({
+        file: plan.file,
+        ok: true,
+        message: `证书化收口完成（${runs.length} 条判据全绿${flip.idempotent ? '，幂等零变更' : ''}）`,
+        idempotent: flip.idempotent,
+      });
+    }
+  } finally {
+    lock.unlock();
+  }
+
+  return {
+    cases,
+    succeeded: cases.filter((entry) => entry.ok).length,
+    gateBlocked: false,
+    gateMessage: '',
+  };
+}