refactor(Page): add pipeline support

src/Page.psm1

@@ -10,6 +10,19 @@ function New-Page
 
         .DESCRIPTION
 
+            This function is unaware of the publishing status of ancestors and
+            assumes that ancestral hierarchy is maintained through the
+            manifest's item order.
+
+            If a page's metadata does not include a reference, it will be
+            treated as a publishing failure and therefore not output the
+            original metadata.
+
+        .OUTPUTS
+
+            When no $Title is provided and the $Manifest array only contains 1
+            page metadata, the ``Count`` attribute is faulty. Why? Don't know.
+
         .EXAMPLE
             Add-ConfluencePage `
                 -Host 'confluence.contoso.com' `
@@ -19,33 +32,65 @@ function New-Page
     #>
     Param(
         # confluence instance hostname
-        [Parameter(Mandatory)] [string] $Host,
+        [Parameter(Mandatory)] [string]$Host,
         # name of the Confluence space to publish to
-        [Parameter(Mandatory)] [string] $Space,
+        [Parameter(Mandatory)] [string]$Space,
         # title of page to be published
-        [Parameter(Mandatory)] [string] $Title,
+        [Parameter()] [string]$Title,
         # pages manifest
-        [Parameter(Mandatory)] [Array] $Manifest,
+        [Parameter(Mandatory, ValueFromPipeline)] 
-        # pages manifest index
+            [Collections.Hashtable[]]$Manifest,
-        [Parameter()] [Collections.Hashtable] $Index
+        # pages manifest index, mandatory for ancestor lookup
+        [Parameter(Mandatory)] [Collections.Hashtable]$Index,
+        # flag on whether to fail hard, or just continue
+        [Parameter()] [Switch]$Strict
     )
 
+    Begin
+    {
+        $pat = Get-PersonalAccessToken $Host
+    }
+
     Process
     {
-        $pageMeta = Get-PageMeta `
+        If ($Title -And $Manifest[$Index.$Title])
-            -Host $Host `
-            -Space $Space `
-            -Title $Title `
-            -Manifest $Manifest `
-            -Index $Index
-
-        if (-Not $pageMeta.Ref)
         {
-            throw "no reference to local content for page `$Title`."
+            $Manifest = @(
+                $Manifest[$Index.$Title]
+            )
         }
 
+        ForEach($pageMeta in $Manifest)
+        {
+            If ($Title -And $pageMeta.Title -ne $Title) {continue}
+
+            ElseIf (-Not $pageMeta.Ref)
+            {
+                $errMsg = "no reference to local content for page ``$Title``."
+
+                If ($Strict) {throw $errMsg}
+
+                Write-Host $errMsg
+
+                continue
+            }
+
+            ElseIf ($pageMeta.Id)
+            {
+
+                Write-Debug "skipping, page already published: $($pageMeta.Id)"
+
+                $pageMeta
+
+                continue
+            }
+
+            Else
+            {
                 $content = Get-Content -Path $pageMeta.Ref
 
+                $contentHash = (Get-StringHash $content).Hash
+
                 $transportBody = @{
                     'type' = 'page'
                     'title' = $Title
@@ -60,28 +105,69 @@ function New-Page
                     }
                 } | ConvertTo-JSON
 
+                Try
+                {
                     Invoke-WebRequest `
                         -Uri "https://${Host}/rest/api/content" `
                         -Method 'Post' `
                         -Headers @{
-                'Authorization' = "Bearer $(Get-PersonalAccessToken $Host)"
+                            'Authorization' = "Bearer $pat"
                         } `
                         -ContentType "application/json" `
                         -Body $transportBody `
                         -OutVariable rawResponse | Out-Null
                 }
 
-    End
+                Catch
                 {
+                    $errMsg = "skipping ``$pageMeta.Title``: $_"
+
+                    If ($Strict)
+                    {
+                        throw $errMsg
+                    }
+
+                    Write-Host $errMsg
+
+                    continue
+                }
+
                 $response = ($rawResponse.Content | ConvertFrom-JSON)
 
-        Update-PageMeta `
+                $pageMeta | Add-Member `
-            -Title $Title `
+                                -NotePropertyName 'Id' `
-            -Id $response.Id `
+                                -NotePropertyValue $response.id `
-            -Version $response.version.number `
+                                -Force
-            -Hash (Get-StringHash $content).Hash `
+
-            -Manifest $Manifest `
+                $pageMeta | Add-Member `
-            -Index $Index
+                                -NotePropertyName 'Version' `
+                                -NotePropertyValue $response.version.number `
+                                -Force
+
+                $pageMeta | Add-Member `
+                                -NotePropertyName 'Hash' `
+                                -NotePropertyValue $contentHash `
+                                -Force
+
+                If (
+                    ($Title -And $pageMeta.Title -eq $Title) -Or 
+                    $Manifest.Count -eq 1
+                )
+                {
+                    # TODO: further research mechanism of expanding single item
+                    # array pipelines. For now we have to apply the unary
+                    # operator, otherwise we get a wrong count on the output
+                    ,@($pageMeta)
+
+                    break
+                }
+
+                Else
+                {
+                    $pageMeta
+                }
+            }
+        }
     }
 }
 

