Update, simplify, and consolidate build scripts

.gitignore

@@ -205,4 +205,10 @@ FakesAssemblies/
 *.opt
 
 ##Our project binplace location
-PSScriptAnalyzer/
+PSScriptAnalyzer/
+
+# Vim swap files
+*.swp
+
+# Test result file
+TestResults.xml

README.md

@@ -123,25 +123,33 @@ Note: the PSScriptAnalyzer Chocolatey package is provided and supported by the c
 * Building
 
     You can either build using the `Visual Studio` solution `PSScriptAnalyzer.sln` or build using `PowerShell` specifically for your platform as follows:
-    * Windows PowerShell version 5.0 and greater
+    * The default build is for PowerShell Core
     ```powershell
-    .\buildCoreClr.ps1 -Framework net451 -Configuration Release -Build
+    .\build.ps1
+    ```
+    * Windows PowerShell version 5.0
+    ```powershell
+    .\build.ps1 -Framework full -PSVersion 5 -Configuration Release
     ```
     * Windows PowerShell version 4.0
     ```powershell
-    .\buildCoreClr.ps1 -Framework net451 -Configuration PSV4Release -Build
+    .\build.ps1 -Framework full -PSVersion 4 -Configuration Release
     ```
     * Windows PowerShell version 3.0
     ```powershell
-    .\buildCoreClr.ps1 -Framework net451 -Configuration PSV3Release -Build
+    .\build.ps1 -Framework full -PSVersion 3 -Configuration Release
     ```
     * PowerShell Core
     ```powershell
-    .\buildCoreClr.ps1 -Framework netstandard2.0 -Configuration Release -Build
+    .\buildCoreClr.ps1 -Framework core -Configuration Release -Build
+    ```
+* Build documentation
+    ```powershell
+    .\build.ps1 -Documentation
     ```
-* Build documenatation
+* Build all versions (PowerShell v3, v4, v5, and Core) and documentation
     ```powershell
-    .\build.ps1 -BuildDocs
+    .\build.ps1 -All
     ```
 * Import the module
 ```powershell
@@ -157,12 +165,25 @@ For adding/removing resource strings in the `*.resx` files, it is recommended to
 #### Tests
 Pester-based ScriptAnalyzer Tests are located in `path/to/PSScriptAnalyzer/Tests` folder.
 
-* Ensure [Pester 4.3.1](https://www.powershellgallery.com/packages/Pester/4.3.1) is installed
-* Copy `path/to/PSScriptAnalyzer/out/PSScriptAnalyzer` to a folder in `PSModulePath`
+* Ensure [Pester 4.3.1](https://www.powershellgallery.com/packages/Pester/4.3.1) or higher is installed
+* Ensure that the documentation has been built (`./build.ps1 -Documentation`) 
 * In the root folder of your local repository, run:
 ``` PowerShell
