build: add PSScriptAnalyzer clean-pass to build

PSKoans/Init/AddPesterAssertionOperator.ps1

@@ -1,5 +1,12 @@
-try {
-    Add-AssertionOperator -Name Fail -Test {
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'ActualValue',
+    Justification = 'Pester always passes the tested value as the first positional argument to a -Test scriptblock; this assertion ignores it because it always fails.'
+)]
+param()
+
+if ('Fail' -notin (Get-ShouldOperator).Name) {
+    Add-ShouldOperator -Name Fail -Test {
         param ($ActualValue, [switch] $Negate, [string] $Because)
 
         if ($Negate) {
@@ -23,4 +30,3 @@ try {
         }
     }
 }
-catch { }

PSKoans/Init/RegisterArgumentCompleters.ps1

@@ -1,3 +1,30 @@
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'Command',
+    Justification = 'Required positional slot in the host-supplied Register-ArgumentCompleter callback signature; this completer does not use its value.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'Parameter',
+    Justification = 'Required positional slot in the host-supplied Register-ArgumentCompleter callback signature; this completer does not use its value.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'CommandAst',
+    Justification = 'Required positional slot in the host-supplied Register-ArgumentCompleter callback signature; this completer does not use its value.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'FakeBoundParams',
+    Justification = 'Required positional slot in the host-supplied Register-ArgumentCompleter callback signature; this completer does not use its value.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'WordToComplete',
+    Justification = 'used only inside a nested .Where{} scriptblock, which PSScriptAnalyzer does not trace back to the enclosing param'
+)]
+param()
+
 $CommandName = @(
     'Get-Karma'
     'Get-PSKoan'

PSKoans/Koans/Cmdlets 1/AboutGroupObject.Koans.ps1

@@ -11,7 +11,7 @@ param()
 #>
 Describe 'Group-Object' {
     BeforeAll {
-        $Files = Get-ChildItem -Path $home -Recurse -Depth 2 -File
+        $script:Files = Get-ChildItem -Path $home -Recurse -Depth 2 -File
     }
 
     It 'groups items based on specified properties' {

PSKoans/Koans/Cmdlets 1/AboutMeasureObject.Koans.ps1

@@ -9,15 +9,15 @@
 #>
 Describe 'Measure-Object' {
     BeforeAll {
-        $Numbers = @(
+        $script:Numbers = @(
             839, 339, 763, 663, 238, 427, 577, 613, 284, 453
             850, 130, 250, 843, 669, 972, 572, 41, 172, 155
             729, 616, 285, 231, 128, 540, 204, 584, 407, 98
             668, 85, 320, 435, 87, 719, 936, 25, 75, 122
             665, 154, 943, 35, 391, 816, 420, 229, 3, 938
         )
 
-        $Files = Get-ChildItem -Path $HOME -Recurse -Depth 2
+        $script:Files = Get-ChildItem -Path $HOME -Recurse -Depth 2
     }
 
     It 'can count objects' {
@@ -91,7 +91,7 @@
             The other said, "The wind moves."
             They argued back and forth but could not agree.
 
             Hui-neng, the sixth patriarch, said:
             "Gentlemen! It is not the flag that moves. It is not the wind that moves. It is your mind that moves."
 
             The two monks were struck with awe.

PSKoans/Koans/Cmdlets 1/AboutModules.Koans.ps1

@@ -1,4 +1,9 @@
 using module PSKoans
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSProvideCommentHelp',
+    '',
+    Justification = 'Test-ModuleFunction is throwaway scaffolding dynamically written to a demo module file for this exercise; formal help is not warranted.'
+)]
 [Koan(Position = 212)]
 param()
 <#
@@ -90,7 +95,7 @@ Describe 'Find-Module' {
                 }, Description
         }
 
-        $Module = Find-Module -Name 'Pester' | Select-Object -First 1
+        $script:Module = Find-Module -Name 'Pester' | Select-Object -First 1
     }
 
     It 'finds modules that can be installed' {
@@ -119,7 +124,7 @@ Describe 'New-Module' {
         a module in-memory without needing a file on disk.
     #>
     BeforeAll {
-        $Module = New-Module -Name 'PSKoans_TestModule' -ScriptBlock {}
+        $script:Module = New-Module -Name 'PSKoans_TestModule' -ScriptBlock {}
     }
 
     It 'creates a dynamic module object' {
@@ -154,7 +159,7 @@ Describe 'Import-Module' {
     #>
     Context 'Importing Installed Modules' {
         BeforeAll {
-            $Module = New-Module -Name 'PSKoans_ImportModuleTest' { }
+            $script:Module = New-Module -Name 'PSKoans_ImportModuleTest' { }
         }
 
         It 'does not produce output' {

PSKoans/Koans/Cmdlets 1/AboutNewObject.Koans.ps1

@@ -1,4 +1,9 @@
 using module PSKoans
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseLiteralInitializerForHashtable',
+    '',
+    Justification = 'Creating a Hashtable via New-Object (vs. the @{} literal) is the exact thing this koan demonstrates.'
+)]
 [Koan(Position = 203)]
 param()
 <#

PSKoans/Koans/Cmdlets 1/AboutPSProviders.Koans.ps1

@@ -1,4 +1,9 @@
 using module PSKoans
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseDeclaredVarsMoreThanAssignments',
+    'File',
+    Justification = 'Setup value for the blank the learner fills in below with $File; unused until solved.'
+)]
 [Koan(Position = 202)]
 param()
 <#
@@ -32,7 +37,7 @@
     #>
     Context 'Direct Access' {
         BeforeAll {
-            $Aliases = Get-ChildItem -Path 'Alias:'
+            $script:Aliases = Get-ChildItem -Path 'Alias:'
         }
 
         It 'can be queried with generic provider cmdlets' {
@@ -141,7 +146,7 @@
         $Path = 'TEMP:' | Join-Path -ChildPath 'File001.tmp'
 
         $FileContent = @'
 PSKOANS!
 The Env: drive contains system environment data. Its contents can vary wildly from OS to OS,
 especially between Windows, Mac, and Linux, for example.
 '@
@@ -169,7 +174,7 @@
         $NewFile.Length | Should -Be $File.Length
         '____' | Should -Be $NewFile.Name
 
         $NewFile = Rename-Item -Path $NewPath -NewName 'TESTNAME.tmp' -PassThru
         '____' | Should -Be $NewFile.Name
         '____' | Should -Be $NewFile.Length
 
@@ -181,7 +186,7 @@
 
 Describe 'Function Provider' {
     BeforeAll {
-        $Functions = Get-ChildItem -Path 'Function:'
+        $script:Functions = Get-ChildItem -Path 'Function:'
     }
 
     It 'allows access to all currently loaded functions' {

PSKoans/Koans/Cmdlets 1/AboutSortObject.Koans.ps1

@@ -15,8 +15,8 @@ param()
 #>
 Describe 'Sort-Object' {
     BeforeAll {
-        $Numbers = 5, 2, 7, 1, 4, 6, 8, 3, 10, 9
-        $Strings = 'hello', 'goodbye', 'who', 'Steve', 'PowerShell'
+        $script:Numbers = 5, 2, 7, 1, 4, 6, 8, 3, 10, 9
+        $script:Strings = 'hello', 'goodbye', 'who', 'Steve', 'PowerShell'
     }
 
     It 'sorts a collection of objects' {

PSKoans/Koans/Cmdlets 2/AboutCsvCmdlets.Koans.ps1

@@ -34,7 +34,7 @@
             to match.
         #>
         BeforeAll {
-            $Objects = foreach ($number in 1..5) {
+            $script:Objects = foreach ($number in 1..5) {
                 [PSCustomObject]@{
                     Number = $number
                     Square = $number * $number
@@ -105,14 +105,14 @@
             All data will be imported as an array of PSCustomObjects with string properties.
         #>
         BeforeAll {
-            $Objects = foreach ($number in 1..5) {
+            $script:Objects = foreach ($number in 1..5) {
                 [bigint]$number
             }
 
             $CsvPath = "$TestDrive/Data.csv"
 
             $Objects | Export-Csv -Path $CsvPath -NoTypeInformation
-            $ImportedData = Import-Csv -Path $CsvPath
+            $script:ImportedData = Import-Csv -Path $CsvPath
         }
 
         It 'imports the stored data as PSCustomObjects' {
@@ -183,10 +183,10 @@
             '____' | Should -Be $HeaderLess.Parrot
 
             # Maybe we should specify headers to make some sense of things.
             $ActualData = Import-Csv -Path $FilePath -Header Species, Age, Name, Colour
             '____' | Should -Be $ActualData[0].Name
             '__' | Should -Be $ActualData[1].Age
             @('____', '____') | Should -Be $ActualData.Colour
         }
     }
 
@@ -196,7 +196,7 @@
             it will output the lines of the CSV as strings instead of storing the data to a file.
         #>
         BeforeAll {
-            $Objects = foreach ($number in 1..5) {
+            $script:Objects = foreach ($number in 1..5) {
                 [PSCustomObject]@{
                     Number = $number
                     Square = $number * $number
@@ -224,7 +224,7 @@
     Context 'ConvertFrom-Csv' {
 
         BeforeAll {
-            $CsvString = @"
+            $script:CsvString = @"
 "Number","Square"
 "1","1"
 "2","4"
@@ -235,7 +235,6 @@
         }
 
         It 'operates on string data rather than directly with files' {
-            $Objects = $CsvString | ConvertFrom-Csv
             $CsvString -is [____] | Should -BeTrue
         }
 

PSKoans/Koans/Constructs and Patterns/AboutBitwiseOperations.Koans.ps1

@@ -37,6 +37,7 @@
         #>
         function ConvertFrom-Binary {
             [CmdletBinding()]
+            [OutputType([string], [byte], [sbyte], [int16], [int32], [int64])]
             param (
                 # The binary string to convert.
                 [Parameter(Mandatory, Position = 0, ValueFromPipeline)]
@@ -142,7 +143,7 @@
     Context 'Int16, Int32, and Int64' {
         # Larger integer types, such as Int32, are made up of several bytes.
 
         It 'uses mulitple bytes to describe a larger integers' {
             '00010100 00000001' | ConvertFrom-Binary -To Int16 | Should -BeOfType [Int16]
             '01000000 00000100 00000010 00110001' | ConvertFrom-Binary -To Int32 | Should -BeOfType [Int32]
         }
@@ -512,7 +513,7 @@
             $BinaryValue | ConvertFrom-Binary -To Int32 | Should -Be 1652126821
             $BinaryValue | ConvertFrom-Binary -To ASCIIString | Should -Be 'byte'
 
             # This can be explored forindividual bytes, by setting all others to 0. For example:
 
             '________ 00000000 00000000 00000000' | ConvertFrom-Binary -To Int32 | Should -Be 1644167168
             '00000000 00000000 00000000 ________' | ConvertFrom-Binary -To Int32 | Should -Be 101

PSKoans/Koans/Constructs and Patterns/AboutEnumerations.Koans.ps1

@@ -1,4 +1,14 @@
 using module PSKoans
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseShouldProcessForStateChangingFunctions',
+    '',
+    Justification = 'New-Enumeration is a minimal in-exercise example defining an enum in a nested scope; it has no real side effects to guard with ShouldProcess.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseUsingScopeModifierInNewRunspaces',
+    '',
+    Justification = '$Type is Get-Objects own function parameter declared inside the Start-Job scriptblock, not a captured outer-scope variable; $using: does not apply.'
+)]
 [Koan(Position = 310)]
 param()
 <#
@@ -147,7 +157,7 @@
             #>
 
             $enumNames = Start-Job -ScriptBlock {
                 enum ColourOfTheRainbow {
                     Red
                     Yellow
                     Pink
@@ -157,7 +167,7 @@
                     Blue
                 }
 
                 [ColourOfTheRainbow].GetEnumNames()
             } | Receive-Job -Wait
 
             $colours = @(

PSKoans/Koans/Constructs and Patterns/AboutErrorHandling.Koans.ps1

@@ -48,7 +48,7 @@ Describe 'ErrorRecord' {
     }
     Context 'Error Assignments' {
         BeforeAll {
-            $ErrorRecord = try {
+            $script:ErrorRecord = try {
                 throw "A challenge to the sky!"
             }
             catch {

PSKoans/Koans/Constructs and Patterns/AboutLists.Koans.ps1

@@ -1,4 +1,9 @@
 using module PSKoans
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'Item',
+    Justification = 'Second $Filter is a blank scriptblock body the learner completes; $Item is unused until solved.'
+)]
 [Koan(Position = 301)]
 param()
 <#
@@ -125,10 +130,10 @@ Describe 'Lists' {
             #>
             $Filter = {
                 # The input variable representing each entry must be named, or use $args[0].
-                param($_)
+                param($Item)
 
                 # Remove everything that contains the number 9, essentially.
-                $_ -match '9'
+                $Item -match '9'
                 # The output must boil down to a $true/$false, or will be coerced to it.
             }
             $List.RemoveAll($Filter) | Should -BeTrue
@@ -137,7 +142,7 @@ Describe 'Lists' {
             $List | Should -Be $RemainingEntries
 
             $Filter = {
-                param($_)
+                param($Item)
                 # Fill in this script block to make the below assertions true!
 
             }

PSKoans/Koans/Constructs and Patterns/AboutPSObjects.Koans.ps1

@@ -19,7 +19,7 @@ param()
 
 Describe 'PSObject' {
     BeforeAll {
-        $Object = @('Stand for nothing; fall for everything.')
+        $script:Object = @('Stand for nothing; fall for everything.')
     }
 
     It "is accessed via a hidden .PSObject property" {

PSKoans/Koans/Constructs and Patterns/AboutRedirection.Koans.ps1

@@ -36,9 +36,9 @@ param()
 #>
 Describe 'Redirection Operators' {
     BeforeAll {
-        $OriginalDebugPreference = $DebugPreference
-        $OriginalVerbosePreference = $VerbosePreference
-        $FilePath = 'TestDrive:\TestFile.txt'
+        $script:OriginalDebugPreference = $DebugPreference
+        $script:OriginalVerbosePreference = $VerbosePreference
+        $script:FilePath = 'TestDrive:\TestFile.txt'
 
         $DebugPreference = $VerbosePreference = 'Continue'
     }