Git Product home page Git Product logo

powershell-analyzers's Introduction

Lombiq PowerShell Analyzers

Lombiq.Analyzers.PowerShell NuGet

About

PowerShell static code analysis via PSScriptAnalyzer and 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.

powershell-analyzers's People

Contributors

0liver avatar benedekfarkas avatar domonkosgabor avatar dorraj07 avatar luko6 avatar mzole avatar piedone avatar psichorex avatar sarahelsaig avatar tteguayco avatar wasnk avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.