@longzai-intelligence-issues/ledger 0.0.1 → 0.0.2

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

@@ -10,6 +10,8 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { CANONICAL_STATUS_LABELS } from '@/parser/format.utils';
+
 /**
  * 字段规范序（排名值越小越靠前；未入表字段按首现序殿后）
  */
@@ -35,6 +37,12 @@ export type NormalizeHeaderFileInput = {
    * issue 文件仓库相对路径
    */
   file: string;
+
+  /**
+   * 无可识别状态行时的显式灯位（--status 语义；frozen 不在此通道——冻结唯一合法
+   * 写入路径是 freeze 命令，其裁定语硬门不可绕过）
+   */
+  status?: 'red' | 'yellow' | 'green' | 'canceled';
 };
 
 /**
@@ -60,7 +68,7 @@ export type NormalizeHeaderResult = {
 /**
  * 头部解析产物
  */
-type ParsedHeader = {
+export type ParsedHeader = {
   /**
    * 字段键值对（保序）
    */
@@ -78,12 +86,12 @@ type ParsedHeader = {
 };
 
 /**
- * 解析头部方言（四种形态逐行尝试）
+ * 解析头部方言（五种形态逐行尝试：粗体标签 / 列表式 / 标题式 / 管道引用行 / 表格）
  *
  * @param lines - 文档行数组
  * @returns 头部解析产物
  */
-function parseHeaderDialect(lines: string[]): ParsedHeader {
+export function parseHeaderDialect(lines: string[]): ParsedHeader {
   /**
    * 字段收集器
    */
@@ -149,6 +157,11 @@ function parseHeaderDialect(lines: string[]): ParsedHeader {
         .split(/[｜|]/)
         .map((segment) => segment.trim());
 
+      /**
+       * 未命中键值的段（零段命中时整行原样入 residual——保 `> ` 前缀原貌）
+       */
+      const unmatched: string[] = [];
+
       for (const segment of segments) {
         /**
          * 段内键值切分
@@ -158,10 +171,70 @@ function parseHeaderDialect(lines: string[]): ParsedHeader {
         if (pairMatch !== null) {
           fields.push({ key: pairMatch[1]?.trim() ?? '', value: pairMatch[2]?.trim() ?? '' });
         } else {
-          residuals.push(segment);
+          unmatched.push(segment);
         }
       }
 
+      if (unmatched.length === segments.length) {
+        residuals.push(line);
+      } else {
+        residuals.push(...unmatched);
+      }
+
+      continue;
+    }
+
+    /**
+     * 形态五：表格方言（两列表 `| 键 | 值 |`；表头行与分隔行为表格脚手架，键值
+     * 提取后丢弃——脚手架无独立语义，保留会在规范头部产出破碎表格残片）
+     */
+    const tableMatch = /^\|([^|]*)\|([^|]*)\|$/.exec(line.trim());
+
+    if (tableMatch !== null) {
+      /**
+       * 键单元格 / 值单元格
+       */
+      const keyCell = (tableMatch[1] ?? '').trim();
+
+      /**
+       * 值单元格（数据行切键值的值侧）
+       */
+      const valueCell = (tableMatch[2] ?? '').trim();
+
+      /**
+       * 分隔行形态（单元格仅 dashes/colons——`| --- | --- |`）
+       */
+      const separatorCellPattern = /^:?-{2,}:?$/;
+
+      /**
+       * 本行是否分隔行
+       */
+      const isSeparator =
+        separatorCellPattern.test(keyCell) && separatorCellPattern.test(valueCell);
+
+      /**
+       * 次行（表头行判定：分隔行紧前的一行是表头）
+       */
+      const nextMatch = /^\|([^|]*)\|([^|]*)\|$/.exec((lines[index + 1] ?? '').trim());
+
+      /**
+       * 次行是否表格分隔行（当前行为表头行的判定依据）
+       */
+      const nextIsTableSeparator =
+        nextMatch !== null &&
+        separatorCellPattern.test((nextMatch[1] ?? '').trim()) &&
+        separatorCellPattern.test((nextMatch[2] ?? '').trim());
+
+      if (isSeparator || (nextIsTableSeparator && keyCell !== '')) {
+        continue;
+      }
+
+      if (keyCell !== '') {
+        fields.push({ key: keyCell, value: valueCell });
+      } else {
+        residuals.push(line);
+      }
+
       continue;
     }
 
@@ -187,6 +260,16 @@ function fieldSortKey(key: string, firstSeenRank: number): number {
  */
 export type NormalizeOutcome = 'rewritten' | 'unchanged' | 'skipped';
 
+/**
+ * normalizeHeader 迁移选项（无可识别状态行时的显式灯位注入）
+ */
+export type NormalizeHeaderOptions = {
+  /**
+   * 显式灯位（--status 语义；frozen 不在此通道——冻结唯一合法写入路径是 freeze）
+   */
+  status?: NormalizeHeaderFileInput['status'];
+};
+
 /**
  * 迁移产物
  */
@@ -206,9 +289,10 @@ export type NormalizeResult = {
  * 迁移单份文档头部
  *
  * @param raw - 文档全文
+ * @param options - 迁移选项（无可识别状态行时的显式灯位注入）
  * @returns 迁移产物
  */
-export function normalizeHeader(raw: string): NormalizeResult {
+export function normalizeHeader(raw: string, options?: NormalizeHeaderOptions): NormalizeResult {
   /**
    * 文档行数组
    */
@@ -220,12 +304,19 @@ export function normalizeHeader(raw: string): NormalizeResult {
   const parsed = parseHeaderDialect(lines);
 
   /**
-   * 「状态」字段定位（无状态行 skipped——灯位属语义判断，不猜灯）
+   * 「状态」字段定位（无状态行且未给 --status 则 skipped——灯位属语义判断，不猜灯）
    */
   const hasStatus = parsed.fields.some((field) => field.key === '状态');
 
   if (!hasStatus) {
-    return { content: raw, outcome: 'skipped' };
+    if (options?.status === undefined) {
+      return { content: raw, outcome: 'skipped' };
+    }
+
+    /**
+     * 显式灯位注入（--status）：以规范标签落状态行，排入 FIELD_RANK 规范序
+     */
+    parsed.fields.push({ key: '状态', value: CANONICAL_STATUS_LABELS[options.status] });
   }
 
   /**
@@ -328,7 +419,7 @@ export function normalizeHeaderFile(input: NormalizeHeaderFileInput): NormalizeH
   /**
    * 迁移产物
    */
-  const normalized = normalizeHeader(raw);
+  const normalized = normalizeHeader(raw, { status: input.status });
 
   if (normalized.outcome === 'skipped') {
     return {

package/src/numbering/numbering.core.ts

@@ -325,9 +325,9 @@ export type ScopeScanInput = {
   allowlist: readonly NumberingAllowlistEntry[];
 
   /**
-   * slug 数字策略（'forbid' 启用判定）
+   * slug 数字策略（'forbid' 启用判定；'allow' 整域放行跳过判定）
    */
-  slugDigitPolicy?: 'forbid';
+  slugDigitPolicy?: 'forbid' | 'allow';
 
   /**
    * slug 数字白名单 glob（仓库相对路径命中豁免）
@@ -503,7 +503,7 @@ export function scanScopeForFindings(input: ScopeScanInput): NumberingFinding[]
     });
   });
 
-  if (input.slugDigitPolicy === 'forbid') {
+  if (input.slugDigitPolicy !== 'allow') {
     /**
      * slug 白名单命中集合（全量档失效对账用）
      */

package/src/parser/format.utils.ts

@@ -131,6 +131,82 @@ export const CANONICAL_STATUS_LABELS: Readonly<
   canceled: '⚫ 已取消',
 };
 
+/**
+ * pre-emoji 存量状态词表（写侧迁移单一真源）
+ *
+ * 读侧归类（classifyStatusLine）不消费本词表——旧词表形态归 unknown 由 lint
+ * status-line-missing 拦截，迁移经由 migrate-legacy 写侧规范化后回归规范五态，
+ * 避免为读侧新增 legacy-red 等形态破坏 IssueStatus 契约面。
+ */
+export const LEGACY_STATUS_VOCABULARY: Readonly<{
+  /**
+   * 绿系词（历史已结案标记）
+   */
+  green: readonly string[];
+
+  /**
+   * 红系词（历史待办标记）
+   */
+  red: readonly string[];
+
+  /**
+   * 延期系词（已登记（延期）族——迁移默认回红灯并保留延期说明）
+   */
+  deferred: readonly string[];
+
+  /**
+   * 取消系词
+   */
+  canceled: readonly string[];
+
+  /**
+   * 进行系词（黄灯候选）
+   */
+  inProgress: readonly string[];
+
+  /**
+   * 冻结系词（不迁移——冻结唯一合法写入路径是 freeze 命令）
+   */
+  frozen: readonly string[];
+}> = {
+  green: [
+    '已解决',
+    '已修复',
+    '已治理',
+    '已处理',
+    '已处置',
+    '已完成',
+    '已闭合',
+    '已消解',
+    '已闭环',
+    '已清治',
+    '已收口',
+    '已根治',
+    '已终态',
+    '已裁决',
+    '已决策',
+    '已验证',
+    '已全部清治',
+    '全量完成',
+    '终态达成',
+  ],
+  red: [
+    '未处理',
+    '待处理',
+    '待治理',
+    '待修复',
+    '未修复',
+    '待验证',
+    '待评估',
+    '紧急',
+    '已立项待治理',
+  ],
+  deferred: ['已登记'],
+  canceled: ['已取消'],
+  inProgress: ['处理中', '进行中'],
+  frozen: ['已冻结'],
+};
+
 /**
  * issue 引用 token 形态
  *

package/src/template/issue-template.renderer.ts

@@ -241,13 +241,24 @@ export function renderCriteriaBlockExample(): string {
 /**
  * 渲染注册表 README 格式存根（init 命令落盘）
  *
- * 一页式格式速览：建档入口、状态行五态、正文四段；完整规范指向格式真源指南。
+ * 一页式格式速览：建档入口、状态行五态、正文四段；完整规范指向格式真源指南
+ * （采用仓不携带指南文件时回退机器真源提示，不落死链）。
  *
  * @param scopeTitle - scope 人类可读名
- * @param guideRelPath - 格式指南相对本注册表目录的路径（如 `../../docs/guides/issue-file-format.md`）
+ * @param guideRelPath - 格式指南相对本注册表目录的路径；指南不在采用仓时为 null
  * @returns README 存根全文
  */
-export function renderRegistryReadmeStub(scopeTitle: string, guideRelPath: string): string {
+export function renderRegistryReadmeStub(scopeTitle: string, guideRelPath: string | null): string {
+  /**
+   * 指南指引行（链接形态或机器真源回退形态）
+   */
+  const guideLine =
+    guideRelPath === null
+      ? '- 标准模板：`lzi-issues template`（字段契约 `--format json`）；完整格式规范见 lzi-issues 仓 docs/guides/issue-file-format.md（本仓未携带指南文件，不落链接）'
+      : '- 标准模板：`lzi-issues template`；完整格式规范：[issue-file-format](' +
+        guideRelPath +
+        ')';
+
   return [
     `# ${scopeTitle} issue 注册表`,
     '',
@@ -256,7 +267,7 @@ export function renderRegistryReadmeStub(scopeTitle: string, guideRelPath: strin
     '## 建档',
     '',
     '- `lzi-issues create --title <标题> --scope <key>`（编号走门禁取号，禁止手工定号）',
-    '- 标准模板：`lzi-issues template`；完整格式规范：[issue-file-format](' + guideRelPath + ')',
+    guideLine,
     '',
     '## 状态行（处理情况第一入口）',
     '',