@longzai-intelligence-issues/ledger 0.0.1 → 0.0.3

package/src/migrate/migrate-legacy.core.ts

@@ -0,0 +1,800 @@
+/**
+ * migrate-legacy 纯变换核（无 IO，可测性单一来源）
+ *
+ * 五方言解析（含表格）→ 字段别名 → pre-emoji 状态词规范化 → H1 编号规范 →
+ * 处置段标题链对齐 → 必填元信息回填 → 体首残留元信息块吸收与键去重收敛。
+ * 全部变换可幂等重放，变换台账逐条记录，供命令层零丢失守卫与人工复核消费。
+ */
+
+import { parseHeaderDialect } from '@/normalize/normalize-header.commands';
+import {
+  CANONICAL_STATUS_LABELS,
+  classifyStatusLine,
+  DISPOSITION_PLACEHOLDER_PATTERN,
+  DISPOSITION_PLACEHOLDER_WINDOW_LINES,
+} from '@/parser/format.utils';
+
+import { backfillRequiredFields } from './migrate-legacy.backfill';
+import { absorbLeadingMetadata, convergeDuplicateFields } from './migrate-legacy.converge';
+import { canonicalizeH1, canonicalizeStatusValue, cleanValue } from './migrate-legacy.vocab';
+
+/**
+ * 单文件迁移变换台账条目
+ */
+export type MigrationTransformation = {
+  /**
+   * 变换类别（人工复核消费的稳定标识）
+   */
+  kind:
+    | 'status-canonicalized'
+    | 'status-downgraded-placeholder'
+    | 'field-alias'
+    | 'priority-mapped'
+    | 'priority-backfilled'
+    | 'h1-numbered'
+    | 'disposition-renamed'
+    | 'disposition-appended'
+    | 'required-backfilled'
+    | 'header-converged'
+    | 'duplicate-field-converged';
+
+  /**
+   * 变换说明（原值 → 新值）
+   */
+  detail: string;
+};
+
+/**
+ * 纯变换产物
+ */
+export type MigrateCoreResult = {
+  /**
+   * 迁移形态
+   */
+  outcome: 'rewritten' | 'unchanged' | 'skipped';
+
+  /**
+   * 产物全文（skipped 时为原文）
+   */
+  content: string;
+
+  /**
+   * skip/unchanged 说明
+   */
+  message: string;
+
+  /**
+   * 变换台账（rewritten 时非空）
+   */
+  transformations: MigrationTransformation[];
+
+  /**
+   * 来源让位标记（回填缺省让位原始语义——守卫对来源键放行依据）
+   */
+  sourceReplaced: boolean;
+};
+
+/**
+ * 迁移选项（引擎零仓库知识——仓库特有缺省值全部经入参注入）
+ */
+export type MigrateCoreOptions = {
+  /**
+   * 编号（文件名前缀，H1 规范化用）
+   */
+  number: string;
+
+  /**
+   * 所属域回填值（scope title）
+   */
+  scopeTitle: string;
+
+  /**
+   * 优先级缺省（原案无优先级与严重程度时回填）
+   */
+  defaultPriority?: 'P1' | 'P2' | 'P3';
+
+  /**
+   * 来源回填缺省文案
+   */
+  defaultSource?: string;
+
+  /**
+   * 立案日期回填缺省（原案无日期字段时；未给则 skipped 交人工）
+   */
+  defaultFilingDate?: string;
+
+  /**
+   * 无状态行历史文档的显式灯位注入（--status；灯位属语义判断由操作者定档，
+   * 引擎仅承接机械迁移。红/绿两态——黄灯须 ≥4 字挂起原因不适用固定文案注入，
+   * 冻结唯一合法路径是 freeze 命令）
+   */
+  status?: 'red' | 'green';
+};
+
+/**
+ * 处置段候选标题链（apex-energy-ktv 全量段名词频盘点驱动；验证族 > 治理记录族 >
+ * 变更/修复族。计划性段名（治理方案/治理方向/修复方向/处置方向）不属处置记录，排除）
+ */
+export const DISPOSITION_CANDIDATES: ReadonlyArray<{ pattern: RegExp; title: string }> = [
+  { pattern: /^验证(结果)?(?!口径)/, title: '处置结果/验证口径' },
+  {
+    pattern: /^(治理记录|治理落地记录|治理落地|落地治理|治理（落地）|治理动作|治理$)/,
+    title: '处置结果/治理记录',
+  },
+  {
+    pattern: /^(修复(?!方向)|解决方案|变更内容|处理报告|处置(?!方向))/,
+    title: '处置结果/变更记录',
+  },
+];
+
+/**
+ * 处置段对齐产物
+ */
+type DispositionAlignment = {
+  /**
+   * 对齐后正文行
+   */
+  lines: string[];
+
+  /**
+   * 对齐变换台账
+   */
+  transformations: MigrationTransformation[];
+
+  /**
+   * 是否探测到处置段占位（触发黄灯降级）
+   */
+  placeholder: boolean;
+};
+
+/**
+ * 对齐处置段（绿灯族专属）：候选标题改名 + 无候选段时追加验证口径段 + 占位降级探测
+ *
+ * @param bodyLines - 正文行（自 bodyStartIndex 起）
+ * @returns 对齐产物（正文行 + 台账 + 是否占位降级）
+ */
+function alignDisposition(bodyLines: string[]): DispositionAlignment {
+  /**
+   * 台账收集器
+   */
+  const transformations: MigrationTransformation[] = [];
+
+  /**
+   * 候选命中下标与目标标题
+   */
+  let hitIndex = -1;
+
+  /**
+   * 命中候选的改名目标标题（如「处置结果/验证口径」）
+   */
+  let hitTitle = '';
+
+  for (const candidate of DISPOSITION_CANDIDATES) {
+    /**
+     * 候选标题行下标（精确行首匹配 `## ` + 模式）
+     */
+    const index = bodyLines.findIndex(
+      (line) => line.startsWith('## ') && candidate.pattern.test(line.slice(3).trim()),
+    );
+
+    if (index !== -1) {
+      hitIndex = index;
+
+      hitTitle = candidate.title;
+
+      break;
+    }
+  }
+
+  /**
+   * 已有含「处置结果」标题（前次迁移或原生）——不重复改名，不追加
+   */
+  const alreadyDisposition = bodyLines.some(
+    (line) => line.startsWith('## ') && line.includes('处置结果'),
+  );
+
+  /**
+   * 产物行
+   */
+  const lines = [...bodyLines];
+
+  /**
+   * 占位降级标记
+   */
+  let placeholder = false;
+
+  if (!alreadyDisposition && hitIndex !== -1) {
+    /**
+     * 原标题行
+     */
+    const original = lines[hitIndex] ?? '';
+
+    lines[hitIndex] = `## ${hitTitle}`;
+
+    transformations.push({
+      kind: 'disposition-renamed',
+      detail: `${original} → ## ${hitTitle}`,
+    });
+
+    /**
+     * 改名段起 8 行内占位探测
+     */
+    const window = lines.slice(hitIndex + 1, hitIndex + 1 + DISPOSITION_PLACEHOLDER_WINDOW_LINES);
+
+    placeholder = window.some((line) => DISPOSITION_PLACEHOLDER_PATTERN.test(line));
+  }
+
+  /**
+   * 追加条件：无任何处置段且改名来源非验证语义（变更记录族——缺独立验证段）
+   */
+  const appendedNeeded =
+    !alreadyDisposition && (hitIndex === -1 || hitTitle === '处置结果/变更记录');
+
+  if (appendedNeeded && !placeholder) {
+    lines.push(
+      '',
+      '## 处置结果/验证口径',
+      '',
+      '（原案无独立验证段；处置证据见上文各节——格式清偿迁移回填）',
+    );
+
+    transformations.push({
+      kind: 'disposition-appended',
+      detail: '追加 ## 处置结果/验证口径（无独立验证段的事实回填说明）',
+    });
+  }
+
+  return { lines, transformations, placeholder };
+}
+
+/**
+ * 头部字段渲染序（模板 §八 规范序；未入表字段按首现序殿后）
+ */
+const HEADER_FIELD_ORDER: readonly string[] = [
+  '优先级',
+  '状态',
+  '立案日期',
+  '所属域',
+  '来源',
+  '沿革',
+  '阻塞',
+];
+
+/**
+ * 执行单文档纯变换
+ *
+ * @param raw - 文档全文
+ * @param options - 迁移选项
+ * @returns 纯变换产物
+ */
+
+/**
+ * 超长状态拆分探测入参
+ */
+type LongStatusProbeInput = {
+  /**
+   * 显式灯位注入标记（注入通道不适用长度门）
+   */
+  injected: boolean;
+
+  /**
+   * 已规范状态标记（已规范值不适用长度门）
+   */
+  alreadyCanonical: boolean;
+
+  /**
+   * 原状态值
+   */
+  originalStatus: string;
+};
+
+/**
+ * 超长状态拆分探测产物
+ */
+type LongStatusSplit = {
+  /**
+   * 全文说明（落处置摘要字段）
+   */
+  summary: string;
+
+  /**
+   * 短规范状态（词表档位 + 原词溯源括注）
+   */
+  canonical: string;
+
+  /**
+   * 拆分档位（红/绿——处置段对齐判定依据）
+   */
+  tier: 'green' | 'red';
+};
+
+/**
+ * 超长状态拆分探测（「状态词 + 长说明」结构——词表命中拆分为短规范状态 +
+ * 处置摘要全文；未命中返回 'manual' 交人工）
+ *
+ * @param input - 探测入参
+ * @returns 拆分产物；'manual' 表示交人工；null 表示未触发（长度未超限）
+ */
+function probeLongStatusSplit(input: LongStatusProbeInput): LongStatusSplit | 'manual' | null {
+  if (input.injected || input.alreadyCanonical || input.originalStatus.length <= 80) {
+    return null;
+  }
+
+  /**
+   * 词表命中探测（值清理后取前缀——消除说明散文对 startsWith 匹配的干扰）
+   */
+  const probe = canonicalizeStatusValue(cleanValue(input.originalStatus).slice(0, 12));
+
+  if (
+    probe === null ||
+    (probe.tier !== 'green' && probe.tier !== 'red' && probe.tier !== 'deferred')
+  ) {
+    return 'manual';
+  }
+
+  /**
+   * 拆分档位
+   */
+  const tier: 'green' | 'red' = probe.tier === 'green' ? 'green' : 'red';
+
+  return {
+    summary: cleanValue(input.originalStatus.replace(/\*\*/g, '')),
+    canonical: `${CANONICAL_STATUS_LABELS[tier]}（原「${probe.word}」）`,
+    tier,
+  };
+}
+
+/**
+ * 来源与所属域回填入参
+ */
+type TailBackfillInput = {
+  /**
+   * 头部字段工作副本（原地回填）
+   */
+  fields: Array<{ key: string; value: string }>;
+
+  /**
+   * 变换台账
+   */
+  transformations: MigrationTransformation[];
+
+  /**
+   * 来源回填缺省文案
+   */
+  defaultSource?: string;
+
+  /**
+   * 所属域（scope title）
+   */
+  scopeTitle: string;
+};
+
+/**
+ * 来源与所属域回填产物
+ */
+type TailBackfillResult = {
+  /**
+   * skip 语（来源缺省未给交人工时非空）
+   */
+  skipMessage: string | null;
+};
+
+/**
+ * 执行来源与所属域回填
+ *
+ * @param input - 回填入参
+ * @returns 回填产物（skipMessage 非空即调用方应 skipped 返回）
+ */
+function backfillSourceAndDomain(input: TailBackfillInput): TailBackfillResult {
+  if (!input.fields.some((field) => field.key === '来源')) {
+    if (input.defaultSource === undefined) {
+      return { skipMessage: '缺来源且未给回填缺省——交人工' };
+    }
+
+    input.fields.push({ key: '来源', value: input.defaultSource });
+
+    input.transformations.push({ kind: 'required-backfilled', detail: '来源 ← 缺省回填' });
+  }
+
+  /**
+   * 所属域回填（scope title）
+   */
+  if (!input.fields.some((field) => field.key === '所属域')) {
+    input.fields.push({ key: '所属域', value: input.scopeTitle });
+
+    input.transformations.push({
+      kind: 'required-backfilled',
+      detail: `所属域 ← ${input.scopeTitle}`,
+    });
+  }
+
+  return { skipMessage: null };
+}
+
+/**
+ * H1 规范化入参
+ */
+type HeaderH1Input = {
+  /**
+   * 文档行数组
+   */
+  lines: string[];
+
+  /**
+   * 文件名编号
+   */
+  number: string;
+
+  /**
+   * 变换台账
+   */
+  transformations: MigrationTransformation[];
+};
+
+/**
+ * H1 规范化产物
+ */
+type HeaderH1 = {
+  /**
+   * 规范标题行
+   */
+  line: string;
+};
+
+/**
+ * 执行 H1 规范化（`# NNNN - 标题`；无一级标题返回 null 交人工）
+ *
+ * @param input - 规范化入参
+ * @returns 规范化产物；null 表示无一级标题
+ */
+function canonicalizeHeaderH1(input: HeaderH1Input): HeaderH1 | null {
+  /**
+   * 一级标题行下标
+   */
+  const h1Index = input.lines.findIndex((line) => line.startsWith('# '));
+
+  if (h1Index === -1) {
+    return null;
+  }
+
+  /**
+   * 规范 H1
+   */
+  const canonicalH1 = canonicalizeH1(input.lines[h1Index] ?? '', input.number);
+
+  if (canonicalH1.line !== (input.lines[h1Index] ?? '')) {
+    input.transformations.push({
+      kind: 'h1-numbered',
+      detail: `${input.lines[h1Index]} → ${canonicalH1.line}`,
+    });
+  }
+
+  return { line: canonicalH1.line };
+}
+
+/**
+ * 执行单文档纯变换
+ *
+ * @param raw - 文档全文
+ * @param options - 迁移选项
+ * @returns 纯变换产物
+ */
+export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): MigrateCoreResult {
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 头部解析产物（五方言）
+   */
+  const parsed = parseHeaderDialect(lines);
+
+  /**
+   * 状态字段定位
+   */
+  const statusIndex = parsed.fields.findIndex((field) => field.key === '状态');
+
+  /**
+   * 显式灯位注入标记（--status：无状态行历史文档的人工定档通道）
+   */
+  const injected = statusIndex === -1 && (options.status === 'red' || options.status === 'green');
+
+  if (statusIndex === -1 && !injected) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: '无可识别状态行——灯位属语义判断，交人工（--status red|green 显式定档）',
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  /**
+   * 原状态值（清理粗体包裹；注入通道为规范标签本身）
+   */
+  const originalStatus = injected
+    ? `${CANONICAL_STATUS_LABELS[options.status ?? 'red']}（存量清偿定档：原案无状态行，依结案内容人工定档）`
+    : cleanValue(parsed.fields[statusIndex ?? 0]?.value ?? '');
+
+  /**
+   * 已规范状态标记（规范五态或 emoji 旧变体——值原样保留，仅走收敛通道：
+   * 体首残留元信息块吸收与键去重，不做状态词规范化）
+   */
+  const alreadyCanonical = !injected && classifyStatusLine(`状态: ${originalStatus}`) !== 'unknown';
+
+  /**
+   * 超长状态拆分产物（null 未触发；'manual' 词表未命中交人工）
+   */
+  const longSplit = probeLongStatusSplit({
+    injected,
+    alreadyCanonical,
+    originalStatus,
+  });
+
+  if (longSplit === 'manual') {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: `状态值超长（${originalStatus.length} 字符——段落级文本混入状态行且词表未命中）——交人工拆分`,
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  /**
+   * 变换台账
+   */
+  const transformations: MigrationTransformation[] = [];
+
+  /**
+   * 字段工作副本（键值清理粗体包裹；注入通道补入状态字段）
+   */
+  const fields = parsed.fields.map((field) => ({ key: field.key, value: cleanValue(field.value) }));
+
+  if (injected) {
+    fields.push({ key: '状态', value: originalStatus });
+
+    transformations.push({
+      kind: 'status-canonicalized',
+      detail: `<无状态行> → ${originalStatus}（--status 注入，人工定档）`,
+    });
+  }
+
+  /**
+   * 必填回填（别名/立案日期/优先级——缺省未给交人工）
+   */
+  const backfill = backfillRequiredFields({
+    fields,
+    transformations,
+    defaultPriority: options.defaultPriority,
+    defaultFilingDate: options.defaultFilingDate,
+  });
+
+  if (backfill.skipMessage !== null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: backfill.skipMessage,
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  /**
+   * 注入通道档位（红/绿直取；声明式注解替代断言窄化）
+   */
+  const injectedTier: 'green' | 'red' = options.status === 'green' ? 'green' : 'red';
+
+  /**
+   * 状态词规范化（注入/已规范通道跳过词表判定：注入为规范标签；已规范值原样保留）
+   */
+  const canonicalStatus = injected
+    ? {
+        value: originalStatus,
+        tier: injectedTier,
+        word: '<无状态行>',
+      }
+    : alreadyCanonical
+      ? {
+          value: originalStatus,
+          tier:
+            classifyStatusLine(`状态: ${originalStatus}`) === 'green' ||
+            classifyStatusLine(`状态: ${originalStatus}`) === 'legacy-green'
+              ? ('green' as const)
+              : ('red' as const),
+          word: '<已规范>',
+        }
+      : longSplit !== null && longSplit !== 'manual'
+        ? {
+            value: longSplit.canonical,
+            tier: longSplit.tier,
+            word: '<超长拆分>',
+          }
+        : canonicalizeStatusValue(originalStatus);
+
+  if (canonicalStatus === null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: `状态值「${originalStatus}」不可机械迁移（冻结/取消无据/黄灯无因/词表未识别）——交人工`,
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  /**
+   * 超长状态拆分产物：短规范状态承载词表档位，全文说明落处置摘要字段
+   */
+  if (
+    longSplit !== null &&
+    longSplit !== 'manual' &&
+    !fields.some((field) => field.key === '处置摘要')
+  ) {
+    fields.push({ key: '处置摘要', value: longSplit.summary });
+
+    transformations.push({
+      kind: 'status-canonicalized',
+      detail: `状态值超长拆分：${longSplit.summary.slice(0, 24)}… → 短规范状态 + 处置摘要字段（${longSplit.summary.length} 字符全文承载）`,
+    });
+  }
+
+  /**
+   * 处置段对齐（绿灯族；黄灯降级案同样需要对齐后的段供回填）
+   */
+  const isGreenFamily = canonicalStatus.tier === 'green';
+
+  /**
+   * 正文行
+   */
+  let bodyLines = lines.slice(parsed.bodyStartIndex);
+
+  /**
+   * 体首残留元信息块吸收（历史批量清偿事故形态：方言行未被解析而落 residual、
+   * 注入回填后又在正文首部原样存留——吸收回头部字段并随后键去重收敛）
+   */
+  const absorbed = absorbLeadingMetadata(bodyLines, fields);
+
+  if (absorbed.consumedLines > 0) {
+    bodyLines = absorbed.restLines;
+
+    transformations.push({
+      kind: 'header-converged',
+      detail: `体首残留元信息块吸收 ${absorbed.consumedLines} 行（键去重收敛见产物）`,
+    });
+  }
+
+  /**
+   * 键去重与语义让位（状态/来源：注入定档/回填标记让位于吸收到的原始语义）
+   */
+  const convergence = convergeDuplicateFields(fields, transformations);
+
+  /**
+   * 处置段对齐产物（非绿灯族不触发）
+   */
+  const alignment = isGreenFamily
+    ? alignDisposition(bodyLines)
+    : { lines: bodyLines, transformations: [], placeholder: false };
+
+  bodyLines = alignment.lines;
+
+  transformations.push(...alignment.transformations);
+
+  /**
+   * 最终状态值（占位降级：历史绿词但验证口径为占位——诚实黄灯；注入通道定档为人工语义不降级）
+   */
+  const finalStatus =
+    convergence.statusValue ??
+    (!injected && alignment.placeholder
+      ? `🟡 处理中（历史标记已处置但验证口径为占位，清偿时待核实；原「${canonicalStatus.word}」）`
+      : canonicalStatus.value);
+
+  if (!injected && !alreadyCanonical) {
+    if (alignment.placeholder) {
+      transformations.push({
+        kind: 'status-downgraded-placeholder',
+        detail: `${originalStatus} → 🟡 处理中（处置段占位降级）`,
+      });
+    } else {
+      transformations.push({
+        kind: 'status-canonicalized',
+        detail: `${originalStatus} → ${canonicalStatus.value}`,
+      });
+    }
+  }
+
+  /**
+   * 状态字段写回
+   */
+  const statusWriteIndex = fields.findIndex((field) => field.key === '状态');
+
+  if (statusWriteIndex !== -1) {
+    fields[statusWriteIndex] = { key: '状态', value: finalStatus };
+  }
+
+  /**
+   * 来源与所属域回填（缺省未给交人工）
+   */
+  const tailBackfill = backfillSourceAndDomain({
+    fields,
+    transformations,
+    defaultSource: options.defaultSource,
+    scopeTitle: options.scopeTitle,
+  });
+
+  if (tailBackfill.skipMessage !== null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: tailBackfill.skipMessage,
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  /**
+   * H1 规范化（无一级标题交人工；编号规范见变换台账）
+   */
+  const h1 = canonicalizeHeaderH1({
+    lines,
+    number: options.number,
+    transformations,
+  });
+
+  if (h1 === null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: '无一级标题——交人工',
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  /**
+   * 头部渲染序（规范序在前，未入表字段按首现序殿后）
+   */
+  const orderedFields = [
+    ...HEADER_FIELD_ORDER.flatMap((key) => fields.filter((field) => field.key === key)),
+    ...fields.filter((field) => !HEADER_FIELD_ORDER.includes(field.key)),
+  ];
+
+  /**
+   * 正文前导空行剥离（分隔空行由组装层统一供给——保证已规范产物逐字幂等）
+   */
+  let bodyStart = 0;
+
+  while (bodyStart < bodyLines.length && (bodyLines[bodyStart] ?? '').trim() === '') {
+    bodyStart += 1;
+  }
+
+  /**
+   * 产物全文
+   */
+  const content = [
+    h1.line,
+    '',
+    ...orderedFields.map((field) => `**${field.key}**: ${field.value}`),
+    ...(parsed.residuals.length > 0 ? ['', ...parsed.residuals] : []),
+    '',
+    ...bodyLines.slice(bodyStart),
+  ].join('\n');
+
+  if (content === raw) {
+    return {
+      outcome: 'unchanged',
+      content: raw,
+      message: '已是规范形态',
+      transformations: [],
+      sourceReplaced: false,
+    };
+  }
+
+  return {
+    outcome: 'rewritten',
+    content,
+    message: '存量头部已清偿为规范形态',
+    transformations,
+    sourceReplaced: convergence.sourceReplaced,
+  };
+}