{"id":10825,"library":"eslint-json-compat-utils","title":"ESLint JSON Compatibility Utilities","description":"eslint-json-compat-utils is a specialized utility designed to bridge the gap between ESLint rules written for `jsonc-eslint-parser` and those compatible with `@eslint/json`. It provides conversion functions that adapt rule objects, plugin objects, and `create` functions, enabling developers to reuse existing logic across different JSON AST parsers in ESLint. The current stable version is 0.2.3, with releases occurring periodically to address bugs and add minor features, as seen in recent patch updates. Its key differentiator is its focused purpose on AST transformation for JSON linting rules, specifically to ensure compatibility when transitioning between or supporting both `jsonc-eslint-parser` (which supports JSONC, JSON5) and `@eslint/json` (standard JSON).","status":"active","version":"0.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/ota-meshi/eslint-json-compat-utils","tags":["javascript","eslint","typescript"],"install":[{"cmd":"npm install eslint-json-compat-utils","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-json-compat-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-json-compat-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for ESLint rule and plugin development.","package":"eslint","optional":false},{"reason":"Required peer dependency as this utility converts rules *from* this parser's AST structure.","package":"jsonc-eslint-parser","optional":false}],"imports":[{"note":"This is the primary function for converting individual ESLint rules.","wrong":"const { toCompatRule } = require('eslint-json-compat-utils');","symbol":"toCompatRule","correct":"import { toCompatRule } from 'eslint-json-compat-utils';"},{"note":"Used for converting an entire ESLint plugin object to be `@eslint/json` compatible.","wrong":"import toCompatPlugin from 'eslint-json-compat-utils';","symbol":"toCompatPlugin","correct":"import { toCompatPlugin } from 'eslint-json-compat-utils';"},{"note":"Converts only the `create` function of an ESLint rule, allowing more granular control.","wrong":"import { toCompatCreate as create } from 'eslint-json-compat-utils';","symbol":"toCompatCreate","correct":"import { toCompatCreate } from 'eslint-json-compat-utils';"}],"quickstart":{"code":"import { toCompatRule } from 'eslint-json-compat-utils';\n\n// Example of a rule originally designed for jsonc-eslint-parser\nconst originalRule = {\n  meta: {\n    type: 'suggestion',\n    docs: {\n      description: 'Ensure all array elements are strings',\n      category: 'Possible Errors',\n      recommended: false,\n    },\n    schema: [],\n  },\n  create(context) {\n    return {\n      // This visitor key is specific to jsonc-eslint-parser's AST\n      JSONArrayExpression(node) {\n        for (const element of node.elements) {\n          if (element.type !== 'Literal' || typeof element.value !== 'string') {\n            context.report({\n              node: element,\n              message: 'Array element must be a string.',\n            });\n          }\n        }\n      },\n    };\n  },\n};\n\n// Convert the rule for compatibility with @eslint/json\nexport default toCompatRule(originalRule);\n\n// To run this in an ESLint setup, ensure your .eslintrc.js has:\n// parser: '@eslint/json',\n// parserOptions: { ecmaVersion: 2020 },\n// rules: { 'your-plugin/your-rule-name': 'error' }","lang":"typescript","description":"Demonstrates how to use `toCompatRule` to convert an existing ESLint rule, originally targeting `jsonc-eslint-parser` AST nodes, into a version compatible with `@eslint/json`."},"warnings":[{"fix":"Only use this package when migrating or supporting rules that were originally written for `jsonc-eslint-parser` and need to function with `@eslint/json`.","message":"This utility is specifically designed for converting rules *from* `jsonc-eslint-parser` to `@eslint/json`. It is not a general-purpose AST transformer or a solution for converting rules between arbitrary ESLint parsers. Misapplication to other parser contexts will not work as expected.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly test converted rules with `@eslint/json` to ensure all original logic is preserved. For very complex rules, manual review of the converted rule's behavior and potential post-conversion tweaks may be necessary.","message":"The package currently assumes that the target rule's AST node visitors (`JSONArrayExpression`, `JSONObjectExpression`, etc.) are based on `jsonc-eslint-parser`'s AST structure. While it performs a conversion, complex or highly parser-specific AST queries might require manual adjustments after conversion if the transformation is not fully comprehensive for edge cases.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure you are using `eslint-json-compat-utils` version `0.2.3` or newer to benefit from recent fixes for node conversion issues, especially for minus number nodes and JSON5 unofficial static nodes. Update your `jsonc-eslint-parser` peer dependency to `^2.4.0 || ^3.0.0`.","message":"Older versions of `eslint-json-compat-utils` might not correctly convert certain JSON AST nodes, particularly related to negative numbers or unofficial JSON5 static nodes. This could lead to incorrect linting results or crashes.","severity":"breaking","affected_versions":"<0.2.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `toCompatRule` or `toCompatCreate` was used correctly on the rule/create function. Verify the `jsonc-eslint-parser` version is compatible with `eslint-json-compat-utils` (current minimum `^2.4.0 || ^3.0.0`). For complex rules, manually inspect the converted AST structure or simplify the original rule's AST traversal.","cause":"The rule is trying to access properties of an AST node that do not exist in the `@eslint/json` AST, indicating incomplete or incorrect conversion by `eslint-json-compat-utils` or a mismatch in AST expectations.","error":"TypeError: Cannot read properties of undefined (reading 'elements') at JSONArrayExpression"},{"fix":"Ensure the converted plugin is correctly installed (`npm install your-plugin`) and registered in your `.eslintrc.*` file under the `plugins` array, and that `parser: '@eslint/json'` is set.","cause":"This error is typically an ESLint configuration issue, not directly related to `eslint-json-compat-utils`, but can arise when attempting to use a converted plugin without properly installing or configuring it in your ESLint setup.","error":"ESLint couldn't find the plugin \"@your-plugin/json\""}],"ecosystem":"npm"}