Add Get-PSRuleHelp and online link #19 #147 #157

microsoft · May 28, 2019 · 1c471c1 · 1c471c1
1 parent 16c96bc
commit 1c471c1
Show file tree

Hide file tree

Showing 10 changed files with 485 additions and 18 deletions.
diff --git a/src/PSRule/Host/HostHelper.cs b/src/PSRule/Host/HostHelper.cs
@@ -20,6 +20,11 @@ public static IEnumerable<Rule> GetRule(RuleSource[] source, RuleFilter filter)
             return ToRule(GetLanguageBlock(sources: source), filter);
         }
 
+        public static RuleHelpInfo GetRuleHelp(RuleSource[] source, RuleFilter filter)
+        {
+            return ToRuleHelp(GetLanguageBlock(sources: source), filter);
+        }
+
         public static DependencyGraph<RuleBlock> GetRuleBlockGraph(RuleSource[] source, RuleFilter filter)
         {
             var builder = new DependencyGraphBuilder<RuleBlock>();
@@ -206,5 +211,33 @@ private static Rule[] ToRule(IEnumerable<ILanguageBlock> blocks, RuleFilter filt
 
             return results.Values.ToArray();
         }
+
+        private static RuleHelpInfo ToRuleHelp(IEnumerable<ILanguageBlock> blocks, RuleFilter filter)
+        {
+            // Index deployments by environment/name
+            var results = new Dictionary<string, RuleHelpInfo>(StringComparer.OrdinalIgnoreCase);
+
+            foreach (var block in blocks.OfType<RuleBlock>())
+            {
+                // Ignore deployment blocks that don't match
+                if (filter != null && !filter.Match(block))
+                {
+                    continue;
+                }
+
+                if (!results.ContainsKey(block.RuleId))
+                {
+                    results[block.RuleId] = new RuleHelpInfo
+                    {
+                        Name = block.RuleName,
+                        Synopsis = block.Description,
+                        Recommendation = block.Recommendation,
+                        Annotations = block.Annotations.ToHashtable()
+                    };
+                }
+            }
+
+            return results.Values.FirstOrDefault();
+        }
     }
 }
diff --git a/src/PSRule/PSRule.Format.ps1xml b/src/PSRule/PSRule.Format.ps1xml
@@ -1,5 +1,73 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <Configuration>
+  <Controls>
+    <Control>
+      <Name>Help-Name</Name>
+      <CustomControl>
+        <CustomEntries>
+          <CustomEntry>
+              <CustomItem>
+                <Text AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Name"/>
+                <NewLine />
+                <Frame>
+                  <LeftIndent>4</LeftIndent>
+                  <CustomItem>
+                    <ExpressionBinding>
+                      <PropertyName>NAME</PropertyName>
+                    </ExpressionBinding>
+                    <NewLine/>
+                  </CustomItem>
+                </Frame>
+              </CustomItem>
+            </CustomEntry>
+        </CustomEntries>
+      </CustomControl>
+    </Control>
+    <Control>
+      <Name>Help-Synopsis</Name>
+      <CustomControl>
+        <CustomEntries>
+          <CustomEntry>
+              <CustomItem>
+                <Text AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Synopsis"/>
+                <NewLine />
+                <Frame>
+                  <LeftIndent>4</LeftIndent>
+                  <CustomItem>
+                    <ExpressionBinding>
+                      <PropertyName>Synopsis</PropertyName>
+                    </ExpressionBinding>
+                    <NewLine/>
+                  </CustomItem>
+                </Frame>
+              </CustomItem>
+            </CustomEntry>
+        </CustomEntries>
+      </CustomControl>
+    </Control>
+    <Control>
+      <Name>Help-Recommendation</Name>
+      <CustomControl>
+        <CustomEntries>
+          <CustomEntry>
+              <CustomItem>
+                <Text AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Recommendation"/>
+                <NewLine />
+                <Frame>
+                  <LeftIndent>4</LeftIndent>
+                  <CustomItem>
+                    <ExpressionBinding>
+                      <PropertyName>Recommendation</PropertyName>
+                    </ExpressionBinding>
+                    <NewLine/>
+                  </CustomItem>
+                </Frame>
+              </CustomItem>
+            </CustomEntry>
+        </CustomEntries>
+      </CustomControl>
+    </Control>
+  </Controls>
   <ViewDefinitions>
     <View>
       <Name>PSRule.Rules.Rule</Name>
