PSScriptAnalyzerSettings.psd1
|
# PSScriptAnalyzer configuration # Usage: Invoke-ScriptAnalyzer -Path .\Modules\LazyCompletions -Recurse -Settings .\Modules\LazyCompletions\PSScriptAnalyzerSettings.psd1 # # Principle: suppress only DESIGN/ARCHITECTURE rules (deliberate performance / cross-reload / # engine-semantics design of the module); real issues (automatic-variable shadowing etc.) are # fixed in the code itself, not listed here. @{ # Excluded rules and the reasons (all are deliberate architectural choices, not oversights): ExcludeRules = @( # global variables (LC_* prefix): the TabExpansion2 wrapper must live in global scope — # module reload (Import-Module -Force) does not clear globals, so the wrapper survives # reloads instead of referencing an unloaded module instance (measured bug). Namespaced, # does not collide with other modules. 'PSAvoidGlobalVars', # global function (the TabExpansion2 wrapper): same reason as global vars — it must be # global to override the engine's default TabExpansion2 and survive reloads. 'PSAvoidGlobalFunctions', # empty catch blocks: silent degradation is core design — completion/load/cleanup # failures must never interrupt Tab or the shell (failure semantics documented above each # catch; swallowing exceptions is a feature, not a bug). 'PSAvoidUsingEmptyCatchBlock', # ShouldProcess: module functions are "config/internal tooling" rather than high-risk # system-changing cmdlets; adding ShouldProcess would pollute parameter sets and call # semantics (Import-LazyCompletion is called without parameters). 'PSUseShouldProcessForStateChangingFunctions', # Invoke-Expression: only used in Add-LazyCompletion -Generator's string mode (a command # the user explicitly passed); output is syntax-checked before writing and the error # stream is separated — not an arbitrary-input injection surface. 'PSAvoidUsingInvokeExpression', # verbs/nouns (Get/Set/Add/Clear/Update/Import/Install/Invoke): function names are the # module's long-term stable API; changing verbs would break user configs and scripts. 'PSUseApprovedVerbs', 'PSUseSingularNouns', # positional parameters: internal helpers and test helpers deliberately use positional # parameters (hot-path performance / test readability); all public APIs use named parameters. 'PSAvoidUsingPositionalParameters', # shadowing a built-in cmdlet (Register-ArgumentCompleter): the same-named function # defined inside Invoke-LazyCompleter is the CORE interception mechanism (scope-isolated, # captures real-script registrations); it must share the built-in name to work. 'PSAvoidOverwritingBuiltInCmdlets', # test code (Tests/**): test function verbs (Reset/Import helpers) / global test # commands / Write-Host (manual verification script) are deliberate test style, not runtime code. 'PSUseApprovedVerbs', 'PSAvoidGlobalVars', 'PSUseSingularNouns', 'PSUseShouldProcessForStateChangingFunctions', 'PSReviewUnusedParameter', 'PSUseDeclaredVarsMoreThanAssignments', 'PSAvoidUsingWriteHost', # output type annotations (Information level): module functions output polymorphic values # (AutomationNull/arrays/counts/status strings); [OutputType] annotations would mislead # callers; no-output semantics are handled at call sites. 'PSUseOutputTypeCorrectly' ) } |