hermex 0.0.1-alpha.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gal Levy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# React Component Usage Analyzer
+
+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.
+
+## ✅ Status: Production Ready
+
+- ✅ **TypeScript** - Migrated to TypeScript with src/ structure
+- ✅ Functional programming architecture
+- ✅ Cross-platform support (Windows/Unix)
+- ✅ Lockfile parsing (npm, yarn, pnpm)
+- ✅ Version tracking from lockfiles
+- ✅ GitHub repository analysis
+- ✅ Multiple output formats
+- ✅ Built with **tsup** for optimized distribution
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project (TypeScript -> JavaScript)
+pnpm run build
+
+# Analyze local files
+node dist/cli.js analyze "src/**/*.tsx" -l @mui/material
+
+# Or use the npm scripts
+pnpm run test-cli
+
+# Analyze GitHub repository
+node dist/cli.js github owner/repo -l @mui/material
+
+# Generate reports with versions
+node dist/cli.js github owner/repo -l @mui/material -f both -o reports-outputs/analysis.json
+```
+
+## 🛠️ Development
+
+```bash
+# Build in watch mode
+pnpm run dev
+
+# Run tests
+pnpm test
+
+# Clean build artifacts
+pnpm run clean
+```
+
+## 📊 Key Features
+
+- **Version Tracking**: Components reported with exact package versions from lockfiles
+- **Multi-Lockfile Support**: Parses package-lock.json, yarn.lock, and pnpm-lock.yaml
+- **Pattern Detection**: Identifies 16+ React usage patterns (imports, lazy loading, HOCs, etc.)
+- **GitHub Analysis**: Clone and analyze multiple repositories
+- **Flexible Output**: Console, JSON, and table formats
+- **Complexity Scoring**: Categorizes usage patterns by complexity
+
+## 📋 Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `analyze` | Analyze local files with detailed patterns |
+| `summary` | Quick component usage overview |
+| `stats` | Detailed statistics with charts |
+| `patterns` | List all detected usage patterns |
+| `table` | Component and import tables |
+| `compare` | Compare usage across libraries |
+| `github` | Analyze GitHub repositories |
+
+## 🎯 Example Output
+
+Components are reported with exact versions:
+
+```
+🏆 TOP COMPONENTS:
+  🥇 1. Button from @mui/material@5.14.0: 45 uses
+  🥈 2. TextField from @mui/material@5.14.0: 32 uses
+  🥉 3. Grid from @mui/material@5.14.0: 28 uses
+```
+
+## 📚 Documentation
+
+- [CLI Guide](./docs/CLI_GUIDE.md) - Complete command reference
+- [GitHub Guide](./docs/GITHUB_GUIDE.md) - Repository analysis guide
+- [Usage Patterns](./docs/USAGE_PATTERNS_GUIDE.md) - Pattern detection details
+- [Demo Examples](./docs/DEMO.md) - Live examples and use cases
+- [Test Results](./docs/TEST_RESULTS.md) - Validation and testing
+
+## 🏗️ Project Structure
+
+```
+swc-parser/
+├── cli.js                  # Main CLI entry point
+├── parser.js               # SWC AST parser
+├── analyze-usage.js        # Pattern analysis
+├── github-analysis.js      # GitHub repository analysis
+├── utils/
+│   ├── formatters.js       # Output formatting
+│   ├── git-utils.js        # Git operations
+│   ├── lockfile-parser.js  # Version extraction
+│   └── file-utils.js       # File operations
+├── code-examples/          # Pattern examples (01-07)
+├── docs/                   # Documentation
+└── reports-outputs/        # Generated reports
+```
+
+## 🔧 Usage Examples
+
+### Local Analysis
+```bash
+# Basic analysis
+node cli.js analyze "src/**/*.tsx" -l @mui/material
+
+# With complexity scoring
+node cli.js analyze "src/**/*.tsx" -l @mui/material --complexity
+
+# JSON output only
+node cli.js analyze "src/**/*.tsx" -l @mui/material -f json -o report.json
+```
+
+### GitHub Analysis
+```bash
+# Single repository
+node cli.js github owner/repo -l @mui/material
+
+# Multiple repositories from config
+node cli.js github --config repos.json -l @design-system
+
+# Keep cloned repos for inspection
+node cli.js github owner/repo -l @mui/material --keep-repos
+```
+
+### Summary Commands
+```bash
+# Quick summary
+node cli.js summary "src/**/*.tsx" -l @mui/material --top 10
+
+# Statistics with charts
+node cli.js stats "src/**/*.tsx" -l @mui/material --chart
+
+# Component table
+node cli.js table "src/**/*.tsx" -l @mui/material --props --top 20
+```
+
+## 🎨 Output Formats
+
+### Console Output
+- Color-coded with emojis
+- Ranked component lists
+- Complexity distributions
+- Version information
+
+### JSON Output
+- Complete analysis data
+- Version mapping
+- Per-file breakdowns
+- Machine-readable
+
+### Table Output
+- Structured data view
+- Sortable columns
+- Props analysis
+- Import tracking
+
+## 🔍 Pattern Detection
+
+Detects 16+ usage patterns including:
+- Direct imports and JSX usage
+- Named imports with aliases
+- Namespace imports
+- Lazy loading and code splitting
+- HOC patterns
+- Dynamic imports
+- Context usage
+- Portal usage
+
+See [Usage Patterns Guide](./docs/USAGE_PATTERNS_GUIDE.md) for details.
+
+## 📦 Requirements
+
+- Node.js 14+
+- Git (for GitHub analysis)
+
+## 🤝 Contributing
+
+This is an internal tool. For bugs or feature requests, contact the team.
+
+## 📄 License
+
+Internal use only.
+
+## 🎯 Use Cases
+
+1. **Dependency Audits** - Understand library usage before migrations
+2. **Version Tracking** - Know exactly which versions are in use
+3. **Migration Planning** - Identify components that need updating
+4. **Component Analytics** - Track most-used components
+5. **Multi-Repo Analysis** - Analyze microservices/microfrontends
+6. **Code Quality** - Identify complex usage patterns
+
+## 🚀 Getting Started
+
+```bash
+# Install
+npm install
+
+# View help
+node cli.js --help
+node cli.js github --help
+
+# Try some examples (see docs/EXAMPLES.md)
+node cli.js analyze "src/**/*.tsx" -l @mui/material
+node cli.js github owner/repo -l @mui/material
+```
+
+For detailed documentation, see the [docs](./docs) folder.