@mohamed_fadl/reactlens 1.2.0-beta.4 → 1.2.0-beta.8

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.
Files changed (2) hide show
  1. package/README.md +58 -72
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,16 +1,20 @@
1
1
  # ReactLens: Advanced Architectural Analysis Engine
2
2
 
3
- ReactLens is a high-performance, deterministic tool designed for deep architectural auditing of React and Next.js applications. It leverages static AST analysis and graph theory to extract actionable intelligence from complex codebases.
3
+ [![npm version](https://img.shields.io/npm/v/@mohamed_fadl/reactlens?color=blue&style=flat-square)](https://www.npmjs.com/package/@mohamed_fadl/reactlens)
4
+ [![build](https://img.shields.io/github/actions/workflow/status/react-lens/reactlens/ci.yml?style=flat-square)](https://github.com/react-lens/reactlens/actions)
5
+ [![license](https://img.shields.io/npm/l/@mohamed_fadl/reactlens?style=flat-square)](LICENSE)
4
6
 
5
- ## System Prerequisites
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
- To use the visual graph generation features (`graph` command), you must have **Graphviz** installed on your system:
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
- - **Windows:** `winget install graphviz`
10
- - **macOS:** `brew install graphviz`
11
- - **Linux:** `sudo apt install graphviz`
12
+ ## Quick Reference (TL;DR)
12
13
 
13
- *Note: The core analysis engine (`analyze`) works without Graphviz.*
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
19
  ## Installation
16
20
 
@@ -18,87 +22,69 @@ To use the visual graph generation features (`graph` command), you must have **G
18
22
  npm install -g @mohamed_fadl/reactlens
19
23
  ```
20
24
 
21
- ## Usage & Commands
22
-
23
- ### 1. Project Analysis
24
- Analyze your project's architectural health, complexity, and dependencies.
25
+ ## Usage Examples
25
26
 
26
27
  ```bash
27
- reactlens analyze [path] [options]
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
- **Options:**
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
- ### 2. Dependency Graph
36
- Generate a visual representation of your project's module relationships.
40
+ ## System Requirements (Graphviz)
37
41
 
38
- ```bash
39
- reactlens graph [path] --output <file.svg|file.dot>
40
- ```
42
+ To use the `graph` command, you need **Graphviz (2.40+)** installed:
41
43
 
42
- ## Logical Flow and Architecture
43
-
44
- ```mermaid
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
- ## Technical Implementation & Algorithms
48
+ > [!TIP]
49
+ > **Troubleshooting:** If the `graph` command fails, verify that the Graphviz `bin` folder is in your system's `PATH`.
69
50
 
70
- ### 1. Semantic AST Traversal & Prop Drilling
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
- ### 2. Dependency Graph Theory
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
- ## Mathematical Scoring Model (Weighted)
55
+ ### `reactlens analyze [path] [options]`
56
+ Analyze architectural health, complexity, and dependencies.
82
57
 
83
- The Architectural Integrity Score ($S$) is calculated using weighted health sections:
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
- $$S = \text{round}(0.4 \cdot S_{comp} + 0.4 \cdot S_{coup} + 0.2 \cdot S_{zom})$$
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
- - **Complexity ($S_{comp}$):** Penalties for large components ($>300$ lines), high prop counts, and detected prop drilling.
88
- - **Coupling ($S_{coup}$):** Penalties for circular dependencies (15% per cycle).
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
- ## Strategic Roadmap
73
+ ---
92
74
 
93
- - **v1.0 - v1.2: Advanced Intelligence (Current)**
94
- AST Analysis, Weighted Scoring, Prop Drilling Detection, JSON Stdout, and Dedicated Graph CLI.
95
- - **v1.5: HTML Interactive Dashboard**
96
- Visual exploration of the architecture with real-time filtering.
97
- - **v1.8: Direct Refactoring AI Integration**
98
- Automated code transformation suggestions.
99
- - **v2.0: Multi-Framework Meta-Analysis**
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
- Technical Reference - ReactLens Engineering Team.
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.*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mohamed_fadl/reactlens",
3
- "version": "1.2.0-beta.4",
3
+ "version": "1.2.0-beta.8",
4
4
  "description": "Intelligent architectural analysis tool for React and Next.js applications.",
5
5
  "main": "./dist/cli/index.js",
6
6
  "bin": {