feat(react-doctor): multi-line JSX & stacked suppressions, per-file rule overrides, near-miss hints

[aidenybai]

Closes #158, #159, #160, #161.

What this PR does

Refactors inline-suppression matching into small composable utilities and extends its semantics to address the four open issues filed against react-doctor 0.0.47. Architecture-wise, the previous monolithic filter-diagnostics.ts is now an orchestrator over single-purpose utilities — one per file, in line with the project's "one utility per file" convention.

#158 — multi-line JSX disable-next-line

A react-doctor-disable-next-line immediately above a multi-line JSX opening tag now suppresses diagnostics on attribute lines inside that opener, matching the ESLint convention users expect:

{/* react-doctor-disable-next-line react-doctor/no-array-index-as-key */}
<li
  key={`item-${index}`}   // diagnostic line — now correctly suppressed
  role="button"
>
  {item.label}
</li>

Coverage extends through the closing > of the opening tag, not into children — so the suppression doesn't silently mask unrelated rules in element bodies. The detection is brace- and string-aware (> inside {...} expressions or string attributes is correctly ignored), skips => and >= operators, and is bounded by JSX_OPENER_SCAN_MAX_LINES to keep worst-case work bounded.

#159 — stacked single-rule comments

Walking the chain of consecutive disable-next-line comments above the diagnostic now applies all of them, not just the immediately-adjacent one:

// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers
// react-doctor-disable-next-line react-doctor/no-derived-useState
const [localSearch, setLocalSearch] = useState(searchQuery); // both rules suppressed

The README's "Inline suppressions" section is also reworked to surface the comma-separated multi-rule form (already supported but easy to miss in docs):

// react-doctor-disable-next-line react-doctor/no-derived-state-effect, react-doctor/no-fetch-in-effect

#160 — per-file rule overrides

New ignore.overrides config field scopes specific rules to specific globs without forcing whole-file ignores:

{
  "ignore": {
    "overrides": [
      {
        "files": ["components/diff/**"],
        "rules": ["react-doctor/no-array-index-as-key"]
      },
      {
        "files": ["components/search/HighlightedSnippet.tsx"],
        "rules": ["react/no-danger"]
      }
    ]
  }
}

A diagnostic is dropped when its file matches an entry's globs and its plugin/rule id is listed. Omit rules (or pass []) to suppress every rule for the matched files.

#161 — near-miss hints + --explain <file:line>

When a diagnostic survives the suppression filter but a nearby disable-next-line looks intentional, an explanatory hint is attached to the diagnostic. Two near-miss shapes get a hint:

• wrong-rule: an in-chain comment lists rules but not this one. Suggests the documented comma form.
• gap-code: the rule matches but a code line broke the chain. Suggests moving / extracting.

The hint is exposed via:

• --verbose output: appended under each affected file:line.
• --json output: as the new optional Diagnostic.suppressionHint field.
• A new --explain <file:line> flag (with --why as a hidden alias) for single-site investigation, mirroring the rustc --explain <error-code> shape:

$ npx react-doctor --explain components/projects/Snapshot.tsx:254
react-doctor/no-array-index-as-key — Use a stable id, not the array index, for `key`
  Use the item's stable id (e.g. `item.id`) as the key, or extract a wrapper component.

  Suppression diagnosis: A react-doctor-disable-next-line for react-doctor/no-array-index-as-key sits at line 252, but 1 line of code separate it from the diagnostic on line 254. Move the comment immediately above line 254, or extract the surrounding code into a helper so the suppression is adjacent.

--explain is mode-exclusive with --json, --score, --annotations, and --staged (consistent with existing CLI mutual-exclusion checks). Passing both --explain and --why is rejected with a clear message.

File layout

New utilities (one per file):

• find-jsx-opener-span.ts — heuristic, brace/string-aware finder for the line that closes a JSX opener.
• find-enclosing-jsx-opener.ts — uses the span finder to locate any multi-line opener that contains a diagnostic.
• find-stacked-disable-comments.ts — single-pass walk that returns all disable-next-line comments above an anchor, tagged with isInChain.
• is-rule-listed-in-comment.ts — atomic helper: does this comment's rule list cover this rule?
• is-rule-suppressed-at.ts — orchestrates same-line + chain-above + opener-above into the boolean answer.
• classify-suppression-near-miss.ts — builds the diagnostic hint string when a near-miss is detected.
• apply-ignore-overrides.ts — compiles ignore.overrides once and matches each diagnostic against it.
• to-relative-path.ts — extracted from is-ignored-file.ts so the override matcher and ignore-file matcher share the same path normalization.
• parse-file-line-argument.ts — last-colon-wins parsing so Windows drive letters round-trip.

Type changes:

• Diagnostic.suppressionHint?: string (additive, backward-compatible).
• ReactDoctorIgnoreOverride { files: string[]; rules?: string[] } and ReactDoctorIgnoreConfig.overrides?: ReactDoctorIgnoreOverride[].

Constants:

• JSX_OPENER_SCAN_MAX_LINES = 32 and SUPPRESSION_NEAR_MISS_MAX_LINES = 10 in constants.ts.

Test coverage

30 new tests across 4 files (510 total, all passing):

• find-jsx-opener-span.test.ts (8): single-line, multi-line, brace/string awareness, => / >= skipping, lookahead cap, closing-tag rejection.
• inline-suppressions.test.ts (8 added): 5 multi-line JSX cases (// react-doctor-disable-next-line doesn't suppress when the rule reports an attribute on a later line of a multi-line JSX element #158), 3 stacked-comment cases (Stacked // react-doctor-disable-next-line comments shadow each other; comma-syntax works but is undocumented #159), preserves the existing JSX-block-comment form (Support block comments with react-doctor-disable-next-line #144).
• classify-suppression-near-miss.test.ts (5): wrong-rule, gap-code, JSX-anchor near-miss, active-suppression silence.
• filter-diagnostics.test.ts (3 added): scoped per-rule override, no-rule-list override, multi-entry override.
• parse-file-line-argument.test.ts (6): standard parse, Windows drive letters, validation errors.

Backward compatibility

• All four existing inline-suppression behaviors continue to work (verified via the original inline-suppressions.test.ts + respect-lint-ignores.test.ts suites). Boundary tests (suppression doesn't leak to N+2, doesn't apply to other rules, etc.) all still pass.
• ignore.rules and ignore.files semantics unchanged.
• Diagnostic.suppressionHint and ignore.overrides are both additive optional fields — existing configs continue to work without changes.

Risk notes

• The JSX opener-span finder is a heuristic, not a parser. Two known limitations:
  • TypeScript generic syntax (<List<Item>) used as a JSX component is rare enough I haven't worked around it; the JSX-block-comment workaround {/* … */} immediately above the offending attribute still works in that case.
  • Coverage extends through attribute lines but not into children. This is intentional — extending into children would silently mask unrelated diagnostics on different rules in nested elements.
• The suppression engine is conservative: when in doubt about whether a suppression applies, it falls back to "doesn't apply" (so users see the diagnostic + the near-miss hint, rather than silently swallowing it).

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-doctor-website	Ready	Preview, Comment	May 8, 2026 5:53am