functions/_Get-ReconciledPSCommandHelp.Tests.ps1

# <copyright file="_Get-ReconciledPSCommandHelp.Tests.ps1" company="Endjin Limited">
# Copyright (c) Endjin Limited. All rights reserved.
# </copyright>

# Evaluated at discovery time so it can gate the integration Describe block below.
$platyPSAvailable = [bool](Get-Module -ListAvailable Microsoft.PowerShell.PlatyPS)

BeforeAll {
    . (Join-Path $PSScriptRoot '_ConvertTo-NormalisedPSMarkdownContent.ps1')
    . (Join-Path $PSScriptRoot '_Get-ReconciledPSCommandHelp.ps1')
    . (Join-Path $PSScriptRoot '_Sync-GeneratedPSMarkdownDoc.ps1')

    Import-Module Microsoft.PowerShell.PlatyPS -ErrorAction SilentlyContinue

    # A fixture module whose comment-based help has a multi-sentence parameter description -
    # the shape that the old Update-CommandHelp merge duplicated on every run.
    function New-FixtureModule {
        param([string] $Root)

        $moduleDir = Join-Path $Root 'Fixture'
        New-Item -ItemType Directory -Path $moduleDir -Force | Out-Null

        Set-Content -LiteralPath (Join-Path $moduleDir 'Fixture.psm1') -Value @'
function Get-FixtureThing {
    <#
    .SYNOPSIS
        Gets a fixture thing.
    .DESCRIPTION
        Returns a fixture thing for test purposes.
        This description deliberately spans several sentences.
        It exists to exercise the sentence-boundary reflow behaviour of PlatyPS.
    .PARAMETER Name
        The name of the thing to get.
        This description deliberately spans several sentences.
        It is here to exercise the sentence-boundary reflow behaviour of PlatyPS.
    .EXAMPLE
        Get-FixtureThing -Name 'widget'
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string] $Name
    )
    $Name
}
'@


        Set-Content -LiteralPath (Join-Path $moduleDir 'Fixture.psd1') -Value @'
@{
    RootModule = 'Fixture.psm1'
    ModuleVersion = '1.0.0'
    GUID = 'd7c2b8e0-1f3a-4c5b-9d6e-0a1b2c3d4e5f'
    FunctionsToExport = @('Get-FixtureThing')
}
'@


        Join-Path $moduleDir 'Fixture.psd1'
    }

    # Runs the generation the same way the GeneratePSMarkdownDocs task does: reconcile
    # CommandHelp, export to a temp folder, then sync into the target.
    function Invoke-FixtureDocGeneration {
        param(
            [string] $ManifestPath,
            [string] $TargetPath
        )

        Import-Module $ManifestPath -Force
        $moduleName = Split-Path -LeafBase $ManifestPath

        $commandHelp = _Get-ReconciledPSCommandHelp -ModuleName $moduleName -ExistingDocsPath $TargetPath

        $temp = Join-Path ([System.IO.Path]::GetTempPath()) ("zf-psdocs-test-" + [Guid]::NewGuid().ToString('N'))
        New-Item -ItemType Directory -Path $temp -Force | Out-Null
        try {
            $commandHelp | Export-MarkdownCommandHelp -OutputFolder $temp -Force | Out-Null
            _Sync-GeneratedPSMarkdownDoc -GeneratedPath (Join-Path $temp $moduleName) -TargetPath $TargetPath
        }
        finally {
            Remove-Item -LiteralPath $temp -Recurse -Force -ErrorAction SilentlyContinue
        }
    }
}

Describe '_Get-ReconciledPSCommandHelp' -Skip:(-not $platyPSAvailable) {

    BeforeEach {
        $script:manifest = New-FixtureModule -Root (Join-Path $TestDrive ([Guid]::NewGuid().ToString('N')))
        $script:docs = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N') + '-docs')
    }

    It 'produces no changes on a second run with unchanged source' {
        $first = Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs
        $first.New | Should -Contain 'Get-FixtureThing.md'

        $second = Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs
        $second.New | Should -BeNullOrEmpty
        $second.Updated | Should -BeNullOrEmpty
    }

    It 'does not accumulate duplicated parameter descriptions across many runs' {
        $sentence = 'It is here to exercise the sentence-boundary reflow behaviour of PlatyPS.'
        1..5 | ForEach-Object { Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs | Out-Null }

        $content = Get-Content -Raw -LiteralPath (Join-Path $script:docs 'Get-FixtureThing.md')
        ([regex]::Matches($content, [regex]::Escape($sentence))).Count | Should -Be 1
    }

    It 'preserves a hand-authored section that comment-based help cannot express' {
        Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs | Out-Null
        $file = Join-Path $script:docs 'Get-FixtureThing.md'

        # Author a RELATED LINKS entry directly in the markdown (as a maintainer would).
        $withLink = (Get-Content -Raw -LiteralPath $file) -replace
            '(?s)## RELATED LINKS.*$', "## RELATED LINKS`n`n- [Fabric REST API](https://learn.microsoft.com/rest/api/fabric/)`n"
        Set-Content -LiteralPath $file -Value $withLink -NoNewline

        $result = Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs
        $result.Updated | Should -Not -Contain 'Get-FixtureThing.md'
        Get-Content -Raw -LiteralPath $file | Should -Match ([regex]::Escape('- [Fabric REST API](https://learn.microsoft.com/rest/api/fabric/)'))
    }

    It 'restores a parameter description that was manually duplicated' {
        Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs | Out-Null
        $file = Join-Path $script:docs 'Get-FixtureThing.md'

        $drifted = (Get-Content -Raw -LiteralPath $file) -replace
            'The name of the thing to get\.', "The name of the thing to get.`nThe name of the thing to get."
        Set-Content -LiteralPath $file -Value $drifted -NoNewline

        $result = Invoke-FixtureDocGeneration -ManifestPath $script:manifest -TargetPath $script:docs
        $result.Updated | Should -Contain 'Get-FixtureThing.md'
        ([regex]::Matches((Get-Content -Raw -LiteralPath $file), 'The name of the thing to get\.')).Count |
            Should -Be 1
    }
}