@longzai-intelligence-issues/ledger 0.0.4 → 0.0.5

package/src/numbering/numbering.core.ts

@@ -2,8 +2,9 @@
  * 编号门禁核心（纯函数，零 fs）
  *
  * apex numbering-guard 语义迁移：四类键型提取、取号（max+1 顺延跳已占与保留、
- * 宽度随最大键）、五类违例扫描（目录=编号命名空间）、slug 数字策略、覆盖面
- * 审计。文件系统编排由 numbering.commands 承担，本模块可独立测试。
+ * 宽度随最大键）、五类违例扫描（目录=编号命名空间）、slug 数字策略、slug 白名单
+ * 失效对账（跨 scope 聚合口径）、覆盖面审计。文件系统编排由 numbering.commands
+ * 承担，本模块可独立测试。
  */
 
 import { matchMiniGlob } from '@/fs/mini-glob.utils';
@@ -338,11 +339,23 @@ export type ScopeScanInput = {
    * 文件仓库相对路径构造器（slug 白名单匹配口径）
    */
   toRepoRelative: (basename: string) => string;
+};
+
+/**
+ * 单 scope 扫描结果
+ */
+export type ScopeScanResult = {
+  /**
+   * 违例列表
+   */
+  findings: NumberingFinding[];
 
   /**
-   * 全量档标记（true 时追加 slug 白名单失效对账）
+   * slug 白名单命中 glob 列表（本 scope 启用域内实匹配到含数字 slug 文件的条目；
+   * 全局条目只在其文件所属 scope 命中——失效对账须由调用方跨全部 scope 聚合
+   * 命中集后经 reconcileSlugDigitAllowlist 统一判定，单 scope 命中集不构成全局口径）
    */
-  fullMode: boolean;
+  slugDigitAllowlistHits: string[];
 };
 
 /**
@@ -374,12 +387,13 @@ function sortedEqual(left: readonly string[], right: readonly string[]): boolean
  * 单 scope 违例扫描（目录=编号命名空间）
  *
  * 判定顺序：先撞号组（豁免须排序文件集双向相等精确覆盖）后保留号；全部组判
- * 完后逐豁免条目对账（棘轮只许缩短）。
+ * 完后逐豁免条目对账（棘轮只许缩短）。slug 白名单命中集随结果返回，失效对账
+ * 不在本函数内做——全局条目跨 scope 存活，须由调用方聚合后统一判定。
  *
  * @param input - 扫描入参
- * @returns 违例列表
+ * @returns 扫描结果（违例列表 + slug 白名单命中集）
  */
-export function scanScopeForFindings(input: ScopeScanInput): NumberingFinding[] {
+export function scanScopeForFindings(input: ScopeScanInput): ScopeScanResult {
   /**
    * 违例收集器
    */
@@ -503,12 +517,12 @@ export function scanScopeForFindings(input: ScopeScanInput): NumberingFinding[]
     });
   });
 
-  if (input.slugDigitPolicy !== 'allow') {
-    /**
-     * slug 白名单命中集合（全量档失效对账用）
-     */
-    const allowlistHits = new Set<string>();
+  /**
+   * slug 白名单命中 glob 收集器（跨 scope 失效对账聚合口径由调用方承担）
+   */
+  const slugDigitAllowlistHits: string[] = [];
 
+  if (input.slugDigitPolicy !== 'allow') {
     for (const basename of input.basenames) {
       /**
        * slug 段
@@ -529,7 +543,7 @@ export function scanScopeForFindings(input: ScopeScanInput): NumberingFinding[]
        */
       const whitelisted = input.slugDigitAllowlist.some((glob) => {
         if (matchMiniGlob(glob, repoRelative)) {
-          allowlistHits.add(glob);
+          slugDigitAllowlistHits.push(glob);
 
           return true;
         }
@@ -545,20 +559,51 @@ export function scanScopeForFindings(input: ScopeScanInput): NumberingFinding[]
         });
       }
     }
+  }
 
-    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, slugDigitAllowlistHits };
+}
+
+/**
+ * slug 白名单失效对账入参
+ */
+export type SlugDigitAllowlistReconcileInput = {
+  /**
+   * slug 数字白名单 glob 全集（根级全局登记，逐条判定）
+   */
+  allowlist: readonly string[];
+
+  /**
+   * 跨全部 slugDigitPolicy 启用域聚合的命中 glob 集（任一 scope 命中即非失效）
+   */
+  hits: ReadonlySet<string>;
+};
+
+/**
+ * slug 白名单失效对账（跨 scope 聚合口径）
+ *
+ * 白名单是根级全局登记而命中发生在各 scope 扫描面内：条目在其文件所属 scope
+ * 命中即存活，其余 scope 不得重复判定——命中集必须由调用方聚合全部 scope 后
+ * 传入。逐条对账，任何启用域内命中不到含数字 slug 文件即失效（棘轮只许缩短）。
+ *
+ * @param input - 对账入参
+ * @returns 违例列表
+ */
+export function reconcileSlugDigitAllowlist(
+  input: SlugDigitAllowlistReconcileInput,
+): NumberingFinding[] {
+  /**
+   * 违例收集器
+   */
+  const findings: NumberingFinding[] = [];
+
+  for (const glob of input.allowlist) {
+    if (!input.hits.has(glob)) {
+      findings.push({
+        kind: 'slugDigitAllowlistStale',
+        scopeKey: 'global',
+        message: `slug 白名单条目「${glob}」在启用域内已匹配不到任何文件——棘轮只许缩短，须同步删除该条目`,
+      });
     }
   }