@@ -9,14 +77,14 @@
       <TableControl>
         <TableHeaders>
           <TableColumnHeader>
-            <Label>RuleName</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="RuleName"/>
             <Width>35</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Description</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Description"/>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>ModuleName</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="ModuleName"/>
           </TableColumnHeader>
         </TableHeaders>
         <TableRowEntries>
@@ -47,15 +115,15 @@
       <TableControl>
         <TableHeaders>
           <TableColumnHeader>
-            <Label>RuleName</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="RuleName"/>
             <Width>35</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Outcome</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Outcome"/>
             <Width>10</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Message</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Message"/>
           </TableColumnHeader>
         </TableHeaders>
         <TableRowEntries>
@@ -83,19 +151,19 @@
       <TableControl>
         <TableHeaders>
           <TableColumnHeader>
-            <Label>RuleName</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="RuleName"/>
             <Width>35</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Pass</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Pass"/>
             <Width>5</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Fail</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Fail"/>
             <Width>5</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Outcome</Label>
+            <Label AssemblyName="PSRule" BaseName="PSRule.Resources.FormatResources" ResourceId="Outcome"/>
           </TableColumnHeader>
         </TableHeaders>
         <TableRowEntries>
@@ -118,5 +186,38 @@
         </TableRowEntries>
       </TableControl>
     </View>
+    <View>
+      <Name>PSRule.Rules.RuleHelpInfo</Name>
+      <ViewSelectedBy>
+        <TypeName>PSRule.Rules.RuleHelpInfo</TypeName>
+      </ViewSelectedBy>
+      <CustomControl>
+         <CustomEntries>
+              <CustomEntry>
+                <CustomItem>
+                  <ExpressionBinding>
+                    <CustomControlName>Help-Name</CustomControlName>
+                  </ExpressionBinding>
+                  <Frame>
+                    <CustomItem>
+                      <NewLine />
+                      <ExpressionBinding>
+                        <CustomControlName>Help-Synopsis</CustomControlName>
+                      </ExpressionBinding>
+                      <Frame>
+                        <CustomItem>
+                          <NewLine />
+                          <ExpressionBinding>
+                            <CustomControlName>Help-Recommendation</CustomControlName>
+                          </ExpressionBinding>
+                        </CustomItem>
+                      </Frame>
+                    </CustomItem>
+                  </Frame>
+                </CustomItem>
+              </CustomEntry>
+            </CustomEntries>
+      </CustomControl>
+    </View>
   </ViewDefinitions>
 </Configuration>
diff --git a/src/PSRule/PSRule.psd1 b/src/PSRule/PSRule.psd1
@@ -76,6 +76,7 @@ FunctionsToExport = @(
     'Invoke-PSRule'
     'Test-PSRuleTarget'
     'Get-PSRule'
+    'Get-PSRuleHelp'
     'New-PSRuleOption'
     'Set-PSRuleOption'
     'AllOf'

diff --git a/src/PSRule/PSRule.psm1 b/src/PSRule/PSRule.psm1
@@ -436,6 +436,119 @@ function Get-PSRule {
     }
 }
 
