`Invoke-ScriptAnalyzer` `-Severity` filters rules rather than diagnostics

Engine/Commands/InvokeScriptAnalyzerCommand.cs と Engine/ScriptAnalyzer.cs から始め、特に重大度の初期化、GetAllowedSeveritiesInInt()、IsSeverityAllowed()、IsRuleAllowed() のエントリーポイントを確認します。ルールと DiagnosticRecords のどちらをフィルタリングするかについて意図された動作を確認し、その判断がドキュメントと重大度の処理に一貫して反映されるようにします。

The -Severity parameter of Invoke-ScriptAnalyzer does not do what it says it does.

Parameter help for the -Severity parameter says:

After running Script Analyzer with all rules, this parameter selects rule violations with the specified severity.
...
The parameter filters the rules violations only after running all rules.
...

In reality the parameter filters rules and not diagnostics; both have the concept of Severity (RuleSeverity, and DiagnosticSeverity)

How the -Severity parameter is ultimately used:

1. The user passes -Severity to Invoke-ScriptAnalyzer. Value validated to be one of "Warning", "Error", "Information", "ParseError".

2. The ScriptAnalyzer singleton instance is initialised with this -Severity string[] value, which is stored as a private member of the singleton object (severity).

3. When analyzing a script, the engine determines which rules to run. It uses IsRuleAllowed() to check each rule.

4. IsRuleAllowed() gets a list of allowedSeverities. It does so by calling GetAllowedSeveritiesInInt().

   Each severity (an array of strings) is parsed into the underlying uint value of the DiagnosticSeverity enum type.

   (I believe this should actually be RuleSeverity enum. It works as both enums have identical members and underlying uint values).
   https://github.com/PowerShell/PSScriptAnalyzer/blob/aba29c31151925bd7180e7dfd578e1bfacdaf2a2/Engine/ScriptAnalyzer.cs#L1929-L1934

5. IsRuleAllowed() then calls IsSeverityAllowed(allowedSeverities, rule) as part of it's decision making on whether to execute a rule. Passing in the list of allowedSeverities and the current rule being considered.

6. IsSeverityAllowed(..) then checks if allowedSeverities contains the rules severity (calling rule.GetSeverity() and casting it to a uint). If it does the rule is allowed to run.
   https://github.com/PowerShell/PSScriptAnalyzer/blob/aba29c31151925bd7180e7dfd578e1bfacdaf2a2/Engine/ScriptAnalyzer.cs#L1914-L1921

So there are 2 issues that need to be addressed:

1. There is a disparity between the documentation and implementation. Either:

   • The documentation needs updating to match reality OR
   • The implementation needs to be updated so -Severity filters the output of DiagnosticRecords.

2. GetAllowedSeveritiesInInt() resolves severities using DiagnosticSeverity and that is then used to compare to rule.GetSeverity() which is a RuleSeverity. It works now as both enums are identical in their definition and are being cast to their underlying uint value. If either was updated this could break. It also does not seem intentional.

@bergmeister - Should we update the documentation as a first pass and revisit behaviour later if it's desired? I will also get the enum corrected to RuleSeverity.

This explains the issue described in #2049 - where a custom rule is emitting error-level DiagnosticRecord but is not showing with -Severity Error, but is with -Severity Warning. -Severity is filtering the rules that are run (by their severity) and all custom rules have Warning severity.

https://github.com/PowerShell/PSScriptAnalyzer/blob/aba29c31151925bd7180e7dfd578e1bfacdaf2a2/Engine/Generic/ExternalRule.cs#L55-L59

n.b. I have typed the word severity so many times now that it no longer looks like a real word...