local-ci-cd-system/PSScriptAnalyzerSettings.psd1

@{
    # ── Rules to suppress project-wide ──────────────────────────────────────────
    ExcludeRules = @(
        # All CI scripts use Write-Host for structured output captured by act_runner.
        # Write-Output would interleave with function return values and break callers.
        'PSAvoidUsingWriteHost',

        # Formatting-only rules: generate one warning per line across all existing scripts
        # (thousands of hits). Run locally with Invoke-ScriptAnalyzer -Fix to auto-format;
        # do not use as CI gate until the whole codebase has been reformatted.
        'PSUseConsistentIndentation',
        'PSUseConsistentWhitespace',

        # The codebase uses the param() + -ArgumentList pattern for remote script blocks
        # (Invoke-Command, Start-Job) consistently and correctly. PSSA does not recognise
        # param() inside a ScriptBlock as a local declaration, so it fires a false positive
        # on every parameter. $Using: is an alternative but not required here.
        'PSUseUsingScopeModifierInNewRunspaces',

        # UTF-8 without BOM is the editor default; adding BOM to ~35 files is cosmetic
        # and does not affect PS 5.1 execution.
        'PSUseBOMForUnicodeEncodedFile',

        # Plural nouns in internal helpers (Get-GuestDiagnostics, Remove-OldJobDirs, etc.)
        # are intentional — they describe collections, not single objects.
        'PSUseSingularNouns',

        # PSAvoidUsingPlainTextForPassword fires as a false positive on *CredentialTarget params
        # (Windows Credential Manager target strings, not passwords). Real plain-text password
        # usage in template setup scripts is already caught by PSAvoidUsingConvertToSecureStringWithPlainText
        # with targeted SuppressMessage attributes where intentional.
        'PSAvoidUsingPlainTextForPassword',

        # These scripts use [switch]$VerifyArtifact = $true for opt-out patterns.
        # Removing the default would silently change script behaviour.
        'PSAvoidDefaultValueSwitchParameter',

        # Stop-Vm is an intentional internal name in a VMware-only CI environment;
        # Hyper-V is not installed on the CI host so there is no real cmdlet to shadow.
        'PSAvoidOverwritingBuiltInCmdlets',

        # Advisory rule only. Params may be declared for external callers, future use,
        # or accepted-but-ignored forwarding. Not a safety issue.
        'PSReviewUnusedParameter'
    )

    # ── Rule-specific configuration ──────────────────────────────────────────────
    Rules = @{
        # Security: never eval arbitrary strings
        PSAvoidUsingInvokeExpression = @{
            Enable = $true
        }

        # ShouldProcess/WhatIf support is not required for one-shot deployment scripts
        # and internal CI helper functions; adding it to all state-changing functions
        # would be invasive with no operational benefit in this environment.
        PSUseShouldProcessForStateChangingFunctions = @{
            Enable = $false
        }

        # Credentials must flow as [PSCredential], not plain strings
        PSUsePSCredentialType = @{
            Enable = $true
        }

        # Covered by ExcludeRules above (false positives on *CredentialTarget params).
        PSAvoidUsingPlainTextForPassword = @{
            Enable = $false
        }

        # ConvertTo-SecureString -AsPlainText only acceptable during template setup;
        # use Suppress comments there if needed.
        PSAvoidUsingConvertToSecureStringWithPlainText = @{
            Enable = $true
        }

        # No script-scope globals that bleed across module boundaries
        PSAvoidGlobalVars = @{
            Enable = $true
        }

        # Formatting — 4-space indentation, spaces (not tabs)
        PSUseConsistentIndentation = @{
            Enable              = $true
            IndentationSize     = 4
            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
            Kind                = 'space'
        }

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

        # Alignment is a style preference; disable to avoid false positives on
        # the deliberate column-aligned hashtable assignments used in this project.
        PSAlignAssignmentStatement = @{
            Enable = $false
        }
    }
}