Generate_Conceptual_Help: Correctly evaluate module version (#23)

* Fixes Generate_Conceptual_Help to use the correct path

* Fix review comments

* Fix failing test

* Revert lost type

* Fixes Generate_Conceptual_Help to correctly evaluate module version

CHANGELOG.md

@@ -23,6 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fixes the build task `Generate_Conceptual_Help` to use the correct
   module version folder name for the built module path ([issue #17](https://github.com/dsccommunity/DscResource.DocGenerator/issues/17)).
+- Fixes the build task `Generate_Conceptual_Help` to correctly evaluate
+  the module version ([issue #21](https://github.com/dsccommunity/DscResource.DocGenerator/issues/21)).
 
 ## [0.3.0] - 2020-02-11
 

source/Private/Get-ModuleVersion.ps1

@@ -0,0 +1,72 @@
+<#
+    .SYNOPSIS
+        This function evaluates the version from a module manifest if the
+        passed ModuleVersion is not already set.
+
+    .PARAMETER OutputDirectory
+        The path to the output folder where the module is built, e.g.
+        'c:\MyModule\output'.
+
+    .PARAMETER ProjectName
+        The name of the project, normally the name of the module that is being
+        built.
+
+    .EXAMPLE
+        Get-ModuleVersion -OutputDirectory 'c:\MyModule\output' -ProjectName 'MyModule' -ModuleVersion $null
+
+        Will evaluate the module version from the module manifest in the path
+        c:\MyModule\output\MyModule\*\MyModule.psd1.
+
+    .EXAMPLE
+        Get-ModuleVersion -ModuleVersion '1.0.0-preview1'.
+
+        Will return the module version as '1.0.0-preview1'.
+
+    .NOTES
+        This is the same function that exits in the module Sampler, so if the
+        function there is moved or exposed it should be reused from there instead.
+#>
+function Get-ModuleVersion
+{
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter()]
+        [System.String]
+        $OutputDirectory,
+
+        [Parameter()]
+        [System.String]
+        $ProjectName,
+
+        [Parameter()]
+        [System.String]
+        $ModuleVersion
+    )
+
+    if ([System.String]::IsNullOrEmpty($ModuleVersion))
+    {
+        $moduleInfo = Import-PowerShellDataFile "$OutputDirectory/$ProjectName/*/$ProjectName.psd1" -ErrorAction 'Stop'
+
+        if ($preReleaseTag = $moduleInfo.PrivateData.PSData.Prerelease)
+        {
+            $moduleVersion = $moduleInfo.ModuleVersion + "-" + $preReleaseTag
+        }
+        else
+        {
+            $moduleVersion = $moduleInfo.ModuleVersion
+        }
+    }
+    else
+    {
+        <#
+            This handles a previous version of the module that suggested to pass
+            a version string with metadata in the CI pipeline that can look like
+            this: 1.15.0-pr0224-0022+Sha.47ae45eb2cfed02b249f239a7c55e5c71b26ab76.Date.2020-01-07
+        #>
+        $moduleVersion = ($moduleVersion -split '\+', 2)[0]
+    }
+
+    return $moduleVersion
+}

source/tasks/Generate_Conceptual_Help.build.ps1

@@ -91,8 +91,8 @@ param
             }
             catch
             {
-                Write-Verbose -Message "Error attempting to use GitVersion $($_), falling back to default of '0.0.1'."
-                '0.0.1'
+                Write-Verbose -Message "Error attempting to use GitVersion $($_)."
+                ''
             }
         )),
 
@@ -107,6 +107,13 @@ task Generate_Conceptual_Help {
         $OutputDirectory = Join-Path -Path $ProjectPath -ChildPath $OutputDirectory
     }
 
+    $getModuleVersionParameters = @{
+        OutputDirectory = $OutputDirectory
+        ProjectName     = $ProjectName
+        ModuleVersion   = $ModuleVersion
+    }
+
+    $ModuleVersion = Get-ModuleVersion @getModuleVersionParameters
     $ModuleVersionFolder, $PreReleaseString = $ModuleVersion -split '\-', 2
 
     $builtModulePath = Join-Path -Path (Join-Path -Path $OutputDirectory -ChildPath $ProjectName) -ChildPath $ModuleVersionFolder

