Bulk Suppressions

Bulk Suppressions patch enables machine-generated lint suppressions to be stored in a separate .eslint-bulk-suppressions.json file, avoiding the need to clutter source code with thousands of // eslint-ignore-next-line directives when rolling out new lint rules.

Capabilities

Bulk Suppressions Patch

Applies runtime patches to ESLint's Linter to process suppressions from .eslint-bulk-suppressions.json files.

/**
 * Applies the bulk suppressions patch to ESLint
 * Must be required before ESLint processes any files
 */
require("@rushstack/eslint-patch/eslint-bulk-suppressions");

Usage Example:

// .eslintrc.js
require("@rushstack/eslint-patch/eslint-bulk-suppressions");

module.exports = {
  rules: {
    'no-var': 'error',
    '@typescript-eslint/no-explicit-any': 'warning'
  },
  parserOptions: { tsconfigRootDir: __dirname }
};

Suppression File Format

Suppressions are stored in .eslint-bulk-suppressions.json files with the following structure:

{
  "suppressions": [
    {
      "rule": "no-var",
      "file": "./src/legacy-file.ts",
      "scopeId": ".ExampleClass.exampleMethod"
    },
    {
      "rule": "@typescript-eslint/no-explicit-any",
      "file": "./src/utils.ts", 
      "scopeId": ".UtilityFunctions.processData"
    }
  ]
}

Field Definitions:

• rule: ESLint rule name to suppress
• file: File path relative to the .eslintrc.js file
• scopeId: Identifies the code region where the rule should be suppressed

Scope ID Generation

Scope IDs are automatically generated strings that identify code regions while remaining stable across edits:

// Internal scope ID calculation (not directly callable)
interface ScopeId {
  calculateScopeId(node: ESTree.Node, sourceCode: SourceCode): string;
}

Scope ID Examples:

• .ClassName.methodName - Method within a class
• .functionName - Top-level function
• .ClassName - Class-level scope
• . - File-level scope

CLI Integration

The patch works with the @rushstack/eslint-bulk CLI package for managing suppressions:

// CLI entry point (requires global installation of @rushstack/eslint-bulk)
require("@rushstack/eslint-patch/lib/exports/eslint-bulk");

CLI Commands:

# Generate suppressions for all violations
eslint-bulk suppress --all ./src

# Generate suppressions for specific rules
eslint-bulk suppress --rule no-var --rule @typescript-eslint/no-explicit-any ./src

# Remove unnecessary suppressions
eslint-bulk prune

# Display help
eslint-bulk --help
eslint-bulk suppress --help
eslint-bulk prune --help

CLI Command Specifications

suppress command:

eslint-bulk suppress [options] <path...>

Options:
  -R, --rule <rulename>    ESLint rule name to suppress (can be repeated)
  -A, --all               Suppress all rules in specified paths
  -h, -H, --help          Display help message

Arguments:
  <path...>               Glob patterns for files to suppress (required)

Exit Codes:
  0    Success
  1    Error (invalid arguments, missing files, or processing failure)

prune command:

eslint-bulk prune [options]

Options:
  -h, -H, --help          Display help message

Exit Codes:
  0    Success  
  1    Error (processing failure or incorrect working directory)

Command Requirements:

• Must be run from directory containing .eslintrc.js or .eslintrc.cjs
• ESLint patches must be loaded in the ESLint configuration
• At least one file path glob pattern is required for suppress

Environment Variables

The patch recognizes these environment variables:

// Environment variable constants
interface BulkSuppressionConstants {
  _RUSHSTACK_ESLINT_BULK_DETECT: string;           // "_RUSHSTACK_ESLINT_BULK_DETECT" - Detection flag
  RUSHSTACK_ESLINT_BULK_PATCH_PATH: string;        // "RUSHSTACK_ESLINT_BULK_PATCH_PATH" - Patch module path
  RUSHSTACK_ESLINT_BULK_SUPPRESS: string;          // "RUSHSTACK_ESLINT_BULK_SUPPRESS" - Suppress mode flag
  ESLINT_BULK_ENABLE: string;                      // "ESLINT_BULK_ENABLE" - Enable bulk suppressions
  ESLINT_BULK_PRUNE: string;                       // "ESLINT_BULK_PRUNE" - Prune mode flag
}

• _RUSHSTACK_ESLINT_BULK_DETECT=true: Enables CLI detection mode
• RUSHSTACK_ESLINT_BULK_PATCH_PATH: Internal path to patch module
• RUSHSTACK_ESLINT_BULK_SUPPRESS: Rules to suppress (comma-separated or '*' for all)
• ESLINT_BULK_ENABLE: Enables bulk suppressions processing
• ESLINT_BULK_PRUNE: Enables prune mode for removing obsolete suppressions

Patched Linter Behavior

The patch extends ESLint's Linter.prototype.verify method:

// Internal patch behavior (not directly callable)
interface LinterPatch {
  verify(
    textOrSourceCode: string | SourceCode,
    config: Config,
    filenameOrOptions?: string | VerifyOptions,
    saveState?: boolean
  ): LintMessage[];
}

Verification Process:

1. Runs normal ESLint verification
2. Loads applicable .eslint-bulk-suppressions.json files
3. Filters out suppressed violations based on rule, file, and scope matching
4. Returns filtered results

File Discovery

The patch automatically discovers suppression files:

• Searches up the directory tree from the linted file
• Loads all .eslint-bulk-suppressions.json files found
• Applies suppressions that match the current file and scope

Typical Workflow

1. Clean State: Start with ESLint reporting no violations
2. Enable New Rules: Update configuration to enable stricter rules
3. Generate Suppressions: Run eslint-bulk suppress --all ./src
4. Commit Changes: Commit both config and suppression file changes
5. Gradual Improvement: Engineers improve code over time
6. Prune Suppressions: Run eslint-bulk prune to remove obsolete suppressions

Error Handling

The patch handles various error scenarios:

• Missing ESLint Installation: Exits with error message if ESLint cannot be located
• Unsupported ESLint Version: Throws error for versions outside 6.x-9.x range
• Malformed Suppression Files: Continues processing, logs warnings for invalid entries
• File Path Resolution: Handles relative path resolution errors gracefully