New rule - ReviewUnusedParameter

Author: mattmcnabb

RuleDocumentation/README.md

@@ -43,6 +43,7 @@
 |[ProvideCommentHelp](./ProvideCommentHelp.md) | Information | Yes |
 |[ReservedCmdletChar](./ReservedCmdletChar.md) | Error | |
 |[ReservedParams](./ReservedParams.md) | Error | |
+|[ReviewUnusedParameter](./ReviewUnusedParameter.md) | Warning | |
 |[ShouldProcess](./ShouldProcess.md) | Error | |
 |[UseApprovedVerbs](./UseApprovedVerbs.md) | Warning | |
 |[UseBOMForUnicodeEncodedFile](./UseBOMForUnicodeEncodedFile.md) | Warning | |

RuleDocumentation/ReviewUnusedParameter.md

@@ -0,0 +1,45 @@
+# ReviewUnusedParameter
+
+**Severity Level: Warning**
+
+## Description
+
+This rule identifies parameters declared in a script, scriptblock, or function scope that have not been used in that scope. 
+
+## How
+
+Consider removing the unused parameter.
+
+## Example
+
+### Wrong
+
+``` PowerShell
+function Test-Parameter
+{
+	Param (
+		$Parameter1,
+		
+		# this parameter is never called in the function
+		$Parameter2
+	)
+	
+	Get-Something $Parameter1
+}
+```
+
+### Correct
+
+``` PowerShell
+function Test-Parameter
+{
+	Param (
+		$Parameter1,
+		
+		# now this parameter is being called in the same scope
+		$Parameter2
+	)
+	
+	Get-Something $Parameter1 $Parameter2
+}
+```

Rules/ReviewUnusedParameter.cs

@@ -0,0 +1,130 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation.Language;
+using Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic;
+#if !CORECLR
+using System.ComponentModel.Composition;
+#endif
+using System.Globalization;
+
+namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
+{
+    /// <summary>
+    /// ReviewUnusedParameter: Check that all declared parameters are used in the script body.
+    /// </summary>
+#if !CORECLR
+[Export(typeof(IScriptRule))]
+#endif
+    public class ReviewUnusedParameter : IScriptRule
+    {
+        public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
+        {
+            if (ast == null)
+            {
+                throw new ArgumentNullException(Strings.NullAstErrorMessage);
+            }
+
+            var scriptBlockAsts = ast.FindAll(x => x is ScriptBlockAst, true);
+            if (scriptBlockAsts == null)
+            {
+                yield break;
+            }
+
+            foreach (ScriptBlockAst scriptBlockAst in scriptBlockAsts)
+            {
+                // find all declared parameters
+                IEnumerable<Ast> parameterAsts = scriptBlockAst.FindAll(a => a is ParameterAst, false);
+
+                // list all variables
+                List<string> variables = scriptBlockAst.FindAll(a => a is VariableExpressionAst, false)
+                    .Cast<VariableExpressionAst>()
+                    .Select(v => v.VariablePath.ToString())
+                    .ToList();
+
+                foreach (ParameterAst parameterAst in parameterAsts)
+                {
+                    // compare the list of variables to the parameter name
+                    // there should be at least two matches of the variable name since the parameter declaration counts as one
+                    int matchCount = variables
+                        .Where(x => x == parameterAst.Name.VariablePath.ToString())
+                        .Count();
+                    if (matchCount > 1)
+                    {
+                        continue;
+                    }
+
+                    // all bets are off if the script uses PSBoundParameters
+                    if (variables.Contains("PSBoundParameters"))
+                    {
+                        continue;
+                    }
+
+                    yield return new DiagnosticRecord(
+                        string.Format(CultureInfo.CurrentCulture, Strings.ReviewUnusedParameterError, parameterAst.Name.VariablePath.UserPath),
+                        parameterAst.Name.Extent,
+                        GetName(),
+                        DiagnosticSeverity.Warning,
+                        fileName,
+                        parameterAst.Name.VariablePath.UserPath
+                    );
+                }
+            }    
+        }
+
+        /// <summary>
+        /// GetName: Retrieves the name of this rule.
+        /// </summary>
+        /// <returns>The name of this rule</returns>
+        public string GetName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.NameSpaceFormat, GetSourceName(), Strings.ReviewUnusedParameterName);
+        }
+
+        /// <summary>
+        /// GetCommonName: Retrieves the common name of this rule.
+        /// </summary>
+        /// <returns>The common name of this rule</returns>
+        public string GetCommonName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.ReviewUnusedParameterCommonName);
+        }
+
+        /// <summary>
+        /// GetDescription: Retrieves the description of this rule.
+        /// </summary>
+        /// <returns>The description of this rule</returns>
+        public string GetDescription()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.ReviewUnusedParameterDescription);
+        }
+
+        /// <summary>
+        /// GetSourceType: Retrieves the type of the rule, builtin, managed or module.
+        /// </summary>
+        public SourceType GetSourceType()
+        {
+            return SourceType.Builtin;
+        }
+
+        /// <summary>
+        /// GetSeverity: Retrieves the severity of the rule: error, warning of information.
+        /// </summary>
+        /// <returns></returns>
+        public RuleSeverity GetSeverity()
+        {
+            return RuleSeverity.Warning;
+        }
+
+        /// <summary>
+        /// GetSourceName: Retrieves the module/assembly name the rule is from.
+        /// </summary>
+        public string GetSourceName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.SourceName);
+        }
+    }
+}

Rules/Strings.Designer.cs

@@ -1104,4 +1104,16 @@
   <data name="UseProcessBlockForPipelineCommandName" xml:space="preserve">
     <value>UseProcessBlockForPipelineCommand</value>
   </data>
+  <data name="ReviewUnusedParameterCommonName" xml:space="preserve">
+    <value>ReviewUnusedParameter</value>
+  </data>
+  <data name="ReviewUnusedParameterDescription" xml:space="preserve">
+    <value>Ensure all parameters are used within the same script, scriptblock, or function where they are declared.</value>
+  </data>
+  <data name="ReviewUnusedParameterError" xml:space="preserve">
+    <value>The parameter {0} has been declared but not used. </value>
+  </data>
+  <data name="ReviewUnusedParameterName" xml:space="preserve">
+    <value>ReviewUnusedParameter</value>
+  </data>
 </root>

Rules/Strings.resx

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