New: Suggestions

designs/2019-suggestions/README.md

@@ -0,0 +1,44 @@
+- Start Date: 2019-07-04
+- RFC PR: (leave this empty, to be filled in later)
+- Authors: Ilya Volodin, Dan Abramov
+
+# Code Suggestions
+
+## Summary
+
+This RTC proposes introducing a new mechanism for providing users with suggestions. It's very similar to fixes mechanism that already exists in ESLint, but will provide ability to create multiple suggestions per rule, suggestions will not be automatically applied by using `--fix` flag, and will require user interaction. This feature will only be exposed through the ESLint API, and will not be available on the CLI. 
+
+## Motivation
+
+This has been suggested multiple times before, but the main driving force behind this proposal is ability to provide user with options on how to automatically refactor/fix their code, without a possibility of "stealthily" breaking it. Examples of such suggestions include ability to suggest adding `import` statement if certain code is added to a file by the user, ability to provide refactoring suggestions like extracting repeated value into a variable, reformatting code to extract repeated statements into reusable function, etc. I do not envision ESLint team to initially create any rules that would provide suggestions, so this would be a feature that would enable plugin authors to do so, but it might be something that ESLint team will eventually do. This feature is geared towards code editor integrations, as such, it will only be available via NodeJS API.
+
+## Detailed Design
+
+* Modify `context.report` function to include optional last parameter of type array of functions. Each function will be able to modify the code of the file to implement suggestion. Syntax is going to be exactly the same as for `fix` functions.
+* Create a new library `SourceCodeSuggestions` that would provide an class with ability to add new suggestions to it. Class will be shaped (or expose) like an object where key is full rule name, and value is a function that can modify the code.
+* Change `_verifyWithoutProcessors` and `_verifyWithProcessor` functions in linter.js to add suggestions returned by the rules to the instance of the `SourceCodeSuggestions` class. Modify output of those functions to include `SourceCodeSuggestions` instance.
+
+## Documentation
+
+This would need to be documented as part of the public API.
+
+## Drawbacks
+
+This might potentially be a bit confusing, since we do not have many functions that we provide through API only and not through CLI.
+
+## Backwards Compatibility Analysis
+
+Since last parameter in `context.report` is optional, this should be fully backwards compatible.
+
+## Alternatives
+
+This functionality is basically the same as existing `autofix` functionality already included in ESLint. The only difference is there might be multiple suggestions per error and they are not applied automatically by ESLint.
+
+## Open Questions
+
+Should we consider instead providing new type of `rules` that would not report any issues, but only provide suggestions?
+
+## Related Discussions
+
+https://github.com/eslint/eslint/issues/7873
+https://github.com/eslint/eslint/issues/6733#issuecomment-234656842