hermex 1.0.0 → 1.1.0

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 (4) hide show
  1. package/README.md +141 -145
  2. package/dist/cli.js +487 -253
  3. package/dist/cli.js.map +1 -1
  4. package/package.json +7 -10
package/README.md CHANGED
@@ -1,201 +1,197 @@
1
- # React Component Usage Analyzer
1
+ # Hermex
2
2
 
3
3
  A powerful SWC-based tool for analyzing React component usage patterns across codebases. Understand how UI library components are used, track dependencies with exact versions, and generate comprehensive reports.
4
4
 
5
- ## ✅ Status: Production Ready
6
-
7
- - ✅ **TypeScript** - Migrated to TypeScript with src/ structure
8
- - ✅ Functional programming architecture
9
- - ✅ Cross-platform support (Windows/Unix)
10
- - ✅ Lockfile parsing (npm, yarn, pnpm)
11
- - ✅ Version tracking from lockfiles
12
- - ✅ GitHub repository analysis
13
- - ✅ Multiple output formats
14
- - ✅ Built with **tsup** for optimized distribution
5
+ Made with AI 🤖
15
6
 
16
7
  ## 🚀 Quick Start
17
8
 
18
9
  ```bash
19
- # Install dependencies
20
- pnpm install
21
-
22
- # Build the project (TypeScript -> JavaScript)
23
- pnpm run build
24
-
25
- # Analyze local files
26
- node dist/cli.js analyze "src/**/*.tsx" -l @mui/material
10
+ # No installation required - use npx
11
+ npx hermex scan "src/**/*.tsx"
27
12
 
28
- # Or use the npm scripts
29
- pnpm run test-cli
13
+ # Or install globally
14
+ npm install -g hermex
15
+ hermex scan "src/**/*.tsx"
30
16
 
31
- # Analyze GitHub repository
32
- node dist/cli.js github owner/repo -l @mui/material
33
-
34
- # Generate reports with versions
35
- node dist/cli.js github owner/repo -l @mui/material -f both -o reports-outputs/analysis.json
17
+ # Or install locally
18
+ npm install hermex
19
+ npx hermex scan "src/**/*.tsx"
36
20
  ```
37
21
 
38
- ## 🛠️ Development
39
-
40
- ```bash
41
- # Build in watch mode
42
- pnpm run dev
43
-
44
- # Run tests
45
- pnpm test
46
-
47
- # Clean build artifacts
48
- pnpm run clean
49
- ```
22
+ ## 📦 Requirements
23
+ - Node.js 24+
50
24
 
51
25
  ## 📊 Key Features
52
26
 
27
+ - **Fast SWC-based Parsing**: Lightning-fast static analysis using SWC's Rust-based parser
28
+ - **Pattern Detection**: Identifies 16+ React usage patterns including:
29
+ - Direct imports and JSX usage
30
+ - Variable assignments and destructuring
31
+ - Conditional usage and object mappings
32
+ - Lazy loading and dynamic imports
33
+ - HOC wrapping and memoization
34
+ - Portal usage and context integration
53
35
  - **Version Tracking**: Components reported with exact package versions from lockfiles
54
36
  - **Multi-Lockfile Support**: Parses package-lock.json, yarn.lock, and pnpm-lock.yaml
55
- - **Pattern Detection**: Identifies 16+ React usage patterns (imports, lazy loading, HOCs, etc.)
56
- - **GitHub Analysis**: Clone and analyze multiple repositories
57
- - **Flexible Output**: Console, JSON, and table formats
37
+ - **Flexible Output**: Console, table, and chart formats
58
38
  - **Complexity Scoring**: Categorizes usage patterns by complexity
39
+ - **Zero Configuration**: Works out of the box with sensible defaults
59
40
 
60
- ## 📋 Available Commands
61
-
62
- | Command | Description |
63
- |---------|-------------|
64
- | `analyze` | Analyze local files with detailed patterns |
65
- | ` ` | Quick component usage overview |
66
- | `stats` | Detailed statistics with charts |
67
- | `patterns` | List all detected usage patterns |
68
- | `table` | Component and import tables |
69
- | `compare` | Compare usage across libraries |
70
- | `github` | Analyze GitHub repositories |
41
+ ## 📋 Commands
71
42
 
