feat: add source-patched native Oxlint path

.changeset/functional-state-rust.md

@@ -0,0 +1,7 @@
+---
+"oxlint-plugin-react-doctor": patch
+"eslint-plugin-react-doctor": patch
+"react-doctor": patch
+---
+
+Run `rerender-functional-setstate` natively in the patched Oxlint binding and avoid reporting a synchronous state update when the only other call to the same setter does not read that state.

.changeset/tidy-oxen-compile.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": patch
+---
+
+Add an opt-in, source-patched Oxlint binding path with native rule parity, cache isolation, provenance metadata, and reproducible cross-platform build tooling.

.gitattributes

@@ -1,2 +1,3 @@
 packages/fuzz/corpus/react-bench-0.9.7-audit/** -text whitespace=-trailing-space
 packages/fuzz/corpus/dummy-threejs-v14-audit/** -text whitespace=-trailing-space
+native/oxlint/*.patch -text whitespace=-trailing-space

.github/workflows/native-oxlint.yml

@@ -0,0 +1,87 @@
+name: Native Oxlint
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "native/oxlint/**"
+      - "scripts/native/**"
+      - "package.json"
+      - "packages/core/src/constants.ts"
+      - "packages/core/src/run-oxlint.ts"
+      - "packages/core/src/runners/oxlint/**"
+      - ".github/workflows/native-oxlint.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "native/oxlint/**"
+      - "scripts/native/**"
+      - "package.json"
+      - "packages/core/src/constants.ts"
+      - "packages/core/src/run-oxlint.ts"
+      - "packages/core/src/runners/oxlint/**"
+      - ".github/workflows/native-oxlint.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  verify-patch:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - run: node scripts/native/build-oxlint-binding.mjs --check-only
+
+  build:
+    needs: verify-patch
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        runner:
+          - ubuntu-24.04
+          - ubuntu-24.04-arm
+          - macos-15-intel
+          - macos-15
+          - windows-2025
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@1.97.1
+        with:
+          components: rustfmt
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: native-oxlint-${{ matrix.runner }}
+      - run: node scripts/native/build-oxlint-binding.mjs --output dist/native-oxlint
+      - uses: actions/upload-artifact@v7
+        with:
+          name: native-oxlint-${{ matrix.runner }}
+          path: dist/native-oxlint/*
+          if-no-files-found: error
+
+  parity:
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22.18.0"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --prefer-offline
+      - run: pnpm --filter oxlint-plugin-react-doctor build
+      - uses: actions/download-artifact@v8
+        with:
+          name: native-oxlint-ubuntu-24.04
+          path: dist/native-oxlint
+      - run: node scripts/native/verify-oxlint-parity.mjs --directory dist/native-oxlint

native/oxlint/README.md

@@ -0,0 +1,24 @@
+# Source-patched Oxlint
+
+This directory contains a patch against one exact Oxc commit. It adds a `react-doctor-native` plugin while leaving the stock Oxlint JavaScript launcher and all unported React Doctor rules unchanged.
+
+The native rule cohort is listed in `upstream.json`, with one Rust source file per rule in `rules/`. React Doctor enables those rules only when `REACT_DOCTOR_NATIVE_OXLINT_BINDING_PATH` points to a built `.node` binding. Without that environment variable, scans use the published Oxlint binding and JavaScript rules exactly as before.
+
+## Build and verify
+
+```sh
+nr native:oxlint:verify
+nr native:oxlint:check
+nr native:oxlint:build
+REACT_DOCTOR_NATIVE_OXLINT_BINDING_PATH=dist/native-oxlint/<binding>.node nr native:oxlint:parity
+REACT_DOCTOR_NATIVE_OXLINT_BINDING_PATH=dist/native-oxlint/<binding>.node nr native:oxlint:parity --benchmark
+REACT_DOCTOR_NATIVE_OXLINT_BINDING_PATH=dist/native-oxlint/<binding>.node nr native:oxlint:parity --corpus packages/fuzz/tmp/corpus-repos
+```
+
+Set `CARGO_BUILD_JOBS=2` for the compile-check and release build on memory-constrained builders.
+
+`native:oxlint:verify` clones the pinned tag, checks its commit, and proves the patch still applies. `native:oxlint:check` overlays every native rule, regenerates Oxc's rule registry, and compile-checks the linter. `native:oxlint:build` performs the same source assembly, compiles and loads the N-API binding, and writes the binding plus provenance and SHA-256 hashes to `dist/native-oxlint`.
+
+The parity check runs the JavaScript and native implementations over the same adversarial TypeScript fixture and compares normalized diagnostics. Pass `--corpus` with a directory of repositories to compare every repository independently. A native rule should not be added to `nativeRules` or `NATIVE_REACT_DOCTOR_RULE_IDS` until both checks pass.
+
+The workflow builds artifacts for Linux x64/arm64, macOS x64/arm64, and Windows x64. It does not publish them. Shipping or making the native patch the default should happen only after corpus parity shows no diagnostic drift and benchmarks show at least a 15% p50 lint improvement.

native/oxlint/react-doctor.patch

@@ -0,0 +1,221 @@
+diff --git a/crates/oxc_linter/src/config/plugins.rs b/crates/oxc_linter/src/config/plugins.rs
+index e4e346c..6ecbfc1 100644
+--- a/crates/oxc_linter/src/config/plugins.rs
++++ b/crates/oxc_linter/src/config/plugins.rs
+@@ -68,6 +68,7 @@ pub fn plugin_display_name(plugin_name: &str) -> &str {
+     match plugin_name {
+         "jsx_a11y" => "jsx-a11y",
+         "react_perf" => "react-perf",
++        "react_doctor_native" => "react-doctor-native",
+         "nextjs" => "next",
+         _ => plugin_name,
+     }
+@@ -121,6 +122,8 @@ bitflags! {
+         const NODE = 1 << 12;
+         /// `eslint-plugin-vue`
+         const VUE = 1 << 13;
++        /// Native React Doctor rules
++        const REACT_DOCTOR_NATIVE = 1 << 14;
+     }
+ }
+
+@@ -186,6 +189,7 @@ impl TryFrom<&str> for LintPlugins {
+             "promise" => Ok(LintPlugins::PROMISE),
+             "node" => Ok(LintPlugins::NODE),
+             "vue" => Ok(LintPlugins::VUE),
++            "react-doctor-native" | "react_doctor_native" => Ok(LintPlugins::REACT_DOCTOR_NATIVE),
+             // "eslint" is not really a plugin, so it's 'empty'. This has the added benefit of
+             // making it the default value.
+             "eslint" => Ok(LintPlugins::ESLINT),
+@@ -211,6 +215,7 @@ impl From<LintPlugins> for &'static str {
+             LintPlugins::PROMISE => "promise",
+             LintPlugins::NODE => "node",
+             LintPlugins::VUE => "vue",
++            LintPlugins::REACT_DOCTOR_NATIVE => "react-doctor-native",
+             _ => "",
+         }
+     }
+@@ -282,6 +287,7 @@ impl JsonSchema for LintPlugins {
+             Promise,
+             Node,
+             Vue,
++            ReactDoctorNative,
+         }
+
+         let enum_schema = r#gen.subschema_for::<LintPluginOptionsSchema>();
+diff --git a/crates/oxc_linter/src/context/mod.rs b/crates/oxc_linter/src/context/mod.rs
+index 152f919..7e451af 100644
+--- a/crates/oxc_linter/src/context/mod.rs
++++ b/crates/oxc_linter/src/context/mod.rs
+@@ -1,15 +1,23 @@
+ #![expect(rustdoc::private_intra_doc_links)] // useful for intellisense
+
+-use std::{ffi::OsStr, ops::Deref, path::Path, rc::Rc};
++use std::{
++    borrow::Cow,
++    cell::OnceCell,
++    collections::HashMap,
++    ffi::OsStr,
++    ops::Deref,
++    path::Path,
++    rc::Rc,
++};
+
+ use javascript_globals::{GLOBALS, GLOBALS_BUILTIN, GLOBALS_ES2026};
+
+ use oxc_allocator::Allocator;
+-use oxc_ast::ast::IdentifierReference;
++use oxc_ast::{AstKind, ast::IdentifierReference};
+ use oxc_cfg::ControlFlowGraph;
+ use oxc_diagnostics::{OxcDiagnostic, Severity};
+ use oxc_semantic::{IsGlobalReference, Semantic};
+-use oxc_span::Span;
++use oxc_span::{GetSpan, LabeledSpan, Span};
+
+ #[cfg(debug_assertions)]
+ use crate::rule::RuleFixMeta;
+@@ -25,6 +33,74 @@ use crate::{
+ mod host;
+ pub use host::{ContextHost, ContextSubHost, ContextSubHostOptions};
+
++fn apply_react_doctor_diagnostic_override(
++    context: &LintContext,
++    rule_name: &str,
++    message: &mut Message,
++) {
++    let upstream_message = message.error.message.as_ref();
++    let diagnostic_message: Cow<'static, str> = match rule_name {
++        "html-has-lang" => {
++            Cow::Borrowed("Screen readers may mispronounce this page because it doesn't declare a language, so add a `lang` attribute like `en`.")
++        }
++        "no-access-key" => {
++            Cow::Borrowed("Screen reader users can lose their shortcuts because `accessKey` clashes with them, so remove it.")
++        }
++        "no-clone-element" => {
++            Cow::Borrowed("`React.cloneElement` couples the parent to the child's prop shape, so child prop changes can silently break injected behavior.")
++        }
++        "no-is-mounted" => {
++            Cow::Borrowed("`isMounted` is unreliable in modern React, so async callbacks can update state after unmount.")
++        }
++        "no-render-return-value" => {
++            Cow::Borrowed("Your app breaks in React 19 because `ReactDOM.render` returns nothing there.")
++        }
++        "no-will-update-set-state" => {
++            Cow::Borrowed("Calling setState in componentWillUpdate can trigger another update immediately, loop forever, and freeze the component.")
++        }
++        "self-closing-comp" => {
++            Cow::Borrowed("This tag has no children, so the closing tag adds noise without changing output.")
++        }
++        "no-distracting-elements" => {
++            let element = upstream_message
++                .split("`<")
++                .nth(1)
++                .and_then(|message| message.split_once('>'))
++                .map_or("element", |(element, _)| element);
++            Cow::Owned(format!("Users with attention or motion sensitivity struggle because `<{element}>` animates on its own, so use normal, accessible markup instead."))
++        }
++        "require-render-return" => Cow::Borrowed(
++            "Your users see nothing because this `render` method returns nothing.",
++        ),
++        _ => return,
++    };
++    if rule_name == "self-closing-comp" {
++        let diagnostic_spans = context.react_doctor_diagnostic_spans.get_or_init(|| {
++            context
++                .nodes()
++                .iter()
++                .filter_map(|node| match (rule_name, node.kind()) {
++                    ("self-closing-comp", AstKind::JSXElement(element)) => element
++                        .closing_element
++                        .as_ref()
++                        .map(|closing_element| {
++                            (closing_element.span().start, element.opening_element.span())
++                        }),
++                    _ => None,
++                })
++                .collect()
++        });
++        if let Some(diagnostic_span) = diagnostic_spans.get(&message.span.start) {
++            message.span = *diagnostic_span;
++        }
++    }
++    message.error.message = diagnostic_message;
++    message.error.help = None;
++    message.error.note = None;
++    message.error.labels.clear();
++    message.error.labels.push(LabeledSpan::underline(message.span));
++}
++
+ /// Contains all of the state and context specific to this lint rule.
+ ///
+ /// Includes information like the rule name, plugin name, and severity of the rule.
+@@ -59,5 +127,6 @@ pub struct LintContext<'a> {
+     /// }
+     /// ```
+     severity: Severity,
++    react_doctor_diagnostic_spans: OnceCell<HashMap<u32, Span>>,
+ }
+
+@@ -264,7 +332,18 @@ impl<'a> LintContext<'a> {
+     /// Add a diagnostic message to the list of diagnostics. Outputs a diagnostic with the current rule
+     /// name, severity, and a link to the rule's documentation URL.
+     fn add_diagnostic(&self, mut message: Message) {
+-        if self.parent.disable_directives().contains(self.current_rule_name, message.span) {
++        if self.current_plugin_name == "react_doctor_native" {
++            apply_react_doctor_diagnostic_override(self, self.current_rule_name, &mut message);
++        }
++        let is_disabled = if self.current_plugin_name == "react_doctor_native" {
++            self.parent.disable_directives().contains(
++                &format!("react-doctor/{}", self.current_rule_name),
++                message.span,
++            )
++        } else {
++            self.parent.disable_directives().contains(self.current_rule_name, message.span)
++        };
++        if is_disabled {
+             return;
+         }
+         message.error = message
+diff --git a/crates/oxc_linter/src/context/host.rs b/crates/oxc_linter/src/context/host.rs
+--- a/crates/oxc_linter/src/context/host.rs
++++ b/crates/oxc_linter/src/context/host.rs
+@@ -493,24 +493,26 @@ impl<'a> ContextHost<'a> {
+         LintContext {
+             parent: self,
++            react_doctor_diagnostic_spans: OnceCell::new(),
+             current_rule_name: rule_name,
+             current_plugin_name: plugin_name,
+             current_plugin_display_name: plugin_display_name(plugin_name),
+             #[cfg(debug_assertions)]
+             current_rule_fix_capabilities: rule.fix(),
+             severity: severity.into(),
+         }
+     }
+
+     /// Creates a new [`LintContext`] for testing purposes only.
+     #[cfg(test)]
+     pub(crate) fn spawn_for_test(self: Rc<Self>) -> LintContext<'a> {
+         LintContext {
+             parent: Rc::clone(&self),
++            react_doctor_diagnostic_spans: OnceCell::new(),
+             current_rule_name: "",
+             current_plugin_name: "eslint",
+             current_plugin_display_name: "eslint",
+             #[cfg(debug_assertions)]
+             current_rule_fix_capabilities: crate::rule::RuleFixMeta::None,
+             severity: oxc_diagnostics::Severity::Warning,
+         }
+     }
+diff --git a/crates/oxc_linter/src/rules.rs b/crates/oxc_linter/src/rules.rs
+index baa13c5..7c21b9d 100644
+--- a/crates/oxc_linter/src/rules.rs
++++ b/crates/oxc_linter/src/rules.rs
+@@ -3,6 +3,8 @@
+ //! New rules need to be added to these `mod` statements.
+ //! Then run `cargo lintgen` to regenerate the RuleEnum and RuleRunnerImpls.
+
++pub(crate) mod react_doctor_native;
++
+ /// <https://github.com/import-js/eslint-plugin-import>
+ pub(crate) mod import {
+     pub mod consistent_type_specifier_style;