Docs: Consider explicitly mentioning rule report properties as not covered by semver

[JoshuaKGoldberg]

Before You File a Documentation Request Please Confirm You Have Done The Following...

• I have looked for existing open or closed documentation requests that match my proposal.
• I have read the FAQ and my problem is not listed.

Suggested Changes

Splitting out of discussion in #8640:

1. That absolutely-reasonable-and-fine change on our end changed the properties of the no-unused-vars rule report
2. We then learned that an external plugin, eslint-plugin-unused-imports, was relying on a now-removed property of no-unused-vars: This plugin breaks when using typescript-eslint 7.8.0. sweepline/eslint-plugin-unused-imports#77
3. It was then unclear to folks: did we break any contracts by changing the properties of the rule in a non-major version?

The answer to (3) is: no, the fact that the rule report switch from node to loc is not covered by our public API contracts. It's an implementation detail that's only exposed to the plugin through eslint-rule-composer: https://github.com/sweepline/eslint-plugin-unused-imports/blob/d77f8e402f09a31a82ca2416b5fe4dace18e0599/lib/rules/no-unused-vars.js. We explained the situation more deeply in the discussion in #8640.

But, in folks' defense, https://typescript-eslint.io/users/versioning/#eslint-plugin never explicitly says whether rule properties are part of the public API. Proposal: let's add a quick list item in the "shall not be considered breaking" section mentioning them?

Affected URL(s)

https://typescript-eslint.io/users/versioning#eslint-plugin

💖

[bradzacher]

From a user's perspective they don't know why it broke - just that it broke.

The reality is that the 3rd party monkey-patched our rules to expose private implementation details to themselves.

No amount of docs will fix that because they can't tell from the crash that the reason it broke was due to this. So you'd still get issues - you'd just get issues that you can close with a doc link.

---

Rule report objects have always been considered "opaque" objects - they're not intended to be consumed by a user and are only intended for use by eslint (eg via ESLint itself then via an ESLint formatter - which 99.9% of the time is an internal ESLint formatter).

ESLint itself regularly changes what is part of the objects - changing report nodes, messages, data, etc.

[Josh-Cena]

I don't think this should be documented. ESLint rules' code is fully internal; the only guaranteed behavior is what ESLint reports through its API or CLI. This can broadly fall into "Refactors a rule's code in a way that does not introduce additional reports."

[JoshuaKGoldberg]

That makes this easier. 🙂