feat: Consider bulk suppressions via the Node.js API by adf0nt3s · Pull Request #142 · eslint/rfcs

adf0nt3s · 2026-01-17T08:11:05Z

Summary

This RFC continues work on the proposal for integrating bulk suppressions support into the Node.js API via the ESLint and LegacyESLint classes. It specifically focusing on considering existing bulk suppressions when linting files or text through the API, ensuring that suppression files (eslint-suppressions.json) created via CLI commands are automatically respected when using the programmatic API.

The scope is limited to applying existing suppressions during linting and does not include suppression file manipulation features (such as --suppress-all, --suppress-rule, or --prune-suppressions), which remain CLI-exclusive functionalities.

Related Issues

eslint/eslint#19603
#133

…` classes

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

eslint-github-bot · 2026-01-17T08:11:12Z

Hi @adf0nt3s!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
There should be a space following the initial tag and colon, for example 'feat: Message'.
The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

linux-foundation-easycla · 2026-01-17T08:11:15Z

The committers listed above are authorized under a signed CLA.

✅ login: adf0nt3s / name: Blake Sager (3e7a386, 17936f4, 1cf8423, 2009171, 680fd22, 788997c, 88564b2, 9217c6a, ab726a8)
✅ login: mdjermanovic / name: Milos Djermanovic (3e7a386)
✅ login: nzakas / name: Nicholas C. Zakas (8b6e973)
✅ login: sushichan044 / name: Kentaro Suzuki (00ba3e9, 40473fd, 8b6e973, bc82f31, c5b4134, f63e63f, fa25623)

adf0nt3s · 2026-01-17T08:14:28Z

designs/2025-bulk-suppressions-api/README.md

+        - `suppressionsLocation: string | undefined`: Specifies the path to the suppressions file (`eslint-suppressions.json`). This path can be absolute or relative to the `cwd`.
+        - If `suppressionsLocation` is provided, ESLint will attempt to load suppressions from that specific file path.
+        - If `suppressionsLocation` is not provided (or is `undefined`), ESLint will default to looking for `eslint-suppressions.json` in the `cwd`.
+    - `applySuppressions`


@nzakas per your suggestion on the previous version of this RFC, i've introduced a new constructor option

designs/2025-bulk-suppressions-api/README.md

mdjermanovic · 2026-01-21T14:16:10Z

designs/2025-bulk-suppressions-api/README.md

+## Backwards Compatibility Analysis
+
+This change is designed to be backward-compatible.
+
+- New Options are Optional: The new `suppressionsLocation` and `applySuppressions` options are optional. Existing code that does not provide these options will continue to work, with `applySuppressions` defaulting to `true` and `suppressionsLocation` defaulting to looking for `eslint-suppressions.json` in the `cwd`.


When someone is already using the default suppression file eslint-suppressions.json, will applySuppressions defaulting to true change the current behavior for API users by not returning suppressed messages in LintResult#messages anymore? For example, suppressed messages will no longer appear in IDEs? If that's the case, it could be argued that this is a breaking change.

Note: I'm not suggesting to change the default to false, but would like to discuss if this is breaking change and how to handle it if that's the case.

Good question. I can't speak definitively about the current API usage patterns amongst ESLint's consumers, but i'm very curious to hear from those that can.

If we're unsure, maybe it would be safer to have applySuppressions default to false for a start and switch it to true in a future major release?

Seems reasonable, i'll make that change in the RFC

👍 to defaulting to false. I think this is the expected behavior from API consumers.

designs/2025-bulk-suppressions-api/README.md

DMartens · 2026-01-21T14:44:19Z

designs/2025-bulk-suppressions-api/README.md

+2. Service Instantiation and Configuration
+    - Upon instantiation, the `ESLint` and `LegacyESLint` constructors will create an instance of `SuppressionsService`.
+    - 2 new constructor options will be added to both classes.
+        - `suppressionsLocation` (string, optional)


Maybe suppressionsLocation should have a special value (e.g. null) to not look up the suppression file. This allows restoring the old behavior and eliminates the file lookup (as mentioned in the drawbacks).

@DMartens Would it be better instead to just not look up the file if applySuppressions is false? That also preserves the previous behavior and eliminates the performance hit, but may be a bit more intuitive than introducing a third option to suppressionsLocation.

Additionally, if we went the suppressionsLocation: null route, we'd also have to add some logic to throw if suppressionsLocations was null and applySuppressions was true.

Thoughts?

On second thought, I agree with you as the cache option is also split into "enabled" and "file path".
On the other hand, how should we handle suppressionFile: /some/path/to/suppressions.json with applySuppressions set to false (throw an error, print a warning, ...)?

IMHO, print a warning. Doesn't feel important enough to me to throw an error and prevent the linting operation.

We don't typically print warnings for API-level mistakes, only user mistakes (through the CLI). I'd say it's fine to quietly ignore suppressionFile when applySuppressions is false. That's not a situation an end user will run into.

mdjermanovic · 2026-01-21T16:15:35Z

designs/2025-bulk-suppressions-api/README.md

+            - If not provided, defaults to `true`.
+
+3. Applying Suppressions
+    - When `applySuppressions` is `true` (the default), the `lintFiles()` and `lintText()` methods will automatically apply suppressions to results before returning.


It would be good to note, when cache (--cache CLI flag or cache API option) is used, what will be stored in the cache file: original results or results with applied suppressions? Storing original results probably makes more sense.

Agreed, seems like storing the suppressed results is asking for all sorts of dirty-state problems (like if a user changes suppressions without changing the source file). Adding a line now.

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

adf0nt3s · 2026-01-31T03:13:41Z

Any other thoughts here? Thanks! :)

fasttime · 2026-01-31T20:59:39Z

designs/2025-bulk-suppressions-api/README.md

+            }),
+        );
+
+        if (!fs.existsSync(suppressionsFilePath) || eslintOptions.applySuppressions === false) {


When options.filePath is not set, looking up the suppressions file seems unnecessary. In that case, the filePath property of the lint result contains the string "<text>".

I think you are suggesting something like this?

Suggested change

if (!fs.existsSync(suppressionsFilePath) || eslintOptions.applySuppressions === false) {

if (!providedFilePath || eslintOptions.applySuppressions === false) {

Is that correct? Im in favor.

I think the variable to check in lintText is called just filePath. Apart from that, this should work. In fact there's no need to check explicitly if the suppressions file exists because the suppressions service will simply do nothing if it doesn't find it.

Suggested change

if (!fs.existsSync(suppressionsFilePath) || eslintOptions.applySuppressions === false) {

if (!filePath || eslintOptions.applySuppressions === false) {

@fasttime Wait, i'm confused. According to the TSDoc strings, options.filePath is for the source code, not the suppression file.

/** * Executes the current configuration on text. * @param {string} code A string of JavaScript code to lint. * @param {Object} [options] The options. * @param {string} [options.filePath] The path to the file of the source code. * @param {boolean} [options.warnIgnored] When set to true, warn if given filePath is an ignored path. * @returns {Promise<LintResult[]>} The results of linting the string of code given. */ async lintText(code, options = {}) {

What are we trying to handle here? An invalid source code path or a non-existent suppression file?

Ok, i think i understand. We are saying two things here:

If filePath (the path for the source code) is falsey, skip applying suppressions

There is no need to check for the existence of the suppressions file at all, since we'll just no-op if it isn't present, so nothing needs to replace the fs.existsSync(suppressionsFilePath) check

Correct. filePath is the path of the file that contains the provided source code, or undefined if not specified.

Cool, change made 👍

fasttime · 2026-01-31T21:25:17Z

designs/2025-bulk-suppressions-api/README.md

+## Backwards Compatibility Analysis
+
+This change is designed to be backward-compatible.
+
+- New Options are Optional: The new `suppressionsLocation` and `applySuppressions` options are optional. Existing code that does not provide these options will continue to work, with `applySuppressions` defaulting to `true` and `suppressionsLocation` defaulting to looking for `eslint-suppressions.json` in the `cwd`.


If we're unsure, maybe it would be safer to have applySuppressions default to false for a start and switch it to true in a future major release?

nzakas

I really like this approach. It's straightforward both to implement and use. 👍

nzakas · 2026-02-03T20:47:04Z

designs/2025-bulk-suppressions-api/README.md

+2. Service Instantiation and Configuration
+    - Upon instantiation, the `ESLint` and `LegacyESLint` constructors will create an instance of `SuppressionsService`.
+    - 2 new constructor options will be added to both classes.
+        - `suppressionsLocation` (string, optional)


We don't typically print warnings for API-level mistakes, only user mistakes (through the CLI). I'd say it's fine to quietly ignore suppressionFile when applySuppressions is false. That's not a situation an end user will run into.

nzakas · 2026-02-03T20:48:04Z

designs/2025-bulk-suppressions-api/README.md

+    - When `applySuppressions` is `true`, the `lintFiles()` and `lintText()` methods will automatically apply suppressions to results before returning.
+    - Within these methods, *after* the initial linting results are obtained, the `applySuppressions` method of the instantiated `SuppressionsService` will be called.
+    - This method takes the raw linting results and the loaded suppressions (from the resolved file path) and returns the results with suppressions applied.
+    - When caching is enabled, the **original lint results** are stored in the cache. Suppressions are applied after cache retrieval, so that changes to the suppression file take effect without needing to bust the cache.


nzakas · 2026-02-03T20:49:56Z

designs/2025-bulk-suppressions-api/README.md

+
+## Open Questions
+
+- Should functionality equivalent to CLI flags like `--suppress-all` or `--suppress-rule` be supported via separate API methods in the future?


I'd say no. The intent of this feature is to honor existing suppression files, not to provide APIs for all aspects of suppressions.

fasttime

LGTM, thanks.

nzakas · 2026-02-11T20:31:36Z

Given that we have two approvals from the TSC, moving to Final Commenting.

mdjermanovic

LGTM, thanks!

sushichan044 and others added 9 commits April 12, 2025 15:24

init

bc82f31

feat: add support for bulk suppressions in ESLint and `LegacyESLint…

f63e63f

…` classes

add changes to cli

c5b4134

fill PR

8b6e973

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

perf: instantiate SuppressionsService once in constructor

fa25623

docs: explicitly show scope

00ba3e9

we don't need to focus on privateMembers in ESLint class

40473fd

Tweak wording for clarity

88564b2

Add new constructor variable

680fd22

adf0nt3s changed the title ~~Bulk suppressions nodejs api~~ feat: Consider bulk suppressions via the Node.js API Jan 17, 2026

eslint-github-bot bot added the feature label Jan 17, 2026

adf0nt3s commented Jan 17, 2026

View reviewed changes

fasttime added the Initial Commenting This RFC is in the initial feedback stage label Jan 17, 2026

fasttime mentioned this pull request Jan 17, 2026

feat: Consider bulk suppressions when running Lint via the Node.js API #133

Closed

mdjermanovic reviewed Jan 21, 2026

View reviewed changes

designs/2025-bulk-suppressions-api/README.md Outdated Show resolved Hide resolved

mdjermanovic reviewed Jan 21, 2026

View reviewed changes

designs/2025-bulk-suppressions-api/README.md Outdated Show resolved Hide resolved

DMartens reviewed Jan 21, 2026

View reviewed changes

mdjermanovic reviewed Jan 21, 2026

View reviewed changes

adf0nt3s and others added 3 commits January 23, 2026 20:00

Remove mention of LegacyESLint from rfc

17936f4

Update designs/2025-bulk-suppressions-api/README.md

3e7a386

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

Clarify caching behavior when applySuppressions is true

2009171

fasttime reviewed Jan 31, 2026

View reviewed changes

adf0nt3s added 4 commits January 31, 2026 16:32

Default applySuppressions for backwards-compat CYA

ab726a8

Update missed default change and drop fs check for suppressions file

788997c

Fix lingering default: true reference

1cf8423

Remove unnecessary check from lintFiles spec

9217c6a

adf0nt3s mentioned this pull request Feb 3, 2026

Plugin throws an error when seatbelt file is frozen AND error count for some error goes to 0 justjake/eslint-seatbelt#5

Open

nzakas approved these changes Feb 3, 2026

View reviewed changes

fasttime approved these changes Feb 9, 2026

View reviewed changes

nzakas added Final Commenting This RFC is in the final week of commenting and removed Initial Commenting This RFC is in the initial feedback stage labels Feb 11, 2026

eggplants mentioned this pull request Feb 12, 2026

ESLint Bulk suppression via xo xojs/xo#826

Open

mdjermanovic approved these changes Feb 13, 2026

View reviewed changes

viddo mentioned this pull request Feb 16, 2026

feat: support bulk suppressions webpack/eslint-webpack-plugin#292

Open

	if (!fs.existsSync(suppressionsFilePath) \|\| eslintOptions.applySuppressions === false) {
	if (!providedFilePath \|\| eslintOptions.applySuppressions === false) {

	if (!fs.existsSync(suppressionsFilePath) \|\| eslintOptions.applySuppressions === false) {
	if (!filePath \|\| eslintOptions.applySuppressions === false) {


		## Open Questions

		- Should functionality equivalent to CLI flags like `--suppress-all` or `--suppress-rule` be supported via separate API methods in the future?

Uh oh!

Conversation

adf0nt3s commented Jan 17, 2026

Summary

Related Issues

Uh oh!

eslint-github-bot bot commented Jan 17, 2026

Uh oh!

linux-foundation-easycla bot commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adf0nt3s Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adf0nt3s commented Jan 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nzakas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fasttime left a comment

Choose a reason for hiding this comment

Uh oh!

nzakas commented Feb 11, 2026

Uh oh!

mdjermanovic left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

linux-foundation-easycla bot commented Jan 17, 2026 •

edited

Loading

adf0nt3s Jan 24, 2026 •

edited

Loading