build: add standard psake bootstrap (Init/Clean/Build/Test/Analyze/Publish)

.gitignore

@@ -5,3 +5,7 @@
 PSKoans.psproj
 
 PSKoans/*/PSKoans-help.xml
+
+Output/**
+Tests/out/**
+testResults.xml

PSKoans/Private/Invoke-Koan.ps1

@@ -11,7 +11,7 @@
         Defines the hashtable that will be splatted into Invoke-Pester in the new PowerShell instance.
 
     .EXAMPLE
-        Invoke-Koan @{ Script = '.\AboutArrays.Koans.ps1'; PassThru = $true; Show = 'None' }
+        Invoke-Koan @{ Path = '.\AboutArrays.Koans.ps1'; PassThru = $true; Show = 'None' }
 
         Triggers Pester to assess the AboutArrays file in the current directory and pass back the complete tests object,
         hiding the standard test results display.
@@ -33,7 +33,7 @@
     end {
         try {
             $Requirements = [System.Management.Automation.Language.Parser]::ParseFile(
-                $ParameterSplat.Script,
+                $ParameterSplat.Path,
                 [ref]$null,
                 [ref]$null
             ).Ast.ScriptRequirements

PSKoans/Public/Get-Blank.ps1

@@ -1,4 +1,43 @@
 function Get-Blank {
+    <#
+    .SYNOPSIS
+        Gets a blank item that does not equal anything.
+
+    .DESCRIPTION
+        Get-Blank returns an object of type [Blank] as defined in the PSKoans module.
+        This object is not equivalent to any other type of object, including itself, when compared
+        with a standard `-eq` comparison.
+
+        The only exception, which is unavoidable, is that it is considered equal to $true when
+        $true is on the left-hand side of the comparison. This kind of comparison may sometimes
+        need to be carefully avoided when framing a koan assertion.
+
+        For instance,an assertion such as `____ | Should -BeTrue` WILL pass, although it should not.
+
+    .PARAMETER |PipeInput
+        Used to capture the input in a pipeline context, to avoid erroring out in those contexts.
+        This parameter is not intended to be used directly, and captures all pipeline input.
+
+    .PARAMETER |ParameterInput
+        Used to capture parameter names and arguments when used as a substitute for any other cmdlet.
+        This parameter is not intended to be used directly, and collects all argument names and values.
+
+    .EXAMPLE
+        Get-Blank
+
+        Returns a blank object.
+
+    .EXAMPLE
+        __
+
+        Returns a blank object.
+
+    .NOTES
+        Author: Joel Sallow (@vexx32)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-Blank.md')]
     [OutputType('Blank')]
     [Alias('__', '____', 'FILL_ME_IN')]

PSKoans/Public/Get-Karma.ps1

@@ -1,4 +1,45 @@
 function Get-Karma {
+    <#
+    .SYNOPSIS
+        Retrieves information about your progress in PSKoans.
+
+    .DESCRIPTION
+        Get-Karma executes Pester against the koans and outputs a short report on your current progress.
+
+    .PARAMETER IncludeModule
+        Get Karma for the default PowerShell Koans as well as Koans for the specified module.
+        Wildcards are supported.
+
+    .PARAMETER List
+        Output a complete list of available koan topics.
+
+    .PARAMETER Module
+        Get Karma for the specified module only.
+        Wildcards are supported.
+
+    .PARAMETER Topic
+        Execute koans only from the selected Topic(s).
+        Wildcard patterns are permitted.
+
+    .EXAMPLE
+        Get-Karma
+
+        Outputs a hashtable containing information about your progress.
+
+    .EXAMPLE
+        Get-Karma -List
+
+        Outputs a list of koan topics, including both the user file location and the module file location.
+
+    .NOTES
+        Author: Joel Sallow (@vexx32)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/Get-Karma.md
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(DefaultParameterSetName = 'Default',
         HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-Karma.md')]
     [OutputType('PSKoans.Result', 'PSKoans.CompleteResult')]
@@ -109,7 +150,7 @@
 
                 # Execute in a fresh scope to prevent internal secrets being leaked
                 $PesterTests = Invoke-Koan @{
-                    Script   = $KoanFile.Path
+                    Path     = $KoanFile.Path
                     PassThru = $true
                     Output   = 'None'
                 }

PSKoans/Public/Get-PSKoan.ps1

@@ -1,4 +1,70 @@
 function Get-PSKoan {
+    <#
+    .SYNOPSIS
+        Gets koan topic metadata for each topic.
+
+    .DESCRIPTION
+        Get-PSKoan finds Koans in either the Module or User locations.
+        Koan information includes position and module information, as well as topic name.
+
+    .PARAMETER IncludeModule
+        Get default PowerShell Koans as well as Koans for the specified module.
+        Wildcards are supported.
+
+    .PARAMETER ListModules
+        List the modules included with PSKoans.
+
+    .PARAMETER Module
+        Get Koans for the specified module only.
+        Wildcards are supported.
+
+    .PARAMETER Scope
+        Get koans from the specified scope.
+        The default scope is Module.
+        User scope gets Koan information from the location used by Get-PSKoanLocation.
+
+    .PARAMETER SkipAttributeParsing
+        By default, Get-PSKoan attempts to retrieve the Position and Module information from the Koan attribute in each file.
+        This process may be skipped by using this parameter.
+
+    .PARAMETER Topic
+        Reset the specified topic or topics.
+        Wildcards are supported.
+
+    .EXAMPLE
+        Get-PSKoan
+
+        Get all Koans in the PSKoans module, excluding koans for individual modules.
+
+    .EXAMPLE
+        Get-PSKoan -IncludeModule *
+
+        Get all Koans in the PSKoans module, include all koans for individual PowerShell modules.
+
+    .EXAMPLE
+        Get-PSKoan -Topic AboutArrays
+
+        Get information about the AboutArrays koans.
+
+    .EXAMPLE
+        Get-PSKoan -Module ActiveDirectory
+
+        Get koans from the ActiveDirectory module only.
+
+    .EXAMPLE
+        Get-PSKoan -Scope User
+
+        Get all Koans in the User location, excluding koans for individual modules.
+
+    .NOTES
+        Author: Chris Dent (@indented-automation)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/Get-PSKoan.md
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(DefaultParameterSetName = 'IncludeModule',
         HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-PSKoan.md')]
     [OutputType('PSKoans.KoanInfo')]

PSKoans/Public/Get-PSKoanLocation.ps1

@@ -1,4 +1,25 @@
 function Get-PSKoanLocation {
+    <#
+    .SYNOPSIS
+        Gets the folder location where the current user's copy of the PSKoans lessons are stored.
+
+    .DESCRIPTION
+        Gets the current value of the PSKoans working library path.
+        This value defaults to `$HOME\PSKoans` but can be changed as you prefer.
+
+    .EXAMPLE
+        Get-PSKoanLocation
+
+        C:\Users\Timmy\PSKoans
+
+        Displays the path to the current user's koan library location.
+
+    .NOTES
+        Author: Joel Sallow (@vexx32)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-PSKoanLocation.md')]
     [OutputType([string])]
     param()

PSKoans/Public/Get-PSKoanSetting.ps1

@@ -1,4 +1,38 @@
 function Get-PSKoanSetting {
+    <#
+    .SYNOPSIS
+        Retrieves the configuration settings for PSKoans.
+
+    .DESCRIPTION
+        Retrieves configuration data from the locally stored json file in `$HOME/.config/PSKoans`.
+
+    .PARAMETER Name
+        Specifies which setting value to retrieve.
+
+    .EXAMPLE
+        Get-PSKoanSetting
+
+        Retrieves all module settings.
+
+    .EXAMPLE
+        Get-PSKoanSetting -Name LibraryFolder
+
+        Retrieves the library folder location (also retrievable with `Get-PSKoanLocation`).
+
+    .EXAMPLE
+        Get-PSKoanSetting -Name Editor
+
+        Retrieves the text editor that PSKoans will use for `Show-Karma -Contemplate`.
+
+    .NOTES
+        Author: Joel Sallow (@vexx32)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/Set-PSKoanSetting.md
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-PSKoanSetting.md')]
     [OutputType([string], [PSCustomObject])]
     param(

PSKoans/Public/Move-PSKoanLibrary.ps1

@@ -1,4 +1,33 @@
 function Move-PSKoanLibrary {
+    <#
+    .SYNOPSIS
+        Move your entire current PSKoans library folder to another location and update your KoanLocation setting to reflect the new location.
+
+    .DESCRIPTION
+        `Move-PSKoanLibrary` takes your current PSKoans library location and moves the folder to the specified destination.
+        Then, it updates the current KoanLocation setting to point to the new location.
+
+    .PARAMETER Path
+        The path to the new library location.
+        This path can be relative to the current session location, but cannot contain wildcards.
+
+    .EXAMPLE
+        Move-PSKoanLibrary -Path C:\Users\Joe\OneDrive
+
+        Moves Joe's koan library into his OneDrive directory.
+
+    .NOTES
+        Author: Joel Sallow (@vexx32)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/Set-PSKoanSetting.md
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/Get-PSKoanSetting.md
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium',
         HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Move-PSKoanLibrary.md')]
     [OutputType([void])]

PSKoans/Public/Register-Advice.ps1

@@ -1,4 +1,29 @@
 function Register-Advice {
+    <#
+    .SYNOPSIS
+        Causes powershell to write a random piece of advice on each start.
+
+    .DESCRIPTION
+        Causes powershell to write a random piece of advice on each start.
+        This is done by creating / modifying the powershell profile to call `Show-Advice` on each session start.
+
+    .PARAMETER TargetProfile
+        Specify a named profile to modify.
+
+    .EXAMPLE
+        Register-Advice
+
+        Causes powershell to write a random piece of advice on each start.
+
+    .NOTES
+        Author: Friedrich Weinmann (@FriedrichWeinmann)
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/Show-Advice.md
+
+    .LINK
+        https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md
+    #>
     [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low',
         HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Register-Advice.md')]
     [OutputType([void])]