@longzai-intelligence-issues/ledger 0.0.1 → 0.0.3

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

@@ -0,0 +1,475 @@
+/**
+ * migrate-legacy 命令层（文件 IO + 零丢失守卫 + 落盘）
+ *
+ * 存量注册表清偿唯一合法批量通道：变换核产出 → 守卫逐项对账（原字段/正文行
+ * 在场或落入变换台账）→ 幂等落盘。dry-run 全程零写入。
+ */
+
+import type { LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { HEADING_ALONE_METADATA_KEYS } from '@/normalize/normalize-header.commands';
+
+import {
+  DISPOSITION_CANDIDATES,
+  migrateLegacyCore,
+  type MigrationTransformation,
+} from './migrate-legacy.core';
+import { cleanValue } from './migrate-legacy.vocab';
+
+/**
+ * 单文件迁移入参
+ */
+export type MigrateLegacyFileInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * issue 文件仓库相对路径（须落 scope registryDir 内）
+   */
+  file: string;
+
+  /**
+   * 解析后配置（所属域回填取 scope title）
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 优先级缺省（原案无优先级与严重程度时回填）
+   */
+  defaultPriority?: 'P1' | 'P2' | 'P3';
+
+  /**
+   * 来源回填缺省文案
+   */
+  defaultSource?: string;
+
+  /**
+   * 立案日期回填缺省（YYYY-MM-DD）
+   */
+  defaultFilingDate?: string;
+
+  /**
+   * 无状态行历史文档的显式灯位注入（--status red|green；灯位语义由操作者定档）
+   */
+  status?: 'red' | 'green';
+
+  /**
+   * 只呈现不落盘
+   */
+  dryRun?: boolean;
+};
+
+/**
+ * 单文件迁移结果
+ */
+export type MigrateLegacyFileResult = {
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 处置形态
+   */
+  outcome: 'rewritten' | 'unchanged' | 'skipped' | 'failed';
+
+  /**
+   * 结果说明
+   */
+  message: string;
+
+  /**
+   * 产物全文（rewritten/unchanged 携带，dry-run 复核消费）
+   */
+  content: string;
+
+  /**
+   * 变换台账（人工复核消费）
+   */
+  transformations: MigrationTransformation[];
+};
+
+/**
+ * 注册表文件名编号提取模式（NNNN-slug.md）
+ */
+const FILE_NUMBER_PATTERN = /^([0-9]{3,4})-.+\.md$/;
+
+/**
+ * 解析文件所属 scope（registryDir 前缀最长匹配）
+ *
+ * @param config - 解析后配置
+ * @param file - 仓库相对文件路径
+ * @returns scope title；无命中为 null
+ */
+function resolveScopeTitle(config: LziIssuesConfig, file: string): string | null {
+  /**
+   * 候选 scope（按 registryDir 长度降序取最长前缀命中）
+   */
+  const hit = config.scopes
+    .filter((scope) => file === scope.registryDir || file.startsWith(`${scope.registryDir}/`))
+    .sort((left, right) => right.registryDir.length - left.registryDir.length)[0];
+
+  return hit?.title ?? null;
+}
+
+/**
+ * 零丢失守卫：原文全部内容必须在产物在场（或属已登记变换：状态规范化/字段
+ * 别名/优先级映射/H1 补编号/处置段标题改名/表格脚手架丢弃）
+ *
+ * @param raw - 原文全文
+ * @param migrated - 变换核产物全文
+ * @param transformedKeys - 已变换字段键集合（状态/日期/优先级等）
+ * @returns 缺失项描述列表（空 = 通过）
+ */
+function findLostContent(raw: string, migrated: string, transformedKeys: string[]): string[] {
+  /**
+   * 缺失收集器
+   */
+  const lost: string[] = [];
+
+  /**
+   * 原文行数组
+   */
+  const rawLines = raw.split(/\r?\n/);
+
+  for (let lineIndex = 0; lineIndex < rawLines.length; lineIndex += 1) {
+    /**
+     * 当前行
+     */
+    const line = rawLines[lineIndex] ?? '';
+
+    /**
+     * 行首去空白形态
+     */
+    const trimmed = line.trim();
+
+    if (trimmed === '') {
+      continue;
+    }
+
+    if (migrated.includes(trimmed)) {
+      continue;
+    }
+
+    /**
+     * 一级标题：补编号/分隔符规范化后标题核心须在场
+     */
+    if (trimmed.startsWith('# ')) {
+      /**
+       * 标题核心（去 `# ` 与既有编号 + 分隔符变体）
+       */
+      const titleCore = trimmed
+        .replace(/^#\s+/, '')
+        .replace(/^[0-9]{3,4}\s*(?:[-—―·.．：:－]+\s*|\s+)/, '')
+        .trim();
+
+      if (titleCore !== '' && migrated.includes(titleCore)) {
+        continue;
+      }
+    }
+
+    /**
+     * 处置段候选标题改名（候选链与变换核 DISPOSITION_CANDIDATES 单一真源）
+     */
+    if (
+      trimmed.startsWith('## ') &&
+      DISPOSITION_CANDIDATES.some((candidate) => candidate.pattern.test(trimmed.slice(3).trim())) &&
+      migrated.includes('处置结果/')
+    ) {
+      continue;
+    }
+
+    /**
+     * 表格行：脚手架（表头/分隔行）设计性丢弃；数据行按键值对账
+     */
+    const tableMatch = /^\|([^|]*)\|([^|]*)\|$/.exec(trimmed);
+
+    if (tableMatch !== null) {
+      /**
+       * 键/值单元格
+       */
+      const key = (tableMatch[1] ?? '').trim();
+
+      /**
+       * 值单元格（与键单元格配对对账）
+       */
+      const value = (tableMatch[2] ?? '').trim();
+
+      /**
+       * 分隔行单元格形态
+       */
+      const separatorCellPattern = /^:?-{2,}:?$/;
+
+      /**
+       * 次行表格匹配（表头行判定：分隔行紧前的一行是表头——与解析器同口径）
+       */
+      const nextLineMatch = /^\|([^|]*)\|([^|]*)\|$/.exec((rawLines[lineIndex + 1] ?? '').trim());
+
+      /**
+       * 次行是否表格分隔行
+       */
+      const nextIsTableSeparator =
+        nextLineMatch !== null &&
+        separatorCellPattern.test((nextLineMatch[1] ?? '').trim()) &&
+        separatorCellPattern.test((nextLineMatch[2] ?? '').trim());
+
+      /**
+       * 分隔行/表头行（表头任意列名形态均属脚手架——设计性丢弃）
+       */
+      if (
+        (separatorCellPattern.test(key) && separatorCellPattern.test(value)) ||
+        (nextIsTableSeparator && key !== '') ||
+        key === ''
+      ) {
+        continue;
+      }
+
+      if (transformedKeys.includes(key) || migrated.includes(`**${key}**: ${value}`)) {
+        continue;
+      }
+
+      lost.push(trimmed.slice(0, 60));
+
+      continue;
+    }
+
+    /**
+     * 管道引用行（`> 键：值 ｜ …`）：逐段键值对账（与解析器形态一同口径）
+     */
+    if (trimmed.startsWith('>')) {
+      /**
+       * 管道分段
+       */
+      const segments = trimmed.slice(1).split(/[｜|]/);
+
+      /**
+       * 全部段对账通过标记
+       */
+      let allMatched = true;
+
+      for (const segment of segments) {
+        /**
+         * 段内键值切分
+         */
+        const pairMatch = /^([^：:]{1,8})\s*[：:]\s*(.+)$/.exec(segment.trim());
+
+        if (pairMatch === null) {
+          continue;
+        }
+
+        /**
+         * 键（清粗体包裹——`> **键**: 值` 复合形态与头部字段行对账同口径）
+         */
+        const key = (pairMatch[1] ?? '').replace(/^\*+|\*+$/g, '').trim();
+
+        /**
+         * 清理后值（与引擎 cleanValue 同口径）
+         */
+        const value = cleanValue(pairMatch[2] ?? '');
+
+        if (!transformedKeys.includes(key) && !migrated.includes(value)) {
+          allMatched = false;
+        }
+      }
+
+      if (allMatched) {
+        continue;
+      }
+    }
+
+    /**
+     * 多行元信息形态：空值键行（键已并入规范头部即通过）
+     */
+    const emptyKeyMatch = /^(?:\*\*|- \*\*|- )([^*：:]{1,20})(?:\*\*)?\s*[：:]\s*$/.exec(trimmed);
+
+    if (emptyKeyMatch !== null && migrated.includes(`**${(emptyKeyMatch[1] ?? '').trim()}**:`)) {
+      continue;
+    }
+
+    /**
+     * 列表子项行：去列表标记后的文本在场即通过（多行元信息子项已并入单行值）
+     */
+    if (trimmed.startsWith('- ') && migrated.includes(trimmed.slice(2).trim())) {
+      continue;
+    }
+
+    /**
+     * 头部字段行：粗体包裹与值清理后的形态在场即可（含列表+粗体复合方言）
+     */
+    const labeled = /^(?:\*\*|- \*\*|- |## )([^*：:]{1,20})(?:\*\*)?\s*[：:]\s*(.+)$/.exec(line);
+
+    if (labeled !== null) {
+      /**
+       * 键
+       */
+      const key = (labeled[1] ?? '').trim();
+
+      /**
+       * 值（与引擎 cleanValue 同口径清理——全包裹/前导/词后粗体三形态）
+       */
+      const value = cleanValue(labeled[2] ?? '');
+
+      if (transformedKeys.includes(key) || migrated.includes(value)) {
+        continue;
+      }
+    }
+
+    /**
+     * 标题式隔行值键行（`## 键` 单独成行）：键行属登记变换被消费进规范头部，
+     * 配对值行自身经上方 includes 对账在场
+     */
+    const aloneKey = /^##\s*([^：:]{1,10})\s*$/.exec(trimmed);
+
+    if (aloneKey !== null && HEADING_ALONE_METADATA_KEYS.has(aloneKey[1]?.trim() ?? '')) {
+      continue;
+    }
+
+    /**
+     * 标题式隔行值配对值行：前非空行是 `## 键` 且键在集合内时按字段值对账
+     * （状态词规范化会重组值文本——键属已变换集合或清理值在场即通过）
+     */
+    let prevIndex = lineIndex - 1;
+
+    while (prevIndex >= 0 && (rawLines[prevIndex] ?? '').trim() === '') {
+      prevIndex -= 1;
+    }
+
+    /**
+     * 前非空行的标题式键形态
+     */
+    const prevAlone = /^##\s*([^：:]{1,10})\s*$/.exec((rawLines[prevIndex] ?? '').trim());
+
+    if (prevAlone !== null && HEADING_ALONE_METADATA_KEYS.has(prevAlone[1]?.trim() ?? '')) {
+      /**
+       * 配对键
+       */
+      const prevKey = (prevAlone[1] ?? '').trim();
+
+      if (transformedKeys.includes(prevKey) || migrated.includes(cleanValue(trimmed))) {
+        continue;
+      }
+    }
+
+    lost.push(trimmed.slice(0, 60));
+  }
+
+  return lost;
+}
+
+/**
+ * 迁移并（缺省）落盘单份存量文档
+ *
+ * @param input - 命令入参
+ * @returns 单文件迁移结果
+ */
+export function migrateLegacyFile(input: MigrateLegacyFileInput): MigrateLegacyFileResult {
+  /**
+   * 编号（文件名前缀）
+   */
+  const basename = input.file.split('/').pop() ?? '';
+
+  /**
+   * 文件名编号提取结果（H1 规范化用）
+   */
+  const numberMatch = FILE_NUMBER_PATTERN.exec(basename);
+
+  if (numberMatch === null) {
+    return {
+      file: input.file,
+      outcome: 'skipped',
+      message: '文件名不属注册表编号形态（NNNN-slug.md）',
+      content: '',
+      transformations: [],
+    };
+  }
+
+  /**
+   * 所属域（scope title）
+   */
+  const scopeTitle = resolveScopeTitle(input.config, input.file);
+
+  if (scopeTitle === null) {
+    return {
+      file: input.file,
+      outcome: 'skipped',
+      message: '文件不在任何已登记 scope 的 registryDir 内——交人工',
+      content: '',
+      transformations: [],
+    };
+  }
+
+  /**
+   * 文档全文
+   */
+  let raw = '';
+
+  try {
+    raw = readFileSync(join(input.root, input.file), 'utf8');
+  } catch {
+    return {
+      file: input.file,
+      outcome: 'failed',
+      message: '读档失败（文件不存在或不可读）',
+      content: '',
+      transformations: [],
+    };
+  }
+
+  /**
+   * 纯变换产物
+   */
+  const migrated = migrateLegacyCore(raw, {
+    number: numberMatch[1] ?? '',
+    scopeTitle,
+    defaultPriority: input.defaultPriority,
+    defaultSource: input.defaultSource,
+    defaultFilingDate: input.defaultFilingDate,
+    status: input.status,
+  });
+
+  if (migrated.outcome !== 'rewritten') {
+    return {
+      file: input.file,
+      outcome: migrated.outcome,
+      message: migrated.message,
+      content: migrated.content,
+      transformations: migrated.transformations,
+    };
+  }
+
+  /**
+   * 零丢失守卫（已变换字段键集合：状态/日期别名/优先级/H1；来源让位时加来源）
+   */
+  const lost = findLostContent(
+    raw,
+    migrated.content,
+    migrated.sourceReplaced ? ['状态', '日期', '优先级', '来源'] : ['状态', '日期', '优先级'],
+  );
+
+  if (lost.length > 0) {
+    return {
+      file: input.file,
+      outcome: 'failed',
+      message: `零丢失守卫失败：${lost.length} 项原文内容未在产物在场（如 ${lost[0]}）——不落盘`,
+      content: migrated.content,
+      transformations: migrated.transformations,
+    };
+  }
+
+  if (input.dryRun !== true) {
+    writeFileSync(join(input.root, input.file), migrated.content);
+  }
+
+  return {
+    file: input.file,
+    outcome: 'rewritten',
+    message: input.dryRun === true ? 'dry-run 通过（未落盘）' : '存量头部已清偿为规范形态',
+    content: migrated.content,
+    transformations: migrated.transformations,
+  };
+}