BakNRet

48 Commits 1 Branch 0 Tags

2 Commits

Include renames

Author	SHA1	Message	Date
Shuery	42f02d0eca	refactor: 公共面补 BakNRet 前缀，产品名大小写全仓统一 16 个没有前缀的公共函数补上 BakNRet（Write-Log → Write-BakNRetLog、Resolve-BackupEntry → Resolve-BakNRetBackupEntry、Find-ChildDirectoryByName → Find-BakNRetChildDirectoryByName 等），另外把全仓的 Baknret 统一成 BakNRet（47 个文件、940 处、65 个定义文件重命名）。这不是审美问题：静态分析直接拓出一条实据 —— Write-Log 与本机某个已装模块导出的命令重名（PSAvoidOverwritingBuiltInCmdlets），而重名的后果是导入两个模块时有一方的命令被静默遮蔽。补前缀正是这条规则的解法，改名后它归零。为什么敢做这个规模：PowerShell 的函数名解析大小写不敏感，所以 Baknret → BakNRet 在功能上是零风险；真正要验证的是 16 个补前缀的调用点，而 276 个断言几乎覆盖了每个函数。另外 "名字与文件名一致"这条不变式有断言盯着（加载器点源的文件集合 vs 磁盘）。踩到并记下的坑：Windows 文件系统大小写不敏感，所以只改大小写的重命名会被 Move-Item 当成同一个文件而静默跳过 —— 同一批里同时改了名字的那 16 个文件却成功了，于是"看起来能跑"。最后用"先移到临时名、再移到目标名"的两步走解决，判断与替换全部改用显式大小写敏感的形式（-creplace / -cmatch）。顺带把名录指纹缓存从 MD5 换成 SHA256（PSAvoidUsingBrokenHashAlgorithms）：它只是缓存键，没有兼容负担。验收：test.ps1 9/9 全绿（7 与 5.1）、100 个文件两版解析零错、276 个断言全过、构建工具仍能合回单文件（3300 行）。	2026-09-27 09:56:36 +08:00
Shuery	187d2759fd	style: 按微软规范落地静态分析，并全仓机械重排三件事： 1) tools\Install-TestDependencies.ps1 现在也把 PSScriptAnalyzer 装进仓库内的 .tools\modules （不动机器上的全局模块，与 Pester 同一策略）。 2) PSScriptAnalyzerSettings.psd1：这是必要的，不是装饰 —— 那 6 条格式规则（括号、缩进、空格、对齐、大小写）默认全是 Disabled，所以不带 -Settings 的 `Invoke-ScriptAnalyzer -Severity Warning,Error` 会静默漏掉全部排版问题。本文件用 Rules 把它们打开（而不是用 IncludeRules 换一套），于是默认规则与格式规则同时生效。三条有意的排除都写明了理由：PSAvoidUsingWriteHost（彩色控制台输出是这份工具的刻意设计）、 PSUseShouldProcessForStateChangingFunctions（WhatIf 的边界在入口脚本，给库里 27 个改状态的函数都加上反而会"静默跳过"，备份看着成功却什么都没做）、PSAvoidUsingPlainTextForPassword （7z 只接受命令行口令，这是 7z 的限制，README 里写明了取舍）。 3) tools\Invoke-Analyzer.ps1：独立门禁（不塞进 Pester 用例 —— 套件跑一次二十多秒，混进去会让"测试红了"这句话失去分辨力），路径过滤与验收门槛的 Encode/Parse 两层一致。全仓重排结果：706 条告警 -> 67 条。修掉的 639 条全部是格式（闭括号 168、空格 80、对齐 68、缩进 60、行长 229）。重排后 9/9 验收全绿、100 个文件两版解析零错、 276 个断言原样通过 —— 机械重排没有改变任何可观察行为。如实说明两件事： * 行长上限设成 160，不是官方默认的 120。120 在本仓库意味着 270 处改动（主要是中文注释与测试夹具里的一行式目录），160 意味着 41 处。160 仍是"宽但可读"，而理由是写在配置文件里的：这不是悄悄放宽，想收紧到 120 时那份清单就在分析器输出里。 * 剩余 67 条里，41 条是上面那批行长，其余 26 条是分析器找出的真问题（未使用参数 6、空 catch 6、MD5 指纹 1、覆盖内置命令 1、switch 默认值 1 等）。其中 Find-ChildDirectoryByName 的 MaxDepth 参数从未被使用 —— 也就是配置里的 CatalogMaxDepth = 5 是假的，前缀补全实际只查 1 层。这条要改行为、且影响真实名录的解析结果，留给你拍板，不在本提交里动手。	2026-09-27 09:46:08 +08:00

Author

