docs: File extension named processor deprecation

[matwilko]

Prerequisites checklist

• I have read the contributing guidelines.

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

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

What changes did you make? (Give an overview)

Added a warning box to the Plugin and Custom Processor docs noting that the file extension-named processor feature has been removed in flat configuration, and therefore will be completely removed in ESLint v9.

Plugin authors need to be aware that when converting to/implementing new flat configs, they can no longer rely on this auto-inclusion, and must explicitly specify their processors in their configs.

[eslint-github-bot]

Hi @matwilko!, thanks for the Pull Request

The first commit message isn't properly formatted. We ask that you update the message to match this format, as we use it to generate changelogs and automate releases.

• The length of the commit message must be less than or equal to 72

To Fix: You can fix this problem by running git commit --amend, editing your commit message, and then running git push -f to update this pull request.

Read more about contributing to ESLint here

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	41c6f71
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/64c3d5cd4333670008048526
😎 Deploy Preview	https://deploy-preview-17362--docs-eslint.netlify.app/use/configure/migration-guide
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[nzakas]

I'm not sure this wording is correct. Can you link to the reference where you found this info?

In particular, if we haven't made any public announcement about deprecation/removal, then we shouldn't insert it into the docs.

(I'm aware I possibly said something at one point, but I can't find any references on my own, so it would be helpful to link to it for context on this PR.)

[matwilko]

I hadn't seen any explicit notice about the change in behaviour, which is why I thought a warning needed adding to the docs 😄

It's just something I've run across while setting up a new project using flat config, and I assumed it was a purposeful change as part of moving to flat config - I even had to shim support into my project locally by post-processing the config array and inserting extra elements after elements with plugins that have extension-named processors to support plugins that haven't updated yet.

Given how explicit flat config likes to make things now, only one processor being permitted per-config-element, and nothing else in the system seeming to modify the array by adding/removing elements, it didn't seem odd that this auto-registration hadn't been brought forward, so I didn't think it was a bug.

If this feature wasn't meant to be removed, then this obviously needs to be converted into a bug report 😄

Reproducible example:

// eslint.config.js
var customPlugin = { 
    name: "custom",
    processors: {
        ".js": {
            preprocess: function(text, filename) { console.log('preprocess'); return [{ text: text, filename: "_" + filename }]; },
            postprocess: function(messages) { console.log('postprocess'); return messages[0]; }
        }
    }
};

module.exports = [
    {
        plugins: { customPlugin },
        //processor: customPlugin.processors[".js"]
    }
];

Commenting/uncommenting the processor turns it on/off - it's not auto-included in the config. Interestingly enough, you also can't refer to these .xx processors by name, processor: "customPlugin/.js" results in TypeError: Key "processor": Expected string in the form "pluginName/objectName" but found "customPlugin/.js".

[nzakas]

Yes, the file extension processors aren't automatically applied in flat config, but you can manually specify them like processor: markdown/.md. I think at some point we were talking about deprecating file extension processors but I can't find a reference, and unfortunately, the team member with the most knowledge about this has left the team.

So, I've left a suggestion for how we can clean up the warning. Please also double-check the linting error.

[matwilko]

As noted above, you can't refer to extension named processors by name in the config - you have to embed the processor object manually because "plugin/.xx" doesn't pass schema validation.

Should I add an extra commit to update the schema validation for processor?

[eslint-github-bot]

Hi @matwilko!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the message to match this format, as we use it to generate changelogs and automate releases.

• The length of the commit message must be less than or equal to 72

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

[matwilko]

@nzakas I've updated the language, with an explicit extra warning that the feature will be removed in ESLint v9.

Also added a fix to the processor string validation to allow arbitrary plugin/processor names to be supported.

[nzakas]

Once again, I really appreciate the enthusiasm, but we can't change the scope of PR once it's started. This one started as a documentation update, which is what we were looking for, so we shouldn't be adding functionality changes into it.

Additionally, changing something as important as the config system can't be done on a whim. It needs to be discussed first, so please open a separate issue with that suggestion.

[matwilko]

No problem, I'll pull out the code change.

Since you already seem to think the system should allow these processors to be named, but it actually doesn't, I'll post it as a new bug fix PR, and we can discuss there 😄

[nzakas]

It might be hard to believe, but after 10 years of working on ESLint, even I don't know how everything works by heart. 😆

That's why we need documentation!

[matwilko]

Haha, I can absolutely believe that with a system this big 😄 But after 10 years, your general feel for how something should be working isn't nothing - our own systems can always surprise us though 😅

Code changes moved into #17384 for review.

[fasttime]

Maybe it would be good to add a note to the migration guide to explain that extension-named processors won't work any more. The mention that the syntax for configuring processors hasn't changed should be updated as well.

[matwilko]

@nzakas Would you prefer an update to the migration guide in a new PR, or can we roll a further docs update into this PR to keep these related updates together?

[nzakas]

@matwilko we can definitely add other docs changes related to explaining file-extension processors in this PR. 👍

[matwilko]

Removed the notice about removal in ESLint 9.

Added a new section to the migration docs covering the differences for processors between eslintrc and flat config, and removed the bullet about processor syntax not changing - while the string form is still around, processor objects can also now be embedded directly.

[fasttime]

LGTM. Leaving open for @nzakas to verify.

[nzakas]

Getting close, just a couple of tweaks to clean things up.

[nzakas]

LGTM. Thanks!