Clearible

System design analysis tool for React projects. Analyze your project's architecture, folder structure, state management patterns, component coupling, and dependencies.

Features

• Folder Structure Analysis: Detects organization patterns (feature-based, component-based, domain-driven)
• State Management Detection: Identifies Redux, Zustand, Context API, Jotai, Recoil, and MobX usage
• Component Coupling Analysis: Measures component dependencies and coupling scores
• Dependency Analysis: Detects circular dependencies and import patterns
• GitHub Integration: Optional GitHub API integration for enhanced pattern analysis
• MDX Reports: Generates detailed MDX reports with recommendations

Installation

npm install -g clearible

Or use with npx:

npx clearible analyze

Usage

Basic Analysis

clearible analyze [path]

Analyzes the project at the specified path (defaults to current directory).

With GitHub API (Enhanced Analysis)

For enhanced analysis with patterns from popular GitHub repositories:

# Using environment variable
export GITHUB_TOKEN=ghp_your_token_here
clearible analyze

# Or using CLI flag
clearible analyze --github-token ghp_your_token_here

Output Options

# Specify output path
clearible analyze --output report.mdx

# Use cache for faster analysis
clearible analyze --cache

# Disable cache
clearible analyze --no-cache

Getting a GitHub Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Click "Generate new token (classic)"
3. Select scopes: public_repo (for public repositories)
4. Copy the token (starts with ghp_)
5. Use it with --github-token or set GITHUB_TOKEN environment variable

Security Best Practices

• Never commit API tokens: Add .env to .gitignore
• Use environment variables: Prefer GITHUB_TOKEN env variable over CLI flags
• Token validation: Clearible validates token format before use
• No token logging: API tokens are never logged or written to output files
• Secure storage: Tokens are only kept in memory, never written to disk

Example Output

The tool generates an MDX report with:

• Folder structure analysis and recommendations
• State management patterns and suggestions
• Component coupling scores and highly coupled components
• Circular dependency detection
• Architecture recommendations based on community best practices

Architecture Recommendations

Clearible provides recommendations based on:

• Base Patterns: Curated patterns included with the package
• GitHub Analysis: Patterns extracted from popular React repositories (if GitHub token provided)
• Community Best Practices: Consensus from React community

Project Structure

clearible/
├── src/
│   ├── cli/              # CLI interface
│   ├── analyzers/        # Analysis modules
│   ├── github/          # GitHub API integration
│   ├── knowledge/        # Knowledge base management
│   ├── reporters/       # Report generators
│   ├── security/         # API key management
│   ├── cache/           # Caching system
│   └── utils/           # Utility functions
├── knowledge/           # Base patterns JSON
└── tests/               # Test files

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT

Support

For issues and questions, please open an issue on GitHub.