Added tests, fixed typos, changed default PowerShellVersion behavior

Author: thomasrayner

RuleDocumentation/AvoidOverwritingBuiltInCmdlets.md

@@ -0,0 +1,42 @@
+# AvoidOverwritingBuiltInCmdlets
+
+**Severity Level: Warning**
+
+## 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. 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.
+
+## Configuration
+
+To enable the rule to check if your script is compatible on PowerShell Core on Windows, put the following your settings file.
+
+
+```PowerShell
+@{
+    'Rules' = @{
+        'PSAvoidOverwritingBuiltInCmdlets' = @{
+            'PowerShellVersion' = @("core-6.1.0-windows")
+        }
+    }
+}
+```
+
+### Parameters
+
+#### PowerShellVersion
+
+The parameter `PowerShellVersion` is a list that contain any of the following
+
+- desktop-2.0-windows
+- desktop-3.0-windows
+- desktop-4.0-windows (taken from Windows Server 2012R2)
+- desktop-5.1.14393.206-windows
+- core-6.1.0-windows (taken from Windows 10 - 1803)
+- core-6.1.0-linux (taken from Ubuntu 18.04)
+- core-6.1.0-linux-arm (taken from Raspbian)
+- core-6.1.0-macos
+
+**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.
+
+Usually, patched versions of PowerShell have the same cmdlet data, therefore only settings of major and minor versions of PowerShell are supplied. One can also create a custom settings file as well with the [New-CommandDataFile.ps1](https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Utils/New-CommandDataFile.ps1) script and use it by placing the created `JSON` into the `Settings` folder of the `PSScriptAnalyzer` module installation folder, then the `PowerShellVersion` parameter is just its file name (that can also be changed if desired).
+Note that the `core-6.0.2-*` files were removed in PSScriptAnalyzer 1.18 since PowerShell 6.0 reached it's end of life.

RuleDocumentation/README.md

@@ -12,6 +12,7 @@
 |[AvoidGlobalFunctions](./AvoidGlobalFunctions.md) | Warning | |
 |[AvoidGlobalVars](./AvoidGlobalVars.md) | Warning | |
 |[AvoidInvokingEmptyMembers](./AvoidInvokingEmptyMembers.md) | Warning | |
+|[AvoidOverwritingBuiltInCmdlets](./AvoidOverwritingBuiltInCmdlets.md) | Warning | |
 |[AvoidNullOrEmptyHelpMessageAttribute](./AvoidNullOrEmptyHelpMessageAttribute.md) | Warning | |
 |[AvoidShouldContinueWithoutForce](./AvoidShouldContinueWithoutForce.md) | Warning | |
 |[AvoidUsingCmdletAliases](./AvoidUsingCmdletAliases.md) | Warning | Yes |

Rules/AvoidOverwritingBuiltInCmdlets.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
 #if !CORECLR
 using System.ComponentModel.Composition;
 #endif
