Merge pull request #88 from michaeltlombardi/gh-81/main/handle-parame…

…ters

(GH-74, GH-81) Handle parameters in type generation and collapse ensure keywords

README.md

@@ -121,7 +121,7 @@ Try {
 }
 ... (snipped for brevity)
 Debug: dsc_psrepository: raw data received: {"SourceLocation"=>"https://www.powershellgallery.com/api/v2", "InstallationPolicy"=>"Trusted", "Registered"=>true, "Name"=>"psgAllery", "ResourceId"=>nil, "PackageManagementProvider"=>"NuGet", "Trusted"=>true, "PsDscRunAsCredential"=>nil, "PublishLocation"=>"https://www.powershellgallery.com/api/v2/package/", "Ensure"=>"Present", "DependsOn"=>nil, "SourceInfo"=>nil, "ScriptPublishLocation"=>"https://www.powershellgallery.com/api/v2/package/", "ConfigurationName"=>nil, "ModuleVersion"=>"2.2.4.1", "ModuleName"=>"C:/code/puppetlabs/Puppet.Dsc/import/powershellget/spec/fixtures/modules/powershellget/lib/puppet_x/dsc_resources/PowerShellGet/PowerShellGet.psd1", "ScriptSourceLocation"=>"https://www.powershellgallery.com/api/v2/items/psscript"}
