Refactor Linter to reduce API surface

[not-an-aardvark]

I think it would be a good idea to refactor Linter in the near future. The goal is to reduce the amount of undocumented API surface area, and simplify the interactions between core modules to make them easier to maintain. Node.js API users frequently handle Linter instances, and having too much API surface area makes it more likely that users will rely on undocumented behavior, and then have their integrations break when we change the implementation details in the future.

Specific action items:

• Don't make Linter a subclass of EventEmitter.

  Linter happens to use the EventEmitter API internally, but there's no reason it has to expose the entire EventEmitter API by being a subclass. We don't want users to use Linter instances in the same way that they would use generic EventEmitters (for example, we don't want API users to do something like linter.emit("foo", node) or linter.on("foo", listener) directly). Instead, one option would be to store an instance of EventEmitter as a private property. Another (possibly better) option would be to use a new EventEmitter for each verify call.

• Don't give RuleContext objects access to the underlying Linter instance.

  Currently, rules can call methods on the Linter instance by accessing context.eslint. This allows them to interfere with other rules, or report problems as other rules (e.g. with context.eslint.report("some-other-rule", ...).

  I think it would be better to have the RuleContext constructor accept a report function as an argument. That way, it wouldn't need a reference to Linter at all -- it would just be able to emit reports.

• Make Linter#verify be side-effect-free.

  Instances of Linter are mutable, and it's probably too late to change that. However, I think it would be good to prevent Linter#verify from having side-effects. To do this, we would get rid of properties like linter.messages, linter.currentConfig, linter.sourceCode, etc. and pass the values around internally instead. We would also remove methods like getAncestors from Linter (and provide an equivalent replacement elsewhere to avoid changing the rule API), since getAncestors necessarily involves some hidden state about the current traversal point, and it doesn't make sense for users of ESLint's Node API to call getAncestors directly.

[not-an-aardvark]

Status of this issue:

• Most undocumented properties have been removed from Linter.
• There are still a few undocumented properties (rules and environments) that I'd like to remove. However, these properties are used in other parts of the codebase, so removing them will require some more refactoring.
• Linter#verify is mostly side-effect-free, except for the fact that it changes the value of Linter#getSourceCode. We can't remove Linter#getSourceCode right now because it's documented here. We could remove it in a major release, but we would probably need to create a usable replacement for it first. (For example, the ESLint demo currently uses Linter#getSourceCode because it's the only good way to get a SourceCode instance for the text being linted.)

[nzakas]

@not-an-aardvark are you still working on this?

[not-an-aardvark]

Not really, I'll close it.