@@ -18,7 +19,7 @@
 namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
 {
     /// <summary>
-    /// AvoidLongLines: Checks if a script overwrites a cmdlet that comes with PowerShell
+    /// AvoidOverwritingBuiltInCmdlets: Checks if a script overwrites a cmdlet that comes with PowerShell
     /// </summary>
 #if !CORECLR
     [Export(typeof(IScriptRule))]
@@ -28,6 +29,12 @@ namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
     /// </summary>
     public class AvoidOverwritingBuiltInCmdlets : ConfigurableRule
     {
+        [ConfigurableRuleProperty(defaultValue: "")]
+        public string[] PowerShellVersion { get; set; }
+        private Dictionary<string, HashSet<string>> cmdletMap;
+        private bool initialized;
+
+
         /// <summary>
         /// Construct an object of AvoidOverwritingBuiltInCmdlets type.
         /// </summary>
@@ -36,14 +43,31 @@ public AvoidOverwritingBuiltInCmdlets() : base()
             initialized = false;
             cmdletMap = new Dictionary<string, HashSet<string>>();
             Enable = true;  // Enable rule by default
-        }
-
-
-        [ConfigurableRuleProperty(defaultValue: "core-6.1.0-windows")]
-        public string PowerShellVersion { get; set; }
+            
+            string versionTest = string.Join("", PowerShellVersion);
 
-        private Dictionary<string, HashSet<string>> cmdletMap;
-        private bool initialized;
+            if (versionTest != "core-6.1.0-windows" && versionTest != "desktop-5.1.14393.206-windows")
+            {
+                // PowerShellVersion is not already set to one of the acceptable defaults
+                // Try launching `pwsh -v` to see if PowerShell 6+ is installed, and use those cmdlets
+                // as a default. If 6+ is not installed this will throw an error, which when caught will
+                // allow us to use the PowerShell 5 cmdlets as a default.
+                try
+                {
+                    var testProcess = new Process();
+                    testProcess.StartInfo.FileName = "pwsh";
+                    testProcess.StartInfo.Arguments = "-v";
+                    testProcess.StartInfo.CreateNoWindow = true;
+                    testProcess.StartInfo.UseShellExecute = false;
+                    testProcess.Start();
+                    PowerShellVersion = new[] {"core-6.1.0-windows"};
+                }
+                catch
+                {
+                    PowerShellVersion = new[] {"desktop-5.1.14393.206-windows"};
+                }
+            }
+        }
 
 
         /// <summary>
@@ -118,29 +142,32 @@ private DiagnosticRecord CreateDiagnosticRecord(string FunctionName, string PSVe
 
         private void Initialize()
         {
-            var psVerList = PowerShellVersion.Split(',').ToList();
+            var psVerList = PowerShellVersion;
 
             string settingsPath = Settings.GetShippedSettingsDirectory();
 
-            if (settingsPath == null || !ContainsReferenceFile(settingsPath))
+            foreach (string reference in psVerList)
             {
-                return;
+                if (settingsPath == null || !ContainsReferenceFile(settingsPath, reference))
+                {
+                    return;
+                }
             }
-            
+
             ProcessDirectory(settingsPath, psVerList);
 
             if (cmdletMap.Keys.Count != psVerList.Count())
             {
                 return;
             }
-            
+
             initialized = true;
         }
 
 
-        private bool ContainsReferenceFile(string directory)
+        private bool ContainsReferenceFile(string directory, string reference)
         {
-            return File.Exists(Path.Combine(directory, PowerShellVersion + ".json"));
+            return File.Exists(Path.Combine(directory, reference + ".json"));
         }
 
 
@@ -193,39 +220,6 @@ private HashSet<string> GetCmdletsFromData(dynamic deserializedObject)
         }
 
 
-        private bool IsValidPlatformString(string fileNameWithoutExt)
-        {
-            string psedition, psversion, os;
-            return GetVersionInfoFromPlatformString(
-                fileNameWithoutExt,
-                out psedition,
-                out psversion,
-                out os);
-        }
-
-
-        private bool GetVersionInfoFromPlatformString(
-            string fileName,
-            out string psedition,
-            out string psversion,
-            out string os)
-        {
-            psedition = null;
-            psversion = null;
-            os = null;
-            const string pattern = @"^(?<psedition>core|desktop)-(?<psversion>[\S]+)-(?<os>windows|linux|macos)$";
-            var match = Regex.Match(fileName, pattern, RegexOptions.IgnoreCase);
-            if (match == Match.Empty)
-            {
-                return false;
-            }
-            psedition = match.Groups["psedition"].Value;
-            psversion = match.Groups["psversion"].Value;
-            os = match.Groups["os"].Value;
-            return true;
-        }
-
-
         /// <summary>
         /// Retrieves the common name of this rule.
         /// </summary>

Tests/Engine/GetScriptAnalyzerRule.tests.ps1

