fix(core): bound scan phases + binary-split cascade with hard timeouts

[rayhanadev]

Why

Production traces show genuine pathological hangs the existing per-unit timeouts do not contain — runInspect max 57,912s (~16h), Linter.run max 26,910s (~7.5h), supply-chain fetchScore max 981s despite a 10s per-fetch timeout (undici sockets that ignore abort), and dead-code workers clipping their 120s ceiling. Every CI run and every interactive scan on a repo with one bad dependency socket or one quadratic file is exposed. This is a correctness/robustness fix that caps worst-case wall time without changing the median scan.

Before:

runInspect            p100 = 57,912s (16h)   ← one wedged phase hangs the whole job
Linter.run            p100 = 26,910s (7.5h)  ← binary-split cascade re-waits 60s per level, unbounded
SupplyChain.fetchScore p100 = 981s           ← socket ignores per-fetch abort, run-to-completion
DeadCode worker       max 1,072s             ← unref'd in-worker timer fires late under a starved loop

After:

Bounded, fail-fast into the existing skipped-check / fail-open channels:
- split cascade  → drop to onPartialFailure after a 3-min cumulative budget / depth-8 cap
- supply-chain   → fail open ([]) after a 90s whole-check cap
- dead-code      → skip after a 2.5-min Effect-side cap (worker SIGKILL'd on interruption)
- lint           → skip + null score after a 5-min Effect-side cap
- whole scan     → ScanDeadlineExceeded after a 15-min backstop

What changed

• Binary-split cascade (spawn-batches.ts): cumulative split-time budget (OXLINT_SPLIT_TOTAL_BUDGET_MS) + recursion-depth cap (OXLINT_SPLIT_MAX_DEPTH) drop remaining files of a pathological batch into the existing onPartialFailure → skippedCheckReasons["lint:partial"] channel instead of re-waiting a full spawn timeout at every split level. Both are injectable params (constant defaults) so the bound is deterministically testable.
• Supply-chain (check-supply-chain.ts): whole-check Effect.timeoutOption(SUPPLY_CHAIN_TOTAL_TIMEOUT_MS) fails open ([]) — the same fail-open contract as the per-fetch orElseSucceed(() => null).
• Dead-code & lint phases (run-inspect.ts): Effect-side timeoutOption caps fold a timeout into the existing deadCodeFailure / lintFailure Refs (lint→score null, tagged OxlintBatchExceeded for renderer dispatch). The dead-code worker's AbortSignal now SIGKILLs the child on Effect interruption (no orphan child).
• Overall deadline (run-inspect.ts): Effect.timeout(ScanDeadlineMs) backstops anything not bounded per phase, raising the new ScanDeadlineExceeded reason on the ReactDoctorError union; the channel type stays ReactDoctorError.
• All caps env-tunable (REACT_DOCTOR_LINT_PHASE_TIMEOUT_MS, REACT_DOCTOR_DEAD_CODE_PHASE_TIMEOUT_MS, REACT_DOCTOR_SCAN_DEADLINE_MS) via Context.Reference; defaults sit above measured p95. Duplicated env-parse logic extracted into a shared readPositiveEnvMs util.

Internal-only — no CLI flag, config-schema, JSON-report, or Action change. Patch changeset included.

Test plan

• pnpm typecheck — 11/11 ✓
• pnpm lint — clean ✓ · pnpm format:check — clean ✓ · pnpm smoke:json-report — OK ✓
• pnpm test (run per-package directly): core 896, api 15, CLI 1837 (+15 skipped), language-server 60 — all pass, including 8 new tests (cascade bound, supply-chain fail-open, dead-code/lint phase caps, overall deadline, dead-code abort→terminate, ScanDeadlineExceeded).
• Note: 2 check-security-scan tests fail only under a local global ~/.config/git/ignore that ignores .env (a pre-existing environmental trap, file untouched here); they pass in CI and locally with core.excludesFile=/dev/null.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes core scan orchestration and subprocess lifecycle; timeouts degrade gracefully via existing skip contracts, but mis-tuned env vars could skip lint/dead-code or fail scans early on legitimately slow repos.

Overview
Adds hard, env-tunable wall-clock caps so pathological scans cannot run for hours. Normal scans should be unchanged; defaults sit above measured p95.

Oxlint binary-split recovery now shares a 3-minute cumulative budget and depth-8 cap across all retries in spawnLintBatches. When exhausted, remaining files go through the existing onPartialFailure / partial-lint skip path instead of re-waiting a full per-batch spawn timeout at every split level.

Supply-chain wraps the concurrent Socket fetches in a 90s whole-check Effect.timeoutOption that fails open to no diagnostics, matching per-fetch skip behavior when sockets ignore abort.

Lint and dead-code get Effect-level caps (5 min / 2.5 min) in runInspect that fold into the existing lint-failure (null score, OxlintBatchExceeded tag) and dead-code skip contracts so the rest of the scan still finishes. AbortSignal is threaded from Effect.tryPromise through the linter into oxlint spawns and the dead-code worker so phase timeouts SIGKILL in-flight children instead of leaving orphans.

Overall scan is wrapped in Effect.timeout(ScanDeadlineMs) (default 15 min), surfacing new ScanDeadlineExceeded on the ReactDoctorError union for wedged phases not individually capped.

New readPositiveEnvMs centralizes env parsing for timeout Context.References (REACT_DOCTOR_*_TIMEOUT_MS, REACT_DOCTOR_SCAN_DEADLINE_MS).

^{Reviewed by Cursor Bugbot for commit 5fb6222. 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@899

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

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

commit: 5fb6222

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

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

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

[devin-ai-integration]

Devin Review found 1 potential issue.

[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.