railsforge 1.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ca67789d645855334565249db474d63bfde8607e031642c52a287924c55b9cf
-  data.tar.gz: 9517139f8e3224a17ebd875c6606a2ea244e183e289acc1599181eed13522f07
+  metadata.gz: b004345e61120afc6f11432c72baeddb6981aee6e504d50b5eedf5b0334f71d6
+  data.tar.gz: 51bae87bc37e99da845f89ea3e9af014a2d9b6d85128417223978e5ffef14958
 SHA512:
-  metadata.gz: db1e954e6df040c1856be4cee40357e781201d29a550f31c1dc8924d4c3e93678daecefa42c8e651d02ddef5dc04d4ebd702cb37cac2a0731111ddf0a6e03d13
-  data.tar.gz: d7f692d25425099a0ea48499655272a70cf77f517cbfdadbe54826c517aa9e989833774feca6fb7742d36e5aa8bdc47c5c9d9760b8a0130009716ea74298e6c6
+  metadata.gz: 1bc07580544ae7d06679dd03986cf6268b7598ead40a495a54ff8b2f8d0da1730871d01738ec419455998992f85cbda3619dbd60ccf77fb6ea73cce53ce7179c
+  data.tar.gz: 7b1b7c639d4da0968d6db7ea4e2a9d98a28398186f93ffeaddab9ee86c60c9481296d72ab64c0c9d552e795f635de3d146664e7cc6415d9c919db16bfe68aa18

data/README.md

@@ -12,513 +12,207 @@
   </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
+## The Problem
 
-### Setup Steps
+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.
 
-#### Option 1: Install from RubyGems (Recommended)
+Most teams only discover these problems during an audit, a security review, or an incident.
 
-```bash
-# Install the gem
-gem install railsforge
-
-# Verify installation
-railsforge --version
-```
+---
 
-#### Option 2: Install from Source
+## The Primary Command
 
 ```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
+railsforge doctor
 ```
 
-Then run:
+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
-bundle install
-```
-
-## Usage Documentation
+---
 
-### Getting Help
+## Example Output
 
-```bash
-railsforge --help
-railsforge --version
 ```
+RailsForge Health Report
+─────────────────────────────��────────────────────
+Score:  61/100
+Issues: 9 total
 
-### Generate Commands
+HIGH (2)
+  [security]
+    app/controllers/users_controller.rb:42 — SQL Injection: User.where("name = '#{params[:name]}'")
+    → Use parameterized queries: Model.where(column: value)
 
-#### Monitoring Configuration
+  [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)
 
-Add Sentry error tracking and Lograge structured logging to your Rails application:
+MEDIUM (4)
+  [controller]
+    app/controllers/admin_controller.rb — AdminController has 214 lines (max 150)
+    → Extract business logic to Service objects
 
-```bash
-railsforge generate monitoring
-railsforge generate monitoring --sentry_dsn=your_dsn_here
-railsforge generate monitoring --environment=production
-```
+  [database]
+    db/schema.rb — Table `events` has datetime columns without an index
+    → add_index :events, :created_at
 
-This creates:
-- `config/initializers/sentry.rb` - Sentry configuration
-- `config/initializers/lograge.rb` - Lograge setup
-- Updates environment configurations
+  [refactor]
+    app/models/user.rb — User has 267 lines (max 200)
+    → Consider extracting concerns or service objects
 
-#### DevOps Configuration
+    app/models/order.rb — Method `process_payment` has 43 lines
+    → Consider extracting to a private method or service
 
-Generate Docker and CI/CD pipeline configurations:
+LOW (3)
+  [spec]
+    app/service/invoice_generator.rb — Service `invoice_generator` has no spec
+    → Create spec/services/invoice_generator_spec.rb
 
-```bash
-railsforge generate devops
-railsforge generate devops --docker
-railsforge generate devops --ci=github
-railsforge generate devops --ci=gitlab
-```
+    app/service/payment_processor.rb — Service `payment_processor` has no spec
+    → Create spec/services/payment_processor_spec.rb
 
-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:
-
-```bash
-railsforge generate demo my_demo
-railsforge generate demo my_demo --type=blog
-railsforge generate demo my_api --type=api
+  [controller]
+    app/controllers/api/v1/orders_controller.rb — OrdersController has 13 methods (max 10)
+    → Consider splitting into focused controllers
 ```
 
-#### Test Files
-
-Generate comprehensive test files:
-
-```bash
-railsforge generate test User
-railsforge generate test PostsController --type=controller
-railsforge generate test UserService --type=service
-railsforge generate test SendEmailJob --type=job
-```
-
-#### Standard Generators
+---
 
-Generate Rails components with template versioning:
+## JSON Mode
 
 ```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
