Add an option to include extension methods from namespaces that are not imported in the rules using OverloadFinder

[meziantou]

Follow-up to #1520.

Problem

The rules that suggest another overload only consider the overloads in scope at the call site. An extension method declared in a namespace that the file does not import is ignored, even though adding a using directive is enough to call it:

using System.Threading.Tasks;

class Test
{
    public async Task A(Sample sample)
    {
        sample.Do(); // not reported, although Ext.SampleExtensions.DoAsync exists
    }
}

Changes

New option, opt-in, for every rule using OverloadFinder

<RuleId>.include_extension_methods_from_not_imported_namespaces = false

Rules	Analyzer	Code fix adds the using
MA0001, MA0074	UseStringComparisonAnalyzer	✔️
MA0002	UseStringComparerAnalyzer (invocations)	✔️
MA0011	UseIFormatProviderAnalyzer	✔️
MA0032, MA0040	UseAnOverloadThatHasCancellationTokenAnalyzer	✔️ (MA0040)
MA0042, MA0045	DoNotUseBlockingCallInAsyncContextAnalyzer	✔️
MA0166, MA0167	UseAnOverloadThatHasTimeProviderAnalyzer	✔️ (MA0166)
MA0210	UseInKeywordForInParameterAnalyzer	✔️

• The option is per rule. When an analyzer reports two rules, the overloads are searched with the extension methods when the option is set for one of them, but the diagnostic is only reported when the option is set for the rule being reported (e.g. MA0045.… does not enable MA0042).
• An overload that does not require a using directive is always preferred.
• No option for MA0054 (only searches constructors, which cannot be extension methods) and MA0193 (its analyzer does not use OverloadFinder). MA0079, MA0080 and MA0209 do not search overloads themselves; MA0079/MA0080 stay consistent with what MA0032/MA0040 report.

OverloadFinder

• New OverloadOptions.IncludeExtensionMethodsFromNotImportedNamespaces. When set (with a SyntaxNode), the candidates also include the extension methods of the compilation and of its references that are accessible at the call site, apply to the receiver, and are not already in scope. They are added after the candidates in scope and go through the same filters.
• The candidates come from an index of the extension methods by name, built lazily once per compilation, only when the option is used. Extension methods of the global namespace are not indexed, as they are always in scope.
• New GetNamespaceToImport(method, syntaxNode), returning the namespace to import when the overload requires a using directive. The analyzers pass it to the code fixes in the OverloadFinder.NamespaceToImportPropertyName diagnostic property.

Code fixes

• New UsingDirectiveHelper: adds the using directive next to the existing ones (innermost namespace declaration that has using directives, otherwise the compilation unit), at its sorted position (System first) when they are sorted, after the global using directives, keeping the file header at the top, with the line endings of the document. FixAll adds it once.
• ArgumentListHelper.AddArgument / GetTargetMethod accept the namespace to import and bind the new invocation in a copy of the compilation where the document imports it. Without it, the overload is not in scope, the invocation does not bind, and the fix would never be offered.
• MA0042/MA0045: the fix renames the method and awaits it. It also fixes an existing bug with an implicit receiver: Do() became await DoAsync(), which does not compile for an extension method; the receiver is now explicit (await this.DoAsync()) when the method cannot be called with a simple name.

Notes for reviewers

• Behavior change: none by default, as the option is false. The first commit of this PR enabled the MA0042 suggestion unconditionally; the second commit makes it opt-in.
• OverloadOptions defaults: the call sites that used options: default keep a zero-initialized OverloadOptions (new OverloadOptions { … }), as its constructor defaults differ (e.g. AllowNumericConversion).
• Cost (only when the option is set): indexing the extension methods of the .NET + ASP.NET reference assemblies (307 assemblies, 4,030 extension methods) takes about 15 ms per compilation once the metadata is loaded. Checking whether an overload requires a using directive repeats a symbol lookup, only for the overload that is found.
• Not handled: the code fix does not detect a name conflict introduced by the new using directive. C# 14 extension(...) block members are only suggested when their namespace is imported.
• Documentation: each rule documentation lists the new option in its .editorconfig section, as the documentation generator requires every configuration key to be documented. docs/README.md is regenerated.

Tests

• Per rule: disabled by default, and diagnostic + code fix adding the using directive when enabled. Per-rule option tests for MA0045/MA0042, MA0001/MA0074, MA0032/MA0040 and MA0167/MA0166.
• MA0042: using placement (sorted, no using directive with a file header, inside a namespace), FixAll, namespace imported in another file, candidates that are not async equivalents, implicit receiver.
• The full suite passes on Roslyn 5.9 (4,717) and 4.8 (4,596); the tests of the affected rules pass on 4.14, 5.0 and 5.6. DocumentationGenerator reports no changes.