Resolve merge conflict

Author: Kapil Borle

Engine/Generic/CorrectionExtent.cs

@@ -0,0 +1,144 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Management.Automation.Language;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic
+{
+    public class CorrectionExtent
+    {
+        public int EndColumnNumber
+        {
+            get
+            {
+                return endColumnNumber;
+            }
+        }
+
+        public int EndLineNumber
+        {
+            get
+            {
+                return endLineNumber;
+            }
+        }
+
+        public string File
+        {
+            get
+            {
+                return file;
+            }
+        }
+
+        public int StartColumnNumber
+        {
+            get
+            {
+                return startColumnNumber;
+            }
+        }
+
+        public int StartLineNumber
+        {
+            get
+            {
+                return startLineNumber;
+            }
+        }
+
+        public string Text
+        {
+            get
+            {
+                return text;
+            }
+        }
+
+        public string Description
+        {
+            get
+            {
+                return description;
+            }
+        }
+
+        private string file;
+        private int startLineNumber;
+        private int endLineNumber;
+        private int startColumnNumber;
+        private int endColumnNumber;
+        private string text;
+        private string description;
+    
+        public CorrectionExtent(
+            int startLineNumber, 
+            int endLineNumber, 
+            int startColumnNumber, 
+            int endColumnNumber, 
+            string text, 
+            string file) 
+            : this(
+                  startLineNumber, 
+                  endLineNumber,
+                  startColumnNumber,
+                  endColumnNumber,
+                  text,
+                  file,
+                  null)
+        {
+        }
+
+        public CorrectionExtent(
+            int startLineNumber, 
+            int endLineNumber, 
+            int startColumnNumber, 
+            int endColumnNumber, 
+            string text, 
+            string file,
+            string description)
+        {
+            this.startLineNumber = startLineNumber;
+            this.endLineNumber = endLineNumber;
+            this.startColumnNumber = startColumnNumber;
+            this.endColumnNumber = endColumnNumber;
+            this.file = file;
+            this.text = text;
+            this.description = description;
+            ThrowIfInvalidArguments();
+        }
+
+
+
+        private void ThrowIfInvalidArguments()
+        {
+            ThrowIfNull<string>(file, "filename");
+            ThrowIfNull<string>(text, "text");
+            ThrowIfDecreasing(startLineNumber, endLineNumber, "start line number cannot be less than end line number");            
+            if (startLineNumber == endLineNumber)
+            {
+                ThrowIfDecreasing(StartColumnNumber, endColumnNumber, "start column number cannot be less than end column number for a one line extent");
+            }
+        }
+
+        private void ThrowIfDecreasing(int start, int end, string message)
+        {
+            if (start > end)
+            {
+                throw new ArgumentException(message);
+            }
+        }
+
+        private void ThrowIfNull<T>(T arg, string argName)
+        {
+            if (arg == null)
+            {
+                throw new ArgumentNullException(argName);
+            }
+        }
+
+    }
+}

Engine/Generic/DiagnosticRecord.cs

@@ -10,7 +10,10 @@
 // THE SOFTWARE.
 //
 
+
+
 using System;
+using System.Collections.Generic;
 using System.Management.Automation.Language;
 
 namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic
@@ -27,6 +30,7 @@ public class DiagnosticRecord
         private DiagnosticSeverity severity;
         private string scriptPath;
         private string ruleSuppressionId;
+        private List<CorrectionExtent> suggestedCorrections;
 
         /// <summary>
         /// Represents a string from the rule about why this diagnostic was created.
@@ -90,43 +94,43 @@ public string RuleSuppressionID
             set { ruleSuppressionId = value; }
         }
 
+        /// <summary>
+        /// Returns suggested correction
+        /// return value can be null
+        /// </summary>
+        public IEnumerable<CorrectionExtent> SuggestedCorrections
+        {
+            get { return suggestedCorrections;  }            
+        }
+
         /// <summary>
         /// DiagnosticRecord: The constructor for DiagnosticRecord class.
         /// </summary>
         public DiagnosticRecord()
         {
 
         }
-
+        
         /// <summary>
