eslint-plugin-complexijs

ESLint plugin that enforces a per-function cognitive complexity threshold using the complexijs Rust/WASM engine.

The analysis runs on raw source text, so it does not depend on ESLint's AST. TypeScript files work: the WASM engine can parse them directly, though you still need the usual typescript-eslint parser configured for ESLint itself if you want type-aware rules.

Install

npm install --save-dev eslint eslint-plugin-complexijs

Usage (flat config)

// eslint.config.js
const complexijs = require("eslint-plugin-complexijs");

module.exports = [
  {
    plugins: { complexijs },
    rules: {
      "complexijs/complexity": ["error", { max: 15 }],
    },
  },
];

The recommended config wires up the rule at warn with max: 15:

// eslint.config.js
const complexijs = require("eslint-plugin-complexijs");

module.exports = [
  complexijs.configs.recommended,
];

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | max | integer >= 0 | 15 | Maximum allowed cognitive complexity per function. Functions strictly above this value are reported. |

Suppressing a function

Place a // complexijs: ignore comment on the function definition line or on the line directly above it:

// complexijs: ignore
function legacyRouter(req, res) {
  // ...
}

The marker is processed by the WASM engine, not by the ESLint rule, so it works regardless of the max setting.

How complexity is scored

See the complexijs CLI README for the full scoring model. In brief: branching constructs (if, loops, switch, ternary, catch) each add 1 plus a nesting penalty. Boolean sequences add 1 per operator-type transition. Direct recursion adds 1.

Rule reference

complexijs/complexity reports one violation per function that exceeds the threshold. The message includes the function name, its score, and the current max.