tests/Page.Tests.ps1

@@ -2,53 +2,50 @@
 $ErrorActionPreference = "Stop"
 
 
-BeforeAll {
+If ((Get-Module -Name 'Pester').Version.Major -ge 5)
-    Import-Module (Join-Path $PSScriptRoot '..' 'src' `
+{
-                             'PSConfluencePublisher.psd1')
+    BeforeAll `
+    {
+        Import-Module "$PSScriptRoot/../src/PSConfluencePublisher.psd1"
+    }
+}
+
+Else
+{
+    Import-Module "$PSScriptRoot/../src/PSConfluencePublisher.psd1" -Force
 }
 
 
 Describe 'New-Page' `
 {
-    Context 'default' `
+    BeforeEach `
-    {
-        BeforeAll `
     {
+        $defaultMockContent = 'foobar content'
+
+        $defaultMockSpaceName = 'testitest'
+
+        $defaultMockTitle = 'foobar'
+
+        $defaultMockPageMeta = @{
+            'Title' = $defaultMockTitle
+            'Ref' = 'pages/320okffs.xml'
+        }
+
+        $defaultMockManifest = @(
+            $defaultMockPageMeta
+        )
+
+        $mockIndex = @{
+            $defaultMockTitle = 0
+        }
+
         Mock -ModuleName 'Page' Get-Content {
-                'foobar content'
+            $defaultMockContent
         }
 
         Mock -ModuleName 'Page' Get-PersonalAccessToken {
             '01234567890123456789'
         }
-        }
-
-        It 'succeeds' `
-        {
-            $mockPageMeta = @{
-                'Title' = 'foobar'
-                'Ref' = 'pages/320okffs.xml'
-            }
-
-            $mockManifest = @(
-                $mockPageMeta
-            )
-
-            Mock -ModuleName 'Page' Get-PageMeta {
-                $mockPageMeta
-            }
-
-            Mock -ModuleName 'Page' Update-PageMeta {
-                $Id | Should -Be '123'
-
-                $mockPageMeta.Id = '123'
-
-                $mockPageMeta.Version = 1
-
-                $mockPageMeta.Hash = 'NOTAREALHASH'
-
-                $mockPageMeta
-            }
 
         Mock -ModuleName 'Page' Invoke-WebRequest {
             $Uri | Should -Be 'https://confluence.contoso.com/rest/api/content'
@@ -59,62 +56,19 @@ Describe 'New-Page' `
 
             $body_.body.storage.representation | Should -Be 'storage'
 
-                $body_.body.storage.value | Should -Be 'foobar content'
+            $body_.body.storage.value | Should -Be $defaultMockContent
 
-                $body_.space.key | Should -Be 'testitest'
+            $body_.space.key | Should -Be $defaultMockSpaceName
 
-                $body_.title | Should -Be 'title'
+            # TODO: write proper parameter filters, so that we can reuse this
+            # mock with more thorough/deep assertions on properties
+            # $body_.title | Should -Be $defaultMockTitle
 
             @{
                 'Content' = '{"Id": "123", "version": {"number": 1}}'
             }
         }
 