-        /// DiagnosticRecord: The constructor for DiagnosticRecord class.
+        /// DiagnosticRecord: The constructor for DiagnosticRecord class that takes in suggestedCorrection
         /// </summary>
         /// <param name="message">A string about why this diagnostic was created</param>
         /// <param name="extent">The place in the script this diagnostic refers to</param>
         /// <param name="ruleName">The name of the rule that created this diagnostic</param>
         /// <param name="severity">The severity of this diagnostic</param>
-        /// <param name="scriptName">The path of the script file being analyzed</param>
-        public DiagnosticRecord(string message, IScriptExtent extent, string ruleName, DiagnosticSeverity severity, string scriptPath, string ruleId = null)
+        /// <param name="scriptPath">The full path of the script file being analyzed</param>
+        /// <param name="suggestedCorrections">The correction suggested by the rule to replace the extent text</param>
+        public DiagnosticRecord(string message, IScriptExtent extent, string ruleName, DiagnosticSeverity severity, string scriptPath, string ruleId = null, List<CorrectionExtent> suggestedCorrections = null)
         {
             Message  = message;
             RuleName = ruleName;
             Extent   = extent;
             Severity = severity;
             ScriptPath = scriptPath;
-            ruleSuppressionId = ruleId;
+            RuleSuppressionID = ruleId;
+            this.suggestedCorrections = suggestedCorrections;
         }
 
-        /// <summary>
-        /// Copy Constructor
-        /// </summary>
-        /// <param name="record"></param>
-        public DiagnosticRecord(DiagnosticRecord diagnosticRecord)
-        {
-            if (diagnosticRecord == null)
-            {
-                throw new ArgumentNullException("diagnosticRecord");
-            }
-        }
     }
 
 

Engine/Helper.cs

@@ -19,6 +19,7 @@
 using System.Management.Automation.Language;
 using System.Globalization;
 using Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic;
+using System.Management.Automation.Runspaces;
 
 namespace Microsoft.Windows.PowerShell.ScriptAnalyzer
 {
@@ -104,14 +105,14 @@ internal set
         private string[] functionScopes = new string[] { "global:", "local:", "script:", "private:"};
 
         private string[] variableScopes = new string[] { "global:", "local:", "script:", "private:", "variable:", ":"};
-
         #endregion
 
         /// <summary>
         /// Initializes the Helper class.
         /// </summary>
         private Helper()
         {
+                                    
         }
 
         /// <summary>
@@ -229,6 +230,61 @@ public bool IsDscResourceModule(string filePath)
 
             return false;
         }
+        
+        /// <summary>
+        /// Gets the module manifest
+        /// </summary>
+        /// <param name="filePath"></param>
+        /// <param name="errorRecord"></param>
+        /// <returns>Returns a object of type PSModuleInfo</returns>
+        public PSModuleInfo GetModuleManifest(string filePath, out IEnumerable<ErrorRecord> errorRecord)
+        {
+            errorRecord = null;
+            PSModuleInfo psModuleInfo = null;
+            Collection<PSObject> psObj = null;
+            var ps = System.Management.Automation.PowerShell.Create();
+            try
+            {
+                ps.AddCommand("Test-ModuleManifest");
+                ps.AddParameter("Path", filePath);
+                ps.AddParameter("WarningAction", ActionPreference.SilentlyContinue);
+                psObj = ps.Invoke();
+            }
+            catch (CmdletInvocationException e)
+            {
+                // Invoking Test-ModuleManifest on a module manifest that doesn't have all the valid keys
+                // throws a NullReferenceException. This is probably a bug in Test-ModuleManifest and hence
+                // we consume it to allow execution of the of this method.
+                if (e.InnerException == null || e.InnerException.GetType() != typeof(System.NullReferenceException))
+                {
+                    throw;
+                }
+            }
+            if (ps.HadErrors && ps.Streams != null && ps.Streams.Error != null)
+            {
+                var errorRecordArr = new ErrorRecord[ps.Streams.Error.Count];
+                ps.Streams.Error.CopyTo(errorRecordArr, 0);
+                errorRecord = errorRecordArr;
+            }
+            if (psObj != null && psObj.Any() && psObj[0] != null)
+            {
+                psModuleInfo = psObj[0].ImmediateBaseObject as PSModuleInfo;
+            }
+            ps.Dispose();
+            return psModuleInfo;
+        }
+
+        /// <summary>
+        /// Checks if the error record is MissingMemberException
+        /// </summary>
+        /// <param name="errorRecord"></param>
+        /// <returns>Returns a boolean value indicating the presence of MissingMemberException</returns>
+        public static bool IsMissingManifestMemberException(ErrorRecord errorRecord)
+        {
+            return errorRecord.CategoryInfo != null
+                && errorRecord.CategoryInfo.Category == ErrorCategory.ResourceUnavailable
+                && string.Equals("MissingMemberException", errorRecord.CategoryInfo.Reason, StringComparison.OrdinalIgnoreCase);
+        }
 
         /// <summary>
         /// Get the list of exported function by analyzing the ast
