Fix table to refer to existing md files, add col for Configurable (#988)

* Fix table to refer to existing md files, add col for Configurable

* Remove deprecated rules, rename to match actual rule sans PS prefix

* Add Pester tests for rule doc files, add back UseSingularNouns.md file

* Add Pester tests for verifying rule doc README.md file

* fix typo in documentation folder, remove redundant ipmo call new tests in CI and add to docs

* Add rules that will be present in 1.17 and fix typo in md file name

* remove redundant import of PSScriptAnalyzerTestHelper test helper module in documentation test

* Fix doc tests for PS v4 and PS Core

This commit removes rules that aren't available on these versions

* Remove leftovers from deprecated rules AvoidUsingFilePath, AvoidUninitializedVariable and AvoidTrapStatement in code and documentation.
Fix markdown in PowerShellBestPractices.md and tidy up

* added remarks about rules not being available in certain powershell versions

* Add superscript/footnote on rules not available everywhere

* Update test to strip off the optional superscript markdown

Author: rkeithhill

Engine/Settings/PSGallery.psd1

@@ -21,7 +21,6 @@
                    'PSAvoidUsingConvertToSecureStringWithPlainText',
                    'PSUsePSCredentialType',
                    'PSAvoidUsingUserNameAndPasswordParams',
-                   'PSAvoidUsingFilePath',
                    'PSDSC*'
                    )
 }

Engine/Settings/ScriptSecurity.psd1

@@ -3,6 +3,5 @@
                    'PSAvoidUsingComputerNameHardcoded',
                    'PSAvoidUsingConvertToSecureStringWithPlainText',
                    'PSUsePSCredentialType',
-                   'PSAvoidUsingUserNameAndPasswordParams',
-                   'PSAvoidUsingFilePath')
+                   'PSAvoidUsingUserNameAndPasswordParams')
 }

PowerShellBestPractices.md

@@ -158,16 +158,10 @@ Pester-based ScriptAnalyzer Tests are located in `path/to/PSScriptAnalyzer/Tests
 
 * Ensure [Pester 4.3.1](https://www.powershellgallery.com/packages/Pester/4.3.1) is installed
 * Copy `path/to/PSScriptAnalyzer/out/PSScriptAnalyzer` to a folder in `PSModulePath`
-* Go the Tests folder in your local repository
-* Run Engine Tests:
+* In the root folder of your local repository, run:
 ``` PowerShell
