<#
    PSScriptAnalyzer 的配置。

    为什么这个文件是必要的，而不是"跑一下默认规则就算按规范了"：

      默认规则集**不含**格式规则 —— PSPlaceOpenBrace / PSPlaceCloseBrace /
      PSUseConsistentWhitespace / PSUseConsistentIndentation / PSAlignAssignmentStatement /
      PSUseCorrectCasing 这六条默认都是 Disabled。所以
      `Invoke-ScriptAnalyzer -Severity Warning,Error`（不带 -Settings）
      会**静默漏掉全部排版问题**。

    这里用 `Rules` 把格式规则**打开**，而不是用 `IncludeRules` 换一套：不带 IncludeRules 时
    默认规则集照常生效，Rules 只是逐条改设置，于是"默认规则 + 格式规则"同时跑。

    逐条决策（都在本次改造里确认过，理由另见 docs/adr/）：

      * PSAvoidUsingWriteHost 全局排除 —— Write-BakNRetLog 的彩色控制台输出是这份工具的**刻意设计**，
        不是疏忽。这是架构性选择，所以在配置里排除掉，而不是逐处 Suppress 假装它是例外。
      * PSUseSingularNouns 放行 SecurityRecords / MapKeys / ArchiveTopLevelNames ——
        单数名 Get-BakNretSecurityRecord 已被"单对象版本"占用，为了规则把两个语义搅在一起
        不值得。Data / Windows 是规则自带的默认放行项，显式写上以免被本条覆盖掉。
      * PSAvoidLongLines 上限 160，而**不是**官方默认的 120：本仓库的中文注释与测试夹具
        里的一行式目录让 120 意味着 270 处改动，而 160 意味着 41 处（并且 160 仍是
        「宽但可读」）。这是一次有意的偏离，理由记在这里而不是悄悄放宽：如果哪天要收
        紧到 120，先看 tools\Invoke-Analyzer.ps1 的输出里还有多少条。

      * PSUseShouldProcessForStateChangingFunctions 全局排除 —— 本模块是库，不是入口：
        WhatIf 的边界在 Backup.ps1 / Restore.ps1（它们自己管 -DryRun / -WhatIf）。
        给库里 27 个改状态的函数都加 SupportsShouldProcess 会更糟：入口把 $WhatIfPreference
        置真之后，这些函数会**静默跳过自己的工作**，备份看起来成功却什么都没做。

      * PSAvoidUsingPlainTextForPassword 全局排除 —— 7z 只接受命令行口令（这是 7z 自身
        的限制，README 的「加密」一节写明了取舍）。口令在这个工具里必然是明文字符串，
        规则说的"用 SecureString"在这里没有可用的落点。
        真正要守的两条已经另有措施：口令不进日志（遮蔽 + 断言）、口令不进版本库
        （.gitignore + 出厂默认值留空）。
      * PSUseConsistentIndentation 用 space + 4，与 .editorconfig 一致。
#>
@{
    Severity     = @('Error', 'Warning')

    ExcludeRules = @(
        'PSAvoidUsingWriteHost',
        'PSUseShouldProcessForStateChangingFunctions',
        'PSAvoidUsingPlainTextForPassword'
    )

    Rules        = @{

        # ---------------------------------------------------------------- 格式规则
        PSPlaceOpenBrace           = @{
            Enable             = $true
            OnSameLine         = $true
            NewLineAfter       = $true
            IgnoreOneLineBlock = $true
        }

        PSPlaceCloseBrace          = @{
            Enable             = $true
            NewLineAfter       = $true
            IgnoreOneLineBlock = $true
            NoEmptyLineBefore  = $false
        }

        PSUseConsistentIndentation = @{
            Enable              = $true
            Kind                = 'space'
            IndentationSize     = 4
            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
        }

        PSUseConsistentWhitespace  = @{
            Enable                                  = $true
            CheckInnerBrace                         = $true
            CheckOpenBrace                          = $true
            CheckOpenParen                          = $true
            CheckOperator                           = $true
            CheckPipe                               = $true
            CheckPipeForRedundantWhitespace         = $false
            CheckSeparator                          = $true
            CheckParameter                          = $false
            IgnoreAssignmentOperatorInsideHashTable = $true
        }

        PSAlignAssignmentStatement = @{
            Enable         = $true
            CheckHashtable = $true
        }

        PSUseCorrectCasing         = @{
            Enable = $true
        }

        # ---------------------------------------------------------------- 行长
        PSAvoidLongLines           = @{
            Enable            = $true
            MaximumLineLength = 160
        }

        # ---------------------------------------------------------------- 名词白名单
        PSUseSingularNouns         = @{
            Enable        = $true
            NounAllowList = @('Data', 'Windows', 'SecurityRecords', 'MapKeys', 'ArchiveTopLevelNames')
        }
    }
}