Update build process

.vscode/launch.json

@@ -0,0 +1,33 @@
+{
+    "version": "0.2.0",
+    "configurations": [{
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Pester Tests",
+            "script": "Invoke-Pester",
+            "args": [],
+            "cwd": "${workspaceRoot}"
+        },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch (current file)",
+            "script": "${file}",
+            "args": [],
+            "cwd": "${file}"
+        },
+        {
+            "type": "PowerShell",
+            "request": "attach",
+            "name": "PowerShell Attach to Host Process",
+            "processId": "${command.PickPSHostProcess}",
+            "runspaceId": 1
+        },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Interactive Session",
+            "cwd": "${workspaceRoot}"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,15 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+    "files.encoding": "utf8",
+    "files.eol": "\r\n",
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true,
+    "editor.tabSize": 4,
+    "[markdown]": {
+        "editor.wordwrap": "on",
+        "editor.renderWhitespace": "all",
+        "editor.acceptSuggestionOnEnter": false,
+        "editor.rulers": [80],
+        "editor.trimAutoWhitespace": false
+    },
+}

.vscode/tasks.json

@@ -0,0 +1,56 @@
+// Available variables which can be used inside of strings.
+// ${workspaceRoot}: the root folder of the team
+// ${file}: the current opened file
+// ${relativeFile}: the current opened file relative to workspaceRoot
+// ${fileBasename}: the current opened file's basename
+// ${fileDirname}: the current opened file's dirname
+// ${fileExtname}: the current opened file's extension
+// ${cwd}: the current working directory of the spawned process
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    // Start PowerShell
+    "windows": {
+        "command": "${env:windir}\\sysnative\\windowspowershell\\v1.0\\PowerShell.exe",
+        "args": [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass"
+        ]
+    },
+    "linux": {
+        "command": "/usr/bin/powershell",
+        "args": [
+            "-NoProfile"
+        ]
+    },
+    "osx": {
+        "command": "/usr/local/bin/powershell",
+        "args": [
+            "-NoProfile"
+        ]
+    },
+    // Show the output window always
+    "showOutput": "always",
+    // Associate with test task runner
+    "tasks": [{
+            "taskName": "Build Help",
+            "suppressTaskName": true,
+            "args": [
+                "Write-Host 'Invoking platyPS'; New-ExternalHelp -Path .\\docs\\en-US -OutputPath .\\ConfluencePS\\en-US -Force;",
+                "Invoke-Command { Write-Host 'Completed Build task in task runner.' }"
+            ]
+        },
+        {
+            "taskName": "Test",
+            "suppressTaskName": true,
+            "isTestCommand": true,
+            "args": [
+                "Write-Host 'Invoking Pester'; Invoke-Pester -PesterOption @{IncludeVSCodeMarker=$true};",
+                "Invoke-Command { Write-Host 'Completed Test task in task runner.' }"
+            ],
+            "problemMatcher": "$pester"
+        }
+    ]
+}

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [1.0] - 2017-11-18

SnipeItPS.build.ps1

