Add AvoidReservedWordsAsFunctionNames Rule

[liamjpeters]

PR Summary

Adds a new rule that warns when reserved words are used as function names.

function function {}

function if {
    function else {}
}

function global:try {}

function private:catch {}

Fixes #2099

I wrote a blog post about putting this together 😀

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]

Just as a note...

I did attempt to use reflection rather than a hard-coded list of keywords. The keyword list is in the Tokenizer.

public static HashSet<string> GetReservedWordsFromTokenizer()
{
    // Get the assembly containing Tokenizer
    var asm = typeof(Token).Assembly;

    // Get the internal Tokenizer type
    var tokenizerType = asm.GetType("System.Management.Automation.Language.Tokenizer");

    // Get the private static readonly field s_keywordTokenKind
    var field = tokenizerType.GetField("s_keywordTokenKind", BindingFlags.NonPublic | BindingFlags.Static);

    // Get the TokenKind[] value
    var tokenKinds = field.GetValue(null) as Array;

    var reservedWords = new HashSet<string>(
        tokenKinds.Cast<Enum>().Select(tk => tk.ToString()),
        StringComparer.OrdinalIgnoreCase
    );

    return reservedWords;
}

With similar on the PowerShell side for the tests.

This worked fine in PS7 but I can't seem to get it to work in PS5.1 - I can't access the s_keywordTokenKind or s_keywordText field.

[andyleejordan]

This worked fine in PS7 but I can't seem to get it to work in PS5.1 - I can't access the s_keywordTokenKind or s_keywordText field.

That makes sense to me. We've run into similar issues in PSES because the visibility of some of them changed making them available through reflection in PS7 but still not in PS5.1. Oh well 🫠

[andyleejordan]

@SeeminglyScience can you take a look at this too? Seems pretty good to me and reasonable to add as a default.

[andyleejordan]

I'm good with this, just want @SeeminglyScience to double check. I'll send it his way.

[SeeminglyScience]

Definitely a useful rule, ty Liam! Couple of small changes

[liamjpeters]

We did it, high-fives all round 🫸🫷

[SeeminglyScience]

LGTM!

[michaeltlombardi]

LGTM!