ESLint version

v8.55.0

What problem do you want to solve?

With the new flat config system, configs are only allowed to export known properties like rules, files, etc.

However, in third-party tooling I maintain like eslint-doc-generator and lintbase.com, I've been letting plugins set an unofficial description / meta.description / meta.docs.description property to annotate their configs (or processors) with a description that can be included in the auto-generated documentation for the plugin. This won't work anymore as flat config will throw an error like Error: Unexpected key "meta" found..

Furthermore, there are a variety of documentation-related properties used, allowed, or not allowed by ESLint core objects/concepts today, and this can be inconsistent and inflexible:

• Plugins: Can export meta.name and meta.version
• Rules: Can export anything, official properties are in meta or meta.docs, meta.docs.description is commonly used
• Rule options: Can export properties controlled by JSONSchema including description
• Configs: No meta/documentation properties currently allowed, but a name property can be included to help with debugging
• Processors: Can export meta.name and meta.version for debugging

What do you think is the correct solution?

In general, it would be useful to be able to accommodate at least the following rule documentation properties on any of the ESLint-controlled core objects/concepts: description, url, deprecated, replacedBy, plus space for arbitrary third-party/user-defined properties.

The challenge is how to place these properties in a consistent fashion across object types and in consideration for the already existing properties.

In particular, some of these rule properties are spread across meta and meta.docs. The dividing line between meta and meta.docs can be a bit blurry. I was thinking that meta would be for properties that are functionally used by ESLint, whereas meta.docs would be for non-critical/informational/custom properties that aren't necessarily used or needed by ESLint. By that division, description, url, deprecated, replacedBy would likely all fall under meta.docs.

Some ideas for improving the consistency and flexibility of properties on ESLint core objects/concepts:

1. Always allow meta.docs as an arbitrary object for any documentation / third-party properties.
2. Suggest using meta.docs for documentation properties like description, url, deprecated, replacedBy.
   • One exception to this: rules place deprecated and replacedBy directly on meta.
   • We can encourage using these common properties and suggest formats for them, as we do today with rules, as they are good for the health of the plugin ecosystem and often used by IDEs and third-party tooling, but ESLint itself wouldn't necessarily enforce anything about them.
   • The list of documentation properties I have mentioned so far is not necessarily comprehensive as it's just a starting point based on existing, commonly-used rule properties.
3. Whenever a name or version is needed to be specified, include it in the meta object. So we could update configs to accept meta.name (falling back to the current name property for backwards compatibility if needed).

To summarize: I took an initial stab at holistically considering documentation properties, but my top priority is really just to decide where documentation properties should go on each ESLint core object (in meta.docs in my proposal) without necessarily specifying a complete list of all potential documentation properties and their exact formats.

Related issue about the deprecation properties:

• Change Request: Support additional rule metadata for deprecations #18061

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response