Intellisense for "settings" files

[travisclagrone]

User Story

As a writer of PSScriptAnalyzer settings files
I want intellisense (autocompletion, hover information, validation)
so that I can have a modern editing experience.

Discussion

Intellisense is an expected part of the modern editing experience. It not only improves programmer efficiency and code correctness, but also discoverability and new user satisfaction (vs. frustration).

Settings in a shell scripting context are generally set either as command options (e.g. PackageManagement\Set-PackageSource -Trusted) or as a data file (e.g. Format.ps1xml). PSScriptAnalyzer uses the data file approach, which is reasonable considering both the use case as well as the extent of possible settings.

PowerShell data files (.psd1) do not have an associated schema specification, and therefore do not support content-specific intellisense. Unfortunately, it does not appear that much progress is being made on this issue from a PowerShell-language standpoint (see PowerShell #4016).

The lack of intellisense for PowerShell script analysis settings stands in contrast to other fundamental PowerShell settings files. E.g. Types.ps1xml and Format.ps1xml files get intellisense because they have schemas. They are able to have schemas because they use a data language (XML) that has an associated schema language (XSD).

The documented format of PSScriptAnalyzer settings files is expressible as a hash table containing only booleans, strings, and arrays of strings. This simple structure does not require the full expressivity of the .psd1 format (e.g. imperative script blocks). Moreover, this structure both resembles and is expressible as JSON, which does have an associated schema language (JSON Schema) that is supported by intellisense in modern editors (e.g. VS Code). Furthermore, PowerShell has built-in cmdlets for JSON (e.g. ConvertFrom-Json).

Proposal

1. Formalize the schema of PSScriptAnalyzer settings using JSON Schema.
2. Accept JSON as a valid file format for PSScriptAnalyzer\Invoke-Formatter -Settings and PSScriptAnalyzer\Invoke-ScriptAnalyzer -Settings.

These two changes would enable editors to provide intellisense for the vast majority of PSScriptAnalyzer settings files.

(The only aspect of PSScriptAnalyzer settings files for which these changes would not enable intellisense is custom rules. As such, that should necessarily be a separate and subsequent feature request.)

An alternative would be to extend the PowerShellEditorServices intellisense feature to provide the requested intellisense. Doing so might be required for custom rule intellisense and documentation, but would likely be more work than is required for built-in rule intellisense. This is because is built-in rules are known at compile time, and so a static JSON schema may published for them.

[bergmeister]

At the moment, PSSA cannot report errors in settings files at all (#1053), therefore I'd consider it more important to report better errors in settings files before doing things like IntelliSense but we would be happy to accept a PR for that if it preserves backwards compatibility of old settings file. Are you planning to work on it?