WIP: Add support for JSON Settings Files

[liamjpeters]

PR Summary

Very much a work in progress, but all (still applicable) tests pass and json files are usable wherever .psd1 settings file can be used.

A refactor of settings handling with the main goal being to add support for multiple settings file formats - adding JSON support. I also found the pre-pr settings implementation quite hard to follow. Lots of contradictory comments and a single class with a lot of responsibility.

• Adjusted settings to have a data model class SettingsData. The Settings file then becomes a static helper class then takes responsibility for constructing them based on need:

  • preset name
  • inline hashtable
  • filepath of settings file
  • Auto-discover settings file in CWD

  delegating to registered parsers when appropriate to parse settings files.

• Defined an ISettingsParser interface with 2 implementations. JsonSettingsParser and Psd1SettingsParser. Hashtable -> SettingsData done by HashtableSettingsConverter. These parsers are registered with Settings class and used to parse files. The first parser to be able to parse the file "wins". The parsers define the file extension they can parse.

• Internal location of Settings Presets moved from Engine\Settings -> Engine\SettingsPresets so Settings folder can be used for all Settings logic and parsers. Presets are still shipped in the built module's Settings folder.

• Internal location of Command Data Files moved from Engine\Settings -> Engine\CommandDataFiles. Separated out from the Settings Presets, as presets could now be in .json format - which is what previously distinguished the command data files from presets. They are shipped with the module in a new folder CommandDataFiles and a helper function added to get this folder path Settings.GetShippedCommandDataFileDirectory(). This is consumed by AvoidOverwritingBuiltInCmdlets and UseCompatibleCmdlets which load and use the data files.

• Amendments to auto discovery to search for settings files in the current working directory based on registered parsers supported formats, in order. For instance with the JsonSettingsParser and Psd1SettingsParser registered (in that order) - Auto-Discovery searches for PSScriptAnalyzerSettings.json first, followed by PSScriptAnalyzerSettings.psd1.

• Amendments to preset resolution to support different settings file formats. You could define multiple presets with different extensions. Registered parser order would decide which was used.

Added lots of comments - not to everyone's taste, but it certainly helps me.

Still to look at:

• Lots of testing. Plenty of coverage needed to ensure no regression. Testing around loading formats and that each format produces the same SettingsData object for equivalent input. Can use Settings.Create('path\to\file\with\file.extension') helper to construct the object.
• Need to check on other (case sensitive) platforms that there are no issues.
• Fixup error messages so they match the current user-experience where possible.
• An idea for a New-ScriptAnalyzerSettingsFile command which will create a PSScriptAnalyzerSettings file for a project. Would have options for it to be based off of a preset, bare (just the structure), or include all current rules and settings (with their default values that you can then easily tweak and play with). Could extend the parser interface to include serialisation in that format. I've seen lots of people not know settings file exist for this tool. Having a first class command to create them is more discoverable than a docs page. Down the line you could imaging this functionality being surfaced in VSCode as a 'Create Settings File` command or similar.

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.