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

> Learn how React Doctor classifies lint rule severity, differentiating errors from warnings based on oxlint analysis and optional internal promotion logic.

- Repository: [Million Software, Inc./react-doctor](https://github.com/millionco/react-doctor)
- Tags: internals
- Published: 2026-05-12

---

**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`](https://github.com/millionco/react-doctor/blob/main/packages/website/src/app/api/score/route.ts) (lines 12‑28), the severity field is strictly typed to accept only two values:

```typescript
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`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/tests/regressions/scan-resilience.test.ts) (lines 354‑358) verifies this promotion logic:

```typescript
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`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/tests/run-oxlint.test.ts) (lines 23‑30) confirm that diagnostics always return a valid severity string:

```typescript
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`](https://github.com/millionco/react-doctor/blob/main/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:

```typescript
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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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.