railsforge 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ca67789d645855334565249db474d63bfde8607e031642c52a287924c55b9cf
-  data.tar.gz: 9517139f8e3224a17ebd875c6606a2ea244e183e289acc1599181eed13522f07
+  metadata.gz: 2c8f6efda41c0957fd4a4675fbd5e310fb825c2a26001c4e5af5abb02af97347
+  data.tar.gz: 91f9e9baf1d073a0bbe8cd7db41972504183281bc27945aaee77185f02229718
 SHA512:
-  metadata.gz: db1e954e6df040c1856be4cee40357e781201d29a550f31c1dc8924d4c3e93678daecefa42c8e651d02ddef5dc04d4ebd702cb37cac2a0731111ddf0a6e03d13
-  data.tar.gz: d7f692d25425099a0ea48499655272a70cf77f517cbfdadbe54826c517aa9e989833774feca6fb7742d36e5aa8bdc47c5c9d9760b8a0130009716ea74298e6c6
+  metadata.gz: bb84ad0cbdbdd3b154c3e4b4dbeb6acbe909f5d67fa8511b2002dccd18756436531e33d508e247335a5ed2603fc5b6654b84136cc2c73d1e75bd3308e797e6f4
+  data.tar.gz: 2705a473ed8ae7323f5800c75e7a5ecb0a077ff07beef6707e830c409d24737a02ce2310241b421127f2ff9cb64bbd583096599a2291c6762246c2077f29bfaf

data/README.md

@@ -12,513 +12,174 @@
   </a>
 </p>
 
-RailsForge is a comprehensive command-line tool for automatically generating essential Rails application components, including monitoring configurations, DevOps setups, and security/performance analyzers.
+**Rails application health diagnostics.** Scans your codebase, surfaces structural issues, and tells you exactly what to fix.
 
-## Project Overview
-
-RailsForge streamlines Rails development by providing automated generators and analyzers for common tasks:
-
-- **Monitoring Configuration** - Sentry error tracking and Lograge structured logging
-- **DevOps Setup** - Docker containerization and CI/CD pipeline configuration
-- **Security Analysis** - Automated vulnerability detection
-- **Performance Analysis** - Performance optimization recommendations
-- **Code Generation** - Services, queries, jobs, and more with template versioning
-
-### Key Features
-
-- 🔧 **Automated Generators** - Generate services, queries, jobs, components with a single command
-- 📊 **Code Analyzers** - Security, performance, and architectural analysis
-- 🐳 **DevOps Ready** - Docker and CI/CD configuration out of the box
-- 📈 **Monitoring** - Sentry and Lograge integration
-- 🎨 **Template System** - v1, v2, and v3 template versions with advanced patterns
-- 🧩 **Plugin System** - Extensible architecture for custom functionality
-- ⚙️ **Configuration** - Customizable via `.railsforgerc` YAML file
-
-## Installation
-
-### Requirements
-
-- **Ruby** version 3.0 or higher
-- **Bundler** for gem management
-
-### Setup Steps
-
-#### Option 1: Install from RubyGems (Recommended)
-
-```bash
-# Install the gem
-gem install railsforge
-
-# Verify installation
-railsforge --version
-```
-
-#### Option 2: Install from Source
-
-```bash
-# Clone the repository
-git clone https://github.com/mfifth/railsforge.git
-cd railsforge
-
-# Install dependencies
-bundle install
-
-# Make the binary executable
-chmod +x bin/railsforge
-
-# Run locally
-./bin/railsforge --version
-```
-
-#### Option 3: Add to Gemfile
-
-```ruby
-# Add to your Rails project's Gemfile
-group :development do
-  gem 'railsforge', require: false
-end
-```
-
-Then run:
-
-```bash
-bundle install
-```
-
-## Usage Documentation
-
-### Getting Help
-
-```bash
-railsforge --help
-railsforge --version
-```
-
-### Generate Commands
+---
 
-#### Monitoring Configuration
+## The Problem
 
-Add Sentry error tracking and Lograge structured logging to your Rails application:
+Rails apps accumulate structural debt invisibly. Fat controllers, missing indexes, unguarded SQL, no specs for business-critical services — none of it surfaces until something breaks in production. By then the cost is high and the cause is buried.
 
