feat: definePlugin

[JoshuaKGoldberg]

Summary

Adds a definePlugin function to @eslint/plugin-kit as a recommended way to group plugin configs, meta, and rules.

Related Issues

• Change Request: Provide a definePlugin function in @eslint/plugin-kit rewrite#176
• Enhancement: Support Lazy Loading Rules typescript-eslint/typescript-eslint#11029
• Support Lazy Loading Rules vuejs/eslint-plugin-vue#2732

[michaelfaith]

This seems like an adjacent but separate conversation.

[nzakas]

Thanks for all the work and research you put into this.

At a high-level, I can see the value of a definePlugin() helper function that:

• provides type safety
• makes it easier to define configs
• enforces best practices (requiring meta.name, meta.version, and meta.namspace

I'm less convinced with some of the more ambitious parts of this proposal such as:

• lazy-loading rules
• autocreation of configs

By way of example, defineConfig()s goals were primary to provide type safety and add an extends key, so I'm wondering if maybe it makes sense to scale down definePlugin()'s MVP?

[JoshuaKGoldberg]

I'm less convinced with some of the more ambitious parts of this proposal such as:

Added:

• autocreation of configs: 5d25577
• lazy-loading rules: feat: definePlugin #132 (comment) ✅

[kirkwaiblinger]

Not totally following this... Are we saying that if I provide

definePlugin({
   meta,
   rules,
   configs: {
     [`${pluginName}/recommended`]: { /* ... */  },
     config1: { /* ... */ },
     config2: { /* ... */ },
   }
});

that all these configs should be transformed? Or that only the `${pluginName}/recommended` one will be? Or maybe something else?

[JoshuaKGoldberg]

Ah, you're right, this is weirdly phrased and kind of wrong. It's the first one. Each individual config will be transformed. Edited:

• This part just says it's an object whose properties describe the configs to create.
• Generated Configs describes the key-value mapping in more detail

cc4e515

Is that more clear? I'm having a hard time describing this.

[fasttime]

Thanks for your work, and apologies for the delayed review. I've added some comments throughout. Given the length of the text, I may have missed something. Feel free to let me know if anything in my remarks seems off.

[JoshuaKGoldberg]

@fasttime @nzakas I removed the config rules generation points and noted them as out of scope, similar to lazy-loading rules. The only modification the definePlugin function now would do is merging in a plugins array with the plugin set by meta.name.

[fasttime]

I think this RFC slipped off our radar for a bit while we were busy with the v10 release. Reading the updated proposal, it seems the main behavior change is that definePlugin would automatically inject the plugin into each provided config (i.e. add plugins: { [meta.name]: plugin }).

That seems useful for the common case. My only concern is that there will be cases where this behavior is undesirable or at least surprising, where plugin authors don't want plugins populated automatically.

To avoid having an automatic behavior that can't be opted out of, maybe we could make this explicit via an option (e.g. addPluginToConfigs: true)? That would keep the helper purely pass-through + validation by default, while still supporting this convenience when required, and it leaves room for additional opt-in behavior later.

For comparison, defineConfig doesn't mutate the passed in config by default; it adds new syntax (extends) to opt into extra functionality. Thoughts?

[bradzacher]

My only concern is that there will be cases where this behavior is undesirable or at least surprising, where plugin authors don't want plugins populated automatically

Is it worth designing around the 0.0001% case? Couldn't those users just not use the function?

[fasttime]

Is it worth designing around the 0.0001% case? Couldn't those users just not use the function?

For example, a plugin like @eslint/markdown that provides a "recommended-legacy" config in eslintrc format couldn't be implemented using only definePlugin as it's currently proposed.

Previous versions of this RFC also included other useful features, such as automatically generating a recommended config. Those ideas were ultimately dismissed because there was no way to opt out of the proposed behavior, which made the helper function less adoptable. That's why I'd suggest avoiding modifying the plugin automatically. If we want to apply defaults for common cases, it would be good to provide at least opt-outs for each of them.

[JoshuaKGoldberg]

that provides a "recommended-legacy" config in eslintrc format

Is that a problem, though? This RFC has no intention of supporting eslintrc. I'm under the impression that's out-of-scope for general ESLint projects as of ESLint 10.

dismissed ... avoiding modifying the plugin automatically

In my mind, the difference between this still-in-the-RFC name merging behavior and those past utilities is that this name merging behavior is seen as useful 100% of the time, whereas those were more subjective. Without the eslintrc use case, is there any time when someone wouldn't want that behavior?