@@ -10,15 +10,20 @@ if ($PSBoundParameters.ContainsKey('Verbose')) {
 if (!($env:releasePath)) {
     $releasePath = "$BuildRoot\Release"
 }
-else {
+elseif ($env:releasePath) {
     $releasePath = $env:releasePath
 }
+else {
+    $releasePath = "$($pwd.Path)\Release"
+}
 $env:PSModulePath = "$($env:PSModulePath);$releasePath"
 
+Import-Module BuildHelpers
 
 # Ensure Invoke-Build works in the most strict mode.
 Set-StrictMode -Version Latest
 
+# region debug information
 task ShowDebug {
     Write-Build Gray
     Write-Build Gray ('Project name:               {0}' -f $env:APPVEYOR_PROJECT_NAME)
@@ -42,12 +47,80 @@ task ShowDebug {
     Write-Build Gray
 }
 
+# Synopsis: Install pandoc to .\Tools\
+task InstallPandoc -If (-not (Test-Path Tools\pandoc.exe)) {
+    # Setup
+    if (-not (Test-Path "$BuildRoot\Tools")) {
+        $null = New-Item -Path "$BuildRoot\Tools" -ItemType Directory
+    }
+
+    # Get latest bits
+    $latestRelease = "https://github.com/jgm/pandoc/releases/download/1.19.2.1/pandoc-1.19.2.1-windows.msi"
+    Invoke-WebRequest -Uri $latestRelease -OutFile "$($env:temp)\pandoc.msi"
+
+    # Extract bits
+    $null = New-Item -Path $env:temp\pandoc -ItemType Directory -Force
+    Start-Process -Wait -FilePath msiexec.exe -ArgumentList " /qn /a `"$($env:temp)\pandoc.msi`" targetdir=`"$($env:temp)\pandoc\`""
+
+    # Move to Tools folder
+    Copy-Item -Path "$($env:temp)\pandoc\Pandoc\pandoc.exe" -Destination "$BuildRoot\Tools\"
+    Copy-Item -Path "$($env:temp)\pandoc\Pandoc\pandoc-citeproc.exe" -Destination "$BuildRoot\Tools\"
+
+    # Clean
+    Remove-Item -Path "$($env:temp)\pandoc" -Recurse -Force
+}
+# endregion
+
+# region test
+task Test RapidTest
+
+# Synopsis: Using the "Fast" Test Suit
+task RapidTest PesterTests
+# Synopsis: Using the complete Test Suit, which includes all supported Powershell versions
+task FullTest TestVersions
+
+# Synopsis: Warn about not empty git status if .git exists.
+task GitStatus -If (Test-Path .git) {
+    $status = exec { git status -s }
+    if ($status) {
+        Write-Warning "Git status: $($status -join ', ')"
+    }
+}
+
+task TestVersions TestPS3, TestPS4, TestPS4, TestPS5
+task TestPS3 {
+    exec {powershell.exe -Version 3 -NoProfile Invoke-Build PesterTests}
+}
+task TestPS4 {
+    exec {powershell.exe -Version 4 -NoProfile Invoke-Build PesterTests}
+}
+task TestPS5 {
+    exec {powershell.exe -Version 5 -NoProfile Invoke-Build PesterTests}
+}
+
+# Synopsis: Invoke Pester Tests
+task PesterTests, {
+    try {
+        $result = Invoke-Pester -PassThru -OutputFile "$BuildRoot\TestResult.xml" -OutputFormat "NUnitXml"
+        if ($env:APPVEYOR_PROJECT_NAME) {
+            Add-TestResultToAppveyor -TestFile "$BuildRoot\TestResult.xml"
+            Remove-Item "$BuildRoot\TestResult.xml" -Force
+        }
+        assert ($result.FailedCount -eq 0) "$($result.FailedCount) Pester test(s) failed."
+    }
+    catch {
+        throw
+    }
+}
+# endregion
+
 # region build
 # Synopsis: Build shippable release
-task Build GenerateRelease, UpdateManifest
+task Build GenerateRelease, ConvertMarkdown, UpdateManifest
+
 
 # Synopsis: Generate .\Release structure
-task GenerateRelease {
+task GenerateRelease, {
     # Setup
     if (-not (Test-Path "$releasePath\SnipeitPS")) {
         $null = New-Item -Path "$releasePath\SnipeitPS" -ItemType Directory
@@ -56,26 +129,20 @@ task GenerateRelease {
     # Copy module
     Copy-Item -Path "$BuildRoot\SnipeitPS\*" -Destination "$releasePath\SnipeitPS" -Recurse -Force
     # Copy additional files
-    <#$additionalFiles = @(
+    $additionalFiles = @(
         "$BuildRoot\CHANGELOG.md"
         "$BuildRoot\LICENSE"
         "$BuildRoot\README.md"
     )
-    Copy-Item -Path $additionalFiles -Destination "$releasePath\SnipeitPS" -Force#>
+    Copy-Item -Path $additionalFiles -Destination "$releasePath\SnipeitPS" -Force
 }
 
 # Synopsis: Update the manifest of the module
 task UpdateManifest GetVersion, {
-    $ModuleAlias = (Get-Alias | Where source -eq JiraPS)
-
-    Remove-Module JiraPS -ErrorAction SilentlyContinue
-    Import-Module "$releasePath\SnipeitPS\SnipeitPS.psd1"
     Update-Metadata -Path "$releasePath\SnipeitPS\SnipeitPS.psd1" -PropertyName ModuleVersion -Value $script:Version
     # Update-Metadata -Path "$releasePath\SnipeitPS\SnipeitPS.psd1" -PropertyName FileList -Value (Get-ChildItem $releasePath\SnipeitPS -Recurse).Name
-    if ($ModuleAlias) {
-        Update-Metadata -Path "$releasePath\SnipeitPS\SnipeitPS.psd1" -PropertyName AliasesToExport -Value @($ModuleAlias.Name)
-    }
-    Set-ModuleFunctions -Name "$releasePath\SnipeitPS\SnipeitPS.psd1" -FunctionsToExport ([string[]](Get-ChildItem "SnipeitPS\public\*.psm1").BaseName)
+    $functionsToExport = Get-ChildItem "$BuildRoot\SnipeitPS\Public" | ForEach-Object {$_.BaseName}
+    Set-ModuleFunctions -Name "$releasePath\SnipeitPS\SnipeitPS.psd1" -FunctionsToExport $functionsToExport
 }
 
 task GetVersion {
@@ -96,12 +163,13 @@ task GetVersion {
     $newRevision
 }
 
-
 # endregion
 
 
+
 #region Cleaning tasks
 task Clean RemoveGeneratedFiles
+
 # Synopsis: Remove generated and temp files.
 task RemoveGeneratedFiles {
     $itemsToRemove = @(
@@ -112,6 +180,6 @@ task RemoveGeneratedFiles {
     Remove-Item $itemsToRemove -Force -Recurse -ErrorAction 0
 }
 
+# endregion
 
-
-task . Build, Clean
+task . ShowDebug, Clean, Test, Build, Deploy

Tests/SnipeItPS.Tests.ps1

@@ -1,53 +1,213 @@
-$ModulePath = Split-Path -Path $PSScriptRoot -Parent
-$ModuleName = Split-Path -Path $ModulePath -Leaf
+#Requires -Modules PSScriptAnalyzer
 
-# Make sure one or multiple versions of the module are not loaded
-Get-Module -Name $ModuleName | Remove-Module
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+$projectRoot = Split-Path -Parent $here
+$moduleRoot = "$projectRoot\SnipeitPS"
 
-# Import the module and store the information about the module
-$ModuleInformation = Import-Module -Name "$ModulePath\$ModuleName.psd1" -PassThru
-$ModuleInformation | Format-List
+$manifestFile = "$moduleRoot\SnipeitPS.psd1"
+$changelogFile = "$projectRoot\CHANGELOG.md"
+$appveyorFile = "$projectRoot\appveyor.yml"
+$publicFunctions = "$moduleRoot\Public"
+$privateFunctions = "$moduleRoot\Private"
 
-# Get the functions present in the Manifest
-$ExportedFunctions = $ModuleInformation.ExportedFunctions.Values.Name
+Describe "SnipeitPS" {
+    Context "All required tests are present" {
+        # We want to make sure that every .ps1 file in the Functions directory that isn't a Pester test has an associated Pester test.
+        # This helps keep me honest and makes sure I'm testing my code appropriately.
+        It "Includes a test for each PowerShell function in the module" {
+            # Get-ChildItem -Path $publicFunctions -Filter "*.ps1" -Recurse | Where-Object -FilterScript {$_.Name -notlike '*.Tests.ps1'} | % {
+            #     $expectedTestFile = Join-Path $projectRoot "Tests\$($_.BaseName).Tests.ps1"
+            #     $expectedTestFile | Should Exist
+            # }
+        }
+    }
 
-# Get the functions present in the Public folder
-$PS1Functions = Get-ChildItem -Path "$ModulePath\Public\*.ps1"
+    Context "Manifest, changelog, and AppVeyor" {
 
-Describe "$ModuleName Module - Testing Manifest File (.psd1)" {
-    Context "Manifest" {
-        It "Should contain RootModule" {
-            $ModuleInformation.RootModule | Should Not BeNullOrEmpty
+        # These tests are...erm, borrowed...from the module tests from the Pester module.
+        # I think they are excellent for sanity checking, and all credit for the following
+        # tests goes to Dave Wyatt, the genius behind Pester.  I've just adapted them
+        # slightly to match ConfluencePS.
+
+        $script:manifest = $null
+
+        foreach ($line in (Get-Content $changelogFile))
+        {
+            if ($line -match "^\D*(?<Version>(\d+\.){1,3}\d+)")
+            {
+                $changelogVersion = $matches.Version
+                break
+            }
         }
 
-        It "Should contain ModuleVersion" {
-            $ModuleInformation.Version | Should Not BeNullOrEmpty
+        foreach ($line in (Get-Content $appveyorFile))
+        {
+            # (?<Version>()) - non-capturing group, but named Version. This makes it
+            # easy to reference the inside group later.
+
+            if ($line -match '^\D*(?<Version>(\d+\.){1,3}\d+).\{build\}')
+            {
+                $appveyorVersion = $matches.Version
+                break
+            }
         }
 
-        It "Should contain GUID" {
-            $ModuleInformation.Guid | Should Not BeNullOrEmpty
+        It "Includes a valid manifest file" {
+            {
+                $script:manifest = Test-ModuleManifest -Path $script:manifestFile -ErrorAction Stop -WarningAction SilentlyContinue
+            } | Should Not Throw
         }
 
-        It "Should contain Author" {
-            $ModuleInformation.Author | Should Not BeNullOrEmpty
+        # There is a bug that prevents Test-ModuleManifest from updating correctly when the manifest file changes. See here:
+        # https://connect.microsoft.com/PowerShell/feedback/details/1541659/test-modulemanifest-the-psmoduleinfo-is-not-updated
+
+        # As a temp workaround, we'll just read the manifest as a raw hashtable.
+        # Credit to this workaround comes from here:
+        # https://psescape.azurewebsites.net/pester-testing-your-module-manifest/
+        $script:manifest = Invoke-Expression (Get-Content $script:manifestFile -Raw)
+
+        It "Manifest file includes the correct root module" {
+            $script:manifest.RootModule | Should Be 'SnipeitPS'
         }
 
-        It "Should contain Description" {
-            $ModuleInformation.Description | Should Not BeNullOrEmpty
+        It "Manifest file includes the correct guid" {
+            $script:manifest.Guid | Should Be 'f86f4db4-1cb1-45c4-b7bf-6762531bfdeb'
         }
 
-        It "Compare the count of Function Exported and the PS1 files found" {
-            $status = $ExportedFunctions.Count -eq $PS1Functions.Count
-            $status | Should Be $true
+        It "Manifest file includes a valid version" {
+            # $script:manifest.Version -as [Version] | Should Not BeNullOrEmpty
+            $script:manifest.ModuleVersion -as [Version] | Should Not BeNullOrEmpty
         }
 
-        It "Compare the missing function" {
-            If ($ExportedFunctions.count -ne $PS1Functions.count) {
-                $Compare = Compare-Object -ReferenceObject $ExportedFunctions -DifferenceObject $PS1Functions.Basename
-                $Compare.InputObject -Join ',' | Should BeNullOrEmpty
+        It "Includes a changelog file" {
+            $changelogFile | Should Exist
+        }
+
+        # $changelogVersion = $null
+        It "Changelog includes a valid version number" {
+            $changelogVersion                | Should Not BeNullOrEmpty
+            $changelogVersion -as [Version]  | Should Not BeNullOrEmpty
+        }
+
+        It "Changelog version matches manifest version" {
+            $changelogVersion -as [Version] | Should Be ( $script:manifest.ModuleVersion -as [Version] )
+        }
+
+        # Back to me! Pester doesn't use AppVeyor, as far as I know, and I do.
+
+        It "Includes an appveyor.yml file" {
+            $appveyorFile | Should Exist
+        }
+
+        It "Appveyor.yml file includes the module version" {
+            $appveyorVersion               | Should Not BeNullOrEmpty
+            $appveyorVersion -as [Version] | Should Not BeNullOrEmpty
+        }
+
+        It "Appveyor version matches manifest version" {
+            $appveyorVersion -as [Version] | Should Be ( $script:manifest.ModuleVersion -as [Version] )
+        }
+    }
+
+    # The CI changes I'm testng now will render this section obsolete,
+    # as it should automatically patch the module manifest file with all
+    # exported function names.
+    # Leaving the code here for the moment while I can ensure those
+    # features are working correctly.
+
+    #
+    # Context "Function checking" {
+    #     $functionFiles = Get-ChildItem $publicFunctions -Filter *.ps1 |
+    #         Select-Object -ExpandProperty BaseName |
+    #         Where-Object { $_ -notlike "*.Tests" }
+
+    #     $internalFiles = Get-ChildItem $privateFunctions -Filter *.ps1 |
+    #         Select-Object -ExpandProperty BaseName |
+    #         Where-Object { $_ -notlike "*.Tests" }
+
+    #     #$exportedFunctions = $script:manifest.ExportedFunctions.Values.Name
+    #     $exportedFunctions = $script:manifest.FunctionsToExport
+
+    #     foreach ($f in $functionFiles) {
+    #         It "Exports $f" {
+    #             $exportedFunctions -contains $f | Should Be $true
+    #         }
+    #     }
+
+    #     foreach ($f in $internalFiles) {
+    #         It "Does not export $f" {
+    #             $exportedFunctions -contains $f | Should Be $false
+    #         }
+    #     }
+    # }
+
+    Context "Style checking" {
+
+        # This section is again from the mastermind, Dave Wyatt. Again, credit
+        # goes to him for these tests.
+
+        $files = @(
+            Get-ChildItem $here -Include *.ps1, *.psm1
+            Get-ChildItem $publicFunctions -Include *.ps1, *.psm1 -Recurse
+        )
+
+        It 'Source files contain no trailing whitespace' {
+            $badLines = @(
+                foreach ($file in $files)
+                {
+                    $lines = [System.IO.File]::ReadAllLines($file.FullName)
+                    $lineCount = $lines.Count
+
+                    for ($i = 0; $i -lt $lineCount; $i++)
+                    {
+                        if ($lines[$i] -match '\s+$')
+                        {
+                            'File: {0}, Line: {1}' -f $file.FullName, ($i + 1)
+                        }
+                    }
+                }
+            )
+
+            if ($badLines.Count -gt 0)
+            {
+                throw "The following $($badLines.Count) lines contain trailing whitespace: `r`n`r`n$($badLines -join "`r`n")"
+            }
+        }
+
+        It 'Source files all end with a newline' {
+            $badFiles = @(
+                foreach ($file in $files)
+                {
+                    $string = [System.IO.File]::ReadAllText($file.FullName)
+                    if ($string.Length -gt 0 -and $string[-1] -ne "`n")
+                    {
+                        $file.FullName
+                    }
+                }
+            )
+
+            if ($badFiles.Count -gt 0)
+            {
+                throw "The following files do not end with a newline: `r`n`r`n$($badFiles -join "`r`n")"
+            }
+        }
+    }
+
+    Context 'PSScriptAnalyzer Rules' {
+        $analysis = Invoke-ScriptAnalyzer -Path "$moduleRoot" -Recurse -Settings "$projectRoot\PSScriptAnalyzerSettings.psd1"
+        $scriptAnalyzerRules = Get-ScriptAnalyzerRule
+
+        forEach ($rule in $scriptAnalyzerRules)
+        {
+            It "Should pass $rule" {
+                If (($analysis) -and ($analysis.RuleName -contains $rule))
+                {
+                    $analysis |
+                        Where RuleName -EQ $rule -OutVariable failures |
+                        Out-Default
+                    $failures.Count | Should Be 0
+                }
             }
         }
     }
 }
-
-Get-Module -Name $ModuleName | Remove-Module