verbose output revisions

Author: jdhitsolutions

License.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2023 JDH Information Technology Solutions, Inc.
+Copyright (c) 2022-2024 JDH Information Technology Solutions, Inc.
 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

PSProjectStatus.psd1

@@ -2,12 +2,12 @@
 
 @{
     RootModule           = 'PSProjectStatus.psm1'
-    ModuleVersion        = '0.12.0'
+    ModuleVersion        = '0.13.0'
     CompatiblePSEditions = 'Desktop', 'Core'
     GUID                 = 'ec249544-dc4e-4e24-aae8-4281ec84f54d'
     Author               = 'Jeff Hicks'
     CompanyName          = 'JDH Information Technology Solutions, Inc.'
-    Copyright            = '(c) 2022-2023 JDH Information Technology Solutions, Inc. All rights reserved.'
+    Copyright            = '(c) 2022-2024 JDH Information Technology Solutions, Inc. All rights reserved.'
     Description          = 'A set of PowerShell tools for tracking module development status. The module uses a JSON file to create a custom object with information about your module. You can use this internally to track the status of your module including a simple to-do tracker. This module was first described at https://jdhitsolutions.com/blog/powershell/8960/introducing-psprojectstatus/'
     PowerShellVersion    = '5.1'
     TypesToProcess       = @('types\psprojectstatus.types.ps1xml')
@@ -16,9 +16,10 @@
         'Get-PSProjectStatus', 'New-PSProjectStatus',
         'Set-PSProjectStatus', 'Get-PSProjectGitStatus',
         'Get-PSProjectReport', 'Get-PSProjectTask',
-        'New-PSProjectTask', 'Remove-PSProjectTask'
+        'New-PSProjectTask', 'Remove-PSProjectTask',
+        'Update-PSProjectStatus'
     )
