@longzai-intelligence-issues/ledger 0.0.1

package/src/lint/lint-baseline.commands.ts

@@ -0,0 +1,147 @@
+/**
+ * lint 基线再生命令核（--write-baseline --issue <指针>）
+ *
+ * 棘轮契约：存在基线外新增违规即拒绝再生（先处置新增违规）；再生以现行违规
+ * 全集重建基线（修复存量即自动缩短），渲染经 config 包 renderBaselineRegeneratedConfig。
+ */
+
+import type { LintBaselineEntry, LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { renderBaselineRegeneratedConfig } from '@longzai-intelligence-issues/config';
+
+import { type LintViolation, runLint } from './lint.core.js';
+
+/**
+ * 基线再生结果
+ */
+export type WriteLintBaselineResult =
+  | {
+      /**
+       * 再生成功标记
+       */
+      ok: true;
+
+      /**
+       * 再生产物全文（整文件写回 lzi-issues.config.ts）
+       */
+      content: string;
+
+      /**
+       * 再生条目数
+       */
+      entryCount: number;
+    }
+  | {
+      /**
+       * 再生成功标记
+       */
+      ok: false;
+
+      /**
+       * 拒绝原因
+       */
+      error: string;
+    };
+
+/**
+ * 基线再生命令入参
+ */
+export type WriteLintBaselineInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 收编指针（非空；作为新条目盖章）
+   */
+  issuePointer: string;
+};
+
+/**
+ * 基线再生命令核
+ *
+ * @param input - 命令入参
+ * @returns 再生结果
+ */
+export function runWriteLintBaseline(input: WriteLintBaselineInput): WriteLintBaselineResult {
+  if (input.issuePointer.trim() === '') {
+    return { ok: false, error: '再生须携带非空 --issue <指针>（收编盖章）' };
+  }
+
+  /**
+   * 全集违规（跳过基线豁免口径）
+   */
+  const raw = runLint({
+    root: input.root,
+    config: input.config,
+    ignoreBaseline: true,
+  }).violations.filter((violation) => violation.rule !== 'baseline-stale');
+
+  /**
+   * 旧基线键集合
+   */
+  const oldKeys = new Set(
+    input.config.lint.baseline.map((entry) => `${entry.file}::${entry.rule}`),
+  );
+
+  /**
+   * 基线外新增违规（须先处置）
+   */
+  const newOutsideOld = raw.filter(
+    (violation) => !oldKeys.has(`${violation.file}::${violation.rule}`),
+  );
+
+  if (newOutsideOld.length > 0) {
+    /**
+     * 新增违规清单（拒绝报文）
+     */
+    const listing = newOutsideOld
+      .slice(0, 10)
+      .map((violation) => `${violation.file} [${violation.rule}]`)
+      .join('\n');
+
+    return {
+      ok: false,
+      error: `存在 ${newOutsideOld.length} 项基线外新增违规，拒绝再生（先处置新增违规后再收编存量）：\n${listing}`,
+    };
+  }
+
+  /**
+   * 再生条目（现行全集 + 收编指针盖章）
+   */
+  const entries: LintBaselineEntry[] = raw.map((violation) => ({
+    file: violation.file,
+    rule: violation.rule,
+    issue: input.issuePointer,
+  }));
+
+  return {
+    ok: true,
+    content: renderBaselineRegeneratedConfig(input.config, 'lint', entries),
+    entryCount: entries.length,
+  };
+}
+
+/**
+ * 从 lint 违规导出基线条目（排序去重；测试与工具消费）
+ *
+ * @param violations - 违规列表
+ * @param issuePointer - 收编指针
+ * @returns 基线条目列表
+ */
+export function deriveEntriesFromViolations(
+  violations: readonly LintViolation[],
+  issuePointer: string,
+): LintBaselineEntry[] {
+  return violations.map((violation) => ({
+    file: violation.file,
+    rule: violation.rule,
+    issue: issuePointer,
+  }));
+}

package/src/lint/lint.core.ts

