eslint-rule-composer

What is eslint-rule-composer?

The eslint-rule-composer npm package is a utility for composing and configuring ESLint rules. It provides a set of functions to help developers extend and modify the behavior of existing ESLint rules without having to write a new rule from scratch. This can be particularly useful for creating project-specific versions of general rules or for combining the checks of multiple rules into a single, more efficient rule.

What are eslint-rule-composer's main functionalities?

Joining Rules

This feature allows you to combine the reports of two or more rules into a single rule. This is useful when you want to enforce multiple related coding standards without requiring separate rules for each one.

const { joinReports } = require('eslint-rule-composer');
const ruleA = require('eslint/lib/rules/rule-a');
const ruleB = require('eslint/lib/rules/rule-b');

module.exports = joinReports(ruleA, ruleB);

Filtering Reports

This feature allows you to modify the behavior of an existing rule by filtering out reports based on specific criteria. This can be useful for ignoring certain patterns or node types that the original rule would normally report.

const { filterReports } = require('eslint-rule-composer');
const originalRule = require('eslint/lib/rules/some-rule');

const filteredRule = filterReports(originalRule, (problem, metadata) => {
  return problem.node.type !== 'Identifier';
});

module.exports = filteredRule;

Mapping Reports

This feature allows you to modify the reports generated by an existing rule. This can include changing the message, severity, or any other property of the report. It's useful for customizing the feedback provided by a rule to better fit your project's guidelines.

const { mapReports } = require('eslint-rule-composer');
const originalRule = require('eslint/lib/rules/another-rule');

const mappedRule = mapReports(originalRule, (problem, metadata) => {
  problem.message = 'Custom message: ' + problem.message;
  return problem;
});

module.exports = mappedRule;

Other packages similar to eslint-rule-composer

eslint-plugin-rulesdir

This package allows you to load custom ESLint rules from a directory. It's similar to eslint-rule-composer in that it helps in extending ESLint's functionality, but it focuses more on adding new rules rather than composing or modifying existing ones.

eslint-plugin

While not a single package, the various `eslint-plugin-*` packages extend ESLint by adding new rules, environments, or configurations. They are similar to eslint-rule-composer in their goal of enhancing ESLint, but they typically introduce new rules or presets rather than modifying existing rules.

README

eslint-rule-composer

This is a utility that allows you to build ESLint rules out of other ESLint rules.

Installation

npm install eslint-rule-composer --save

Requires Node 4 or later.

Examples

The following example creates a modified version of the no-unused-expressions rule which does not report lines starting with expect.

const ruleComposer = require('eslint-rule-composer');
const eslint = require('eslint');
const noUnusedExpressionsRule = new eslint.Linter().getRules().get('no-unused-expressions');

module.exports = ruleComposer.filterReports(
  noUnusedExpressionsRule,
  (problem, metadata) => metadata.sourceCode.getFirstToken(problem.node).value !== 'expect'
);

The following example creates a modified version of the semi rule which reports missing semicolons after experimental class properties:

const ruleComposer = require('eslint-rule-composer');
const eslint = require('eslint');
const semiRule = new eslint.Linter().getRules().get('semi');

module.exports = ruleComposer.joinReports([
  semiRule,
  context => ({
    ClassProperty(node) {
      if (context.getSourceCode().getLastToken(node).value !== ';') {
        context.report({ node, message: 'Missing semicolon.' })
      }
    }
  })
]);

You can access rule's options and shared settings from the current ESLint configuration. The following example creates a modified version of the no-unused-expressions rule which accepts a list of exceptions.

/*
  rule configuration:

  {
    "custom-no-unused-expressions": ["error", {
      "whitelist": ["expect", "test"]
    }]
  }
*/

const ruleComposer = require('eslint-rule-composer');
const eslint = require('eslint');
const noUnusedExpressionsRule = new eslint.Linter().getRules().get('no-unused-expressions');

module.exports = ruleComposer.filterReports(
  noUnusedExpressionsRule,
  (problem, metadata) => {
    const firstToken = metadata.sourceCode.getFirstToken(problem.node);
    const whitelist = metadata.options[0].whitelist;
    return whitelist.includes(value) === false
  }
);

API

ruleComposer.filterReports(rule, predicate) and ruleComposer.mapReports(rule, predicate)

Both of these functions accept two arguments: rule (an ESLint rule object) and predicate (a function)

filterReports(rule, predicate) returns a new rule such that whenever the original rule would have reported a problem, the new rule will report a problem only if predicate returns true for that problem. mapReports(rule, predicate) returns a new rule such that whenever the original rule would have reported a problem, the new rule reports the result of calling predicate on the problem.

In both cases, predicate is called with two arguments: problem and metadata.

• problem is a normalized representation of a problem reported by the original rule. This has the following schema:

  {
    node: ASTNode | null,
    message: string,
    messageId: string | null,
    data: Object | null,
    loc: {
      start: { line: number, column: number },
      end: { line: number, column: number } | null
    },
    fix: Function
  }
  

  Note that the messageId and data properties will only be present if the original rule reported a problem using Message IDs, otherwise they will be null.

  When returning a descriptor with mapReports, the messageId property on the returned descriptor will be used to generate the new message. To modify a report message directly for a rule that uses message IDs, ensure that the predicate function returns an object without a messageId property.

• metadata is an object containing information about the source text that was linted. This has the following properties:

• sourceCode: a SourceCode instance corresponding to the linted text.

• settings: linter instance's shared settings

• options: rule's configuration options

• filename: corresponding filename for the linted text.

ruleComposer.joinReports(rules)

Given an array of ESLint rule objects, joinReports returns a new rule that will report all of the problems from any of the rules in the array. The options provided to the new rule will also be provided to all of the rules in the array.

Getting a reference to an ESLint rule

To get a reference to an ESLint core rule, you can use ESLint's public API like this:

// get a reference to the 'semi' rule

const eslint = require('eslint');
const semiRule = new eslint.Linter().getRules().get('semi');

To get a reference to a rule from a plugin, you can do this:

// get a reference to the 'react/boolean-prop-naming' rule
const booleanPropNamingRule = require('eslint-plugin-react').rules['boolean-prop-naming'];

You can also create your own rules (see the rule documentation):

const myCustomRule = {
  create(context) {
    return {
      DebuggerStatement(node) {
        context.report({ node, message: 'Do not use debugger statements.' });
      }
    }
  }
};

License

MIT License

Changelog

v0.3.0 (2018-04-16)

• Update: Add filename property to metadata (#3) (c6982df)