@longzai-intelligence-issues/ledger 0.0.1

package/src/numbering/numbering.core.ts

@@ -0,0 +1,685 @@
+/**
+ * 编号门禁核心（纯函数，零 fs）
+ *
+ * apex numbering-guard 语义迁移：四类键型提取、取号（max+1 顺延跳已占与保留、
+ * 宽度随最大键）、五类违例扫描（目录=编号命名空间）、slug 数字策略、覆盖面
+ * 审计。文件系统编排由 numbering.commands 承担，本模块可独立测试。
+ */
+
+import { matchMiniGlob } from '@/fs/mini-glob.utils';
+
+/**
+ * 编号键规则（判别联合；v1 issues 注册表固定 numericPrefix，其余键型供通用引擎使用）
+ */
+export type NumberingKeyRule =
+  | { kind: 'numericPrefix' }
+  | { kind: 'compositePrefix'; groups: number }
+  | { kind: 'numericSuffix' }
+  | { kind: 'customPattern'; pattern: string };
+
+/**
+ * 编号违例种类
+ */
+export type NumberingFindingKind =
+  | 'duplicate'
+  | 'reservedOccupied'
+  | 'widthInconsistent'
+  | 'allowlistStale'
+  | 'slugContainsDigit'
+  | 'slugDigitAllowlistStale';
+
+/**
+ * 编号违例
+ */
+export type NumberingFinding = {
+  /**
+   * 违例种类
+   */
+  kind: NumberingFindingKind;
+
+  /**
+   * 所属 scope（slugDigitAllowlistStale 为 'global'）
+   */
+  scopeKey: string;
+
+  /**
+   * 人类可读违例消息（含文件清单与处置指引）
+   */
+  message: string;
+};
+
+/**
+ * 审计违例种类
+ */
+export type NumberingAuditFindingKind = 'coverageGap' | 'pendingStale';
+
+/**
+ * 审计违例
+ */
+export type NumberingAuditFinding = {
+  /**
+   * 违例种类
+   */
+  kind: NumberingAuditFindingKind;
+
+  /**
+   * 人类可读违例消息
+   */
+  message: string;
+};
+
+/**
+ * 编号豁免条目（引擎消费形态；files 为仓库相对 posix 路径，精确文件集）
+ */
+export type NumberingAllowlistEntry = {
+  /**
+   * 所属 scope key
+   */
+  scopeKey: string;
+
+  /**
+   * 豁免编号
+   */
+  number: string;
+
+  /**
+   * 精确文件集（排序后与磁盘对照）
+   */
+  files: string[];
+
+  /**
+   * 棘轮状态
+   */
+  status: string;
+
+  /**
+   * 豁免理由
+   */
+  reason: string;
+};
+
+/**
+ * 提取文件名编号键
+ *
+ * 提不出键的文件（README 等）返回 null，天然不占号。
+ *
+ * @param basename - 文件名
+ * @param rule - 键规则
+ * @returns 编号键原文；无键为 null
+ */
+export function extractFileKey(basename: string, rule: NumberingKeyRule): string | null {
+  if (rule.kind === 'numericPrefix') {
+    return /^(\d+)(?=[-._ ]|$)/.exec(basename)?.[1] ?? null;
+  }
+
+  if (rule.kind === 'compositePrefix') {
+    /**
+     * 复合键正则（2-5 段数字，段间 - _ . 或空格分隔）
+     */
+    const pattern = new RegExp(`^(\\d+(?:[-._ ]\\d+){${rule.groups - 1}})(?=[-._ ]|$)`);
+
+    return pattern.exec(basename)?.[1] ?? null;
+  }
+
+  if (rule.kind === 'numericSuffix') {
+    /**
+     * 剥最后一个扩展名后的主干
+     */
+    const stem = basename.replace(/\.[^.]+$/, '');
+
+    return /(\d+)$/.exec(stem)?.[1] ?? null;
+  }
+
+  /**
+   * 自定义正则（具名捕获组 key）
+   */
+  const custom = new RegExp(rule.pattern).exec(basename);
+
+  return custom?.groups?.key ?? null;
+}
+
+/**
+ * 提取键的前导数值
+ *
+ * @param key - 编号键
+ * @returns 前导数值；非数字键为 null
+ */
+export function keyLeadingNumber(key: string): number | null {
+  /**
+   * 前导数字命中
+   */
+  const match = /^\d+/.exec(key);
+
+  return match === null ? null : Number.parseInt(match[0] ?? '', 10);
+}
+
+/**
+ * 取号入参
+ */
+export type NextNumberInput = {
+  /**
+   * 扫描面文件名列表（键提取口径占号）
+   */
+  basenames: readonly string[];
+
+  /**
+   * 键规则
+   */
+  rule: NumberingKeyRule;
+
+  /**
+   * 保留号列表（不回收复用）
+   */
+  reserved: readonly string[];
+};
+
+/**
+ * 取号结果
+ */
+export type NextNumberResult =
+  | { ok: true; number: string; skippedOccupied: number; skippedReserved: number }
+  | { ok: false; error: string };
+
+/**
+ * 取号：max+1 起顺延，跳过磁盘已占与保留号，取首个空闲
+ *
+ * 宽度 = 数值最大键的字符串长度（零填充跟随现行形态）；空范围拒绝取号（无法
+ * 推断位数，人工定号）。
+ *
+ * @param input - 取号入参
+ * @returns 取号结果
+ */
+export function computeNextNumber(input: NextNumberInput): NextNumberResult {
+  /**
+   * 已占键集合（磁盘原文形态，保留零填充）
+   */
+  const occupied = new Set<string>();
+
+  for (const basename of input.basenames) {
+    /**
+     * 文件键
+     */
+    const key = extractFileKey(basename, input.rule);
+
+    if (key !== null) {
+      occupied.add(key);
+    }
+  }
+
+  if (occupied.size === 0) {
+    return { ok: false, error: '该范围当前无编号文件，无法推断位数——请人工定号后落盘' };
+  }
+
+  /**
+   * 数值最大键（宽度与起点基准）
+   */
+  let maxKey = '';
+
+  for (const key of occupied) {
+    if ((keyLeadingNumber(key) ?? 0) > (keyLeadingNumber(maxKey) || 0)) {
+      maxKey = key;
+    }
+  }
+
+  if (maxKey === '') {
+    return { ok: false, error: '该范围无数字前缀键，无法取号' };
+  }
+
+  /**
+   * 零填充宽度
+   */
+  const width = maxKey.length;
+
+  /**
+   * 保留号集合
+   */
+  const reserved = new Set(input.reserved);
+
+  /**
+   * 跳过统计
+   */
+  let skippedOccupied = 0;
+
+  /**
+   * 跳过保留号计数
+   */
+  let skippedReserved = 0;
+
+  /**
+   * 候选号（自 max+1 顺延）
+   */
+  let candidate = (keyLeadingNumber(maxKey) ?? 0) + 1;
+
+  for (;;) {
+    /**
+     * 零填充形态候选
+     */
+    const formatted = String(candidate).padStart(width, '0');
+
+    if (occupied.has(formatted)) {
+      skippedOccupied += 1;
+      candidate += 1;
+
+      continue;
+    }
+
+    if (reserved.has(formatted)) {
+      skippedReserved += 1;
+      candidate += 1;
+
+      continue;
+    }
+
+    return { ok: true, number: formatted, skippedOccupied, skippedReserved };
+  }
+}
+
+/**
+ * 提取文件名 slug 段（剥前缀键 + 单个分隔符 + 最后一个扩展名）
+ *
+ * 空.slug 放行（返回空串）；非前缀数字形态返回 null（不属判定面）。
+ *
+ * @param basename - 文件名
+ * @returns slug 段；非判定面为 null
+ */
+export function extractSlugSegment(basename: string): string | null {
+  /**
+   * 前缀数字键 + 分隔符 + slug + 扩展名形态
+   */
+  const match = /^\d+[-._ ](.+)\.[^.]+$/.exec(basename);
+
+  if (match === null) {
+    return null;
+  }
+
+  return match[1] ?? '';
+}
+
+/**
+ * 违例扫描入参（单 scope）
+ */
+export type ScopeScanInput = {
+  /**
+   * scope key
+   */
+  scopeKey: string;
+
+  /**
+   * 扫描面文件名列表
+   */
+  basenames: readonly string[];
+
+  /**
+   * 键规则
+   */
+  rule: NumberingKeyRule;
+
+  /**
+   * 保留号（含理由，报文引用）
+   */
+  reserved: ReadonlyArray<{ number: string; reason: string }>;
+
+  /**
+   * 该 scope 的豁免条目（files 为仓库相对 posix 路径）
+   */
+  allowlist: readonly NumberingAllowlistEntry[];
+
+  /**
+   * slug 数字策略（'forbid' 启用判定）
+   */
+  slugDigitPolicy?: 'forbid';
+
+  /**
+   * slug 数字白名单 glob（仓库相对路径命中豁免）
+   */
+  slugDigitAllowlist: readonly string[];
+
+  /**
+   * 文件仓库相对路径构造器（slug 白名单匹配口径）
+   */
+  toRepoRelative: (basename: string) => string;
+
+  /**
+   * 全量档标记（true 时追加 slug 白名单失效对账）
+   */
+  fullMode: boolean;
+};
+
+/**
+ * 排序数组双向相等判定
+ *
+ * @param left - 左列表
+ * @param right - 右列表
+ * @returns 排序后是否逐项相等
+ */
+function sortedEqual(left: readonly string[], right: readonly string[]): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  /**
+   * 左右排序副本
+   */
+  const sortedLeft = [...left].sort();
+
+  /**
+   * 右列表排序副本
+   */
+  const sortedRight = [...right].sort();
+
+  return sortedLeft.every((item, index) => item === sortedRight[index]);
+}
+
+/**
+ * 单 scope 违例扫描（目录=编号命名空间）
+ *
+ * 判定顺序：先撞号组（豁免须排序文件集双向相等精确覆盖）后保留号；全部组判
+ * 完后逐豁免条目对账（棘轮只许缩短）。
+ *
+ * @param input - 扫描入参
+ * @returns 违例列表
+ */
+export function scanScopeForFindings(input: ScopeScanInput): NumberingFinding[] {
+  /**
+   * 违例收集器
+   */
+  const findings: NumberingFinding[] = [];
+
+  /**
+   * 键分组（键 → 文件名列表）
+   */
+  const groups = new Map<string, string[]>();
+
+  for (const basename of input.basenames) {
+    /**
+     * 文件键
+     */
+    const key = extractFileKey(basename, input.rule);
+
+    if (key === null) {
+      continue;
+    }
+
+    groups.set(key, [...(groups.get(key) ?? []), basename]);
+  }
+
+  /**
+   * 保留号查找表
+   */
+  const reservedMap = new Map(input.reserved.map((entry) => [entry.number, entry.reason]));
+
+  /**
+   * 已对账豁免条目下标集
+   */
+  const consumedAllowlist = new Set<number>();
+
+  for (const [key, files] of groups) {
+    if (files.length >= 2) {
+      /**
+       * 撞号豁免命中判定（同键且排序文件集双向相等）
+       */
+      const coveredIndex = input.allowlist.findIndex(
+        (entry, index) =>
+          !consumedAllowlist.has(index) &&
+          entry.number === key &&
+          sortedEqual(
+            entry.files,
+            files.map((file) => input.toRepoRelative(file)),
+          ),
+      );
+
+      if (coveredIndex === -1) {
+        findings.push({
+          kind: 'duplicate',
+          scopeKey: input.scopeKey,
+          message: `scope「${input.scopeKey}」编号 ${key} 撞号：${files.join('、')}——先入库者保号，后到线顺延清偿`,
+        });
+      } else {
+        consumedAllowlist.add(coveredIndex);
+      }
+
+      continue;
+    }
+
+    /**
+     * 单文件组：保留号占用判定
+     */
+    const reservedReason = reservedMap.get(key);
+
+    if (reservedReason !== undefined) {
+      findings.push({
+        kind: 'reservedOccupied',
+        scopeKey: input.scopeKey,
+        message: `scope「${input.scopeKey}」保留号 ${key} 被占用（${files.join('、')}；保留理由：${reservedReason}——保留号不回收复用，请让号重编`,
+      });
+    }
+  }
+
+  /**
+   * 零填充族位数一致性：存在长度>1 且以 0 起首的键即成族（目录全键入族），
+   * 族内键长度集合 >1 即混用（混入无填充键同样计混用）
+   */
+  const zeroPaddedExists = [...groups.keys()].some((key) => key.length > 1 && key.startsWith('0'));
+
+  if (zeroPaddedExists) {
+    /**
+     * 族内键长度集合（目录全部键）
+     */
+    const widths = new Set([...groups.keys()].map((key) => key.length));
+
+    if (widths.size > 1) {
+      findings.push({
+        kind: 'widthInconsistent',
+        scopeKey: input.scopeKey,
+        message: `scope「${input.scopeKey}」零填充位数混用（族内键长 ${[...widths].sort((a, b) => a - b).join('/')}）：${[...groups.keys()].slice(0, 6).join('、')}`,
+      });
+    }
+  }
+
+  /**
+   * 豁免条目对账（allowlistStale——棘轮只许缩短）
+   */
+  input.allowlist.forEach((entry, index) => {
+    if (consumedAllowlist.has(index)) {
+      return;
+    }
+
+    /**
+     * 同键磁盘现状（对账展示用）
+     */
+    const diskFiles = entry.files.filter((file) => {
+      /**
+       * 磁盘文件名
+       */
+      const basename = file.split('/').pop() ?? '';
+
+      return (groups.get(entry.number) ?? []).includes(basename);
+    });
+
+    findings.push({
+      kind: 'allowlistStale',
+      scopeKey: input.scopeKey,
+      message: `scope「${input.scopeKey}」豁免条目（${entry.number}，${entry.status}）已无对应现行撞号组——棘轮只许缩短，须同步删除该条目（登记集：${entry.files.join('、')}；磁盘现状：${diskFiles.length > 0 ? diskFiles.join('、') : '无'}）`,
+    });
+  });
+
+  if (input.slugDigitPolicy === 'forbid') {
+    /**
+     * slug 白名单命中集合（全量档失效对账用）
+     */
+    const allowlistHits = new Set<string>();
+
+    for (const basename of input.basenames) {
+      /**
+       * slug 段
+       */
+      const slug = extractSlugSegment(basename);
+
+      if (slug === null || slug === '' || !/\d/.test(slug)) {
+        continue;
+      }
+
+      /**
+       * 仓库相对路径（白名单匹配口径）
+       */
+      const repoRelative = input.toRepoRelative(basename);
+
+      /**
+       * 白名单命中判定
+       */
+      const whitelisted = input.slugDigitAllowlist.some((glob) => {
+        if (matchMiniGlob(glob, repoRelative)) {
+          allowlistHits.add(glob);
+
+          return true;
+        }
+
+        return false;
+      });
+
+      if (!whitelisted) {
+        findings.push({
+          kind: 'slugContainsDigit',
+          scopeKey: input.scopeKey,
+          message: `scope「${input.scopeKey}」slug 段含数字：${basename}（白名单登记请到配置 slugDigitAllowlist，逐条带理由）`,
+        });
+      }
+    }
+
+    if (input.fullMode) {
+      /**
+       * 白名单失效对账（policy 启用域内命中不到任何文件即失效）
+       */
+      for (const glob of input.slugDigitAllowlist) {
+        if (!allowlistHits.has(glob)) {
+          findings.push({
+            kind: 'slugDigitAllowlistStale',
+            scopeKey: 'global',
+            message: `slug 白名单条目「${glob}」在启用域内已匹配不到任何文件——棘轮只许缩短，须同步删除该条目`,
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * 覆盖面审计入参
+ */
+export type AuditCoverageInput = {
+  /**
+   * 全仓扫描面文件列表（posix 相对路径，已过全局排除）
+   */
+  files: readonly string[];
+
+  /**
+   * 形似编号筛选模式（作用于 basename）
+   */
+  numberishPattern: string;
+
+  /**
+   * 已登记注册表目录列表（文件落于其下即被 scope 收编）
+   */
+  registryDirs: readonly string[];
+
+  /**
+   * pending 探针列表（glob + 理由；命中即视为已规划覆盖）
+   */
+  pending: ReadonlyArray<{ glob: string; reason: string }>;
+};
+
+/**
+ * 覆盖面审计：形似编号文件必须被 scope / 排除 / pending 三者之一覆盖
+ *
+ * 未覆盖按目录聚合为 coverageGap；pending 未命中计 pendingStale。
+ *
+ * @param input - 审计入参
+ * @returns 审计违例列表
+ */
+export function auditCoverage(input: AuditCoverageInput): NumberingAuditFinding[] {
+  /**
+   * 违例收集器
+   */
+  const findings: NumberingAuditFinding[] = [];
+
+  /**
+   * 形似编号筛选正则
+   */
+  const numberish = new RegExp(input.numberishPattern);
+
+  /**
+   * 未覆盖文件按目录聚合
+   */
+  const gapDirs = new Map<string, string[]>();
+
+  /**
+   * pending 命中标记
+   */
+  const pendingMatched = new Set<string>();
+
+  for (const file of input.files) {
+    /**
+     * 文件名
+     */
+    const basename = file.split('/').pop() ?? '';
+
+    if (!numberish.test(basename)) {
+      continue;
+    }
+
+    /**
+     * scope 收编判定
+     */
+    const coveredByScope = input.registryDirs.some(
+      (dir) => file === dir || file.startsWith(`${dir}/`),
+    );
+
+    if (coveredByScope) {
+      continue;
+    }
+
+    /**
+     * pending 覆盖判定
+     */
+    const pendingHit = input.pending.find((entry) => {
+      if (matchMiniGlob(entry.glob, file)) {
+        pendingMatched.add(entry.glob);
+
+        return true;
+      }
+
+      return false;
+    });
+
+    if (pendingHit !== undefined) {
+      continue;
+    }
+
+    /**
+     * 未覆盖：按目录聚合
+     */
+    const dir = file.split('/').slice(0, -1).join('/');
+
+    gapDirs.set(dir, [...(gapDirs.get(dir) ?? []), basename]);
+  }
+
+  for (const dir of [...gapDirs.keys()].sort((a, b) => a.localeCompare(b))) {
+    findings.push({
+      kind: 'coverageGap',
+      message: `未登记编号区：目录 ${dir === '' ? '（仓库根）' : dir} 有 ${gapDirs.get(dir)?.length ?? 0} 个编号文件未被任何 scope/pending 覆盖——${(gapDirs.get(dir) ?? []).join('、')}（请在 lzi-issues.config.ts 登记 scope 或 pending 并注明理由）`,
+    });
+  }
+
+  for (const entry of input.pending) {
+    if (!pendingMatched.has(entry.glob)) {
+      findings.push({
+        kind: 'pendingStale',
+        message: `pending 条目「${entry.glob}」已匹配不到任何编号文件——棘轮只许缩短，须同步删除该条目（登记理由：${entry.reason}）`,
+      });
+    }
+  }
+
+  return findings;
+}