feat: Flat config support in Linter (refs #13481)

[nzakas]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[ ] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofixing to a rule
[ ] Add a CLI option
[x] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Updated Linter to accept FlatConfigArray as an argument. To do so, I added a new configType option that must be set to "flat". When set to "flat", the defineRule, defineRules, and defineParser methods all throw an error because there is no good way to mimic this functionality with flat config. (People can instead define a plugin directly in the config.) Ultimately, we'll end up removing these methods.

I've only added enough tests to verify each of the initial paths for flat config. In a future pull request I'll work on converting the existing tests to work with flat config. I just don't want to wait too long before merging these changes in order to avoid conflicts.

Note: These changes are a prerequisite for the ESLint class changes.

Task list:

• Linting both with and without processors
• Environments do not work when configType is "flat"
• Globals added via comments are correctly added to the global scope
• Autofixing
• context.parserPath compatibility
• context.languageOptions doesn't exist
• languageOptions.ecmaVersion is year-based (2015 instead of 6)
• languageOptions.ecmaVersion translates to parserOptions.ecmaVersion
• languageOptions.ecmaVersion adds globals for the appropriate version
• languageOptions.ecmaVersion: 3 only has ES3 globals
• languageOptions.sourceType: "commonjs" adds Node.js globals
• languageOptions.sourceType: "commonjs" switches parser options to parse global return
• Convert all eslintrc tests into flat config tests
• Update defaults (reconsider the defaults of eslint config #14588)
• All tests passing

Is there anything you'd like reviewers to focus on?

Is there any danger in merging this?

[nzakas]

Since feedback is a bit slow these days, I'm going to convert to a draft and keep adding changes to this PR.

[nzakas]

With context.parserPath -- it appears there's no easy way to make this work. I thought I could stick something into require.cache, but I didn't fully appreciate the complexity of attempting to do that.

At this point, I think the best path forward is to encourage people to switch to using context.languageOptions.parser if present and default back to context.parserPath if not.

This situation will only arise when someone is using flat config, which case context.parserPath won't have a value; for eslintrc configs, everything will continue to work as usual.

Thoughts?

[mdjermanovic]

With context.parserPath -- it appears there's no easy way to make this work. I thought I could stick something into require.cache, but I didn't fully appreciate the complexity of attempting to do that.

I don't think there's any way to reliably find the path, because the config gets just the loaded parser object.

At this point, I think the best path forward is to encourage people to switch to using context.languageOptions.parser if present and default back to context.parserPath if not.

Agree, this was already predicted in the RFC:

11. Replace context.parserPath with context.parser (the path to the parser is no longer valid)

[nzakas]

Moved globals here since the list is much smaller without environments, allowing us to update more easily and also support ES3 correctly (right now we still add JSON when ecmaVersion is 3.

[nzakas]

Updating the defaults as briefly discussed in #14588. I think it makes sense to assume people will be using ESM and always want the latest ecmaVersion.

[nzakas]

For .cjs files, I think it makes sense to opt them into "commonjs" sourceType.

[nzakas]

Okay, I think I've got everything

[nzakas]

I just upgraded Espree and eslint-scope to the versions that support sourceType:commonjs and eliminated a bunch of the code that managed that conversion. Should be all set now.

[mdjermanovic]

Is there any danger in merging this?

I could find only 3 differences with eslintrc configs before and after this change.

---

1. If configured parserOptions doesn't have sourceType property, what will be passed to parsers as sourceType property in the options object that is the second argument of parse()/parseForESLint().

• Before this change: there will be no sourceType property in the options object.
• After this change: sourceType: undefined.

In theory, this could affect parsing, depending on how the handling of options is implemented in a custom parser, although it does not seem likely. Thoughts? I checked espree, @typescript-eslint/parser and @babel/eslint-parser, and It doesn't seem that this change will affect the behavior.

---

2. Possible ecmaVersion values passed to eslint-scope.

• Before this change: 3, 5, 6, 7, 8, 9, 10, 11, 12, 13.
• After this change: 3, 5, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022.

eslint-scope expects ecmaVersion normalized to 6 ... 13, not 2015 ... 2022. Nonetheless, this change doesn't really affect the scope analysis, because the only conditions related to ecmaVersion in eslint-scope are ecmaVersion >= 5 and ecmaVersion >= 6, so they'll work the same with 2015 ... 2022 instead of 6 ... 13. However, there are no tests in eslint-scope that would make sure that 2015 and others work the same as 6, all tests are based on the 6 ... 13 normalization.

---

3. ecmaVersion passed to eslint-scope when a custom parser is used and ecmaVersion is not a number.

• Before this change: 6 (per Change Request: If ecmaVersion: latest pass ecmaVersion: 6 to eslint-scope #15256).
• After this change: 2022.

Similar to the previous point, this doesn't really change how eslint-scope works.

[nzakas]

1. I don’t think it’s worth addressing this now. While it’s technically a change, it shouldn’t affect anything. And if it does affect something, it will be easier to solve when we have a real world use case.

2. Can you open an issue on eslint-scope for that? We can certainly add tests.

3. This is intentional. The new default ecmaVersion with flat config is latest.

[mdjermanovic]

2. Can you open an issue on eslint-scope for that? We can certainly add tests.

eslint/eslint-scope#82

[mdjermanovic]

In the if (config.processor) path, _verifyWithFlatConfigArray calls _verifyWithFlatConfigArrayAndProcessor with options.preprocess, and then _verifyWithFlatConfigArrayAndProcessor calls _verifyWithFlatConfigArray with the same options.preprocess, so this will run config.processor.preprocess() again on its output:

const { Linter } = require("eslint");

const linter = new Linter({ configType: "flat" });

const config = {
    files: ["*.md"],
    processor: {
        preprocess(text, filename) {
            console.log(`Called with text = '${text}', filename = '${filename}'`);

            return [{ text: "bar", filename: "0.js" }];
        },
        postprocess() {
            return [];
        }
    }
};

linter.verify("foo", config, "a.md");

// logs:
//       Called with text = 'foo', filename = 'a.md'
//       Called with text = 'bar', filename = 'a.md/0_0.js'

[nzakas]

Huh, nice catch. I'll look at that.

Just FYI: It was a little bit difficult to understand that you were pointing out a problem here. When you state the behavior you're seeing, it would help me out a lot if you'd say something like, "This behavior is unexpected and I don't see it when using eslintrc." This is probably just the brain fog, but little hints like saying "unexpected" make it a lot easier for me to decipher descriptions.

[mdjermanovic]

_verifyWithoutProcessors (resolveParserOptions) is overwriting globalReturn regardless of the parser, but _verifyWithFlatConfigArrayAndWithoutProcessors will do that only if the parser is Espree?

[nzakas]

Yes. I don’t think we should be messing around with other parsers’ options. Ideally, the parser itself will throw an error with an unexpected combination of options. I think we should do that, too, but it would be a breaking change.

[mdjermanovic]

LGTM, thanks!

[nzakas]

@btmills can you give this a once-over before I merge?

[btmills]

I only found one potential functional change where this branch is currently passing void 0 as parserName. I left a couple inline suggestions, but if the void 0 question is answered, this can be merged as-is.

I'm very excited to see this go into the release, even if undocumented. Great work!

[btmills]

It would be possible for this test and the next few, which also use this pattern, to pass if Program() were never called. Elsewhere you declare let ecmaVersion; above, assign it here, and move the assertion to the line after the verify() call so that the assertion is guaranteed to be called. Not a required change, but I wanted to point it out in case you prefer that pattern.