Allow processor API to be configurable and to formally be able to lint both a file and its blocks

Update: see updated description below

The version of ESLint you are using.

7.29.0

The problem you want to solve.

A few facts:

1. Per the v7.29.0 blog release, further changes are anticpated toward dropping CLIEngine.

2. Its replacement, the ESLint class, relies on some async-only methods.

3. However, ESLint rules do not, and per @nzakas in this comment, there have been no discussions or apparent interest in making Linter async so that asynchronous rules could be supported.

This all means that if CLIEngine is dropped, rules cannot take advantage of ESLint linting within their own rules.

Why would one want to run linting within a linting rule?

In eslint-plugin-jsdoc, we allow it in three cases all within our jsdoc/check-examples rule:

1. To lint JavaScript code within @example tags

2. To lint a JavaScript value within @default/@defaultvalue tags

3. To lint a JavaScript expression within the likes of @param {type} [name=default] or @property {type} [name=default]

Your take on the correct solution to problem.

Besides adding synchronous methods, I would think that allowing some config to be passed to the ESLint class which triggered use of the synchronous rather than asynchronous methods would be sufficient.

Are you willing to submit a pull request to implement this change?

Yes (if my health-based limits on energy and concentration allow).

[btmills]

I looked at standardizing the existing workaround in which preprocess() returns the full file text as the first “block” in the array. However, that mean would mean the processor and not the user determines when to further lint the file. In contrast, the processor API change released in ESLint v6 was all about giving users control over processors.

I’m now thinking the processor key should optionally accept an array of multiple processors to apply, and the special value "passthrough" would tell ESLint to lint the file as normal in addition to running any other processors:

const config = {
    files: ["*.js"],
    processor: [
        // Continue to lint this file as normal...
        "passthrough",
        // ...but also extract and lint any JSDoc blocks.
        "jsdoc/processor"
    ]
};

[btmills]

Yes, assuming there are no objections, I need to write an RFC that will allow linting a file and extracting its blocks with a processor and linting those too.

There’s already an unofficial way to do that mentioned in #14198, so the RFC may just pave that cow path and add make it configurable.

The second half of this is asking for processor configuration, but if the RFC unblocks the first half, I believe the second half can be achieved with parser options for the processor’s parser and may not need any further changes.