microsoft / PSRule

Validate infrastructure as code (IaC) and objects using PowerShell rules.
https://microsoft.github.io/PSRule/v2/
MIT License
395 stars 49 forks source link

Get-PSRuleHelp search into the current directory by default #197

Closed LaurentDardenne closed 5 years ago

LaurentDardenne commented 5 years ago

The cmdlet Get-PSRuleHelp must search into the current directory if the 'Path' parameter has no argument :

cd C:\Prive\PSRule\Rule1
dir -rec

#     Répertoire : C:\Prive\PSRule\Rule1

# Mode                LastWriteTime         Length Name
# ----                -------------         ------ ----
# d-----       19/06/2019     14:45                fr-FR
# -a----       19/06/2019     11:12            371 Test.Rule.ps1

#     Répertoire : C:\Prive\PSRule\Rule1\fr-FR

# Mode                LastWriteTime         Length Name
# ----                -------------         ------ ----
# -a----       19/06/2019     14:42            264 Test.md

One rule file exist into the current directory, but Get-PSRuleHelp do not read it :

Get-PSRuleHelp -Name Test -verbose
# COMMENTAIRES : [Get-PSRuleHelp]::BEGIN
# COMMENTAIRES : [New-PSRuleOption] BEGIN::
# COMMENTAIRES : Attempting to read: C:\Prive\PSRule\Rule1
# COMMENTAIRES : [New-PSRuleOption] END::
# COMMENTAIRES : [PSRule][D] -- Found 0 PSRule module(s)
# COMMENTAIRES : [Get-PSRuleHelp] -- Could not find any .Rule.ps1 script files in the path
# COMMENTAIRES : [Get-PSRuleHelp]::END

When I specify the 'Path' parameter with a relative path, it finds the help file

Get-PSRuleHelp -Name Test -Path .\Test.Rule.ps1 -verbose
# COMMENTAIRES : [Get-PSRuleHelp]::BEGIN
# COMMENTAIRES : [New-PSRuleOption] BEGIN::
# COMMENTAIRES : Attempting to read: C:\Prive\PSRule\Rule1
# COMMENTAIRES : [New-PSRuleOption] END::
# COMMENTAIRES : [PSRule][D] -- Scanning for source files: .\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found 0 PSRule module(s)
# COMMENTAIRES : [Get-PSRuleHelp] -- Found 1 source file(s)
# COMMENTAIRES : [PSRule][D] -- Discovering rules in: C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found Test in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found Test1 in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found Test2 in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found Test3 in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found Test4 in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found Test5 in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found WithDependency2 in C:\Prive\PSRule\Rule1\Test.Rule.ps1
# COMMENTAIRES : [PSRule][D] -- Found WithDependency5 in C:\Prive\PSRule\Rule1\Test.Rule.ps1

# NAME
#     Test

# SYNOPSIS
#     A brief summary of the rule

# DESCRIPTION
#     A detailed description of the rule

# RECOMMENDATION
#     A detailed explanation of the steps required to pass the rule

# COMMENTAIRES : [Get-PSRuleHelp]::END

That said, research in the current path can often be problematic with Powershell :

cd hklm:
Get-PSRuleHelp -Name Test -Path .\Test.Rule.ps1 -verbose
#COMMENTAIRES : [Get-PSRuleHelp]::BEGIN
#COMMENTAIRES : [New-PSRuleOption] BEGIN::
#COMMENTAIRES : Attempting to read: HKLM:\
#Exception lors de l'appel de «FromFile» avec «2» argument(s): «Le format du chemin d'accès donné n'est pas pris en charge.»
#NotSupportedException
...
BernieWhite commented 5 years ago

@LaurentDardenne Yeah, so Get-PSRuleHelp searches rules in loaded modules first. The intent was to match similar functionality to Get-Help.

The reasoning for this was that modules are more likely to have markdown help created for them then standalone rules.

-Path can be used, but it is more explicit.

This this behaviour may be confusing since, most of the other PSRule cmdlets operate on the current working path first.

However i'm interested in your feedback to improve this in the future.

LaurentDardenne commented 5 years ago

However i'm interested in your feedback to improve this in the future.

According to the documentation:

If the rules are loose (not part of a module), PSRule will search for documentation in the .\\ subdirectory relative to where the rule script .ps1 file is located.

If one is already in the directory of a script of a rule, I think that if Path is not informed one can first search the help file in the current directory before displaying an error s' he does not exist. I have not yet studied the creation of modules of rule, but already I know one of the advantages.