Merge pull request #772 from PowerShell/kapilmb/add-formatter

Add an Invoke-Formatter cmdlet to provide code formatting

Author: Kapil Borle

Engine/Commands/InvokeFormatterCommand.cs

@@ -0,0 +1,130 @@
+//
+// Copyright (c) Microsoft Corporation.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+
+using System;
+using System.Globalization;
+using System.Management.Automation;
+
+namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.Commands
+{
+    using PSSASettings = Microsoft.Windows.PowerShell.ScriptAnalyzer.Settings;
+
+    /// <summary>
+    /// A cmdlet to format a PowerShell script text.
+    /// </summary>
+    [Cmdlet(VerbsLifecycle.Invoke, "Formatter")]
+    public class InvokeFormatterCommand : PSCmdlet, IOutputWriter
+    {
+        private const string defaultSettingsPreset = "CodeFormatting";
+        private Settings defaultSettings;
+        private Settings inputSettings;
+
+        /// <summary>
+        /// The script text to be formated.
+        ///
+        /// *NOTE*: Unlike ScriptBlock parameter, the ScriptDefinition parameter require a string value.
+        /// </summary>
+        [ParameterAttribute(Mandatory = true)]
+        [ValidateNotNull]
+        public string ScriptDefinition { get; set; }
+
+        /// <summary>
+        /// A settings hashtable or a path to a PowerShell data file (.psd1) file that contains the settings.
+        /// </summary>
+        [Parameter(Mandatory = false)]
+        [ValidateNotNull]
+        public object Settings { get; set; }
+
+#if DEBUG
+        [Parameter(Mandatory = false)]
+        public Range Range { get; set; }
+
+        [Parameter(Mandatory = false, ParameterSetName = "NoRange")]
+        public int StartLineNumber { get; set; } = -1;
+        [Parameter(Mandatory = false, ParameterSetName = "NoRange")]
+        public int StartColumnNumber { get; set; } = -1;
+        [Parameter(Mandatory = false, ParameterSetName = "NoRange")]
+        public int EndLineNumber { get; set; } = -1;
+        [Parameter(Mandatory = false, ParameterSetName = "NoRange")]
+        public int EndColumnNumber { get; set; } = -1;
+
+        /// <summary>
+        /// Attaches to an instance of a .Net debugger
+        /// </summary>
+        [Parameter(Mandatory = false)]
+        public SwitchParameter AttachAndDebug
+        {
+            get { return attachAndDebug; }
+            set { attachAndDebug = value; }
+        }
+
+        private bool attachAndDebug = false;
+#endif
+
+        protected override void BeginProcessing()
+        {
+#if DEBUG
+            if (attachAndDebug)
+            {
+                if (System.Diagnostics.Debugger.IsAttached)
+                {
+                    System.Diagnostics.Debugger.Break();
+                }
+                else
+                {
+                    System.Diagnostics.Debugger.Launch();
+                }
+            }
+#endif
+
+            try
+            {
+                inputSettings = PSSASettings.Create(Settings, null, this);
+                if (inputSettings == null)
+                {
+                    inputSettings = new PSSASettings(
+                        defaultSettingsPreset,
+                        PSSASettings.GetSettingPresetFilePath);
+                }
+            }
+            catch
+            {
+                this.WriteWarning(String.Format(CultureInfo.CurrentCulture, Strings.SettingsNotParsable));
+                return;
+            }
+        }
+
+        protected override void ProcessRecord()
+        {
+            // todo add tests to check range formatting
+            string formattedScriptDefinition;
+#if DEBUG
+            var range = Range;
+            if (this.ParameterSetName.Equals("NoRange"))
+            {
+                range = new Range(StartLineNumber, StartColumnNumber, EndLineNumber, EndColumnNumber);
+            }
+
+            formattedScriptDefinition = Formatter.Format(ScriptDefinition, inputSettings, range, this);
+#endif // DEBUG
+
+            formattedScriptDefinition = Formatter.Format(ScriptDefinition, inputSettings, null, this);
+            this.WriteObject(formattedScriptDefinition);
+        }
+
+        private void ValidateInputSettings()
+        {
+            // todo implement this
+            return;
+        }
+    }
+}

Engine/Commands/InvokeScriptAnalyzerCommand.cs