@@ -0,0 +1,584 @@
+/**
+ * lint 规则核（12 条核心规则 + 规则包扩展点 + 棘轮基线三态）
+ *
+ * 判定全部基于 registry.parser 的解析产物（口径单一真源）；规则包经
+ * registerLintRulePack 注册、config lint.rulePacks 启用（引擎零仓库知识）。
+ * 基线三态：命中豁免→suppressed；未命中→active 红；条目无现行违规→stale 红
+ * （棘轮只许缩短）。
+ */
+
+import type { LintBaselineEntry, LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { matchMiniGlob } from '@/fs/mini-glob.utils';
+import { walkFilesUnderPrefixes } from '@/fs/walk-surface.utils';
+import { ASCII_KEBAB_SLUG_PATTERN } from '@/parser/format.utils';
+import { type IssueDocRecord, scanRegistryDir } from '@/parser/registry.parser';
+
+/**
+ * lint 违规
+ */
+export type LintViolation = {
+  /**
+   * issue 文件仓库相对 posix 路径
+   */
+  file: string;
+
+  /**
+   * 违规行号（0 = 全文级）
+   */
+  line: number;
+
+  /**
+   * 规则名
+   */
+  rule: string;
+
+  /**
+   * 人类可读违规消息
+   */
+  message: string;
+};
+
+/**
+ * lint 结果
+ */
+export type LintResult = {
+  /**
+   * 违规列表（active + baseline-stale，按 file/rule 排序）
+   */
+  violations: LintViolation[];
+
+  /**
+   * 基线豁免计数（命中存量）
+   */
+  suppressed: number;
+
+  /**
+   * 基线条目总数
+   */
+  baselineCount: number;
+};
+
+/**
+ * 规则判定上下文
+ */
+export type LintRuleContext = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 所属 scope key
+   */
+  scopeKey: string;
+
+  /**
+   * 注册表目录（posix 相对）
+   */
+  registryDir: string;
+
+  /**
+   * 该注册表全部文件名集合（blocking 引用存在性判定）
+   */
+  registryBasenames: ReadonlySet<string>;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+};
+
+/**
+ * 单条规则（返回违规消息即违规；null 放行）
+ */
+export type LintRule = {
+  /**
+   * 规则名（基线 (file, rule) 豁免键成分）
+   */
+  name: string;
+
+  /**
+   * 判定函数
+   *
+   * @param record - 解析产物
+   * @param ctx - 判定上下文
+   * @returns 违规消息；放行为 null
+   */
+  evaluate: (record: IssueDocRecord, ctx: LintRuleContext) => string | null;
+};
+
+/**
+ * 规则包注册表（packId → 规则列表）
+ */
+const rulePackRegistry = new Map<string, readonly LintRule[]>();
+
+/**
+ * 注册 lint 规则包（域规则扩展点；覆盖同名包）
+ *
+ * @param packId - 规则包 id（config lint.rulePacks 引用）
+ * @param rules - 规则列表
+ */
+export function registerLintRulePack(packId: string, rules: readonly LintRule[]): void {
+  rulePackRegistry.set(packId, rules);
+}
+
+/**
+ * 「状态行含判据锚点指引」识别标记（手工翻绿识别的判定成分）
+ */
+const CANONICAL_GREEN_HINT = '判据证据锚点见处置段';
+
+/**
+ * 读取评论边车条目 issueId 列表（Reflect.get 无断言窄化）
+ *
+ * @param value - 边车解析值
+ * @returns issueId 列表；结构非法（items 非数组）返回 null
+ */
+function readSidecarIssueIds(value: unknown): string[] | null {
+  if (typeof value !== 'object' || value === null) {
+    return null;
+  }
+
+  /**
+   * items 字段值
+   */
+  const items = Reflect.get(value, 'items');
+
+  if (items === undefined) {
+    return [];
+  }
+
+  if (!Array.isArray(items)) {
+    return null;
+  }
+
+  /**
+   * issueId 收集器
+   */
+  const ids: string[] = [];
+
+  for (const item of items) {
+    if (typeof item !== 'object' || item === null) {
+      continue;
+    }
+
+    /**
+     * 单条 issueId
+     */
+    const issueId = Reflect.get(item, 'issueId');
+
+    if (typeof issueId === 'string' && issueId !== '') {
+      ids.push(issueId);
+    }
+  }
+
+  return ids;
+}
+
+/**
+ * 核心规则全集（13 条）
+ */
+export const CORE_LINT_RULES: readonly LintRule[] = [
+  {
+    name: 'status-line-missing',
+    evaluate: (record) =>
+      record.status === 'unknown'
+        ? '头部 30 行内未定位到状态行（状态行是处理情况的第一入口）'
+        : null,
+  },
+  {
+    name: 'status-line-legacy-format',
+    evaluate: (record, ctx) =>
+      ctx.config.lint.strictLegacy &&
+      (record.status === 'legacy-yellow' || record.status === 'legacy-green')
+        ? `状态行为旧格式变体（${record.status}）——须迁移为规范五态写法`
+        : null,
+  },
+  {
+    name: 'yellow-no-pending-reason',
+    evaluate: (record) =>
+      (record.status === 'yellow' || record.status === 'legacy-yellow') &&
+      record.pendingReason === null
+        ? '黄灯（处理中）状态行须括注 ≥4 字挂起原因'
+        : null,
+  },
+  {
+    name: 'green-no-disposition-section',
+    evaluate: (record) =>
+      (record.status === 'green' || record.status === 'legacy-green') &&
+      !record.hasDispositionSection
+        ? '绿灯缺少「处置结果/验证口径」段'
+        : null,
+  },
+  {
+    name: 'green-disposition-placeholder',
+    evaluate: (record) =>
+      (record.status === 'green' || record.status === 'legacy-green') &&
+      record.hasDispositionSection &&
+      record.dispositionIsPlaceholder
+        ? '处置段仍为占位形态（处置中/待回填）——禁止虚标终态'
+        : null,
+  },
+  {
+    name: 'green-canonical-no-evidence-block',
+    evaluate: (record) =>
+      record.status === 'green' &&
+      record.statusLine.includes(CANONICAL_GREEN_HINT) &&
+      !record.hasEvidenceAnchorBlock
+        ? '状态行声称「判据证据锚点见处置段」而证据锚点块缺席（手工翻绿识别——收口须经 verify-close）'
+        : null,
+  },
+  {
+    name: 'frozen-format',
+    evaluate: (record) =>
+      record.status === 'frozen' && !/⚪\s*已冻结/.test(record.statusLine)
+        ? '冻结状态行须为「⚪ 已冻结（…）」规范形态'
+        : null,
+  },
+  {
+    name: 'frozen-no-adjudication-note',
+    evaluate: (record) =>
+      record.status === 'frozen' && !record.statusLine.includes('用户裁定')
+        ? '冻结状态行须含「用户裁定」语（工具拒绝形式冻结）'
+        : null,
+  },
+  {
+    name: 'issue-slug-non-ascii',
+    evaluate: (record) =>
+      ASCII_KEBAB_SLUG_PATTERN.test(record.slug)
+        ? null
+        : `slug 段须为纯 ASCII kebab（小写字母/数字/连字符，禁中文与非 ASCII 字符）：${record.file}`,
+  },
+  {
+    name: 'issue-slug-contains-digit',
+    evaluate: (record, ctx) => {
+      if (!/\d/.test(record.slug)) {
+        return null;
+      }
+
+      /**
+       * 仓库相对路径（白名单匹配口径）
+       */
+      const repoRelative = `${ctx.registryDir}/${record.file}`;
+
+      /**
+       * 白名单命中判定结果
+       */
+      const whitelisted = ctx.config.slugDigitAllowlist.some((entry) =>
+        matchMiniGlob(entry.glob, repoRelative),
+      );
+
+      return whitelisted
+        ? null
+        : `slug 段含数字（白名单登记请到配置 slugDigitAllowlist）：${record.file}`;
+    },
+  },
+  {
+    name: 'canceled-no-reason',
+    evaluate: (record) =>
+      record.status === 'canceled' && record.pendingReason === null
+        ? '已取消（⚫）状态行须括注 ≥4 字取消原因'
+        : null,
+  },
+  {
+    name: 'blocking-ref-unknown',
+    evaluate: (record, ctx) => {
+      /**
+       * 缺席阻塞引用列表
+       */
+      const missing = record.blockedByRefs.filter(
+        (ref) => !ctx.registryBasenames.has(`${ref.number}.md`),
+      );
+
+      return missing.length > 0
+        ? `「阻塞」引用的 issue 不存在：${missing.map((ref) => ref.number).join('、')}`
+        : null;
+    },
+  },
+  {
+    name: 'orphan-sidecar',
+    evaluate: (record, ctx) => {
+      /**
+       * 评论边车路径（.lzi/issues/comments/<scopeKey>/<NNNN>.json）
+       */
+      const commentsPath = join(
+        ctx.root,
+        '.lzi',
+        'issues',
+        'comments',
+        ctx.scopeKey,
+        `${record.id}.json`,
+      );
+
+      if (!existsSync(commentsPath)) {
+        return null;
+      }
+
+      try {
+        /**
+         * 边车解析产物
+         */
+        const parsed: unknown = JSON.parse(readFileSync(commentsPath, 'utf8'));
+
+        /**
+         * 边车 issueId 列表（结构非法返回 null）
+         */
+        const ids = readSidecarIssueIds(parsed);
+
+        if (ids === null) {
+          return '评论边车结构非法（items 非数组）——孤儿判定降级为违规提示';
+        }
+
+        /**
+         * 指向不存在 issue 的引用列表
+         */
+        const orphans = ids.filter((issueId) => !ctx.registryBasenames.has(`${issueId}.md`));
+
+        return orphans.length > 0
+          ? `评论边车存在孤儿引用（issue 不存在）：${orphans.join('、')}`
+          : null;
+      } catch {
+        return '评论边车 JSON 解析失败（孤儿判定降级为违规提示）';
+      }
+    },
+  },
+];
+
+/**
+ * lint 命令入参
+ */
+export type RunLintInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 限定注册表目录（缺省全部 scope）
+   */
+  dirRels?: readonly string[];
+
+  /**
+   * 是否跳过基线豁免（write-baseline 再生口径：全集违规）
+   */
+  ignoreBaseline?: boolean;
+};
+
+/**
+ * 运行 lint（核心规则 + 启用的规则包 + 棘轮基线三态）
+ *
+ * @param input - 命令入参
+ * @returns lint 结果（violations 非空即违规）
+ */
+export function runLint(input: RunLintInput): LintResult {
+  /**
+   * 生效规则列表（核心 + config 启用的规则包）
+   */
+  const rules: LintRule[] = [...CORE_LINT_RULES];
+
+  for (const packId of input.config.lint.rulePacks) {
+    /**
+     * 命中规则包
+     */
+    const pack = rulePackRegistry.get(packId);
+
+    if (pack !== undefined) {
+      rules.push(...pack);
+    }
+  }
+
+  /**
+   * 参与判定的 scope 列表
+   */
+  const scopes =
+    input.dirRels === undefined
+      ? input.config.scopes
+      : input.config.scopes.filter((scope) => input.dirRels?.includes(scope.registryDir));
+
+  /**
+   * 全量违规收集器（基线豁免前）
+   */
+  const raw: LintViolation[] = [];
+
+  for (const scope of scopes) {
+    /**
+     * 注册表解析产物列表
+     */
+    const records = scanRegistryDir(join(input.root, scope.registryDir));
+
+    /**
+     * 注册表文件名集合（blocking 存在性判定）
+     */
+    const basenames = new Set(records.map((record) => record.file));
+
+    /**
+     * 判定上下文
+     */
+    const ctx: LintRuleContext = {
+      root: input.root,
+      scopeKey: scope.key,
+      registryDir: scope.registryDir,
+      registryBasenames: basenames,
+      config: input.config,
+    };
+
+    for (const record of records) {
+      for (const rule of rules) {
+        /**
+         * 规则判定结果
+         */
+        const message = rule.evaluate(record, ctx);
+
+        if (message !== null) {
+          raw.push({
+            file: `${scope.registryDir}/${record.file}`,
+            line: record.statusLineNumber,
+            rule: rule.name,
+            message,
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * 基线查找表 ((file, rule) → issue 指针)
+   */
+  const baseline = new Map<string, LintBaselineEntry>(
+    input.config.lint.baseline.map((entry) => [`${entry.file}::${entry.rule}`, entry]),
+  );
+
+  if (input.ignoreBaseline === true) {
+    return {
+      violations: raw.sort(compareViolations),
+      suppressed: 0,
+      baselineCount: baseline.size,
+    };
+  }
+
+  /**
+   * active 违规（基线外新增）
+   */
+  const active: LintViolation[] = [];
+
+  /**
+   * 基线豁免计数
+   */
+  let suppressed = 0;
+
+  /**
+   * 已命中基线键集合（stale 对账用）
+   */
+  const matchedBaselineKeys = new Set<string>();
+
+  for (const violation of raw) {
+    /**
+     * 基线键
+     */
+    const key = `${violation.file}::${violation.rule}`;
+
+    if (baseline.has(key)) {
+      suppressed += 1;
+      matchedBaselineKeys.add(key);
+
+      continue;
+    }
+
+    active.push(violation);
+  }
+
+  /**
+   * stale 基线条目（无对应现行违规——棘轮只许缩短）
+   */
+  const stale: LintViolation[] = [...baseline.entries()]
+    .filter(([key]) => !matchedBaselineKeys.has(key))
+    .map(([key, entry]) => ({
+      file: key.split('::')[0] ?? '',
+      line: 0,
+      rule: 'baseline-stale',
+      message: `基线条目已无对应现行违规——棘轮只许缩短，须同步删除该条目（收编指针：${entry.issue}）`,
+    }));
+
+  return {
+    violations: [...active, ...stale].sort(compareViolations),
+    suppressed,
+    baselineCount: baseline.size,
+  };
+}
+
+/**
+ * 违规排序比较器（file 升序、rule 次序）
+ *
+ * @param left - 左违规
+ * @param right - 右违规
+ * @returns 排序值
+ */
+function compareViolations(left: LintViolation, right: LintViolation): number {
+  if (left.file !== right.file) {
+    return left.file.localeCompare(right.file);
+  }
+
+  return left.rule.localeCompare(right.rule);
+}
+
+/**
+ * 全仓 sidecar 孤儿扫描辅助（orphan-sidecar 的目录级补充：边车存在而注册表无文件）
+ *
+ * @param root - 仓库根绝对路径
+ * @param config - 解析后配置
+ * @returns 孤儿边车违规列表
+ */
+export function scanOrphanSidecars(root: string, config: LziIssuesConfig): LintViolation[] {
+  /**
+   * 违规收集器
+   */
+  const violations: LintViolation[] = [];
+
+  for (const scope of config.scopes) {
+    /**
+     * 评论边车目录
+     */
+    const sidecarDir = join(root, '.lzi', 'issues', 'comments', scope.key);
+
+    if (!existsSync(sidecarDir)) {
+      continue;
+    }
+
+    /**
+     * 注册表现存编号集合
+     */
+    const existing = new Set(
+      scanRegistryDir(join(root, scope.registryDir)).map((record) => record.id),
+    );
+
+    for (const file of walkFilesUnderPrefixes(sidecarDir, [''])) {
+      /**
+       * 边车编号（文件名去扩展名）
+       */
+      const id =
+        file
+          .split('/')
+          .pop()
+          ?.replace(/\.json$/, '') ?? '';
+
+      if (id !== '' && !existing.has(id)) {
+        violations.push({
+          file: `.lzi/issues/comments/${scope.key}/${id}.json`,
+          line: 0,
+          rule: 'orphan-sidecar',
+          message: `评论边车为孤儿（注册表无 ${scope.registryDir}/${id}-*.md）——请联动清理`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}