Lombiq PowerShell Analyzers

About

PowerShell static code analysis via PSScriptAnalyzer and custom analyzer rules, accompanied by Lombiq's recommended configuration for it. Use it from the CLI, in GitHub Actions, or integrated into MSBuild builds. Demo video here.

Looking for .NET static code analysis? Check out our .NET Analyzers project.

Do you want to quickly try out this project and see it in action? Check it out in our Open-Source Orchard Core Extensions full Orchard Core solution and also see our other useful Orchard Core-related open-source projects!

Documentation

Pre-requisites

• You must have PowerShell 7 or greater installed.
• The PSScriptAnalyzer module must be installed. The script will attempt to auto-install it, however if this fails (e.g. on Windows PowerShell you have to be admin to install modules) follow the steps here.

Note that if you are using this in GitHub Actions, the common images (windows-latest and ubuntu-latest) already have these so you don't need to install anything.

Usage

PowerShell CLI

Use the script like this to output the analyzer violations with Write-Error:

./Invoke-Analyzer.ps1 -SettingsPath PSScriptAnalyzerSettings.psd1

The -SettingsPath can be omitted, in this case the PSScriptAnalyzerSettings.psd1 in the same directory as the Invoke-Analyzer.ps1 will be used.

GitHub Actions

There are a few different ways to execute PowerShell static code analysis using GitHub Actions:

PowerShell Analyzers is a submodule of your repository

You can invoke it from an action.yml file like this:

    - name: Analyze PowerShell scripts
      shell: powershell # Run analysis from Windows PowerShell.
      run: <path-to-submodule>/Lombiq.Analyzers.PowerShell/Invoke-Analyzer.ps1 -ForGitHubAction
    - name: Analyze PowerShell scripts
      shell: pwsh # Run analysis from PowerShell Core.
      run: <path-to-submodule>/Lombiq.Analyzers.PowerShell/Invoke-Analyzer.ps1 -ForGitHubAction

The -ForGitHubAction switch enables displaying the results using error workflow commands. These create file annotations pointing to the exact script path and line number provided by PSScriptAnalyzer. You can review the results in the workflow summary page. If the violating files aren't in a submodule then they will be marked in the related pull request's Files tab as well.

Adding the reusable action to a workflow

See the action's parameters for configuration options. Example:

    - name: PowerShell Static Code Analysis
      uses: Lombiq/PowerShell-Analyzers/.github/actions/static-code-analysis@dev

Calling the reusable workflow directly

See the workflow, which is a wrapper for the action above, and its parameters for configuration options. Example:

  powershell-static-code-analysis:
    uses: Lombiq/PowerShell-Analyzers/.github/workflows/static-code-analysis.yml@dev

MSBuild

This way you associate the analyzer with a .NET project and MSBuild automatically invokes analysis before building. If the analysis passes, it creates a timestamp and won't perform the analysis again until a new script file has been added or an existing one modified.

If this project is included via a submodule, edit the csproj file of your primary project(s) and add the following:

<Import Project="path\to\Lombiq.Analyzers.PowerShell\Lombiq.Analyzers.PowerShell.targets" />

You don't need to <ProjectReference> Lombiq.Analyzers.PowerShell.csproj.

If you include the project as a NuGet package, it will work as-is.

Additionally, you can set these properties in the importing project's <PropertyGroup>:

• <PowerShellAnalyzersRootDirectory>: The analysis root directory, only files recursively found here are checked. If not specified, it uses the solution directory if present (if you are building the whole solution), otherwise the project directory (if you are building just the project).
• <PowerShellAnalyzersArguments>: Set it to customize the arguments passed to the script. This is useful if you want to provide your own rules configuration by setting it to -ForMsBuild -SettingsPath path/to/settings.psd1. If not specified, its value is -ForMsBuild unless a GitHub Actions environment is detected (via the $GITHUB_ENV variable) in which case the default value is -ForGitHubAction.

Visual Studio Code

Live analysis is outside of the scope of this project, however you can use the Visual Studio Code extension:

1. Install it from the Marketplace.
2. Go to Settings and paste powershell.scriptAnalysis.settingsPath into the search bar.
3. Set it to the path of the PSScriptAnalyzerSettings.psd1 file to use our settings.

Suppressing PSScriptAnalyzer rules

Occasionally there is good reason to ignore an analyzer warning. In this case add the [Diagnostics.CodeAnalysis.SuppressMessage('PSCategoryId', 'ParameterName', Justification = 'Explain why.')] attribute to the cmdlet's param() block. The first two parameters are mandatory:

1. PSCategoryId is an example for the Id of the analyzer rule and it usually starts with PS.
2. ParameterName is an example for the name of the parameter (notice that it doesn't start with $). Leave it empty if the suppression is not specific to a parameter.

For more information, see the module's documentation.

Suppressing a specific line or range (like #pragma warning disable in C#) is not currently supported. See the associated PSScriptAnalyzer issue.

Implementing custom analyzer rules

Check out the official documentation for instructions and CommunityAnalyzerRules for additional inspiration. Custom rule modules should be placed in the Lombiq.Analyzers.PowerShell\Rules folder to be automatically detected by the Invoke-Analyzer script.

Contributing and support

Bug reports, feature requests, comments, questions, code contributions and love letters are warmly welcome. You can send them to us via GitHub issues and pull requests. Please adhere to our open-source guidelines while doing so.

This project is developed by Lombiq Technologies. Commercial-grade support is available through Lombiq.

Publishing a new NuGet package

When publishing a new version of the NuGet package, even if it's just a pre-release, also update the package references under TestSolutions\Lombiq.Analyzers.PowerShell.PackageReference to the new version. This is necessary to test the analyzers in the context of a consuming project.