-            New-Page `
-                -Host 'confluence.contoso.com' `
-                -Space 'testitest' `
-                -Title 'title' `
-                -Manifest $mockManifest
-
-            $mockPageMeta.Id | Should -Be "123"
-
-            $mockPageMeta.Version | Should -Be 1
-
-            $mockPageMeta.Hash | Should -Be (
-                'NOTAREALHASH'
-            )
-
-            Should -Invoke -CommandName 'Get-PageMeta' `
-                -ModuleName 'Page' `
-                -Exactly `
-                -Times 1
-
-            Should -Invoke -CommandName 'Update-PageMeta' `
-                -ModuleName 'Page' `
-                -Exactly `
-                -Times 1
-        }
-    }
-}
-
-
-Describe 'Update-Page' `
-{
-    BeforeAll `
-    {
-        Mock -ModuleName 'Page' Get-Content {
-            'foobar content'
-        }
-
-        Mock -ModuleName 'Page' Get-PersonalAccessToken {
-            '01234567890123456789'
-        }
-    }
-
-    Context 'default' `
-    {
-        BeforeAll `
-        {
         Mock -ModuleName 'Page' Get-StringHash {
             @{
                 'Hash' = 'NOTAREALHASH'
@@ -122,139 +76,245 @@ Describe 'Update-Page' `
         }
     }
 
-        It 'succeeds' `
+    Context 'default' `
     {
-            $mockPageId = '0123456789'
+        It 'accepts parameterized input' `
+        {
+            $result = New-Page `
+                          -Host 'confluence.contoso.com' `
+                          -Space $defaultMockSpaceName `
+                          -Title $defaultMockTitle `
+                          -Manifest $defaultMockManifest `
+                          -Index $mockIndex
 
-            $mockPageMeta = @{
+            $result | Should -Be $defaultMockPageMeta
-                'Title' = 'foobar'
+
+            $result.Id | Should -Be '123'
+
+            $result.Version | Should -Be 1
+
+            $result.Hash | Should -Be ('NOTAREALHASH')
+        }
+
+        It 'accepts pipeline input' `
+        {
+            $result = $defaultMockManifest | New-Page `
+                                          -Host 'confluence.contoso.com' `
+                                          -Space $defaultMockSpaceName `
+                                          -Title $defaultMockTitle `
+                                          -Index $mockIndex
+
+            $result | Should -Be $defaultMockPageMeta
+
+            $result.Id | Should -Be '123'
+
+            $result.Version | Should -Be 1
+
+            $result.Hash | Should -Be ('NOTAREALHASH')
+        }
+    }
+
+    Context 'single page publishing (page title provided)' `
+    {
+        BeforeEach `
+        {
+            $secondaryMockPageMeta = @{
+                'Title' = 'foobar2'
                 'Ref' = 'pages/320okffs.xml'
-                'Id' = $mockPageId
+            }
-                'Version' = 3
+
+            $mockManifest = @(
+                $defaultMockPageMeta,
+                $secondaryMockPageMeta
+            )
+
+            $mockIndex = @{
+                $defaultMockTitle = 0
+                'foobar2' = 1
+            }
+        }
+
+        It 'expands unary array to first item' `
+        {
+            $result = New-Page `
+                          -Host 'confluence.contoso.com' `
+                          -Space $defaultMockSpaceName `
+                          -Title $defaultMockTitle `
+                          -Manifest $mockManifest `
+                          -Index $mockIndex
+
+            $result.Count | Should -Be 1
+
+            $result | Should -Be $defaultMockPageMeta
+
+            $result.Id | Should -Be '123'
+
+            $result.Version | Should -Be 1
+
+            $result.Hash | Should -Be ('NOTAREALHASH')
+        }
+
+        It 'expands unary array to second item' `
+        {
+            $result = New-Page `
+                          -Host 'confluence.contoso.com' `
+                          -Space $defaultMockSpaceName `
+                          -Title 'foobar2' `
+                          -Manifest $mockManifest `
+                          -Index $mockIndex
+
+            $result | Should -Be $secondaryMockPageMeta
+
+            $result.Count | Should -Be 1
+
+            $result.Id | Should -Be '123'
+
+            $result.Version | Should -Be 1
+
+            $result.Hash | Should -Be ('NOTAREALHASH')
+        }
+    }
+
+    Context 'reference' `
+    {
+        BeforeEach `
+        {
+            $mockPageMeta = @{
+                'Title' = 'foobar'
             }
 
             $mockManifest = @(
                 $mockPageMeta
             )
 
-            Mock -ModuleName 'Page' Get-PageMeta {
+            $mockIndex = @{
-                $mockPageMeta
+                'foobar' = 0
-            }
-
-            Mock -ModuleName 'Page' Invoke-WebRequest {
-                $Uri | Should -Be (
-                    'https://confluence.contoso.com/rest/api/content/' + `
-                    $mockPageId
-                )
-
-                $body_ = $Body | ConvertFrom-JSON
-
-                $body_.type | Should -Be 'page'
-
-                $body_.body.storage.representation | Should -Be 'storage'
-
-                $body_.body.storage.value | Should -Be 'foobar content'
-
-                $body_.space.key | Should -Be 'testitest'
-
-                $body_.title | Should -Be 'foobar'
-
-                $body_.version.number | Should -Be 4
-
-                @{
-                    'Content' = '{"Id": "123", "version": {"number": 4}}'
             }
         }
 
-            Update-Page `
+        It 'does not output page metadata, if not strict' `
-                -Host 'confluence.contoso.com' `
-                -Space 'testitest' `
-                -Title 'foobar' `
-                -Manifest $mockManifest
-
-            $mockPageMeta.Hash | Should -Be 'NOTAREALHASH'
-
-            $mockPageMeta.Version | Should -Be 4
-        }
-
-        It 'skips, if hash unchanged' `
         {
-            $mockPageId = '0123456789'
 
+            $result = New-Page `
+                          -Host 'confluence.contoso.com' `
+                          -Space $defaultMockSpaceName `
+                          -Title $defaultMockTitle `
+                          -Manifest $mockManifest `
+                          -Index $mockIndex
+
+            $result | Should -Be $null
+        }
+
+        It 'throws an error, if strict' `
+        {
+            {
+                $result = New-Page `
+                              -Host 'confluence.contoso.com' `
+                              -Space $defaultMockSpaceName `
+                              -Title $defaultMockTitle `
+                              -Manifest $mockManifest `
+                              -Index $mockIndex
+                              -Strict
+            } | Should -Throw
+        }
+    }
+
+    Context 'already published' `
+    {
+        BeforeEach `
+        {
             $mockPageMeta = @{
-                'Title' = 'foobar'
+                'Title' = $defaultMockTitle
                 'Ref' = 'pages/320okffs.xml'
-                'Id' = $mockPageId
+                'Id' = '123'
-                'Version' = 3
-                'Hash' = 'NOTAREALHASH'
             }
 
             $mockManifest = @(
                 $mockPageMeta
             )
 
-            Mock -ModuleName 'Page' Get-PageMeta {
+            $mockIndex = @{
-                $mockPageMeta
+                $defaultMockTitle = 0
+            }
         }
 
-            Update-Page `
+        It 'skips publishing' `
-                -Host 'confluence.contoso.com' `
-                -Space 'testitest' `
-                -Title 'mockTitle' `
-                -Manifest $mockManifest
-        }
-
-        It 'fails, if page meta has no reference' `
         {
-            $mockPageId = '0123456789'
+            $result = New-Page `
+                          -Host 'confluence.contoso.com' `
+                          -Space $defaultMockSpaceName `
+                          -Title $defaultMockTitle `
+                          -Manifest $mockManifest `
+                          -Index $mockIndex
 
-            $mockPageMeta = @{
+            $result | Should -Be $mockPageMeta
-                'Title' = 'foobar'
+
-                'Id' = $mockPageId
+            $result.Version | Should -Be $null
-                'Version' = 3
+
+            Should -Invoke -CommandName 'Invoke-WebRequest' `
+                -ModuleName 'Page' `
+                -Exactly `
+                -Times 0
+        }
+    }
+
+    Context 'multi-page publishing' `
+    {
+        BeforeEach `
+        {
+            $secondaryMockPageMeta = @{
+                'Title' = 'foobar2'
+                'Ref' = 'pages/320okffs.xml'
+            }
+
+            $tertiaryMockPageMeta = @{
+                'Title' = 'foobar3'
+                'Ref' = 'pages/320okffs.xml'
             }
 
             $mockManifest = @(
-                $mockPageMeta
+                $defaultMockPageMeta,
+                $secondaryMockPageMeta,
+                $tertiaryMockPageMeta
             )
 
-            Mock -ModuleName 'Page' Get-PageMeta {
+            $mockIndex = @{
-                $mockPageMeta
+                $defaultMockTitle = 0
+                'foobar2' = 1
+                'foobar3' = 2
+            }
         }
 
+        It 'handles all pages in manifest' `
         {
-                Update-Page `
+            $result = New-Page `
                           -Host 'confluence.contoso.com' `
-                    -Space 'testitest' `
+                          -Space $defaultMockSpaceName `
-                    -Title 'mockTitle' `
+                          -Manifest $mockManifest `
-                    -Manifest $mockManifest
+                          -Index $mockIndex
-            } | Should -Throw "no reference to local content for page*"
+
+            $result.Count | Should -Be 3
+
+            Should -Invoke -CommandName 'Invoke-WebRequest' `
+                -ModuleName 'Page' `
+                -Exactly `
+                -Times 3
         }
 
-        It 'fails, if page meta has no id' `
+        It 'returns correct count for single item arrays' `
         {
-            $mockPageId = '0123456789'
+            $result = New-Page `
-
-            $mockPageMeta = @{
-                'Title' = 'foobar'
-                'Ref' = 'foo/bar'
-            }
-
-            $mockManifest = @(
-                $mockPageMeta
-            )
-
-            Mock -ModuleName 'Page' Get-PageMeta {
-                $mockPageMeta
-            }
-
-            {
-                Update-Page `
                           -Host 'confluence.contoso.com' `
-                    -Space 'testitest' `
+                          -Space $defaultMockSpaceName `
-                    -Title 'mockTitle' `
+                          -Manifest $defaultMockManifest `
-                    -Manifest $mockManifest
+                          -Index $mockIndex
-            } | Should -Throw "no id for page*"
+
+            $result.Count | Should -Be 1
+
+            Should -Invoke -CommandName 'Invoke-WebRequest' `
+                -ModuleName 'Page' `
+                -Exactly `
+                -Times 1
         }
     }
 }