How React-Doctor Determines Error Versus Warning Severity for Lint Rules

In react-doctor, a diagnostic's severity is determined by the underlying oxlint analyzer and can be overridden by internal promotion logic that forces specific rule groups—such as react-hooks-js—to error status.

React-doctor leverages oxlint to analyze React codebases and assigns each diagnostic a severity level that affects CI behavior and scoring penalties. Understanding what criteria determine if a rule is classified as an error versus a warning severity is essential for configuring build pipelines and interpreting health scores accurately.

The Source of Severity Levels

Oxlint as the Foundation

React-doctor does not generate severity classifications independently. Instead, each diagnostic's severity property originates from the oxlint analysis engine that powers the tool, as implemented in the owner/millionco/react-doctor repository.

According to the type definitions in packages/website/src/app/api/score/route.ts (lines 12‑28), the severity field is strictly typed to accept only two values:

type Diagnostic = {
  severity: "error" | "warning";
  // … additional fields
};

This type constraint ensures that every diagnostic carries an explicit severity label consumed by the scoring API and report builders to differentiate penalties.

Criteria for Error Classification

A rule receives error severity through two distinct mechanisms:

Oxlint Native Configuration – When oxlint defines a rule as error-level by default, react-doctor preserves this classification without modification.

Forced Promotion via Internal Lists – React-doctor maintains internal "error-rules" lists that upgrade specific rules to error status regardless of oxlint's default. This ensures critical issues fail CI pipelines when the --fail-on error flag is used. For example, all react-hooks-js rules are explicitly forced to error severity.

The test suite in packages/react-doctor/tests/regressions/scan-resilience.test.ts (lines 354‑358) verifies this promotion logic:

it("emits every react-hooks-js rule at error severity", () => {
  // react-hooks-js rules are intentionally upgraded to "error"
  // to ensure CI failure when --fail-on error is used
});

Criteria for Warning Classification

Warning severity serves as the default classification for non-critical rules that oxlint reports as warnings. This applies to any rule that react-doctor does not explicitly promote to error status through its internal mapping.

The validation tests in packages/react-doctor/tests/run-oxlint.test.ts (lines 23‑30) confirm that diagnostics always return a valid severity string:

it("exposes error or warning severity", () => {
  const diagnostic = runOxlint(...);
  expect(["error", "warning"]).toContain(diagnostic.severity);
});

Consumption in the Scoring System

The severity field directly influences penalty calculations in the scoring API. In packages/website/src/app/api/score/route.ts, the application differentiates between error and warning rules to apply appropriate weighting to the final health score:

const errorRules = new Set<string>();
diagnostics.forEach(diagnostic => {
  if (diagnostic.severity === "error") {
    errorRules.add(diagnostic.rule);
  }
});

This logic ensures that error-level diagnostics contribute more heavily to scoring penalties than warnings, reflecting their critical nature in the codebase.

Summary

• Oxlint assigns the initial severity when discovering a problem, defaulting to either "error" or "warning" based on the rule's criticality.
• React-doctor may rewrite the severity for specific rule groups—most notably promoting all react-hooks-js rules to error to enforce CI failures.
• The final severity field is consumed by the scoring API in packages/website/src/app/api/score/route.ts to calculate penalties and by report builders to group diagnostics.
• Severity is strictly typed as "error" | "warning" throughout the codebase to ensure type safety.

Frequently Asked Questions

Can I override a warning to be treated as an error in react-doctor?

React-doctor supports overriding specific rule groups to error severity through internal configuration lists, but this requires modifying the source code. Currently, the tool automatically promotes react-hooks-js rules to error, though arbitrary end-user configuration via CLI flags is not exposed in the current implementation.

How does severity affect the health score calculation?

Error severity carries a higher penalty weight than warnings in the scoring algorithm. The API specifically checks for severity === "error" to populate the errorRules set, which receives stricter scoring deductions than warnings according to the logic in packages/website/src/app/api/score/route.ts.

Why are react-hooks-js rules forced to error severity?

These rules are promoted to error status to ensure that violations fail CI pipelines when using the --fail-on error flag. This enforcement prevents broken hook rules from passing automated checks, as verified in packages/react-doctor/tests/regressions/scan-resilience.test.ts.

Where does react-doctor get the initial severity classification?

React-doctor inherits severity levels directly from oxlint, the underlying Rust-based linter. The severity property is preserved from oxlint's diagnostic output and only modified by react-doctor's internal promotion logic for specific critical rule groups.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}