@longzai-intelligence-issues/ledger 0.0.1

package/src/parser/format.utils.ts

@@ -0,0 +1,279 @@
+/**
+ * issue 注册表格式单一真源
+ *
+ * 全部格式口径（文件名、状态行、处置段、criteria 围栏块、引用形态）的常量与判定
+ * 函数集中于此模块。读侧（解析器 / lint / 收口）与写侧（模板渲染 / 翻绿回填 / 冻结
+ * 写入）共用同一真源，杜绝两套口径漂移——该纪律经 apex-energy-turbo
+ * issue-verify-ledger 长期验证有效后迁移（其 registry.parser.ts 同构实现）。
+ */
+
+/**
+ * 注册表文件收集口径
+ *
+ * 3-4 位零填充数字前缀 + `-` + slug + `.md`；README 等不匹配文件天然不收编。
+ */
+export const REGISTRY_FILE_PATTERN = /^[0-9]{3,4}-.+\.md$/;
+
+/**
+ * slug 合法字符集（单一真源）：仅 ASCII kebab——小写字母、数字、连字符，
+ * 禁中文与任何非 ASCII 字符（与契约层 SlugVO 口径一致）。
+ */
+export const ASCII_KEBAB_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * 状态行前缀正则源（读写共用单一真源）
+ *
+ * 「状态」+ 可选 0-2 个粗体星号 + 可选空白 + 全/半角冒号。以源字符串形态导出，
+ * 写侧改写正则由本源动态构造，保证读/写口径永不分裂。
+ */
+export const STATUS_LINE_PREFIX_SOURCE = '状态\\*{0,2}\\s*[：:]';
+
+/**
+ * 状态行定位正则（读侧使用，由前缀源构造）
+ */
+export const STATUS_LINE_LOCATE_PATTERN = new RegExp(STATUS_LINE_PREFIX_SOURCE);
+
+/**
+ * 状态行定位扫描窗口（头部前 N 行）
+ */
+export const STATUS_LINE_SCAN_LINES = 30;
+
+/**
+ * 挂起原因括注提取模式：全/半角括号内至少 4 字符
+ */
+export const PENDING_REASON_PATTERN = /[（(]([^）)]{4,})[）)]/;
+
+/**
+ * 处置段标题关键词
+ *
+ * `## ` 标题行包含本关键词即认定为处置段。
+ */
+export const DISPOSITION_TITLE_KEYWORD = '处置结果';
+
+/**
+ * 处置段占位判定模式（读写共用单一真源）
+ *
+ * 「处置中 / 待回填」后须紧跟右括号 / 标点 / 破折号 / 行尾才计占位——占位是终态
+ * 标签，正文状语（如「处置中新核实的…」后为继续字符）不计。
+ */
+export const DISPOSITION_PLACEHOLDER_PATTERN = /(?:处置中|待回填)(?=[）)：:，,。；;、]|——|$)/;
+
+/**
+ * 处置段占位判定窗口（处置段标题起 N 行）
+ */
+export const DISPOSITION_PLACEHOLDER_WINDOW_LINES = 8;
+
+/**
+ * 证据锚点块在位判定标记
+ *
+ * 两种收口形态的回填标题前缀：零执行证据收口 / 证书化真跑收口。
+ */
+export const EVIDENCE_ANCHOR_MARKERS = ['证据锚点（末次通过零执行收口', '判据执行证据（'] as const;
+
+/**
+ * criteria 围栏块开栏行模式
+ */
+export const CRITERIA_FENCE_OPEN_PATTERN = /^```criteria\s*$/;
+
+/**
+ * criteria 围栏块闭栏行模式
+ */
+export const CRITERIA_FENCE_CLOSE_PATTERN = /^```\s*$/;
+
+/**
+ * criteria 判据行 channel 段合法形态（字母数字起首，限字母数字与 . _ -）
+ */
+export const CRITERIA_CHANNEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * 元信息行「沿革」键：前序 issue 引用载体
+ */
+export const HISTORY_LINE_KEY = '沿革';
+
+/**
+ * 元信息行「阻塞」键：阻塞关系引用载体（全部 🟢 后方可收口）
+ */
+export const BLOCKING_LINE_KEY = '阻塞';
+
+/**
+ * 元信息行键定位前缀源
+ *
+ * 粗体标签（`**沿革**:`）与裸键（`沿革:`）两形态通吃；冒号全/半角均可。
+ */
+export const META_LINE_PREFIX_SOURCE_TEMPLATE = '\\*{0,2}%s\\*{0,2}\\s*[：:]';
+
+/**
+ * issue 状态归类
+ *
+ * 规范五态（red / yellow / green / frozen / canceled）+ 旧格式变体
+ * （legacy-yellow / legacy-green，仅 --strict-legacy 计违规）+ 未知（unknown）。
+ */
+export type IssueStatusKind =
+  | 'red'
+  | 'yellow'
+  | 'green'
+  | 'frozen'
+  | 'canceled'
+  | 'legacy-yellow'
+  | 'legacy-green'
+  | 'unknown';
+
+/**
+ * 规范状态标签（写侧单一真源）
+ */
+export const CANONICAL_STATUS_LABELS: Readonly<
+  Record<'red' | 'yellow' | 'green' | 'frozen' | 'canceled', string>
+> = {
+  red: '🔴 待处理',
+  yellow: '🟡 处理中',
+  green: '🟢 已处置',
+  frozen: '⚪ 已冻结',
+  canceled: '⚫ 已取消',
+};
+
+/**
+ * issue 引用 token 形态
+ *
+ * `number` 为 3-4 位编号；`slug` 为可空的不完整 slug 段（纯编号引用无 slug）。
+ */
+export type IssueRefToken = {
+  /**
+   * 引用编号（3-4 位零填充）
+   */
+  number: string;
+
+  /**
+   * 引用 slug 段（纯编号引用时为 null）
+   */
+  slug: string | null;
+};
+
+/**
+ * issue 引用 token 提取模式
+ *
+ * 命中 markdown 链接 label 与纯文本两种形态：`[0035](./0035-xxx.md)` 与 `[0035]`，
+ * 以及行内代码中的不完整 slug 前缀 `[0035-slug-pre]` 形态。链接目标（第三捕获组）
+ * 作为 slug 兜底来源——label 只有编号时从目标文件名 `NNNN-slug.md` 反解 slug。
+ */
+export const ISSUE_REF_TOKEN_PATTERN = /\[([0-9]{3,4})(?:-([a-z0-9-]+))?\](?:\(([^)]*)\))?/g;
+
+/**
+ * 链接目标文件名反解模式（slug 兜底来源）
+ */
+const LINK_TARGET_SLUG_PATTERN = /([0-9]{3,4})-([a-z0-9-]+)\.md/;
+
+/**
+ * 从任意文本行提取 issue 引用 token 列表
+ *
+ * slug 解析优先级：label 内 slug 段 > 链接目标文件名 slug；两者皆无时为 null
+ * （纯编号引用）。
+ *
+ * @param text - 待提取文本（沿革/阻塞行内容、正文段落等）
+ * @returns 按出现顺序去重后的引用 token 列表
+ */
+export function extractIssueRefTokens(text: string): IssueRefToken[] {
+  /**
+   * 命中收集器（保序）
+   */
+  const hits: IssueRefToken[] = [];
+
+  /**
+   * 全局匹配游标（pattern 带 g 标志，须逐次 exec）
+   */
+  const pattern = new RegExp(ISSUE_REF_TOKEN_PATTERN.source, 'g');
+
+  /**
+   * 当前命中结果
+   */
+  let match: RegExpExecArray | null = pattern.exec(text);
+
+  while (match !== null) {
+    /**
+     * 当前命中编号
+     */
+    const number = match[1] ?? '';
+
+    /**
+     * label 内 slug 段
+     */
+    let slug = match[2] ?? null;
+
+    /**
+     * 链接目标（缺席为 null）
+     */
+    const target = match[3] ?? null;
+
+    if (slug === null && target !== null) {
+      /**
+       * 目标文件名 slug 反解结果
+       */
+      const targetMatch = LINK_TARGET_SLUG_PATTERN.exec(target);
+
+      slug = targetMatch?.[2] ?? null;
+    }
+
+    /**
+     * 去重判定：同 number+slug 已收集则跳过
+     */
+    const duplicated = hits.some((hit) => hit.number === number && hit.slug === slug);
+
+    if (!duplicated) {
+      hits.push({ number, slug });
+    }
+
+    match = pattern.exec(text);
+  }
+
+  return hits;
+}
+
+/**
+ * 构造元信息行键定位正则
+ *
+ * @param key - 元信息键（如「沿革」「阻塞」）
+ * @returns 行首锚定的键定位正则
+ */
+export function buildMetaLineLocatePattern(key: string): RegExp {
+  return new RegExp(`^\\*{0,2}${key}\\*{0,2}\\s*[：:]`);
+}
+
+/**
+ * 状态行归类
+ *
+ * 归类优先级：已冻结 > 🔴 > ⚫ > 🟡 处理中 > 🟡（旧格式）> 🟢 已处置 > 🟢/✅（旧格式）>
+ * 未知。未识别形态归 unknown（与「无状态行」同判，lint 由 status-line-missing 拦截）。
+ *
+ * @param line - 状态行全文
+ * @returns 状态归类
+ */
+export function classifyStatusLine(line: string): IssueStatusKind {
+  if (line.includes('已冻结')) {
+    return 'frozen';
+  }
+
+  if (line.includes('🔴')) {
+    return 'red';
+  }
+
+  if (line.includes('⚫')) {
+    return 'canceled';
+  }
+
+  if (/🟡\s*处理中/.test(line)) {
+    return 'yellow';
+  }
+
+  if (line.includes('🟡')) {
+    return 'legacy-yellow';
+  }
+
+  if (/🟢\s*已处置/.test(line)) {
+    return 'green';
+  }
+
+  if (line.includes('🟢') || line.includes('✅')) {
+    return 'legacy-green';
+  }
+
+  return 'unknown';
+}

