OSOE-580: Custom analyzer rule for parameter and variable name styling

.github/workflows/static-code-analysis-this-repo.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   powershell-static-code-analysis:
     name: PowerShell Static Code Analysis
-    uses: Lombiq/PowerShell-Analyzers/.github/workflows/static-code-analysis.yml@dev
+    uses: Lombiq/PowerShell-Analyzers/.github/workflows/static-code-analysis.yml@issue/OSOE-580
     with:
       # Making sure that analysis runs through both PowerShell editions regardless of the default configuration of the
       # workflow and the underlying action to ensure backwards-compatibility.

.github/workflows/static-code-analysis.yml

@@ -79,7 +79,7 @@ jobs:
           token: ${{ secrets.CHECKOUT_TOKEN }}
 
       - name: PowerShell Static Code Analysis
-        uses: Lombiq/PowerShell-Analyzers/.github/actions/static-code-analysis@dev
+        uses: Lombiq/PowerShell-Analyzers/.github/actions/static-code-analysis@issue/OSOE-580
         with:
           run-windows-powershell: ${{ inputs.run-windows-powershell }}
           run-powershell-core: ${{ inputs.run-powershell-core }}

.github/workflows/test-analysis-failure.yml

@@ -23,10 +23,15 @@ jobs:
         PSAvoidUsingDoubleQuotesForConstantString: Use single quotes when a string is constant.
         PSAvoidUsingEmptyCatchBlock: Empty catch block is used.
         PSAvoidUsingLineContinuation: Using backtick (line continuation) makes the code harder to read and maintain.
+        PSAvoidUsingUnnecessaryBracesInVariableNames: Variable names should not use unnecessary braces
         PSAvoidUsingWriteHost: File 'Violate-Analyzers.ps1' uses Write-Host.
         PSPlaceOpenBrace: Open brace is not on a new line.
         PSUseApprovedVerbs: The cmdlet 'Violate-Analyzers' uses an unapproved verb.
         PSUseConsistentIndentation: Indentation not consistent
+        PSUseCorrectAutomaticVariableNames: Automatic variables should be used exactly as they are documented
+        PSUseCorrectParameterNameCasing: Parameter names should start with an uppercase letter
+        PSUseCorrectVariableNameCasing: Variable names should start with a lowercase letter
+        PSUseParametersAsDeclared: Parameters should be used with exactly as they were declared
         PSUseSingularNouns: The cmdlet 'Violate-Analyzers' uses a plural noun.
 
   call-test-analysis-failure-local:
@@ -44,8 +49,13 @@ jobs:
         PSAvoidUsingDoubleQuotesForConstantString: Use single quotes when a string is constant.
         PSAvoidUsingEmptyCatchBlock: Empty catch block is used.
         PSAvoidUsingLineContinuation: Using backtick (line continuation) makes the code harder to read and maintain.
+        PSAvoidUsingUnnecessaryBracesInVariableNames: Variable names should not use unnecessary braces
         PSAvoidUsingWriteHost: File 'Violate-Analyzers.ps1' uses Write-Host.
         PSPlaceOpenBrace: Open brace is not on a new line.
         PSUseApprovedVerbs: The cmdlet 'Violate-Analyzers' uses an unapproved verb.
         PSUseConsistentIndentation: Indentation not consistent
+        PSUseCorrectAutomaticVariableNames: Automatic variables should be used exactly as they are documented
+        PSUseCorrectParameterNameCasing: Parameter names should start with an uppercase letter
+        PSUseCorrectVariableNameCasing: Variable names should start with a lowercase letter
+        PSUseParametersAsDeclared: Parameters should be used with exactly as they were declared
         PSUseSingularNouns: The cmdlet 'Violate-Analyzers' uses a plural noun.

Lombiq.Analyzers.PowerShell/Invoke-Analyzer.ps1

@@ -66,7 +66,7 @@ function Write-FileError([string] $Message, [string] $Path, [int] $Line = 0, [in
     }
     else
     {
-        Write-Error $(if ($Path) { "[$Path|ln ${Line}:${Column}] $Message" } else { $Message })
+        Write-Error $(if ($Path) { "[$Path|ln $($Line):$Column] $Message" } else { $Message })
     }
 }
 

Lombiq.Analyzers.PowerShell/Rules/AstFunctions.ps1

