@longzai-intelligence-records/ledger 0.0.1

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

@@ -0,0 +1,163 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { runRecordsLint } from '@/lint/lint.core';
+import { renderRecordTemplate } from '@/template/record-template.renderer';
+
+/**
+ * lint 核临时目录夹具测试：合法建档零违例；各规则面拦截；基线豁免命中。
+ */
+describe('records lint core', () => {
+  /**
+   * 夹具根目录
+   */
+  let fixtureRoot: string;
+
+  /**
+   * 最小测试配置（引擎零仓库知识——配置内联构造）
+   */
+  const baseConfig = {
+    scopes: [{ key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/records' }],
+  };
+
+  beforeAll(() => {
+    fixtureRoot = mkdtempSync(join(tmpdir(), 'lzi-records-lint-'));
+    mkdirSync(join(fixtureRoot, 'docs/records'), { recursive: true });
+  });
+
+  afterAll(() => {
+    rmSync(fixtureRoot, { recursive: true, force: true });
+  });
+
+  test('create 渲染产物零违例（构造上天然过 lint）', () => {
+    writeFileSync(
+      join(fixtureRoot, 'docs/records/0001-good-entry.md'),
+      renderRecordTemplate({
+        number: '0001',
+        slug: 'good-entry',
+        title: '合法条目',
+        date: '2026-09-27',
+        source: '测试夹具',
+      }),
+    );
+
+    /**
+     * lint 结果
+     */
+    const result = runRecordsLint({
+      root: fixtureRoot,
+      config: { ...baseConfig, lint: { baseline: [] } },
+    });
+
+    expect(result.violations.filter((v) => v.file === 'docs/records/0001-good-entry.md')).toEqual(
+      [],
+    );
+  });
+
+  test('文件名形态违规拦截（R-FILENAME）', () => {
+    writeFileSync(
+      join(fixtureRoot, 'docs/records/badname.md'),
+      '# 0002 — x\n\n> 记录日期：2026-09-27\n> 来源：t\n',
+    );
+
+    /**
+     * lint 结果
+     */
+    const result = runRecordsLint({
+      root: fixtureRoot,
+      config: { ...baseConfig, lint: { baseline: [] } },
+    });
+
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'R-FILENAME' && v.file === 'docs/records/badname.md',
+      ),
+    ).toBe(true);
+  });
+
+  test('H1 编号不一致拦截（R-H1-NUMBER）', () => {
+    writeFileSync(
+      join(fixtureRoot, 'docs/records/0003-slug.md'),
+      renderRecordTemplate({
+        number: '0009',
+        slug: 'slug',
+        title: '编号错位',
+        date: '2026-09-27',
+        source: 't',
+      }),
+    );
+
+    /**
+     * lint 结果
+     */
+    const result = runRecordsLint({
+      root: fixtureRoot,
+      config: { ...baseConfig, lint: { baseline: [] } },
+    });
+
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'R-H1-NUMBER' && v.file === 'docs/records/0003-slug.md',
+      ),
+    ).toBe(true);
+  });
+
+  test('头部元数据缺失与假日期拦截（R-DATE-LINE / R-DATE-REAL / R-SOURCE-LINE）', () => {
+    writeFileSync(join(fixtureRoot, 'docs/records/0004-no-meta.md'), '# 0004 — 无元数据\n\n正文\n');
+
+    writeFileSync(
+      join(fixtureRoot, 'docs/records/0005-fake-date.md'),
+      '# 0005 — 假日期\n\n> 记录日期：2025-02-29\n> 来源：t\n',
+    );
+
+    /**
+     * lint 结果
+     */
+    const result = runRecordsLint({
+      root: fixtureRoot,
+      config: { ...baseConfig, lint: { baseline: [] } },
+    });
+
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'R-DATE-LINE' && v.file === 'docs/records/0004-no-meta.md',
+      ),
+    ).toBe(true);
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'R-SOURCE-LINE' && v.file === 'docs/records/0004-no-meta.md',
+      ),
+    ).toBe(true);
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'R-DATE-REAL' && v.file === 'docs/records/0005-fake-date.md',
+      ),
+    ).toBe(true);
+  });
+
+  test('基线豁免命中（file + rule 精确匹配，豁免计数入观测面）', () => {
+    /**
+     * lint 结果（badname 档案 R-FILENAME 豁免）
+     */
+    const result = runRecordsLint({
+      root: fixtureRoot,
+      config: {
+        ...baseConfig,
+        lint: {
+          baseline: [
+            { file: 'docs/records/badname.md', rule: 'R-FILENAME', reason: '存量宽口径命名' },
+          ],
+        },
+      },
+    });
+
+    expect(
+      result.violations.some(
+        (v) => v.rule === 'R-FILENAME' && v.file === 'docs/records/badname.md',
+      ),
+    ).toBe(false);
+    expect(result.exemptedCount).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/__tests__/parser/format.utils.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  ASCII_KEBAB_SLUG_PATTERN,
+  extractIndexRefs,
+  extractRecordKey,
+  isRealCalendarDate,
+  RECORD_FILENAME_PATTERN,
+} from '@/parser/format.utils';
+
+/**
+ * 格式单一真源口径测试：accept / reject 双面样本。
+ */
+describe('format.utils 口径', () => {
+  test('文件名形态：合法样本通过', () => {
+    for (const name of ['0001-a.md', '0013-fallback-channel.md', '9999-x9-y.md', '013-a.md']) {
+      expect(RECORD_FILENAME_PATTERN.test(name)).toBe(true);
+    }
+  });
+
+  test('文件名形态：非法样本拒绝', () => {
+    for (const name of [
+      '1-a.md',
+      '00001-a.md',
+      '0001_A.md',
+      '0001-a.md.bak',
+      '0001-a',
+      'A-001-a.md',
+    ]) {
+      expect(RECORD_FILENAME_PATTERN.test(name)).toBe(false);
+    }
+  });
+
+  test('slug 门禁：ASCII kebab 通过、中文与下划线拒绝', () => {
+    expect(ASCII_KEBAB_SLUG_PATTERN.test('fallback-channel')).toBe(true);
+    expect(ASCII_KEBAB_SLUG_PATTERN.test('通道启用')).toBe(false);
+    expect(ASCII_KEBAB_SLUG_PATTERN.test('fallback_channel')).toBe(false);
+    expect(ASCII_KEBAB_SLUG_PATTERN.test('-leading')).toBe(false);
+  });
+
+  test('extractRecordKey 宽口径提取编号键', () => {
+    expect(extractRecordKey('0002-x.md')).toBe('0002');
+    expect(extractRecordKey('12-x.md')).toBe('12');
+    expect(extractRecordKey('README.md')).toBeNull();
+    expect(extractRecordKey('notes.md')).toBeNull();
+  });
+
+  test('isRealCalendarDate 真实日历日判定（进位日拒绝）', () => {
+    expect(isRealCalendarDate('2026-09-27')).toBe(true);
+    expect(isRealCalendarDate('2024-02-29')).toBe(true);
+    expect(isRealCalendarDate('2025-02-29')).toBe(false);
+    expect(isRealCalendarDate('2026-13-01')).toBe(false);
+    expect(isRealCalendarDate('2026-04-31')).toBe(false);
+  });
+
+  test('extractIndexRefs 提取 README 链接引用集', () => {
+    /**
+     * 引用集
+     */
+    const refs = extractIndexRefs(
+      [
+        '# records',
+        '',
+        '- [0001 — 通道启用](./0001-channel-open.md)',
+        '- [0002 — 补充](./0002-second.md)',
+        '（见 ./0003-third.md 无链接形态不提取）',
+      ].join('\n'),
+    );
+
+    expect(refs.get('0001')).toBe('channel-open');
+    expect(refs.get('0002')).toBe('second');
+    expect(refs.has('0003')).toBe(false);
+  });
+});

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

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test';
+
+import { parseRecordDoc } from '@/parser/record.parser';
+import {
+  renderRecordTemplate,
+  renderRecordTemplateSkeleton,
+} from '@/template/record-template.renderer';
+
+/**
+ * 渲染-解析回环测试：渲染产物（骨架与实例）必须可被解析器读档为合法建档态
+ * ——create 产物在构造上天然通过 lint 的守卫。
+ */
+describe('record-template renderer（渲染-解析回环）', () => {
+  test('skeleton 为取号前形态：占位编号被严格解析器拒绝（门禁属性非缺陷）', () => {
+    /**
+     * 骨架全文
+     */
+    const skeleton = renderRecordTemplateSkeleton();
+
+    expect(skeleton.startsWith('# <NNNN> — ')).toBe(true);
+
+    /**
+     * 解析结果（占位编号非数字——解析器必须拒绝，防止占位形态混入注册表）
+     */
+    const parsed = parseRecordDoc(skeleton);
+
+    expect(parsed.record).toBeNull();
+    expect(parsed.issues).toHaveLength(1);
+    expect(parsed.issues[0]?.message).toContain('H1');
+  });
+
+  test('instance 头部实际值回读一致（编号/标题/日期/来源）', () => {
+    /**
+     * 实例全文
+     */
+    const rendered = renderRecordTemplate({
+      number: '0013',
+      slug: 'fallback-channel-first-entry',
+      title: 'records 通道启用',
+      date: '2026-09-27',
+      source: 'Task 011 自举（2026-09-27）',
+    });
+
+    /**
+     * 解析结果
+     */
+    const parsed = parseRecordDoc(rendered);
+
+    expect(parsed.issues).toEqual([]);
+    expect(parsed.record?.number).toBe('0013');
+    expect(parsed.record?.title).toBe('records 通道启用');
+    expect(parsed.record?.date).toBe('2026-09-27');
+    expect(parsed.record?.source).toBe('Task 011 自举（2026-09-27）');
+    expect(parsed.record?.ref).toBeNull();
+  });
+
+  test('ref 提供时渲染关联行并可回读', () => {
+    /**
+     * 带关联实例全文
+     */
+    const rendered = renderRecordTemplate({
+      number: '0002',
+      slug: 'with-ref',
+      title: '带关联条目',
+      date: '2026-09-27',
+      source: '测试',
+      ref: '[decisions/021](../../decisions/021-records-fallback-no-typing.md)',
+    });
+
+    /**
+     * 解析结果
+     */
+    const parsed = parseRecordDoc(rendered);
+
+    expect(parsed.record?.ref).toBe(
+      '[decisions/021](../../decisions/021-records-fallback-no-typing.md)',
+    );
+  });
+
+  test('两模式正文共享同一占位指引（结构漂移在构造上不可能）', () => {
+    expect(renderRecordTemplateSkeleton()).toContain('（正文自由格式');
+    expect(
+      renderRecordTemplate({
+        number: '0001',
+        slug: 'x',
+        title: 't',
+        date: '2026-09-27',
+        source: 's',
+      }),
+    ).toContain('（正文自由格式');
+  });
+});

package/src/fs/scan-registry.utils.ts

@@ -0,0 +1,74 @@
+/**
+ * 注册表目录扫描工具（fs 编排层）
+ *
+ * 读侧统一入口：lint / index check / list 共用本扫描，文件枚举口径单一。
+ */
+
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { extractRecordKey } from '@/parser/format.utils';
+
+/**
+ * 扫描到的注册表条目
+ */
+export type ScannedRecord = {
+  /**
+   * 文件基名（含扩展名）
+   */
+  basename: string;
+
+  /**
+   * 编号键（数字字符串原样；宽口径非编号形态为 null）
+   */
+  key: string | null;
+
+  /**
+   * 绝对路径
+   */
+  absPath: string;
+};
+
+/**
+ * 扫描注册表目录（仅 .md 文件，按编号键升序；目录不存在返回空数组）
+ *
+ * @param dirAbs - 注册表目录绝对路径
+ * @returns 扫描条目列表
+ */
+export function scanRecordsDir(dirAbs: string): ScannedRecord[] {
+  if (!existsDir(dirAbs)) {
+    return [];
+  }
+
+  /**
+   * .md 基名列表
+   */
+  const basenames = readdirSync(dirAbs).filter(
+    (name) => name.endsWith('.md') && name !== 'README.md',
+  );
+
+  /**
+   * 扫描条目列表
+   */
+  const entries: ScannedRecord[] = basenames.map((basename) => ({
+    basename,
+    key: extractRecordKey(basename),
+    absPath: join(dirAbs, basename),
+  }));
+
+  return entries.sort((a, b) => (a.key ?? 'zzzz').localeCompare(b.key ?? 'zzzz'));
+}
+
+/**
+ * 判定目录存在（读侧守卫——注册表目录未建视为空注册表）
+ *
+ * @param dirAbs - 目录绝对路径
+ * @returns 存在为 true
+ */
+function existsDir(dirAbs: string): boolean {
+  try {
+    return readdirSync(dirAbs).length >= 0;
+  } catch {
+    return false;
+  }
+}

package/src/index-check/index-check.core.ts

@@ -0,0 +1,200 @@
+/**
+ * records README 索引差量核（只查不写）
+ *
+ * 索引行人工登记、工具只检查不写入（与 decision 项目 index 先例同款裁定）。
+ * 判定三态：缺行（文件在、索引无）/ 多行（索引有、文件无）/ slug 漂移（索引
+ * 链接 slug 与实际文件 slug 不一致）；报文附期望行供人工粘贴。
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { scanRecordsDir } from '@/fs/scan-registry.utils';
+import { captureGroup, extractIndexRefs, RECORD_FILENAME_PATTERN } from '@/parser/format.utils';
+import { parseRecordDoc } from '@/parser/record.parser';
+
+/**
+ * 索引差量发现条目
+ */
+export type IndexCheckFinding = {
+  /**
+   * 发现类别：readme-missing（README 未建）/ missing（缺行）/ stale（多行）/ slug-drift（slug 漂移）
+   */
+  kind: 'readme-missing' | 'missing' | 'stale' | 'slug-drift';
+
+  /**
+   * 相关文件（posix 相对注册表目录）
+   */
+  file: string;
+
+  /**
+   * 发现消息
+   */
+  message: string;
+};
+
+/**
+ * 索引差量结果
+ */
+export type IndexCheckResult = {
+  /**
+   * 新鲜判定（无任何发现）
+   */
+  ok: boolean;
+
+  /**
+   * 发现列表
+   */
+  findings: IndexCheckFinding[];
+
+  /**
+   * 期望索引行列表（供人工粘贴）
+   */
+  expectedLines: string[];
+
+  /**
+   * 注册表文件数
+   */
+  fileCount: number;
+
+  /**
+   * 索引引用数
+   */
+  indexedCount: number;
+};
+
+/**
+ * 索引差量入参
+ */
+export type IndexCheckInput = {
+  /**
+   * 注册表目录绝对路径
+   */
+  registryDirAbs: string;
+};
+
+/**
+ * 运行索引差量检查（只读——本函数不写任何文件）
+ *
+ * @param input - 检查入参
+ * @returns 差量结果
+ */
+export function runIndexCheck(input: IndexCheckInput): IndexCheckResult {
+  /**
+   * 发现列表
+   */
+  const findings: IndexCheckFinding[] = [];
+
+  /**
+   * 扫描条目（编号形态合法者参与索引比对）
+   */
+  const entries = scanRecordsDir(input.registryDirAbs).filter((entry) =>
+    RECORD_FILENAME_PATTERN.test(entry.basename),
+  );
+
+  /**
+   * 编号 → 条目映射（filter 已保证形态合法——exec 必中）
+   */
+  const byKey = new Map(
+    entries.map((entry) => {
+      /**
+       * 文件名命中
+       */
+      const match = RECORD_FILENAME_PATTERN.exec(entry.basename);
+
+      return [match === null ? (entry.key ?? entry.basename) : captureGroup(match, 1), entry];
+    }),
+  );
+
+  /**
+   * README 绝对路径
+   */
+  const readmeAbs = join(input.registryDirAbs, 'README.md');
+
+  /**
+   * 索引引用集（编号 → slug）
+   */
+  const refs = existsSync(readmeAbs)
+    ? extractIndexRefs(readFileSync(readmeAbs, 'utf8'))
+    : new Map<string, string>();
+
+  if (!existsSync(readmeAbs)) {
+    findings.push({
+      kind: 'readme-missing',
+      file: 'README.md',
+      message: '注册表 README 未建（init 可落存根；索引行人工登记）',
+    });
+  }
+
+  /**
+   * 缺行检测（文件在、索引无）+ 期望行构造
+   */
+  const expectedLines: string[] = [];
+
+  for (const entry of entries) {
+    /**
+     * 文件名命中（filter 已保证形态合法）
+     */
+    const match = RECORD_FILENAME_PATTERN.exec(entry.basename);
+
+    if (match === null) {
+      continue;
+    }
+
+    /**
+     * 文件编号
+     */
+    const key = captureGroup(match, 1);
+
+    /**
+     * 文件 slug
+     */
+    const slug = captureGroup(match, 2);
+
+    /**
+     * 解析标题（期望行用；解析失败回退文件名）
+     */
+    const parsed = parseRecordDoc(readFileSync(entry.absPath, 'utf8'));
+
+    expectedLines.push(`- [${key} — ${parsed.record?.title ?? slug}](./${entry.basename})`);
+
+    if (!refs.has(key)) {
+      findings.push({
+        kind: 'missing',
+        file: entry.basename,
+        message: `索引缺行：${entry.basename}（期望行见报文，人工登记）`,
+      });
+
+      continue;
+    }
+
+    if (refs.get(key) !== slug) {
+      findings.push({
+        kind: 'slug-drift',
+        file: entry.basename,
+        message: `索引 slug 漂移：索引指向 ${key}-${refs.get(key)}.md，实际为 ${entry.basename}`,
+      });
+    }
+  }
+
+  /**
+   * 多行检测（索引有、文件无）
+   */
+  for (const [key, slug] of refs) {
+    if (!byKey.has(key)) {
+      findings.push({
+        kind: 'stale',
+        file: `${key}-${slug}.md`,
+        message: `索引多行：引用 ${key}-${slug}.md 但文件不存在（删除索引行或补文件）`,
+      });
+    }
+  }
+
+  return {
+    ok: findings.length === 0,
+    findings,
+    expectedLines,
+    fileCount: entries.length,
+    indexedCount: refs.size,
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 引擎核入口
+ *
+ * 汇出：格式单一真源、解析器、模板渲染器、注册表扫描、lint 核、索引差量核。
+ * 引擎零仓库知识——一切仓库特有信息走 config（LziRecordsConfig 类型面）。
+ */
+
+export * from '@/fs/scan-registry.utils';
+
+export * from '@/index-check/index-check.core';
+
+export * from '@/lint/lint.core';
+
+export * from '@/parser/format.utils';
+
+export * from '@/parser/record.parser';
+
+export * from '@/template/record-template.renderer';