codehealth

A fast, framework-aware React code scanner that tells you exactly which component, on which line has a problem — and gives you a copy-paste ready fix for every issue found.

Works completely standalone. No ESLint dependency. No config files needed.

codehealth  Next.js  ·  104 files scanned

── correctness ───────────────────────────── 2 ──
 ✗  missing-use-client            2×
    Client hook used without "use client" directive

── best-practice ─────────────────────────── 3 ──
 ⚠  index-as-key                  2×
    Array index used as key — use a stable unique ID instead
 ⚠  effect-set-state              1×
    Multiple setState calls inside useEffect — consider useReducer

╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
  87 / 100  Great  😺  ·  ✗ 2  ·  ⚠ 3  ·  104 files
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Install

npm install -g codehealth

Or run without installing:

npx codehealth .

Usage

codehealth <path> [framework] [options]

If you don't pass a framework flag, an interactive prompt lets you pick one with arrow keys.

codehealth .                     # interactive framework selector
codehealth . --react             # React (CRA, Vite, etc.)
codehealth . --next              # Next.js (App Router / Pages Router)
codehealth . --react-native      # React Native (bare workflow)
codehealth . --expo              # Expo (managed / bare)

Options

| Flag | Description | |------|-------------| | --react | Use the React rule profile | | --next | Use the Next.js rule profile | | --react-native | Use the React Native rule profile | | --expo | Use the Expo rule profile | | -w, --watch | Re-scan on every file save | | -r, --rule <id> | Run only a single rule | | --ignore <pattern> | Glob pattern to exclude (repeatable) | | --list-rules | List rules for the selected profile | | --max-issues <n> | Show only first N issues (0 = all) | | --compact | Show file headers only, no code snippets or fix details | | --ai-prompt | Output a plain-text AI prompt for refactoring assistance |

Examples

codehealth . --next
codehealth . --next --watch
codehealth . --react --rule fetch-in-effect
codehealth . --next --ignore "src/generated/**"
codehealth . --list-rules --expo
codehealth . --next --ai-prompt

Interactive Mode

In a TTY terminal, after the scan completes you get an interactive menu:

  What would you like to do?  (↑↓ arrow keys, Enter to confirm)

  ❯ Overview & score
    Detailed fixes
    AI refactoring view
    Exit

• Overview & score — category breakdown and score summary
• Detailed fixes — full issue list with affected files, code context and copy-paste fixes
• AI refactoring view — grouped output formatted for pasting into an AI assistant
• Exit — quit the process

The screen clears between views so output never accumulates.

In non-TTY environments (CI, pipes, redirects) the interactive menu is skipped and output is printed directly.

Framework Profiles

Each framework flag activates a curated set of rules relevant to that stack.

--react

For projects using Create React App, Vite, or any plain React setup.

| Rule | Severity | Description | |------|----------|-------------| | fetch-in-effect | error | fetch() inside useEffect — use a data fetching library | | multiple-usestate | warning | 4+ useState calls — consider useReducer | | large-component | warning | Component over 300 lines — consider splitting | | effect-set-state | warning | Multiple setState calls inside one useEffect | | effect-as-handler | warning | useEffect watching an event flag — move logic to the handler | | index-as-key | warning | key={index} in a list — use a stable unique ID | | heavy-import | warning | Heavy library without lazy loading (moment, lodash, etc.) | | a11y-autofocus | warning | autoFocus attribute disrupts screen readers | | a11y-label | warning | <input> / <textarea> with no accessible label | | a11y-interactive | warning | Clickable element with no keyboard listener | | a11y-role | warning | Element with event handler but no ARIA role | | no-console-log | warning | console statement in production code |

--next

Everything in --react, plus Next.js App Router specific rules.

| Rule | Severity | Description | |------|----------|-------------| | missing-use-client | error | Hook used without "use client" directive | | use-search-params | warning | useSearchParams() without a <Suspense> boundary | | img-not-optimized | warning | Raw <img> tag — use next/image instead |

--react-native

Core React rules adapted for mobile, plus React Native specific checks. Web a11y rules are excluded.

| Rule | Severity | Description | |------|----------|-------------| | inline-styles | warning | style={{ }} inline object — use StyleSheet.create() | | flatlist-for-lists | warning | .map() inside <ScrollView> — use <FlatList> | | rn-accessibility | warning | <Pressable> / <TouchableOpacity> with no accessibilityLabel |

--expo

Everything in --react-native, plus Expo specific rules.

| Rule | Severity | Description | |------|----------|-------------| | constants-manifest | error | Constants.manifest is deprecated — use Constants.expoConfig |

Scoring

Every scan produces a score from 0 to 100.

100 - (errors × 5) - (warnings × 1)

| Score | Label | | |-------|-------|-| | 90–100 | Excellent | 😸 | | 75–89 | Great | 😺 | | 50–74 | Needs work | 😾 | | 0–49 | Needs work | 🙀 |

The process exits with code 1 if any errors are found, making it easy to use in CI.

Watch Mode

codehealth . --next --watch

Uses chokidar to watch .ts, .tsx, .js, .jsx files. When a file changes, only that file is re-scanned and the output is refreshed in place.

CI Usage

- name: Run codehealth
  run: npx codehealth . --next

Exits with code 1 on errors, 0 on warnings-only or clean scan.

Programmatic API

import { scan, getRulesForFramework } from 'codehealth';

const { diagnostics, totalFiles } = await scan({
  targetPath: './src',
  framework: 'next',
});

for (const d of diagnostics) {
  console.log(`${d.ruleId} — ${d.message} (${d.filePath}:${d.line})`);
}

Types

interface Diagnostic {
  ruleId: string;
  severity: 'error' | 'warning';
  message: string;
  filePath: string;
  line: number;
  column: number;
  codeSnippet: string[];
  fix: string;
  suggestions: string[];
}

type Framework = 'react' | 'next' | 'react-native' | 'expo';

How It Works

1. Glob — finds all .ts/.tsx/.js/.jsx files (ignores node_modules, dist, *.test.*, etc.)
2. Parse — builds an AST using @typescript-eslint/typescript-estree with JSX support
3. Parent refs — injects node.parent on every AST node so rules can walk up the tree
4. Rules — each rule traverses the AST, finds matching patterns, and returns Diagnostic[]
5. Score — calculates a 0–100 health score weighted by severity
6. Report — prints colored output with code snippets, fix suggestions and an interactive menu