refactor: Common.psm1 拆成 BakNRet/{Public,Private}，一函数一文件 + 薄加载器

3152 行、66 个函数的单文件模块拆成： BakNRet\BakNRet.psd1 模块清单：FunctionsToExport 是显式白名单（62 个名字） BakNRet\BakNRet.psm1 加载器：点源顺序的唯一一处声明 BakNRet\Public\*.ps1 62 个对外函数，一函数一文件，文件名 = 函数名 BakNRet\Private\*.ps1 4 个内部函数 + State.ps1（模块级状态集中一处）为什么是一函数一文件：这是社区里脚本模块的主流形态（调研实测：winutil 79 个、 Terminal-Icons 24 个、ModuleBuilder 23 个，全部如此）。收益是改动落在小文件里、diff 按职责可读、模块级状态有唯一去处。为什么这不算"打散"：模块内 dot-source 的文件共享同一个模块作用域（实测确认），所以 "按顺序点源 67 个文件"与"点源一个大文件"在语义上等价；顺序只在加载器里出现一次， tools\Build-BakNRetModule.ps1 从那里读出顺序就能拼回单文件 —— 本次产物 dist\BakNRet.psm1 3240 行、两个版本都解析零错。新增一条断言把这条承诺钉住：加载器点源的文件集合必须与磁盘一致、导出名单必须与 Public\ 一一对应。漏一个文件或漏一个名字就是静默少一个函数 —— 而那种错在运行时只表现为 "找不到命令"。引用更新：11 个文件里的 Common.psm1 改成 BakNRet\BakNRet.psd1（走清单导入， FunctionsToExport 才真的说了算）；Common.psm1 直接删除，不留转发垫片。验收：test.ps1 9/9 全绿（7 与 5.1），98 个文件两版解析零错，276 个断言原样通过 —— 这次搬家没有改变任何可观察行为。
2026-09-27 09:34:10 +08:00
1 parent 78f43c8cc9
commit 2ad7987ffe
@@ -0,0 +1,73 @@
+function Get-BaknretRegexExclude {
+    <#
+    .SYNOPSIS
+        把一条 `!re:<正则>` 展开成若干 `-x!<归档内路径>` 参数。
+
+    .DESCRIPTION
+        7z 本身只认通配符，不认正则，所以正则只能由脚本自己遍历源目录后翻译成
+        一条条精确的 `-x!<完整归档内路径>`：
+          * 逐层遍历，命中"目录名或相对路径"就把该目录整个排除，并且**不再往下走**
+            （否则一个命中会产生成千上万条参数）；
+          * 展开结果有上限（MaxMatches），超过就明确报错，而不是悄悄漏排除或写出超长命令行。
+
+        注意：`!<通配>`（例如 `!*Cache`）不走这里——它在 .NET 里是非法正则
+        （`*` 前没有可重复的表达式），仍然按"任意层级匹配组件名"翻译成 `-xr!`。
+    #>
+    param(
+        [Parameter(Mandatory = $true)]$Item,
+        [Parameter(Mandatory = $true)][string]$Pattern,
+        [int]$MaxMatches = 300
+    )
+
+    $arguments = @()
+    $errorText = $null
+
+    try {
+        $regex = [System.Text.RegularExpressions.Regex]::new(
+            $Pattern, [System.Text.RegularExpressions.RegexOptions]::IgnoreCase)
+    } catch {
+        return [pscustomobject]@{ Arguments = @(); Matches = 0; Error = "排除正则非法：$Pattern —— $($_.Exception.Message)" }
+    }
+
+    $real = [string]$Item.RealPath
+    if (-not $real -or -not (Test-Path -LiteralPath $real)) {
+        return [pscustomobject]@{ Arguments = @(); Matches = 0; Error = $null }
+    }
+
+    $root = Get-Item -LiteralPath $real -Force -ErrorAction SilentlyContinue
+    if (-not $root) { return [pscustomobject]@{ Arguments = @(); Matches = 0; Error = $null } }
+
+    if (-not $root.PSIsContainer) {
+        if ($regex.IsMatch($root.Name)) { $arguments += "-x!$($Item.ArchivePath)" }
+        return [pscustomobject]@{ Arguments = @($arguments); Matches = $arguments.Count; Error = $null }
+    }
+
+    # 用显式栈做深度优先遍历：命中就整棵剪掉，所以匹配数是"命中的最浅层数"。
+    $stack = New-Object System.Collections.Generic.Stack[object]
+    foreach ($child in @(Get-ChildItem -LiteralPath $root.FullName -Force -ErrorAction SilentlyContinue)) {
+        $stack.Push(@{ Relative = $child.Name; Item = $child })
+    }
+
+    while ($stack.Count -gt 0) {
+        $node = $stack.Pop()
+        $relative = [string]$node.Relative
+        $entry = $node.Item
+
+        if ($regex.IsMatch($entry.Name) -or $regex.IsMatch($relative)) {
+            $arguments += ('-x!{0}\{1}' -f $Item.ArchivePath, ($relative -replace '/', '\'))
+            if ($arguments.Count -gt $MaxMatches) {
+                $errorText = "排除正则 $Pattern 命中的路径超过 $MaxMatches 条，7z 命令行会过长；请改用更粗的通配模式（例如 !*Cache）"
+                break
+            }
+            continue
+        }
+
+        if ($entry.PSIsContainer) {
+            foreach ($child in @(Get-ChildItem -LiteralPath $entry.FullName -Force -ErrorAction SilentlyContinue)) {
+                $stack.Push(@{ Relative = ('{0}\{1}' -f $relative, $child.Name); Item = $child })
+            }
+        }
+    }
+
+    return [pscustomobject]@{ Arguments = @($arguments); Matches = $arguments.Count; Error = $errorText }
+}