Measure-ParamBlock - New Check (#20)

dsccommunity · Oct 6, 2024 · 1000b22 · 1000b22
1 parent 73bb393
commit 1000b22
Show file tree

Hide file tree

Showing 13 changed files with 490 additions and 26 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Add LICENSE.md.
   - Add SECURITY.md
   - Add codecov config.
+- `Measure-ParamBlock` fixes [#13](https://github.com/dsccommunity/DscResource.AnalyzerRules/issues/13).
+  - New localization strings.
+  - `Test-StatementEmptyParenthesesHasWhitespace` helper method.
+  - `Test-StatementOpeningParenthsesOnSameLine` helper method.
+  - Fixed type on `Test-StatementOpeningBrace*`.
+  - `Measure-ParameterBlock*` format test data.
 
 ### Fixed
 

diff --git a/Source/Private/Test-StatementEmptyParenthsesHasWhitespace.ps1 b/Source/Private/Test-StatementEmptyParenthsesHasWhitespace.ps1
@@ -0,0 +1,39 @@
+
+<#
+    .SYNOPSIS
+        Helper function for the Measure-*Block PSScriptAnalyzer rules.
+        Test a single statement block for whitespace inside the parentheses.
+
+    .EXAMPLE
+        Test-StatementEmptyParenthsesHasWhitespace -StatementBlock $ScriptBlockAst.Extent
+
+    .INPUTS
+        [System.String]
+
+    .OUTPUTS
+        [System.Boolean]
+
+    .NOTES
+        None
+#>
+
+function Test-StatementEmptyParenthsesHasWhitespace
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $StatementBlock
+    )
+
+    # Check that the parentheses does not contain whitespace.
+    if ($statementBlock -match '\(\s+\)')
+    {
+        return $true
+    } # if
+
+    return $false
+}
diff --git a/Source/Private/Test-StatementOpeningBraceIsFollowedByMoreThanOneNewLine.ps1 b/Source/Private/Test-StatementOpeningBraceIsFollowedByMoreThanOneNewLine.ps1
@@ -13,7 +13,7 @@
     .OUTPUTS
         [System.Boolean]
 
-   .NOTES
+    .NOTES
         None
 #>
 function Test-StatementOpeningBraceIsFollowedByMoreThanOneNewLine
@@ -28,7 +28,7 @@ function Test-StatementOpeningBraceIsFollowedByMoreThanOneNewLine
         $StatementBlock
     )
 
-    $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
+    [System.String[]] $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
     if ($statementBlockRows.Count -ge 3)
     {
         # Check so that an opening brace is followed by only one new line.

diff --git a/Source/Private/Test-StatementOpeningBraceIsNotFollowedByNewLine.ps1 b/Source/Private/Test-StatementOpeningBraceIsNotFollowedByNewLine.ps1
@@ -13,7 +13,7 @@
     .OUTPUTS
         [System.Boolean]
 
-   .NOTES
+    .NOTES
         None
 #>
 function Test-StatementOpeningBraceIsNotFollowedByNewLine
@@ -28,7 +28,7 @@ function Test-StatementOpeningBraceIsNotFollowedByNewLine
         $StatementBlock
     )
 
-    $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
+    [System.String[]] $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
     if ($statementBlockRows.Count -ge 2)
     {
         # Check so that an opening brace is followed by a new line.

diff --git a/Source/Private/Test-StatementOpeningBraceOnSameLine.ps1 b/Source/Private/Test-StatementOpeningBraceOnSameLine.ps1
@@ -13,7 +13,7 @@
     .OUTPUTS
         [System.Boolean]
 
-   .NOTES
+    .NOTES
         None
 #>
 function Test-StatementOpeningBraceOnSameLine
@@ -28,7 +28,7 @@ function Test-StatementOpeningBraceOnSameLine
         $StatementBlock
     )
 