72
- ## 🎯 Example Output
43
+ ### `scan` Command
73
44
 
74
- Components are reported with exact versions:
45
+ Scan and analyze local files for React component usage patterns.
75
46
 
76
- ```
77
- 🏆 TOP COMPONENTS:
78
- 🥇 1. Button from @mui/material@5.14.0: 45 uses
79
- 🥈 2. TextField from @mui/material@5.14.0: 32 uses
80
- 🥉 3. Grid from @mui/material@5.14.0: 28 uses
47
+ ```bash
48
+ hermex scan [pattern] [options]
81
49
  ```
82
50
 
83
- ## 📚 Documentation
51
+ #### Arguments
84
52
 
85
- - [CLI Guide](./docs/CLI_GUIDE.md) - Complete command reference
86
- - [GitHub Guide](./docs/GITHUB_GUIDE.md) - Repository analysis guide
87
- - [Usage Patterns](./docs/USAGE_PATTERNS_GUIDE.md) - Pattern detection details
88
- - [Demo Examples](./docs/DEMO.md) - Live examples and use cases
89
- - [Test Results](./docs/TEST_RESULTS.md) - Validation and testing
53
+ | Argument | Description | Default |
54
+ |----------|-------------|---------|
55
+ | `[pattern]` | Glob pattern for files to analyze | `**/*.{tsx,jsx,ts,js}` |
90
56
 
91
- ## 🏗️ Project Structure
57
+ #### Options
92
58
 
93
- ```
94
- swc-parser/
95
- ├── cli.js # Main CLI entry point
96
- ├── parser.js # SWC AST parser
97
- ├── analyze-usage.js # Pattern analysis
98
- ├── github-analysis.js # GitHub repository analysis
99
- ├── utils/
100
- │ ├── formatters.js # Output formatting
101
- │ ├── git-utils.js # Git operations
102
- │ ├── lockfile-parser.js # Version extraction
103
- │ └── file-utils.js # File operations
104
- ├── code-examples/ # Pattern examples (01-07)
105
- ├── docs/ # Documentation
106
- └── reports-outputs/ # Generated reports
107
- ```
59
+ | Option | Description | Values | Default |
60
+ |--------|-------------|--------|---------|
61
+ | `--ignore <pattern>` | Glob pattern for files to ignore | Any glob pattern | `**/node_modules/**`, `**/dist/**`, `**/build/**` |
62
+ | `--verbose` | Show detailed file-by-file analysis | `true`/`false` | `false` |
63
+ | `--summary [mode]` | Show summary statistics | `log`, `false` | `log` |
64
+ | `--details` | Show detailed pattern counts | `true`/`false` | `false` |
65
+ | `--top-components [mode]` | Show top components | `log`, `table`, `chart` | `log` |
66
+ | `--components-usage [mode]` | Show components usage table/chart | `table`, `chart` | `table` |
67
+ | `--patterns [mode]` | Show patterns table/chart | `table`, `chart` | `table` |
108
68
 
109
- ## 🔧 Usage Examples
69
+ #### Examples
110
70
 
111
- ### Local Analysis
112
71
  ```bash
113
- # Basic analysis
114
- node cli.js analyze "src/**/*.tsx" -l @mui/material
72
+ # Basic scan with defaults
73
+ hermex scan
115
74
 
116
- # With complexity scoring
117
- node cli.js analyze "src/**/*.tsx" -l @mui/material --complexity
75
+ # Scan specific directory
76
+ hermex scan "src/**/*.tsx"
118
77
 
119
- # JSON output only
120
- node cli.js analyze "src/**/*.tsx" -l @mui/material -f json -o report.json
121
- ```
78
+ # Verbose output
79
+ hermex scan "src/**/*.tsx" --verbose
122
80
 
123
- ### GitHub Analysis
124
- ```bash
125
- # Single repository
126
- node cli.js github owner/repo -l @mui/material
81
+ # Show only summary and top components
82
+ hermex scan "src/**/*.tsx" --components-usage false --patterns false
127
83
 
