Shuery
187d2759fd
三件事：
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 层。这条要改行为、且影响真实名录的解析
结果，留给你拍板，不在本提交里动手。
102 lines
3.8 KiB
PowerShell
102 lines
3.8 KiB
PowerShell
<#
|
||
.SYNOPSIS
|
||
对全仓跑 PSScriptAnalyzer（默认规则集 + 格式规则集），按规则汇总。
|
||
|
||
.DESCRIPTION
|
||
为什么要有这个入口，而不是直接敲 Invoke-ScriptAnalyzer：
|
||
|
||
* 分析器装在**仓库内**（.tools\modules），不能指望机器上全局有一份；
|
||
* 格式规则默认是 Disabled —— 不带 -Settings 的调用会静默漏掉全部排版问题，
|
||
那会让"按微软规范检查过了"变成一句空话；
|
||
* 结果要能一眼看出"哪条规则、几个文件、几行"，而不是几百行原始输出；
|
||
* 路径过滤要与验收门槛一致：.tools\ / Backups\ / logs\ / dist\ 不进分析范围。
|
||
|
||
与测试的分工：这是**独立的门禁**，不塞进 Pester 用例。那个套件跑一次二十多秒，
|
||
把静态分析混进去会让"测试红了"这句话失去分辨力。
|
||
|
||
.PARAMETER Severity
|
||
只报这些级别，默认 Error 与 Warning。
|
||
|
||
.PARAMETER Quiet
|
||
只打印按规则汇总的计数，不逐条列出。
|
||
|
||
.EXAMPLE
|
||
.\tools\Invoke-Analyzer.ps1
|
||
|
||
.EXAMPLE
|
||
.\tools\Invoke-Analyzer.ps1 -Quiet
|
||
#>
|
||
[CmdletBinding()]
|
||
param(
|
||
[string[]]$Severity = @('Error', 'Warning'),
|
||
|
||
[switch]$Quiet
|
||
)
|
||
|
||
$ErrorActionPreference = 'Stop'
|
||
|
||
$projectRoot = Split-Path -Parent $PSScriptRoot
|
||
$localModules = Join-Path $projectRoot '.tools\modules'
|
||
if (Test-Path -LiteralPath (Join-Path $localModules 'PSScriptAnalyzer')) {
|
||
$env:PSModulePath = $localModules + [System.IO.Path]::PathSeparator + $env:PSModulePath
|
||
}
|
||
|
||
$analyzer = Get-Module -ListAvailable PSScriptAnalyzer |
|
||
Sort-Object { [version]$_.Version } -Descending |
|
||
Select-Object -First 1
|
||
|
||
if (-not $analyzer) {
|
||
Write-Host ''
|
||
Write-Host '找不到 PSScriptAnalyzer。把它装进仓库（不动机器上的全局模块）：' -ForegroundColor Red
|
||
Write-Host ' .\tools\Install-TestDependencies.ps1' -ForegroundColor Cyan
|
||
Write-Host ''
|
||
exit 2
|
||
}
|
||
|
||
Import-Module $analyzer.Path -Force
|
||
|
||
# 分析范围与验收门槛的 Encode / Parse 两层保持一致：只分析仓库自己的源码
|
||
$excluded = '\\(\.git|\.tools|\.scratch|Backups|logs|dist|snapshots)\\'
|
||
$targets = @(Get-ChildItem -LiteralPath $projectRoot -Recurse -File |
|
||
Where-Object { $_.Extension -in '.ps1', '.psm1', '.psd1' } |
|
||
Where-Object { $_.FullName -notmatch $excluded } |
|
||
Select-Object -ExpandProperty FullName)
|
||
|
||
$settings = Join-Path $projectRoot 'PSScriptAnalyzerSettings.psd1'
|
||
|
||
Write-Host ''
|
||
Write-Host ("PSScriptAnalyzer {0}（{1}）" -f $analyzer.Version, $analyzer.ModuleBase) -ForegroundColor DarkGray
|
||
Write-Host ("分析 {0} 个文件，配置 {1}" -f $targets.Count, $settings) -ForegroundColor DarkGray
|
||
Write-Host ''
|
||
|
||
# 逐个文件调用：-Path 在这个版本上只接受单个路径（传数组会报 Cannot convert
|
||
# 'System.Object[]' to the type 'System.String'），而我们要的正是「只分析仓库自己的
|
||
# 源码」这个范围 —— 自己枚举文件反而更准。
|
||
$results = @(foreach ($file in $targets) {
|
||
Invoke-ScriptAnalyzer -Path $file -Settings $settings -Severity $Severity
|
||
})
|
||
|
||
if ($results.Count -eq 0) {
|
||
Write-Host ("没有 {0} 级别的告警。" -f ($Severity -join '/')) -ForegroundColor Green
|
||
Write-Host ''
|
||
exit 0
|
||
}
|
||
|
||
$byRule = $results | Group-Object RuleName | Sort-Object Count -Descending
|
||
Write-Host ("共 {0} 条，按规则汇总：" -f $results.Count) -ForegroundColor Yellow
|
||
foreach ($group in $byRule) {
|
||
Write-Host (" {0,4} {1}" -f $group.Count, $group.Name)
|
||
}
|
||
|
||
if (-not $Quiet) {
|
||
Write-Host ''
|
||
Write-Host '逐条：' -ForegroundColor Yellow
|
||
foreach ($item in ($results | Sort-Object ScriptName, Line)) {
|
||
$relative = $item.ScriptName.Replace($projectRoot, '').TrimStart('\')
|
||
Write-Host (" {0}:{1} [{2}] {3}" -f $relative, $item.Line, $item.RuleName, $item.Message)
|
||
}
|
||
}
|
||
|
||
Write-Host ''
|
||
exit 1
|