diagnose()

Programmatic API for diagnosing React codebase health

Function Signature

export const diagnose = async (
  directory: string,
  options: DiagnoseOptions = {},
): Promise<DiagnoseResult>

The diagnose() function is the primary programmatic API for React Doctor. It analyzes a React codebase and returns diagnostics, score, and project information.

Parameters

directory · string · required

Absolute or relative path to the project directory to scan.

options · DiagnoseOptions · default: "{}"

Configuration options for the diagnosis.

Show DiagnoseOptions properties

lint · boolean · default: "true"

Enable linting checks using oxlint. Defaults to true unless overridden by config file.

deadCode · boolean · default: "true"

Enable dead code detection using Knip. Defaults to true unless overridden by config file.

Note: Dead code analysis is automatically skipped when includePaths is provided (diff mode).

includePaths · string[] · default: "[]"

Array of file paths to scan. When provided, enables “diff mode” and only scans the specified files.

Note: Dead code detection is automatically disabled in diff mode.

{
  includePaths: [
    'src/components/Button.tsx',
    'src/utils/format.ts'
  ]
}

Return Value

DiagnoseResult · object

The result of the diagnosis operation.

Show DiagnoseResult properties

diagnostics · Diagnostic[]

Array of diagnostic issues found in the codebase. See Diagnostic type.

score · ScoreResult | null

Overall codebase health score, or null if calculation failed. See ScoreResult type.

project · ProjectInfo

Information about the analyzed project. See ProjectInfo type.

elapsedMilliseconds · number

Time taken to complete the diagnosis in milliseconds.

Errors

The function throws an error if:

• No React dependency is found in package.json
• The directory path is invalid or inaccessible

if (!projectInfo.reactVersion) {
  throw new Error("No React dependency found in package.json");
}

Examples

Basic usage

import { diagnose } from 'react-doctor/api';

const result = await diagnose('./my-app');

console.log(`Found ${result.diagnostics.length} issues`);
console.log(`Score: ${result.score?.score}`);
console.log(`Completed in ${result.elapsedMilliseconds}ms`);

With options

import { diagnose } from 'react-doctor/api';

const result = await diagnose('./my-app', {
  lint: true,
  deadCode: false,
});

for (const diagnostic of result.diagnostics) {
  console.log(`${diagnostic.severity}: ${diagnostic.message}`);
  console.log(`  at ${diagnostic.filePath}:${diagnostic.line}:${diagnostic.column}`);
}

Diff mode (scan specific files)

import { diagnose, getDiffInfo, filterSourceFiles } from 'react-doctor/api';

// Get changed files from git
const diffInfo = getDiffInfo('./my-app');
const changedFiles = diffInfo ? filterSourceFiles(diffInfo.changedFiles) : [];

// Scan only changed files
const result = await diagnose('./my-app', {
  includePaths: changedFiles,
});

console.log(`Scanned ${changedFiles.length} changed files`);
console.log(`Found ${result.diagnostics.length} issues in changes`);

Error handling

import { diagnose } from 'react-doctor/api';

try {
  const result = await diagnose('./my-app');
  
  if (result.diagnostics.some(d => d.severity === 'error')) {
    console.error('Critical errors found!');
    process.exit(1);
  }
} catch (error) {
  console.error('Diagnosis failed:', error.message);
  process.exit(1);
}

CI integration

import { diagnose } from 'react-doctor/api';

const result = await diagnose(process.cwd(), {
  lint: true,
  deadCode: true,
});

const errorCount = result.diagnostics.filter(d => d.severity === 'error').length;
const warningCount = result.diagnostics.filter(d => d.severity === 'warning').length;

console.log(`Errors: ${errorCount}, Warnings: ${warningCount}`);
console.log(`Score: ${result.score?.score} (${result.score?.label})`);

if (errorCount > 0) {
  process.exit(1);
}

Configuration File

The diagnose() function automatically loads configuration from react-doctor.config.json in the project directory. Options passed to the function take precedence over config file settings.

See Configuration for more details.

Related

• Types Reference - TypeScript type definitions
• Utility Functions - getDiffInfo() and filterSourceFiles()
• Configuration - Config file format