# Rule Categories and Severity Levels in React-Doctor: A Complete Diagnostic Guide

> Explore React-Doctor's rule categories like Architecture, Performance, and Security, with error and warning severity levels. Master diagnostic insights for your React app.

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

---

**React-Doctor organizes linting results into logical categories such as Architecture, Performance, and Security, while using a binary severity system of "error" and "warning" to distinguish between hard failures and advisory notices.**

React-Doctor is a specialized diagnostic scanner for React applications that evaluates code health across multiple dimensions. As implemented in the `millionco/react-doctor` repository, every diagnostic report is tagged with both a **category** for logical grouping and a **severity** level to indicate urgency. This dual-classification system enables developers to filter noise from critical issues and prioritize fixes effectively.

## Binary Severity Levels: Error vs Warning

React-Doctor treats severity as a strict binary value defined in the diagnostic structure. Unlike systems with multiple gradations, this approach simplifies CI/CD integration and immediate actionability.

### Error Severity

The `"error"` level indicates a hard problem that will break continuous integration pipelines when the `--fail-on error` flag is enabled. These violations represent architectural blockers or correctness issues that must be resolved before deployment.

### Warning Severity

The `"warning"` level marks advisory notices that appear in reports but do not abort the scan. While warnings suggest potential improvements or technical debt, they allow the build process to continue uninterrupted.

## Rule Categories in React-Doctor

Categories are not hard-coded into a central enum; instead, each rule supplies its category string via metadata. During the scan, diagnostics inherit these categories, enabling flexible grouping across diverse technology stacks.

The existing rule set produces the following taxonomy:

- **Architecture**: `no-architecture-violations`, `no-circular-deps`
- **Bundle Size**: `no-large-bundles`, `no-unnecessary-dependencies`
- **Correctness**: `no-missing-key`, `no-undefined-prop`
- **Performance**: `no-unoptimized-loops`, `no-excessive-renders`
- **Security**: `no-xss-payload`, `no-hard-coded-secrets`
- **State & Effects**: `no-derived-state`, `no-effect-chain`
- **Next.js**: `no-unused-getStaticProps`, `no-invalid-router-usage`
- **Server**: `no-blocking-calls-in-api`, `no-direct-db-queries`
- **TanStack Query**: `no-missing-query-keys`, `no-stale-query-data`
- **TanStack Start**: `no-duplicate-routes`, `no-missing-loader`
- **React Native**: `no-inline-styles-in-RN`, `no-deprecated-RN-APIs`
- **Test**: `no-focused-tests`, `no-missing-assertions`
- **Other**: Custom legacy rules or domain-specific classifications

Note that category matching is case-insensitive, allowing "Security" and "security" to aggregate together.

## The Diagnostic Data Structure

According to [`src/types.ts`](https://github.com/millionco/react-doctor/blob/main/src/types.ts), every diagnostic is a JavaScript object implementing the `Diagnostic` interface. This structure ensures consistency across plugins and rules.

```ts
// From src/types.ts
interface Diagnostic {
  plugin: string;      // e.g., "react"
  rule: string;        // e.g., "no-missing-key"
  severity: "error" | "warning";
  message: string;
  help?: string;
  line: number;
  column: number;
  category: string;    // e.g., "Correctness"
}

```

When filtering results, you can leverage this structure:

```ts
// Filter for hard errors only
const errors = diagnostics.filter(d => d.severity === "error");

// Group by specific category
const perfIssues = diagnostics.filter(d => 
  d.category.toLowerCase() === "performance"
);

```

## Aggregating Category Breakdowns

The CLI report utilizes the `buildCategoryBreakdown` utility from [`src/utils/build-category-breakdown.ts`](https://github.com/millionco/react-doctor/blob/main/src/utils/build-category-breakdown.ts) (lines 10-31) to generate a summary view. This function iterates over the diagnostic array, aggregates counts per category, and sorts results by error frequency.

```ts
import { buildCategoryBreakdown } from "./utils/build-category-breakdown.js";

const breakdown = buildCategoryBreakdown(diagnostics);
// Output: [{ category: "Performance", totalCount: 12, errorCount: 4, warningCount: 8 }, ...]

```

The resulting breakdown sorts categories so those with the highest error counts appear first, allowing developers to identify the most critical problem areas at a glance.

## Summary

- React-Doctor employs two severity levels: `"error"` for critical failures and `"warning"` for advisory notices.
- Categories such as Architecture, Performance, and Security are defined by individual rule metadata rather than a centralized enum.
- The `Diagnostic` interface in [`src/types.ts`](https://github.com/millionco/react-doctor/blob/main/src/types.ts) standardizes the inclusion of both `category` and `severity` fields.
- The `buildCategoryBreakdown` utility in [`src/utils/build-category-breakdown.ts`](https://github.com/millionco/react-doctor/blob/main/src/utils/build-category-breakdown.ts) aggregates diagnostics by category and severity for reporting.
- Severity levels integrate with CI pipelines via the `--fail-on error` flag to enforce code quality gates.

## Frequently Asked Questions

### What severity levels does React-Doctor support?

React-Doctor supports two severity levels: `"error"` and `"warning"`. Errors represent critical issues that can fail CI builds when using `--fail-on error`, while warnings indicate non-blocking suggestions for improvement.

### How are rule categories defined in React-Doctor?

Rule categories are defined in each rule's metadata rather than a hard-coded enum. When a rule detects a violation, it populates the `category` field of the diagnostic object with strings like "Performance", "Security", or "Architecture".

### Can I filter diagnostics by category in React-Doctor?

Yes. Since every diagnostic object contains a `category` string, you can filter the diagnostics array using standard JavaScript array methods like `filter()`, or use the `buildCategoryBreakdown` utility to view aggregated counts per category.

### Where is the category aggregation logic implemented?

The aggregation logic resides in [`src/utils/build-category-breakdown.ts`](https://github.com/millionco/react-doctor/blob/main/src/utils/build-category-breakdown.ts). This file contains the function that tallies total, error, and warning counts per category and sorts them by severity priority for the final report.