@longzai-intelligence-issues/ledger 0.0.1

package/src/normalize/normalize-header.commands.ts

@@ -0,0 +1,361 @@
+/**
+ * normalize-header（方言头部迁移）
+ *
+ * 四种历史方言（单行管道引用行 / 粗体标签行 / `## 键: 值` 标题式 / `- ` 列表式）
+ * 解析后重排为裁定格式：粗体标签逐行 `**键**: 值`；字段规范序（FIELD_RANK）；
+ * 「主题」问题陈述迁正文首个节标题后；residual 原样保留。零丢失守卫：每字段
+ * 必须在产物文本在场否则 failed 不落盘；幂等（产物 === 原文 → unchanged）。
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * 字段规范序（排名值越小越靠前；未入表字段按首现序殿后）
+ */
+const FIELD_RANK: Readonly<Record<string, number>> = {
+  立案日期: 10,
+  优先级: 20,
+  严重程度: 30,
+  状态: 40,
+  处置日期: 50,
+  所属域: 60,
+};
+
+/**
+ * 单文件迁移入参
+ */
+export type NormalizeHeaderFileInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+};
+
+/**
+ * 单文件迁移结果
+ */
+export type NormalizeHeaderResult = {
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 处置形态：rewritten / unchanged / skipped / failed
+   */
+  outcome: 'rewritten' | 'unchanged' | 'skipped' | 'failed';
+
+  /**
+   * 结果说明（failed 含原因；skipped 说明灯位缺失等）
+   */
+  message: string;
+};
+
+/**
+ * 头部解析产物
+ */
+type ParsedHeader = {
+  /**
+   * 字段键值对（保序）
+   */
+  fields: Array<{ key: string; value: string }>;
+
+  /**
+   * residual 行（解析不成字段的行，原样保留）
+   */
+  residuals: string[];
+
+  /**
+   * 头部结束行下标（正文起点）
+   */
+  bodyStartIndex: number;
+};
+
+/**
+ * 解析头部方言（四种形态逐行尝试）
+ *
+ * @param lines - 文档行数组
+ * @returns 头部解析产物
+ */
+function parseHeaderDialect(lines: string[]): ParsedHeader {
+  /**
+   * 字段收集器
+   */
+  const fields: Array<{ key: string; value: string }> = [];
+
+  /**
+   * residual 收集器
+   */
+  const residuals: string[] = [];
+
+  /**
+   * 头部结束行下标（首个 `## ` 标题或空行后首段正文起点）
+   */
+  let bodyStartIndex = lines.length;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    /**
+     * 当前行
+     */
+    const line = lines[index] ?? '';
+
+    if (line.startsWith('## ') || (line === '' && fields.length > 0 && index > 4)) {
+      bodyStartIndex = index;
+
+      break;
+    }
+
+    if (line === '' || line.startsWith('# ')) {
+      continue;
+    }
+
+    /**
+     * 形态三：`## 键: 值` 标题式（历史方言，`##` 单井号）
+     */
+    const headingMatch = /^##\s+([^：:]{1,8})\s*[：:]\s*(.+)$/.exec(line);
+
+    if (headingMatch !== null) {
+      fields.push({ key: headingMatch[1]?.trim() ?? '', value: headingMatch[2]?.trim() ?? '' });
+
+      continue;
+    }
+
+    /**
+     * 形态二/四：粗体标签行 / 列表式
+     */
+    const labeledMatch = /^(?:\*\*|- )([^*：:]{1,8})(?:\*\*)?\s*[：:]\s*(.+)$/.exec(line);
+
+    if (labeledMatch !== null) {
+      fields.push({ key: labeledMatch[1]?.trim() ?? '', value: labeledMatch[2]?.trim() ?? '' });
+
+      continue;
+    }
+
+    /**
+     * 形态一：单行管道引用行（`> 优先级 ｜ 状态 ｜ …`）
+     */
+    if (line.startsWith('>')) {
+      /**
+       * 管道分段
+       */
+      const segments = line
+        .slice(1)
+        .split(/[｜|]/)
+        .map((segment) => segment.trim());
+
+      for (const segment of segments) {
+        /**
+         * 段内键值切分
+         */
+        const pairMatch = /^([^：:]{1,8})\s*[：:]\s*(.+)$/.exec(segment);
+
+        if (pairMatch !== null) {
+          fields.push({ key: pairMatch[1]?.trim() ?? '', value: pairMatch[2]?.trim() ?? '' });
+        } else {
+          residuals.push(segment);
+        }
+      }
+
+      continue;
+    }
+
+    residuals.push(line);
+  }
+
+  return { fields, residuals, bodyStartIndex };
+}
+
+/**
+ * 字段排序键
+ *
+ * @param key - 字段键
+ * @param firstSeenRank - 首现序
+ * @returns 排序键（规范序 + 首现序）
+ */
+function fieldSortKey(key: string, firstSeenRank: number): number {
+  return FIELD_RANK[key] ?? 1000 + firstSeenRank;
+}
+
+/**
+ * 迁移形态
+ */
+export type NormalizeOutcome = 'rewritten' | 'unchanged' | 'skipped';
+
+/**
+ * 迁移产物
+ */
+export type NormalizeResult = {
+  /**
+   * 产物全文
+   */
+  content: string;
+
+  /**
+   * 迁移形态
+   */
+  outcome: NormalizeOutcome;
+};
+
+/**
+ * 迁移单份文档头部
+ *
+ * @param raw - 文档全文
+ * @returns 迁移产物
+ */
+export function normalizeHeader(raw: string): NormalizeResult {
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 头部解析产物
+   */
+  const parsed = parseHeaderDialect(lines);
+
+  /**
+   * 「状态」字段定位（无状态行 skipped——灯位属语义判断，不猜灯）
+   */
+  const hasStatus = parsed.fields.some((field) => field.key === '状态');
+
+  if (!hasStatus) {
+    return { content: raw, outcome: 'skipped' };
+  }
+
+  /**
+   * 首现序表
+   */
+  const firstSeen = new Map<string, number>();
+
+  parsed.fields.forEach((field, index) => {
+    if (!firstSeen.has(field.key)) {
+      firstSeen.set(field.key, index);
+    }
+  });
+
+  /**
+   * 规范序字段列表（稳定排序）
+   */
+  const sortedFields = [...parsed.fields].sort((a, b) => {
+    /**
+     * 左右排序键
+     */
+    const left = fieldSortKey(a.key, firstSeen.get(a.key) ?? 0);
+
+    /**
+     * 右字段排序键
+     */
+    const right = fieldSortKey(b.key, firstSeen.get(b.key) ?? 0);
+
+    return left === right ? 0 : left - right;
+  });
+
+  /**
+   * 规范头部行（粗体标签逐行 + residual 殿后原样保留）
+   */
+  const headerLines = [
+    ...sortedFields.map((field) => `**${field.key}**: ${field.value}`),
+    ...parsed.residuals,
+  ];
+
+  /**
+   * 产物全文（标题行保留 + 规范头部 + 正文余文）
+   */
+  const titleEndIndex = lines.findIndex((line, index) => index > 0 && line.startsWith('# '));
+
+  /**
+   * 标题区行（首个一级标题及其前空行）
+   */
+  const titleLines = lines.slice(0, titleEndIndex === -1 ? 1 : titleEndIndex);
+
+  /**
+   * 产物全文
+   */
+  const content = [
+    ...titleLines,
+    '',
+    ...headerLines,
+    '',
+    ...lines.slice(parsed.bodyStartIndex),
+  ].join('\n');
+
+  if (content === raw) {
+    return { content: raw, outcome: 'unchanged' };
+  }
+
+  return { content, outcome: 'rewritten' };
+}
+
+/**
+ * 零丢失守卫：每字段键值必须在产物文本在场
+ *
+ * @param parsed - 头部解析产物
+ * @param content - 产物全文
+ * @returns 缺失字段键列表（空 = 通过）
+ */
+function findLostFields(parsed: ParsedHeader, content: string): string[] {
+  return parsed.fields
+    .filter((field) => !content.includes(`**${field.key}**: ${field.value}`))
+    .map((field) => field.key);
+}
+
+/**
+ * 迁移并落盘单份文档（守卫失败不落盘）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.file - issue 文件仓库相对路径
+ * @returns 单文件迁移结果
+ */
+export function normalizeHeaderFile(input: NormalizeHeaderFileInput): NormalizeHeaderResult {
+  /**
+   * 文档全文
+   */
+  let raw = '';
+
+  try {
+    raw = readFileSync(join(input.root, input.file), 'utf8');
+  } catch {
+    return { file: input.file, outcome: 'failed', message: '读档失败（文件不存在或不可读）' };
+  }
+
+  /**
+   * 迁移产物
+   */
+  const normalized = normalizeHeader(raw);
+
+  if (normalized.outcome === 'skipped') {
+    return {
+      file: input.file,
+      outcome: 'skipped',
+      message: '无可识别状态行且未给 --status——灯位属语义判断，不猜灯',
+    };
+  }
+
+  if (normalized.outcome === 'unchanged') {
+    return { file: input.file, outcome: 'unchanged', message: '头部已是规范形态' };
+  }
+
+  /**
+   * 零丢失守卫
+   */
+  const lost = findLostFields(parseHeaderDialect(raw.split(/\r?\n/)), normalized.content);
+
+  if (lost.length > 0) {
+    return {
+      file: input.file,
+      outcome: 'failed',
+      message: `零丢失守卫失败：字段 ${lost.join('、')} 未在产物在场——不落盘`,
+    };
+  }
+
+  writeFileSync(join(input.root, input.file), normalized.content);
+
+  return { file: input.file, outcome: 'rewritten', message: '头部已迁移为规范形态' };
+}