Use allowlist and blocklist terminology, supply alternate configuration key for PSAvoidUsingCmdletAliases (#1604)

Author: bergmeister

CHANGELOG.MD

@@ -503,7 +503,7 @@ Many thanks to @rkeithhill for contributing the _Stroustrup_ style code formatti
 ## [1.11.1](https://github.com/PowerShell/PSScriptAnalyzer/tree/1.11.1) - 2017-04-04
 ### Fixed
 - CodeFormatting settings file (#727, #728).
-- Whitelisted aliases comparison in AvoidUsingCmdletAliases rule (#739).
+- Allowlist aliases comparison in AvoidUsingCmdletAliases rule (#739).
 - PlaceCloseBrace rule behavior for NewLineAfter option (#741).
 - UseConsistentIndentation rule to ignore open brace in magic methods (#744).
 
@@ -600,7 +600,7 @@ Here are some improvements since the last release.
 - Fix `SaveDscDependency` switch implementation, which use fail if more than one parameter is given to `Import-DSCResource` dynamic keyword.
 - Add support for external AST based rule suppression
 - Fix rule suppression caused by inavlid offsets
-- Whitelist `Data` in `PSUseSingularNoun` rule
+- Allowlist `Data` in `PSUseSingularNoun` rule
 - Fix rule documentation of `PSDSCExamplesPresent`
 - Fix false positives caused by PSD1 files which are not module manifests
     - affects `PSUseToExportFieldsInManifest`, `PSMissingModuleManifestField` and `PSAvoidUsingDeprecatedManifestFields` rules

RuleDocumentation/AvoidOverwritingBuiltInCmdlets.md

@@ -4,7 +4,7 @@
 
 ## Description
 
-This rule flags cmdlets that are available in a given edition/version of PowerShell on a given operating system which are overwritten by a function declaration. It works by comparing function declarations against a set of whitelists which ship with PSScriptAnalyzer. These whitelist files are used by other PSScriptAnalyzer rules. More information can be found in the documentation for the [UseCompatibleCmdlets](./UseCompatibleCmdlets.md) rule.
+This rule flags cmdlets that are available in a given edition/version of PowerShell on a given operating system which are overwritten by a function declaration. It works by comparing function declarations against a set of allowlists which ship with PSScriptAnalyzer. These allowlist files are used by other PSScriptAnalyzer rules. More information can be found in the documentation for the [UseCompatibleCmdlets](./UseCompatibleCmdlets.md) rule.
 
 ## Configuration
 
@@ -25,7 +25,7 @@ To enable the rule to check if your script is compatible on PowerShell Core on W
 
 #### PowerShellVersion
 
-The parameter `PowerShellVersion` is a list of whitelists that ship with PSScriptAnalyzer.
+The parameter `PowerShellVersion` is a list of allowlists that ship with PSScriptAnalyzer.
 
 **Note**: The default value for `PowerShellVersion` is `"core-6.1.0-windows"` if PowerShell 6 or later is installed, and `"desktop-5.1.14393.206-windows"` if it is not.
 

RuleDocumentation/AvoidUsingCmdletAliases.md

@@ -18,9 +18,9 @@ The use of full command names also allows for syntax highlighting in sites and a
 
 Use the full cmdlet name and not an alias.
 
-## Alias Whitelist
+## Alias Allowlist
 
-To prevent `PSScriptAnalyzer` from flagging your preferred aliases, create a whitelist of the aliases in your settings file and point `PSScriptAnalyzer` to use the settings file. For example, to disable `PSScriptAnalyzer` from flagging `cd`, which is an alias of `Set-Location`, set the settings file content to the following.
+To prevent `PSScriptAnalyzer` from flagging your preferred aliases, create an allowlist of the aliases in your settings file and point `PSScriptAnalyzer` to use the settings file. For example, to disable `PSScriptAnalyzer` from flagging `cd`, which is an alias of `Set-Location`, set the settings file content to the following.
 
 ```PowerShell
 # PSScriptAnalyzerSettings.psd1

RuleDocumentation/UseCompatibleCmdlets.md

@@ -4,7 +4,7 @@
 
 ## Description
 
-This rule flags cmdlets that are not available in a given Edition/Version of PowerShell on a given Operating System. It works by comparing a cmdlet against a set of whitelists which ship with PSScriptAnalyzer. They can be found at `/path/to/PSScriptAnalyzerModule/Settings`. These files are of the form, `PSEDITION-PSVERSION-OS.json` where `PSEDITION` can be either `Core` or `Desktop`, `OS` can be either `Windows`, `Linux` or `MacOS`, and `Version` is the PowerShell version. To enable the rule to check if your script is compatible on PowerShell Core on windows, put the following your settings file:
+This rule flags cmdlets that are not available in a given Edition/Version of PowerShell on a given Operating System. It works by comparing a cmdlet against a set of allowlists which ship with PSScriptAnalyzer. They can be found at `/path/to/PSScriptAnalyzerModule/Settings`. These files are of the form, `PSEDITION-PSVERSION-OS.json` where `PSEDITION` can be either `Core` or `Desktop`, `OS` can be either `Windows`, `Linux` or `MacOS`, and `Version` is the PowerShell version. To enable the rule to check if your script is compatible on PowerShell Core on windows, put the following your settings file:
 
 ```PowerShell
 @{

Rules/AvoidAlias.cs

@@ -22,13 +22,11 @@ namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
 #endif
     public class AvoidAlias : IScriptRule
     {
-        private readonly string whiteListArgName = "whitelist";
+        private readonly string allowListArgName = "allowlist";
+        // keep legacy argument name for next version to allow customers to transition but remove later
+        private readonly string allowListLegacyArgName = "whitelist";
         private bool isPropertiesSet;
-        private List<string> whiteList;
-        public List<string> WhiteList
-        {
-            get { return whiteList; }
-        }
+        public List<string> AllowList { get; private set; }
 
         public AvoidAlias()
         {
@@ -38,22 +36,27 @@ public AvoidAlias()
         /// <summary>
         /// Configure the rule.
         ///
-        /// Sets the whitelist of this rule
+        /// Sets the allowlist of this rule
         /// </summary>
         private void SetProperties()
         {
-            whiteList = new List<string>();
+            AllowList = new List<string>();
             isPropertiesSet = true;
             Dictionary<string, object> ruleArgs = Helper.Instance.GetRuleArguments(GetName());
             if (ruleArgs == null)
             {
                 return;
             }
-            object obj;
-            if (!ruleArgs.TryGetValue(whiteListArgName, out obj))
+            object objLegacy = null;
+            if (!ruleArgs.TryGetValue(allowListArgName, out object obj) &&
+                !ruleArgs.TryGetValue(allowListLegacyArgName, out objLegacy))
             {
                 return;
             }
+            // Fallback for object from legacy allowlist argument name 
+            if (obj == null) {
+                obj = objLegacy;
+            }
             IEnumerable<string> aliases = obj as IEnumerable<string>;
             if (aliases == null)
             {
@@ -72,13 +75,13 @@ private void SetProperties()
                     }
                     else
                     {
-                        whiteList.Add(y);
+                        AllowList.Add(y);
                     }
                 }
             }
             else
             {
-                whiteList.AddRange(aliases);
+                AllowList.AddRange(aliases);
             }
         }
 
@@ -110,7 +113,7 @@ public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
                 // You can also review the remark section in following document,
                 // MSDN: CommandAst.GetCommandName Method
                 if (commandName == null
-                    || whiteList.Contains<string>(commandName, StringComparer.OrdinalIgnoreCase))
+                    || AllowList.Contains<string>(commandName, StringComparer.OrdinalIgnoreCase))
                 {
                     continue;
                 }

Rules/AvoidUserNameAndPasswordParams.cs

@@ -36,7 +36,7 @@ public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
 
             List<String> passwords = new List<String>() {"Password", "Passphrase"};
             List<String> usernames = new List<String>() { "Username", "User"};
-            Type[] typeWhiteList = {typeof(CredentialAttribute),
+            Type[] typeAllowList = {typeof(CredentialAttribute),
                                             typeof(PSCredential),
                                             typeof(System.Security.SecureString),
                                             typeof(SwitchParameter),
@@ -54,7 +54,7 @@ public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
                 // Iterates all ParamAsts and check if their names are on the list.
                 foreach (ParameterAst paramAst in paramAsts)
                 {
-                    var attributes = typeWhiteList.Select(x => GetAttributeOfType(paramAst.Attributes, x));
+                    var attributes = typeAllowList.Select(x => GetAttributeOfType(paramAst.Attributes, x));
                     String paramName = paramAst.Name.VariablePath.ToString();                    
                     foreach (String password in passwords)
                     {

Rules/ProvideCommentHelp.cs

@@ -264,13 +264,13 @@ private void GetCorrectionPosition(
 
         private class ViolationFinder : AstVisitor
         {
-            private HashSet<string> functionWhitelist;
+            private HashSet<string> functionAllowList;
             private List<FunctionDefinitionAst> functionDefinitionAsts;
-            private bool useFunctionWhitelist;
+            private bool useFunctionAllowList;
 
             public ViolationFinder()
             {
-                functionWhitelist = new HashSet<string>();
+                functionAllowList = new HashSet<string>();
                 functionDefinitionAsts = new List<FunctionDefinitionAst>();
             }
 
@@ -281,12 +281,12 @@ public ViolationFinder(HashSet<string> exportedFunctions) : this()
                     throw new ArgumentNullException(nameof(exportedFunctions));
                 }
 
-                this.functionWhitelist = exportedFunctions;
+                this.functionAllowList = exportedFunctions;
             }
 
             public ViolationFinder(HashSet<string> exportedFunctions, bool exportedOnly) : this(exportedFunctions)
             {
-                this.useFunctionWhitelist = exportedOnly;
+                this.useFunctionAllowList = exportedOnly;
             }
 
             public IEnumerable<FunctionDefinitionAst> FunctionDefinitionAsts
@@ -299,7 +299,7 @@ public IEnumerable<FunctionDefinitionAst> FunctionDefinitionAsts
 
             public override AstVisitAction VisitFunctionDefinition(FunctionDefinitionAst funcAst)
             {
-                if ((!useFunctionWhitelist || functionWhitelist.Contains(funcAst.Name))
+                if ((!useFunctionAllowList || functionAllowList.Contains(funcAst.Name))
                     && funcAst.GetHelpContent() == null)
                 {
                     functionDefinitionAsts.Add(funcAst);

Rules/UseCompatibleCmdlets.cs

@@ -498,7 +498,7 @@ private bool RuleParamsValid(Dictionary<string, object> ruleArgs)
         }
 
         /// <summary>
-        /// Check if current command is present in the whitelists
+        /// Check if current command is present in the allowlists
         /// If not, flag the corresponding value in curCmdletCompatibilityMap
         /// </summary>
         private void CheckCompatibility()

Rules/UseConsistentWhitespace.cs

@@ -26,7 +26,7 @@ private enum ErrorKind { BeforeOpeningBrace, Paren, Operator, SeparatorComma, Se
             AfterOpeningBrace, BeforeClosingBrace, BeforePipe, AfterPipe, BetweenParameter };
         private const int whiteSpaceSize = 1;
         private const string whiteSpace = " ";
-        private readonly SortedSet<TokenKind> openParenKeywordWhitelist = new SortedSet<TokenKind>()
+        private readonly SortedSet<TokenKind> openParenKeywordAllowList = new SortedSet<TokenKind>()
         {
             TokenKind.If,
             TokenKind.ElseIf,
@@ -474,7 +474,7 @@ private DiagnosticRecord getDiagnosticRecord(
 
         private bool IsKeyword(Token token)
         {
-            return openParenKeywordWhitelist.Contains(token.Kind);
+            return openParenKeywordAllowList.Contains(token.Kind);
         }
 
         private static bool IsPreviousTokenApartByWhitespace(LinkedListNode<Token> tokenNode)

Rules/UseSingularNouns.cs

@@ -28,7 +28,7 @@ namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
     [Export(typeof(IScriptRule))]
     public class CmdletSingularNoun : IScriptRule {
 
-        private readonly string[] nounWhiteList =
+        private readonly string[] nounAllowList =
         {
             "Data"
         };
@@ -68,7 +68,7 @@ public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName) {
                     if (!ps.IsSingular(noun) && ps.IsPlural(noun))
                     {
                         IScriptExtent extent = Helper.Instance.GetScriptExtentForFunctionName(funcAst);
-                        if (nounWhiteList.Contains(noun, StringComparer.OrdinalIgnoreCase))
+                        if (nounAllowList.Contains(noun, StringComparer.OrdinalIgnoreCase))
                         {
                             continue;
                         }