ESLint Rule Composer

Common errors

• TypeError: ruleComposer.filterReports is not a function

  cause The `eslint-rule-composer` module was not correctly imported or `require`d, or it returned an unexpected value.
  fix Ensure `const ruleComposer = require('eslint-rule-composer');` is used and the package is correctly installed. Double-check the path if it's a local file.

• TypeError: Cannot read properties of undefined (reading 'getRules')

  cause The `eslint.Linter` object was not correctly instantiated or imported, or the `eslint` package itself is not installed or compatible.
  fix Verify that `const { Linter } = require('eslint');` is correctly used and `const linter = new Linter();` is called before accessing `linter.getRules()`.

• TypeError: Cannot read properties of undefined (reading 'whitelist')

  cause Attempted to access a property (e.g., `whitelist`) from `metadata.options[0]` when `metadata.options` or `metadata.options[0]` was `undefined` or `null`.
  fix Add defensive coding for accessing rule options: `const whitelist = metadata.options?.[0]?.whitelist || [];` to safely handle cases where options might not be provided in the ESLint configuration.

Warnings

• breaking The package is currently in version 0.x.y. According to semantic versioning, minor versions (`0.y.z`) can introduce breaking API changes without a major version increment. Developers should pin exact versions or thoroughly test upgrades.
  Fix: Pin the exact version (e.g., `"eslint-rule-composer": "0.3.0"`) in `package.json` to prevent unexpected breaking changes on update, or implement robust integration tests for your custom rules.
• gotcha Compatibility with `eslint` versions is not explicitly guaranteed. Changes in ESLint's internal `Linter` API or AST structures across major `eslint` versions could potentially break rules composed with `eslint-rule-composer`.
  Fix: Test your custom rules against the specific `eslint` version(s) used in your project. Refer to ESLint's release notes for any breaking changes in its public API or internal structures.
• gotcha When accessing rule options via `metadata.options`, directly indexing `metadata.options[0]` can lead to runtime errors if options are not provided or are malformed in the ESLint configuration. `metadata.options` could be `undefined` or an empty array.
  Fix: Always implement defensive checks when accessing rule options. For example, `const whitelist = metadata.options?.[0]?.whitelist || [];` to safely access properties and provide fallbacks.
• gotcha The package uses CommonJS `require()`. Integrating it into an ESM-only project or an `eslint.config.js` using flat config (which often implies ESM) might require specific setup (e.g., using `createRequire` or dynamic `import()`) or might not be directly compatible.
  Fix: For CommonJS-based projects or older `.eslintrc.js` configurations, `require()` works as shown. For modern ESLint flat configs (`eslint.config.js`) or ESM projects, you might need to wrap `require()` or use a transpilation step if direct `import` is not supported.

Install

• npm install eslint-rule-composer npm
• yarn add eslint-rule-composer yarn
• pnpm add eslint-rule-composer pnpm

Imports

• ruleComposer
  wrong:

  import ruleComposer from 'eslint-rule-composer';

  correct:

  const ruleComposer = require('eslint-rule-composer');

  The package currently primarily supports CommonJS `require()` syntax. There is no official ESM export or guidance for `import` statements in the documentation. Compatibility with older Node.js versions (>=4.0.0) suggests CJS-first design.
• Linter

  const { Linter } = require('eslint');

  When using `eslint-rule-composer`, you typically need to access ESLint's core `Linter` to get references to built-in rules. Ensure `eslint` is installed in your project.

Quickstart

This example demonstrates how to create a custom ESLint rule using `eslint-rule-composer` to modify the behavior of an existing core rule, specifically `no-unused-expressions`, to ignore specific patterns. It also shows the necessary setup for integrating the composed rule into an ESLint configuration.

const ruleComposer = require('eslint-rule-composer');
const { Linter } = require('eslint');

// Instantiate ESLint's Linter to get access to core rules
const linter = new Linter();
const noUnusedExpressionsRule = linter.getRules().get('no-unused-expressions');

// Create a modified version of 'no-unused-expressions' that ignores lines starting with 'expect'
module.exports = ruleComposer.filterReports(
  noUnusedExpressionsRule,
  (problem, metadata) => {
    // Ensure the problem node and its first token exist before accessing properties
    if (!problem.node || !metadata.sourceCode || !metadata.sourceCode.getFirstToken(problem.node)) {
      return true; // Keep the report if parsing issue or no token
    }
    return metadata.sourceCode.getFirstToken(problem.node).value !== 'expect';
  }
);

/* To use this rule:
  1. Save this code as a rule file (e.g., `rules/custom-no-unused-expressions.js`)
  2. In your `.eslintrc.js` or equivalent config, define a plugin:
     module.exports = {
       plugins: {
         'my-plugin': {
           rules: {
             'custom-no-unused-expressions': require('./rules/custom-no-unused-expressions'),
           },
         },
       },
       rules: {
         'my-plugin/custom-no-unused-expressions': 'error',
       },
     };
*/