tests/unit/private/Get-ModuleVersion.Tests.ps1

@@ -0,0 +1,74 @@
+#region HEADER
+$script:projectPath = "$PSScriptRoot\..\..\.." | Convert-Path
+$script:projectName = (Get-ChildItem -Path "$script:projectPath\*\*.psd1" | Where-Object -FilterScript {
+        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
+        $(try
+            {
+                Test-ModuleManifest -Path $_.FullName -ErrorAction Stop
+            }
+            catch
+            {
+                $false
+            })
+    }).BaseName
+
+$script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Select-Object -First 1
+Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue'
+
+Import-Module $script:moduleName -Force -ErrorAction 'Stop'
+#endregion HEADER
+
+InModuleScope $script:moduleName {
+    Describe 'Get-ModuleVersion' {
+        Context 'When ModuleVersion is not $null' {
+            It 'Should return the correct module version' {
+                Get-ModuleVersion -ModuleVersion '1.0.0-preview1' | Should -Be '1.0.0-preview1'
+            }
+
+            It 'Should return the correct module version when it contained metadata' {
+                Get-ModuleVersion -ModuleVersion '1.0.0-preview1+metadata.2019-01-01' | Should -Be '1.0.0-preview1'
+            }
+        }
+
+        Context 'When ModuleVersion is $null' {
+            Context 'When module manifest has a prerelease string set' {
+                BeforeAll {
+                    Mock -CommandName Import-PowerShellDataFile -MockWith {
+                        return @{
+                            ModuleVersion = '2.0.0'
+                            PrivateData = @{
+                                PSData = @{
+                                    Prerelease = 'preview2'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                It 'Should return the correct module version' {
+                    Get-ModuleVersion -OutputDirectory $TestDrive -ProjectName 'MyModule' | Should -Be '2.0.0-preview2'
+                }
+            }
+
+            Context 'When module manifest does not have prerelease string set' {
+                BeforeAll {
+                    Mock -CommandName Import-PowerShellDataFile -MockWith {
+                        return @{
+                            ModuleVersion = '2.0.0'
+                            PrivateData = @{
+                                PSData = @{
+                                    Prerelease = ''
+                                }
+                            }
+                        }
+                    }
+                }
+
+                It 'Should return the correct module version' {
+                    Get-ModuleVersion -OutputDirectory $TestDrive -ProjectName 'MyModule' | Should -Be '2.0.0'
+                }
+            }
+        }
+
+    }
+}

tests/unit/tasks/Generate_Conceptual_Help.build.Tests.ps1

@@ -107,11 +107,6 @@ Describe 'Generate_Conceptual_Help' {
         }
 
         It 'Should run the build task with the correct destination module path and without throwing' {
-            $mockTaskParameters = @{
-                ProjectName = 'MyModule'
-                SourcePath = $TestDrive
-            }
-
             {
                 Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @mockTaskParameters
             } | Should -Not -Throw
@@ -129,22 +124,21 @@ Describe 'Generate_Conceptual_Help' {
                 throw
             }
 
+            Mock -CommandName Get-ModuleVersion -MockWith {
+                return '1.0.0'
+            }
+
             $mockTaskParameters = @{
                 ProjectName = 'MyModule'
                 SourcePath = $TestDrive
             }
 
             $mockExpectedDestinationModulePath = Join-Path -Path $script:projectPath -ChildPath 'output' |
                 Join-Path -ChildPath $mockTaskParameters.ProjectName |
-                    Join-Path -ChildPath '0.0.1'
+                    Join-Path -ChildPath '1.0.0'
         }
 
         It 'Should run the build task with the correct destination module path and without throwing' {
-            $mockTaskParameters = @{
-                ProjectName = 'MyModule'
-                SourcePath = $TestDrive
-            }
-
             {
                 Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @mockTaskParameters
             } | Should -Not -Throw