BakNRet

59 Commits 1 Branch 0 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
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
Shuery	2d26f78d15	fix: 源文件改存 UTF-8 with BOM，让 Windows PowerShell 5.1 真正可用改造前：全仓 6/6 个源文件在 5.1 上解析失败（README 却承诺支持 5.1）。原因是文件是无 BOM 的 UTF-8，而 5.1 没有 BOM 就按 ANSI 代码页解码源码，中文变乱码、全角问号吃掉引号，整块语法塌掉。现在 28/28 个文件在 5.1 与 7 上都解析零错误，E2E 36 项在 5.1 上全绿。顺带修掉一个被 5.1 掩盖的缺陷：带 [CmdletBinding()] 的脚本在 5.1 上，param() 默认值里拿不到 $PSScriptRoot（实测为空串，7 上正常）。于是 Backup.ps1 / Restore.ps1 在 5.1 上不传路径参数就报错退出 —— 而计划任务恰恰不传。E2E 之所以看不见，是因为它总是显式传路径。 8 处默认值全部移到 param() 之后的解析段，沿用本仓库对 -BackupDir 一直在用的写法。新增三条可重放的约定，让编码不再是一次性动作： .gitattributes 接管行尾（本机 core.autocrlf=true，会把工作区改成 CRLF 制造伪 diff） .editorconfig 用 charset = utf-8-bom 锁住 BOM tools\Set-SourceEncoding.ps1 是规范化脚本，tools\Invoke-* 之外的任何改动之后都能重放 test.ps1 是唯一验收入口：Encode + Parse + Unit + Smoke + E2E，在 7 与 5.1 上各跑一遍 test.ps1 的 Encode 层直接检查"必须有 BOM"这条规则。加它的原因很实际：实测本仓库用的编辑工具在保存时会悄悄去掉 BOM，而丢了 BOM 的文件只在 5.1 上出错、在 7 上完全正常，没有这条检查就会一直漏过去。已知未修（下一步处理）：5.1 上 Unit 有 6 项、Smoke 有 1 项失败，全部源于测试夹具写临时文件时没指定编码（5.1 的 Set-Content 默认 ANSI），与产品代码无关。	2026-09-26 22:05:42 +08:00
Shuery	e114cae8c8	P0-P3 全量重构：退出码 / 解析修复、manifest 与 7z t 校验、干跑、排除规则、日志、测试与计划任务 P0 正确性 - 退出码：改用 .NET Process 直接启动、让子进程继承控制台，不再用 Start-Process -PassThru （在 7.7.0-preview.4 上 ExitCode 恒为 $null，会把成功的压缩判成失败）； 7z / RAR / tar 三条解压分支统一走同一个取退出码的封装。 - BackupList 解析：先按第一个 :: 切段再处理引号（整行被一对引号包住的写法不再把排除表吞进路径）；排除表同时接受 , 与 ;（旧实现只认 ;，导致排除从未生效）；支持 :- / :+ / @flag。 - 补回 .ssh 与孤儿归档：.ssh 进清单；孤儿归档在备份端也做审计并点名；带 -Only / -Skip 时不再把未选中的归档误报成孤儿。 - Resolve-BackupEntry 里 $rootName 在赋值前被引用（会读到外层作用域残留值），已提前赋值。 P1 归档可靠性 - 每个条目写进 manifest.json：源、归档、时间、退出码、校验结果、失败原因，并区分 warnings（在位归档）与 attemptWarnings（本次尝试）。 - 归档后做 7z t 内容校验，先写 .tmp、校验通过再原子替换（File.Move overwrite）。 - manifest.roots 记录归档内真实的顶层条目名（原先记的是软件名，Edge 实际是 "User Data"）。 P2 可用性 - Restore 支持 -WhatIf / -DryRun / -VerifyOnly / -Only / -Skip；这三种"只看不写"的模式一个字节都不写（原先会写回 manifest.json）。 - Edge 等高缓存条目加排除规则并实测：1781 MB / 27961 项 -> 72 MB / 2294 项；书签、密码、Cookies、偏好、历史、IndexedDB、Local Storage 全部保留。普通模式是相对归档根目录锚定的，嵌套的那些（如 OneAuth\WebView2 里的 Crashpad）改用 ! 组件形式才会命中。 - 日志落盘 logs/<backup\|restore>-<时间戳>.log；退出码按失败数返回。 - tools/Register-BackupTask.ps1 注册每日计划任务；tools/Rename-Archives.ps1 迁移旧归档名。 - root= 标记此前静默失效，现在明确告警（该功能尚未实现）。 P3 测试与验证 - tests/BakNRet.Tests.ps1：Pester 5 套件 62 项（含用子进程跑 Backup.ps1 / Restore.ps1 的端到端与针对上述缺陷的回归）。 - tests/Run-Pester.ps1 + tools/Install-TestDependencies.ps1：把 Pester 装到仓库内 .tools/，不动机器上的全局模块（系统自带的 3.4.0 缺 Should -Be）。 - tests/Restore-Drill.ps1：真实归档恢复演练，明确区分"源在备份后变过"与"归档/解压有问题"。 - tests/Run-Tests.ps1（49 项，零依赖）与 tests/Run-E2E.ps1（23 项）继续可用；三套共 134 项全通过。真实机器验证 - 生产归档 22/22 通过 7z t；-VerifyOnly 不再改动 manifest.json（SHA256 前后一致）。 - 真实恢复演练 12/12 通过，27,670 个文件与活源逐字节一致。 - 修复了生产 scoop-persist.7z：原先只有 90 字节（空归档）而源有 1.3 GB，重打包后 233 MB，恢复演练 26981/26981 全部一致。	2026-09-21 23:02:47 +08:00

Author

SHA1

Message

Date

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

