PSCodeHealth

Overview

"If you can't measure it, you can't improve it."
Peter Drucker

PSCodeHealth allows you to measure the quality and maintainability of your PowerShell code, based on a variety of metrics related to :

Code length
Code complexity
Code smells, styling issues and violations of best practices
Tests and test coverage
Comment-based help

It can allow you to ensure that your code is compliant with metrics goals (quality gates). You can use the default (built-in) compliance rules, and you can also customize some (or all) compliance rules to fit your goals.

These features can be leveraged from within your PowerShell release pipeline.

PSCodeHealth can also generate a highly visual HTML report so that you can interpret the results at a glance, and easily share them.
For example, here is what the Summary tab looks like :

And here is an example of what the Style & Best Practices tab looks like :

Requirements

Before using PSCodeHealth, you need :

PowerShell 5.x
The Pester PowerShell module (version 3.4.0 or later)
The PSScriptAnalyzer PowerShell module
Internet access when opening the HTML report (to download some CSS and Javascript for Bootstrap, jQuery and Chart.js)

Installation

From the PowerShell Gallery

The easiest and preferred way to install PSCodeHealth is via the PowerShell Gallery. For more information, see the PowerShell Gallery Getting Started page.

Run the following command to install PSCodeHealth and its 2 dependencies (Pester and PSScriptAnalyzer) :

Install-Module -Name PSCodeHealth -Repository PSGallery

From Chocolatey

If you prefer to manage PSCodeHealth as a Windows package, you can use Chocolatey. If you don't have Chocolatey, you can install it from the Chocolately Install page. With Chocolatey installed, execute the following command to install:

choco install pscodehealth

Note: the PSCodeHealth Chocolatey package is provided and supported by the community.

From Github

As an alternative, you can clone this repository to a location on your system and copy the PSCodeHealth subfolder into : C:\Program Files\WindowsPowerShell\Modules\.

Getting Started

To evaluate the code quality of a single script, simply use the Invoke-PSCodeHealth command.
Specify the relative or full path of the script file via the Path parameter and specify the location of the tests via the TestsPath parameter, like so :

PS C:\> Invoke-PSCodeHealth -Path '.\coveralls\Coveralls.ps1' -TestsPath '.\coveralls'

Files    Functions      LOC (Average)  Findings       Findings       Complexity    Test Coverage
                                       (Total)        (Average)      (Average)                  
-----    ---------      -------------  -------------- -------------- ------------- -------------
1        9              22.33          0              0              2             39.58 %

To evaluate the code quality of all the PowerShell code in a directory, specify the relative or full path of the directory via the Path parameter, like so :

PS C:\> Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls'

Files    Functions      LOC (Average)  Findings       Findings       Complexity    Test Coverage
                                       (Total)        (Average)      (Average)                  
-----    ---------      -------------  -------------- -------------- ------------- -------------
3        9              22.33          0              0              2             38.78 %

To view the per-function information, access the FunctionHealthRecords property of the output of Invoke-PSCodeHealth :

C:\> $HealthReport = Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls'
C:\> $HealthReport.FunctionHealthRecords

Function Name               Lines of Code   Complexity     Contains Help  Test Coverage  ScriptAnalyzer
                                                                                            Findings   
-------------               -------------   ----------     -------------  -------------  --------------
Add-CoverageInfo            14              1              False          0 %                  0       
Merge-CoverageResult        21              1              False          0 %                  0       
Get-CoverageArray           30              5              False          94.44 %              0       
Format-FileCoverage         24              2              False          100 %                0       
Get-CommandsForFile         16              1              False          100 %                0       
Get-GitInfo                 23              2              False          0 %                  0       
Format-Coverage             39              3              False          0 %                  0       
Publish-Coverage            18              1              False          0 %                  0       
Get-CoveragePercentage      16              2              False          100 %                0

To output the PSCodeHealth report as an HTML file, use the HtmlReportPath parameter to specify the full path of the HTML file :

C:\> Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls' -HtmlReportPath "$env:USERPROFILE\Desktop\Report.html"

The above command will not output anything to the PowerShell pipeline, unless you add the PassThru parameter.

Want to know more ? Head to the full documentation :
http://pscodehealth.readthedocs.io/en/latest/

Contributing to PSCodeHealth

You are welcome to contribute to this project. There are many ways you can contribute :

Submit issues. In this case, please use the project's issue template.
Submit a fix for an issue.
Submit a feature request.
Submit test cases.
Tell others about the project.
Tell the developers how much you appreciate the project !

For more information on how to contribute to PSCodeHealth, please refer to the contributing guidelines document.

kunaludapi/PSCodeHealth