Project Rules
The default PSScriptAnalyzer lint checks your code follows common PowerShell practice. Project Rules checks it follows your standards: rules your team or organization cares about that a general-purpose linter doesn’t, such as code that must run under Constrained Language Mode, or every public function having a help example.
It is optional, additive and advisory:
- Optional. Nothing runs until you add rules and enable the workflow.
- Additive. It runs only the rules you give it, never the default ones again, and posts its own pull request comment beside the default lint comment.
- Advisory. Findings are reported, never a reason to fail a pull request.
Quick start: Add-MFProjectRules
Add-MFProjectRules
This adds two ready-made rule sets to a PSScriptAnalyzer folder in your project root, and enables the Project Rules workflow (GitHub) or pipeline (Azure DevOps) in whichever CI folders your project has, by renaming projectRules.yml.example to projectRules.yml. On Azure DevOps you still need to create a pipeline for the file, and add it to your branch policy, as with the others.
Pick rule sets with -RuleSet:
Add-MFProjectRules -RuleSet CLM
| Rule set | Adds | Checks |
|---|---|---|
CLM | PSScriptAnalyzer/clm.psd1 | Compatibility with Constrained Language Mode, with PSScriptAnalyzer’s PSUseConstrainedLanguageMode rule. Needs PSScriptAnalyzer 1.25.0 or newer |
HelpExamples | PSScriptAnalyzer/rules/HelpExamples/HelpExamples.psm1 | Every public function, in source/functions, has at least one .EXAMPLE in its comment-based help. Your docs are generated from that help, and an example is the first thing most people look for |
Existing files are kept unless you pass -Force. A CLM finding is a prompt, not proof: a clean static check doesn’t guarantee your module works under CLM, so test it there too if it matters.
How it decides what to run
The files in PSScriptAnalyzer/ decide everything. Each one is a rule set, with its own line in the report:
| File | Is |
|---|---|
PSScriptAnalyzer/*.psd1 | A settings file naming the rules to run, in IncludeRules or Rules |
PSScriptAnalyzer/rules/<Name>/ | A custom rule module |
With no files, Project Rules does nothing and posts no comment.
It scans source/functions, private, classes, enums and validationClasses. That is wider than the default lint, as a class anywhere in a module can matter as much as a function.
So it never repeats the default lint:
- A settings file only runs the rules it names. Naming a default rule is the one way to run it here.
IncludeDefaultRules,CustomRulePathandRecurseCustomRulePathare ignored in settings files. Custom rules belong in therulesfolder.- A
PSScriptAnalyzerSettings.psd1beside a source file isn’t picked up.
A rule set that reports nothing is only shown as clean when it can be shown to have run. A misspelled rule name, or a missing Enable = $true, also produces zero findings, and the report says so rather than calling it clean.
Writing your own rules
A custom rule is a PowerShell module of Measure-* functions that take an AST and return diagnostic records. The HelpExamples rule is a short, complete example to copy:
# PSScriptAnalyzer/rules/MyRules/MyRules.psm1
function Measure-MyRule
{
[CmdletBinding()]
[OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
PARAM(
[Parameter(Mandatory)]
[System.Management.Automation.Language.ScriptBlockAst]$ScriptBlockAst
)
process{
# Inspect $ScriptBlockAst, and for each problem output a DiagnosticRecord:
# [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
# Message = '...'; Extent = $someAst.Extent; RuleName = 'Measure-MyRule'; Severity = 'Warning'
# }
}
}
Export-ModuleMember -Function Measure-*
See Creating custom rules in the PSScriptAnalyzer docs for the details.
Custom rules are code, and they run in CI. The workflow runs them in a job with read-only access and no write token, and posts the comment from a separate job that never runs your code. Even so, treat
PSScriptAnalyzer/like workflow files: consider adding it toCODEOWNERS, so changes to it need review.
Run it locally
Project Rules is a script in your project, so you can run exactly what CI runs before you open a pull request:
# Each finding, with its line number
.\scripts\Invoke-MFProjectRules.ps1
# The same markdown report CI posts to a pull request
(.\scripts\Invoke-MFProjectRules.ps1).Report