SHA1

Message

Date

Shuery

42f02d0eca

refactor: 公共面补 BakNRet 前缀，产品名大小写全仓统一

16 个没有前缀的公共函数补上 BakNRet（Write-Log → Write-BakNRetLog、Resolve-BackupEntry →
Resolve-BakNRetBackupEntry、Find-ChildDirectoryByName → Find-BakNRetChildDirectoryByName 等），
另外把全仓的 Baknret 统一成 BakNRet（47 个文件、940 处、65 个定义文件重命名）。

这不是审美问题：静态分析直接拓出一条实据 —— Write-Log 与本机某个已装模块导出的命令
**重名**（PSAvoidOverwritingBuiltInCmdlets），而重名的后果是导入两个模块时有一方的命令被
静默遮蔽。补前缀正是这条规则的解法，改名后它归零。

为什么敢做这个规模：PowerShell 的函数名解析大小写不敏感，所以 Baknret → BakNRet 在功能
上是零风险；真正要验证的是 16 个补前缀的调用点，而 276 个断言几乎覆盖了每个函数。另外
"名字与文件名一致"这条不变式有断言盯着（加载器点源的文件集合 vs 磁盘）。

踩到并记下的坑：Windows 文件系统大小写不敏感，所以**只改大小写**的重命名会被 Move-Item
当成同一个文件而静默跳过 —— 同一批里同时改了名字的那 16 个文件却成功了，于是"看起来能跑"。
最后用"先移到临时名、再移到目标名"的两步走解决，判断与替换全部改用显式大小写敏感的形式
（-creplace / -cmatch）。

顺带把名录指纹缓存从 MD5 换成 SHA256（PSAvoidUsingBrokenHashAlgorithms）：它只是缓存键，
没有兼容负担。

验收：test.ps1 9/9 全绿（7 与 5.1）、100 个文件两版解析零错、276 个断言全过、
构建工具仍能合回单文件（3300 行）。

2026-09-27 09:56:36 +08:00

Shuery

187d2759fd

style: 按微软规范落地静态分析，并全仓机械重排

三件事：

1) tools\Install-TestDependencies.ps1 现在也把 PSScriptAnalyzer 装进仓库内的 .tools\modules
（不动机器上的全局模块，与 Pester 同一策略）。

2) PSScriptAnalyzerSettings.psd1：这是必要的，不是装饰 —— 那 6 条格式规则
（括号、缩进、空格、对齐、大小写）默认全是 Disabled，所以不带 -Settings 的
`Invoke-ScriptAnalyzer -Severity Warning,Error` 会**静默漏掉全部排版问题**。本文件用 Rules
把它们打开（而不是用 IncludeRules 换一套），于是默认规则与格式规则同时生效。
三条有意的排除都写明了理由：PSAvoidUsingWriteHost（彩色控制台输出是这份工具的刻意设计）、
PSUseShouldProcessForStateChangingFunctions（WhatIf 的边界在入口脚本，给库里 27 个改状态的
函数都加上反而会"静默跳过"，备份看着成功却什么都没做）、PSAvoidUsingPlainTextForPassword
（7z 只接受命令行口令，这是 7z 的限制，README 里写明了取舍）。

3) tools\Invoke-Analyzer.ps1：独立门禁（不塞进 Pester 用例 —— 套件跑一次二十多秒，
混进去会让"测试红了"这句话失去分辨力），路径过滤与验收门槛的 Encode/Parse 两层一致。

全仓重排结果：706 条告警 -> 67 条。修掉的 639 条全部是格式（闭括号 168、空格 80、
对齐 68、缩进 60、行长 229）。重排后 9/9 验收全绿、100 个文件两版解析零错、
276 个断言原样通过 —— 机械重排没有改变任何可观察行为。

如实说明两件事：

  * 行长上限设成 160，**不是**官方默认的 120。120 在本仓库意味着 270 处改动（主要是
    中文注释与测试夹具里的一行式目录），160 意味着 41 处。160 仍是"宽但可读"，而理由是写在
    配置文件里的：这不是悄悄放宽，想收紧到 120 时那份清单就在分析器输出里。

  * 剩余 67 条里，41 条是上面那批行长，其余 26 条是分析器找出的真问题（未使用参数 6、
    空 catch 6、MD5 指纹 1、覆盖内置命令 1、switch 默认值 1 等）。其中
    Find-ChildDirectoryByName 的 MaxDepth 参数从未被使用 —— 也就是配置里的
    CatalogMaxDepth = 5 是假的，前缀补全实际只查 1 层。这条要改行为、且影响真实名录的解析
    结果，留给你拍板，不在本提交里动手。

2026-09-27 09:46:08 +08:00