How to Configure Ignore Rules Per File or Per Rule Using Overrides in React-Doctor

React-Doctor supports granular diagnostic suppression through the ignore.overrides configuration field, allowing you to target specific file glob patterns and optionally limit suppression to individual rule identifiers such as react/no-raw-text or oxlint/no-unused-vars.

React-Doctor, an open-source diagnostic scanner from the millionco/react-doctor repository, provides fine-grained control over linting rule enforcement beyond global settings. The ignore.overrides configuration mechanism, defined in src/types.ts and implemented in src/utils/apply-ignore-overrides.ts, enables developers to configure ignore rules per file or per specific rule using overrides that operate additively alongside top-level ignore.rules and ignore.files arrays.

Understanding the ignore.overrides Configuration Schema

The ignore.overrides field accepts an array of override objects. According to the ReactDoctorIgnoreOverride interface defined in src/types.ts, each entry must contain a files property and may contain a rules property.

Required Files Array

The files property is a required array of glob patterns (e.g., ["src/legacy/**/*.tsx"]). The compileIgnoreOverrides utility in src/utils/apply-ignore-overrides.ts compiles these patterns into RegExp objects for efficient matching during the scan.

Optional Rules Array

The rules property is an optional array of full rule identifiers (e.g., ["react/no-inline-styles", "oxlint/no-debugger"]). When omitted, all diagnostics matching the file patterns are ignored. When provided, only the specified rules are silenced for those files.

How Override Matching Works in the Source Code

The implementation relies on two core functions exported from src/utils/apply-ignore-overrides.ts. The compileIgnoreOverrides function validates entries, ensures files is an array, and stores both the compiled regex patterns and rule identifiers in a Set for fast lookup. During the diagnostic filtering phase, isDiagnosticIgnoredByOverrides tests each diagnostic against these compiled overrides.

The matching logic is additive: if multiple override entries match a file, their effects are merged. A diagnostic is ignored if any matching override applies. This works in addition to top-level ignore settings, not as a replacement.

Practical Configuration Examples

Ignore a Single Rule for a Specific File

Use the rules array to suppress only one diagnostic while preserving others:

{
  "ignore": {
    "overrides": [
      {
        "files": ["src/components/OldButton.tsx"],
        "rules": ["react/no-raw-text"]
      }
    ]
  }
}

This silences only the react/no-raw-text rule in src/components/OldButton.tsx.

Ignore All Diagnostics for Generated Files

Omit the rules array to suppress every diagnostic for matched files:

{
  "ignore": {
    "overrides": [
      {
        "files": ["dist/**/*.js"]
      }
    ]
  }
}

Every diagnostic from any file under dist/ is dropped, regardless of which rule triggered it.

Combine Multiple Overrides for Legacy Code

Layer entries to achieve comprehensive suppression:

{
  "ignore": {
    "overrides": [
      {
        "files": ["src/legacy/**/*.tsx"],
        "rules": ["react/no-inline-styles"]
      },
      {
        "files": ["src/legacy/**/*.tsx"]
      }
    ]
  }
}

The first entry silences only react/no-inline-styles, while the second silences all remaining rules for the same files. The combined effect is a complete ignore of all diagnostics in src/legacy/.

Target Test Files with Glob Patterns

Apply rules selectively to specific file types:

{
  "ignore": {
    "overrides": [
      {
        "files": ["**/*.test.ts", "**/*.test.tsx"],
        "rules": ["oxlint/no-debugger"]
      }
    ]
  }
}

This ignores oxlint/no-debugger violations in test files while preserving other rule checks.

Invalid Entry Handling

The validator in src/utils/apply-ignore-overrides.ts emits warnings for malformed entries. For example, providing a string instead of an array for files generates: ignore.overrides[0].files must be an array of strings; ignoring this entry.

Integration with the Diagnostic Pipeline

The src/utils/filter-diagnostics.ts module integrates overrides into the diagnostic filtering pipeline. It invokes compileIgnoreOverrides during initialization to process the configuration, then calls isDiagnosticIgnoredByOverrides for each diagnostic to determine if it should be suppressed before final reporting.

Summary

• The ignore.overrides array enables per-file and per-rule suppression using glob patterns defined in your React-Doctor configuration.
• Each override requires a files array and optionally accepts a rules array; omitting rules ignores all diagnostics for matched files.
• The compileIgnoreOverrides and isDiagnosticIgnoredByOverrides functions in src/utils/apply-ignore-overrides.ts handle validation, regex compilation, and runtime matching.
• Override behavior is additive: multiple matching entries are merged, and any match results in suppression.
• Invalid configurations trigger warnings rather than hard failures, ensuring the scan continues with valid entries.

Frequently Asked Questions

Can I use negative glob patterns to exclude files from an override?

React-Doctor's compileIgnoreOverrides function compiles glob patterns using standard regular expressions. While specific negation syntax depends on the implementation details in src/utils/apply-ignore-overrides.ts, you should structure your files array to include only the paths you want to target. For complex exclusions, define separate overrides with precise positive globs rather than relying on negation.

Do overrides replace the top-level ignore configuration?

No. The ignore.overrides field works additively with the top-level ignore.rules and ignore.files arrays. A diagnostic is suppressed if it matches either the global ignore settings or any entry in the overrides array. The runtime check in isDiagnosticIgnoredByOverrides operates independently of the global filter logic in src/utils/filter-diagnostics.ts.

What happens if I specify an invalid rule identifier in the rules array?

The rules array stores identifiers in a Set for efficient lookup. If you specify a rule that does not exist in the current React-Doctor rule registry, the override will simply never match any diagnostics for that non-existent rule. The validator focuses on ensuring files is an array of strings and that the override object structure is valid, rather than validating rule existence against the plugin registry.

How are multiple override entries with overlapping file patterns handled?

When file patterns overlap, the effects are merged. The isDiagnosticIgnoredByOverrides function checks a diagnostic against all compiled overrides, and if any match applies, the diagnostic is ignored. This means you can layer specific rule exemptions with broad file ignores to achieve precise control over your diagnostic output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}