From d61f552703b7e1de2dcc26837ad302a3c88ae0d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Raimund=20Andr=C3=A9e=20=5BMSFT=5D?= Date: Mon, 9 May 2022 18:43:16 +0200 Subject: [PATCH] Get-CompositeSchemaObject now handles missing comment-based help (minor bump) (#117) --- CHANGELOG.md | 7 + source/Private/Get-CompositeSchemaObject.ps1 | 25 +- .../tasks/Generate_Conceptual_Help.build.ps1 | 15 +- source/tasks/Generate_Wiki_Content.build.ps1 | 13 +- .../Publish_GitHub_Wiki_Content.build.ps1 | 17 +- .../Get-CompositeSchemaObject.Tests.ps1 | 280 +++++++++++++----- .../Generate_Conceptual_Help.build.Tests.ps1 | 16 +- .../Generate_Wiki_Content.build.Tests.ps1 | 5 +- ...ublish_GitHub_Wiki_Content.build.Tests.ps1 | 5 +- 9 files changed, 262 insertions(+), 121 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4bcbdea..b9c31f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Fix statement so function passed HQRM tests. - Tasks now uses `Set-SamplerTaskVariable` from the module Sampler to set the common build task variables. +- Updated task parameters `ProjectName` and `SourcePath` to reflect Sampler + +### Fixed + +- Common task variables have not been set, fixed that. +- `Get-CompositeSchemaObject` threw an error when a composite did not have + comment based help, now returns `$null`. ## [0.10.3] - 2022-01-26 diff --git a/source/Private/Get-CompositeSchemaObject.ps1 b/source/Private/Get-CompositeSchemaObject.ps1 index 9a9f61b..a54524c 100644 --- a/source/Private/Get-CompositeSchemaObject.ps1 +++ b/source/Private/Get-CompositeSchemaObject.ps1 @@ -37,8 +37,8 @@ function Get-CompositeSchemaObject throw $script:localizedData.MacOSNotSupportedError } - $manifestFileName = $FileName -replace '.schema.psm1','.psd1' - $compositeName = [System.IO.Path]::GetFileName($FileName) -replace '.schema.psm1','' + $manifestFileName = $FileName -replace '.schema.psm1', '.psd1' + $compositeName = [System.IO.Path]::GetFileName($FileName) -replace '.schema.psm1', '' $manifestData = Import-LocalizedData ` -BaseDirectory ([System.IO.Path]::GetDirectoryName($manifestFileName)) ` -FileName ([System.IO.Path]::GetFileName($manifestFileName)) @@ -57,15 +57,22 @@ function Get-CompositeSchemaObject { $parameterName = $parameter.Name.VariablePath.ToString() - # The parameter name in comment-based help is returned as upper so need to match correctly. - $parameterDescription = $commentBasedHelp.Parameters[$parameterName.ToUpper()] -replace '\r?\n+$' + if ($commentBasedHelp) + { + # The parameter name in comment-based help is returned as upper so need to match correctly. + $parameterDescription = $commentBasedHelp.Parameters[$parameterName.ToUpper()] -replace '\r?\n+$' + } + else + { + $parameterDescription = '' + } @{ - Name = $parameterName - State = (Get-CompositeResourceParameterState -Ast $parameter) - Type = $parameter.StaticType.FullName - ValidateSet = (Get-CompositeResourceParameterValidateSet -Ast $parameter) - Description = $parameterDescription + Name = $parameterName + State = (Get-CompositeResourceParameterState -Ast $parameter) + Type = $parameter.StaticType.FullName + ValidateSet = (Get-CompositeResourceParameterValidateSet -Ast $parameter) + Description = $parameterDescription } } diff --git a/source/tasks/Generate_Conceptual_Help.build.ps1 b/source/tasks/Generate_Conceptual_Help.build.ps1 index dd58ac5..a7ca70a 100644 --- a/source/tasks/Generate_Conceptual_Help.build.ps1 +++ b/source/tasks/Generate_Conceptual_Help.build.ps1 @@ -22,13 +22,10 @@ For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` .PARAMETER ProjectName - The project name. Defaults to the BaseName of the module manifest it finds - in either the folder 'source', 'src, or a folder with the same name as - the module. + The project name. Defaults to the empty string. .PARAMETER SourcePath - The path to the source folder name. Defaults to the same path where the - module manifest is found. + The path to the source folder name. Defaults to the empty string. .PARAMETER MarkdownCodeRegularExpression An array with regular expressions that will be used to remove markdown code @@ -65,11 +62,11 @@ param [Parameter()] [System.String] - $ProjectName = (property ProjectName $(Get-SamplerProjectName -BuildRoot $BuildRoot)), + $ProjectName = (property ProjectName ''), [Parameter()] [System.String] - $SourcePath = (property SourcePath $(Get-SamplerSourcePath -BuildRoot $BuildRoot)), + $SourcePath = (property SourcePath ''), [Parameter()] [System.String] @@ -82,7 +79,7 @@ param # Synopsis: This task generates conceptual help for DSC resources. task Generate_Conceptual_Help { - # Get the values for task variables + # Get the vales for task variables, see https://github.com/gaelcolas/Sampler#task-variables. . Set-SamplerTaskVariable $configParameterName = 'MarkdownCodeRegularExpression' @@ -108,7 +105,7 @@ task Generate_Conceptual_Help { "`tMarkdownCodeRegularExpression = RegEx: {0}" -f ($MarkdownCodeRegularExpression -join ' | RegEx: ') } - Write-Build Magenta "Generating conceptual help for all DSC resources based on source." + Write-Build Magenta 'Generating conceptual help for all DSC resources based on source.' $newDscResourcePowerShellHelpParameters = @{ ModulePath = $SourcePath diff --git a/source/tasks/Generate_Wiki_Content.build.ps1 b/source/tasks/Generate_Wiki_Content.build.ps1 index 0fc783e..f06f69e 100644 --- a/source/tasks/Generate_Wiki_Content.build.ps1 +++ b/source/tasks/Generate_Wiki_Content.build.ps1 @@ -22,13 +22,10 @@ For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` .PARAMETER ProjectName - The project name. Defaults to the BaseName of the module manifest it finds - in either the folder 'source', 'src, or a folder with the same name as - the module. + The project name. Defaults to the empty string. .PARAMETER SourcePath - The path to the source folder name. Defaults to the same path where the - module manifest is found. + The path to the source folder name. Defaults to the empty string. .PARAMETER WikiSourceFolderName The name of the folder that contains the source markdown files (e.g. 'Home.md') @@ -68,11 +65,11 @@ param [Parameter()] [System.String] - $ProjectName = (property ProjectName $(Get-SamplerProjectName -BuildRoot $BuildRoot)), + $ProjectName = (property ProjectName ''), [Parameter()] [System.String] - $SourcePath = (property SourcePath $(Get-SamplerSourcePath -BuildRoot $BuildRoot)), + $SourcePath = (property SourcePath ''), [Parameter()] [System.String] @@ -85,7 +82,7 @@ param # Synopsis: This task generates wiki documentation for the DSC resources. task Generate_Wiki_Content { - # Get the values for task variables + # Get the vales for task variables, see https://github.com/gaelcolas/Sampler#task-variables. . Set-SamplerTaskVariable $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent' diff --git a/source/tasks/Publish_GitHub_Wiki_Content.build.ps1 b/source/tasks/Publish_GitHub_Wiki_Content.build.ps1 index 12c05ec..76b3bb2 100644 --- a/source/tasks/Publish_GitHub_Wiki_Content.build.ps1 +++ b/source/tasks/Publish_GitHub_Wiki_Content.build.ps1 @@ -22,13 +22,10 @@ For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` .PARAMETER ProjectName - The project name. Defaults to the BaseName of the module manifest it finds - in either the folder 'source', 'src, or a folder with the same name as - the module. + The project name. Defaults to the empty string. .PARAMETER SourcePath - The path to the source folder name. Defaults to the same path where the - module manifest is found. + The path to the source folder name. Defaults to the empty string. .PARAMETER WikiContentFolderName The name of the folder that contain the content to publish to the wiki. @@ -71,11 +68,11 @@ param [Parameter()] [System.String] - $ProjectName = (property ProjectName $(Get-SamplerProjectName -BuildRoot $BuildRoot)), + $ProjectName = (property ProjectName ''), [Parameter()] [System.String] - $SourcePath = (property SourcePath $(Get-SamplerSourcePath -BuildRoot $BuildRoot)), + $SourcePath = (property SourcePath ''), [Parameter()] [System.String] @@ -111,13 +108,13 @@ task Publish_GitHub_Wiki_Content { # Only show debug information if Debug was set to 'true' in build configuration. if ($debugTask) { - "Running task with debug information." + 'Running task with debug information.' $local:VerbosePreference = 'Continue' $local:DebugPreference = 'Continue' } - # Get the values for task variables + # Get the vales for task variables, see https://github.com/gaelcolas/Sampler#task-variables. . Set-SamplerTaskVariable # If variables are not set then update variables from the property values in the build.yaml. @@ -183,7 +180,7 @@ task Publish_GitHub_Wiki_Content { $publishWikiContentParameters.Debug = $true } - Write-Build Magenta "Publishing Wiki content." + Write-Build Magenta 'Publishing Wiki content.' Publish-WikiContent @publishWikiContentParameters } diff --git a/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 b/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 index c417269..8ed71e3 100644 --- a/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 +++ b/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 @@ -41,14 +41,15 @@ InModuleScope $script:moduleName { } else { - BeforeAll { - $script:name = 'CompositeHelperTest' - $script:moduleVersion = '1.0.0' - $script:description = 'Composite resource.' - $script:schemaFileName = '{0}.schema.psm1' -f $script:name - $script:schemaFilePath = Join-Path -Path $TestDrive -ChildPath $script:schemaFileName + Context 'When the composite has comment based help' { + BeforeAll { + $script:name = 'CompositeHelperTest' + $script:moduleVersion = '1.0.0' + $script:description = 'Composite resource.' + $script:schemaFileName = '{0}.schema.psm1' -f $script:name + $script:schemaFilePath = Join-Path -Path $TestDrive -ChildPath $script:schemaFileName - $script:schemaFileContent = @' + $script:schemaFileContent = @' <# .SYNOPSIS A composite DSC resource. @@ -86,12 +87,12 @@ configuration CompositeHelperTest # Composite resource code would be here. } '@ - Set-Content -Path $script:schemaFilePath -Value $script:schemaFileContent + Set-Content -Path $script:schemaFilePath -Value $script:schemaFileContent - $script:manifestFileName = '{0}.psd1' -f $script:name - $script:manifestFilePath = Join-Path -Path $TestDrive -ChildPath $script:manifestFileName + $script:manifestFileName = '{0}.psd1' -f $script:name + $script:manifestFilePath = Join-Path -Path $TestDrive -ChildPath $script:manifestFileName - $script:manifestFileContent = @" + $script:manifestFileContent = @" @{ RootModule = '$script:name.schema.psm1' ModuleVersion = '$script:moduleVersion' @@ -104,82 +105,213 @@ configuration CompositeHelperTest } "@ - Set-Content -Path $script:manifestFilePath -Value $script:manifestFileContent - } + Set-Content -Path $script:manifestFilePath -Value $script:manifestFileContent + } - It 'Should process the composite resource from the schema file without throwing' { - { - $script:schema = Get-CompositeSchemaObject -FileName $script:schemaFilePath -Verbose - } | Should -Not -Throw - } + It 'Should process the composite resource from the schema file without throwing' { + { + $script:schema = Get-CompositeSchemaObject -FileName $script:schemaFilePath -Verbose + } | Should -Not -Throw + } - It "Should return the composite resource schema with name '$script:name'" { - $script:schema.Name | Should -Be $script:name - } + It "Should return the composite resource schema with name '$script:name'" { + $script:schema.Name | Should -Be $script:name + } - It "Should return the composite resource schema with module version '$script:moduleVersion'" { - $script:schema.ModuleVersion | Should -Be $script:moduleVersion - } + It "Should return the composite resource schema with module version '$script:moduleVersion'" { + $script:schema.ModuleVersion | Should -Be $script:moduleVersion + } - It "Should return the composite resource schema with description '$script:description'" { - $script:schema.Description | Should -Be $script:description - } + It "Should return the composite resource schema with description '$script:description'" { + $script:schema.Description | Should -Be $script:description + } + + It 'Should get property with all correct properties' { + [CmdletBinding()] + param ( + [Parameter()] + [System.String] + $Name, - It 'Should get property with all correct properties' { - [CmdletBinding()] - param ( - [Parameter()] - [System.String] - $Name, + [Parameter()] + [System.String] + $State, - [Parameter()] - [System.String] - $State, + [Parameter()] + [System.String] + $Type, - [Parameter()] - [System.String] - $Type, + [Parameter()] + [System.String] + $Description + ) - [Parameter()] - [System.String] - $Description + $parameter = $script:schema.Parameters.Where({ + $_.Name -eq $Name + }) + + $parameter.State | Should -Be $State + $parameter.Type | Should -Be $Type + $parameter.Description | Should -Be $Description + } -TestCases @( + @{ + Name = 'Name' + State = 'Required' + Type = 'System.String[]' + Description = 'An array of the names.' + } + @{ + Name = 'Ensure' + State = 'Write' + Type = 'System.String' + Description = 'Specifies whether or not the the thing should exist.' + } + @{ + Name = 'Credential' + State = 'Write' + Type = 'System.Management.Automation.PSCredential' + Description = 'The credential to use to set the thing.' + } ) - $parameter = $script:schema.Parameters.Where({ - $_.Name -eq $Name - }) - - $parameter.State | Should -Be $State - $parameter.Type | Should -Be $Type - $parameter.Description | Should -Be $Description - } -TestCases @( - @{ - Name = 'Name' - State = 'Required' - Type = 'System.String[]' - Description = 'An array of the names.' + It 'Should return the proper ValidateSet' { + $parameter = $script:schema.Parameters.Where({ + $_.Name -eq 'Ensure' + }) + $parameter.ValidateSet | Should -HaveCount 2 + $parameter.ValidateSet | Should -Contain 'Absent' + $parameter.ValidateSet | Should -Contain 'Present' + } + } + + Context 'When the composite is missing comment based help' { + BeforeAll { + $script:name = 'CompositeHelperTest' + $script:moduleVersion = '1.0.0' + $script:description = 'Composite resource.' + $script:schemaFileName = '{0}.schema.psm1' -f $script:name + $script:schemaFilePath = Join-Path -Path $TestDrive -ChildPath $script:schemaFileName + + $script:schemaFileContent = @' +configuration CompositeHelperTest +{ + [CmdletBinding()] + param + ( + [Parameter(Mandatory = $true)] + [ValidateNotNullOrEmpty()] + [System.String[]] + $Name, + + [Parameter()] + [ValidateSet('Present', 'Absent')] + [System.String] + $Ensure, + + [Parameter()] + [System.Management.Automation.PSCredential] + [System.Management.Automation.Credential()] + $Credential + ) + + # Composite resource code would be here. +} +'@ + Set-Content -Path $script:schemaFilePath -Value $script:schemaFileContent + + $script:manifestFileName = '{0}.psd1' -f $script:name + $script:manifestFilePath = Join-Path -Path $TestDrive -ChildPath $script:manifestFileName + + $script:manifestFileContent = @" +@{ + RootModule = '$script:name.schema.psm1' + ModuleVersion = '$script:moduleVersion' + GUID = 'c5e227b5-52dc-4653-b08f-6d94e06bb90b' + Author = 'DSC Community' + CompanyName = 'DSC Community' + Copyright = 'Copyright the DSC Community contributors. All rights reserved.' + Description = '$script:description' + PowerShellVersion = '4.0' +} +"@ + + Set-Content -Path $script:manifestFilePath -Value $script:manifestFileContent + } + + It 'Should process the composite resource from the schema file without throwing' { + { + $script:schema = Get-CompositeSchemaObject -FileName $script:schemaFilePath -Verbose + } | Should -Not -Throw } - @{ - Name = 'Ensure' - State = 'Write' - Type = 'System.String' - Description = 'Specifies whether or not the the thing should exist.' + + It "Should return the composite resource schema with name '$script:name'" { + $script:schema.Name | Should -Be $script:name } - @{ - Name = 'Credential' - State = 'Write' - Type = 'System.Management.Automation.PSCredential' - Description = 'The credential to use to set the thing.' + + It "Should return the composite resource schema with module version '$script:moduleVersion'" { + $script:schema.ModuleVersion | Should -Be $script:moduleVersion + } + + It "Should return the composite resource schema with description '$script:description'" { + $script:schema.Description | Should -Be $script:description + } + + It 'Should get property with all correct properties' { + [CmdletBinding()] + param ( + [Parameter()] + [System.String] + $Name, + + [Parameter()] + [System.String] + $State, + + [Parameter()] + [System.String] + $Type, + + [Parameter()] + [System.String] + $Description + ) + + $parameter = $script:schema.Parameters.Where({ + $_.Name -eq $Name + }) + + $parameter.State | Should -Be $State + $parameter.Type | Should -Be $Type + $parameter.Description | Should -Be $Description + } -TestCases @( + @{ + Name = 'Name' + State = 'Required' + Type = 'System.String[]' + Description = '' + } + @{ + Name = 'Ensure' + State = 'Write' + Type = 'System.String' + Description = '' + } + @{ + Name = 'Credential' + State = 'Write' + Type = 'System.Management.Automation.PSCredential' + Description = '' + } + ) + + It 'Should return the proper ValidateSet' { + $parameter = $script:schema.Parameters.Where({ + $_.Name -eq 'Ensure' + }) + $parameter.ValidateSet | Should -HaveCount 2 + $parameter.ValidateSet | Should -Contain 'Absent' + $parameter.ValidateSet | Should -Contain 'Present' } - ) - - It 'Should return the proper ValidateSet' { - $parameter = $script:schema.Parameters.Where({ - $_.Name -eq 'Ensure' - }) - $parameter.ValidateSet | Should -HaveCount 2 - $parameter.ValidateSet | Should -Contain 'Absent' - $parameter.ValidateSet | Should -Contain 'Present' } } } diff --git a/tests/unit/tasks/Generate_Conceptual_Help.build.Tests.ps1 b/tests/unit/tasks/Generate_Conceptual_Help.build.Tests.ps1 index 829212f..b44b47b 100644 --- a/tests/unit/tasks/Generate_Conceptual_Help.build.Tests.ps1 +++ b/tests/unit/tasks/Generate_Conceptual_Help.build.Tests.ps1 @@ -59,9 +59,10 @@ Describe 'Generate_Conceptual_Help' { } Mock -CommandName Get-Item -MockWith { - $Path = $Path -replace '\*', '99.1.1' + $Path = [System.String] ($Path -replace '\*', '99.1.1') + [PSCustomObject]@{ - FullName = [System.String] $Path + FullName = $Path } } @@ -72,7 +73,7 @@ Describe 'Generate_Conceptual_Help' { $mockTaskParameters = @{ ProjectName = 'MyModule' - SourcePath = $TestDrive + SourcePath = $TestDrive } } @@ -97,9 +98,10 @@ Describe 'Generate_Conceptual_Help' { } Mock -CommandName Get-Item -MockWith { - $Path = $Path -replace '\*', '99.1.1' + $Path = [System.String] ($Path -replace '\*', '99.1.1') + [PSCustomObject]@{ - FullName = [System.String] $Path + FullName = $Path } } @@ -109,8 +111,8 @@ Describe 'Generate_Conceptual_Help' { } $mockTaskParameters = @{ - ProjectName = 'MyModule' - SourcePath = $TestDrive + ProjectName = 'MyModule' + SourcePath = $TestDrive MarkdownCodeRegularExpression = @( '\`(.+?)\`' ) diff --git a/tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 b/tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 index e03c218..b74d78d 100644 --- a/tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 +++ b/tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 @@ -33,9 +33,10 @@ Describe 'Generate_Wiki_Content' { } Mock -CommandName Get-Item -MockWith { - $Path = $Path -replace '\*', '1.0.0' + $Path = [System.String] ($Path -replace '\*','1.0.0') + [PSCustomObject]@{ - FullName = [System.String] $Path + FullName = $Path } } diff --git a/tests/unit/tasks/Publish_GitHub_Wiki_Content.build.Tests.ps1 b/tests/unit/tasks/Publish_GitHub_Wiki_Content.build.Tests.ps1 index 80d657e..dc6dae1 100644 --- a/tests/unit/tasks/Publish_GitHub_Wiki_Content.build.Tests.ps1 +++ b/tests/unit/tasks/Publish_GitHub_Wiki_Content.build.Tests.ps1 @@ -47,9 +47,10 @@ Describe 'Publish_GitHub_Wiki_Content' { } Mock -CommandName Get-Item -MockWith { - $Path = $Path -replace '\*', '1.0.0' + $Path = [System.String] ($Path -replace '\*','1.0.0') + [PSCustomObject]@{ - FullName = [System.String] $Path + FullName = $Path } }