@longzai-intelligence-issues/ledger 0.0.1

package/src/numbering/numbering.commands.ts

@@ -0,0 +1,375 @@
+/**
+ * 编号门禁命令核（fs 编排层）
+ *
+ * 承接 next / check（全量与目录增量）/ audit 三命令的文件系统编排：扫描面收集
+ * 走 walk-surface 前缀定向，判定全部委托 numbering.core 纯函数。结果对象携带
+ * 退出语义（findings 非空即违规），报文渲染由 CLI 层承担。
+ */
+
+import type { LziIssuesConfig, ScopeEntry } from '@longzai-intelligence-issues/config';
+
+import { join } from 'node:path';
+
+import { walkFilesUnderPrefixes, walkFilesUnderRoots } from '@/fs/walk-surface.utils';
+
+import {
+  auditCoverage,
+  computeNextNumber,
+  type NumberingAllowlistEntry,
+  type NumberingAuditFinding,
+  type NumberingFinding,
+  type NumberingKeyRule,
+  scanScopeForFindings,
+} from './numbering.core.js';
+
+/**
+ * issues 注册表键规则（数字前缀；v1 注册表固定形态）
+ */
+export const ISSUES_KEY_RULE: NumberingKeyRule = { kind: 'numericPrefix' };
+
+/**
+ * 取号命令结果
+ */
+export type NumberingNextResult =
+  | {
+      /**
+       * 取号成功标记
+       */
+      ok: true;
+
+      /**
+       * 下一可用编号（零填充）
+       */
+      number: string;
+
+      /**
+       * 取号目标描述（scope key 或目录）
+       */
+      target: string;
+
+      /**
+       * 跳过的已占用号数
+       */
+      skippedOccupied: number;
+
+      /**
+       * 跳过的保留号数
+       */
+      skippedReserved: number;
+    }
+  | {
+      /**
+       * 取号成功标记
+       */
+      ok: false;
+
+      /**
+       * 失败原因
+       */
+      error: string;
+    };
+
+/**
+ * 检查命令结果
+ */
+export type NumberingCheckResult = {
+  /**
+   * 违例列表（空 = 通过）
+   */
+  findings: NumberingFinding[];
+
+  /**
+   * 参与判定的 scope 数
+   */
+  scopeCount: number;
+
+  /**
+   * 扫描面文件数
+   */
+  scannedFiles: number;
+};
+
+/**
+ * 审计命令结果
+ */
+export type NumberingAuditResult = {
+  /**
+   * 违例列表（空 = 通过）
+   */
+  findings: NumberingAuditFinding[];
+
+  /**
+   * 全仓扫描面文件数
+   */
+  scannedFiles: number;
+};
+
+/**
+ * 收集注册表目录文件名列表（前缀定向，含非编号文件——键提取口径天然过滤）
+ *
+ * @param root - 仓库根绝对路径
+ * @param registryDir - 注册表目录（posix 相对）
+ * @returns 文件名列表
+ */
+function collectBasenames(root: string, registryDir: string): string[] {
+  return walkFilesUnderPrefixes(root, [registryDir]).map((file) => file.split('/').pop() ?? '');
+}
+
+/**
+ * 取号命令入参
+ */
+export type NumberingNextCommandInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 目标 scope key（与 dirRel 互斥）
+   */
+  scopeKey?: string;
+
+  /**
+   * 目标注册表目录（posix 相对，与 scopeKey 互斥）
+   */
+  dirRel?: string;
+};
+
+/**
+ * 取号命令核（只读不写；编号写入时刻确定——落盘前重跑取最新值）
+ *
+ * @param input - 命令入参
+ * @returns 取号结果
+ */
+export function runNumberingNext(input: NumberingNextCommandInput): NumberingNextResult {
+  /**
+   * 双目标同时提供标记
+   */
+  const bothGiven = input.scopeKey !== undefined && input.dirRel !== undefined;
+
+  /**
+   * 双目标同时缺席标记
+   */
+  const neitherGiven = input.scopeKey === undefined && input.dirRel === undefined;
+
+  if (bothGiven || neitherGiven) {
+    return { ok: false, error: '取号须且仅须指定 --scope <key> 或 --dir <目录> 之一' };
+  }
+
+  if (input.scopeKey !== undefined) {
+    /**
+     * 目标 scope
+     */
+    const scope = input.config.scopes.find((entry) => entry.key === input.scopeKey);
+
+    if (scope === undefined) {
+      return {
+        ok: false,
+        error: `scope「${input.scopeKey}」未登记（请在 lzi-issues.config.ts 注册）`,
+      };
+    }
+
+    /**
+     * 取号结果
+     */
+    const next = computeNextNumber({
+      basenames: collectBasenames(input.root, scope.registryDir),
+      rule: ISSUES_KEY_RULE,
+      reserved: scope.numbering.reserved.map((entry) => entry.number),
+    });
+
+    if (!next.ok) {
+      return next;
+    }
+
+    return {
+      ok: true,
+      number: next.number,
+      target: scope.key,
+      skippedOccupied: next.skippedOccupied,
+      skippedReserved: next.skippedReserved,
+    };
+  }
+
+  /**
+   * 目录模式：覆盖 scope 查找（registryDir 精确等于目录）
+   */
+  const covering = input.config.scopes.filter((scope) => scope.registryDir === input.dirRel);
+
+  if (covering.length === 0) {
+    return {
+      ok: false,
+      error: `目录「${input.dirRel}」未登记为任何 scope 的注册表（请在 lzi-issues.config.ts 注册后再取号）`,
+    };
+  }
+
+  /**
+   * 保留号并集（保守防复用）
+   */
+  const reservedUnion = [
+    ...new Set(covering.flatMap((scope) => scope.numbering.reserved.map((r) => r.number))),
+  ];
+
+  /**
+   * 目录模式取号结果
+   */
+  const next = computeNextNumber({
+    basenames: collectBasenames(input.root, input.dirRel ?? ''),
+    rule: ISSUES_KEY_RULE,
+    reserved: reservedUnion,
+  });
+
+  if (!next.ok) {
+    return next;
+  }
+
+  return {
+    ok: true,
+    number: next.number,
+    target: input.dirRel ?? '',
+    skippedOccupied: next.skippedOccupied,
+    skippedReserved: next.skippedReserved,
+  };
+}
+
+/**
+ * 检查命令入参
+ */
+export type NumberingCheckCommandInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 目录增量档目标（缺省全量档）
+   */
+  dirRel?: string;
+};
+
+/**
+ * 检查命令核（全量档 / 目录增量档）
+ *
+ * 目录增量档：只判覆盖 scope，豁免按目录过滤（防其他目录条目误判 stale），
+ * 不跑 slug 白名单失效对账（扫描面不完整防假阳性）。
+ *
+ * @param input - 命令入参
+ * @returns 检查结果
+ */
+export function runNumberingCheck(input: NumberingCheckCommandInput): NumberingCheckResult {
+  /**
+   * 参与判定的 scope 列表
+   */
+  const scopes: ScopeEntry[] =
+    input.dirRel === undefined
+      ? input.config.scopes
+      : input.config.scopes.filter((scope) => scope.registryDir === input.dirRel);
+
+  /**
+   * 违例收集器
+   */
+  const findings: NumberingFinding[] = [];
+
+  /**
+   * 扫描面文件计数
+   */
+  let scannedFiles = 0;
+
+  for (const scope of scopes) {
+    /**
+     * 注册表文件名列表
+     */
+    const basenames = collectBasenames(input.root, scope.registryDir);
+
+    scannedFiles += basenames.length;
+
+    /**
+     * 全量档豁免（scope 维度过滤）
+     */
+    const allowlist: NumberingAllowlistEntry[] =
+      input.dirRel === undefined
+        ? input.config.numbering.allowlist
+            .filter((entry) => entry.scopeKey === scope.key)
+            .map((entry) => ({ ...entry, files: [...entry.files] }))
+        : input.config.numbering.allowlist
+            .filter(
+              (entry) =>
+                entry.scopeKey === scope.key &&
+                entry.files.some((file) => file.startsWith(`${input.dirRel}/`)),
+            )
+            .map((entry) => ({ ...entry, files: [...entry.files] }));
+
+    findings.push(
+      ...scanScopeForFindings({
+        scopeKey: scope.key,
+        basenames,
+        rule: ISSUES_KEY_RULE,
+        reserved: scope.numbering.reserved,
+        allowlist,
+        slugDigitPolicy: scope.slugDigitPolicy,
+        slugDigitAllowlist: input.config.slugDigitAllowlist.map((entry) => entry.glob),
+        toRepoRelative: (basename) => `${scope.registryDir}/${basename}`,
+        fullMode: input.dirRel === undefined,
+      }),
+    );
+  }
+
+  return { findings, scopeCount: scopes.length, scannedFiles };
+}
+
+/**
+ * 审计命令入参
+ */
+export type NumberingAuditCommandInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+};
+
+/**
+ * 审计命令核（全仓严格遍历防逃逸；审计根缺失抛错防扫描面缩水）
+ *
+ * @param input - 命令入参
+ * @returns 审计结果
+ * @throws {@link Error} 审计根缺失
+ */
+export function runNumberingAudit(input: NumberingAuditCommandInput): NumberingAuditResult {
+  /**
+   * 全仓扫描面文件收集器（posix 相对根路径）
+   */
+  const files: string[] = [];
+
+  for (const auditRoot of input.config.numbering.audit.roots) {
+    files.push(
+      ...walkFilesUnderRoots(join(input.root, auditRoot), {
+        excludeGlobs: input.config.numbering.globalExclusions.map((entry) => entry.glob),
+      }).map((file) => (auditRoot === '' ? file : `${auditRoot}/${file}`)),
+    );
+  }
+
+  return {
+    findings: auditCoverage({
+      files,
+      numberishPattern: input.config.numbering.audit.numberishPattern,
+      registryDirs: input.config.scopes.map((scope) => scope.registryDir),
+      pending: input.config.numbering.audit.pending,
+    }),
+    scannedFiles: files.length,
+  };
+}