@longzai-intelligence-issues/config 0.0.1

package/src/__tests__/scaffold/render-scaffold.renderer.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  appendScopeToConfigText,
+  renderConfigScaffoldFile,
+} from '@/scaffold/render-scaffold.renderer';
+import { parseLziIssuesConfig } from '@/schema/lzi-issues-config.schema';
+
+/**
+ * 动态导入序号（每次唯一文件名，规避 bun 模块 URL 缓存返回陈旧模块）
+ */
+let importSequence = 0;
+
+/**
+ * 动态导入生成的配置文本（改写包导入为本包内路径后落盘导入并解析）
+ *
+ * @param generated - 生成的配置文件全文
+ * @returns 解析后配置
+ */
+async function importAndParse(generated: string) {
+  /**
+   * 临时目录（包内，保证模块解析可用）
+   */
+  const tmpDir = join(import.meta.dir, '__tmp-scaffold__');
+
+  /**
+   * 临时文件路径（序号唯一化）
+   */
+  const tmpFile = join(tmpDir, `gen-${(importSequence += 1)}.config.ts`);
+
+  mkdirSync(tmpDir, { recursive: true });
+
+  try {
+    /**
+     * 可导入文本（包导入改写为包内别名，规避 dist 构建依赖）
+     */
+    const importable = generated.replace(
+      "'@longzai-intelligence-issues/config'",
+      "'@/schema/lzi-issues-config.schema'",
+    );
+
+    writeFileSync(tmpFile, importable);
+
+    /**
+     * 动态导入的配置模块
+     */
+    const module = (await import(pathToFileURL(tmpFile).href)) as { default: unknown };
+
+    return parseLziIssuesConfig(module.default);
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+describe('renderConfigScaffoldFile', () => {
+  test('生成文件含契约头、defineConfig 与缺省 scope 值', () => {
+    const text = renderConfigScaffoldFile({ key: 'demo', title: '演示域' });
+
+    expect(
+      text.includes("import { defineConfig } from '@longzai-intelligence-issues/config';"),
+    ).toBe(true);
+    expect(text.includes('lzi-issues init')).toBe(true);
+    expect(text.includes("key: 'demo'")).toBe(true);
+    expect(text.includes("paths: ['.']")).toBe(true);
+    expect(text.includes("registryDir: 'docs/issues'")).toBe(true);
+  });
+
+  test('生成文件回环：动态导入后解析合法', async () => {
+    const config = await importAndParse(renderConfigScaffoldFile({ key: 'demo', title: '演示域' }));
+
+    expect(config.scopes).toHaveLength(1);
+    expect(config.scopes[0]?.key).toBe('demo');
+    expect(config.scopes[0]?.paths).toEqual(['.']);
+    expect(config.storage.strategy).toBe('files');
+  });
+});
+
+describe('appendScopeToConfigText', () => {
+  test('追加成功：两 scope 在场且回环解析合法', async () => {
+    /**
+     * 追加后文本
+     */
+    const appended = appendScopeToConfigText(
+      renderConfigScaffoldFile({ key: 'demo', title: '演示域' }),
+      { key: 'domains', title: '领域层', paths: ['domains/**'], registryDir: 'docs/domain-issues' },
+    );
+
+    expect(appended.includes("key: 'demo'")).toBe(true);
+    expect(appended.includes("key: 'domains'")).toBe(true);
+
+    const config = await importAndParse(appended);
+
+    expect(config.scopes.map((scope) => scope.key)).toEqual(['demo', 'domains']);
+  });
+
+  test('重复 key 显式抛错', () => {
+    /**
+     * 起步文本
+     */
+    const base = renderConfigScaffoldFile({ key: 'demo', title: '演示域' });
+
+    expect(() => appendScopeToConfigText(base, { key: 'demo', title: '再注册' })).toThrow('已注册');
+  });
+
+  test('非规范缩进的手写形态同样可追加且回环合法', async () => {
+    /**
+     * 手写形态（紧凑数组、双引号、注释干扰）
+     */
+    const handwritten = [
+      "import { defineConfig } from '@longzai-intelligence-issues/config';",
+      '',
+      '/** 手写配置（含注释与字符串中的括号 [ ] 干扰） */',
+      'export default defineConfig({',
+      '  schemaVersion: 1,',
+      "  scopes: [{ key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/issues' }],",
+      '});',
+    ].join('\n');
+
+    const appended = appendScopeToConfigText(handwritten, { key: 'demo', title: '演示域' });
+
+    const config = await importAndParse(appended);
+
+    expect(config.scopes.map((scope) => scope.key)).toEqual(['root', 'demo']);
+  });
+
+  test('缺 scopes 数组显式抛错', () => {
+    expect(() =>
+      appendScopeToConfigText('export default defineConfig({ schemaVersion: 1 });', {
+        key: 'demo',
+        title: 'x',
+      }),
+    ).toThrow('缺少 scopes 数组');
+  });
+});

package/src/__tests__/schema/lzi-issues-config.schema.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEFAULT_PENDING_WORDS,
+  DEFAULT_SQLITE_PATH,
+  parseLziIssuesConfig,
+} from '@/schema/lzi-issues-config.schema';
+
+/**
+ * 最小合法配置（仅必填项）
+ */
+const MINIMAL_INPUT = {
+  schemaVersion: 1,
+  scopes: [
+    {
+      key: 'root',
+      title: '项目全局',
+      paths: ['.'],
+      registryDir: 'docs/issues',
+    },
+  ],
+};
+
+describe('parseLziIssuesConfig 默认值落定', () => {
+  test('最小配置补全全部默认值', () => {
+    const config = parseLziIssuesConfig(MINIMAL_INPUT);
+
+    expect(config.storage.strategy).toBe('files');
+    expect(config.storage.sqlitePath).toBe(DEFAULT_SQLITE_PATH);
+    expect(config.lint).toEqual({ baseline: [], strictLegacy: false, rulePacks: [] });
+    expect(config.numbering.audit.roots).toEqual(['docs']);
+    expect(config.numbering.allowlist).toEqual([]);
+    expect(config.slugDigitAllowlist).toEqual([]);
+    expect(config.docs).toBeUndefined();
+    expect(config.close.pendingWords).toEqual([...DEFAULT_PENDING_WORDS]);
+    expect(config.close.blockingMustBeGreen).toBe(true);
+    expect(config.prompts.builtin).toBe(true);
+  });
+
+  test('scope.numbering 缺省为空保留号集', () => {
+    const config = parseLziIssuesConfig(MINIMAL_INPUT);
+
+    expect(config.scopes[0]?.numbering).toEqual({ reserved: [] });
+  });
+
+  test('显式值覆盖默认值', () => {
+    const config = parseLziIssuesConfig({
+      ...MINIMAL_INPUT,
+      storage: { strategy: 'sqlite', sqlitePath: 'custom.sqlite' },
+      close: { blockingMustBeGreen: false },
+      scopes: [
+        {
+          key: 'root',
+          title: '项目全局',
+          paths: ['packages/**'],
+          registryDir: 'docs/issues',
+          numbering: { reserved: [{ number: '0024', reason: '历史空洞不回收' }] },
+          slugDigitPolicy: 'forbid',
+        },
+      ],
+    });
+
+    expect(config.storage.strategy).toBe('sqlite');
+    expect(config.storage.sqlitePath).toBe('custom.sqlite');
+    expect(config.close.blockingMustBeGreen).toBe(false);
+    expect(config.scopes[0]?.numbering.reserved).toEqual([
+      { number: '0024', reason: '历史空洞不回收' },
+    ]);
+    expect(config.scopes[0]?.slugDigitPolicy).toBe('forbid');
+  });
+
+  test('docs 节可省略，登记时 scanRoots 必填', () => {
+    const withDocs = parseLziIssuesConfig({
+      ...MINIMAL_INPUT,
+      docs: { scanRoots: ['docs'] },
+    });
+
+    expect(withDocs.docs?.scanRoots).toEqual(['docs']);
+    expect(withDocs.docs?.includeExtensions).toEqual(['.md']);
+
+    expect(() =>
+      parseLziIssuesConfig({
+        ...MINIMAL_INPUT,
+        docs: { scanRoots: [] },
+      }),
+    ).toThrow('docs');
+  });
+});
+
+describe('parseLziIssuesConfig 形态拒收', () => {
+  test('schemaVersion 非字面量 1 拒收', () => {
+    expect(() => parseLziIssuesConfig({ ...MINIMAL_INPUT, schemaVersion: 2 })).toThrow(
+      'schemaVersion',
+    );
+  });
+
+  test('scope key 非 kebab-case 拒收', () => {
+    expect(() =>
+      parseLziIssuesConfig({
+        ...MINIMAL_INPUT,
+        scopes: [{ key: 'Bad_Key', title: 'x', paths: ['.'], registryDir: 'docs/issues' }],
+      }),
+    ).toThrow('key');
+  });
+
+  test('存储策略非法值拒收', () => {
+    expect(() =>
+      parseLziIssuesConfig({
+        ...MINIMAL_INPUT,
+        storage: { strategy: 'mongo' },
+      }),
+    ).toThrow('strategy');
+  });
+
+  test('保留号非数字拒收', () => {
+    expect(() =>
+      parseLziIssuesConfig({
+        ...MINIMAL_INPUT,
+        scopes: [
+          {
+            key: 'root',
+            title: 'x',
+            paths: ['.'],
+            registryDir: 'docs/issues',
+            numbering: { reserved: [{ number: 'abc', reason: 'r' }] },
+          },
+        ],
+      }),
+    ).toThrow('number');
+  });
+
+  test('豁免条目文件集少于 2 拒收', () => {
+    expect(() =>
+      parseLziIssuesConfig({
+        ...MINIMAL_INPUT,
+        numbering: {
+          allowlist: [
+            { scopeKey: 'root', number: '0001', files: ['a.md'], status: '待清偿', reason: 'r' },
+          ],
+        },
+      }),
+    ).toThrow('files');
+  });
+});

package/src/__tests__/validation/validate-cross-entries.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from 'bun:test';
+
+import { parseLziIssuesConfig } from '@/schema/lzi-issues-config.schema';
+import { validateCrossEntries } from '@/validation/validate-cross-entries';
+
+/**
+ * 合法基准配置（跨条目校验用）
+ */
+const BASE_INPUT = {
+  schemaVersion: 1,
+  scopes: [
+    { key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/issues' },
+    {
+      key: 'domains',
+      title: '领域层',
+      paths: ['domains/**'],
+      registryDir: 'docs/domain-issues',
+      numbering: { reserved: [{ number: '0081', reason: '历史空洞不回收' }] },
+    },
+  ],
+  docs: { scanRoots: ['docs'], exclusions: [{ glob: 'docs/generated/**', reason: '生成物' }] },
+};
+
+/**
+ * 解析基准配置（形态合法，跨条目校验前）
+ */
+const parseBase = (overrides: Record<string, unknown>) =>
+  parseLziIssuesConfig({ ...BASE_INPUT, ...overrides });
+
+describe('validateCrossEntries', () => {
+  test('合法配置零违规', () => {
+    expect(validateCrossEntries(parseBase({}))).toEqual([]);
+  });
+
+  test('scope key 重复注册违规', () => {
+    const config = parseBase({
+      scopes: [
+        { key: 'root', title: 'a', paths: ['.'], registryDir: 'docs/issues' },
+        { key: 'root', title: 'b', paths: ['.'], registryDir: 'docs/other' },
+      ],
+    });
+
+    const violations = validateCrossEntries(config);
+
+    expect(violations.some((v) => v.includes('root') && v.includes('重复'))).toBe(true);
+  });
+
+  test('保留号逐 scope 查重违规', () => {
+    const config = parseBase({
+      scopes: [
+        {
+          key: 'root',
+          title: '全局',
+          paths: ['.'],
+          registryDir: 'docs/issues',
+          numbering: {
+            reserved: [
+              { number: '0024', reason: 'a' },
+              { number: '0024', reason: 'b' },
+            ],
+          },
+        },
+      ],
+    });
+
+    expect(validateCrossEntries(config).some((v) => v.includes('0024') && v.includes('重复'))).toBe(
+      true,
+    );
+  });
+
+  test('lint 基线 (file,rule) 重复违规', () => {
+    const config = parseBase({
+      lint: {
+        baseline: [
+          { file: 'docs/issues/0001-a.md', rule: 'x', issue: '0002' },
+          { file: 'docs/issues/0001-a.md', rule: 'x', issue: '0003' },
+        ],
+      },
+    });
+
+    expect(validateCrossEntries(config).some((v) => v.includes('lint.baseline'))).toBe(true);
+  });
+
+  test('docs 基线 (file,rule) 重复违规', () => {
+    const config = parseBase({
+      docs: {
+        scanRoots: ['docs'],
+        baseline: [
+          { file: 'README.md', rule: 'doc-ref-unknown', issue: '0001' },
+          { file: 'README.md', rule: 'doc-ref-unknown', issue: '0002' },
+        ],
+      },
+    });
+
+    expect(validateCrossEntries(config).some((v) => v.includes('docs.baseline'))).toBe(true);
+  });
+
+  test('allowlist 指向未登记 scope 违规', () => {
+    const config = parseBase({
+      numbering: {
+        allowlist: [
+          {
+            scopeKey: 'ghost',
+            number: '0001',
+            files: ['a.md', 'b.md'],
+            status: '维持现状',
+            reason: 'r',
+          },
+        ],
+      },
+    });
+
+    expect(
+      validateCrossEntries(config).some((v) => v.includes('ghost') && v.includes('未登记')),
+    ).toBe(true);
+  });
+
+  test('allowlist 条目（排序文件集一致即判重）违规', () => {
+    const config = parseBase({
+      numbering: {
+        allowlist: [
+          {
+            scopeKey: 'root',
+            number: '0053',
+            files: ['a.md', 'b.md'],
+            status: '待清偿',
+            reason: 'r',
+          },
+          {
+            scopeKey: 'root',
+            number: '0053',
+            files: ['b.md', 'a.md'],
+            status: '待清偿',
+            reason: 'r',
+          },
+        ],
+      },
+    });
+
+    expect(
+      validateCrossEntries(config).some((v) => v.includes('allowlist') && v.includes('重复')),
+    ).toBe(true);
+  });
+
+  test('glob 反斜杠与绝对起首违规', () => {
+    const config = parseBase({
+      slugDigitAllowlist: [{ glob: 'docs\\win\\**', reason: 'r' }],
+      numbering: { globalExclusions: [{ glob: '/abs/**', reason: 'r' }] },
+    });
+
+    const violations = validateCrossEntries(config);
+
+    expect(violations.some((v) => v.includes('反斜杠'))).toBe(true);
+    expect(violations.some((v) => v.includes('不得以 / 起首'))).toBe(true);
+  });
+
+  test('audit.roots 绝对路径与 .. 上溯违规', () => {
+    const config = parseBase({
+      numbering: { audit: { roots: ['/docs', 'docs/../etc'] } },
+    });
+
+    const violations = validateCrossEntries(config);
+
+    expect(violations.some((v) => v.includes('audit.roots') && v.includes('绝对路径'))).toBe(true);
+    expect(violations.some((v) => v.includes('audit.roots') && v.includes('..'))).toBe(true);
+  });
+
+  test('registryDir 绝对路径违规', () => {
+    const config = parseBase({
+      scopes: [{ key: 'root', title: 'a', paths: ['.'], registryDir: '/docs/issues' }],
+    });
+
+    expect(
+      validateCrossEntries(config).some((v) => v.includes('registryDir') && v.includes('绝对路径')),
+    ).toBe(true);
+  });
+});

package/src/baseline/render-baseline.renderer.ts

@@ -0,0 +1,120 @@
+/**
+ * 棘轮基线再生渲染
+ *
+ * `lint --write-baseline --issue <指针>` / `docs check --write-baseline --issue <指针>`
+ * 的落盘载体：以解析值重建配置文件（值保留、基线节替换为再生条目），带棘轮治理
+ * 契约注释头。语义边界：再生只许缩短——存在基线外新增违规时由命令层先行拒绝，
+ * 本模块只负责渲染。
+ */
+
+import type { LintBaselineEntry, LziIssuesConfig } from '@/schema/lzi-issues-config.schema';
+
+import { renderConfigFile } from '@/scaffold/render-scaffold.renderer';
+
+/**
+ * 棘轮契约注释头（再生文件头）
+ */
+export const RATCHET_CONTRACT_HEADER = [
+  '/**',
+  ' * lzi-issues 配置（单一真源）——由 `--write-baseline --issue <指针>` 再生。',
+  ' *',
+  ' * 棘轮基线语义：基线按 (file, rule) 精确命中豁免存量违规；基线外新增违规仍红；',
+  ' * 基线条目无对应现行违规计陈旧红——修复存量即须同步删除对应条目，棘轮只许缩短直至清零；',
+  ' * 每条豁免必须携带 issue 收编指针（非空）。',
+  ' *',
+  ' * 注意：再生以解析值重建本文件，节内手工注释不保留——长篇说明请写入 docs/guides。',
+  ' */',
+].join('\n');
+
+/**
+ * 基线再生目标节
+ */
+export type BaselineSection = 'lint' | 'docs';
+
+/**
+ * 基线条目排序与去重（(file, rule) 唯一，file 升序、rule 次序）
+ *
+ * @param entries - 原始条目列表
+ * @returns 排序去重后的条目列表
+ */
+export function deriveBaselineEntries(entries: readonly LintBaselineEntry[]): LintBaselineEntry[] {
+  /**
+   * (file, rule) 唯一键去重收集器
+   */
+  const unique = new Map<string, LintBaselineEntry>();
+
+  for (const entry of entries) {
+    /**
+     * 条目唯一键
+     */
+    const key = `${entry.file}::${entry.rule}`;
+
+    if (!unique.has(key)) {
+      unique.set(key, { ...entry });
+    }
+  }
+
+  return [...unique.values()].sort((a, b) => {
+    if (a.file !== b.file) {
+      return a.file.localeCompare(b.file);
+    }
+
+    return a.rule.localeCompare(b.rule);
+  });
+}
+
+/**
+ * 渲染基线再生后的完整配置文件
+ *
+ * @param config - 当前解析后配置（其余节值原样保留）
+ * @param section - 再生目标节（lint / docs）
+ * @param baseline - 再生基线条目（通常为 deriveBaselineEntries 产物）
+ * @returns 完整配置文件文本（棘轮契约头 + defineConfig 体）
+ * @throws {@link Error} section 为 docs 但配置未登记 docs 节
+ */
+export function renderBaselineRegeneratedConfig(
+  config: LziIssuesConfig,
+  section: BaselineSection,
+  baseline: readonly LintBaselineEntry[],
+): string {
+  /**
+   * 再生条目（排序去重）
+   */
+  const entries = deriveBaselineEntries(baseline);
+
+  if (section === 'lint') {
+    return renderConfigFile(
+      {
+        schemaVersion: config.schemaVersion,
+        storage: config.storage,
+        scopes: config.scopes,
+        lint: { ...config.lint, baseline: entries },
+        numbering: config.numbering,
+        slugDigitAllowlist: config.slugDigitAllowlist,
+        docs: config.docs,
+        close: config.close,
+        prompts: config.prompts,
+      },
+      RATCHET_CONTRACT_HEADER,
+    );
+  }
+
+  if (config.docs === undefined) {
+    throw new Error('配置未登记 docs 节，无法再生 docs 基线');
+  }
+
+  return renderConfigFile(
+    {
+      schemaVersion: config.schemaVersion,
+      storage: config.storage,
+      scopes: config.scopes,
+      lint: config.lint,
+      numbering: config.numbering,
+      slugDigitAllowlist: config.slugDigitAllowlist,
+      docs: { ...config.docs, baseline: entries },
+      close: config.close,
+      prompts: config.prompts,
+    },
+    RATCHET_CONTRACT_HEADER,
+  );
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 配置包入口
+ *
+ * 汇出：defineConfig、schema 与解析、跨条目校验、加载器、init 脚手架渲染、
+ * 棘轮基线再生渲染。
+ */
+
+export * from '@/baseline/render-baseline.renderer';
+
+export * from '@/loader/load-issues-config.utils';
+
+export * from '@/schema/lzi-issues-config.schema';
+
+export * from '@/scaffold/render-scaffold.renderer';
+
+export * from '@/validation/validate-cross-entries';