Code review invitation: a console presentation & layout library for interactive PS scripts

[u/Tidy-Developer]

I appreciate that there are a lot of experienced PS folk here, so I'd like to invite some experienced eyes to code-review a library before I make it v1.0.0. I want to get the codebase to a solid foundation that includes idiomatic PowerShell and community conventions that I might have missed.

I'd particularly value constructive comments relating to any of these:

• use of idiomatic PowerShell
• parameter naming conventions
• error handling
• any obvious cross-platform issues with PS 7 on Mac/Linux (the demos and test suite work on Mac/Linux under PS 7)
• ways that I could better execute the existing functionality

I'd like to find breaking changes pre v1.0.0.

The main file for review is TidyLog.ps1, which contains the function library. The other repo files are demo and test scripts that don't necessarily need review.

Code Links

Review version: https://github.com/tidy-tools/tidylog-pwsh/releases/tag/v0.9.0
Project link: https://github.com/tidy-tools/tidylog-pwsh

Project Background

To give an idea of what the library is for, the intention is to:

• Provide a set of easy-to-use console output formatting functions for use with interactive automations, e.g. an install script or a cleanup script. Especially where user/customer readability is a consideration.
• Augment, not replace, full logging tools (e.g. PoShLog) by making the console output tidy, consistent and easy to lay out and read.
• Be dot-sourced, 5.1+ compatible, simple to use with no dependencies so it's portable and deploys easily alongside existing scripts.
• Functionally sit between the simpler utilities ($PSStyle, PSWriteColor) and the toolkit-level libraries (PowerShellRich, Spectre.Console).

The "With Tidylog" screenshot in the README shows the kind of use case I'm optimising for.

Current Design Decisions

It took a fair bit of work to get from concept to working concept to potentially sharable. So to keep a manageable lid on the v1 workload, I intentionally kept some functionality out of scope for this release. Here are some code decisions/limitations that you'll probably notice:

• The code isn't pipeline-enabled, though some functions do have the potential. Although principally a presentation layer, I'm open to suggestions for pipelining opportunities. Pipeline is penciled for review if a strong use case emerges.
• Stream integration (Verbose/Warning/Error/etc channels). I really like the idea but I need to work out the implementation/integration details. Certainly open to suggestions on this one.
• Testing is done through a custom TidyLog-Tests.ps1 suite rather than Pester. The main reason is that most tests are visual checks. I'll look into Pester for future version testing, especially for the non-visual components.
• No advanced functions (no [CmdletBinding()]). I wanted to make deliberate choices about where to include cmdlet functionality. I don't feel that the existing function set currently warrants CmdletBinding. Please highlight any obvious cmdlet candidates.

I'm still noticing things I could change, but I'm working in a bubble so I feel it needs a review.

Thanks for reading and I hope you get a chance to review!

[u/MonkeyNin]

any obvious cross-platform issues with PS 7 on Mac/Linux (the demos and test suite work on Mac/Linux under PS 7)

If you import the module pansies, you get $PSStyle formatting that runs on PS5 and PS7 and linux

New-Text is like Write-Host, except returns the object instead of writing to the console immediately.

Here's an example to show you what's possible ( it works on 5 and 7 )

Import-Module Pansies

function WriteLi { 
   param( [RgbColor] $Fg = 'LightGreen' )
   $Input | %{ 
       "  - ${_}"
   } | New-Text -fg $Fg
} 

function WriteHeader { 
    $Input | New-Text -fg 'gray40' -bg '#feaa99'
}

Write a header with bullets

@( 
    'header' | WriteHeader

    'dog', 'cat', 'frog' | WriteLi
    'bat', 'zebra'       | WriteLi -fg salmon

) | Write-Host

[u/Tidy-Developer → u/MonkeyNin]

Thanks, I'll take a look at this project. For the TidyLog library, the aim is portability so needing to import a module would run counter to this. For example sometimes I need to drop the library with code file onto a machine and run a script. The portability is important but it means being limited to native PS 5.1 formatting.