package/src/parser/guide-fixture.utils.ts

@@ -0,0 +1,117 @@
+/**
+ * 格式指南夹具工具（零漂移守卫的切片面）
+ *
+ * 格式真源指南（docs/guides/issue-file-format.md）内的活样板以 HTML 注释标记
+ * 圈定边界；本模块负责定位指南文件、切片活样板，供测试与渲染器比对——
+ * 「写指南即写测试，改解析器必改指南」（apex guide-fixture 同款机制）。
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * 活样板起点标记
+ */
+export const GUIDE_FIXTURE_START_MARK = '<!-- issue-file-format-fixture:start -->';
+
+/**
+ * 活样板终点标记
+ */
+export const GUIDE_FIXTURE_END_MARK = '<!-- issue-file-format-fixture:end -->';
+
+/**
+ * 格式指南相对项目根路径
+ */
+export const ISSUE_FILE_FORMAT_GUIDE_RELATIVE = 'docs/guides/issue-file-format.md';
+
+/**
+ * 指南向上查找最大层数
+ */
+const GUIDE_LOCATE_MAX_DEPTH = 10;
+
+/**
+ * 定位格式指南绝对路径
+ *
+ * 从本模块运行位置逐级向上查找 `docs/guides/issue-file-format.md`（源码运行与
+ * dist 构建产物两种位置均可命中；上限 10 层防失控上溯）。
+ *
+ * @returns 指南绝对路径
+ * @throws {@link Error} 超出查找上限仍未命中
+ */
+export function locateIssueFileFormatGuide(): string {
+  /**
+   * 当前查找目录
+   */
+  let currentDir = dirname(resolve(import.meta.url.replace('file://', '')));
+
+  for (let depth = 0; depth < GUIDE_LOCATE_MAX_DEPTH; depth += 1) {
+    /**
+     * 当前层指南候选路径
+     */
+    const candidate = join(currentDir, ISSUE_FILE_FORMAT_GUIDE_RELATIVE);
+
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+
+    /**
+     * 上一级目录（根目录判定：上溯不变即停）
+     */
+    const parent = dirname(currentDir);
+
+    if (parent === currentDir) {
+      break;
+    }
+
+    currentDir = parent;
+  }
+
+  throw new Error(
+    `未定位到格式指南：${ISSUE_FILE_FORMAT_GUIDE_RELATIVE}（自模块位置向上 ${GUIDE_LOCATE_MAX_DEPTH} 层内）`,
+  );
+}
+
+/**
+ * 读取格式指南全文
+ *
+ * @returns 指南全文
+ */
+export function loadIssueFileFormatGuide(): string {
+  return readFileSync(locateIssueFileFormatGuide(), 'utf8');
+}
+
+/**
+ * 切片指南活样板
+ *
+ * @param guide - 指南全文
+ * @returns 起终点标记之间的活样板文本（去首尾空白行）
+ * @throws {@link Error} 标记缺席或次序颠倒（显式抛错，不静默返回空）
+ */
+export function sliceGuideFixtureSample(guide: string): string {
+  /**
+   * 起点标记下标
+   */
+  const startIndex = guide.indexOf(GUIDE_FIXTURE_START_MARK);
+
+  /**
+   * 终点标记下标
+   */
+  const endIndex = guide.indexOf(GUIDE_FIXTURE_END_MARK);
+
+  if (startIndex === -1) {
+    throw new Error(`指南活样板起点标记缺席：${GUIDE_FIXTURE_START_MARK}`);
+  }
+
+  if (endIndex === -1) {
+    throw new Error(`指南活样板终点标记缺席：${GUIDE_FIXTURE_END_MARK}`);
+  }
+
+  if (endIndex < startIndex) {
+    throw new Error('指南活样板标记次序颠倒（终点在起点之前）');
+  }
+
+  return guide
+    .slice(startIndex + GUIDE_FIXTURE_START_MARK.length, endIndex)
+    .replace(/^\n+/, '')
+    .replace(/\n+$/, '');
+}