@longzai-intelligence-issues/ledger 0.0.2 → 0.0.4

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

@@ -0,0 +1,384 @@
+/**
+ * migrate-legacy 头部收敛（体首残留元信息块吸收与键去重，自 core 拆出守文件行上限）
+ *
+ * 事故背景见 docs/issues/0012：方言缺口致元信息落 residual 挂于规范头部下方，
+ * 此模块提供机械收敛通道（吸收、键去重、注入/回填标记让位原始语义）。
+ */
+
+import type { MigrationTransformation } from './migrate-legacy.core';
+
+import { canonicalizeStatusValue, cleanValue } from './migrate-legacy.vocab';
+
+/**
+ * 体首残留元信息块吸收产物
+ */
+type AbsorbResult = {
+  /**
+   * 吸收行数（元信息行数，不含间夹空行）
+   */
+  consumedLines: number;
+
+  /**
+   * 吸收后的正文余行
+   */
+  restLines: string[];
+};
+
+/**
+ * 吸收触发认定的核心元信息键（块内至少含其一才整块吸收——纯描述性键
+ * 开头的正文不受影响）
+ */
+const CORE_METADATA_KEYS: ReadonlySet<string> = new Set([
+  '状态',
+  '优先级',
+  '立案日期',
+  '日期',
+  '来源',
+  '严重程度',
+  '严重度',
+  '所属域',
+  '处置日期',
+  '沿革',
+  '阻塞',
+]);
+
+/**
+ * 吸收正文首部的残留元信息块（历史批量清偿事故形态收敛）
+ *
+ * 两段式：先收集正文首部连续的元信息形态行（键白名单外键也入列——键值形态
+ * 本身即头部元信息特征，未知键升格为额外字段），再按触发条件（含核心键 /
+ * ≥2 行 / 含多行子项结构）整块吸收或全不吸收——正文证据散文行不在键值
+ * 形态内，天然中断收集。
+ *
+ * @param bodyLines - 正文行
+ * @param fields - 头部字段收集器（吸收行入列）
+ * @returns 吸收产物
+ */
+export function absorbLeadingMetadata(
+  bodyLines: string[],
+  fields: Array<{ key: string; value: string }>,
+): AbsorbResult {
+  /**
+   * 吸收的原始行区（含间夹空行，末尾空行归还正文）
+   */
+  const consumedRegion: string[] = [];
+
+  /**
+   * 元信息行命中计数
+   */
+  let metadataHits = 0;
+
+  /**
+   * 核心键命中标记（整块吸收触发条件）
+   */
+  let coreHit = false;
+
+  /**
+   * 带子项的多行元信息命中标记（结构特征即头部元信息，触发整块吸收）
+   */
+  let childrenHit = false;
+
+  /**
+   * 游标（首个非元信息行位置）
+   */
+  let cursor = 0;
+
+  /**
+   * 吸收行暂存（触发条件确认后再入列，防误吞后回滚复杂化）
+   */
+  const absorbedFields: Array<{ key: string; value: string }> = [];
+
+  while (cursor < bodyLines.length) {
+    /**
+     * 当前行
+     */
+    const line = bodyLines[cursor] ?? '';
+
+    if (line.trim() === '') {
+      consumedRegion.push(line);
+
+      cursor += 1;
+
+      continue;
+    }
+
+    /**
+     * 元信息行匹配（单行形态；键不设白名单——键值形态本身即元信息特征，
+     * 未知键以额外字段升格，键长度上限 20 防散文前缀误判）
+     */
+    const match = /^(?:\*\*|- \*\*|- )([^*：:]{1,20})(?:\*\*)?\s*[：:]\s*(.+)$/.exec(line);
+
+    /**
+     * 多行形态匹配（`- 键：` 空值 + 缩进子项）
+     */
+    const multiLineKey = /^(?:\*\*|- \*\*|- )([^*：:]{1,20})(?:\*\*)?\s*[：:]\s*$/.exec(line);
+
+    if (match === null && multiLineKey === null) {
+      break;
+    }
+
+    /**
+     * 键（单行或多行形态取一）
+     */
+    const key = ((match ?? multiLineKey)?.[1] ?? '').trim();
+
+    if (key === '') {
+      break;
+    }
+
+    consumedRegion.push(line);
+
+    metadataHits += 1;
+
+    if (CORE_METADATA_KEYS.has(key)) {
+      coreHit = true;
+    }
+
+    if (match !== null) {
+      absorbedFields.push({ key, value: cleanValue(match[2] ?? '') });
+
+      cursor += 1;
+
+      continue;
+    }
+
+    /**
+     * 多行形态：收集缩进深于键行的子项（子项文本去列表标记后以「；」并入单行值）
+     */
+    const childTexts: string[] = [];
+
+    /**
+     * 键行缩进宽度
+     */
+    const keyIndent = line.length - line.trimStart().length;
+
+    cursor += 1;
+
+    while (cursor < bodyLines.length) {
+      /**
+       * 候选子项行
+       */
+      const childLine = bodyLines[cursor] ?? '';
+
+      if (childLine.trim() === '') {
+        break;
+      }
+
+      /**
+       * 子项缩进
+       */
+      const childIndent = childLine.length - childLine.trimStart().length;
+
+      if (childIndent <= keyIndent) {
+        break;
+      }
+
+      consumedRegion.push(childLine);
+
+      childTexts.push(childLine.trim().replace(/^-\s*/, ''));
+
+      cursor += 1;
+    }
+
+    if (childTexts.length === 0) {
+      /**
+       * 空值键无子项：按空值入列（键确在元信息形态内，吸收防重复挂留）
+       */
+      absorbedFields.push({ key, value: '' });
+    } else {
+      absorbedFields.push({ key, value: childTexts.join('；') });
+
+      childrenHit = true;
+    }
+  }
+
+  if (metadataHits === 0 || (!coreHit && metadataHits < 2 && !childrenHit)) {
+    return { consumedLines: 0, restLines: bodyLines };
+  }
+
+  fields.push(...absorbedFields);
+
+  /**
+   * 吸收区末尾空行归还正文（保持正文段前空行结构）
+   */
+  while (
+    consumedRegion.length > 0 &&
+    (consumedRegion[consumedRegion.length - 1] ?? '').trim() === ''
+  ) {
+    consumedRegion.pop();
+
+    cursor -= 1;
+  }
+
+  return { consumedLines: metadataHits, restLines: bodyLines.slice(cursor) };
+}
+
+/**
+ * 键去重与语义让位产物
+ */
+type FieldConvergence = {
+  /**
+   * 状态让位值（注入定档让位原始语义后的规范化值；未发生让位为 undefined）
+   */
+  statusValue?: string;
+
+  /**
+   * 来源让位标记（回填缺省让位原始语义时置 true——守卫对来源键放行）
+   */
+  sourceReplaced: boolean;
+};
+
+/**
+ * 键去重与语义让位
+ *
+ * 状态/来源：首值含注入或回填标记（存量清偿定档 / 格式清偿迁移回填）而后值
+ * 为原始语义时，用后值的规范化结果替换首值——原始信息优先；其余键重复时
+ * 保留首现值并记台账。
+ *
+ * @param fields - 头部字段（原地收敛）
+ * @param transformations - 变换台账
+ * @returns 收敛产物（状态让位值供终值写回优先采用）
+ */
+export function convergeDuplicateFields(
+  fields: Array<{ key: string; value: string }>,
+  transformations: MigrationTransformation[],
+): FieldConvergence {
+  /**
+   * 状态让位值（终值写回优先采用）
+   */
+  let convergedStatusValue: string | undefined;
+
+  /**
+   * 来源让位标记（守卫放行依据）
+   */
+  let sourceReplaced = false;
+
+  /**
+   * 状态原始值定位（重复且首值含注入标记）
+   */
+  const statusEntries = fields.filter((field) => field.key === '状态');
+
+  if (statusEntries.length > 1) {
+    /**
+     * 注入定档首值
+     */
+    const injectedFirst = statusEntries[0]?.value.includes('存量清偿定档：原案无状态行') === true;
+
+    /**
+     * 原始语义候选（不含注入标记的首个后值）
+     */
+    const originalCandidate = statusEntries
+      .slice(1)
+      .find((field) => !field.value.includes('存量清偿定档：原案无状态行'));
+
+    if (injectedFirst && originalCandidate !== undefined) {
+      /**
+       * 原始语义规范化产物
+       */
+      const reCanonical = canonicalizeStatusValue(originalCandidate.value);
+
+      if (reCanonical !== null) {
+        /**
+         * 状态首现条目（让位写回目标）
+         */
+        const first = fields.find((field) => field.key === '状态');
+
+        if (first !== undefined) {
+          first.value = reCanonical.value;
+        }
+
+        convergedStatusValue = reCanonical.value;
+
+        transformations.push({
+          kind: 'duplicate-field-converged',
+          detail: `状态 键去重：注入定档让位原始语义 → ${reCanonical.value}`,
+        });
+      }
+    }
+  }
+
+  /**
+   * 来源原始值定位（重复且首值含回填标记）
+   */
+  const sourceEntries = fields.filter((field) => field.key === '来源');
+
+  if (sourceEntries.length > 1) {
+    /**
+     * 回填首值
+     */
+    const backfilledFirst = sourceEntries[0]?.value.includes('格式清偿迁移回填') === true;
+
+    /**
+     * 原始语义候选
+     */
+    const originalCandidate = sourceEntries
+      .slice(1)
+      .find((field) => !field.value.includes('格式清偿迁移回填'));
+
+    if (backfilledFirst && originalCandidate !== undefined) {
+      /**
+       * 来源首现条目（让位写回目标）
+       */
+      const first = fields.find((field) => field.key === '来源');
+
+      if (first !== undefined) {
+        first.value = originalCandidate.value;
+      }
+
+      sourceReplaced = true;
+
+      transformations.push({
+        kind: 'duplicate-field-converged',
+        detail: `来源 键去重：回填缺省让位原始语义 → ${originalCandidate.value.slice(0, 60)}`,
+      });
+    }
+  }
+
+  /**
+   * 通用去重（保留各键首现条目；异值合并为分号单行，不丢信息——状态/来源的
+   * 让位已在上方完成）
+   */
+  const keeperIndex = new Map<string, number>();
+
+  for (let index = 0; index < fields.length; index += 1) {
+    /**
+     * 正向遍历到的字段条目（首现登记为保留位，重复并入后移除）
+     */
+    const field = fields[index];
+
+    if (field === undefined) {
+      continue;
+    }
+
+    /**
+     * 该键首现保留位下标
+     */
+    const firstIndex = keeperIndex.get(field.key);
+
+    if (firstIndex === undefined) {
+      keeperIndex.set(field.key, index);
+
+      continue;
+    }
+
+    /**
+     * 首现保留条目（异值并入目标）
+     */
+    const keeper = fields[firstIndex];
+
+    if (field.value !== '' && keeper !== undefined && !keeper.value.includes(field.value)) {
+      keeper.value = keeper.value === '' ? field.value : `${keeper.value}；${field.value}`;
+    }
+
+    transformations.push({
+      kind: 'duplicate-field-converged',
+      detail: `${field.key} 键去重：重复值并入首现（${field.value.slice(0, 40)}）`,
+    });
+
+    fields.splice(index, 1);
+
+    index -= 1;
+  }
+
+  return { statusValue: convergedStatusValue, sourceReplaced };
+}