-```bash
-railsforge generate monitoring
-railsforge generate monitoring --sentry_dsn=your_dsn_here
-railsforge generate monitoring --environment=production
-```
+Most teams only discover these problems during an audit, a security review, or an incident.
 
-This creates:
-- `config/initializers/sentry.rb` - Sentry configuration
-- `config/initializers/lograge.rb` - Lograge setup
-- Updates environment configurations
-
-#### DevOps Configuration
+---
 
-Generate Docker and CI/CD pipeline configurations:
+## The Primary Command
 
 ```bash
-railsforge generate devops
-railsforge generate devops --docker
-railsforge generate devops --ci=github
-railsforge generate devops --ci=gitlab
+railsforge doctor
 ```
 
-This creates:
-- `Dockerfile` - Container definition
-- `docker-compose.yml` - Multi-service setup
-- `.github/workflows/ci.yml` - GitHub Actions CI/CD
-- `.gitlab-ci.yml` - GitLab CI configuration
-- `config/kubernetes/` - Kubernetes manifests
-- `bin/deploy` - Deployment script
-
-#### Demo Project
-
-Create a sample Rails project for learning or prototyping:
+Runs a full diagnostic scan across your Rails app. Returns a health score and every detected issue, ranked by severity, with a concrete fix for each one.
 
-```bash
-railsforge generate demo my_demo
-railsforge generate demo my_demo --type=blog
-railsforge generate demo my_api --type=api
-```
-
-#### Test Files
+---
 
-Generate comprehensive test files:
+## Example Output
 
-```bash
-railsforge generate test User
-railsforge generate test PostsController --type=controller
-railsforge generate test UserService --type=service
-railsforge generate test SendEmailJob --type=job
 ```
+RailsForge Health Report
+─────────────────────────────��────────────────────
+Score:  61/100
+Issues: 9 total
 
-#### Standard Generators
-
-Generate Rails components with template versioning:
-
-```bash
-# Service objects
-railsforge generate service user_creator
-railsforge generate service user_creator --template=v2
-railsforge generate service user_creator --template=v3
-
-# Query objects  
-railsforge generate query active_users
-railsforge generate query posts --template=v2
-
-# Jobs
-railsforge generate job send_email
-railsforge generate job process_data --template=v3
-
-# Form objects
-railsforge generate form contact_form
+HIGH (2)
+  [security]
+    app/controllers/users_controller.rb:42 — SQL Injection: User.where("name = '#{params[:name]}'")
+    → Use parameterized queries: Model.where(column: value)
 
-# Presenters
-railsforge generate presenter user_presenter
+  [performance]
+    app/controllers/posts_controller.rb:18 — N+1 Query: @posts.each do |post| post.comments.find
+    → Use eager loading: includes(:association) or preload(:association)
 
-# Policies
-railsforge generate policy post_policy
+MEDIUM (4)
+  [controller]
+    app/controllers/admin_controller.rb — AdminController has 214 lines (max 150)
+    → Extract business logic to Service objects
 
-# Serializers
-railsforge generate serializer post_serializer
+  [database]
+    db/schema.rb — Table `events` has datetime columns without an index
+    → add_index :events, :created_at
 
-# View Components
-railsforge generate component button
-railsforge generate component modal --template=v2
+  [refactor]
+    app/models/user.rb — User has 267 lines (max 200)
+    → Consider extracting concerns or service objects
 
-# Stimulus Controllers
-railsforge generate stimulus dropdown
+    app/models/order.rb — Method `process_payment` has 43 lines
+    → Consider extracting to a private method or service
 
-# Mailers
-railsforge generate mailer user_mailer
+LOW (3)
+  [spec]
+    app/service/invoice_generator.rb — Service `invoice_generator` has no spec
+    → Create spec/services/invoice_generator_spec.rb
 
-# Features
-railsforge generate feature user_signup
+    app/service/payment_processor.rb — Service `payment_processor` has no spec
+    → Create spec/services/payment_processor_spec.rb
 
-# API Resources
-railsforge generate api posts
+  [controller]
+    app/controllers/api/v1/orders_controller.rb — OrdersController has 13 methods (max 10)
+    → Consider splitting into focused controllers
 ```
 