128
- # Multiple repositories from config
129
- node cli.js github --config repos.json -l @design-system
84
+ # Chart visualization
85
+ hermex scan "src/**/*.tsx" --top-components chart --components-usage chart
130
86
 
131
- # Keep cloned repos for inspection
132
- node cli.js github owner/repo -l @mui/material --keep-repos
87
+ # Detailed analysis
88
+ hermex scan "src/**/*.tsx" --details --verbose
133
89
  ```
134
90
 
135
- ### Summary Commands
136
- ```bash
137
- # Quick summary
138
- node cli.js summary "src/**/*.tsx" -l @mui/material --top 10
91
+ ## 🎯 Example Output
139
92
 
140
- # Statistics with charts
141
- node cli.js stats "src/**/*.tsx" -l @mui/material --chart
93
+ ### Summary Statistics
94
+ ```
95
+ [SUMMARY] Analysis completed successfully in 0.1s
96
+ [SUMMARY] Files analyzed: 42
97
+ [SUMMARY] Total imports: 156
98
+ [SUMMARY] Total components: 38
99
+ ```
142
100
 
143
- # Component table
144
- node cli.js table "src/**/*.tsx" -l @mui/material --props --top 20
101
+ ### Top Components
145
102
  ```
103
+ 🏆 Top Components
146
104
 
147
- ## 🎨 Output Formats
105
+ [TOP-COMPONENTS] 🥇 1. Button from @design-system/button: 45 uses
106
+ [TOP-COMPONENTS] 🥈 2. Card from @design-system/card: 32 uses
107
+ [TOP-COMPONENTS] 🥉 3. Input from @design-system/input: 28 uses
108
+ ```
148
109
 
149
- ### Console Output
150
- - Color-coded with emojis
151
- - Ranked component lists
152
- - Complexity distributions
153
- - Version information
110
+ ### Components Usage Table
111
+ ```
112
+ ⚛️ Components Usage
113
+
114
+ ┌────────────┬──────────────────────────┬─────────┬───────┐
115
+ │ Component │ Source │ Version │ Count │
116
+ ├────────────┼──────────────────────────┼─────────┼───────┤
117
+ │ Button │ @design-system/button │ 2.1.5 │ 45 │
118
+ │ Card │ @design-system/card │ 1.8.3 │ 32 │
119
+ │ Input │ @design-system/input │ 2.0.1 │ 28 │
120
+ └────────────┴──────────────────────────┴─────────┴───────┘
121
+ ```
154
122
 
155
- ### JSON Output
156
- - Complete analysis data
157
- - Version mapping
158
- - Per-file breakdowns
159
- - Machine-readable
123
+ ### Code Patterns
124
+ ```
125
+ 🔍 Code Patterns
126
+
127
+ ┌──────────────────────┬───────┐
128
+ │ Pattern │ Count │
129
+ ├──────────────────────┼───────┤
130
+ │ JSX Usage │ 145 │
131
+ │ Named Imports │ 89 │
132
+ │ Default Imports │ 67 │
133
+ │ Variable Assignments │ 23 │
134
+ │ Object Mappings │ 15 │
135
+ │ Conditional Usage │ 12 │
136
+ │ Lazy Loading │ 8 │
137
+ └──────────────────────┴───────┘
138
+ ```
160
139
 
161
- ### Table Output
162
- - Structured data view
163
- - Sortable columns
164
- - Props analysis
165
- - Import tracking
140
+ ## 📚 Documentation
166
141
 
167
- ## 🔍 Pattern Detection
142
+ - **[Examples](./docs/EXAMPLES.md)** - Comprehensive examples and command usage
143
+ - **[Patterns Guide](./docs/PATTERNS.md)** - All detectable React usage patterns
144
+ - **[Project Milestones](./docs/MILESTONES.md)** - Roadmap and future features
168
145
 