-    $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
+    [System.String[]] $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
     if ($statementBlockRows.Count)
     {
         # Check so that an opening brace does not exist on the same line as the statement.

diff --git a/Source/Private/Test-StatementOpeningParenthsesOnSameLine.ps1 b/Source/Private/Test-StatementOpeningParenthsesOnSameLine.ps1
@@ -0,0 +1,44 @@
+
+<#
+    .SYNOPSIS
+        Helper function for the Measure-*Block PSScriptAnalyzer rules.
+        Test a single statement block for opening parentheses on the same line.
+
+    .EXAMPLE
+        Test-StatementOpeningParenthsesOnSameLine -StatementBlock $ScriptBlockAst.Extent
+
+    .INPUTS
+        [System.String]
+
+    .OUTPUTS
+        [System.Boolean]
+
+    .NOTES
+        None
+#>
+
+function Test-StatementOpeningParenthsesOnSameLine
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $StatementBlock
+    )
+
+    [System.String[]] $statementBlockRows = Get-StatementBlockAsRow -StatementBlock $StatementBlock
+    if ($statementBlockRows.Count)
+    {
+
+        # Check so that an opening brace does not exist on the same line as the statement.
+        if ($statementBlockRows[0] -match '\(')
+        {
+            return $true
+        } # if
+    } # if
+
+    return $false
+}
diff --git a/Source/Public/Measure-ParamBlock.ps1 b/Source/Public/Measure-ParamBlock.ps1
@@ -0,0 +1,69 @@
+<#
+    .SYNOPSIS
+        Validates the param-block parentheses and new lines around parentheses.
+
+    .DESCRIPTION
+        Each param-block should have the opening parentheses on the same line if empty.
+        If the param-block has values then the parentheses should be on a new line.
+
+    .EXAMPLE
+        Measure-ParamBlock -ParamBlockAst $ScriptBlockAst
+
+    .INPUTS
+        [System.Management.Automation.Language.ParamBlockAst]
+
+    .OUTPUTS
+        [Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]]
+
+    .NOTES
+        None
+#>
+function Measure-ParamBlock
+{
+    [CmdletBinding()]
+    [OutputType([Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.Language.ParamBlockAst]
+        $ParamBlockAst
+    )
+
+    try
+    {
+        $script:diagnosticRecord['Extent'] = $ParamBlockAst.Extent
+        $script:diagnosticRecord['RuleName'] = $PSCmdlet.MyInvocation.InvocationName
+
+        $testParameters = @{
+            StatementBlock = $ParamBlockAst.Extent
+        }
+
+        if ($ParamBlockAst.Parameters)
+        {
+            if (Test-StatementOpeningParenthsesOnSameLine @testParameters)
+            {
+                $script:diagnosticRecord['Message'] = $localizedData.ParamBlockNotEmptyParenthesesShouldBeOnNewLine
+                $script:diagnosticRecord -as $diagnosticRecordType
+            } # if
+        }
+        else
+        {
+            if (-not (Test-StatementOpeningParenthsesOnSameLine @testParameters))
+            {
+                $script:diagnosticRecord['Message'] = $localizedData.ParamBlockEmptyParenthesesShouldBeOnSameLine
+                $script:diagnosticRecord -as $diagnosticRecordType
+            } # if
+
+            if (Test-StatementEmptyParenthsesHasWhitespace @testParameters)
+            {
+                $script:diagnosticRecord['Message'] = $localizedData.ParamBlockEmptyParenthesesShouldNotHaveWhitespace
+                $script:diagnosticRecord -as $diagnosticRecordType
+            } # if
+        }
+    }
+    catch
+    {
+        $PSCmdlet.ThrowTerminatingError($PSItem)
+    }
+}
diff --git a/Source/en-US/DscResource.AnalyzerRules.psd1 b/Source/en-US/DscResource.AnalyzerRules.psd1
@@ -44,4 +44,7 @@ ClassOpeningBraceShouldBeFollowedByNewLine = Opening brace on Class should be fo
 ClassOpeningBraceShouldBeFollowedByOnlyOneNewLine = Opening brace on Class should only be followed by one new line. See https://dsccommunity.org/styleguidelines/whitespace/#one-newline-after-opening-brace
 OneSpaceBetweenKeywordAndParenthesis = If a keyword is followed by a parenthesis, there should be single space between the keyword and the parenthesis. See https://dsccommunity.org/styleguidelines/whitespace/#one-space-between-keyword-and-parenthesis
 HashtableShouldHaveCorrectFormat = Hashtable is not correctly formatted. See https://dsccommunity.org/styleguidelines/general/#correct-format-for-hashtables-or-objects
+ParamBlockEmptyParenthesesShouldBeOnSameLine = If ParamBlock parentheses are empty they should be on the same line. See https://dsccommunity.org/styleguidelines/parameters/#correct-format-for-parameter-block
+ParamBlockEmptyParenthesesShouldNotHaveWhitespace = If ParamBlock parentheses are empty they should not contain whitespace. See https://dsccommunity.org/styleguidelines/parameters/#correct-format-for-parameter-block
+ParamBlockNotEmptyParenthesesShouldBeOnNewLine = If ParamBlock parentheses are not empty they should be on a new line. See https://dsccommunity.org/styleguidelines/parameters/#correct-format-for-parameter-block
 '@
diff --git a/tests/Unit/Private/Test-StatementEmptyParenthsesHasWhitespace.Tests.ps1 b/tests/Unit/Private/Test-StatementEmptyParenthsesHasWhitespace.Tests.ps1
@@ -0,0 +1,62 @@
+$ProjectPath = "$PSScriptRoot\..\..\.." | Convert-Path
+$ProjectName = ((Get-ChildItem -Path $ProjectPath\*\*.psd1).Where{
+        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
+        $(try
+            {
+                Test-ModuleManifest -Path $_.FullName -ErrorAction Stop
+            }
+            catch
+            {
+                $false
+            } )
+    }).BaseName
+
+
+Import-Module $ProjectName
+
+InModuleScope $ProjectName {
+    Describe 'Test-StatementEmptyParenthsesHasWhitespace' {
+        Context 'When statement has just whitespace in parentheses' {
+            It 'Should return $true' {
+                $testStatementEmptyParenthsesHasWhitespaceParameters = @{
+                    StatementBlock = `
+                    'param ( )'
+                }
+
+                $testStatementEmptyParenthsesHasWhitespaceResult = `
+                    Test-StatementEmptyParenthsesHasWhitespace @testStatementEmptyParenthsesHasWhitespaceParameters
+
+                $testStatementEmptyParenthsesHasWhitespaceResult | Should -Be $true
+            }
+        }
+
+        Context 'When statement has a newline in parentheses' {
+            It 'Should return $true' {
+                $testStatementEmptyParenthsesHasWhitespaceParameters = @{
+                    StatementBlock = `
+                    'param (
+                    )'
+                }
+
+                $testStatementEmptyParenthsesHasWhitespaceResult = `
+                    Test-StatementEmptyParenthsesHasWhitespace @testStatementEmptyParenthsesHasWhitespaceParameters
+
+                $testStatementEmptyParenthsesHasWhitespaceResult | Should -Be $true
+            }
+        }
+
+        Context 'When statement follows style guideline' {
+            It 'Should return $false' {
+                $testStatementEmptyParenthsesHasWhitespaceParameters = @{
+                    StatementBlock = `
+                    'param ()'
+                }
+
+                $testStatementEmptyParenthsesHasWhitespaceResult = `
+                    Test-StatementEmptyParenthsesHasWhitespace @testStatementEmptyParenthsesHasWhitespaceParameters
+
+                $testStatementEmptyParenthsesHasWhitespaceResult | Should -Be $false
+            }
+        }
+    }
+}
diff --git a/tests/Unit/Private/Test-StatementOpeningParenthsesOnSameLine.Tests.ps1 b/tests/Unit/Private/Test-StatementOpeningParenthsesOnSameLine.Tests.ps1
@@ -0,0 +1,48 @@
+$ProjectPath = "$PSScriptRoot\..\..\.." | Convert-Path
+$ProjectName = ((Get-ChildItem -Path $ProjectPath\*\*.psd1).Where{
+        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
+        $(try
+            {
+                Test-ModuleManifest -Path $_.FullName -ErrorAction Stop
+            }
+            catch
+            {
+                $false
+            } )
+    }).BaseName
+
+
+Import-Module $ProjectName
+
+InModuleScope $ProjectName {
+    Describe 'Test-StatementOpeningParenthsesOnSameLine' {
+        Context 'When statement has an opening parentheses on the same line' {
+            It 'Should return $true' {
+                $testStatementOpeningParenthsesOnSameLineParameters = @{
+                    StatementBlock = `
+                        'param ()'
+                }
+
+                $testStatementOpeningParenthsesOnSameLineResult = `
+                    Test-StatementOpeningParenthsesOnSameLine @testStatementOpeningParenthsesOnSameLineParameters
+
+                $testStatementOpeningParenthsesOnSameLineResult | Should -Be $true
+            }
+        }
+
+        Context 'When statement does not have an opening parentheses on the same line' {
+            It 'Should return $false' {
+                $testStatementOpeningParenthsesOnSameLineParameters = @{
+                    StatementBlock = `
+                        'param
+                        ()'
+                }
+
+                $testStatementOpeningParenthsesOnSameLineResult = `
+                    Test-StatementOpeningParenthsesOnSameLine @testStatementOpeningParenthsesOnSameLineParameters
+
+                $testStatementOpeningParenthsesOnSameLineResult | Should -Be $false
+            }
+        }
+    }
+}