@longzai-intelligence-issues/ledger 0.0.1 → 0.0.2

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

@@ -0,0 +1,519 @@
+import { parseLziIssuesConfig } from '@longzai-intelligence-issues/config';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { migrateLegacyFile } from '@/migrate/migrate-legacy.commands';
+
+/**
+ * 测试夹具根（包内临时目录）
+ */
+const FIXTURE_ROOT = join(import.meta.dir, '__tmp-migrate__');
+
+/**
+ * 注册表目录
+ */
+const REGISTRY_REL = 'docs/issues';
+
+/**
+ * 基准配置（scope root）
+ */
+const config = parseLziIssuesConfig({
+  schemaVersion: 1,
+  scopes: [
+    {
+      key: 'root',
+      title: '项目全局',
+      paths: ['.'],
+      registryDir: REGISTRY_REL,
+    },
+  ],
+});
+
+/**
+ * 写入注册表文件
+ *
+ * @param name - 文件名
+ * @param content - 文档全文
+ */
+function writeIssue(name: string, content: string): void {
+  mkdirSync(join(FIXTURE_ROOT, REGISTRY_REL), { recursive: true });
+
+  writeFileSync(join(FIXTURE_ROOT, REGISTRY_REL, name), content);
+}
+
+/**
+ * 基准迁移入参（dry-run 只读形态）
+ *
+ * @param file - 仓库相对文件路径
+ * @returns 命令入参
+ */
+function input(file: string) {
+  return {
+    root: FIXTURE_ROOT,
+    file,
+    config,
+    defaultPriority: 'P2' as const,
+    defaultSource: '格式清偿迁移回填（2026-09-14）：原案未登记来源',
+    dryRun: true,
+  };
+}
+
+/**
+ * 列表方言（KTV 主流形态）样例
+ */
+const LIST_DIALECT_GREEN = [
+  '# 0400 - roles-matrix 观测两行 deny 错误码红于 deny-first 校验先行分叉族',
+  '',
+  '- 日期：2026-08-27',
+  '- 来源：docs/issues/0390 治理 sweep 复跑发现',
+  '- 状态：**已治理（2026-08-27 同日：守门与口径对齐完成）**',
+  '- 严重程度：中',
+  '- 影响包：packages/api',
+  '',
+  '## 现象',
+  '',
+  '正文。',
+  '',
+  '## 验证结果',
+  '',
+  '验证正文：lint 全绿。',
+].join('\n');
+
+/**
+ * 表格方言（KTV 最新形态）样例
+ */
+const TABLE_DIALECT = [
+  '# 0549 check:testing-coverage 门禁存在 15 处既有违规',
+  '',
+  '| 元数据 | 内容 |',
+  '| --- | --- |',
+  '| Issue 编号 | 0549 |',
+  '| 日期 | 2026-09-14 |',
+  '| 状态 | 已处理 |',
+  '| 来源 | 门禁收尾时发现 |',
+  '| 配对决策 | 无（纯欠账清偿） |',
+  '',
+  '## 现象',
+  '',
+  '正文。',
+  '',
+  '## 治理记录',
+  '',
+  '治理正文。',
+].join('\n');
+
+/**
+ * 粗体旧式（KTV 最老形态）样例
+ */
+const BOLD_DIALECT_RED = [
+  '# StreamableFile 与 typedResponse 类型不兼容问题',
+  '',
+  '**日期**: 2026-06-13',
+  '**状态**: 未处理',
+  '**涉及文件**: `apps/nest-server/src/x.ts`',
+  '',
+  '## 问题描述',
+  '',
+  '正文。',
+].join('\n');
+
+beforeEach(() => {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+});
+
+describe('migrateLegacyFile 存量清偿（dry-run 只读）', () => {
+  test('列表方言：状态规范化 + 字段别名 + 处置段标题链 + 必填回填', () => {
+    writeIssue('0400-roles-matrix-deny-divergence.md', LIST_DIALECT_GREEN);
+
+    const result = migrateLegacyFile(input(`${REGISTRY_REL}/0400-roles-matrix-deny-divergence.md`));
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain(
+      '**状态**: 🟢 已处置（2026-08-27 同日：守门与口径对齐完成；原「已治理」）',
+    );
+    expect(result.content).toContain('**立案日期**: 2026-08-27');
+    expect(result.content).toContain('**优先级**: P2');
+    expect(result.content).toContain('**所属域**: 项目全局');
+    expect(result.content).toContain('**来源**: docs/issues/0390 治理 sweep 复跑发现');
+    expect(result.content).toContain('**严重程度**: 中');
+    expect(result.content).toContain('**影响包**: packages/api');
+    expect(result.content).toContain('## 处置结果/验证口径');
+    expect(result.content).toContain('验证正文：lint 全绿。');
+    expect(result.content).toContain('## 现象');
+    expect(result.content.startsWith('# 0400 - ')).toBe(true);
+  });
+
+  test('表格方言：数据行提取为字段、脚手架丢弃、治理记录对齐处置段', () => {
+    writeIssue('0549-testing-coverage-gate.md', TABLE_DIALECT);
+
+    const result = migrateLegacyFile(input(`${REGISTRY_REL}/0549-testing-coverage-gate.md`));
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain('**状态**: 🟢 已处置（原「已处理」）');
+    expect(result.content).toContain('**Issue 编号**: 0549');
+    expect(result.content).toContain('**配对决策**: 无（纯欠账清偿）');
+    expect(result.content).toContain('## 处置结果/治理记录');
+    expect(result.content.includes('| --- | --- |')).toBe(false);
+    expect(result.content.includes('| 元数据 | 内容 |')).toBe(false);
+  });
+
+  test('粗体旧式：红灯映射 + H1 补编号 + 无验证段红灯不追加处置段', () => {
+    writeIssue('0001-streamablefile-typed-response.md', BOLD_DIALECT_RED);
+
+    const result = migrateLegacyFile(
+      input(`${REGISTRY_REL}/0001-streamablefile-typed-response.md`),
+    );
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain('**状态**: 🔴 待处理（原「未处理」）');
+    expect(result.content).toContain('**立案日期**: 2026-06-13');
+    expect(result.content).toContain('**来源**: 格式清偿迁移回填（2026-09-14）：原案未登记来源');
+    expect(result.content).toContain('**涉及文件**: `apps/nest-server/src/x.ts`');
+    expect(result.content.startsWith('# 0001 - StreamableFile')).toBe(true);
+    expect(result.content.includes('处置结果/')).toBe(false);
+  });
+
+  test('绿灯但处置段占位：降级黄灯并给挂起原因', () => {
+    writeIssue(
+      '0300-green-placeholder.md',
+      [
+        '# 0300 - 样例',
+        '',
+        '- 日期：2026-08-01',
+        '- 状态：已治理',
+        '- 来源：会话记录',
+        '',
+        '## 验证结果',
+        '',
+        '（待回填）',
+      ].join('\n'),
+    );
+
+    const result = migrateLegacyFile(input(`${REGISTRY_REL}/0300-green-placeholder.md`));
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain(
+      '**状态**: 🟡 处理中（历史标记已处置但验证口径为占位，清偿时待核实；原「已治理」）',
+    );
+    expect(result.content).toContain('## 处置结果/验证口径');
+  });
+
+  test('候选段词汇表：落地治理/治理记录（带日期）/验证（治理后）/修复 均命中改名链，计划性段名不误吞', () => {
+    /**
+     * 落地治理族样例（KTV 真实段名词汇）
+     */
+    writeIssue(
+      '0320-landing-governance.md',
+      [
+        '# 0320 - 样例',
+        '',
+        '- 日期：2026-08-03',
+        '- 状态：已治理',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+        '',
+        '## 落地治理',
+        '',
+        '治理正文。',
+        '',
+        '## 修复方向',
+        '',
+        '计划正文（不应被改名）。',
+      ].join('\n'),
+    );
+
+    /**
+     * 治理记录带日期样例
+     */
+    writeIssue(
+      '0321-dated-record.md',
+      [
+        '# 0321 - 样例',
+        '',
+        '- 日期：2026-08-04',
+        '- 状态：已治理',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+        '',
+        '## 治理记录（2026-08-31）',
+        '',
+        '记录正文。',
+      ].join('\n'),
+    );
+
+    const first = migrateLegacyFile(input(`${REGISTRY_REL}/0320-landing-governance.md`));
+
+    expect(first.outcome).toBe('rewritten');
+    expect(first.content).toContain('## 处置结果/治理记录');
+    expect(first.content).toContain('## 修复方向');
+    expect(first.content).toContain('计划正文（不应被改名）。');
+    expect(first.content.includes('处置结果/验证口径')).toBe(false);
+
+    const second = migrateLegacyFile(input(`${REGISTRY_REL}/0321-dated-record.md`));
+
+    expect(second.outcome).toBe('rewritten');
+    expect(second.content).toContain('## 处置结果/治理记录');
+  });
+
+  test('绿灯无任何候选验证段：追加处置段与事实回填说明', () => {
+    writeIssue(
+      '0310-green-nosection.md',
+      [
+        '# 0310 - 样例',
+        '',
+        '- 日期：2026-08-02',
+        '- 状态：已解决',
+        '- 来源：会话记录',
+        '',
+        '## 解决方案',
+        '',
+        '改了 X。',
+      ].join('\n'),
+    );
+
+    const result = migrateLegacyFile(input(`${REGISTRY_REL}/0310-green-nosection.md`));
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain('## 处置结果/变更记录');
+    expect(result.content).toContain('## 处置结果/验证口径');
+  });
+
+  test('无状态行且未注入灯位：skipped 交人工', () => {
+    writeIssue('0547-anomaly.md', '# 0547 · 无元信息异类\n\n## 现象\n\n正文。\n');
+
+    const result = migrateLegacyFile(input(`${REGISTRY_REL}/0547-anomaly.md`));
+
+    expect(result.outcome).toBe('skipped');
+  });
+
+  test('无状态行 + status 注入（green）：规范标签落位且处置段对齐执行', () => {
+    writeIssue(
+      '0350-status-inject.md',
+      [
+        '# Git 换行符问题分析与处理',
+        '',
+        '## 问题描述',
+        '',
+        '正文。',
+        '',
+        '## 解决方案',
+        '',
+        '已落地 .gitattributes 统一换行。',
+      ].join('\n'),
+    );
+
+    const result = migrateLegacyFile({
+      ...input(`${REGISTRY_REL}/0350-status-inject.md`),
+      status: 'green',
+      defaultFilingDate: '2026-06-13',
+    });
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain(
+      '**状态**: 🟢 已处置（存量清偿定档：原案无状态行，依结案内容人工定档）',
+    );
+    expect(result.content).toContain('**立案日期**: 2026-06-13');
+    expect(result.content).toContain('## 处置结果/变更记录');
+    expect(result.content).toContain('## 处置结果/验证口径');
+    expect(result.content.startsWith('# 0350 - Git 换行符')).toBe(true);
+  });
+
+  test('H1 编号句点分隔符变体（# 0279. 标题）规范为 # 0279 - 标题且守卫通过', () => {
+    writeIssue(
+      '0279-dot-separator.md',
+      [
+        '# 0279. 包厢预订配置页默认值全 0：分组缺 defaultValue 建模',
+        '',
+        '- 日期：2026-08-10',
+        '- 状态：已治理',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+        '',
+        '## 验证结果',
+        '',
+        '验证正文。',
+      ].join('\n'),
+    );
+
+    const result = migrateLegacyFile(input(`${REGISTRY_REL}/0279-dot-separator.md`));
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content.startsWith('# 0279 - 包厢预订配置页默认值全 0')).toBe(true);
+    expect(result.content.includes('0279.')).toBe(false);
+  });
+
+  test('状态值粗体形态三变体（全包裹/前导无尾随/词中包裹）均可命中词表', () => {
+    writeIssue(
+      '0330-bold-variants.md',
+      [
+        '# 0330 - 样例',
+        '',
+        '- 日期：2026-08-21',
+        '- 状态：**已治理（2026-08-21，commit 57a2d80ef9）',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+        '',
+        '## 治理记录',
+        '',
+        '治理正文。',
+      ].join('\n'),
+    );
+
+    writeIssue(
+      '0331-bold-word-wrap.md',
+      [
+        '# 0331 - 样例',
+        '',
+        '- 日期：2026-08-25',
+        '- 状态：**已治理**（2026-08-25 同日收口）',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+        '',
+        '## 验证结果',
+        '',
+        '验证正文。',
+      ].join('\n'),
+    );
+
+    const first = migrateLegacyFile(input(`${REGISTRY_REL}/0330-bold-variants.md`));
+
+    expect(first.outcome).toBe('rewritten');
+    expect(first.content).toContain(
+      '**状态**: 🟢 已处置（2026-08-21，commit 57a2d80ef9；原「已治理」）',
+    );
+
+    const second = migrateLegacyFile(input(`${REGISTRY_REL}/0331-bold-word-wrap.md`));
+
+    expect(second.outcome).toBe('rewritten');
+    expect(second.content).toContain('**状态**: 🟢 已处置（2026-08-25 同日收口；原「已治理」）');
+  });
+
+  test('规范词无 emoji 形态（已处置/已完成/已闭合）命中绿系词表', () => {
+    writeIssue(
+      '0334-canonical-word-no-emoji.md',
+      [
+        '# 0334 - 样例',
+        '',
+        '| 元数据 | 内容 |',
+        '| --- | --- |',
+        '| 状态 | 已处置（单例化修复 + e2e 复绿） |',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+        '',
+        '## 验证结果',
+        '',
+        '验证正文。',
+      ].join('\n'),
+    );
+
+    const result = migrateLegacyFile({
+      ...input(`${REGISTRY_REL}/0334-canonical-word-no-emoji.md`),
+      defaultFilingDate: '2026-09-01',
+    });
+
+    expect(result.outcome).toBe('rewritten');
+    expect(result.content).toContain('**状态**: 🟢 已处置（单例化修复 + e2e 复绿；原「已处置」）');
+  });
+
+  test('扩展词表：待处理/未修复/已收口/已根治/终态达成 等命中', () => {
+    writeIssue(
+      '0332-vocab-extended.md',
+      [
+        '# 0332 - 样例',
+        '',
+        '- 日期：2026-08-22',
+        '- 状态：已收口（2026-08-19，D-3 维持现状）',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+      ].join('\n'),
+    );
+
+    writeIssue(
+      '0333-vocab-red.md',
+      [
+        '# 0333 - 样例',
+        '',
+        '- 日期：2026-08-23',
+        '- 状态：未修复（本次质量检查发现并归档，待用户决策修复范围）',
+        '- 来源：会话记录',
+        '',
+        '## 现象',
+        '',
+        '正文。',
+      ].join('\n'),
+    );
+
+    const first = migrateLegacyFile(input(`${REGISTRY_REL}/0332-vocab-extended.md`));
+
+    expect(first.outcome).toBe('rewritten');
+    expect(first.content).toContain(
+      '**状态**: 🟢 已处置（2026-08-19，D-3 维持现状；原「已收口」）',
+    );
+
+    const second = migrateLegacyFile(input(`${REGISTRY_REL}/0333-vocab-red.md`));
+
+    expect(second.outcome).toBe('rewritten');
+    expect(second.content).toContain(
+      '🔴 待处理（本次质量检查发现并归档，待用户决策修复范围；原「未修复」）',
+    );
+  });
+
+  test('幂等：对已规范产物重跑 unchanged', () => {
+    writeIssue('0400-roles-matrix-deny-divergence.md', LIST_DIALECT_GREEN);
+
+    /**
+     * 第一轮落盘
+     */
+    const first = migrateLegacyFile({
+      ...input(`${REGISTRY_REL}/0400-roles-matrix-deny-divergence.md`),
+      dryRun: false,
+    });
+
+    expect(first.outcome).toBe('rewritten');
+
+    /**
+     * 第二轮对产物重跑
+     */
+    const second = migrateLegacyFile(input(`${REGISTRY_REL}/0400-roles-matrix-deny-divergence.md`));
+
+    expect(second.outcome).toBe('unchanged');
+  });
+
+  test('dry-run 不落盘', () => {
+    writeIssue('0001-streamablefile-typed-response.md', BOLD_DIALECT_RED);
+
+    migrateLegacyFile(input(`${REGISTRY_REL}/0001-streamablefile-typed-response.md`));
+
+    expect(
+      readFileSync(
+        join(FIXTURE_ROOT, REGISTRY_REL, '0001-streamablefile-typed-response.md'),
+        'utf8',
+      ),
+    ).toBe(BOLD_DIALECT_RED);
+  });
+});

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

