Allow plugins to override default options (#3991)

* refactor(cli): defer default value applying

* Allow plugins to override default options

* Move "defaultOptions" to top level of plugin

* Simplify implementation

* Attach plugin name

* Add pluginOptions to cli help

* Update snapshots

* Code review (immutable style)

* Add test for help output

* Use snapshot test, fix Object.assign

* Refactor to immutable style

* Add test case for automatic plugin resolution

* Add tests for applying and overriding default opts

* Remove "since" option

* Only set defaults for CLI args when no pluginDefaults are present

* Revert workaround, rebase to #4045

* Add basic documentation for `options` and `defaultOptions`

docs/plugins.md

@@ -46,7 +46,13 @@ If the plugin is unable to be found automatically, you can load them with:
 
 ## Developing Plugins
 
-Prettier plugins are regular JavaScript modules with three exports, `languages`, `parsers` and `printers`.
+Prettier plugins are regular JavaScript modules with five exports:
+
+* `languages`
+* `parsers`
+* `printers`
+* `options`
+* `defaultOptions`
 
 ### `languages`
 
@@ -149,6 +155,33 @@ function embed(
 
 If you don't want to switch to a different parser, simply return `null` or `undefined`.
 
+### `options`
+
+`options` is an object containing the custom options your plugin supports.
+
+Example:
+
+```js
+options: {
+  openingBraceNewLine: {
+    type: "boolean",
+    category: "Global",
+    default: true,
+    description: "Move open brace for code blocks onto new line."
+  }
+}
+```
+
+### `defaultOptions`
+
+If your plugin requires different default values for some of prettier's core options, you can specify them in `defaultOptions`:
+
+```
+defaultOptions: {
+  tabWidth: 4
+}
+```
+
 ### Utility functions
 
 A `util` module from prettier core is considered a private API and is not meant to be consumed by plugins. Instead, the `util-shared` module provides the following limited set of utility functions for plugins: