0
# Bulk Suppressions
1

2
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.
3

4
## Capabilities
5

6
### Bulk Suppressions Patch
7

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

10
```javascript { .api }
11
/**
12
 * Applies the bulk suppressions patch to ESLint
13
 * Must be required before ESLint processes any files
14
 */
15
require("@rushstack/eslint-patch/eslint-bulk-suppressions");
16
```
17

18
**Usage Example:**
19

20
```javascript
21
// .eslintrc.js
22
require("@rushstack/eslint-patch/eslint-bulk-suppressions");
23

24
module.exports = {
25
  rules: {
26
    'no-var': 'error',
27
    '@typescript-eslint/no-explicit-any': 'warning'
28
  },
29
  parserOptions: { tsconfigRootDir: __dirname }
30
};
31
```
32

33
### Suppression File Format
34

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

37
```json { .api }
38
{
39
  "suppressions": [
40
    {
41
      "rule": "no-var",
42
      "file": "./src/legacy-file.ts",
43
      "scopeId": ".ExampleClass.exampleMethod"
44
    },
45
    {
46
      "rule": "@typescript-eslint/no-explicit-any",
47
      "file": "./src/utils.ts", 
48
      "scopeId": ".UtilityFunctions.processData"
49
    }
50
  ]
51
}
52
```
53

54
**Field Definitions:**
55
- `rule`: ESLint rule name to suppress
56
- `file`: File path relative to the .eslintrc.js file
57
- `scopeId`: Identifies the code region where the rule should be suppressed
58

59
### Scope ID Generation
60

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

63
```javascript { .api }
64
// Internal scope ID calculation (not directly callable)
65
interface ScopeId {
66
  calculateScopeId(node: ESTree.Node, sourceCode: SourceCode): string;
67
}
68
```
69

70
**Scope ID Examples:**
71
- `.ClassName.methodName` - Method within a class
72
- `.functionName` - Top-level function
73
- `.ClassName` - Class-level scope
74
- `.` - File-level scope
75

76
### CLI Integration
77

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

80
```javascript { .api }
81
// CLI entry point (requires global installation of @rushstack/eslint-bulk)
82
require("@rushstack/eslint-patch/lib/exports/eslint-bulk");
83
```
84

85
**CLI Commands:**
86

87
```bash
88
# Generate suppressions for all violations
89
eslint-bulk suppress --all ./src
90

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

94
# Remove unnecessary suppressions
95
eslint-bulk prune
96

97
# Display help
98
eslint-bulk --help
99
eslint-bulk suppress --help
100
eslint-bulk prune --help
101
```
102

103
### CLI Command Specifications
104

105
**suppress command:**
106

107
```bash { .api }
108
eslint-bulk suppress [options] <path...>
109

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

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

118
Exit Codes:
119
  0    Success
120
  1    Error (invalid arguments, missing files, or processing failure)
121
```
122

123
**prune command:**
124

125
```bash { .api }
126
eslint-bulk prune [options]
127

128
Options:
129
  -h, -H, --help          Display help message
130

131
Exit Codes:
132
  0    Success  
133
  1    Error (processing failure or incorrect working directory)
134
```
135

136
**Command Requirements:**
137
- Must be run from directory containing `.eslintrc.js` or `.eslintrc.cjs`
138
- ESLint patches must be loaded in the ESLint configuration
139
- At least one file path glob pattern is required for `suppress`
140

141
### Environment Variables
142

143
The patch recognizes these environment variables:
144

145
```javascript { .api }
146
// Environment variable constants
147
interface BulkSuppressionConstants {
148
  _RUSHSTACK_ESLINT_BULK_DETECT: string;           // "_RUSHSTACK_ESLINT_BULK_DETECT" - Detection flag
149
  RUSHSTACK_ESLINT_BULK_PATCH_PATH: string;        // "RUSHSTACK_ESLINT_BULK_PATCH_PATH" - Patch module path
150
  RUSHSTACK_ESLINT_BULK_SUPPRESS: string;          // "RUSHSTACK_ESLINT_BULK_SUPPRESS" - Suppress mode flag
151
  ESLINT_BULK_ENABLE: string;                      // "ESLINT_BULK_ENABLE" - Enable bulk suppressions
152
  ESLINT_BULK_PRUNE: string;                       // "ESLINT_BULK_PRUNE" - Prune mode flag
153
}
154
```
155

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

162
### Patched Linter Behavior
163

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

166
```javascript { .api }
167
// Internal patch behavior (not directly callable)
168
interface LinterPatch {
169
  verify(
170
    textOrSourceCode: string | SourceCode,
171
    config: Config,
172
    filenameOrOptions?: string | VerifyOptions,
173
    saveState?: boolean
174
  ): LintMessage[];
175
}
176
```
177

178
**Verification Process:**
179
1. Runs normal ESLint verification
180
2. Loads applicable `.eslint-bulk-suppressions.json` files
181
3. Filters out suppressed violations based on rule, file, and scope matching
182
4. Returns filtered results
183

184
### File Discovery
185

186
The patch automatically discovers suppression files:
187

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

192
### Typical Workflow
193

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

201
### Error Handling
202

203
The patch handles various error scenarios:
204

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