Parser services are undocumented

[not-an-aardvark]

The parseForESLint API from #6974 was added in #6975, but there isn't any documentation for this.

[VictorHom]

@not-an-aardvark
For this issue, should it be a new .md file under docs/developer_guide or can it live in an existing file?

I've read through #6974 and #6975 (among other links in those threads and pr) and I don't have experience with this feature.

From what I understand, the parseForESLint capabilities are meant to work with services like https://github.com/eslint/typescript-eslint-parser . By default, the parser will parse with existing configurations. If you set up your eslint configurations with "parser": "my-custom-eslint-parser", then that means"my-custom-eslint-parser" is going to create your own AST for ESLint to work with. The custom ESLint parser should reveal a function "parseForESLint" which is what the ESLint linter will use to make the AST.

Question:
Does the custom parser have to use a certain type of javascript parser? I'm unfamiliar with the parsers. If you have any good resources for high level overview, I would greatly appreciate.

[not-an-aardvark]

Sorry about the delay -- I missed this notification and hadn't realized you replied.

Basically, a parser is a module which accepts some some source code text and returns an AST. By default, ESLint uses the espree parser to create an AST.

Parsers work by exposing a parse method. The parse method accepts the source code text as the first argument, and can optionally accept an object containing parse options as the second argument. The parse method returns an AST, which must conform to the ESTree specification. Beyond this spec, there aren't any requirements for how the parser is implemented. For example, a parser could theoretically ignore the source text and return an entirely unrelated AST. (Of course, a parser that did this would not be very useful.)

The motivation for #6974 was that it would be useful for parsers to be able to provide additional data or functionality, beyond just an AST. For example, it would be nice if the typescript parser could provide type-checking capabilities, but that wasn't possible with the parse method because it was required to just return the AST.

To allow this, we now use the parseForESLint method on a parser (and fall back to the parse method if parseForESLint isn't present). parseForESLint accepts the same arguments as parse, but instead of just returning an AST, it returns an object where the ast property is the AST. The object can also have a services property containing arbitrary parser-dependent services (e.g. type-checking methods). The value of the service property is available to rules as context.parserServices.