@@ -59,7 +59,7 @@ Describe "Test Name parameters" {
 
         It "get Rules with no parameters supplied" {
 			$defaultRules = Get-ScriptAnalyzerRule
-            $expectedNumRules = 59
+            $expectedNumRules = 60
             if ((Test-PSEditionCoreClr) -or (Test-PSVersionV3) -or (Test-PSVersionV4))
             {
                 # for PSv3 PSAvoidGlobalAliases is not shipped because

Tests/Rules/AvoidOverwritingBuiltInCmdlets.tests.ps1

@@ -0,0 +1,86 @@
+$ruleName = "PSAvoidOverwritingBuiltInCmdlets"
+
+$ruleSettingsWindows = @{$ruleName = @{PowerShellVersion = @('desktop-5.1.14393.206-windows')}}
+$ruleSettingsCore = @{$ruleName = @{PowerShellVersion = @('core-6.1.0-windows')}}
+$ruleSettingsBoth = @{$ruleName = @{PowerShellVersion = @('core-6.1.0-windows', 'desktop-5.1.14393.206-windows')}}
+
+$settings = @{
+    IncludeRules = @($ruleName)
+}
+
+# Get-Something is not a built in cmdlet on any platform and should never be flagged
+# Get-ChildItem is available on all versions of PowerShell and should always be flagged
+# Get-Clipboard is available on PowerShell 5 but not 6 and should be flagged conditionally
+$scriptDefinition = @"
+function Get-Something {
+    Write-Output "Get-Something"
+}
+
+function Get-ChildItem {
+    Write-Output "Get-ChildItem"
+}
+
+function Get-Clipboard {
+    Write-Output "Get-Clipboard"
+}
+"@
+
+describe 'AvoidOverwritingBuiltInCmdlets' {
+    context 'No settings specified' {
+        it 'should default to core-6.1.0-windows' {
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $settings
+            $violations.Count | Should -Be 1
+            $violations.Extent.StartLineNumber | Should -Be 5
+        }
+    }
+
+    context 'PowerShellVersion explicitly set to Windows PowerShell' {
+        $settings['Rules'] = $ruleSettingsWindows
+        $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $settings
+
+        it 'should find two violations' {
+            $violations.Count | Should -Be 2
+        }
+        it 'should find the violations on the correct line' {
+            $violations[0].Extent.StartLineNumber | Should -Be 5
+            $violations[0].Extent.EndLineNumber | Should -Be 7
+
+            $violations[1].Extent.StartLineNumber | Should -Be 9
+            $violations[1].Extent.EndLineNumber | Should -Be 11
+        }
+    }
+
+    context 'PowerShellVersion explicitly set to PowerShell 6' {
+        $settings['Rules'] = $ruleSettingsCore
+        $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $settings
+
+        it 'should find one violation' {
+            $violations.Count | Should -Be 1
+        }
+        it 'should find the correct violating function' {
+            $violations.Extent.StartLineNumber | Should -Be 5
+            $violations.Extent.EndLineNumber | Should -Be 7
+        }
+    }
+
+    context 'PowerShellVersion explicitly set to both Windows PowerShell and PowerShell 6' {
+        $settings['Rules'] = $ruleSettingsBoth
+        $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -Settings $settings
+
+        it 'should find three violations' {
+            $violations.Count | Should -Be 3
+        }
+        it 'should find the correct violating functions' {
+            $violations[0].Extent.StartLineNumber | Should -Be 5
+            $violations[0].Extent.EndLineNumber | Should -Be 7
+
+            $violations[1].Extent.StartLineNumber | Should -Be 5
+            $violations[1].Extent.EndLineNumber | Should -Be 7
+
+            $violations[2].Extent.StartLineNumber | Should -Be 9
+            $violations[2].Extent.EndLineNumber | Should -Be 11
+
+        }
+    }
+
+}