-### Analyze Commands
-
-#### Security Analysis
+---
 
-Run security vulnerability checks on your codebase:
+## JSON Mode
 
 ```bash
-railsforge analyze security
-railsforge analyze security --verbose
+railsforge doctor --format=json
 ```
 
-Checks for:
-- SQL injection vulnerabilities
-- Cross-site scripting (XSS) risks
-- Authentication/authorization issues
-- Insecure configuration patterns
-- Sensitive data exposure
-
-#### Performance Analysis
+Returns structured output for CI pipelines and automated tooling:
 
-Identify performance optimization opportunities:
-
-```bash
-railsforge analyze performance
-railsforge analyze performance --verbose
+```json
+{
+  "score": 61,
+  "issues": [
+    {
+      "analyzer": "security",
+      "type": "sql_injection",
+      "severity": "high",
+      "file": "app/controllers/users_controller.rb",
+      "line": 42,
+      "message": "SQL Injection: User.where(\"name = '#{params[:name]}'\")",
+      "suggestion": "Use parameterized queries: Model.where(column: value)"
+    }
+  ],
+  "summary": {
+    "total": 9,
+    "by_severity": {
+      "high": 2,
+      "medium": 4,
+      "low": 3
+    }
+  }
+}
 ```
 
-Checks for:
-- N+1 query patterns
-- Missing database indexes
-- Inefficient queries
-- Memory leak patterns
-- Unoptimized asset loading
-
-#### Other Analyzers
+**Fail a CI build when score drops below threshold:**
 
 ```bash
-# Analyze controllers
-railsforge analyze controllers
-railsforge analyze c
-
-# Analyze models
-railsforge analyze models
-railsforge analyze m
-
-# Analyze specs
-railsforge analyze specs
-railsforge analyze spec
-
-# Analyze database
-railsforge analyze db
-railsforge analyze database
-
-# Analyze metrics
-railsforge analyze metrics
-
-# Run all analyzers
-railsforge analyze all
-railsforge analyze full
+score=$(railsforge doctor --format=json | jq '.score')
+[ "$score" -ge 70 ] || exit 1
 ```
 
-### Other Commands
-
-#### Doctor - Health Check
-
-Comprehensive project health report:
-
-```bash
-railsforge doctor
-```
-
-Combines all analyzers and calculates an architecture score (0-100).
-
-#### Dependency Graph
-
-Generate a Graphviz diagram of your Rails architecture:
-
-```bash
-railsforge graph
-```
-
-Outputs `.dot` and `.svg` files to `tmp/railsforge/`.
-
-#### Wizard - Interactive Setup
-
-Interactive project configuration:
-
-```bash
-railsforge wizard
-railsforge wizard --profile=blog
-```
+---
 
-#### Plugin Management
+## What RailsForge Detects
 
-```bash
-# List available plugins
-railsforge plugins list
+- **Security** — SQL injection, XSS, weak cryptography, sensitive data exposure
+- **Performance** — N+1 queries, missing database indexes, inefficient query patterns
+- **Architecture** — Fat controllers, fat models, methods that exceed complexity thresholds
+- **Test coverage** — Service objects, queries, jobs, policies with no corresponding spec
+- **Refactoring opportunities** — Long methods, oversized files
 
-# Load a specific plugin
-railsforge plugins load my_plugin
-```
+---
 
-#### Configuration
+## What RailsForge Is Not
 
-```bash
-# View current configuration
-railsforge config
+RailsForge is not a generator, scaffolding system, or DevOps platform.
 
-# Set configuration values
-railsforge config set default_template v2
-railsforge config set analyzer_threshold 10
-```
+It does not create architecture. It diagnoses existing architecture.
 
-#### Profiles
+---
 
-List available project profiles:
+## Installation
 
 ```bash