-Debug: dsc_psrepository: Returned to Puppet as {:dsc_sourcelocation=>"https://www.powershellgallery.com/api/v2", :dsc_installationpolicy=>"Trusted", :dsc_name=>"psgAllery", :dsc_packagemanagementprovider=>"NuGet", :dsc_publishlocation=>"https://www.powershellgallery.com/api/v2/package/", :dsc_ensure=>"Present", :dsc_scriptpublishlocation=>"https://www.powershellgallery.com/api/v2/package/", :dsc_scriptsourcelocation=>"https://www.powershellgallery.com/api/v2/items/psscript", :name=>"PowerShell Gallery", :ensure=>"present"}
+Debug: dsc_psrepository: Returned to Puppet as {:dsc_sourcelocation=>"https://www.powershellgallery.com/api/v2", :dsc_installationpolicy=>"Trusted", :dsc_name=>"psgAllery", :dsc_packagemanagementprovider=>"NuGet", :dsc_publishlocation=>"https://www.powershellgallery.com/api/v2/package/", :dsc_ensure=>"Present", :dsc_scriptpublishlocation=>"https://www.powershellgallery.com/api/v2/package/", :dsc_scriptsourcelocation=>"https://www.powershellgallery.com/api/v2/items/psscript", :name=>"PowerShell Gallery"}
 Debug: dsc_psrepository: Canonicalized Resources: [{:dsc_installationpolicy=>"Trusted", :dsc_name=>"psgAllery", :name=>"PowerShell Gallery"}]
 ... (snipped for brevity)
 ```

build.Tests.ps1

@@ -177,7 +177,7 @@ Describe $script {
         $_ -match 'Creating: Finished'
       }
       $ErrorFilterScript = {
-        $_ -match 'Error'
+        $_ -match '(Error|has not provided canonicalized values)'
       }
       Invoke-PdkCommand -Path $expected_base -Command $Command -SuccessFilterScript $SuccessFilterScript -ErrorFilterScript $ErrorFilterScript
     }

src/internal/functions/Get-DscResourceParameterInfo.ps1

@@ -91,6 +91,7 @@ function Get-DscResourceParameterInfo {
         # # Turn a boolean into a string and downcase for Puppet language
         mandatory_for_get = $MandatoryGet.ToString().ToLowerInvariant()
         mandatory_for_set = $MandatorySet.ToString().ToLowerInvariant()
+        is_parameter      = Test-DscResourcePropertyParameterStatus -Property $Parameter
         # Because we can't check the flags per resource, we have to assume any mandatory params are also namevars
         # This is *not* accurate - properties with the Key flag are namevars whereas ones with Required are merely mandatory
         is_namevar        = $MandatoryGet.ToString().ToLowerInvariant()

src/internal/functions/Get-DscResourceParameterInfoByCimClass.ps1

@@ -103,6 +103,7 @@ Function Get-DscResourceParameterInfoByCimClass {
         # only retrieve default values by parsing the AST, so this is acceptable, if not ideal.
         DefaultValue = $null
         Help = $Property.Qualifiers['Description'].Value
+        is_parameter      = Test-DscResourcePropertyParameterStatus -Property $Property
         is_namevar        = ($Property.Flags -Match 'Key').ToString().ToLowerInvariant()
         mandatory_for_get = $IsMandatory.ToString().ToLowerInvariant()
         mandatory_for_set = $IsMandatory.ToString().ToLowerInvariant()

src/internal/functions/Get-ReadmeContent.ps1

@@ -102,9 +102,6 @@ For reference documentation about the DSC resources exposed in this module, see
 # Include a meaningful title for your resource declaration
 dsc_psrepository { 'Add team module repo':
     dsc_name               => 'foo',
-    # Note that we specify dsc_ensure; do NOT specify the Puppet
-    # ensure property, it exists only for the underlying system.
-    # You will always use dsc_ensure.
     dsc_ensure             => present,
     # This location is nonsense, can be any valid folder on your
     # machine or in a share, any location the SourceLocation param

src/internal/functions/Get-TypeContent.ps1

@@ -55,11 +55,6 @@ Puppet::ResourceApi.register_type(
   docs: $(ConvertTo-PuppetRubyString $ResourceDescription),
   features: ['simple_get_filter', 'canonicalize'],
   attributes: {
-    ensure: {
-      type:    'Enum[present, absent]',
-      desc:    'Whether this resource should be present or absent on the target system.',
-      default: 'present',
-    },
     name: {
       type:      'String',
       desc:      'Description of the purpose for this resource declaration.',

src/internal/functions/Get-TypeParameterContent.ps1

@@ -37,8 +37,13 @@ $(
   }
 )
 $(
-  If ($Parameter.is_namevar -eq 'true'){
-    "      behaviour: :namevar,"
+  $Behaviours = @()
+  If ($Parameter.is_namevar -eq 'true') { $Behaviours += ':namevar' }
+  If ($Parameter.is_parameter -eq $true) { $Behaviours += ':parameter' }
+  If ($Behaviours.count -eq 1) {
+    "      behaviour: $($Behaviours[0]),"
+  } ElseIf ($Behaviours.count -gt 1) {
+    "      behaviour: [$($Behaviours -join ', ')],"
   }
 )
       mandatory_for_get: $($Parameter.mandatory_for_get),

src/internal/functions/Test-DscResourcePropertyParameterStatus.ps1

@@ -0,0 +1,34 @@
+Function Test-DscResourcePropertyParameterStatus {
+  <#
+    .SYNOPSIS
+      Return whether or not a DSC Resource Property can be read from a target system
+    .DESCRIPTION
+      Some DSC Resources have properties which cannot be read back from a target system
+      with the Get method. These properties are classified as parameters in Puppet.
+    .PARAMETER Property
+      The DSC Resource property to check for parameter status
+    .EXAMPLE
+      Test-DscResourcePropertyParameterStatus -Property $DscResource.Properties[0]
+      
+      This will return `$True` if the property is a parameter and `$False` otherwise.
+  #>
+  [cmdletbinding()]
+  [OutputType([Boolean])]
+  Param(
+    # We cannot strongly type this *and* have useful unit tests as the type
+    # has read-only values and cannot be created properly nor updated. For
+    # other commands we could just grab real examples but for processing a
+    # ton of data types, that's just not feasible. It *should* be:
+    # Microsoft.PowerShell.DesiredStateConfiguration.DscResourcePropertyInfo
+    [ValidateNotNullOrEmpty()]
+    $Property
+  )
+
+  $KnownParameters = @(
+    'Force'
+    'Purge'
+    'Validate'
+  )
+
+  $Property.Name -in $KnownParameters -or  $Property.ReferenceClassName -match 'Credential'
+}

src/tests/functions/Get-DscResourceParameterInfo.Tests.ps1

@@ -14,6 +14,7 @@ Describe 'Get-DscResourceParameterInfo' {
         $ParameterToInspect.DefaultValue | Should -BeExactly '$false'
         $ParameterToInspect.Type | Should -BeExactly 'Optional[Boolean]'
         $ParameterToInspect.Help | Should -MatchExactly '^Specifies whether or not'
+        $ParameterToInspect.is_parameter      | Should -Be $true
         $ParameterToInspect.is_namevar        | Should -BeExactly 'false'
         $ParameterToInspect.mandatory_for_get | Should -BeExactly 'false'
         $ParameterToInspect.mandatory_for_set | Should -BeExactly 'false'
@@ -35,6 +36,7 @@ Describe 'Get-DscResourceParameterInfo' {
         $ParameterToInspect.Type | Should -BeExactly 'String'
         # The help info for a parameter can only be discovered via the AST
         $ParameterToInspect.Help | Should -BeNullOrEmpty
+        $ParameterToInspect.is_parameter      | Should -Be $false
         $ParameterToInspect.is_namevar        | Should -BeExactly 'true'
         $ParameterToInspect.mandatory_for_get | Should -BeExactly 'true'
         $ParameterToInspect.mandatory_for_set | Should -BeExactly 'true'

src/tests/functions/Get-DscResourceParameterInfoByCimClass.Tests.ps1

@@ -19,6 +19,7 @@ Describe 'Get-DscResourceParameterInfoByCimClass' {
         $CimlessParameterToInspect.DefaultValue      | Should -BeNullOrEmpty
         $CimlessParameterToInspect.Type              | Should -BeExactly 'Optional[Boolean]'
         $CimlessParameterToInspect.Help              | Should -MatchExactly '^Specifies whether or not'
+        $CimlessParameterToInspect.is_parameter      | Should -BeExactly $true
         $CimlessParameterToInspect.is_namevar        | Should -BeExactly 'false'
         $CimlessParameterToInspect.mandatory_for_get | Should -BeExactly 'false'
         $CimlessParameterToInspect.mandatory_for_set | Should -BeExactly 'false'
@@ -44,6 +45,7 @@ Describe 'Get-DscResourceParameterInfoByCimClass' {
         $AclProperty.DefaultValue      | Should -BeNullOrEmpty
         $AclProperty.Type              | Should -MatchExactly ([Regex]::Escape('Array[Struct[{'))
         $AclProperty.Help              | Should -MatchExactly '^Indicates the access control information'
+        $AclProperty.is_parameter      | Should -Be $false
         $AclProperty.is_namevar        | Should -BeExactly 'false'
         $AclProperty.mandatory_for_get | Should -BeExactly 'true'
         $AclProperty.mandatory_for_set | Should -BeExactly 'true'

src/tests/functions/Test-DscResourcePropertyParameterStatus.Tests.ps1

@@ -0,0 +1,28 @@
+Describe 'Test-SymLinkedItem' {
+  InModuleScope puppet.dsc {
+    Context 'Basic verification' {
+      Function New-DscParameter {
+        Param (
+          [string]$Name = 'foo',
+          [string]$ReferenceClassName
+        )
+        [pscustomobject]@{
+          Name               = $Name
+          ReferenceClassName = $ReferenceClassName
+        }
+      }
+
+      It 'A parameter which is not in the known parameter list or a credential returns false' {
+        Test-DscResourcePropertyParameterStatus -Property (New-DscParameter) | Should -Be $false
+      }
+      It 'A parameter whose name is in the known parameter list returns true' {
+        Test-DscResourcePropertyParameterStatus -Property (New-DscParameter -Name 'Force') | Should -Be $true
+        Test-DscResourcePropertyParameterStatus -Property (New-DscParameter -Name 'Purge') | Should -Be $true
+        Test-DscResourcePropertyParameterStatus -Property (New-DscParameter -Name 'Validate') | Should -Be $true
+      }
+      It 'A parameter whose reference class is a credential returns true' {
+        Test-DscResourcePropertyParameterStatus -Property (New-DscParameter -ReferenceClassName 'MSFT_Credential') | Should -Be $true
+      }
+    }
+  }
+}