How to Diagnose Failed Suppressions Using the react-doctor --explain Flag

The --explain flag (alias --why) runs a targeted, silent diagnostic scan that reveals exactly why a specific rule fired and why a suppression comment failed to silence it at a given line.

The react-doctor CLI includes a specialized diagnostic mode designed to debug false positives and misconfigured inline suppressions. When a // react-doctor-disable-next-line comment fails to suppress a rule, the --explain flag provides a focused, line-level analysis of the mismatch between the diagnostic and the suppression directive.

How the --explain Flag Works

The diagnostic flow implemented in packages/react-doctor/src/cli.ts follows a strict pipeline to isolate and explain specific rule violations.

Target Selection and Project Resolution

The runExplain() function, located at lines 274–382 of cli.ts, requires a <file>:<line> argument (e.g., src/App.tsx:42). It parses this input and calls resolveExplainTargetDirectory() to identify the owning project context. If the --project flag is provided, it restricts the search to that specific project; otherwise, it resolves the project from the file path.

Silent Diagnostic Scanning

Once the target is resolved, runExplain() triggers a full project scan with silent mode enabled. According to lines 78–84 of cli.ts, the scan executes with silent: true and offline: true, ensuring that only raw diagnostic objects are collected without UI formatting, progress bars, or network-dependent features.

Line-Level Filtering and Suppression Analysis

The scan results are filtered to diagnostics matching the exact filePath and line provided by the user (lines 86–90 of cli.ts). For each matching diagnostic, the system checks for a suppressionHint property. This hint is injected by filterInlineSuppressions() in src/utils/filter-diagnostics.ts (lines 61–66) when a rule is not suppressed but a nearby disable comment exists with a mismatching rule name or malformed syntax.

Understanding Suppression Hints

The suppression hint mechanism diagnoses "near misses" between suppression comments and actual diagnostics. When filterInlineSuppressions() detects a // react-doctor-disable-next-line comment that is either missing, malformed, or targeting a different rule, it generates a detailed explanation.

For example, if a disable comment on line 41 targets no-inline-styles but the diagnostic on line 42 is for react-hooks-exhaustive-deps, the hint explains: "disable comment found on line 41 applies to rule 'no-inline-styles', but the diagnostic is for 'react-hooks-exhaustive-deps'." This precision eliminates guesswork when suppression comments fail silently.

Usage Examples

Invoke the diagnostic mode using either the --explain or --why alias followed by a file path and line number separated by a colon.

# Diagnose a specific line

npx react-doctor --explain src/App.tsx:42

# Using the alias

npx react-doctor --why src/App.tsx:42

When a suppression hint exists, the output identifies the specific mismatch:

✗ react-hooks/exhaustive-deps (⚠) — React hook has missing dependency
  Suppression diagnosis: disable comment on line 41 applies to rule 'no-inline-styles', not 'exhaustive-deps'

If no suppression comment is detected, the output prompts for remediation:

⚠ react-hooks/exhaustive-deps (⚠) — React hook has missing dependency
  No nearby react-doctor-disable-next-line comment was detected — add one immediately above this line to suppress.

Constraints and Isolation Mode

The --explain flag operates in strict isolation. As enforced by lines 66–73 of cli.ts, it cannot be combined with other output modes such as --json, --score, --annotations, or --staged. This constraint ensures the explanation remains the sole output, preventing conflicting formatting or data structures from obscuring the diagnostic details.

Summary

• The --explain (or --why) flag performs a silent, offline scan targeting a specific file:line coordinate.
• It filters diagnostics to the exact location and checks for suppressionHint properties added by filterInlineSuppressions().
• Suppression hints reveal why a // react-doctor-disable-next-line comment failed, detailing rule mismatches or malformed syntax.
• The mode cannot be combined with --json, --score, or other output flags, ensuring focused, readable diagnostic output.
• If no suppression comment is found, the tool explicitly advises adding one above the flagged line.

Frequently Asked Questions

What is the difference between --explain and --why?

There is no functional difference; --why is simply an alias for --explain. Both invoke the runExplain() function in cli.ts and accept a <file>:<line> argument to diagnose specific rule violations and failed suppressions.

Why does --explain require a file:line argument?

The flag requires precise coordinates to filter the diagnostic stream effectively. According to the implementation in cli.ts lines 86–90, the tool matches diagnostics by exact filePath and line number, allowing it to isolate the specific suppression logic and generate targeted hints without processing unrelated violations.

Can I use --explain with --json output?

No. The runExplain() function explicitly forbids combining --explain with --json, --score, --annotations, or --staged flags (lines 66–73 of cli.ts). This design ensures that explanatory text and suppression diagnoses remain human-readable and are not corrupted by structured data formatting.

What does it mean when no suppression hint is shown?

If the output displays a diagnostic but states "No nearby react-doctor-disable-next-line comment was detected", it indicates that filterInlineSuppressions() found no suppression comments in the vicinity of the flagged line. The tool is prompting you to add a properly formatted // react-doctor-disable-next-line <rule-name> comment immediately above the diagnostic line to suppress the warning.

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