-railsforge profiles
-```
-
-Available profiles: blog, admin_app, api_only, standard
-
-## Configuration Options
-
-### .railsforgerc
-
-Create a `.railsforgerc` file in your project root to customize RailsForge behavior:
-
-```yaml
-# .railsforgerc
-default_template: v2
-analyzer_threshold: 10
-
-# Generator settings
-generators:
-  with_specs: true
-  template_version: v2
-
-# Analyzer settings  
-security:
-  strict_mode: true
-performance:
-  check_n_plus_queries: true
-```
-
-### Available Flags
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--sentry_dsn` | Sentry DSN for error tracking | - |
-| `--environment` | Rails environment | development |
-| `--template` | Template version (v1, v2, v3) | v1 |
-| `--dry-run` | Preview changes without executing | false |
-| `--no-spec` | Generate without spec files | false |
-
-## Template System
-
-RailsForge supports multiple template versions for each component:
-
-### v1 - Standard Templates
-
-Basic templates suitable for simple applications:
-
-```ruby
-class UserCreator
-  def initialize(params)
-    @params = params
-  end
-
-  def call
-    # Basic implementation
-  end
-end
-```
-
-### v2 - Enhanced Templates
-
-Enhanced templates with additional features:
-
-```ruby
-class UserCreator < BaseService
-  option :name
-  
-  def call
-    # Enhanced with Dry::Schema validation
-  end
-end
+gem install railsforge
 ```
 
-### v3 - Advanced Templates
-
-Advanced templates with best practices:
+Or in your `Gemfile`:
 
 ```ruby
-class UserCreator
-  include Dry::Monads[:result, :do]
-
-  def call
-    yield validate!
-    yield process!
-    Success(result_data)
-  end
+group :development do
+  gem 'railsforge', require: false
 end
 ```
 
-## Examples
-
-### Complete Workflow Example
-
-```bash
-# 1. Create a new Rails app (optional)
-railsforge new my_app --profile=api
-
-# 2. Add monitoring
-cd my_app
-railsforge generate monitoring --sentry_dsn=https://key@sentry.io/123
-
-# 3. Add DevOps setup
-railsforge generate devops --ci=github
-
-# 4. Generate components
-railsforge generate service user_creator --template=v3
-railsforge generate job send_welcome_email --template=v3
-railsforge generate query active_users --template=v3
-
-# 5. Run analysis
-railsforge analyze all
-railsforge doctor
-
-# 6. Check architecture
-railsforge graph
-```
-
-### Output Examples
-
-```
-$ railsforge generate monitoring
-Generating Monitoring configurations...
-Created config/initializers/sentry.rb
-Created config/initializers/lograge.rb
-Updated production.rb
-
-$ railsforge analyze security
-Security Analysis
-==================================================
-✓ No security issues found
-
-$ railsforge analyze performance
-Performance Analysis
-==================================================
-✓ No performance issues found
-```
-
-## Contributing
-
-We welcome contributions! Please see our contributing guidelines:
-
-### Development Setup
+Requires Ruby 3.0+.
 
-```bash
-# Fork the repository
-git clone https://github.com/mfifth/RailsForge.git
-cd railsforge
+---
 
-# Install dependencies
-bundle install
+## Configuration
 
-# Run tests
-bundle exec rake test
+Optional `.railsforgerc` in your project root:
 
-# Run linter
-bundle exec rubocop
+```yaml
+analyzers:
+  controller_max_lines: 150
+  controller_max_methods: 10
+  model_max_lines: 200
+  model_max_method_lines: 15
 ```
 
-### Submitting Changes
+---
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+## Philosophy
 
-### Code Style
+Analyze reality. Don't prescribe structure.
 
-- Follow Ruby community style guides
-- Write tests for new features
-- Update documentation for any changes
-- Use meaningful commit messages
+---
 
 ## License
 
-RailsForge is released under the MIT License.
-
-Copyright (c) 2024 RailsForge Contributors
-
-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.
-
-## Support
-
-- 📖 [Documentation](https://github.com/railsforge/railsforge/wiki)
-- 🐛 [Issue Tracker](https://github.com/railsforge/railsforge/issues)
-- 💬 [Discussions](https://github.com/railsforge/railsforge/discussions)
-- ⭐ [Give us a star](https://github.com/railsforge/railsforge)
-
----
-
-<p align="center">Built with ❤️ for the Rails community</p>
+MIT