Support SuggestedCorrections property on DiagnosticRecord for script based rules

[bergmeister]

PR Summary

Closes #619
Populate property and make it public to keep construction of the object easy.

PR Checklist

Note: Tick the boxes below that apply to this pull request by putting an x between the square brackets. Please mark anything not applicable to this PR NA.

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• User facing documentation needed
• Change is not breaking
• Make sure you've added a new test if existing tests do not effectively test the code changed
• This PR is ready to merge and is not work in progress
  • If the PR is work in progress, please add the prefix WIP: to the beginning of the title and remove the prefix when the PR is ready

[JamesWTruher]

This looks great and really needed. My comment is not blocking as we can go back and change it later.

[JamesWTruher]

in PowerShellCore tests, we're moving away from using new-object in favor of this:

$l = [System.Collections.ObjectModel.Collection[Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.CorrectionExtent]]::new()
$c = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.CorrectionExtent]::new(1,2,3,4,'text','filePath','description')
$null = $l.Add($c)
$dr = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]::new(
    "This is help", 
    $ast.Extent,$PSCmdlet.MyInvocation.InvocationName,
    "Warning",
    $null,
    $null,
    $l)
return $dr

which I think is much tidier. I know it's inconsistent, but that's ok - we can go back where we need to.

[bergmeister]

@JamesWTruher I tried it at first but then had to revert this change because the [Type]::new() constructor was only introduced in version 5, therefore it failed the WMF4 build and we should not document examples that do not work on supported PS versions. Will therefore merge

[JamesWTruher]

yah - I thought about this again last night and realized this wouldn't work because of the downlevel requirements. We won't be able to support the modern constructor syntax until we drop support for ps v3/4

[LaurentDardenne]

For information, these changes are a breaking change, because a priori the 'lookup algorithm' of Powershell does not know how to call the code that worked previously.

[bergmeister]

@LaurentDardenne I am sorry for that, every release comes with minor breaking changes, which are usually for a better experience, which is to actually propagate the SuggestedCorrections to the end user (one can use them inside vscode now for example). Thank you for your continued and detailed feedback though :)
You could create a DiagnosticRecord as follows to avoid any future breaking changes in the constructor (which is from the examples that I documented here), which will also work on PS versions lower than 5 in contrast to the ::new operator

[Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
    "Message"              = "This is a rule with a suggested correction"
    "Extent"               = $ast.Extent
    "RuleName"             = $PSCmdlet.MyInvocation.InvocationName
    "Severity"             = "Warning"
    "SuggestedCorrections" = $suggestedCorrections
}

[LaurentDardenne]

"every release comes with minor breaking changes,"
I agree, but it better when the changelog contains this change.
Here, I discover it.