@longzai-intelligence-issues/ledger 0.0.1

package/src/__tests__/docs-refs/docs-refs.commands.test.ts

@@ -0,0 +1,213 @@
+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 { runDocsCheck, runDocsFix, runWriteDocsBaseline } from '@/docs-refs/docs-refs.commands';
+
+/**
+ * 测试夹具根（包内临时目录）
+ */
+const FIXTURE_ROOT = join(import.meta.dir, '__tmp-docsrefs__');
+
+/**
+ * 解析后的测试配置
+ */
+const CONFIG = parseLziIssuesConfig({
+  schemaVersion: 1,
+  scopes: [
+    { key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/issues' },
+    { key: 'domains', title: '领域层', paths: ['domains/**'], registryDir: 'docs/domain-issues' },
+  ],
+  docs: { scanRoots: ['docs-guides'] },
+});
+
+/**
+ * 写入夹具：两 scope 注册表 + 引用文档
+ */
+function writeFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+
+  for (const dir of ['docs/issues', 'docs/domain-issues', 'docs-guides']) {
+    mkdirSync(join(FIXTURE_ROOT, dir), { recursive: true });
+  }
+
+  writeFileSync(join(FIXTURE_ROOT, 'docs/issues/0048-runs-list-grace.md'), '**状态**: 🔴 待处理\n');
+  writeFileSync(join(FIXTURE_ROOT, 'docs/issues/0050-alpha-one.md'), '**状态**: 🔴 待处理\n');
+  writeFileSync(join(FIXTURE_ROOT, 'docs/issues/0050-alpha-two.md'), '**状态**: 🔴 待处理\n');
+  writeFileSync(
+    join(FIXTURE_ROOT, 'docs/domain-issues/0048-domain-variant.md'),
+    '**状态**: 🔴 待处理\n',
+  );
+
+  /**
+   * 引用文档：完整 / 纯编号多义 / 唯一前缀（两种粒度）/ 前缀撞车 / 未知编号
+   */
+  writeFileSync(
+    join(FIXTURE_ROOT, 'docs-guides/guide.md'),
+    [
+      '# 指南',
+      '',
+      '完整引用：[0048-runs-list-grace](./../docs/issues/0048-runs-list-grace.md) 通过。',
+      '纯编号跨 scope 多义：[0048] 应报 ambiguous。',
+      '唯一前缀（短）：[0048-runs] 应通过并可机械展开。',
+      '唯一前缀（长）：[0048-runs-list] 应通过并可机械展开。',
+      '前缀撞车：[0050-alpha] 命中两条，应 refused 交人工。',
+      '未知编号：[0099-ghost]。',
+    ].join('\n'),
+  );
+}
+
+/**
+ * 清理夹具
+ */
+function cleanFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+}
+
+beforeEach(writeFixture);
+
+afterEach(cleanFixture);
+
+describe('runDocsCheck', () => {
+  test('完整引用与唯一前缀通过；多义列候选；未知报 unknown', () => {
+    const result = runDocsCheck({ root: FIXTURE_ROOT, config: CONFIG });
+
+    /**
+     * 规则 → 违例数
+     */
+    const byRule = new Map<string, number>();
+
+    for (const violation of result.violations) {
+      byRule.set(violation.rule, (byRule.get(violation.rule) ?? 0) + 1);
+    }
+
+    expect(byRule.get('doc-ref-ambiguous')).toBe(2);
+    expect(byRule.get('doc-ref-unknown')).toBe(1);
+    expect(result.scannedFiles).toBe(1);
+
+    /**
+     * 纯编号跨 scope 多义报文含 scope 与完整 slug 候选
+     */
+    const pureNumber = result.violations.find(
+      (v) => v.rule === 'doc-ref-ambiguous' && v.message.includes('引用 0048 '),
+    );
+
+    expect(pureNumber?.message).toContain('root/0048-runs-list-grace');
+    expect(pureNumber?.message).toContain('domains/0048-domain-variant');
+  });
+
+  test('未登记 docs 节显式拒绝', () => {
+    expect(() =>
+      runDocsCheck({
+        root: FIXTURE_ROOT,
+        config: parseLziIssuesConfig({
+          schemaVersion: 1,
+          scopes: CONFIG.scopes,
+        }),
+      }),
+    ).toThrow('docs 节');
+  });
+
+  test('棘轮基线三态（豁免/新增红/陈旧红）', () => {
+    /**
+     * 带基线配置：豁免 unknown + 登记一条陈旧
+     */
+    const configWithBaseline = parseLziIssuesConfig({
+      schemaVersion: 1,
+      scopes: CONFIG.scopes,
+      docs: {
+        scanRoots: ['docs-guides'],
+        baseline: [
+          { file: 'docs-guides/guide.md', rule: 'doc-ref-unknown', issue: '0050' },
+          { file: 'docs-guides/other.md', rule: 'doc-ref-unknown', issue: '0051' },
+        ],
+      },
+    });
+
+    const result = runDocsCheck({ root: FIXTURE_ROOT, config: configWithBaseline });
+
+    expect(result.suppressed).toBe(1);
+    expect(result.violations.some((v) => v.rule === 'baseline-stale')).toBe(true);
+    expect(result.violations.some((v) => v.rule === 'doc-ref-unknown')).toBe(false);
+    expect(result.violations.some((v) => v.rule === 'doc-ref-ambiguous')).toBe(true);
+  });
+});
+
+describe('runDocsFix', () => {
+  test('唯一前缀机械展开为完整 slug，撞车 refused 交人工', () => {
+    const result = runDocsFix({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(result.fixedFiles).toEqual(['guide.md']);
+    expect(result.refused).toHaveLength(1);
+    expect(result.refused[0]?.message).toContain('0050-alpha');
+
+    /**
+     * 修复产物：两种粒度前缀均已展开，其余文本不动
+     */
+    const fixed = readFileSync(join(FIXTURE_ROOT, 'docs-guides/guide.md'), 'utf8');
+
+    expect(fixed).toContain('[0048-runs-list-grace](./../docs/issues/0048-runs-list-grace.md)');
+    expect(fixed).toContain('[0048-runs-list-grace] 应通过并可机械展开。');
+    expect(fixed).toContain('[0050-alpha] 命中两条，应 refused 交人工。');
+  });
+
+  test('dry-run 只呈现不落盘', () => {
+    runDocsFix({ root: FIXTURE_ROOT, config: CONFIG, dryRun: true });
+
+    const content = readFileSync(join(FIXTURE_ROOT, 'docs-guides/guide.md'), 'utf8');
+
+    expect(content).toContain('[0048-runs-list]');
+  });
+
+  test('复跑幂等（无前缀可展开时零修复）', () => {
+    runDocsFix({ root: FIXTURE_ROOT, config: CONFIG });
+
+    const second = runDocsFix({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(second.fixedFiles).toEqual([]);
+  });
+});
+
+describe('runWriteDocsBaseline', () => {
+  test('存在基线外新增违规拒绝再生', () => {
+    const result = runWriteDocsBaseline({
+      root: FIXTURE_ROOT,
+      config: CONFIG,
+      issuePointer: '0060',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toContain('拒绝再生');
+  });
+
+  test('基线覆盖全集时再生成功', () => {
+    /**
+     * 全集违例
+     */
+    const all = runDocsCheck({
+      root: FIXTURE_ROOT,
+      config: CONFIG,
+      ignoreBaseline: true,
+    }).violations;
+
+    const configWithBaseline = parseLziIssuesConfig({
+      schemaVersion: 1,
+      scopes: CONFIG.scopes,
+      docs: {
+        scanRoots: ['docs-guides'],
+        baseline: all.map((v) => ({ file: v.file, rule: v.rule, issue: '0050' })),
+      },
+    });
+
+    const result = runWriteDocsBaseline({
+      root: FIXTURE_ROOT,
+      config: configWithBaseline,
+      issuePointer: '0060',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.ok === true && result.content).toContain('棘轮只许缩短');
+    expect(result.ok === true && result.entryCount).toBe(all.length);
+  });
+});

package/src/__tests__/fs/mini-glob.utils.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test';
+
+import { compileMiniGlob, matchMiniGlob, MiniGlobError } from '@/fs/mini-glob.utils';
+
+describe('matchMiniGlob 语义', () => {
+  test('`*` 匹配段内任意字符不跨分隔', () => {
+    expect(matchMiniGlob('docs/*.md', 'docs/a.md')).toBe(true);
+    expect(matchMiniGlob('docs/*.md', 'docs/x/y.md')).toBe(false);
+    expect(matchMiniGlob('docs/*.md', 'apps/a.md')).toBe(false);
+  });
+
+  test('`**/` 匹配零或多层目录', () => {
+    expect(matchMiniGlob('docs/**/*.md', 'docs/a.md')).toBe(true);
+    expect(matchMiniGlob('docs/**/*.md', 'docs/x/y/z.md')).toBe(true);
+    expect(matchMiniGlob('docs/**/*.md', 'a.md')).toBe(false);
+    expect(matchMiniGlob('docs/**/*.md', 'docs/x/y.txt')).toBe(false);
+  });
+
+  test('前缀 `**/` 同样成立', () => {
+    expect(matchMiniGlob('**/issues/*.md', 'issues/a.md')).toBe(true);
+    expect(matchMiniGlob('**/issues/*.md', 'docs/issues/a.md')).toBe(true);
+    expect(matchMiniGlob('**/issues/*.md', 'docs/other/a.md')).toBe(false);
+  });
+
+  test('尾缀 `**` 匹配子树全部', () => {
+    expect(matchMiniGlob('docs/**', 'docs/a/b.md')).toBe(true);
+    expect(matchMiniGlob('docs/**', 'docs')).toBe(false);
+  });
+
+  test('`?` 匹配段内单字符', () => {
+    expect(matchMiniGlob('docs/?eadme.md', 'docs/readme.md')).toBe(true);
+    expect(matchMiniGlob('docs/?eadme.md', 'docs/reaadme.md')).toBe(false);
+  });
+
+  test('`{a,b}` 段内多选一', () => {
+    expect(matchMiniGlob('{docs,apps}/x.md', 'docs/x.md')).toBe(true);
+    expect(matchMiniGlob('{docs,apps}/x.md', 'apps/x.md')).toBe(true);
+    expect(matchMiniGlob('{docs,apps}/x.md', 'pkg/x.md')).toBe(false);
+  });
+
+  test('`{a,b}` 候选项可含通配', () => {
+    expect(matchMiniGlob('docs/{*a,b}/x.md', 'docs/alpha/x.md')).toBe(true);
+    expect(matchMiniGlob('docs/{*a,b}/x.md', 'docs/b/x.md')).toBe(true);
+    expect(matchMiniGlob('docs/{*a,b}/x.md', 'docs/zzz/x.md')).toBe(false);
+  });
+
+  test('字面模式仅精确匹配', () => {
+    expect(matchMiniGlob('docs/issues/0001-a.md', 'docs/issues/0001-a.md')).toBe(true);
+    expect(matchMiniGlob('docs/issues/0001-a.md', 'docs/issues/0001-b.md')).toBe(false);
+  });
+
+  test('中文与点号字面安全', () => {
+    expect(matchMiniGlob('docs/报告/*.md', 'docs/报告/一.md')).toBe(true);
+    expect(matchMiniGlob('docs/a.b.md', 'docs/a.b.md')).toBe(true);
+    expect(matchMiniGlob('docs/a.b.md', 'docs/aXb.md')).toBe(false);
+  });
+});
+
+describe('不支持语法显式抛错', () => {
+  test('字符类 `[` 抛错', () => {
+    expect(() => compileMiniGlob('docs/[abc].md')).toThrow(MiniGlobError);
+  });
+
+  test('大括号未闭合抛错', () => {
+    expect(() => compileMiniGlob('docs/{a/*.md')).toThrow(MiniGlobError);
+  });
+
+  test('嵌套大括号抛错', () => {
+    expect(() => compileMiniGlob('docs/{{a,b}}.md')).toThrow(MiniGlobError);
+  });
+});

package/src/__tests__/fs/walk-surface.utils.test.ts

@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { matchMiniGlob } from '@/fs/mini-glob.utils';
+import {
+  deriveWalkPrefixes,
+  walkFilesUnderPrefixes,
+  walkFilesUnderRoots,
+} from '@/fs/walk-surface.utils';
+
+/**
+ * 测试夹具根目录（包内临时目录）
+ */
+const FIXTURE_ROOT = join(import.meta.dir, '__tmp-walk__');
+
+/**
+ * 写入测试夹具目录树
+ */
+function writeFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+
+  /**
+   * 目录清单
+   */
+  const dirs = ['docs/issues', 'docs/generated', 'docs/other/deep', 'apps/cli', '.git/objects'];
+
+  for (const dir of dirs) {
+    mkdirSync(join(FIXTURE_ROOT, dir), { recursive: true });
+  }
+
+  /**
+   * 文件清单（相对路径 → 内容）
+   */
+  const files: Record<string, string> = {
+    'a.md': '',
+    'root.txt': '',
+    'docs/b.md': '',
+    'docs/issues/0001-x.md': '',
+    'docs/issues/README.md': '',
+    'docs/generated/g.md': '',
+    'docs/other/deep/d.md': '',
+    'apps/c.md': '',
+    'apps/cli/main.ts': '',
+    '.git/hidden.md': '',
+  };
+
+  for (const [rel, content] of Object.entries(files)) {
+    writeFileSync(join(FIXTURE_ROOT, rel), content);
+  }
+
+  /**
+   * 符号链接（指向目录，验证跳过语义）
+   */
+  symlinkSync(join(FIXTURE_ROOT, 'docs'), join(FIXTURE_ROOT, 'docs-link'));
+}
+
+/**
+ * 清理测试夹具
+ */
+function cleanFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+}
+
+beforeEach(writeFixture);
+
+afterEach(cleanFixture);
+
+describe('deriveWalkPrefixes', () => {
+  test('字面目录续推到倒数第二段', () => {
+    expect(deriveWalkPrefixes(['docs/issues/*.md'])).toEqual(['docs/issues']);
+  });
+
+  test('通配目录段截断（保守超集）', () => {
+    expect(deriveWalkPrefixes(['docs/**/*.md'])).toEqual(['docs']);
+    expect(deriveWalkPrefixes(['docs/*abc/x.md'])).toEqual(['docs']);
+  });
+
+  test('首段即通配贡献全仓标记', () => {
+    expect(deriveWalkPrefixes(['*.md'])).toEqual(['']);
+  });
+
+  test('大括号分叉（字面候选续推，通配候选截断）', () => {
+    expect(deriveWalkPrefixes(['{docs,apps}/issues/*.md'])).toEqual(['docs/issues', 'apps/issues']);
+    expect(deriveWalkPrefixes(['docs/{*a,b}/x.md'])).toEqual(['docs']);
+  });
+
+  test('包含关系裁剪（宽前缀吞并窄前缀）', () => {
+    expect(deriveWalkPrefixes(['docs/*.md', 'docs/issues/*.md'])).toEqual(['docs']);
+  });
+
+  test('空模式集产出空前缀集（无扫描面）', () => {
+    expect(deriveWalkPrefixes([])).toEqual([]);
+  });
+});
+
+describe('walkFilesUnderPrefixes', () => {
+  test('前缀定向只收前缀下文件，.git 恒跳过', () => {
+    const files = walkFilesUnderPrefixes(FIXTURE_ROOT, ['docs/issues']);
+
+    expect(files).toEqual(['docs/issues/0001-x.md', 'docs/issues/README.md']);
+  });
+
+  test('排除 glob 整树剪枝（子树口径）', () => {
+    const files = walkFilesUnderPrefixes(FIXTURE_ROOT, ['docs'], {
+      excludeGlobs: ['docs/generated/**'],
+    });
+
+    expect(files.includes('docs/generated/g.md')).toBe(false);
+    expect(files.includes('docs/b.md')).toBe(true);
+  });
+
+  test('符号链接跳过', () => {
+    const files = walkFilesUnderPrefixes(FIXTURE_ROOT, ['']);
+
+    expect(files.some((file) => file.startsWith('docs-link'))).toBe(false);
+  });
+
+  test('前缀目录缺失静默跳过（未来目录合法）', () => {
+    expect(walkFilesUnderPrefixes(FIXTURE_ROOT, ['future/registry'])).toEqual([]);
+  });
+});
+
+describe('walkFilesUnderRoots', () => {
+  test('缺根抛错（防扫描面缩水）', () => {
+    expect(() => walkFilesUnderRoots(join(FIXTURE_ROOT, 'missing'))).toThrow('扫描面目录缺失');
+  });
+
+  test('全仓严格遍历收齐全部文件（.git 除外）', () => {
+    const files = walkFilesUnderRoots(FIXTURE_ROOT);
+
+    expect(files).toEqual([
+      'a.md',
+      'apps/c.md',
+      'apps/cli/main.ts',
+      'docs/b.md',
+      'docs/generated/g.md',
+      'docs/issues/0001-x.md',
+      'docs/issues/README.md',
+      'docs/other/deep/d.md',
+      'root.txt',
+    ]);
+  });
+});
+
+describe('前缀推导与全仓口径等价守卫（常驻）', () => {
+  test('推导前缀收集 ≡ 全仓收集（按 include 过滤后）', () => {
+    /**
+     * 等价性守卫用的 include glob 集（覆盖字面/通配/大括号/全仓四形态）
+     */
+    const includeGlobs = ['docs/**/*.md', '*.md', '{apps,docs}/*.md'];
+
+    /**
+     * 推导前缀收集结果
+     */
+    const viaPrefixes = walkFilesUnderPrefixes(
+      FIXTURE_ROOT,
+      deriveWalkPrefixes(includeGlobs),
+    ).filter((file) => includeGlobs.some((glob) => matchMiniGlob(glob, file)));
+
+    /**
+     * 全仓收集结果
+     */
+    const viaWhole = walkFilesUnderRoots(FIXTURE_ROOT).filter((file) =>
+      includeGlobs.some((glob) => matchMiniGlob(glob, file)),
+    );
+
+    expect(viaPrefixes).toEqual(viaWhole);
+  });
+});

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

@@ -0,0 +1,131 @@
+import { parseLziIssuesConfig } from '@longzai-intelligence-issues/config';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { runHealth, runTriage } from '@/health/health.commands';
+
+/**
+ * 测试夹具根（包内临时目录）
+ */
+const FIXTURE_ROOT = join(import.meta.dir, '__tmp-health__');
+
+/**
+ * 解析后的测试配置
+ */
+const CONFIG = parseLziIssuesConfig({
+  schemaVersion: 1,
+  scopes: [{ key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/issues' }],
+});
+
+/**
+ * 写入夹具
+ */
+function writeFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+  mkdirSync(join(FIXTURE_ROOT, 'docs/issues'), { recursive: true });
+
+  /**
+   * 黄灯三类样例 + 红灯
+   */
+  writeFileSync(
+    join(FIXTURE_ROOT, 'docs/issues/0001-yellow-a.md'),
+    '**状态**: 🟡 处理中（判据补跑中）\n\n```criteria\nsummary: s\n单包测试|test|pkg|bun run test\n```\n',
+  );
+  writeFileSync(
+    join(FIXTURE_ROOT, 'docs/issues/0002-yellow-b.md'),
+    '**状态**: 🟡 处理中（等待真机回归）\n',
+  );
+  writeFileSync(
+    join(FIXTURE_ROOT, 'docs/issues/0003-yellow-c.md'),
+    '**状态**: 🟡 处理中（被并行线阻断）\n',
+  );
+  writeFileSync(join(FIXTURE_ROOT, 'docs/issues/0004-red.md'), '**状态**: 🔴 待处理\n');
+}
+
+/**
+ * 清理夹具
+ */
+function cleanFixture(): void {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+}
+
+beforeEach(writeFixture);
+
+afterEach(cleanFixture);
+
+describe('runHealth', () => {
+  test('状态分布、黄灯总数与 A-B-C 分类', () => {
+    const report = runHealth({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(report.statusCounts['yellow']).toBe(3);
+    expect(report.statusCounts['red']).toBe(1);
+    expect(report.yellowTotal).toBe(3);
+    expect(report.categoryCounts['A']).toBe(1);
+    expect(report.categoryCounts['B']).toBe(1);
+    expect(report.categoryCounts['C']).toBe(1);
+  });
+
+  test('最老黄灯账龄按 mtime 天计算', () => {
+    const report = runHealth({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(report.oldestYellowAgeDays).toBeGreaterThanOrEqual(0);
+  });
+
+  test('无黄灯时账龄为 0', () => {
+    rmSync(join(FIXTURE_ROOT, 'docs/issues/0001-yellow-a.md'));
+    rmSync(join(FIXTURE_ROOT, 'docs/issues/0002-yellow-b.md'));
+    rmSync(join(FIXTURE_ROOT, 'docs/issues/0003-yellow-c.md'));
+
+    const report = runHealth({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(report.yellowTotal).toBe(0);
+    expect(report.oldestYellowAgeDays).toBe(0);
+  });
+});
+
+describe('runTriage', () => {
+  test('台账只收黄灯，append-only 落盘且结构完整', () => {
+    const { ledgerPath, ledger } = runTriage({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(existsSync(ledgerPath)).toBe(true);
+    expect(ledgerPath).toContain(join('.lzi', 'issues', 'runs', 'ledger'));
+
+    expect(ledger.items).toHaveLength(3);
+
+    /**
+     * B/C 类理由与判据命令
+     */
+    const bItem = ledger.items.find((item) => item.category === 'B');
+    const aItem = ledger.items.find((item) => item.category === 'A');
+
+    expect(bItem?.reason).toContain('真机');
+    expect(aItem?.criteriaCommands).toEqual(['bun run test']);
+
+    /**
+     * 落盘内容可解析且与返回一致
+     */
+    const persisted = JSON.parse(readFileSync(ledgerPath, 'utf8')) as typeof ledger;
+
+    expect(persisted.items).toHaveLength(3);
+  });
+
+  test('再次运行产生新台账文件（append-only 不覆盖）', () => {
+    const first = runTriage({ root: FIXTURE_ROOT, config: CONFIG });
+
+    const second = runTriage({ root: FIXTURE_ROOT, config: CONFIG });
+
+    expect(first.ledgerPath).not.toBe(second.ledgerPath);
+  });
+
+  test('outDir 覆盖生效', () => {
+    /**
+     * 自定义输出目录
+     */
+    const outDir = join(FIXTURE_ROOT, 'custom-ledger');
+
+    const { ledgerPath } = runTriage({ root: FIXTURE_ROOT, config: CONFIG, outDir });
+
+    expect(ledgerPath.startsWith(outDir)).toBe(true);
+  });
+});