fix(jsx-no-undef): honor /* global */ comments for runtime-injected identifiers

[skoshx]

Summary

Fixes #959 — jsx-no-undef false positives for JSX identifiers provided via runtime-injected scope (e.g., react-live <LiveProvider scope={...}>, Storybook globals, or MDX live code blocks).

Root Cause

The rule flags identifiers that don't have a local binding or import, even when they're legitimately provided at runtime by:

• react-live's <LiveProvider scope={...}> injecting components into playground snippets
• Ambient type declarations in separate .d.ts files (e.g., declare global { const X: any; })
• Other runtime-scope mechanisms (Storybook, MDX, custom render harnesses)

The AST-only rule can't see cross-file type declarations or runtime scope injection, so every unimported identifier is flagged.

Solution

The rule now honors ESLint-style /* global X, Y, Z */ or // global X comments, providing an opt-in escape hatch for files that use injected globals.

Why This Approach?

1. Standard pattern — ESLint's react/jsx-no-undef and many other linters use the same comment syntax
2. Self-documenting — the comment explains why identifiers aren't imported
3. No infrastructure changes — works within the existing AST-only rule architecture
4. Practical workaround — users can fix the false positives immediately by adding one comment to affected files

Example

Before (112 false positives in react-datepicker):

// docs-site/src/examples/ts/calendarContainer.tsx
const CustomCalendarContainer = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());
  
  return (
    <DatePicker selected={selectedDate} onChange={setSelectedDate}>
      <CalendarContainer />  {/* ✖ "CalendarContainer crashes at runtime" */}
    </DatePicker>
  );
};

After (no errors):

/* global DatePicker, CalendarContainer, useState */

const CustomCalendarContainer = () => {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());
  
  return (
    <DatePicker selected={selectedDate} onChange={setSelectedDate}>
      <CalendarContainer />  {/* ✓ recognized as a declared global */}
    </DatePicker>
  );
};

Scope

The fix is narrowly scoped:

• Only affects files that explicitly add /* global */ comments (opt-in)
• No behavioral change for files without the comments
• Doesn't weaken the rule's ability to catch real undefined identifiers

Testing

• ✅ Added 5 new regression tests covering block comments, line comments, multiple globals, and partial coverage
• ✅ All existing tests pass
• ✅ Manually verified fix works on react-datepicker example files
• ✅ CI: All checks now passing (formatting issue resolved)

RDE Parity

Per the triage playbook, rde parity should be run during review to validate no regressions across the OSS corpus. The fix is narrowly scoped (opt-in via comments only) and expected to have zero impact on repos without /* global */ comments.

Changeset

Included a patch-level changeset for oxlint-plugin-react-doctor.

Closes #959

  

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@960

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@960

npm i https://pkg.pr.new/react-doctor@960

commit: 963442c