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

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, every diagnostic is a JavaScript object implementing the Diagnostic interface. This structure ensures consistency across plugins and rules.

// 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:

// 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 (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.

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 standardizes the inclusion of both category and severity fields.
• The buildCategoryBreakdown utility in 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. This file contains the function that tallies total, error, and warning counts per category and sorts them by severity priority for the final report.

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