Add annotations and import markdown #148 #18

microsoft · May 27, 2019 · 16c96bc · 16c96bc
1 parent dd34fdd
commit 16c96bc
Show file tree

Hide file tree

Showing 37 changed files with 2,641 additions and 74 deletions.
diff --git a/PSRule.build.ps1 b/PSRule.build.ps1
@@ -60,7 +60,7 @@ function CopyModuleFiles {
 task BuildDotNet {
     exec {
         # Build library
-        dotnet publish src/PSRule -c $Configuration -f netstandard2.0 -o $(Join-Path -Path $PWD -ChildPath out/modules/PSRule/core)
+        dotnet publish src/PSRule -c $Configuration -f netstandard2.0 -o $(Join-Path -Path $PWD -ChildPath out/modules/PSRule)
     }
 }
 

diff --git a/docs/commands/PSRule/en-US/Get-PSRule.md b/docs/commands/PSRule/en-US/Get-PSRule.md
@@ -15,7 +15,7 @@ Get a list of rule definitions.
 
 ```text
 Get-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]
- [-Module <String[]>] [-ListAvailable] [<CommonParameters>]
+ [-Module <String[]>] [-ListAvailable] [-Culture <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -148,6 +148,26 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/commands/PSRule/en-US/Invoke-PSRule.md b/docs/commands/PSRule/en-US/Invoke-PSRule.md
@@ -18,15 +18,17 @@ Evaluate objects against matching rules.
 ```text
 Invoke-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>
  [-Outcome <RuleOutcome>] [-Option <PSRuleOption>] [-As <ResultFormat>] [-Format <InputFormat>]
- [-ObjectPath <String>] [-Module <String[]>] [-OutputFormat <OutputFormat>] [<CommonParameters>]
+ [-ObjectPath <String>] [-Module <String[]>] [-OutputFormat <OutputFormat>] [-Culture <String>]
+ [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
 Invoke-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Outcome <RuleOutcome>]
  [-Option <PSRuleOption>] [-As <ResultFormat>] [-Format <InputFormat>] [-ObjectPath <String>]
- [-Module <String[]>] [-OutputFormat <OutputFormat>] -InputPath <String[]> [<CommonParameters>]
+ [-Module <String[]>] [-OutputFormat <OutputFormat>] -InputPath <String[]> [-Culture <String>]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -330,6 +332,26 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/commands/PSRule/en-US/Test-PSRuleTarget.md b/docs/commands/PSRule/en-US/Test-PSRuleTarget.md
@@ -18,14 +18,15 @@ Pass or fail objects against matching rules.
 ```text
 Test-PSRuleTarget [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>
  [-Option <PSRuleOption>] [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>]
- [<CommonParameters>]
+ [-Culture <String>] [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
 Test-PSRuleTarget [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]
- [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>] -InputPath <String[]> [<CommonParameters>]
+ [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>] -InputPath <String[]> [-Culture <String>]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -211,6 +212,26 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Culture
+
+Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
+
+This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
+
+The PowerShell cmdlet `Get-Culture` shows the current culture of PowerShell.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/src/PSRule/Annotations/BlockMetadata.cs b/src/PSRule/Annotations/BlockMetadata.cs
@@ -3,7 +3,7 @@
     /// <summary>
     /// Metadata properties that can be exposed by comment help.
     /// </summary>
-    public sealed class BlockMetadata
+    internal sealed class BlockMetadata
     {
         public string Description;
     }

diff --git a/src/PSRule/Commands/NewRuleDefinitionCommand.cs b/src/PSRule/Commands/NewRuleDefinitionCommand.cs
@@ -1,6 +1,8 @@
-using PSRule.Pipeline;
+using PSRule.Parser;
+using PSRule.Pipeline;
 using PSRule.Rules;
 using System.Collections;
+using System.IO;
 using System.Management.Automation;
 
 namespace PSRule.Commands
@@ -60,33 +62,63 @@ internal sealed class NewRuleDefinitionCommand : LanguageBlock
 
         protected override void ProcessRecord()
         {
+            var context = PipelineContext.CurrentThread;
             var metadata = GetMetadata(MyInvocation.ScriptName, MyInvocation.ScriptLineNumber, MyInvocation.OffsetInLine);
             var tag = GetTag(Tag);
-            var moduleName = PipelineContext.CurrentThread.ModuleName;
+            var moduleName = context.Source.ModuleName;
 
-            PipelineContext.CurrentThread.VerboseFoundRule(ruleName: Name, scriptName: MyInvocation.ScriptName);
+            context.VerboseFoundRule(ruleName: Name, scriptName: MyInvocation.ScriptName);
 
             var ps = PowerShell.Create();
-            ps.Runspace = PipelineContext.CurrentThread.GetRunspace();
+            ps.Runspace = context.GetRunspace();
             ps.AddCommand(new CmdletInfo(InvokeBlockCmdletName, typeof(InvokeRuleBlockCommand)));
             ps.AddParameter(InvokeBlockCmdlet_TypeParameter, Type);
             ps.AddParameter(InvokeBlockCmdlet_IfParameter, If);
             ps.AddParameter(InvokeBlockCmdlet_BodyParameter, Body);
 
             PipelineContext.EnableLogging(ps);
 
+            var doc = GetDoc(context: context, Name);
+
             var block = new RuleBlock(
                 sourcePath: MyInvocation.ScriptName,
                 moduleName: moduleName,
                 ruleName: Name,
-                description: metadata.Description,
+                description: doc == null ? metadata.Description : doc.Synopsis.Text,
+                recommendation: doc != null ? doc.Recommendation[0].Introduction : null,
                 condition: ps,
                 tag: tag,
+                annotations: doc?.Annotations,
                 dependsOn: RuleHelper.ExpandRuleName(DependsOn, MyInvocation.ScriptName, moduleName),
                 configuration: Configure
             );
 
             WriteObject(block);
         }
+
+        private Parser.RuleDocument GetDoc(PipelineContext context, string name)
+        {
+            if (context.Source.HelpPath == null || context.Source.HelpPath.Length == 0)
+            {
+                return null;
+            }
+
+            for (var i = 0; i < context.Source.HelpPath.Length; i++)
+            {
+                var path = Path.Combine(context.Source.HelpPath[i], $"{name}.md");
+
+                if (!File.Exists(path))
+                {
+                    continue;
+                }
+
+                var reader = new MarkdownReader(yamlHeaderOnly: false);
+                var stream = reader.Read(markdown: File.ReadAllText(path: path), path: path);
+                var lexer = new RuleLexer(preserveFomatting: false);
+                return lexer.Process(stream: stream);
+            }
+
+            return null;
+        }
     }
 }
diff --git a/src/PSRule/Host/HostHelper.cs b/src/PSRule/Host/HostHelper.cs
@@ -1,6 +1,7 @@
 using PSRule.Annotations;
 using PSRule.Configuration;
 using PSRule.Pipeline;
+using PSRule.Resources;
 using PSRule.Rules;
 using System;
 using System.Collections.Generic;
@@ -96,17 +97,12 @@ private static IEnumerable<ILanguageBlock> GetLanguageBlock(RuleSource[] sources
 
                     if (!File.Exists(source.Path))
                     {
-                        throw new FileNotFoundException("The script was not found.", source.Path);
+                        throw new FileNotFoundException(PSRuleResources.ScriptNotFound, source.Path);
                     }
 
-                    PipelineContext.CurrentThread.ModuleName = string.IsNullOrEmpty(source.ModuleName) ? null : source.ModuleName;
-
+                    PipelineContext.CurrentThread.Source = source;
                     PipelineContext.CurrentThread.VerboseRuleDiscovery(path: source.Path);
-
-                    if (!File.Exists(source.Path))
-                    {
-                        throw new FileNotFoundException("Can't find file", source.Path);
-                    }
+                    //PipelineContext.CurrentThread.UseSource(source: source);
 
                     // Invoke script
                     ps.AddScript(source.Path, true);
@@ -120,18 +116,22 @@ private static IEnumerable<ILanguageBlock> GetLanguageBlock(RuleSource[] sources
 
                     foreach (var ir in invokeResults)
                     {
-                        if (ir.BaseObject is ILanguageBlock)
+                        if (ir.BaseObject is RuleBlock)
                         {
-                            var block = ir.BaseObject as ILanguageBlock;
-
+                            var block = ir.BaseObject as RuleBlock;
                             results.Add(block);
                         }
+                        //else if (ir.BaseObject is ILanguageBlock)
+                        //{
+                        //    var block = ir.BaseObject as ILanguageBlock;
+                        //    results.Add(block);
+                        //}
                     }
                 }
             }
             finally
             {
-                PipelineContext.CurrentThread.ModuleName = null;
+                PipelineContext.CurrentThread.Source = null;
                 ps.Runspace = null;
                 ps.Dispose();
             }
@@ -198,7 +198,8 @@ private static Rule[] ToRule(IEnumerable<ILanguageBlock> blocks, RuleFilter filt
                         SourcePath = block.SourcePath,
                         ModuleName = block.ModuleName,
                         Description = block.Description,
-                        Tag = block.Tag
+                        Tag = block.Tag,
+                        Annotations = block.Annotations
                     };
                 }
             }

diff --git a/src/PSRule/PSRule.csproj b/src/PSRule/PSRule.csproj
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0;net472</TargetFrameworks>
@@ -19,10 +19,11 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Folder Include="Resources\" />
-  </ItemGroup>
-
-  <ItemGroup>
+    <Compile Update="Resources\FormatResources.Designer.cs">
+      <DesignTime>True</DesignTime>
+      <AutoGen>True</AutoGen>
+      <DependentUpon>FormatResources.resx</DependentUpon>
+    </Compile>
     <Compile Update="Resources\PSRuleResources.Designer.cs">
       <DesignTime>True</DesignTime>
       <AutoGen>True</AutoGen>
@@ -31,6 +32,10 @@
   </ItemGroup>
 
   <ItemGroup>
+    <EmbeddedResource Update="Resources\FormatResources.resx">
+      <Generator>ResXFileCodeGenerator</Generator>
+      <LastGenOutput>FormatResources.Designer.cs</LastGenOutput>
+    </EmbeddedResource>
     <EmbeddedResource Update="Resources\PSRuleResources.resx">
       <Generator>ResXFileCodeGenerator</Generator>
       <LastGenOutput>PSRuleResources.Designer.cs</LastGenOutput>

diff --git a/src/PSRule/PSRule.psd1 b/src/PSRule/PSRule.psd1
@@ -54,7 +54,9 @@ DotNetFrameworkVersion = '4.7.2'
 # RequiredModules = @()
 
 # Assemblies that must be loaded prior to importing this module
-# RequiredAssemblies = @()
+RequiredAssemblies = @(
+    'PSRule.dll'
+)
 
 # Script files (.ps1) that are run in the caller's environment prior to importing this module.
 # ScriptsToProcess = @()