-cd /path/to/PSScriptAnalyzer/Tests/Engine
-Invoke-Pester
-```
-* Run Tests for Built-in rules:
-``` PowerShell
-cd /path/to/PSScriptAnalyzer/Tests/Rules
-Invoke-Pester
+$testScripts = ".\Tests\Engine",".\Tests\Rules",".\Tests\Documentation"
+Invoke-Pester -Script $testScripts
 ```
 
 [Back to ToC](#table-of-contents)

README.md

@@ -4,11 +4,12 @@
 
 ## Description
 
-Globally scoped aliases override existing aliases within the sessions with matching names. This name collision can cause difficult to debug issues for consumers of modules and scripts.  
-
+Globally scoped aliases override existing aliases within the sessions with matching names. This name collision can cause difficult to debug issues for consumers of modules and scripts.
 
 To understand more about scoping, see ```Get-Help about_Scopes```.
 
+**NOTE** This rule is not available in PowerShell version 3 and 4 due to the `StaticParameterBinder.BindCommand` API that the rule uses internally.
+
 ## How
 
 Use other scope modifiers for new aliases.

RuleDocumentation/AvoidGlobalAliases.md

@@ -0,0 +1,63 @@
+# PSScriptAnalyzer Rules
+
+## Table of Contents
+
+| Rule | Severity | Configurable |
+|------|----------------------------------|--------------|
+|[AlignAssignmentStatement](./AlignAssignmentStatement.md) | Warning | |
+|[AvoidAssignmentToAutomaticVariable](./AvoidAssignmentToAutomaticVariable.md) | Warning | |
+|[AvoidDefaultValueForMandatoryParameter](./AvoidDefaultValueForMandatoryParameter.md) | Warning | |
+|[AvoidDefaultValueSwitchParameter](./AvoidDefaultValueSwitchParameter.md) | Warning | |
+|[AvoidGlobalAliases<sup>*</sup>](./AvoidGlobalAliases.md) | Warning | |
+|[AvoidGlobalFunctions](./AvoidGlobalFunctions.md) | Warning | |
+|[AvoidGlobalVars](./AvoidGlobalVars.md) | Warning | |
+|[AvoidInvokingEmptyMembers](./AvoidInvokingEmptyMembers.md) | Warning | |
+|[AvoidNullOrEmptyHelpMessageAttribute](./AvoidNullOrEmptyHelpMessageAttribute.md) | Warning | |
+|[AvoidShouldContinueWithoutForce](./AvoidShouldContinueWithoutForce.md) | Warning | |
+|[AvoidUsingCmdletAliases](./AvoidUsingCmdletAliases.md) | Warning | Yes |
+|[AvoidUsingComputerNameHardcoded](./AvoidUsingComputerNameHardcoded.md) | Error | |
+|[AvoidUsingConvertToSecureStringWithPlainText](./AvoidUsingConvertToSecureStringWithPlainText.md) | Error | |
+|[AvoidUsingDeprecatedManifestFields](./AvoidUsingDeprecatedManifestFields.md) | Warning | |
+|[AvoidUsingEmptyCatchBlock](./AvoidUsingEmptyCatchBlock.md) | Warning | |
+|[AvoidUsingInvokeExpression](./AvoidUsingInvokeExpression.md) | Warning | |
+|[AvoidUsingPlainTextForPassword](./AvoidUsingPlainTextForPassword.md) | Warning | |
+|[AvoidUsingPositionalParameters](./AvoidUsingPositionalParameters.md) | Warning | |
+|[AvoidTrailingWhitespace](./AvoidTrailingWhitespace.md) | Warning | |
+|[AvoidUsingUsernameAndPasswordParams](./AvoidUsingUsernameAndPasswordParams.md) | Error | |
+|[AvoidUsingWMICmdlet](./AvoidUsingWMICmdlet.md) | Warning | |
+|[AvoidUsingWriteHost](./AvoidUsingWriteHost.md) | Warning | |
+|[DSCDscExamplesPresent](./DSCDscExamplesPresent.md) | Information | |
+|[DSCDscTestsPresent](./DSCDscTestsPresent.md) | Information | |
+|[DSCReturnCorrectTypesForDSCFunctions](./DSCReturnCorrectTypesForDSCFunctions.md) | Information | |
+|[DSCStandardDSCFunctionsInResource](./DSCStandardDSCFunctionsInResource.md) | Error | |
+|[DSCUseIdenticalMandatoryParametersForDSC](./DSCUseIdenticalMandatoryParametersForDSC.md) | Error | |
+|[DSCUseIdenticalParametersForDSC](./DSCUseIdenticalParametersForDSC.md) | Error | |
+|[DSCUseVerboseMessageInDSCResource](./DSCUseVerboseMessageInDSCResource.md) | Error | |
+|[MisleadingBacktick](./MisleadingBacktick.md) | Warning | |
+|[MissingModuleManifestField](./MissingModuleManifestField.md) | Warning | |
+|[PossibleIncorrectComparisonWithNull](./PossibleIncorrectComparisonWithNull.md) | Warning | |
+|[PossibleIncorrectUsageOfAssignmentOperator](./PossibleIncorrectUsageOfAssignmentOperator.md) | Warning | |
+|[PossibleIncorrectUsageOfRedirectionOperator](./PossibleIncorrectUsageOfRedirectionOperator.md) | Warning | |
+|[ProvideCommentHelp](./ProvideCommentHelp.md) | Information | Yes |
+|[ReservedCmdletChar](./ReservedCmdletChar.md) | Error | |
+|[ReservedParams](./ReservedParams.md) | Error | |
+|[ShouldProcess](./ShouldProcess.md) | Error | |
+|[UseApprovedVerbs](./UseApprovedVerbs.md) | Warning | |
+|[UseBOMForUnicodeEncodedFile](./UseBOMForUnicodeEncodedFile.md) | Warning | |
+|[UseCmdletCorrectly](./UseCmdletCorrectly.md) | Warning | |
+|[UseDeclaredVarsMoreThanAssignments](./UseDeclaredVarsMoreThanAssignments.md) | Warning | |
+|[UseLiteralInitializerForHashtable](./UseLiteralInitializerForHashtable.md) | Warning | |
+|[UseOutputTypeCorrectly](./UseOutputTypeCorrectly.md) | Information | |
+|[UsePSCredentialType](./UsePSCredentialType.md) | Warning | |
+|[UseShouldProcessForStateChangingFunctions](./UseShouldProcessForStateChangingFunctions.md) | Warning | |
+|[UseSingularNouns<sup>*</sup>](./UseSingularNouns.md) | Warning | |
+|[UseSupportsShouldProcess](./UseSupportsShouldProcess.md) | Warning | |
+|[UseToExportFieldsInManifest](./UseToExportFieldsInManifest.md) | Warning | |
+|[UseCompatibleCmdlets](./UseCompatibleCmdlets.md) | Warning | Yes |
+|[PlaceOpenBrace](./PlaceOpenBrace.md) | Warning | Yes |
+|[PlaceCloseBrace](./PlaceCloseBrace.md) | Warning | Yes |
+|[UseConsistentIndentation](./UseConsistentIndentation.md) | Warning | Yes |
+|[UseConsistentWhitespace](./UseConsistentWhitespace.md) | Warning | Yes |
+|[UseUTF8EncodingForHelpFile](./UseUTF8EncodingForHelpFile.md) | Warning | |
+
+<sup>*</sup> Rule is not available on all PowerShell versions, editions and/or OS platforms. See the rule's documentation for details.

RuleDocumentation/AvoidTrapStatement.md

@@ -6,6 +6,8 @@
 
 PowerShell team best practices state cmdlets should use singular nouns and not plurals.
 
+**NOTE** This rule is not available in PowerShell Core due to the PluralizationService API that the rule uses internally.
+
 ## How
 
 Change plurals to singular.
@@ -17,7 +19,7 @@ Change plurals to singular.
 ``` PowerShell
 function Get-Files
 {
-	...
+    ...
 }
 ```
 
@@ -26,6 +28,6 @@ function Get-Files
 ``` PowerShell
 function Get-File
 {
-	...
+    ...
 }
 ```