@longzai-intelligence-issues/ledger 0.0.1

package/src/__tests__/lint/lint.core.test.ts

@@ -0,0 +1,332 @@
+import { parseLziIssuesConfig } from '@longzai-intelligence-issues/config';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { runWriteLintBaseline } from '@/lint/lint-baseline.commands';
+import { registerLintRulePack, runLint, scanOrphanSidecars } from '@/lint/lint.core';
+import { renderIssueTemplate } from '@/template/issue-template.renderer';
+
+/**
+ * 测试夹具根（包内临时目录）
+ */
+const FIXTURE_ROOT = join(import.meta.dir, '__tmp-lint__');
+
+/**
+ * 注册表目录
+ */
+const REGISTRY_REL = 'docs/issues';
+
+/**
+ * 写入注册表文件
+ *
+ * @param name - 文件名
+ * @param content - 文档全文
+ */
+function writeIssue(name: string, content: string): void {
+  writeFileSync(join(FIXTURE_ROOT, REGISTRY_REL, name), content);
+}
+
+/**
+ * 基准配置文本（scope root + slug 白名单 + strictLegacy 可变体）
+ */
+const BASE_INPUT = {
+  schemaVersion: 1,
+  scopes: [
+    {
+      key: 'root',
+      title: '全局',
+      paths: ['.'],
+      registryDir: REGISTRY_REL,
+    },
+  ],
+};
+
+/**
+ * 解析配置（覆盖变体）
+ */
+const parseConfig = (overrides: Record<string, unknown> = {}) =>
+  parseLziIssuesConfig({ ...BASE_INPUT, ...overrides });
+
+/**
+ * 干净骨架样例（模板 instance 渲染——新案形态）
+ */
+const CLEAN_INSTANCE = renderIssueTemplate({
+  number: '0100',
+  slug: 'clean-case',
+  title: '干净样例',
+  priority: 'P2',
+  scopeTitle: '全局',
+  date: '2026-09-14',
+  source: '测试夹具',
+});
+
+/**
+ * 写入夹具目录树（基线三态用例外的全部规则样例）
+ */
+function writeFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+  mkdirSync(join(FIXTURE_ROOT, REGISTRY_REL), { recursive: true });
+
+  writeIssue('0100-clean-case.md', CLEAN_INSTANCE);
+  writeIssue('0002-no-status.md', '# 0002 - 无状态行\n\n正文\n');
+  writeIssue('0003-yellow-noreason.md', '# 0003 - 黄灯无原因\n\n**状态**: 🟡 处理中\n');
+  writeIssue('0004-green-nodispo.md', '# 0004 - 绿灯缺处置段\n\n**状态**: 🟢 已处置（完成）\n');
+  writeIssue(
+    '0005-green-placeholder.md',
+    [
+      '# 0005 - 处置段占位',
+      '',
+      '**状态**: 🟢 已处置（完成）',
+      '',
+      '## 四、处置结果/验证口径',
+      '',
+      '（处置中）',
+    ].join('\n'),
+  );
+  writeIssue(
+    '0006-fake-flip.md',
+    [
+      '# 0006 - 手工翻绿',
+      '',
+      '**状态**: 🟢 已处置（完成——判据证据锚点见处置段）',
+      '',
+      '## 四、处置结果/验证口径',
+      '',
+      '已修复。',
+    ].join('\n'),
+  );
+  writeIssue('0007-frozen-bad.md', '# 0007 - 冻结不规范\n\n**状态**: 已冻结（临时搁置）\n');
+  writeIssue('0008-model-v2.md', '# 0008 - slug 含数字\n\n**状态**: 🔴 待处理\n');
+  writeIssue('0009-canceled-noreason.md', '# 0009 - 取消无原因\n\n**状态**: ⚫ 已取消\n');
+  writeIssue(
+    '0011-blocking-ghost.md',
+    '# 0011 - 阻塞引用缺失\n\n**状态**: 🔴 待处理\n\n**阻塞**: [0099](./0099-ghost.md)\n',
+  );
+  writeIssue('0012-legacy-yellow.md', '# 0012 - 旧格式黄灯\n\n**状态**: 🟡 某旧写法\n');
+  writeIssue('0013-中文-slug.md', '# 0013 - 中文 slug\n\n**状态**: 🔴 待处理\n');
+}
+
+/**
+ * 清理夹具
+ */
+function cleanFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+}
+
+beforeEach(writeFixture);
+
+afterEach(cleanFixture);
+
+describe('runLint 核心规则', () => {
+  test('新落盘骨架实跑 lint 零违规（模板零漂移机检承诺）', () => {
+    const result = runLint({ root: FIXTURE_ROOT, config: parseConfig() });
+
+    const cleanViolations = result.violations.filter((v) => v.file.includes('0100-clean-case'));
+
+    expect(cleanViolations).toEqual([]);
+  });
+
+  test('各规则正例逐一命中', () => {
+    const result = runLint({ root: FIXTURE_ROOT, config: parseConfig() });
+
+    /**
+     * 规则 → 命中文件断言表
+     */
+    const expected: Record<string, string> = {
+      'status-line-missing': '0002-no-status.md',
+      'yellow-no-pending-reason': '0003-yellow-noreason.md',
+      'green-no-disposition-section': '0004-green-nodispo.md',
+      'green-disposition-placeholder': '0005-green-placeholder.md',
+      'green-canonical-no-evidence-block': '0006-fake-flip.md',
+      'frozen-format': '0007-frozen-bad.md',
+      'frozen-no-adjudication-note': '0007-frozen-bad.md',
+      'issue-slug-contains-digit': '0008-model-v2.md',
+      'issue-slug-non-ascii': '0013-中文-slug.md',
+      'canceled-no-reason': '0009-canceled-noreason.md',
+      'blocking-ref-unknown': '0011-blocking-ghost.md',
+    };
+
+    for (const [rule, filePart] of Object.entries(expected)) {
+      expect(
+        result.violations.some((v) => v.rule === rule && v.file.includes(filePart)),
+        `${rule} 应命中 ${filePart}`,
+      ).toBe(true);
+    }
+  });
+
+  test('legacy 变体仅 strictLegacy 计违规', () => {
+    const off = runLint({ root: FIXTURE_ROOT, config: parseConfig() });
+
+    expect(off.violations.some((v) => v.rule === 'status-line-legacy-format')).toBe(false);
+
+    const on = runLint({
+      root: FIXTURE_ROOT,
+      config: parseConfig({ lint: { strictLegacy: true } }),
+    });
+
+    expect(
+      on.violations.some(
+        (v) => v.rule === 'status-line-legacy-format' && v.file.includes('0012-legacy-yellow'),
+      ),
+    ).toBe(true);
+  });
+
+  test('slug 白名单豁免', () => {
+    const result = runLint({
+      root: FIXTURE_ROOT,
+      config: parseConfig({
+        slugDigitAllowlist: [{ glob: 'docs/issues/0008-model-v2.md', reason: '既有编号语义' }],
+      }),
+    });
+
+    expect(result.violations.some((v) => v.rule === 'issue-slug-contains-digit')).toBe(false);
+  });
+
+  test('orphan-sidecar：评论边车指向不存在 issue', () => {
+    mkdirSync(join(FIXTURE_ROOT, '.lzi/issues/comments/root'), { recursive: true });
+
+    writeFileSync(
+      join(FIXTURE_ROOT, '.lzi/issues/comments/root/0100.json'),
+      JSON.stringify({ items: [{ issueId: '0099' }] }),
+    );
+
+    const result = runLint({ root: FIXTURE_ROOT, config: parseConfig() });
+
+    expect(result.violations.some((v) => v.rule === 'orphan-sidecar')).toBe(true);
+  });
+
+  test('目录级孤儿边车扫描（注册表无对应文件）', () => {
+    mkdirSync(join(FIXTURE_ROOT, '.lzi/issues/comments/root'), { recursive: true });
+
+    writeFileSync(
+      join(FIXTURE_ROOT, '.lzi/issues/comments/root/0098.json'),
+      JSON.stringify({ items: [] }),
+    );
+
+    const orphans = scanOrphanSidecars(FIXTURE_ROOT, parseConfig());
+
+    expect(orphans).toHaveLength(1);
+    expect(orphans[0]?.rule).toBe('orphan-sidecar');
+    expect(orphans[0]?.message).toContain('0098');
+  });
+});
+
+describe('runLint 规则包扩展点', () => {
+  test('注册并启用的规则包生效；未启用不生效', () => {
+    registerLintRulePack('fixture-pack', [
+      {
+        name: 'fixture-custom-rule',
+        evaluate: (record) => (record.id === '0100' ? '夹具自定义规则命中' : null),
+      },
+    ]);
+
+    const enabled = runLint({
+      root: FIXTURE_ROOT,
+      config: parseConfig({ lint: { rulePacks: ['fixture-pack'] } }),
+    });
+
+    expect(enabled.violations.some((v) => v.rule === 'fixture-custom-rule')).toBe(true);
+
+    const disabled = runLint({ root: FIXTURE_ROOT, config: parseConfig() });
+
+    expect(disabled.violations.some((v) => v.rule === 'fixture-custom-rule')).toBe(false);
+  });
+});
+
+describe('runLint 棘轮基线三态', () => {
+  test('命中豁免 suppressed / 基线外 active / 陈旧条目 stale', () => {
+    /**
+     * 豁免一条现行违规（0003 黄灯无原因）+ 登记一条已修复存量（陈旧）
+     */
+    const config = parseConfig({
+      lint: {
+        baseline: [
+          {
+            file: `${REGISTRY_REL}/0003-yellow-noreason.md`,
+            rule: 'yellow-no-pending-reason',
+            issue: '0050',
+          },
+          {
+            file: `${REGISTRY_REL}/0888-fixed-legacy.md`,
+            rule: 'yellow-no-pending-reason',
+            issue: '0051',
+          },
+        ],
+      },
+    });
+
+    const result = runLint({ root: FIXTURE_ROOT, config });
+
+    expect(result.suppressed).toBe(1);
+    expect(result.baselineCount).toBe(2);
+
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'yellow-no-pending-reason' && v.file.includes('0003'),
+      ),
+    ).toBe(false);
+
+    expect(result.violations.some((v) => v.rule === 'baseline-stale')).toBe(true);
+
+    expect(
+      result.violations.some((v) => v.rule === 'status-line-missing' && v.file.includes('0002')),
+    ).toBe(true);
+  });
+});
+
+describe('runWriteLintBaseline 拒绝扩基线', () => {
+  test('存在基线外新增违规拒绝再生', () => {
+    const config = parseConfig({
+      lint: {
+        baseline: [
+          {
+            file: `${REGISTRY_REL}/0003-yellow-noreason.md`,
+            rule: 'yellow-no-pending-reason',
+            issue: '0050',
+          },
+        ],
+      },
+    });
+
+    const result = runWriteLintBaseline({
+      root: FIXTURE_ROOT,
+      config,
+      issuePointer: '0060',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toContain('拒绝再生');
+  });
+
+  test('无新增违规时再生（现行全集重建基线）', () => {
+    /**
+     * 基线覆盖全部现行违规的配置——用全集违规预生成
+     */
+    const allViolations = runLint({
+      root: FIXTURE_ROOT,
+      config: parseConfig(),
+      ignoreBaseline: true,
+    }).violations;
+
+    const config = parseConfig({
+      lint: {
+        baseline: allViolations.map((v) => ({
+          file: v.file,
+          rule: v.rule,
+          issue: '0050',
+        })),
+      },
+    });
+
+    const result = runWriteLintBaseline({
+      root: FIXTURE_ROOT,
+      config,
+      issuePointer: '0060',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.ok === true && result.entryCount).toBe(allViolations.length);
+    expect(result.ok === true && result.content).toContain('棘轮只许缩短');
+  });
+});

package/src/__tests__/numbering/numbering.commands.test.ts

@@ -0,0 +1,194 @@
+import type { LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { parseLziIssuesConfig } from '@longzai-intelligence-issues/config';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  runNumberingAudit,
+  runNumberingCheck,
+  runNumberingNext,
+} from '@/numbering/numbering.commands';
+
+/**
+ * 命令测试夹具根（包内临时目录）
+ */
+const FIXTURE_ROOT = join(import.meta.dir, '__tmp-numbering__');
+
+/**
+ * 解析后的测试配置
+ */
+const CONFIG: LziIssuesConfig = parseLziIssuesConfig({
+  schemaVersion: 1,
+  scopes: [
+    {
+      key: 'root',
+      title: '全局',
+      paths: ['.'],
+      registryDir: 'docs/issues',
+      numbering: { reserved: [{ number: '0081', reason: '历史空洞不回收' }] },
+      slugDigitPolicy: 'forbid',
+    },
+    {
+      key: 'domains',
+      title: '领域层',
+      paths: ['domains/**'],
+      registryDir: 'docs/domain-issues',
+    },
+  ],
+  numbering: {
+    audit: {
+      roots: ['docs'],
+      numberishPattern: '^\\d{1,4}[-._]',
+      pending: [{ glob: 'docs/reports/*.md', reason: '报告族规划中' }],
+    },
+  },
+  slugDigitAllowlist: [],
+});
+
+/**
+ * 写入夹具目录树
+ */
+function writeFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+
+  for (const dir of ['docs/issues', 'docs/domain-issues', 'docs/reports', 'docs/decisions']) {
+    mkdirSync(join(FIXTURE_ROOT, dir), { recursive: true });
+  }
+
+  const files: Record<string, string> = {
+    'docs/issues/0001-first-case.md': '',
+    'docs/issues/0002-second-case.md': '',
+    'docs/issues/README.md': '',
+    'docs/domain-issues/0001-domain-case.md': '',
+    'docs/reports/0003-report.md': '',
+    'docs/decisions/0004-decision.md': '',
+  };
+
+  for (const [rel, content] of Object.entries(files)) {
+    writeFileSync(join(FIXTURE_ROOT, rel), content);
+  }
+}
+
+/**
+ * 清理夹具
+ */
+function cleanFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+}
+
+beforeEach(writeFixture);
+
+afterEach(cleanFixture);
+
+describe('runNumberingNext', () => {
+  test('scope 模式：max+1 顺延', () => {
+    const result = runNumberingNext({ root: FIXTURE_ROOT, config: CONFIG, scopeKey: 'root' });
+
+    expect(result.ok).toBe(true);
+    expect(result.ok === true && result.number).toBe('0003');
+    expect(result.ok === true && result.target).toBe('root');
+  });
+
+  test('dir 模式：目录即目标', () => {
+    const result = runNumberingNext({
+      root: FIXTURE_ROOT,
+      config: CONFIG,
+      dirRel: 'docs/domain-issues',
+    });
+
+    expect(result.ok === true && result.number).toBe('0002');
+  });
+
+  test('未登记 scope 报错', () => {
+    const result = runNumberingNext({ root: FIXTURE_ROOT, config: CONFIG, scopeKey: 'ghost' });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toContain('未登记');
+  });
+
+  test('未登记目录报错', () => {
+    const result = runNumberingNext({ root: FIXTURE_ROOT, config: CONFIG, dirRel: 'docs/unknown' });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test('互斥校验', () => {
+    const both = runNumberingNext({
+      root: FIXTURE_ROOT,
+      config: CONFIG,
+      scopeKey: 'root',
+      dirRel: 'docs/issues',
+    });
+
+    expect(both.ok).toBe(false);
+  });
+});
+
+describe('runNumberingCheck', () => {
+  test('全量档：干净夹具零违例', () => {
+    const result = runNumberingCheck({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(result.findings).toEqual([]);
+    expect(result.scopeCount).toBe(2);
+    expect(result.scannedFiles).toBe(4);
+  });
+
+  test('增量档：单目录判定', () => {
+    const result = runNumberingCheck({
+      root: FIXTURE_ROOT,
+      config: CONFIG,
+      dirRel: 'docs/issues',
+    });
+
+    expect(result.scopeCount).toBe(1);
+    expect(result.scannedFiles).toBe(3);
+  });
+
+  test('保留号占用全量档报违规', () => {
+    writeFileSync(join(FIXTURE_ROOT, 'docs/issues/0081-hole.md'), '');
+
+    const result = runNumberingCheck({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(result.findings.some((f) => f.kind === 'reservedOccupied')).toBe(true);
+  });
+
+  test('撞号在增量档同样拦截', () => {
+    writeFileSync(join(FIXTURE_ROOT, 'docs/domain-issues/0001-dup-a.md'), '');
+    writeFileSync(join(FIXTURE_ROOT, 'docs/domain-issues/0001-dup-b.md'), '');
+
+    const result = runNumberingCheck({
+      root: FIXTURE_ROOT,
+      config: CONFIG,
+      dirRel: 'docs/domain-issues',
+    });
+
+    expect(result.findings.some((f) => f.kind === 'duplicate')).toBe(true);
+  });
+});
+
+describe('runNumberingAudit', () => {
+  test('未覆盖编号区按目录聚合，pending 覆盖免报', () => {
+    const result = runNumberingAudit({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0]?.kind).toBe('coverageGap');
+    expect(result.findings[0]?.message).toContain('docs/decisions');
+    expect(result.findings[0]?.message).not.toContain('docs/reports');
+    expect(result.scannedFiles).toBe(6);
+  });
+
+  test('审计根缺失抛错（防扫描面缩水）', () => {
+    expect(() =>
+      runNumberingAudit({
+        root: FIXTURE_ROOT,
+        config: parseLziIssuesConfig({
+          schemaVersion: 1,
+          scopes: CONFIG.scopes,
+          numbering: { audit: { roots: ['missing-root'] } },
+        }),
+      }),
+    ).toThrow('扫描面目录缺失');
+  });
+});