+# .ExternalHelp PSRule-Help.xml
+function Get-PSRuleHelp {
+    [CmdletBinding()]
+    [OutputType([PSRule.Rules.RuleHelpInfo])]
+    param (
+        # A list of paths to check for rule definitions
+        [Parameter(Position = 0, Mandatory = $False)]
+        [Alias('p')]
+        [String]$Path = $PWD,
+
+        # Filter to rules with the following names
+        [Parameter(Mandatory = $True)]
+        [Alias('n')]
+        [String]$Name,
+
+        [Parameter(Mandatory = $False)]
+        [String]$Module,
+
+        [Parameter(Mandatory = $False)]
+        [String]$Culture,
+
+        [Parameter(Mandatory = $False)]
+        [Switch]$Online = $False
+    )
+
+    begin {
+        Write-Verbose -Message "[Get-PSRuleHelp]::BEGIN";
+
+        # Get parameter options, which will override options from other sources
+        $optionParams = @{ };
+
+        if ($PSBoundParameters.ContainsKey('Option')) {
+            $optionParams['Option'] =  $Option;
+        }
+
+        # Get an options object
+        $Option = New-PSRuleOption @optionParams;
+
+        # Discover scripts in the specified paths
+        $sourceParams = @{ };
+
+        if ($PSBoundParameters.ContainsKey('Path')) {
+            $sourceParams['Path'] = $Path;
+        }
+        if ($PSBoundParameters.ContainsKey('Module')) {
+            $sourceParams['Module'] = $Module;
+        }
+        if ($sourceParams.Count -eq 0) {
+            $sourceParams['Path'] = $Path;
+        }
+        if ($PSBoundParameters.ContainsKey('Culture')) {
+            $sourceParams['Culture'] = $Culture;
+        }
+        [PSRule.Rules.RuleSource[]]$sourceFiles = GetRuleScriptPath @sourceParams -Verbose:$VerbosePreference;
+
+        # Check that some matching script files were found
+        if ($Null -eq $sourceFiles) {
+            Write-Verbose -Message "[Get-PSRuleHelp] -- Could not find any .Rule.ps1 script files in the path";
+            return; # continue causes issues with Pester
+        }
+
+        Write-Verbose -Message "[Get-PSRuleHelp] -- Found $($sourceFiles.Length) script(s)";
+
+        $isDeviceGuard = IsDeviceGuardEnabled;
+
+        # If DeviceGuard is enabled, force a contrained execution environment
+        if ($isDeviceGuard) {
+            $Option.Execution.LanguageMode = [PSRule.Configuration.LanguageMode]::ConstrainedLanguage;
+        }
+
+        if ($PSBoundParameters.ContainsKey('Name')) {
+            $Option.Baseline.RuleName = $Name;
+        }
+
+        $builder = [PSRule.Pipeline.PipelineBuilder]::GetHelp().Configure($Option);
+        $builder.Source($sourceFiles);
+        $builder.UseCommandRuntime($PSCmdlet.CommandRuntime);
+        $builder.UseLoggingPreferences($ErrorActionPreference, $WarningPreference, $VerbosePreference, $InformationPreference);
+        $pipeline = $builder.Build();
+    }
+
+    process {
+        if ($Null -ne (Get-Variable -Name pipeline -ErrorAction SilentlyContinue)) {
+            try {
+                # Get matching rule help
+                $result = $pipeline.Process();
+
+                if ($Null -ne $result -and $Online) {
+                    $launchUri = $result.GetOnlineHelpUri();
+
+                    if ($Null -ne $launchUri) {
+                        LaunchOnlineHelp -Uri $launchUri -Verbose:$VerbosePreference;
+                    }
+                }
+                else {
+                    $result;
+                }
+            }
+            catch {
+                $pipeline.Dispose();
+                throw;
+            }
+        }
+    }
+
+    end {
+        if ($Null -ne (Get-Variable -Name pipeline -ErrorAction SilentlyContinue)) {
+            $pipeline.Dispose();
+        }
+        Write-Verbose -Message "[Get-PSRuleHelp]::END";
+    }
+}
+
 # .ExternalHelp PSRule-Help.xml
 function New-PSRuleOption {
     [CmdletBinding()]
@@ -1180,12 +1293,9 @@ function YamlContainsComments {
 }
 
 function IsDeviceGuardEnabled {
-
     [CmdletBinding()]
     [OutputType([System.Boolean])]
-    param (
-
-    )
+    param ()
 
     process {
 
@@ -1202,13 +1312,26 @@ function IsDeviceGuardEnabled {
     }
 }
 
-function InitEditorServices {
-
+function LaunchOnlineHelp {
     [CmdletBinding()]
+    [OutputType([void])]
     param (
-
+        [Parameter(Mandatory = $True)]
+        [System.Uri]$Uri
     )
 
+    process {
+        $launchProcess = New-Object -TypeName System.Diagnostics.Process;
+        $launchProcess.StartInfo.FileName = $Uri.OriginalString;
+        $launchProcess.StartInfo.UseShellExecute = $True;
+        $Null = $launchProcess.Start();
+    }
+}
+
+function InitEditorServices {
+    [CmdletBinding()]
+    param ()
+
     process {
         if ($Null -ne (Get-Variable -Name psEditor -ErrorAction Ignore)) {
             # Export keywords
@@ -1255,6 +1378,7 @@ Export-ModuleMember -Function @(
     'Invoke-PSRule'
     'Test-PSRuleTarget'
     'Get-PSRule'
+    'Get-PSRuleHelp'
     'New-PSRuleOption'
     'Set-PSRuleOption'
 )