npm package: @react-state-map/core
Description: Static analysis engine for React state flow visualization — parses components, detects prop drilling, context boundaries, and state patterns (useState, Redux, Zustand)
Author: Olaf Glad
Latest version: 0.2.0

# @react-state-map/core

Core static analysis engine for [React State Map](https://github.com/olafglad/react-state-map).

Parses React codebases and builds component graphs with state flow, context boundaries, prop drilling detection, and anti-pattern analysis — all without executing code.

## Installation

```bash
npm install @react-state-map/core
```

## Usage

```typescript
import { ReactParser, serializeGraph, GraphAnalyzer } from '@react-state-map/core';

// Parse a React project
const parser = new ReactParser({
  rootDir: './src',
  drillingThreshold: 3,
  exclude: ['**/node_modules/**', '**/dist/**'],
  include: ['**/*.tsx', '**/*.jsx'],
});

const result = parser.parse();

// Serialize the graph for visualization
const graph = serializeGraph(result.graph);

// Analyze the graph
const analyzer = new GraphAnalyzer(result.graph);
const summary = analyzer.getSummary();

console.log(`Components: ${summary.components.totalComponents}`);
console.log(`State nodes: ${summary.state.totalStateNodes}`);
console.log(`Edges: ${summary.flow.totalEdges}`);
```

## Features

- **Static Analysis**: Parses React components without executing code
- **State Detection**: Finds useState, useReducer, useContext, Redux, Zustand, and custom hooks
- **Graph Building**: Constructs a complete dependency graph of state flow
- **Prop Drilling Detection**: Identifies props passed through too many layers
- **Context Boundaries**: Maps React Context provider/consumer relationships
- **Pass-Through Analysis**: Classifies components as consumer, passthrough, transformer, or mixed
- **Bundle Detection**: Identifies large object props (5+ properties) being passed through
- **Context Leak Detection**: Finds components that extract from useContext and re-pass as props
- **Rename Tracking**: Tracks props through destructuring renames across components

## What It Detects

| State Type | Detection |
|------------|-----------|
| `useState` | Variable name, initial value |
| `useReducer` | Reducer name, initial state |
| `useContext` | Context name, provider/consumer relationships |
| **Redux** | `useSelector`, `useDispatch` |
| **Zustand** | `useStore`, `useXxxStore` patterns |
| **Custom Hooks** | Any `useXxx` hook calls |

## Anti-Pattern Detection

| Detection | Description |
|-----------|-------------|
| Prop Drilling | Props passed through 3+ components without being used |
| Pass-Through Components | Components that only forward props without consuming them |
| Large Prop Bundles | Object props with 5+ properties being passed through |
| Context Leaks | useContext values extracted and re-passed as props |
| Prop Renames | Props renamed 2+ times through destructuring |

## For Most Users

If you just want to visualize your React state flow, use the CLI:

```bash
npx @react-state-map/cli ./src
```

Or install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=OlafGlad.react-state-map-vscode) for real-time visualization while you code.

## License

MIT