TypeScript Types

Complete TypeScript type definitions for React Doctor

Core Types

Diagnostic

Represents a single diagnostic issue found in the codebase.

export interface Diagnostic {
  filePath: string;
  plugin: string;
  rule: string;
  severity: "error" | "warning";
  message: string;
  help: string;
  line: number;
  column: number;
  category: string;
  weight?: number;
}

filePath · string

Absolute path to the file containing the issue.

plugin · string

Source of the diagnostic (e.g., "oxlint", "knip").

rule · string

Specific rule that was violated (e.g., "react-hooks/exhaustive-deps").

severity · 'error' | 'warning'

Severity level of the issue.

message · string

Human-readable description of the issue.

help · string

Additional context or guidance for fixing the issue.

line · number

Line number where the issue occurs (1-indexed).

column · number

Column number where the issue occurs (1-indexed).

category · string

Categorization of the issue (e.g., "correctness", "style", "performance").

weight · number

Numeric weight for score calculation. Higher weights have more impact on the score.

ProjectInfo

Information about the analyzed React project.

export interface ProjectInfo {
  rootDirectory: string;
  projectName: string;
  reactVersion: string | null;
  framework: Framework;
  hasTypeScript: boolean;
  hasReactCompiler: boolean;
  sourceFileCount: number;
}

rootDirectory · string

Absolute path to the project root directory.

projectName · string

Name of the project from package.json.

reactVersion · string | null

Version of React installed, or null if not found.

framework · Framework

Detected framework. See Framework type.

hasTypeScript · boolean

Whether TypeScript is detected in the project.

hasReactCompiler · boolean

Whether React Compiler (babel-plugin-react-compiler) is detected.

sourceFileCount · number

Total number of source files in the project.

ScoreResult

Overall health score for the codebase.

export interface ScoreResult {
  score: number;
  label: string;
}

score · number

Numeric score from 0-100, where 100 is perfect health.

label · string

Human-readable label for the score (e.g., "Excellent", "Good", "Fair", "Poor").

DiffInfo

Information about changed files in a git repository.

export interface DiffInfo {
  currentBranch: string;
  baseBranch: string;
  changedFiles: string[];
  isCurrentChanges?: boolean;
}

currentBranch · string

Name of the current git branch.

baseBranch · string

Name of the base branch for comparison.

changedFiles · string[]

Array of file paths that have changed.

isCurrentChanges · boolean

Whether the changes are uncommitted (working directory changes).

ReactDoctorConfig

Configuration object from react-doctor.config.json.

export interface ReactDoctorConfig {
  ignore?: ReactDoctorIgnoreConfig;
  lint?: boolean;
  deadCode?: boolean;
  verbose?: boolean;
  diff?: boolean | string;
  failOn?: FailOnLevel;
}

ignore · ReactDoctorIgnoreConfig

Rules and files to ignore. See ReactDoctorIgnoreConfig.

lint · boolean

Enable linting checks.

deadCode · boolean

Enable dead code detection.

verbose · boolean

Show verbose output with file details.

diff · boolean | string

Enable diff mode. If a string, specifies the base branch name.

failOn · FailOnLevel

Exit code behavior. See FailOnLevel.

ReactDoctorIgnoreConfig

Configuration for ignoring specific rules or files.

export interface ReactDoctorIgnoreConfig {
  rules?: string[];
  files?: string[];
}

rules · string[]

Array of rule IDs to ignore (e.g., ["react-hooks/exhaustive-deps"]).

files · string[]

Array of file glob patterns to ignore (e.g., ["**/*.test.tsx"]).

Enums & Unions

Framework

Supported React frameworks.

export type Framework =
  | "nextjs"
  | "vite"
  | "cra"
  | "remix"
  | "gatsby"
  | "expo"
  | "react-native"
  | "unknown";

nextjs · Framework

Next.js framework

vite · Framework

Vite framework