-$testScripts = ".\Tests\Engine",".\Tests\Rules",".\Tests\Documentation"
-Invoke-Pester -Script $testScripts
+./build -Test
+```
+
+To retrieve the results of the run, you can use the tools which are part of the build module (`build.psm1`)
+
+```powershell
+Import-Module ./build.psm1
+Get-TestResults
+```
+
+To retrieve only the errors, you can use the following:
+
+```powershell
+Import-Module ./build.psm1
+Get-TestFailures
 ```
 
 [Back to ToC](#table-of-contents)

Tests/Engine/CustomizedRule.tests.ps1

@@ -97,7 +97,7 @@ Describe "Test importing correct customized rules" {
 		It "will show the custom rules when given a glob" {
 			# needs fixing for Linux
 			$expectedNumRules = 4
-			if ($IsLinux -or $IsMacOS)
+			if ($IsLinux)
 			{
 				$expectedNumRules = 3
 			}
@@ -113,7 +113,7 @@ Describe "Test importing correct customized rules" {
 		It "will show the custom rules when given glob with recurse switch" {
 			# needs fixing for Linux
 			$expectedNumRules = 5
-			if ($IsLinux -or $IsMacOS)
+			if ($IsLinux)
 			{
 				$expectedNumRules = 4
 			}

build.ps1

@@ -1,183 +1,72 @@
-# This function might be a partially out of date and only the -BuildDoc switch is guaranteed to work since it is used and needed for the build process.
-[CmdletBinding()]
-param(
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
 
-    [Parameter(ParameterSetName='Build')]
-    [ValidateSet('PSV3 Debug','PSV3 Release','Debug','Release')]
-    [string] $Configuration = 'Debug',
+[CmdletBinding(DefaultParameterSetName="BuildOne")]
+param(
+    [Parameter(ParameterSetName="BuildAll")]
+    [switch]$All,
 
-    [Parameter(ParameterSetName='Build')]
-    [switch] $BuildDocs = $false,
+    [Parameter(ParameterSetName="BuildOne")]
+    [ValidateSet("full", "core")]
+    [string]$Framework = "core",
 
-    [Parameter(ParameterSetName='Build')]
-    [switch] $CleanOutput = $false,
+    [Parameter(ParameterSetName="BuildOne")]
+    [ValidateSet("3","4","5")]
+    [string]$PSVersion = "5",
 
-    [Parameter(ParameterSetName='Build')]
-    [switch] $Install = $false,
+    [Parameter(ParameterSetName="BuildOne")]
+    [Parameter(ParameterSetName="BuildAll")]
+    [ValidateSet("Debug", "Release")]
+    [string]$Configuration = "Debug",
 
-    [Parameter(ParameterSetName='Build')]
-    [switch] $Uninstall = $false,
+    [Parameter(ParameterSetName="BuildDoc")]
+    [switch]$Documentation,
 
-    [Parameter(ParameterSetName='Test')]
-    [switch] $Test = $false,
+    [Parameter(ParameterSetName='BuildAll')]
+    [Parameter(ParameterSetName='BuildOne')]
+    [switch]$Clobber,
 
-    [Parameter(ParameterSetName='Test')]
-    [switch] $Engine = $false,
+    [Parameter(Mandatory=$true,ParameterSetName='Clean')]
+    [switch] $Clean,
 
-    [Parameter(ParameterSetName='Test')]
-    [switch] $Rules = $false,
+    [Parameter(Mandatory=$true,ParameterSetName='Test')]
+    [switch] $Test,
 
     [Parameter(ParameterSetName='Test')]
-    [switch] $RunInDifferentProcess = $false
+    [switch] $InProcess
 )
 
-# Some cmdlets like copy-item do not respond to the $verbosepreference variable
-# hence we set it explicitly
-$verbosity = $false
-if ($VerbosePreference.Equals([System.Management.Automation.ActionPreference]'Continue'))
-{
-    $verbosity = $true
-}
-
-Function CreateIfNotExists([string] $folderPath)
-{
-    if (-not (Test-Path $folderPath))
-    {
-        New-Item -Path $folderPath -ItemType Directory -Verbose:$verbosity
-    }
-}
-
-$projectRoot = Resolve-path (Split-Path $MyInvocation.InvocationName)
-$solutionPath = Join-Path $projectRoot 'PSScriptAnalyzer.sln'
-$outPath = Join-Path $projectRoot 'out'
-$destinationPath = Join-Path $outPath PSScriptAnalyzer
-
-if (-not (Test-Path $solutionPath))
-{
-    $errMsg = "{0} not the right directory" -f $solutionPath
-    throw $errMsg
-}
-
-if ($CleanOutput)
-{
-    Remove-Item -Recurse $outPath\* -Force -Verbose:$verbosity
-}
-
-if ($BuildDocs)
-{
-    $docsPath = Join-Path $projectRoot 'docs'
-    $markdownDocsPath = Join-Path $docsPath 'markdown'
-    $outputDocsPath = Join-Path $destinationPath en-US
-
-    CreateIfNotExists($outputDocsPath)
-
-    # Build documentation using platyPS
-    $requiredVersionOfplatyPS = 0.9
-    if ($null -eq (Get-Module platyPS -ListAvailable -Verbose:$verbosity | Where-Object { $_.Version -ge $requiredVersionOfplatyPS }))
-    {
-        "Cannot find required minimum version $requiredVersionOfplatyPS of platyPS. Please install it from https://www.powershellgallery.com/packages/platyPS/ using e.g. the following command: Install-Module platyPS"
-    }
-    if ($null -eq (Get-Module platyPS -Verbose:$verbosity))
-    {
-        Import-Module platyPS -Verbose:$verbosity
-    }
-    if (-not (Test-Path $markdownDocsPath -Verbose:$verbosity))
-    {
-        throw "Cannot find markdown documentation folder."
-    }
-    New-ExternalHelp -Path $markdownDocsPath -OutputPath $outputDocsPath -Force -Verbose:$verbosity
-}
-
-# Appveyor errors out due to $profile being null. Hence...
-$moduleRootPath = "$HOME/Documents/WindowsPowerShell/Modules"
-if ($null -ne $profile)
-{
-    $moduleRootPath = Join-Path (Split-Path $profile) 'Modules'
-}
-$modulePSSAPath = Join-Path $moduleRootPath 'PSScriptAnalyzer'
-if ($Install)
-{
-    if (-not (Test-Path $moduleRootPath))
-    {
-        New-Item -Path $moduleRootPath -ItemType Directory -Force -Verbose:$verbosity
-    }
-    if (-not (Test-Path -Path $destinationPath))
-    {
-        throw "Please build the module first."
-    }
-    Copy-Item -Path $destinationPath -Destination $modulePSSAPath -Recurse -Verbose:$verbosity
-}
-
-if ($Test)
-{
-    Import-Module -Name Pester -MinimumVersion 4.3.1 -ErrorAction Stop
-    Function GetTestRunnerScriptContent($testPath)
-    {
-        $x = @"
-        cd $testPath
-        Invoke-Pester
-"@
-        return $x
-    }
-
-    Function CreateTestRunnerScript($testPath)
-    {
-        $tmptmpFilePath = [System.IO.Path]::GetTempFileName()
-        $tmpFilePath = $tmptmpFilePath + '.ps1'
-        Move-Item $tmptmpFilePath $tmpFilePath -Verbose:$verbosity
-        $content = GetTestRunnerScriptContent $testPath
-        Set-Content -Path $tmpFilePath -Value $content -Verbose:$verbosity
-        return $tmpFilePath
-    }
-
-    Function GetTestPath($TestType)
-    {
-        if ($TestType -eq "engine")
-        {
-            $testPath = Join-Path $projectRoot "Tests/Engine"
-        }
-        else
-        {
-            $testPath = Join-Path $projectRoot "Tests/Rules"
+END {
+    Import-Module -Force (Join-Path $PSScriptRoot build.psm1)
+    if ( $Clean -or $Clobber ) {
+        Remove-Build
+        if ( $PSCmdlet.ParameterSetName -eq "Clean" ) {
+            return
         }
-        return $testPath
     }
 
-    Function RunTest($TestType, [Boolean] $DifferentProcess)
-    {
-        $testPath = GetTestPath($TestType)
-        if ($DifferentProcess)
-        {
-            $testScriptFilePath = CreateTestRunnerScript $testPath
-            Start-Process powershell -ArgumentList "-NoExit","-File $testScriptFilePath" -Verb runas
-            # clean up the test file
+    $setName = $PSCmdlet.ParameterSetName
+    switch ( $setName ) {
+        "BuildAll" {
+            Build-ScriptAnalyzer -All -Configuration $Configuration
         }
-        else
-        {
-            try
-            {
-                Push-Location .
-                ([scriptblock]::Create((GetTestRunnerScriptContent $testPath))).Invoke()
-            }
-            finally
-            {
-                Pop-Location
-
+        "BuildDoc" {
+            Build-ScriptAnalyzer -Documentation
+        }
+        "BuildOne" {
+            $buildArgs = @{
+                Framework = $Framework
+                PSVersion = $PSVersion
+                Configuration = $Configuration
             }
+            Build-ScriptAnalyzer @buildArgs
+        }
+        "Test" {
+            Test-ScriptAnalyzer -InProcess:$InProcess
+            return
+        }
+        default {
+            throw "Unexpected parameter set '$setName'"
         }
     }
-
-    if ($Engine -or (-not ($Engine -or $Rules)))
-    {
-        RunTest 'engine' $RunInDifferentProcess
-    }
-    if ($Rules -or (-not ($Engine -or $Rules)))
-    {
-        RunTest 'rules' $RunInDifferentProcess
-    }
-}
-
-if ($Uninstall)
-{
-    Remove-Item -Path $modulePSSAPath -Force -Verbose:$verbosity -Recurse
 }