Add -ScriptBlock parameter to Invoke-ScriptAnalyzer

[liamjpeters]

PR Summary

Two separate but related changes (in different commits)

Adds a -ScriptBlock parameter to Invoke-ScriptAnalyzer

Can be passed by pipeline and also positionally.

Invoke-ScriptAnalyzer -ScriptBlock {
    $foo = 'bar'
}

Invoke-ScriptAnalyzer {
    $foo = 'bar'
}

{$foo = 'bar'} | Invoke-ScriptAnalyzer

I would say the usefulness of it is perhaps mixed/niche. For instance, it can never report a parse error, as the ScriptBlock must already be valid at runtime before it gets to Invoke-ScriptAnalyzer to be stringified and analysed.

It feels like this should already be part of PSSA. The number of times that I've tried to use a ScriptBlock is silly at this point - only to realise I need to quote (and fix existing quotes etc).

closes #1937

Remove ValueFromPipeline and Position=0 from ScriptDefinition

These are functionally impossible to use as there's no disambiguating parameter to differentiate the two (sets of two) string parameter sets ScriptDefinition, and Path. One of the path parameter sets is the default so pipeline and positional strings are always bound to Path.

Some doc updates that go along with it (I'm no wordsmith, so I'm very open to making any suggested changes here)

closes #2130

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Change is not breaking
• Make sure all .cs, .ps1 and .psm1 files have the correct copyright header
• Make sure you've added a new test if existing tests do not effectively test the code changed and/or updated documentation
• 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.

[liamjpeters]

A thought occurs to me that this could potentially be a breaking change as is - albeit a fairly low risk one.

There could be usage in the wild where the -ScriptDefinition parameter is used in a shortened form.

Currently everything from -Sc to -ScriptDefinition is permissible as there's no conflicting parameter name, so no ambiguity.

Introducing -ScriptBlock means that the below become ambiguous and will error if used.

• -Sc
• -Scr
• -Scri
• -Scrip
• -Script

I know a it's not a definitive source but searching GitHub using a regex, I can only find shortened parameter usages in text (not code). All copies of the same file from DbaChecks.