Shuery

2d26f78d15

fix: 源文件改存 UTF-8 with BOM，让 Windows PowerShell 5.1 真正可用

改造前：全仓 6/6 个源文件在 5.1 上解析失败（README 却承诺支持 5.1）。原因是文件是无 BOM 的
UTF-8，而 5.1 没有 BOM 就按 ANSI 代码页解码源码，中文变乱码、全角问号吃掉引号，整块语法塌掉。
现在 28/28 个文件在 5.1 与 7 上都解析零错误，E2E 36 项在 5.1 上全绿。

顺带修掉一个被 5.1 掩盖的缺陷：带 [CmdletBinding()] 的脚本在 5.1 上，param() 默认值里
拿不到 $PSScriptRoot（实测为空串，7 上正常）。于是 Backup.ps1 / Restore.ps1 在 5.1 上不传
路径参数就报错退出 —— 而计划任务恰恰不传。E2E 之所以看不见，是因为它总是显式传路径。
8 处默认值全部移到 param() 之后的解析段，沿用本仓库对 -BackupDir 一直在用的写法。

新增三条可重放的约定，让编码不再是一次性动作：
  .gitattributes 接管行尾（本机 core.autocrlf=true，会把工作区改成 CRLF 制造伪 diff）
  .editorconfig 用 charset = utf-8-bom 锁住 BOM
  tools\Set-SourceEncoding.ps1 是规范化脚本，tools\Invoke-* 之外的任何改动之后都能重放
  test.ps1 是唯一验收入口：Encode + Parse + Unit + Smoke + E2E，在 7 与 5.1 上各跑一遍

test.ps1 的 Encode 层直接检查"必须有 BOM"这条规则。加它的原因很实际：实测本仓库用的
编辑工具在保存时会悄悄去掉 BOM，而丢了 BOM 的文件只在 5.1 上出错、在 7 上完全正常，
没有这条检查就会一直漏过去。

已知未修（下一步处理）：5.1 上 Unit 有 6 项、Smoke 有 1 项失败，全部源于测试夹具写
临时文件时没指定编码（5.1 的 Set-Content 默认 ANSI），与产品代码无关。

2026-09-26 22:05:42 +08:00

Shuery

e114cae8c8

P0-P3 全量重构：退出码 / 解析修复、manifest 与 7z t 校验、干跑、排除规则、日志、测试与计划任务

P0 正确性
- 退出码：改用 .NET Process 直接启动、让子进程继承控制台，不再用 Start-Process -PassThru
  （在 7.7.0-preview.4 上 ExitCode 恒为 $null，会把成功的压缩判成失败）；
  7z / RAR / tar 三条解压分支统一走同一个取退出码的封装。
- BackupList 解析：先按第一个 :: 切段再处理引号（整行被一对引号包住的写法不再把排除表
  吞进路径）；排除表同时接受 , 与 ;（旧实现只认 ;，导致排除从未生效）；支持 :- / :+ / @flag。
- 补回 .ssh 与孤儿归档：.ssh 进清单；孤儿归档在备份端也做审计并点名；
  带 -Only / -Skip 时不再把未选中的归档误报成孤儿。
- Resolve-BackupEntry 里 $rootName 在赋值前被引用（会读到外层作用域残留值），已提前赋值。

P1 归档可靠性
- 每个条目写进 manifest.json：源、归档、时间、退出码、校验结果、失败原因，
  并区分 warnings（在位归档）与 attemptWarnings（本次尝试）。
- 归档后做 7z t 内容校验，先写 .tmp、校验通过再原子替换（File.Move overwrite）。
- manifest.roots 记录归档内**真实**的顶层条目名（原先记的是软件名，Edge 实际是 "User Data"）。

P2 可用性
- Restore 支持 -WhatIf / -DryRun / -VerifyOnly / -Only / -Skip；
  这三种"只看不写"的模式一个字节都不写（原先会写回 manifest.json）。
- Edge 等高缓存条目加排除规则并实测：1781 MB / 27961 项 -> 72 MB / 2294 项；
  书签、密码、Cookies、偏好、历史、IndexedDB、Local Storage 全部保留。
  普通模式是相对归档根目录锚定的，嵌套的那些（如 OneAuth\WebView2 里的 Crashpad）
  改用 ! 组件形式才会命中。
- 日志落盘 logs/<backup|restore>-<时间戳>.log；退出码按失败数返回。
- tools/Register-BackupTask.ps1 注册每日计划任务；tools/Rename-Archives.ps1 迁移旧归档名。
- root= 标记此前静默失效，现在明确告警（该功能尚未实现）。

P3 测试与验证
- tests/BakNRet.Tests.ps1：Pester 5 套件 62 项（含用子进程跑 Backup.ps1 / Restore.ps1
  的端到端与针对上述缺陷的回归）。
- tests/Run-Pester.ps1 + tools/Install-TestDependencies.ps1：把 Pester 装到仓库内 .tools/，
  不动机器上的全局模块（系统自带的 3.4.0 缺 Should -Be）。
- tests/Restore-Drill.ps1：真实归档恢复演练，明确区分"源在备份后变过"与"归档/解压有问题"。
- tests/Run-Tests.ps1（49 项，零依赖）与 tests/Run-E2E.ps1（23 项）继续可用；三套共 134 项全通过。

真实机器验证
- 生产归档 22/22 通过 7z t；-VerifyOnly 不再改动 manifest.json（SHA256 前后一致）。
- 真实恢复演练 12/12 通过，27,670 个文件与活源逐字节一致。
- 修复了生产 scoop-persist.7z：原先只有 90 字节（空归档）而源有 1.3 GB，
  重打包后 233 MB，恢复演练 26981/26981 全部一致。

2026-09-21 23:02:47 +08:00