#7 - Add a check for external help into Test-FunctionHelpCoverage

PSCodeHealth/PSCodeHealth.psm1

@@ -10,6 +10,7 @@ Foreach ( $Import in @($Public + $Private) ) {
         Write-Error -Message "Failed to import function $($Import.FullName): $_"
     }
 }
+$Script:ExternalHelpCommandNames = @()
 
 Export-ModuleMember -Function $Public.Basename
 Set-Alias -Name ipch -Value Invoke-PSCodeHealth -Force

PSCodeHealth/Private/Get-ExternalHelpCommand.ps1

@@ -0,0 +1,41 @@
+Function Get-ExternalHelpCommand {
+    <#
+    .SYNOPSIS
+        Gets the name of the commands listed in external help files.
+    .DESCRIPTION
+        Gets the name of the commands listed in external (MAML-formatted) help files.
+    
+    .PARAMETER Path
+        Root directory where the function looks for external help files.  
+        The function looks for files with a name ending with "-help.xml" in a "en-US" subdirectory.
+    
+    .EXAMPLE
+        PS C:\> Get-ExternalHelpCommand -Path 'C:\GitRepos\MyModule'
+    
+        Gets the name of all the commands listed in external help files found in the folder : C:\GitRepos\MyModule\.
+        
+    .NOTES
+        https://info.sapien.com/index.php/scripting/scripting-help/writing-xml-help-for-advanced-functions
+    #>
+    [CmdletBinding()]
+    Param (
+        [Parameter(Position=0, Mandatory)]
+        [ValidateScript({ Test-Path $_ -PathType Container })]
+        [string[]]$Path
+    )
+
+    $LocaleFolder = Get-ChildItem -Path $Path -Directory -Filter 'en-US' -Recurse
+    If ( $LocaleFolder ) {
+        $MamlHelpFile = Get-ChildItem -Path $LocaleFolder.FullName -File -Filter '*-help.xml'
+        If ( $MamlHelpFile ) {
+            Try {
+                [xml]$Maml = Get-Content -Path $MamlHelpFile.FullName
+            }
+            Catch {
+                Write-Warning "The content of the file $($MamlHelpFile.FullName) was not valid XML"
+                return
+            }
+            return $Maml.helpItems.command.details.name
+        }
+    }
+}

PSCodeHealth/Private/Metrics/Test-FunctionHelpCoverage.ps1

@@ -27,5 +27,8 @@ Function Test-FunctionHelpCoverage {
     )
 
     $FunctionHelpInfo = $FunctionDefinition.GetHelpContent()
-    return ($FunctionHelpInfo -is [System.Management.Automation.Language.CommentHelpInfo])
+    $CommentBasedHelpPresent = $FunctionHelpInfo -is [System.Management.Automation.Language.CommentHelpInfo]
+    $ExternalHelpPresent = $FunctionDefinition.Name -in $Script:ExternalHelpCommandNames
+    $HelpPresent = $CommentBasedHelpPresent -or $ExternalHelpPresent
+    return $HelpPresent
 }

PSCodeHealth/Public/Invoke-PSCodeHealth.ps1

@@ -127,6 +127,7 @@ Function Invoke-PSCodeHealth {
     }
 
     If ( (Get-Item -Path $Path).PSIsContainer ) {
+        $ExternalHelpSearchRoot = $Path
         If ( $PSBoundParameters.ContainsKey('Exclude') ) {
             $PowerShellFiles = Get-PowerShellFile -Path $Path -Recurse:$($Recurse.IsPresent) -Exclude $Exclude
         }
@@ -135,6 +136,7 @@ Function Invoke-PSCodeHealth {
         }
     }
     Else {
+        $ExternalHelpSearchRoot = Split-Path -Path $Path -Parent
         $PowerShellFiles = $Path
     }
 
@@ -145,6 +147,7 @@ Function Invoke-PSCodeHealth {
         Write-VerboseOutput -Message 'Found the following PowerShell files in the directory :'
         Write-VerboseOutput -Message "$($PowerShellFiles | Out-String)"
     }
+    $Script:ExternalHelpCommandNames = Get-ExternalHelpCommand -Path $ExternalHelpSearchRoot
 
     $FunctionDefinitions = Get-FunctionDefinition -Path $PowerShellFiles
     [System.Collections.ArrayList]$FunctionHealthRecords = @()

Tests/TestData/InvalidHelp/en-US/Invalid-help.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<helpItems schema="maml">
+
+<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">

Tests/TestData/TestHelp/ExternalHelp.psm1

@@ -0,0 +1,18 @@
+Function Public () {
+<#
+.SYNOPSIS
+    This cmdlet configures nothing and does it remarkably well.
+
+.DESCRIPTION
+    This cmdlet configures nothing and does it remarkably well.
+    It takes objects as input and it sets nothing to 42.
+#>
+
+    Function Nested ($InputObject) {
+        Get-Item $InputObject
+    }
+}
+
+Function Get-PlasterTemplate ($InputObject) {
+    Get-Item $InputObject
+}

Tests/Unit/Private/Get-ExternalHelpCommand.Tests.ps1

@@ -0,0 +1,42 @@
+$ModuleName = 'PSCodeHealth'
+Import-Module "$PSScriptRoot\..\..\..\$ModuleName\$($ModuleName).psd1" -Force
+
+Describe 'Get-ExternalHelpCommand' {
+    InModuleScope $ModuleName {
+        Context 'The specified folder does not contain any external help file' {
+
+            It 'Should not throw' {
+               {Get-ExternalHelpCommand -Path $TestDrive} | Should -Not -Throw
+            }
+        }
+        Context 'The specified folder contains an external help file with invalid XML' {
+
+            $InvalidXmlFile = "$PSScriptRoot\..\..\TestData\InvalidHelp"
+
+            It 'Should not throw' {
+                {Get-ExternalHelpCommand -Path $InvalidXmlFile -WarningAction SilentlyContinue} |
+                Should -Not -Throw
+             }
+         }
+        Context 'The specified folder contains a valid external help file' {
+
+            $HelpFile = "$PSScriptRoot\..\..\TestData\TestHelp"
+            $Results = Get-ExternalHelpCommand -Path $HelpFile
+            $ExpectedCommandName = @('Get-PlasterTemplate', 'Invoke-Plaster', 'New-PlasterManifest', 'Test-PlasterManifest')
+
+            It 'Should return an object of the type [string]' {
+                Foreach ( $Result in $Results ) {
+                    $Result | Should -BeOfType [string]
+                }
+            }
+            It 'Should return 4 objects' {
+                $Results.Count | Should -Be 4
+            }
+            It 'Should return the expected command names from the external help file' {
+                Foreach ( $Result in $Results ) {
+                    $Result | Should -BeIn $ExpectedCommandName
+                }
+            }
+        }
+    }
+}