Registry / testing / eslint-json-compat-utils

eslint-json-compat-utils

library0.2.3jsnpmunverified

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).

testing

npm install eslint-json-compat-utils

github ↗package ↗

INSTALL

IMPORT

SIG · ESLINT-JSON-COMPAT

eslint-json-compat-utils

testingjavascriptv0.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

toCompatRule

✓ import { toCompatRule } from 'eslint-json-compat-utils';

✗ const { toCompatRule } = require('eslint-json-compat-utils');

This is the primary function for converting individual ESLint rules.

toCompatPlugin

✓ import { toCompatPlugin } from 'eslint-json-compat-utils';

✗ import toCompatPlugin from 'eslint-json-compat-utils';

Used for converting an entire ESLint plugin object to be `@eslint/json` compatible.

toCompatCreate

✓ import { toCompatCreate } from 'eslint-json-compat-utils';

✗ import { toCompatCreate as create } from 'eslint-json-compat-utils';

Converts only the `create` function of an ESLint rule, allowing more granular control.

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`.

import { toCompatRule } from 'eslint-json-compat-utils'; // Example of a rule originally designed for jsonc-eslint-parser const originalRule = { meta: { type: 'suggestion', docs: { description: 'Ensure all array elements are strings', category: 'Possible Errors', recommended: false, }, schema: [], }, create(context) { return { // This visitor key is specific to jsonc-eslint-parser's AST JSONArrayExpression(node) { for (const element of node.elements) { if (element.type !== 'Literal' || typeof element.value !== 'string') { context.report({ node: element, message: 'Array element must be a string.', }); } } }, }; }, }; // Convert the rule for compatibility with @eslint/json export default toCompatRule(originalRule); // To run this in an ESLint setup, ensure your .eslintrc.js has: // parser: '@eslint/json', // parserOptions: { ecmaVersion: 2020 }, // rules: { 'your-plugin/your-rule-name': 'error' }

Debug

Known issues

gotchaThis 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.

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`.

affects: >=0.1.0

gotchaThe 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.

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.

affects: >=0.1.0

breakingOlder 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.

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`.

affects: <0.2.3

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'elements') at JSONArrayExpression

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.

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.

ESLint couldn't find the plugin "@your-plugin/json"

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.

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.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

eslintrequiredRequired peer dependency for ESLint rule and plugin development.

jsonc-eslint-parserrequiredRequired peer dependency as this utility converts rules *from* this parser's AST structure.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ota-meshi/eslint-json-compat-utils ↗

packagehttps://www.npmjs.com/package/eslint-json-compat-utils ↗