@@ -0,0 +1,65 @@
+using namespace System.Management.Automation.Language
+
+# Traverse the chain of parents of an AST object until a parent of a specific type is found.
+function Find-AstNearestParent
+{
+    param(
+        [Parameter(Mandatory = $true)] [Ast] $AstObject,
+        [Parameter(Mandatory = $true)] [Type] $ParentType
+    )
+
+    $parent = $AstObject.Parent
+    while ($null -ne $parent -and $parent -isNot $ParentType)
+    {
+        $parent = $parent.Parent
+    }
+
+    return $parent
+}
+
+# Traverse the chain of parents of an AST object to extract each parent of a specific type.
+function Find-AstParent
+{
+    param(
+        [Parameter(Mandatory = $true)] [Ast] $AstObject,
+        [Parameter(Mandatory = $true)] [Type] $ParentType
+    )
+
+    $parents = @()
+    $currentParent = Find-AstNearestParent -AstObject $AstObject -ParentType $ParentType
+    while ($null -ne $currentParent)
+    {
+        $parents += @($currentParent)
+        $currentParent = Find-AstNearestParent -AstObject $currentParent -ParentType $ParentType
+    }
+
+    return $parents
+}
+
+# Extract the parameters of a script block or a function definition.
+function Find-AstParameter
+{
+    param([Parameter(Mandatory = $true)] [Ast] $AstObject)
+
+    $parameters = @()
+
+    if (-not $AstObject -is [ScriptBlockAst] -and -not $AstObject -is [FunctionDefinitionAst])
+    {
+        throw 'The provided AST object is not a script block or a function definition.'
+    }
+
+    if ($AstObject.Parameters)
+    {
+        $parameters += $AstObject.Parameters
+    }
+    elseif ($AstObject.ParamBlock.Parameters)
+    {
+        $parameters += $AstObject.ParamBlock.Parameters
+    }
+    elseif ($AstObject.Body.ParamBlock.Parameters)
+    {
+        $parameters += $AstObject.Body.ParamBlock.Parameters
+    }
+
+    return $parameters
+}

Lombiq.Analyzers.PowerShell/Rules/CustomRules.md

@@ -0,0 +1,7 @@
+# Custom analyzer rules
+
+Our custom analyzer rules are automatically included when using `Invoke-Analyzer.ps1` or GitHub Actions.
+
+- `Measure-AutomaticVariableAlias`: Detects the usages of the alias `$_` of the automatic variable `$PSItem` and suggests to correct them.
+- `Measure-LineContinuation`: Detects the usages of the backtick (line continuation) character.
+- `Measure-VariableNameCasing`: Detects inconsistencies in the casing of parameter names and variable names (including automatic variables).

Lombiq.Analyzers.PowerShell/Rules/Measure-AutomaticVariableAlias/Measure-AutomaticVariableAlias.psm1

@@ -1,16 +1,18 @@
 <#
 .SYNOPSIS
-    Detects the usages of the alias $_ of the automatic variable $PSItem and suggests to correct them.
+    Detects the usages of the alias '$_' of the automatic variable '$PSItem' and suggests to correct them.
 .DESCRIPTION
-    The full name of the automatic variable $PSItem should be used instead of its alias $_ for consistency.
+    The full name of the automatic variable '$PSItem' should be used instead of its alias '$_' for consistency. Produces
+    warnings of the type 'PSAvoidUsingAutomaticVariableAlias'.
 .EXAMPLE
     Measure-AutomaticVariableAlias -Token $Token
 .INPUTS
     [System.Management.Automation.Language.Token[]]
 .OUTPUTS
     [Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]]
 .NOTES
-    Inspired by https://github.com/PowerShell/PSScriptAnalyzer/blob/master/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1#L613.
+    Inspired by
+    https://github.com/PowerShell/PSScriptAnalyzer/blob/master/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1#L613.
 #>
 function Measure-AutomaticVariableAlias
 {
@@ -31,14 +33,12 @@ function Measure-AutomaticVariableAlias
         try
         {
             # Filter down tokens to just variable tokens with the name "_".
-            foreach ($automaticVariableAliasToken in $Token | Where-Object { $PSItem.GetType().Name -eq 'VariableToken' -and $PSItem.Name -eq '_' })
+            foreach ($automaticVariableAliasToken in $Token | Where-Object {
+                    $PSItem.Kind -eq [System.Management.Automation.Language.TokenKind]::Variable -and $PSItem.Name -eq '_' })
             {
                 $correctionTypeName = 'Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.CorrectionExtent'
                 $correctionExtent = New-Object -TypeName $correctionTypeName -ArgumentList @(
-                    $automaticVariableAliasToken.Extent.StartLineNumber
-                    $automaticVariableAliasToken.Extent.EndLineNumber
-                    $automaticVariableAliasToken.Extent.StartColumnNumber
-                    $automaticVariableAliasToken.Extent.EndColumnNumber
+                    $automaticVariableAliasToken.Extent
                     '$PSItem'
                     'Replaced the usage of the alias of the automatic variable "$_" with its full name "$PSItem".'
                 )

Lombiq.Analyzers.PowerShell/Rules/Measure-LineContinuation/Measure-LineContinuation.psm1

@@ -5,7 +5,8 @@
     In general, the community feels you should avoid using those backticks as "line continuation characters" when
     possible. They are hard to read, and easy to miss and mistype. Also, adding an extra whitespace after the backtick
     breaks the command execution. To fix a violation of this rule, please remove backticks from your script and use
-    parameter splatting instead. You can run "Get-Help about_splatting" to get more details.
+    parameter splatting instead. You can run "Get-Help about_splatting" to get more details. Produces warnings of type
+    'PSAvoidUsingLineContinuation'.
 .EXAMPLE
     Measure-LineContinuation -Token $Token
 .INPUTS