@longzai-intelligence-issues/ledger 0.0.1

package/src/parser/registry.parser.ts

@@ -0,0 +1,679 @@
+/**
+ * issue 注册表解析器（读侧唯一入口）
+ *
+ * 文件名级收集 + 头部状态行 / 处置段 / criteria 围栏块 / 沿革阻塞引用抽取。
+ * 零子进程、零网络；全部口径来自 format.utils 单一真源。
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  BLOCKING_LINE_KEY,
+  buildMetaLineLocatePattern,
+  classifyStatusLine,
+  CRITERIA_CHANNEL_PATTERN,
+  CRITERIA_FENCE_CLOSE_PATTERN,
+  CRITERIA_FENCE_OPEN_PATTERN,
+  DISPOSITION_PLACEHOLDER_PATTERN,
+  DISPOSITION_PLACEHOLDER_WINDOW_LINES,
+  DISPOSITION_TITLE_KEYWORD,
+  EVIDENCE_ANCHOR_MARKERS,
+  extractIssueRefTokens,
+  HISTORY_LINE_KEY,
+  IssueRefToken,
+  IssueStatusKind,
+  PENDING_REASON_PATTERN,
+  REGISTRY_FILE_PATTERN,
+  STATUS_LINE_LOCATE_PATTERN,
+  STATUS_LINE_SCAN_LINES,
+} from './format.utils.js';
+
+/**
+ * criteria 判据条目（一行一判据，四段竖线分隔）
+ */
+export type ParsedCriterion = {
+  /**
+   * 判据标签（人类可读名）
+   */
+  label: string;
+
+  /**
+   * 判据通道（证书库的通道维度）
+   */
+  channel: string;
+
+  /**
+   * 判据工作目录（相对仓库根）
+   */
+  cwd: string;
+
+  /**
+   * 判据命令（退出码即判据）
+   */
+  command: string;
+};
+
+/**
+ * criteria 围栏块解析产物
+ */
+export type ParsedCriteriaBlock = {
+  /**
+   * 概要行（唯一非空；缺席为 null）
+   */
+  summary: string | null;
+
+  /**
+   * 判据条目列表（至少一条）
+   */
+  criteria: ParsedCriterion[];
+};
+
+/**
+ * issue 文档解析产物（IssueDocRecord）
+ */
+export type IssueDocRecord = {
+  /**
+   * 编号（文件名 3-4 位数字前缀）
+   */
+  id: string;
+
+  /**
+   * slug（文件名剥前缀与扩展名）
+   */
+  slug: string;
+
+  /**
+   * 文件名（basename）
+   */
+  file: string;
+
+  /**
+   * 标题（首个 `# ` 行内容；缺席为空串）
+   */
+  title: string;
+
+  /**
+   * 状态归类
+   */
+  status: IssueStatusKind;
+
+  /**
+   * 状态行全文（未定位为空串）
+   */
+  statusLine: string;
+
+  /**
+   * 状态行行号（1 起；未定位为 0）
+   */
+  statusLineNumber: number;
+
+  /**
+   * 挂起原因（状态行首个 ≥4 字括注；缺席为 null）
+   */
+  pendingReason: string | null;
+
+  /**
+   * 是否存在处置段标题
+   */
+  hasDispositionSection: boolean;
+
+  /**
+   * 处置段是否命中占位模式（标题起 8 行窗口）
+   */
+  dispositionIsPlaceholder: boolean;
+
+  /**
+   * 证据锚点块是否在位
+   */
+  hasEvidenceAnchorBlock: boolean;
+
+  /**
+   * criteria 围栏块解析产物（块在位且解析成功）
+   */
+  criteria: ParsedCriteriaBlock | null;
+
+  /**
+   * criteria 围栏块解析错误消息（块缺席为 null；多块/畸形带行号）
+   */
+  criteriaError: string | null;
+
+  /**
+   * 沿革引用 token 列表
+   */
+  historyRefs: IssueRefToken[];
+
+  /**
+   * 阻塞引用 token 列表
+   */
+  blockedByRefs: IssueRefToken[];
+
+  /**
+   * 文档全文
+   */
+  rawContent: string;
+
+  /**
+   * 文件 mtime（毫秒；账龄计算口径）
+   */
+  modifiedAtMs: number;
+};
+
+/**
+ * criteria 围栏块范围定位
+ */
+type CriteriaBlockRange = {
+  /**
+   * 开栏行下标（0 起）
+   */
+  start: number;
+
+  /**
+   * 闭栏行下标（0 起）
+   */
+  end: number;
+};
+
+/**
+ * 注册表文件名解析产物
+ */
+export type RegistryFileNameParts = {
+  /**
+   * 编号（3-4 位零填充）
+   */
+  id: string;
+
+  /**
+   * slug 段
+   */
+  slug: string;
+};
+
+/**
+ * 解析文件名为编号与 slug
+ *
+ * @param file - 文件名（basename）
+ * @returns 编号与 slug；不符合收集口径返回 null
+ */
+export function parseRegistryFileName(file: string): RegistryFileNameParts | null {
+  /**
+   * 收集口径命中结果
+   */
+  const match = /^([0-9]{3,4})-(.+)\.md$/.exec(file);
+
+  if (match === null) {
+    return null;
+  }
+
+  return {
+    id: match[1] ?? '',
+    slug: match[2] ?? '',
+  };
+}
+
+/**
+ * 定位全部 criteria 围栏块范围
+ *
+ * @param lines - 文档行数组
+ * @returns 围栏块范围列表（未闭合块以 end = -1 标记）
+ */
+function locateCriteriaBlockRanges(lines: string[]): CriteriaBlockRange[] {
+  /**
+   * 已开栏待闭范围收集器
+   */
+  const ranges: CriteriaBlockRange[] = [];
+
+  /**
+   * 当前未闭合开栏行下标
+   */
+  let openIndex = -1;
+
+  lines.forEach((line, index) => {
+    if (openIndex === -1) {
+      if (CRITERIA_FENCE_OPEN_PATTERN.test(line)) {
+        openIndex = index;
+      }
+
+      return;
+    }
+
+    if (CRITERIA_FENCE_CLOSE_PATTERN.test(line)) {
+      ranges.push({ start: openIndex, end: index });
+      openIndex = -1;
+    }
+  });
+
+  if (openIndex !== -1) {
+    ranges.push({ start: openIndex, end: -1 });
+  }
+
+  return ranges;
+}
+
+/**
+ * 解析 criteria 围栏块（宁可拒收不可猜）
+ *
+ * 全文必须单块唯一；`summary:` 唯一非空；判据行四段逐段非空、channel 合法、
+ * 段内禁多余竖线；块内至少一条判据。所有违规抛带行号错误。
+ *
+ * @param raw - 文档全文
+ * @returns 围栏块解析产物
+ * @throws {@link Error} 块缺席 / 多块 / 未闭合 / 行内违规（错误消息含行号）
+ */
+export function parseCriteriaBlock(raw: string): ParsedCriteriaBlock {
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 围栏块范围列表
+   */
+  const ranges = locateCriteriaBlockRanges(lines);
+
+  if (ranges.length === 0) {
+    throw new Error('未找到 criteria 围栏块（```criteria 开栏）');
+  }
+
+  if (ranges.length > 1) {
+    /**
+     * 第二块开栏行号（1 起）
+     */
+    const secondOpenLine = (ranges[1]?.start ?? 0) + 1;
+
+    throw new Error(`criteria 围栏块必须唯一：第 ${secondOpenLine} 行出现第二块`);
+  }
+
+  /**
+   * 唯一块范围
+   */
+  const range = ranges[0];
+
+  if (range === undefined) {
+    throw new Error('未找到 criteria 围栏块（```criteria 开栏）');
+  }
+
+  if (range.end === -1) {
+    throw new Error(`criteria 围栏块未闭合（第 ${range.start + 1} 行开栏后无闭栏）`);
+  }
+
+  /**
+   * 概要行内容
+   */
+  let summary: string | null = null;
+
+  /**
+   * 概要行出现次数
+   */
+  let summaryCount = 0;
+
+  /**
+   * 判据条目收集器
+   */
+  const criteria: ParsedCriterion[] = [];
+
+  for (let index = range.start + 1; index < range.end; index += 1) {
+    /**
+     * 当前块内行
+     */
+    const line = lines[index] ?? '';
+
+    /**
+     * 当前行行号（1 起）
+     */
+    const lineNumber = index + 1;
+
+    if (line.trim() === '' || line.trimStart().startsWith('#')) {
+      continue;
+    }
+
+    if (line.startsWith('summary:')) {
+      /**
+       * 概要值
+       */
+      const value = line.slice('summary:'.length).trim();
+
+      if (value === '') {
+        throw new Error(`第 ${lineNumber} 行 summary 值为空（须唯一且非空）`);
+      }
+
+      summaryCount += 1;
+
+      if (summaryCount > 1) {
+        throw new Error(`第 ${lineNumber} 行 summary 重复（summary 行必须唯一）`);
+      }
+
+      summary = value;
+
+      continue;
+    }
+
+    /**
+     * 判据行四段切分结果
+     */
+    const segments = line.split('|');
+
+    if (segments.length !== 4) {
+      throw new Error(
+        `第 ${lineNumber} 行判据须为四段 label|channel|cwd|command（命令含竖线须以脚本承载）`,
+      );
+    }
+
+    /**
+     * 判据标签段
+     */
+    const label = (segments[0] ?? '').trim();
+
+    /**
+     * 判据通道段
+     */
+    const channel = (segments[1] ?? '').trim();
+
+    /**
+     * 判据工作目录段
+     */
+    const cwd = (segments[2] ?? '').trim();
+
+    /**
+     * 判据命令段
+     */
+    const command = (segments[3] ?? '').trim();
+
+    if (label === '' || channel === '' || cwd === '' || command === '') {
+      throw new Error(`第 ${lineNumber} 行判据存在空段（四段逐段非空）`);
+    }
+
+    if (!CRITERIA_CHANNEL_PATTERN.test(channel)) {
+      throw new Error(
+        `第 ${lineNumber} 行 channel「${channel}」不合法（限字母数字起首的 [A-Za-z0-9._-]）`,
+      );
+    }
+
+    criteria.push({ label, channel, cwd, command });
+  }
+
+  if (criteria.length === 0) {
+    throw new Error(`criteria 围栏块内至少一条判据（第 ${range.start + 1} 行块为空）`);
+  }
+
+  return { summary, criteria };
+}
+
+/**
+ * 在头部窗口内定位元信息行并提取引用 token
+ *
+ * @param lines - 文档行数组
+ * @param key - 元信息键
+ * @returns 引用 token 列表（行缺席为空列表）
+ */
+function extractMetaLineRefs(lines: string[], key: string): IssueRefToken[] {
+  /**
+   * 键定位正则
+   */
+  const locatePattern = buildMetaLineLocatePattern(key);
+
+  /**
+   * 扫描窗口上界（头部前 N 行，与状态行窗口一致）
+   */
+  const scanLimit = Math.min(lines.length, STATUS_LINE_SCAN_LINES);
+
+  for (let index = 0; index < scanLimit; index += 1) {
+    /**
+     * 当前行
+     */
+    const line = lines[index] ?? '';
+
+    if (locatePattern.test(line)) {
+      return extractIssueRefTokens(line);
+    }
+  }
+
+  return [];
+}
+
+/**
+ * 解析单份 issue 文档
+ *
+ * @param file - 文件名（basename，用于编号与 slug 提取）
+ * @param raw - 文档全文
+ * @param modifiedAtMs - 文件 mtime（毫秒）
+ * @returns 解析产物（收集口径外的文件返回 null）
+ */
+export function parseIssueDoc(
+  file: string,
+  raw: string,
+  modifiedAtMs: number,
+): IssueDocRecord | null {
+  /**
+   * 文件名解析结果
+   */
+  const nameParts = parseRegistryFileName(file);
+
+  if (nameParts === null) {
+    return null;
+  }
+
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 标题：首个 `# ` 行内容
+   */
+  let title = '';
+
+  for (const line of lines) {
+    if (line.startsWith('# ')) {
+      title = line.slice(2).trim();
+
+      break;
+    }
+  }
+
+  /**
+   * 状态行定位结果
+   */
+  let statusLine = '';
+
+  /**
+   * 状态行行号（1 起，0 = 未定位）
+   */
+  let statusLineNumber = 0;
+
+  /**
+   * 状态归类
+   */
+  let status: IssueStatusKind = 'unknown';
+
+  /**
+   * 状态行扫描窗口上界
+   */
+  const statusScanLimit = Math.min(lines.length, STATUS_LINE_SCAN_LINES);
+
+  for (let index = 0; index < statusScanLimit; index += 1) {
+    /**
+     * 当前行
+     */
+    const line = lines[index] ?? '';
+
+    if (STATUS_LINE_LOCATE_PATTERN.test(line)) {
+      statusLine = line.trim();
+      statusLineNumber = index + 1;
+      status = classifyStatusLine(line);
+
+      break;
+    }
+  }
+
+  /**
+   * 挂起原因：状态行首个 ≥4 字括注（无括注或不足 4 字为 null）
+   */
+  const pendingMatch = statusLine === '' ? null : PENDING_REASON_PATTERN.exec(statusLine);
+
+  /**
+   * 挂起原因值
+   */
+  const pendingReason = pendingMatch === null ? null : (pendingMatch[1] ?? '').trim();
+
+  /**
+   * 处置段标题行下标（-1 = 缺席）
+   */
+  let dispositionIndex = -1;
+
+  lines.forEach((line, index) => {
+    if (
+      dispositionIndex === -1 &&
+      line.startsWith('## ') &&
+      line.includes(DISPOSITION_TITLE_KEYWORD)
+    ) {
+      dispositionIndex = index;
+    }
+  });
+
+  /**
+   * 处置段占位判定：标题起 8 行窗口内逐行匹配占位模式
+   */
+  let dispositionIsPlaceholder = false;
+
+  if (dispositionIndex !== -1) {
+    /**
+     * 占位窗口上界
+     */
+    const placeholderLimit = Math.min(
+      lines.length,
+      dispositionIndex + DISPOSITION_PLACEHOLDER_WINDOW_LINES,
+    );
+
+    for (let index = dispositionIndex; index < placeholderLimit; index += 1) {
+      if (DISPOSITION_PLACEHOLDER_PATTERN.test(lines[index] ?? '')) {
+        dispositionIsPlaceholder = true;
+
+        break;
+      }
+    }
+  }
+
+  /**
+   * 证据锚点块在位判定
+   */
+  const hasEvidenceAnchorBlock = EVIDENCE_ANCHOR_MARKERS.some((marker) => raw.includes(marker));
+
+  /**
+   * criteria 围栏块解析（缺席 / 多块 / 畸形记录错误消息，不中断读档）
+   */
+  /**
+   * criteria 围栏块解析产物（块在位且解析成功时非 null）
+   */
+  let criteria: ParsedCriteriaBlock | null = null;
+
+  /**
+   * criteria 围栏块解析错误消息（多块 / 畸形时非 null，不中断读档）
+   */
+  let criteriaError: string | null = null;
+
+  if (locateCriteriaBlockRanges(lines).length > 0) {
+    try {
+      criteria = parseCriteriaBlock(raw);
+    } catch (error) {
+      criteriaError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  return {
+    id: nameParts.id,
+    slug: nameParts.slug,
+    file,
+    title,
+    status,
+    statusLine,
+    statusLineNumber,
+    pendingReason,
+    hasDispositionSection: dispositionIndex !== -1,
+    dispositionIsPlaceholder,
+    hasEvidenceAnchorBlock,
+    criteria,
+    criteriaError,
+    historyRefs: extractMetaLineRefs(lines, HISTORY_LINE_KEY),
+    blockedByRefs: extractMetaLineRefs(lines, BLOCKING_LINE_KEY),
+    rawContent: raw,
+    modifiedAtMs,
+  };
+}
+
+/**
+ * 扫描注册表目录
+ *
+ * 只收集口径内文件（NNNN-slug.md），逐份解析，按编号升序；目录缺席返回空数组；
+ * 单份读档失败降级为 unknown 最小形态（不中断批次，apex 同款语义）。
+ *
+ * @param registryDir - 注册表目录绝对或相对路径
+ * @returns 解析产物列表（编号升序）
+ */
+export function scanRegistryDir(registryDir: string): IssueDocRecord[] {
+  if (!existsSync(registryDir)) {
+    return [];
+  }
+
+  /**
+   * 口径内文件名列表
+   */
+  const files = readdirSync(registryDir)
+    .filter((file) => REGISTRY_FILE_PATTERN.test(file))
+    .sort((a, b) => a.localeCompare(b));
+
+  /**
+   * 解析产物收集器
+   */
+  const records: IssueDocRecord[] = [];
+
+  for (const file of files) {
+    /**
+     * 文档绝对路径
+     */
+    const filePath = join(registryDir, file);
+
+    try {
+      /**
+       * 文档全文
+       */
+      const raw = readFileSync(filePath, 'utf8');
+
+      /**
+       * mtime（毫秒）
+       */
+      const modifiedAtMs = statSync(filePath).mtimeMs;
+
+      /**
+       * 解析产物（口径内文件必非 null）
+       */
+      const record = parseIssueDoc(file, raw, modifiedAtMs);
+
+      if (record !== null) {
+        records.push(record);
+      }
+    } catch {
+      records.push({
+        id: parseRegistryFileName(file)?.id ?? '',
+        slug: parseRegistryFileName(file)?.slug ?? '',
+        file,
+        title: '',
+        status: 'unknown',
+        statusLine: '',
+        statusLineNumber: 0,
+        pendingReason: null,
+        hasDispositionSection: false,
+        dispositionIsPlaceholder: false,
+        hasEvidenceAnchorBlock: false,
+        criteria: null,
+        criteriaError: null,
+        historyRefs: [],
+        blockedByRefs: [],
+        rawContent: '',
+        modifiedAtMs: 0,
+      });
+    }
+  }
+
+  return records;
+}