feat(core): per-file content-addressed lint cache with cross-file sidecar

[rayhanadev]

Why

Today the only lint cache is whole-repo all-or-nothing: a single dirty file, a new HEAD SHA, or a CI re-clone voids the entire payload and lint re-runs on every file. This adds a second tier — a per-file content-addressed cache — so repeat scans (local pre-commit loops, CI on incremental commits) re-lint only the files whose content actually changed, while staying byte-identical to a cold scan.

Before:

# whole-repo cache misses on ANY change → full re-lint of all ~1,274 files (~4.2s)
$ react-doctor          # edited 1 file → re-lints everything

After:

# unchanged files replay cached diagnostics; only changed files re-lint
$ react-doctor          # edited 1 file → re-lints ~1 file, replays the rest

What changed

• Two-config sidecar split inside the oxlint runner: a cacheable config (all rules except the cross-file set) runs only on changed files; a sidecar config (only the 5 cross-file rules) always runs fresh on every file, so a dependency change can never serve a stale cross-file verdict on an unchanged file.
• Content-hash keying (<relativePath> <sha1(content)> under a ruleset-hash bucket) — survives CI re-clones (mtime would not). The ruleset hash captures the normalized config + toolchain versions + ignore patterns; absolute paths are stripped for portability.
• Caches the raw oxlint diagnostics (pre-presentation), so --no-warnings / suppressions / surface filtering never bust the cache.
• CROSS_FILE_RULE_IDS (exactly 5, verified by transitive import-graph analysis) exported from oxlint-plugin-react-doctor; a guard test (cross-file-rule-ids.test.ts) fails if a future rule reads other files without being carved into the sidecar.
• On by default; auto-bypassed in audit mode / adopted extends / user plugins. Opt out via REACT_DOCTOR_NO_FILE_CACHE=1 (REACT_DOCTOR_NO_CACHE=1 now disables both caches).
• CLI emits lintCacheHitRatio on the Sentry run wide event (numeric; null when the cache was off/bypassed, threaded outside CachedScanPayload so a whole-repo cache-hit replay reads as "no lint ran").
• Changeset: patch for react-doctor, @react-doctor/core, oxlint-plugin-react-doctor.

Test plan

• pnpm typecheck — green (11/11 packages)
• pnpm lint / pnpm format:check / pnpm smoke:json-report — green (schemaVersion=1, output unchanged)
• pnpm test — green except the two known env-file gitignore-trap tests (check-security-scan/check-expo-project), which fail locally due to a global ~/.config/git/ignore .env* entry and are unrelated to this change
• New tests: byte-identical (cache on/off), cache-stats, content-change invalidation, cross-file staleness (dependency changes, unchanged file gets the fresh verdict), audit-mode bypass, ruleset-hash portability/stability, file-cache round-trip/fail-open/malformed/LRU, and the cross-file-rule guard
• The entire react-doctor e2e suite (1842 tests) runs through the cache-on split path by default and passes → byte-identical evidence across the fixture corpus

Note: no action.yml change — the GitHub Action's actions/cache step is a separate action release (the cache is transparent to it).

🤖 Generated with Claude Code

---

Note

Medium Risk
Large change to the core lint path with correctness invariants (sidecar split, store guards); mistakes could serve stale diagnostics, though extensive e2e byte-identical tests and the cross-file guard mitigate that.

Overview
Adds a default-on per-file lint cache so repeat scans replay raw oxlint diagnostics for unchanged files (keyed by path + SHA-1 content under a portable ruleset hash) and only re-lint misses. Scores, JSON reports, and inspect/diagnose output stay byte-identical to a cold run; the cache stores pre-presentation diagnostics so warning/suppression toggles do not bust entries.

The oxlint runner splits into a cacheable pass (within-file rules only, changed files) and an always-fresh sidecar for five cross-file rules exported as CROSS_FILE_RULE_IDS; a guard test fails if a new rule reads other files without joining that set. The cache is skipped for audit mode, adopted extends, user plugins, and React Compiler projects; opt out with REACT_DOCTOR_NO_FILE_CACHE=1 or global REACT_DOCTOR_NO_CACHE=1. Disk cache lives under node_modules/.cache/react-doctor with fail-open I/O, LRU caps, and conservative skip-on-partial-failure store rules.

Telemetry: lintCacheHitFileCount / ratio on inspect results and Sentry run events (lintCacheHitRatio).

^{Reviewed by Cursor Bugbot for commit 7db6e41. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

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

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

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

commit: 7db6e41

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0b0c6ee. Configure here.}

[rayhanadev]

Superseded by #903, which integrated this work and squash-merged to main (commit 627f9ca). The changes shipped there — some reworked during integration (e.g. the dead-code overlap became sequential-by-default, and cost-ordering was defaulted off); see the #903 description and the changesets on main. Closing in favor of main.