-    AliasesToExport      = @('gpstat', 'npstat', 'spstat', 'gitstat', 'Update-PSProjectStatus')
+    AliasesToExport      = @('gpstat', 'npstat', 'spstat', 'gitstat')
     PrivateData          = @{
         PSData = @{
             Tags                     = @('modules', 'scripting', 'project-management', 'project', 'psmodule', 'to-do')

PSProjectStatus.psm1

@@ -1,7 +1,8 @@
+#region load string data
 # used for culture debugging
-# write-host "Importing with culture $(Get-Culture)"
+# write-host "Importing with culture $(Get-Culture)" -ForeGroundColor yellow
 
-if ((Get-Culture).Name -match "\w+") {
+if ((Get-Culture).Name -match '\w+') {
     #write-host "Using culture $(Get-Culture)" -ForegroundColor yellow
     Import-LocalizedData -BindingVariable strings
 }
@@ -11,12 +12,14 @@ else {
     Import-LocalizedData -BindingVariable strings -FileName psprojectstatus.psd1 -BaseDirectory $PSScriptRoot/en-us
 }
 
+#endregion
 
-#dot source functions
+#region dot source functions
 Get-ChildItem $PSScriptRoot\functions\*.ps1 -Recurse |
 ForEach-Object {
     . $_.FullName
 }
+#endregion
 
 
 #region class definitions
@@ -75,12 +78,12 @@ Class PSProject {
         $json = Join-Path -Path $this.path -ChildPath psproject.json
         #convert the ProjectVersion to a string in the JSON file
         #convert the LastUpdate to a formatted date string
-        $this | Select-Object @{Name = '$schema'; Expression = { 'https://raw.githubusercontent.com/jdhitsolutions/PSProjectStatus/main/psproject.schema.json' } },
+        $this | Select-Object -Property @{Name = '$schema'; Expression = { 'https://raw.githubusercontent.com/jdhitsolutions/PSProjectStatus/main/psproject.schema.json' } },
         Name, Path,
         @{Name = 'LastUpdate'; Expression = { '{0:o}' -f $_.LastUpdate } },
         @{Name = 'Status'; Expression = { $_.status.toString() } },
         @{Name = 'ProjectVersion'; Expression = { $_.ProjectVersion.toString() } },
-        UpdateUser,Computername,RemoteRepository,Tasks,GitBranch,Tags,Comment |
+        UpdateUser, Computername, RemoteRepository, Tasks, GitBranch, Tags, Comment |
         ConvertTo-Json | Out-File -FilePath $json -Encoding utf8
     }
     [void]RefreshProjectVersion() {
@@ -283,12 +286,32 @@ if ($host.name -match 'ISE') {
 
 #endregion
 
+#region definitions and exports
+
 #path to the JSON schema file
 $jsonSchema = 'https://raw.githubusercontent.com/jdhitsolutions/PSProjectStatus/main/psproject.schema.json'
 
 # for testing
 # $jsonSchema = "file:///c:/scripts/psprojectstatus/psproject.schema.json"
 
+#a hash table to store ANSI escape sequences for different commands used in verbose output with the
+#private _verbose helper function
+$PSProjectANSI = @{
+    'Get-PSProjectGitStatus' = '[1;38;5;51m'
+    'Get-PSProjectReport'    = '[1;38;5;111m'
+    'Get-PSProjectStatus'    = '[1;96m'
+    'Get-PSProjectTask'      = '[1;38;5;10m'
+    'New-PSProjectStatus'    = '[1;38;5;208m'
+    'New-PSProjectTask'      = '[1;38;5;159m'
+    'Remove-PSProjectTask'   = '[1;38;5;195m'
+    'Set-PSProjectStatus'    = '[1;38;5;214m'
+    Default                  = '[1;38;5;51m'
+}
+Set-Variable -Name PSProjectANSI -Description "a hash table to store ANSI escape sequences for different commands used in verbose output. You can modify settings using ANSI sequences or `$PSStyle"
+
 #Export the module version to a global variable that will be used in Verbose messages
-New-Variable -Name PSProjectStatusModule -Value "0.12.0" -Description "The PSProjectStatus module version used in verbose messaging."
-Export-ModuleMember -Variable PSProjectStatusModule -Alias 'Update-PSProjectStatus','gitstat','gpstat', 'npstat', 'spstat'
+New-Variable -Name PSProjectStatusModule -Value '0.13.0' -Description 'The PSProjectStatus module version used in verbose messaging.'
+
+Export-ModuleMember -Variable PSProjectStatusModule, PSProjectANSI -Alias 'Update-PSProjectStatus', 'gitstat', 'gpstat', 'npstat', 'spstat'
+
+#endregion

README.md

@@ -279,9 +279,9 @@ PS C:\scripts\PSHelpDesk> Set-PSProjectStatus -LastUpdate (Get-Date) -Status Dev
 
    Name: PSHelpDesk [C:\Scripts\PSHelpDesk]
 
-LastUpdate             Status            Tasks                 GitBranch        Age
-----------             ------            -----                 ---------        ---
-3/15/2023 5:53:54 PM   Development  {update help, add...             dev   00.00:00
+LastUpdate             Status            Tasks             GitBranch        Age
+----------             ------            -----             ---------        ---
+3/15/2023 5:53:54 PM   Development  {update help, add...         dev   00.00:00
 ```
 
 When defining tasks, use `-Concatenate` to append the tasks. Otherwise, tasks will be overwritten with the new value.
@@ -519,9 +519,9 @@ Status           Property       PSProjectStatus Status {get;set;}
 Tags             Property       string[] Tags {get;set;}
 Tasks            Property       string[] Tasks {get;set;}
 UpdateUser       Property       string UpdateUser {get;set;}
-Info             PropertySet    Info {Name, Status, Version, GitBranch, Tasks, Tags, Comment}
-versionInfo      PropertySet    versionInfo {Name, Status, Version, GitBranch, LastUpdate}
-Age              ScriptProperty System.Object Age {get=(Get-Date) - $this.lastUpdate;}
+Info             PropertySet    Info {Name, Status, Version, GitBranch, Tasks...
+versionInfo      PropertySet    versionInfo {Name, Status, Version, GitBranch...
+Age              ScriptProperty System.Object Age {get=(Get-Date) - $this.las...
 ```
 
 The property sets make it easier to display a group of related properties.
@@ -530,13 +530,23 @@ The property sets make it easier to display a group of related properties.
 PS C:\Scripts\PSProjectStatus> Get-PSProjectstatus | Select Info
 
 Name      : PSProjectStatus
-Status    : Updating
-Version   : 0.12.0
-GitBranch : 0.12.0
-Tasks     : {Create TUI-based management tools, Consider extending schema for a structured Task item [Issue 10],
-            Pester tests, Update README…}
-Tags      : {json}
+Status    : AcceptanceTesting
+Version   : 0.13.0
+GitBranch : 0.13.0
+Tasks     : {Create TUI-based management tools, Consider extending schema for a
+             structured Task item [Issue 10],
+            Pester tests}
+Tags      : {}
 Comment   : none
+
+PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object VersionInfo,age
+
+Name       : PSProjectStatus
+Status     : AcceptanceTesting
+Version    : 0.13.0
+GitBranch  : 0.13.0
+LastUpdate : 12/30/2023 1:43:37 PM
+Age        : 00:03:56.0703713
 ```
 
 ### Formatting
@@ -579,6 +589,37 @@ The commands in this module use localized string data to display verbose, warnin
 
 ![Sample verbose output](images/verbose-output.png)
 
+The defined ANSI sequences are stored in a variable called `$PSProjectANSI`. You can modify this variable to change the color for each command.
+
+```powershell
+$PSProjectANSI = @{
+    'Get-PSProjectGitStatus' = '[1;38;5;51m'
+    'Get-PSProjectReport'    = '[1;38;5;111m'
+    'Get-PSProjectStatus'    = '[1;96m'
+    'Get-PSProjectTask'      = '[1;38;5;10m'
+    'New-PSProjectStatus'    = '[1;38;5;208m'
+    'New-PSProjectTask'      = '[1;38;5;159m'
+    'Remove-PSProjectTask'   = '[1;38;5;195m'
+    'Set-PSProjectStatus'    = '[1;38;5;214m'
+    Default                  = '[1;38;5;51m'
+}
+```
+
+You can change a setting by modifying the variable. You can use ANSI sequences or `$PSStyle`
+
+```powershell
+$PSProjectANSI["Get-PSProjectStatus"] = "[1;92m"
+$PSProjectANSI["Get-PSProjectGitStatus"] = $PSStyle.Foreground.Cyan
+```
+
+These changes only persist for the duration of your PowerShell session or until you re-import the module. Use your profile script to import the module and update the variable.
+
+```powershell
+Import-Module PSProjectStatus
+$PSProjectANSI["Get-PSProjectStatus"] = "[1;38;5;140m"
+$PSProjectANSI["Get-PSProjectGitStatus"] = "[1;38;5;77m"
+```
+
 You must use a PowerShell console that supports ANSI escape sequences. The PowerShell ISE __does not__ support this feature.
 
 ## Editor Integration

docs/Get-PSProjectGitStatus.md

@@ -19,7 +19,7 @@ Get-PSProjectGitStatus [<CommonParameters>]
 
 ## DESCRIPTION
 
-Presumably you are using git to manage your project. If so, some git-related information is included in the PSProjectStatus output. Get-PSProjectGitStatus is intended to provide more git-specific details. You should run this command in the root of your project directory. If the project is not a git repository, nothing will be returned.
+Presumably you are using git to manage your project. If so, some git-related information is included in the PSProjectStatus output. Get-PSProjectGitStatus is intended to provide more git-specific details. You should run this command in the root of your project directory. If the project is not git initialized, nothing will be returned.
 
 ## EXAMPLES
 

docs/Get-PSProjectReport.md

@@ -33,7 +33,7 @@ Get-PSProjectReport [-Path] <String> [-Status <PSProjectStatus>]
 
 ## DESCRIPTION
 
-The PSProjectStatus module makes an assumption that the majority of your projects are organized under a parent folder like C:\Scripts. This command is designed to make it easier to identify and manage projects you are working on. The default behavior is to get PSProject information from the top-level folders in your root directory. But you can also filter on status or age.
+The PSProjectStatus module makes an assumption that the majority of your projects are organized under a parent folder like C:\Scripts. This command is designed to make it easier to identify and manage projects you are working on. The default behavior is to get PSProject information from the top-level folders in your root directory. But you can also filter on status, age, or tag.
 
 ## EXAMPLES
 
@@ -70,10 +70,10 @@ Get PSProjects modified within the last 10 days.
 ### Example 3
 
 ```powershell
-PS C>\> Get-PSProjectReport c:\scripts -NewerThan 30 | Select Path,Name,Status,LastUpdate | Out-GridView -Title "Select a project" -OutputMode Single | foreach-object { code $_.path }
+PS C>\> Get-PSProjectReport c:\scripts -NewerThan 60 | Select-Object Path,Name,Status,Tags,LastUpdate | Out-GridView -Title "Select a project" -OutputMode Single | Foreach-Object { set-location $_.path ; code $_.path }
 ```
 
-Get projects modified in the last 30 days and send to Out-GridView. The selected project folder will be opened in VSCode.
+Get projects modified in the last 60 days and send to Out-GridView. The selected project folder will be opened in VSCode.
 
 ## PARAMETERS
 

docs/Get-PSProjectStatus.md

@@ -30,9 +30,9 @@ PS C:\Scripts\PSClock> Get-PSProjectStatus
 
    Name: PSClock [C:\Scripts\PSClock]
 
-LastUpdate             Status            Tasks                 GitBranch     Age
-----------             ------            -----                 ---------     ---
-3/2/2022 3:43:34 PM    Stable                                        main    12.19:14
+LastUpdate             Status            Tasks            GitBranch          Age
+----------             ------            -----            ---------          ---
+3/2/2022 3:43:34 PM    Stable                                   main    12.19:14
 ```
 
 Get the status from the current directory.
@@ -44,46 +44,48 @@ C:\Scripts\ dir -Directory | Get-PSProjectStatus -WarningAction SilentlyContinue
 
    Name: ADReportingTools [C:\Scripts\ADReportingTools]
 
-LastUpdate             Status            Tasks                 GitBranch        Age
-----------             ------            -----                 ---------        ---
-6/21/2021 4:47:11 PM   Updating          {Publish new releas…      1.4.0  266.17:59
+LastUpdate             Status            Tasks             GitBranch        Age
+----------             ------            -----             ---------        ---
+6/21/2021 4:47:11 PM   Updating          {Publish new re…      1.4.0  266.17:59
 
    Name: GitDevTest [C:\scripts\GitDevTest]
 
-LastUpdate             Status            Tasks                 GitBranch        Age
-----------             ------            -----                 ---------        ---
-2/3/2022 4:50:37 PM    Stable            {update readme, add…     master   39.17:55
+LastUpdate             Status            Tasks             GitBranch        Age
+----------             ------            -----             ---------        ---
+2/3/2022 4:50:37 PM    Stable            {update readme,…     master   39.17:55
 
    Name: MyTasks [C:\Scripts\MyTasks]
 
-LastUpdate             Status            Tasks                 GitBranch        Age
-----------             ------            -----                 ---------        ---
-10/14/2020 1:29:59 PM  Stable                                     master  516.21:16
+LastUpdate             Status            Tasks             GitBranch        Age
+----------             ------            -----             ---------        ---
+10/14/2020 1:29:59 PM  Stable                                 master  516.21:16
 ...
 ```
 
-Get status for multiple projects.
+Get status for multiple projects. You could also use the Get-PSProjectReport command.
 
 ### Example 3
 
 ```powershell
 PS C:\Scripts\PSCalendar> Get-PSProjectStatus | Format-List
 
-   Project: PSCalendar [C:\Scripts\PSCalendar]
+   Project: PSCalendar [C:\scripts\PSCalendar]
 
 Version    : 2.9.0
-Status     : Patching
-Tasks      : {Update help documentation, Issue #31, Issue #34, Issue #33}
-GitBranch  : 2.9.0
-LastUpdate : 3/3/2022 10:24:49 AM
+Status     : Stable
+Tasks      : {Update Help, Issue 34}
+Tags       : {}
+GitBranch  : master
+LastUpdate : 3/1/2022 5:50:00 AM
+Age        : 669.10:07:19
 ```
 
 Use the default List view. This makes it easier to view the tasks.
 
 ### Example 4
 
 ```powershell
-PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object VersionInfo,age
+PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object VersionInfo,Age
 
 Name       : PSProjectStatus
 Status     : Updating
@@ -136,3 +138,5 @@ Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell
 [Set-PSProjectStatus](Set-PSProjectStatus.md)
 
 [New-PSProjectStatus](New-PSProjectStatus.md)
+
+[Get-PSProjectReport](Get-PSProjectReport.md)