cra · Framework

Create React App

remix · Framework

Remix framework

gatsby · Framework

Gatsby framework

expo · Framework

Expo framework

react-native · Framework

React Native (non-Expo)

unknown · Framework

Framework could not be detected

FailOnLevel

Exit code behavior based on diagnostic severity.

export type FailOnLevel = "error" | "warning" | "none";

error · FailOnLevel

Exit with code 1 only if errors are found.

warning · FailOnLevel

Exit with code 1 if any warnings or errors are found.

none · FailOnLevel

Always exit with code 0 regardless of diagnostics.

Internal Types

These types are used internally by React Doctor but may be useful for advanced use cases.

EstimatedScoreResult

Estimated score improvement after fixing issues.

export interface EstimatedScoreResult {
  currentScore: number;
  currentLabel: string;
  estimatedScore: number;
  estimatedLabel: string;
}

ScanOptions

Internal options used by the CLI scanner.

export interface ScanOptions {
  lint?: boolean;
  deadCode?: boolean;
  verbose?: boolean;
  scoreOnly?: boolean;
  offline?: boolean;
  includePaths?: string[];
}

ScanResult

Internal result from the scanner.

export interface ScanResult {
  diagnostics: Diagnostic[];
  scoreResult: ScoreResult | null;
  skippedChecks: string[];
}

PackageJson

Structure of a package.json file.

export interface PackageJson {
  name?: string;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  workspaces?: string[] | { packages: string[] };
}

WorkspacePackage

Information about a workspace package in a monorepo.

export interface WorkspacePackage {
  name: string;
  directory: string;
}

Utility Functions

getDiffInfo()

Returns information about changed files in a git repository.

export function getDiffInfo(
  directory: string,
  baseBranch?: string
): DiffInfo | null

directory · string · required

Path to the git repository.

baseBranch · string

Base branch for comparison. If not provided, uses the default base branch (usually main or master).

Returns: DiffInfo | null - Diff information or null if not a git repository or no changes found.

filterSourceFiles()

Filters an array of file paths to include only source files.

export function filterSourceFiles(files: string[]): string[]

files · string[] · required

Array of file paths to filter.

Returns: string[] - Array containing only source files (JavaScript, TypeScript, JSX, TSX).

Examples

Type-safe diagnostic handling

import type { Diagnostic } from 'react-doctor/api';

function groupDiagnosticsBySeverity(diagnostics: Diagnostic[]) {
  const errors = diagnostics.filter(d => d.severity === 'error');
  const warnings = diagnostics.filter(d => d.severity === 'warning');
  
  return { errors, warnings };
}

Custom score display

import type { ScoreResult } from 'react-doctor/api';

function formatScore(score: ScoreResult | null): string {
  if (!score) return 'N/A';
  
  const emoji = score.score >= 90 ? '🟢' :
                score.score >= 70 ? '🟡' :
                score.score >= 50 ? '🟠' : '🔴';
  
  return `${emoji} ${score.score}/100 (${score.label})`;
}

Working with project info

import type { ProjectInfo, Framework } from 'react-doctor/api';

function getFrameworkDisplayName(framework: Framework): string {
  const names: Record<Framework, string> = {
    nextjs: 'Next.js',
    vite: 'Vite',
    cra: 'Create React App',
    remix: 'Remix',
    gatsby: 'Gatsby',
    expo: 'Expo',
    'react-native': 'React Native',
    unknown: 'Unknown',
  };
  
  return names[framework];
}

function displayProjectInfo(project: ProjectInfo) {
  console.log(`Project: ${project.projectName}`);
  console.log(`Framework: ${getFrameworkDisplayName(project.framework)}`);
  console.log(`React: ${project.reactVersion || 'Not found'}`);
  console.log(`TypeScript: ${project.hasTypeScript ? 'Yes' : 'No'}`);
  console.log(`Files: ${project.sourceFileCount}`);
}