-
-# Presenters
-railsforge generate presenter user_presenter
-
-# Policies
-railsforge generate policy post_policy
-
-# Serializers
-railsforge generate serializer post_serializer
-
-# View Components
-railsforge generate component button
-railsforge generate component modal --template=v2
-
-# Stimulus Controllers
-railsforge generate stimulus dropdown
-
-# Mailers
-railsforge generate mailer user_mailer
-
-# Features
-railsforge generate feature user_signup
-
-# API Resources
-railsforge generate api posts
+railsforge doctor --format=json
 ```
 
-### Analyze Commands
-
-#### Security Analysis
+Returns structured output for CI pipelines and automated tooling:
 
-Run security vulnerability checks on your codebase:
-
-```bash
-railsforge analyze security
-railsforge analyze security --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": {
+      "critical": 0,
+      "high": 2,
+      "medium": 4,
+      "low": 3,
+      "info": 0
+    }
+  }
+}
 ```
 
-Checks for:
-- SQL injection vulnerabilities
-- Cross-site scripting (XSS) risks
-- Authentication/authorization issues
-- Insecure configuration patterns
-- Sensitive data exposure
-
-#### Performance Analysis
+All five severity keys are always present, even when zero. Score is always an integer. Output is deterministic.
 
-Identify performance optimization opportunities:
-
-```bash
-railsforge analyze performance
-railsforge analyze performance --verbose
-```
+---
 
-Checks for:
-- N+1 query patterns
-- Missing database indexes
-- Inefficient queries
-- Memory leak patterns
-- Unoptimized asset loading
+## CI Usage
 
-#### Other Analyzers
+RailsForge provides signal. CI decides consequences.
 
 ```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
+railsforge doctor --format=json | jq '.score'
 ```
 
-### Other Commands
-
-#### Doctor - Health Check
-
-Comprehensive project health report:
-
-```bash
-railsforge doctor
-```
+RailsForge always exits `0` on a successful run. Your CI script owns the pass/fail logic.
 
-Combines all analyzers and calculates an architecture score (0-100).
+### GitHub Actions
 
-#### Dependency Graph
-
-Generate a Graphviz diagram of your Rails architecture:
-
-```bash
-railsforge graph
-```
-
-Outputs `.dot` and `.svg` files to `tmp/railsforge/`.
+```yaml
+name: RailsForge Health Check
 
-#### Wizard - Interactive Setup
+on: [push, pull_request]
 
-Interactive project configuration:
+jobs:
+  railsforge:
+    runs-on: ubuntu-latest
 
-```bash
-railsforge wizard
-railsforge wizard --profile=blog
-```
+    steps:
+      - uses: actions/checkout@v3
 
-#### Plugin Management
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
 
-```bash
-# List available plugins
-railsforge plugins list
+      - name: Install RailsForge
+        run: gem install railsforge
 
-# Load a specific plugin
-railsforge plugins load my_plugin
+      - name: Run RailsForge
+        run: |
+          score=$(railsforge doctor --format=json | jq '.score')
+          echo "Score: $score"
+          if [ "$score" -lt 80 ]; then
+            echo "RailsForge score below threshold"
+            exit 1
+          fi
 ```
 
-#### Configuration
+---
 
-```bash
-# View current configuration
-railsforge config
+## What RailsForge Detects
 
-# Set configuration values
-railsforge config set default_template v2
-railsforge config set analyzer_threshold 10
-```
+- **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
 
-#### 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:
+Requires Ruby 3.0+.
 
-### Development Setup
-
-```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