169
- Detects 16+ usage patterns including:
170
- - Direct imports and JSX usage
171
- - Named imports with aliases
172
- - Namespace imports
173
- - Lazy loading and code splitting
174
- - HOC patterns
175
- - Dynamic imports
176
- - Context usage
177
- - Portal usage
146
+ ## 🎯 Use Cases
178
147
 
179
- See [Usage Patterns Guide](./docs/USAGE_PATTERNS_GUIDE.md) for details.
148
+ 1. **Dependency Audits** - Understand library usage before migrations
149
+ 2. **Version Tracking** - Know exactly which component versions are in use
150
+ 3. **Migration Planning** - Identify components that need updating when migrating UI libraries
151
+ 4. **Component Analytics** - Track most-used components and usage patterns
152
+ 5. **Code Quality** - Identify complex usage patterns that may need refactoring
153
+ 6. **Team Insights** - Understand how your team uses component libraries
154
+ 7. **Documentation** - Generate usage reports for component library documentation
180
155
 
181
- ## 📦 Requirements
156
+ ## 🔍 Pattern Detection
182
157
 
183
- - Node.js 24+
184
- - Git (for GitHub analysis)
158
+ Hermex detects 16+ React component usage patterns with varying complexity levels:
159
+
160
+ | Pattern | Complexity | Examples |
161
+ |---------|------------|----------|
162
+ | Direct Import & Usage | 1/10 | `import Button from '@lib/button'` |
163
+ | Named Import with Alias | 2/10 | `import { Button as Btn } from '@lib'` |
164
+ | Variable Assignment | 3/10 | `const MyButton = Button` |
165
+ | Destructuring Usage | 4/10 | `const { Button } = Foundation` |
166
+ | Object Mapping | 5/10 | `const map = { btn: Button }` |
167
+ | Lazy Loading | 6/10 | `lazy(() => import('@lib/button'))` |
168
+ | Dynamic Import | 7/10 | `await import('@lib/button')` |
169
+ | HOC Wrapping | 7/10 | `withWrapper(Button)` |
170
+ | Context Integration | 7/10 | `useContext(ComponentContext)` |
171
+ | Portal Usage | 8/10 | `createPortal(<Button />)` |
172
+
173
+ See the [Patterns Guide](./docs/PATTERNS.md) for complete details.
174
+
175
+ ## 🛠️ Tech Stack
176
+ - **Runtime**: Node.js 24
177
+ - **Parser**: [@swc/core](https://swc.rs/)
178
+ - **CLI**: [Commander.js](https://github.com/tj/commander.js)
179
+ - **Build**: [tsup](https://tsup.egoist.dev/)
180
+ - **Language**: [TypeScript](https://www.typescriptlang.org/)
181
+ - **Formatter**: [Biome](https://biomejs.dev/)
182
+ - **Linter**: [oxlint](https://oxc-project.github.io/)
183
+ - **Tests**: [Vitest](https://vitest.dev/)
185
184
 
186
185
  ## 🤝 Contributing
187
186
 
188
- [Contributing](Contributing.md)
187
+ Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details.
189
188
 
190
189
  ## 📄 License
191
190
 
192
- [MIT License](License.md)
191
+ MIT License - see [LICENSE.md](./LICENSE.md)
193
192
 
194
- ## 🎯 Use Cases
193
+ ## 🔗 Links
195
194
 
196
- 1. **Dependency Audits** - Understand library usage before migrations
197
- 2. **Version Tracking** - Know exactly which versions are in use
198
- 3. **Migration Planning** - Identify components that need updating
199
- 4. **Component Analytics** - Track most-used components
200
- 5. **Multi-Repo Analysis** - Analyze microservices/microfrontends
201
- 6. **Code Quality** - Identify complex usage patterns
195
+ - [GitHub Repository](https://github.com/Gallevy/hermex)
196
+ - [npm Package](https://www.npmjs.com/package/hermex)
197
+ - [Report Issues](https://github.com/Gallevy/hermex/issues)