Bug: JSON v1.0.1 is not backward-compatible with ESLint v9.39.2

[lumirlumir]

Environment

ESLint version: 9.39.2
@eslint/json version: 1.0.1
Node version: 20.19.1
npm version: 10.8.2
Operating System: Stackblitz

Which language are you using?

json

What did you do?

// eslint.config.js

import json from '@eslint/json';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  {
    files: ['**/*.jsonc'],
    plugins: { json },
    language: 'json/jsonc',
    extends: ['json/recommended'],
  },
]);

// tsconfig.json

{
  "include": ["eslint.config.js"],
  "compilerOptions": {
    /* Type Checking */
    "allowUnreachableCode": false,
    "allowUnusedLabels": false,
    "alwaysStrict": true,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noPropertyAccessFromIndexSignature": false, 
    "noUncheckedIndexedAccess": false,
    "noUnusedLocals": false,
    "noUnusedParameters": true,
    "strict": true,
    "strictBindCallApply": true,
    "strictBuiltinIteratorReturn": true,
    "strictFunctionTypes": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "useUnknownInCatchVariables": true,

    /* Modules */
    "module": "NodeNext",
    "moduleResolution": "nodenext",

    /* JavaScript Support */
    "allowJs": true,
    "checkJs": true,

    /* Language and Environment */
    "target": "ESNext"
  }
}

What did you expect to happen?

I expected the types in @eslint/json@1.0.1 to be compatible with ESLint v9.

According to the CI test strategy, README.md, and the comments in markdown (eslint/markdown#593 (comment)), JSON v1 is expected to remain backward compatible with ESLint v9.

json/.github/workflows/ci.yml

Line 30 in 4106331

eslint: [9.15.0, 9.x, 10.x]

What actually happened?

The types in JSON v1 are not compatible with ESLint v9, which prevents using this plugin with ESLint v9 despite it being mentioned as compatible.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/stackblitz-starters-kpy9aaea?file=eslint.config.js

Please run npm run tsc at the reproduction link.

Participation

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

Additional comments

The problem is that the ESLint.plugin type, which is extracted from import type { ESLint } from "eslint";, now has different type signatures:

• ESLint v9.39.2 depends on @eslint/core 0.17.0
• ESLint v10.0.0 depends on @eslint/core 1.1.0
• JSON v0.14.0 depends on @eslint/core 0.17.0
• JSON v1.0.1 depends on @eslint/core 1.1.0

So,

• JSON v1 and ESLint v10 is compatible. ✅
• JSON v1 and ESLint v9 is incompatible ❌

---

Another point is that the HEAD branches of CSS and Markdown are affected by this problem. I discovered it while working on eslint/markdown#593.

To summarize, my question is: do we need to retain type compatibility with ESLint v9 for JSON v1 / CSS v1 / and Markdown v8? If so, I think we need a fundamental solution to ensure these types work seamlessly. Since one of the primary aims of the major releases of language plugins was to maintain backward compatibility, I hope this issue can be addressed.

[fasttime]

During the ESLint v9 cycle, the Plugin type went through several backwards‑incompatible changes. For example, the type in @eslint/json v0.14.0 is not only incompatible with ESLint v10.0.0, but even with ESLint v9.36.0 (StackBlitz repro). It wasn't expected that plugin types remain compatible with older versions of core types previously. Given that, I'm surprised to see this new expectation that plugin types stay backwards‑compatible all the way back to ESLint v9.15.0 now.

[lumirlumir]

I understand we've gone through backwards-incompatible type changes for language plugins in ESLint v9, which inevitably causes type inconsistencies and means type fixes can't be applied uniformly across all v9 versions (for example, v9.15.0 or v9.36.0 mentioned above). So, to clarify, I'm mainly seeking advice on type compatibility with ESLint v9.39.2 (the latest v9).

For example, (while I understand that there can be various mutations), downstream language plugins or configs that want to support ESLint v10 usually just start by adding ESLint v10 to their peerDependencies, such as "eslint": "^9.15.0 || ^10.0.0".

The problem is that if I bump one of the language plugin dependencies to its latest version (JSON v1, CSS v1 (HEAD), and Markdown v8 (HEAD)), users who are still on ESLint v9 start experiencing type inconsistency errors, even if they are already using the latest v9.39.2 release.

I’m not sure how many users are actually facing this issue, but it’s a painful situation for plugin or config authors (including myself) to maintain a package that is compatible with both the latest v9 and v10. Since many personal plugins and configs heavily depend on community packages, the migration from v9 to v10 does not seem to be seamless.

So even if others may not be interested in this issue, I still think some form of mitigation is needed during the transition from v9 to v10. The type incompatibilities in language plugins make this transition particularly difficult.

[nzakas]

This is going to be true for all language plugins, and this is something we were aware of.

Unless there's an easy, clean solution to this, I think it's just something we live with. I don't consider type incompatibilities to be important enough to put a lot of effort into because everything is still functional. At worst, people can just do @ts-ignore.