Validate new Rule definition API

PSSA2 provides a new way to specify rules, which you can see here:

https://github.com/PowerShell/PSScriptAnalyzer/blob/9ee8c0f3110fda305314b050bf0c74766bfcce42/ScriptAnalyzer2/Builtin/Rules/AvoidEmptyCatchBlock.cs#L12-L48

That is based on the following implementation:

https://github.com/PowerShell/PSScriptAnalyzer/blob/9ee8c0f3110fda305314b050bf0c74766bfcce42/ScriptAnalyzer2/Rules/Rule.cs#L12-L91

This is nice because:

• The rule uses attributes, so we can know about it before instantiating one, and it's also neater and more declarative
• The abstract class can provide convenience methods that simplify invocation, helpfully transform inputs, and even can do diagnostic suppression before a diagnostic record object is allocated
• A rule can be generic in its settings object and then allow for those settings to be injected through the constructor based on a deserialised settings object. This adds boilerplate, but allows the object configuration to be totally up to the implementer based on their settings definition (which can be defined next to the rule) and their constructor logic

However, some downsides of the current implementation are:

• Allowing the same class to implement a rule and, say, a formatter is harder with the abstract class vs an interface (and interfaces should generally be preferred when possible)
• Using a protected method to emit diagnostics means there's no type check for rules that will never emit a diagnostic
• We force constructor injection. This is so you can use settings in your rule at the correct time from the code's perspective (e.g. default property values will work, unlike today), but it means more boilerplate for implementers.

I would very much like to keep the feature where we don't allocate an object for suppressed diagnostics, and it has the advantage that there's one fewer classes for an implementer to think about. Some convenience functions can be preserved with extension methods on interfaces, but some cannot.

So an example alternate implementation might look like:

public interface IScriptRule
{
    IEnumerable<Diagnostic> AnalyzeScript(Ast ast, IReadOnlyList<Token> tokens, string scriptFilePath);
}

public static class ScriptRuleExtensions
{
    // Convenience methods
}

But the main issue there is we lose the elegance of (1) making it easier to construct diagnostics, particularly passing in rule metadata automatically, and (2) being able to filter diagnostics before they are created.

So another alternative would be:

public interface IScriptRule
{
    void AnalyzeScript(IDiagnosticEmitter diagnosticEmitter, Ast ast, IReadOnlyList<Token> tokens, string scriptFilePath);
}

// This could be something like an abstract class instead
// But ideally something we could shift the core implementation of if we needed to
public interface IDiagnosticEmitter
{
    // Rule required so that diagnostics know what rule they came from
    // But we trust the caller -- it would be possible to instantiate another rule and pass it in, but this is undesirable
    // Also having to pass `this` is something of an anti-pattern
    void EmitDiagnostic(IScriptRule rule, Ast ast, IReadOnlyList<Token> tokens, string scriptFilePath);
}

public static class DiagnosticEmitterExtensions
{
    // Convenience methods
}

Basically, the abstract class approach makes life better for both the framework and for rule implementers, but has the big downside that multiple inheritance is impossible... OTOH, there are other ways to do something like take a rule and turn it into a formatter, and single-inheritance generally promotes good cohesion...

Beginne mit dem Lesen der zitierten Implementierungen von ScriptAnalyzer2/Builtin/Rules/AvoidEmptyCatchBlock.cs und ScriptAnalyzer2/Rules/Rule.cs. Vergleiche die aktuelle abstract-class API mit den im Issue beschriebenen Alternativen interface und diagnostic-emitter. Als abgeschlossen gilt die Aufgabe, wenn eine klare Entscheidung darüber getroffen und festgehalten wurde, welches rule-definition design validiert oder geändert werden sollte.