Merge pull request #758 from PowerShell/kapilmb/use-should-process-rule

Add UseSupportsShouldProcess rule

Author: Kapil Borle

Engine/EditableText.cs

@@ -0,0 +1,168 @@
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Management.Automation.Language;
+using System.Text;
+using Microsoft.Windows.PowerShell.ScriptAnalyzer.Extensions;
+
+namespace Microsoft.Windows.PowerShell.ScriptAnalyzer
+{
+    /// <summary>
+    /// A class to represent text to which `TextEdit`s can be applied.
+    /// </summary>
+    public class EditableText
+    {
+        private TextLines lines { get; set; }
+
+        /// <summary>
+        /// The text that is available for editing.
+        /// </summary>
+        public string Text { get { return String.Join(NewLine, lines); } }
+
+        /// <summary>
+        /// The lines in the Text.
+        /// </summary>
+        public string[] Lines { get { return lines.ToArray(); } }
+
+        /// <summary>
+        /// The new line character in the Text.
+        /// </summary>
+        public string NewLine { get; private set; }
+
+        /// <summary>
+        /// Construct an EditableText type object.
+        /// </summary>
+        /// <param name="text"></param>
+        public EditableText(string text)
+        {
+            if (text == null)
+            {
+                throw new ArgumentNullException(nameof(text));
+            }
+
+            string[] lines;
+            NewLine = GetNewLineCharacters(text, out lines);
+            this.lines = new TextLines(lines);
+        }
+
+        /// <summary>
+        /// Apply edits defined by a TextEdit object to Text.
+        /// </summary>
+        /// <param name="textEdit">A TextEdit object that encapsulates the text and the range that need to be replaced.</param>
+        /// <returns>An editable object which contains the supplied edit.</returns>
+        public EditableText ApplyEdit(TextEdit textEdit)
+        {
+            ValidateTextEdit(textEdit);
+
+            var editLines = textEdit.Lines;
+
+            // Get the first fragment of the first line
+            string firstLineFragment =
+                lines[textEdit.StartLineNumber - 1]
+                    .Substring(0, textEdit.StartColumnNumber - 1);
+
+            // Get the last fragment of the last line
+            string endLine = lines[textEdit.EndLineNumber - 1];
+            string lastLineFragment =
+                endLine.Substring(
+                    textEdit.EndColumnNumber - 1,
+                    lines[textEdit.EndLineNumber - 1].Length - textEdit.EndColumnNumber + 1);
+
+            // Remove the old lines
+            for (int i = 0; i <= textEdit.EndLineNumber - textEdit.StartLineNumber; i++)
+            {
+                lines.RemoveAt(textEdit.StartLineNumber - 1);
+            }
+
+            // Build and insert the new lines
+            int currentLineNumber = textEdit.StartLineNumber;
+            for (int changeIndex = 0; changeIndex < editLines.Length; changeIndex++)
+            {
+                // Since we split the lines above using \n, make sure to
+                // trim the ending \r's off as well.
+                string finalLine = editLines[changeIndex].TrimEnd('\r');
+
+                // Should we add first or last line fragments?
+                if (changeIndex == 0)
+                {
+                    // Append the first line fragment
+                    finalLine = firstLineFragment + finalLine;
+                }
+                if (changeIndex == editLines.Length - 1)
+                {
+                    // Append the last line fragment
+                    finalLine = finalLine + lastLineFragment;
+                }
+
+                lines.Insert(currentLineNumber - 1, finalLine);
+                currentLineNumber++;
+            }
+
+            return new EditableText(String.Join(NewLine, lines));
+        }
+
+        // TODO Add a method that takes multiple edits, checks if they are unique and applies them.
+
+        public override string ToString()
+        {
+            return Text;
+        }
+
+        private void ValidateTextEdit(TextEdit textEdit)
+        {
+            if (textEdit == null)
+            {
+                throw new NullReferenceException(nameof(textEdit));
+            }
+
+            ValidateTextEditExtent(textEdit);
+        }
+
+        private void ValidateTextEditExtent(TextEdit textEdit)
+        {
+            if (textEdit.StartLineNumber > Lines.Length
+                || textEdit.EndLineNumber > Lines.Length
+                || textEdit.StartColumnNumber > Lines[textEdit.StartLineNumber - 1].Length
+                || textEdit.EndColumnNumber > Lines[textEdit.EndLineNumber - 1].Length + 1)
+            {
+                throw new ArgumentException(String.Format(
+                    CultureInfo.CurrentCulture,
+                    Strings.EditableTextRangeIsNotContained));
+            }
+        }
+
+        private static string GetNewLineCharacters(string text, out string[] lines)
+        {
+            int numNewLineChars = GetNumNewLineCharacters(text, out lines);
+            if (lines.Length == 1)
+            {
+                return Environment.NewLine;
+            }
+
+            return text.Substring(lines[0].Length, numNewLineChars);
+        }
+
+        private static int GetNumNewLineCharacters(string text, out string[] lines)
+        {
+            lines = text.GetLines().ToArray();
+            if (lines.Length == 1)
+            {
+                return Environment.NewLine.Length;
+            }
+
+            var charsInLines = lines.Sum(line => line.Length);
+            var numCharDiff = text.Length - charsInLines;
+            int remainder = numCharDiff % (lines.Length - 1);
+            if (remainder != 0)
+            {
+                throw new ArgumentException(
+                    String.Format(CultureInfo.CurrentCulture, Strings.EditableTextInvalidLineEnding),
+                    nameof(text));
+            }
+
+            return numCharDiff / (lines.Length - 1);
+        }
+    }
+}

