@mohamed_fadl/reactlens 1.2.0-beta.2 → 1.2.0-beta.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -74
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,104 +1,90 @@
|
|
|
1
1
|
# ReactLens: Advanced Architectural Analysis Engine
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@mohamed_fadl/reactlens)
|
|
4
|
+
[](https://github.com/react-lens/reactlens/actions)
|
|
5
|
+
[](LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
> [!WARNING]
|
|
8
|
+
> **Beta Version:** This tool is currently in beta. Features are subject to change, and we are continuously refining our analysis algorithms.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
ReactLens is a high-performance tool designed for deep architectural auditing of React and Next.js applications. It uses static AST analysis to give you a clear "X-ray" view of your project's health.
|
|
8
11
|
|
|
9
|
-
|
|
10
|
-
- **macOS:** `brew install graphviz`
|
|
11
|
-
- **Linux:** `sudo apt install graphviz`
|
|
12
|
+
## 🚀 Quick Reference (TL;DR)
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
| Command | Description | Example |
|
|
15
|
+
| :--- | :--- | :--- |
|
|
16
|
+
| `analyze` | Full architectural health audit | `reactlens analyze ./src` |
|
|
17
|
+
| `graph` | Visual dependency graph (SVG/PNG) | `reactlens graph ./src --output architecture.svg` |
|
|
14
18
|
|
|
15
|
-
## Installation
|
|
19
|
+
## 📦 Installation
|
|
16
20
|
|
|
17
21
|
```bash
|
|
18
|
-
npm install -g
|
|
22
|
+
npm install -g @mohamed_fadl/reactlens
|
|
19
23
|
```
|
|
20
24
|
|
|
21
|
-
## Usage
|
|
22
|
-
|
|
23
|
-
### 1. Project Analysis
|
|
24
|
-
Analyze your project's architectural health, complexity, and dependencies.
|
|
25
|
+
## 🛠️ Usage Examples
|
|
25
26
|
|
|
26
27
|
```bash
|
|
27
|
-
|
|
28
|
+
# Basic health check
|
|
29
|
+
reactlens analyze
|
|
30
|
+
|
|
31
|
+
# Enforce quality standards (fails if score < 80)
|
|
32
|
+
reactlens analyze ./src --fail-under 80
|
|
33
|
+
|
|
34
|
+
# Export for CI/CD integration
|
|
35
|
+
reactlens analyze --json report.json --silent
|
|
28
36
|
```
|
|
29
37
|
|
|
30
|
-
|
|
31
|
-
- `-j, --json [file]` : Output report in JSON format. If no file is provided, it prints to stdout.
|
|
32
|
-
- `-s, --silent` : Suppress the visual terminal report (ideal for piping JSON).
|
|
33
|
-
- `--fail-under <score>` : Exit with code 1 if the Architectural Score is below the threshold.
|
|
38
|
+
---
|
|
34
39
|
|
|
35
|
-
|
|
36
|
-
Generate a visual representation of your project's module relationships.
|
|
40
|
+
## 🔧 System Requirements (Graphviz)
|
|
37
41
|
|
|
38
|
-
|
|
39
|
-
react-lens graph [path] --output <file.svg|file.dot>
|
|
40
|
-
```
|
|
42
|
+
To use the `graph` command, you need **Graphviz (2.40+)** installed:
|
|
41
43
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
graph TD
|
|
46
|
-
A[Project Root] --> B[FileScanner]
|
|
47
|
-
B --> C{Framework Detection}
|
|
48
|
-
C -->|Next.js| D[App Router Analysis]
|
|
49
|
-
C -->|React/Vite| E[Basic Component Analysis]
|
|
50
|
-
C -->|Node CLI| F[CLI Tool Analysis]
|
|
51
|
-
|
|
52
|
-
B --> G[Babel AST Parser]
|
|
53
|
-
G --> H[ComponentAnalyzer]
|
|
54
|
-
H --> I[Extraction: Props/Hooks/Client-Directives]
|
|
55
|
-
H --> J[Prop Drilling Detection]
|
|
56
|
-
|
|
57
|
-
B --> K[Madge Dependency Engine]
|
|
58
|
-
K --> L[Graph Theory Resolution]
|
|
59
|
-
L --> M[Cycle & Zombie Detection]
|
|
60
|
-
|
|
61
|
-
I --> N[Insight Engine]
|
|
62
|
-
J --> N
|
|
63
|
-
M --> N
|
|
64
|
-
N --> O[Mathematical Scoring Model]
|
|
65
|
-
O --> P[Terminal/JSON/Silent Reporting]
|
|
66
|
-
```
|
|
44
|
+
- **Windows:** `winget install graphviz`
|
|
45
|
+
- **macOS:** `brew install graphviz`
|
|
46
|
+
- **Linux:** `sudo apt install graphviz`
|
|
67
47
|
|
|
68
|
-
|
|
48
|
+
> [!TIP]
|
|
49
|
+
> **Troubleshooting:** If the `graph` command fails, verify that the Graphviz `bin` folder is in your system's `PATH`.
|
|
69
50
|
|
|
70
|
-
|
|
71
|
-
ReactLens utilizes the `@babel/parser` for Abstract Syntax Tree (AST) generation. The `ComponentAnalyzer` implements:
|
|
72
|
-
- **Functional Components:** Identified via function signatures returning JSX.
|
|
73
|
-
- **Prop Drilling Heuristic:** Detects properties passed down to children without local usage within the component body.
|
|
74
|
-
- **Hook Signatures:** Detected through the `use` prefix heuristic.
|
|
51
|
+
---
|
|
75
52
|
|
|
76
|
-
|
|
77
|
-
The `DependencyAnalyzer` constructs a Directed Acyclic Graph (DAG) using **Madge**.
|
|
78
|
-
- **Cycle Detection:** Utilizes DFS to identify circular imports.
|
|
79
|
-
- **Zombie Analysis:** Identifies "Zombie Components" (unreachable nodes) by excluding test files and entry points.
|
|
53
|
+
## 📊 Detailed Commands
|
|
80
54
|
|
|
81
|
-
|
|
55
|
+
### `reactlens analyze [path] [options]`
|
|
56
|
+
Analyze architectural health, complexity, and dependencies.
|
|
82
57
|
|
|
83
|
-
|
|
58
|
+
**Options:**
|
|
59
|
+
- `-j, --json [file]` : Output report in JSON format.
|
|
60
|
+
- `-s, --silent` : Suppress visual terminal report.
|
|
61
|
+
- `--fail-under <score>` : Exit with error if score is below the limit.
|
|
84
62
|
|
|
85
|
-
|
|
63
|
+
### 🧩 JSON Structure
|
|
64
|
+
When using `--json`, the output follows this schema:
|
|
65
|
+
- `summary`: High-level counts (Modules, Components).
|
|
66
|
+
- `metrics`: Scores for Complexity, Coupling, and Zombies.
|
|
67
|
+
- `insights`: Detailed findings and refactoring recommendations.
|
|
68
|
+
- `score`: The final architectural integrity percentage.
|
|
86
69
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
- **Zombies ($S_{zom}$):** Penalties for unused modules (2% per instance).
|
|
70
|
+
### `reactlens graph [path] --output <file>`
|
|
71
|
+
Visualize module relationships. Supports `.svg`, `.png`, and `.dot` formats.
|
|
90
72
|
|
|
91
|
-
|
|
73
|
+
---
|
|
92
74
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
Unified quality standards for Vue, Svelte, and Angular.
|
|
75
|
+
## 🧠 Understanding the Score
|
|
76
|
+
|
|
77
|
+
We calculate project health based on three pillars:
|
|
78
|
+
|
|
79
|
+
1. **Complexity (40%)**: Analysis of component size and prop health.
|
|
80
|
+
2. **Coupling (40%)**: Detection of circular dependencies.
|
|
81
|
+
3. **Zombies (20%)**: Identification of unreachable/unused modules.
|
|
101
82
|
|
|
102
83
|
---
|
|
103
84
|
|
|
104
|
-
|
|
85
|
+
## 📖 Deep Dive
|
|
86
|
+
|
|
87
|
+
For technical details on algorithms and scoring, visit the [Engineering Reference](ENGINEERING.md).
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
*Maintained by the ReactLens Engineering Team.*
|