@@ -30,12 +30,14 @@
 
 namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.Commands
 {
+    using PSSASettings = Microsoft.Windows.PowerShell.ScriptAnalyzer.Settings;
+
     /// <summary>
     /// InvokeScriptAnalyzerCommand: Cmdlet to statically check PowerShell scripts.
     /// </summary>
     [Cmdlet(VerbsLifecycle.Invoke,
         "ScriptAnalyzer",
-        DefaultParameterSetName="File",
+        DefaultParameterSetName = "File",
         HelpUri = "http://go.microsoft.com/fwlink/?LinkId=525914")]
     public class InvokeScriptAnalyzerCommand : PSCmdlet, IOutputWriter
     {
@@ -208,6 +210,9 @@ public SwitchParameter SaveDscDependency
 #endif // !PSV3
 
 #if DEBUG
+        /// <summary>
+        /// Attaches to an instance of a .Net debugger
+        /// </summary>
         [Parameter(Mandatory = false)]
         public SwitchParameter AttachAndDebug
         {
@@ -260,64 +265,22 @@ protected override void BeginProcessing()
                 ProcessPath();
             }
 
-            object settingsFound;
-            var settingsMode = PowerShell.ScriptAnalyzer.Settings.FindSettingsMode(
-                this.settings,
-                processedPaths == null || processedPaths.Count == 0 ? null : processedPaths[0],
-                out settingsFound);
-
-            switch (settingsMode)
-            {
-                case SettingsMode.Auto:
-                    this.WriteVerbose(
-                        String.Format(
-                            CultureInfo.CurrentCulture,
-                            Strings.SettingsNotProvided,
-                            path));
-                    this.WriteVerbose(
-                        String.Format(
-                            CultureInfo.CurrentCulture,
-                            Strings.SettingsAutoDiscovered,
-                            (string)settingsFound));
-                    break;
-
-                case SettingsMode.Preset:
-                case SettingsMode.File:
-                    this.WriteVerbose(
-                        String.Format(
-                            CultureInfo.CurrentCulture,
-                            Strings.SettingsUsingFile,
-                            (string)settingsFound));
-                    break;
-
-                case SettingsMode.Hashtable:
-                    this.WriteVerbose(
-                        String.Format(
-                            CultureInfo.CurrentCulture,
-                            Strings.SettingsUsingHashtable));
-                    break;
-
-                default: // case SettingsMode.None
-                    this.WriteVerbose(
-                        String.Format(
-                            CultureInfo.CurrentCulture,
-                            Strings.SettingsCannotFindFile));
-                    break;
-            }
-
-            if (settingsMode != SettingsMode.None)
+            try
             {
-                try
+                var settingsObj = PSSASettings.Create(
+                    settings,
+                    processedPaths == null || processedPaths.Count == 0 ? null : processedPaths[0],
+                    this);
+                if (settingsObj != null)
                 {
-                    var settingsObj = new Settings(settingsFound);
                     ScriptAnalyzer.Instance.UpdateSettings(settingsObj);
                 }
-                catch
-                {
-                        this.WriteWarning(String.Format(CultureInfo.CurrentCulture, Strings.SettingsNotParsable));
-                        stopProcessing = true;
-                        return;
-                }
+            }
+            catch
+            {
+                this.WriteWarning(String.Format(CultureInfo.CurrentCulture, Strings.SettingsNotParsable));
+                stopProcessing = true;
+                return;
             }
 
             ScriptAnalyzer.Instance.Initialize(

Engine/EditableText.cs

@@ -100,7 +100,8 @@ public EditableText ApplyEdit(TextEdit textEdit)
                 currentLineNumber++;
             }
 
-            return new EditableText(String.Join(NewLine, lines));
+            // returning self allows us to chain ApplyEdit calls.
+            return this;
         }
 
         // TODO Add a method that takes multiple edits, checks if they are unique and applies them.

Engine/Formatter.cs

@@ -0,0 +1,80 @@
+using System;
+using System.Collections;
+using System.Management.Automation;
+
+namespace Microsoft.Windows.PowerShell.ScriptAnalyzer
+{
+    /// <summary>
+    /// A class to provide code formatting capability.
+    /// </summary>
+    public class Formatter
+    {
+        /// <summary>
+        /// Format a powershell script.
+        /// </summary>
+        /// <param name="scriptDefinition">A string representing a powershell script.</param>
+        /// <param name="settings">Settings to be used for formatting</param>
+        /// <param name="range">The range in which formatting should take place.</param>
+        /// <param name="cmdlet">The cmdlet object that calls this method.</param>
+        /// <returns></returns>
+        public static string Format<TCmdlet>(
+            string scriptDefinition,
+            Settings settings,
+            Range range,
+            TCmdlet cmdlet) where TCmdlet : PSCmdlet, IOutputWriter
+        {
+            // todo implement notnull attribute for such a check
+            ValidateNotNull(scriptDefinition, "scriptDefinition");
+            ValidateNotNull(settings, "settings");
+            ValidateNotNull(cmdlet, "cmdlet");
+
+            Helper.Instance = new Helper(cmdlet.SessionState.InvokeCommand, cmdlet);
+            Helper.Instance.Initialize();
+
+            var ruleOrder = new string[]
+            {
+                "PSPlaceCloseBrace",
+                "PSPlaceOpenBrace",
+                "PSUseConsistentWhitespace",
+                "PSUseConsistentIndentation",
+                "PSAlignAssignmentStatement"
+            };
+
+            var text = new EditableText(scriptDefinition);
+            foreach (var rule in ruleOrder)
+            {
+                if (!settings.RuleArguments.ContainsKey(rule))
+                {
+                    continue;
+                }
+
+                var currentSettings = GetCurrentSettings(settings, rule);
+                ScriptAnalyzer.Instance.UpdateSettings(currentSettings);
+                ScriptAnalyzer.Instance.Initialize(cmdlet, null, null, null, null, true, false);
+
+                Range updatedRange;
+                text = ScriptAnalyzer.Instance.Fix(text, range, out updatedRange);
+                range = updatedRange;
+            }
+
+            return text.ToString();
+        }
+
+        private static void ValidateNotNull<T>(T obj, string name)
+        {
+            if (obj == null)
+            {
+                throw new ArgumentNullException(name);
+            }
+        }
+
+        private static Settings GetCurrentSettings(Settings settings, string rule)
+        {
+            return new Settings(new Hashtable()
+            {
+                {"IncludeRules", new string[] {rule}},
+                {"Rules", new Hashtable() { { rule, new Hashtable(settings.RuleArguments[rule]) } } }
+            });
+        }
+    }
+}

Engine/PSScriptAnalyzer.psd1

@@ -65,7 +65,7 @@ FormatsToProcess = @('ScriptAnalyzer.format.ps1xml')
 FunctionsToExport = @()
 
 # Cmdlets to export from this module
-CmdletsToExport = @('Get-ScriptAnalyzerRule','Invoke-ScriptAnalyzer')
+CmdletsToExport = @('Get-ScriptAnalyzerRule', 'Invoke-ScriptAnalyzer', 'Invoke-Formatter')
 
 # Variables to export from this module
 VariablesToExport = @()

Engine/PSScriptAnalyzer.psm1

@@ -14,8 +14,7 @@ $binaryModuleRoot = $PSModuleRoot
 if (($PSVersionTable.Keys -contains "PSEdition") -and ($PSVersionTable.PSEdition -ne 'Desktop')) {
     $binaryModuleRoot = Join-Path -Path $PSModuleRoot -ChildPath 'coreclr'
 }
-else
-{
+else {
     if ($PSVersionTable.PSVersion -lt [Version]'5.0') {
         $binaryModuleRoot = Join-Path -Path $PSModuleRoot -ChildPath 'PSv3'
     }
@@ -29,18 +28,23 @@ $PSModule.OnRemove = {
     Remove-Module -ModuleInfo $binaryModule
 }
 
-if (Get-Command Register-ArgumentCompleter -ErrorAction Ignore)
-{
-    Register-ArgumentCompleter -CommandName 'Invoke-ScriptAnalyzer' -ParameterName 'Settings' -ScriptBlock {
+if (Get-Command Register-ArgumentCompleter -ErrorAction Ignore) {
+    $settingPresetCompleter = {
         param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParmeter)
 
         [Microsoft.Windows.PowerShell.ScriptAnalyzer.Settings]::GetSettingPresets() | `
             Where-Object {$_ -like "$wordToComplete*"} | `
             ForEach-Object { New-Object System.Management.Automation.CompletionResult $_ }
     }
 
-    Function RuleNameCompleter
-    {
+    @('Invoke-ScriptAnalyzer', 'Invoke-Formatter') | ForEach-Object {
+        Register-ArgumentCompleter -CommandName $_ `
+            -ParameterName 'Settings' `
+            -ScriptBlock $settingPresetCompleter
+
+    }
+
+    Function RuleNameCompleter {
         param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParmeter)
 
         Get-ScriptAnalyzerRule *$wordToComplete* | `
@@ -50,4 +54,4 @@ if (Get-Command Register-ArgumentCompleter -ErrorAction Ignore)
     Register-ArgumentCompleter -CommandName 'Invoke-ScriptAnalyzer' -ParameterName 'IncludeRule' -ScriptBlock $Function:RuleNameCompleter
     Register-ArgumentCompleter -CommandName 'Invoke-ScriptAnalyzer' -ParameterName 'ExcludeRule' -ScriptBlock $Function:RuleNameCompleter
     Register-ArgumentCompleter -CommandName 'Get-ScriptAnalyzerRule' -ParameterName 'Name' -ScriptBlock $Function:RuleNameCompleter
-}
+}