@@ -130,4 +130,14 @@ describe('renderRegistryReadmeStub', () => {
     expect(stub.includes('🔴 待处理')).toBe(true);
     expect(stub.includes('⚪ 已冻结')).toBe(true);
   });
+
+  test('指南不在采用仓时（null）回退机器真源提示且不含死链', () => {
+    const stub = renderRegistryReadmeStub('项目全局', null);
+
+    expect(stub.includes('# 项目全局 issue 注册表')).toBe(true);
+    expect(stub.includes('lzi-issues template')).toBe(true);
+    expect(stub.includes('docs/guides/issue-file-format.md')).toBe(true);
+    expect(stub.includes('](../')).toBe(false);
+    expect(stub.includes('](../../')).toBe(false);
+  });
 });

package/src/index.ts

@@ -29,6 +29,10 @@ export * from './lint/lint.core.js';
 
 export * from './normalize/normalize-header.commands.js';
 
+export * from './migrate/migrate-legacy.commands.js';
+
+export * from './migrate/migrate-legacy.core.js';
+
 export * from './numbering/numbering.commands.js';
 
 export * from './numbering/numbering.core.js';

package/src/lint/lint.core.ts

@@ -259,6 +259,17 @@ export const CORE_LINT_RULES: readonly LintRule[] = [
         return null;
       }
 
+      /**
+       * 所属 scope 数字政策（allow 档位整域放行，缺省 forbid 走白名单例外通道）
+       */
+      const scopePolicy = ctx.config.scopes.find(
+        (scope) => scope.key === ctx.scopeKey,
+      )?.slugDigitPolicy;
+
+      if (scopePolicy === 'allow') {
+        return null;
+      }
+
       /**
        * 仓库相对路径（白名单匹配口径）
        */
@@ -273,7 +284,7 @@ export const CORE_LINT_RULES: readonly LintRule[] = [
 
       return whitelisted
         ? null
-        : `slug 段含数字（白名单登记请到配置 slugDigitAllowlist）：${record.file}`;
+        : `slug 段含数字（scope 政策 slugDigitPolicy 或白名单 slugDigitAllowlist 登记）：${record.file}`;
     },
   },
   {