Engine/Extensions.cs

@@ -0,0 +1,155 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Management.Automation.Language;
+
+namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.Extensions
+{
+    public static class Extensions
+    {
+        /// <summary>
+        /// Return the lines in a text string.
+        /// </summary>
+        /// <param name="text">Text string to be split around new lines.</param>
+        /// <returns></returns>
+        public static IEnumerable<string> GetLines(this string text)
+        {
+            return text.Split('\n').Select(line => line.TrimEnd('\r'));
+        }
+
+        /// <summary>
+        /// Converts IScriptExtent to Range
+        /// </summary>
+        public static Range ToRange(this IScriptExtent extent)
+        {
+            return new Range(
+                 extent.StartLineNumber,
+                 extent.StartColumnNumber,
+                 extent.EndLineNumber,
+                 extent.EndColumnNumber);
+        }
+
+        /// <summary>
+        /// Get the parameter Asts from a function definition Ast.
+        ///
+        /// If not parameters are found, return null.
+        /// </summary>
+        /// <param name="paramBlockAst">If a parameter block is present, set this argument's value to the parameter block.</param>
+        /// <returns></returns>
+        public static IEnumerable<ParameterAst> GetParameterAsts(
+            this FunctionDefinitionAst functionDefinitionAst,
+            out ParamBlockAst paramBlockAst)
+        {
+            paramBlockAst = null;
+            if (functionDefinitionAst.Parameters != null)
+            {
+                return functionDefinitionAst.Parameters;
+            }
+            else if (functionDefinitionAst.Body.ParamBlock?.Parameters != null)
+            {
+                paramBlockAst = functionDefinitionAst.Body.ParamBlock;
+                return functionDefinitionAst.Body.ParamBlock.Parameters;
+            }
+
+            return null;
+        }
+
+        /// <summary>
+        /// Get the CmdletBinding attribute ast
+        /// </summary>
+        /// <param name="attributeAsts"></param>
+        /// <returns>Returns CmdletBinding attribute ast if it exists, otherwise returns null</returns>
+        public static AttributeAst GetCmdletBindingAttributeAst(this ParamBlockAst paramBlockAst)
+        {
+            var attributeAsts = paramBlockAst.Attributes;
+            if (attributeAsts == null)
+            {
+                return null;
+            }
+
+            foreach (var attributeAst in attributeAsts)
+            {
+                if (attributeAst != null && attributeAst.IsCmdletBindingAttributeAst())
+                {
+                    return attributeAst;
+                }
+            }
+
+            return null;
+        }
+
+        /// <summary>
+        /// Check if an attribute Ast is of CmdletBindingAttribute type.
+        /// </summary>
+        public static bool IsCmdletBindingAttributeAst(this AttributeAst attributeAst)
+        {
+            return attributeAst.TypeName.GetReflectionAttributeType() == typeof(CmdletBindingAttribute);
+        }
+
+        /// <summary>
+        /// Given a CmdletBinding attribute ast, return the SupportsShouldProcess argument Ast.
+        ///
+        /// If no SupportsShouldProcess argument is found, return null.
+        /// </summary>
+        public static NamedAttributeArgumentAst GetSupportsShouldProcessAst(this AttributeAst attributeAst)
+        {
+            if (!attributeAst.IsCmdletBindingAttributeAst()
+                || attributeAst.NamedArguments == null)
+            {
+                return null;
+            }
+
+            foreach (var namedAttrAst in attributeAst.NamedArguments)
+            {
+                if (namedAttrAst != null
+                    && namedAttrAst.ArgumentName.Equals(
+                        "SupportsShouldProcess",
+                        StringComparison.OrdinalIgnoreCase))
+                {
+                    return namedAttrAst;
+                }
+            }
+
+            return null;
+        }
+
+        /// <summary>
+        /// Return the boolean value of a named attribute argument.
+        /// </summary>
+        /// <param name="argumentAst">The ast of the argument's value</param>
+        public static bool GetValue(this NamedAttributeArgumentAst attrAst, out ExpressionAst argumentAst)
+        {
+            argumentAst = null;
+            if (attrAst.ExpressionOmitted)
+            {
+                return true;
+            }
+
+            var varExpAst = attrAst.Argument as VariableExpressionAst;
+            argumentAst = attrAst.Argument;
+            if (varExpAst == null)
+            {
+                var constExpAst = attrAst.Argument as ConstantExpressionAst;
+                if (constExpAst == null)
+                {
+                    return false;
+                }
+
+                bool constExpVal;
+                if (LanguagePrimitives.TryConvertTo(constExpAst.Value, out constExpVal))
+                {
+                    return constExpVal;
+                }
+            }
+            else
+            {
+                return varExpAst.VariablePath.UserPath.Equals(
+                    bool.TrueString,
+                    StringComparison.OrdinalIgnoreCase);
+            }
+
+            return false;
+        }
+    }
+}