@@ -1328,7 +1384,7 @@ public static string[] ProcessCustomRulePaths(string[] rulePaths, SessionState s
             return outPaths.ToArray();
 
         }
-
+        
         /// <summary>
         /// Check if the function name starts with one of potentailly state changing verbs
         /// </summary>
@@ -1458,7 +1514,7 @@ public bool GetNamedArgumentAttributeValue(NamedAttributeArgumentAst namedAttrib
             return false;
         }
 
-        #endregion
+        #endregion Methods
     }
 
 

Engine/ScriptAnalyzerEngine.csproj

@@ -71,6 +71,7 @@
     <Compile Include="Generic\AvoidCmdletGeneric.cs" />
     <Compile Include="Generic\AvoidParameterGeneric.cs" />
     <Compile Include="Generic\ModuleDependencyHandler.cs" />
+    <Compile Include="Generic\CorrectionExtent.cs" />
     <Compile Include="Generic\SuppressedRecord.cs" />
     <Compile Include="Generic\DiagnosticRecord.cs" />
     <Compile Include="Generic\ExternalRule.cs" />

Engine/about_PSScriptAnalyzer.help.txt

@@ -183,6 +183,47 @@ RULE SUPPRESSSION
                                                                Target="*")]
             param() 
         }
+
+VIOLATION CORRECTION
+
+Most violations can be fixed by replacing the violation causing content with the correct alternative. In an attempt to provide the user with the ability to correct the violation we provide a property - `SuggestedCorrections`, in each DiagnosticRecord instance. This property contains the information needed to rectify the violation. For example, consider a script `C:\tmp\test.ps1` with the following content.
+
+PS> Get-Content C:\tmp\test.ps1
+gci C:\
+
+Invoking PSScriptAnalyzer on the file gives the following output. 
+
+PS>$diagnosticRecord = Invoke-ScriptAnalyzer -Path C:\tmp\test.p1
+PS>$diagnosticRecord | select SuggestedCorrections | Format-Custom
+
+class DiagnosticRecord
+{
+  SuggestedCorrections =
+    [
+      class CorrectionExtent
+      {
+        EndColumnNumber = 4
+        EndLineNumber = 1
+        File = C:\Users\kabawany\tmp\test3.ps1
+        StartColumnNumber = 1
+        StartLineNumber = 1
+        Text = Get-ChildItem
+        Description = Replace gci with Get-ChildItem
+      }
+    ]
+
+}
+
+The *LineNumber and *ColumnNumber properties give the region of the script that can be replaced by the contents of Text property, i.e., replace gci with Get-ChildItem.
+
+The main motivation behind having SuggestedCorrections is to enable quick-fix like scenarios in editors like VSCode, Sublime, etc. At present, we provide valid SuggestedCorrection only for the following rules, while gradually adding this feature to more rules. 
+
+  * AvoidAlias.cs 
+  * AvoidUsingPlainTextForPassword.cs
+  * MisleadingBacktick.cs
+  * MissingModuleManifestField.cs
+  * UseToExportFieldsInManifest.cs
+
 
 EXTENSIBILITY