rails_code_health 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fcf270392e52c8b6ab9783a9ed2ffaa133825210ff18c0c4ec124ce8b8d2b7f
+  data.tar.gz: 6ddc72d1451b604e7df94e655e22b225647842dcbd0a00baec0618d4e3b1c823
+SHA512:
+  metadata.gz: 416a30e4fd42da4f2f8fe100e349c611c009d5468710974c59d945036145ce1c0df543ca1a8f51f3bf53868cd6ce9472e4be3457dcdaca3d5de12258ef16ed77
+  data.tar.gz: 44e261b45a963e81c5d3ace4be6b360ff8c052ba39dd4b0e3fa56789c145673e3b51d5359ebed08a2f7eb50214044031f0f6185760e3ac06072531be25659769

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-06-17
+
+### Added
+- Initial release of Rails Code Health analyzer
+- Ruby code complexity analysis (cyclomatic complexity, method length, class length)
+- Rails-specific pattern detection for controllers, models, views, helpers, and migrations
+- Health scoring system (1-10 scale) based on CodeScene research
+- Command-line interface with console and JSON output options
+- Configurable thresholds and scoring weights
+- Actionable recommendations for code improvements
+- Support for Ruby 3.0+ and Rails 7.0+
+
+### Features
+- **Ruby Analysis**: Method/class length, cyclomatic complexity, nesting depth, parameter count
+- **Rails Analysis**: Controller actions, model validations, view logic detection, migration complexity
+- **Code Smells**: God classes/methods, long parameter lists, nested conditionals, missing validations
+- **Reporting**: Detailed console output with health categories and JSON export
+- **CLI**: `rails-health` command with options for format, output file, and custom configuration
+
+[Unreleased]: https://github.com/yourusername/rails_code_health/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/yourusername/rails_code_health/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 George Kosmopoulos
+
+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.

data/README.md

@@ -0,0 +1,237 @@
+# Rails Code Health
+
+A Ruby gem that evaluates the code health of Ruby on Rails applications, inspired by CodeScene's research on technical debt and maintainability.
+
+## Overview
+
+Rails Code Health analyzes your Rails codebase and provides:
+- **Health scores** (1-10 scale) for each file based on complexity, maintainability, and Rails conventions
+- **Categorization** of files into Healthy (🟢), Warning (🟡), Alert (🔴), and Critical (⚫) categories
+- **Actionable recommendations** for improving code quality
+- **Rails-specific analysis** for controllers, models, views, helpers, and migrations
+
+## Installation
+
+Add this gem to your Rails application's Gemfile:
+
+```ruby
+gem 'rails_code_health', group: :development
+```
+
+Or install it globally:
+
+```bash
+gem install rails_code_health
+```
+
+## Usage
+
+### Command Line Interface
+
+Run analysis on your current Rails project:
+
+```bash
+rails-health
+```
+
+Analyze a specific Rails project:
+
+```bash
+rails-health /path/to/rails/project
+```
+
+Generate JSON output:
+
+```bash
+rails-health --format json --output report.json
+```
+
+Use custom configuration:
+
+```bash
+rails-health --config custom_thresholds.json
+```
+
+### Programmatic Usage
+
+```ruby
+require 'rails_code_health'
+
+# Analyze current directory
+report = RailsCodeHealth.analyze('.')
+
+# Analyze specific path
+report = RailsCodeHealth.analyze('/path/to/rails/project')
+
+# Configure custom thresholds
+RailsCodeHealth.configure do |config|
+  config.load_thresholds_from_file('custom_config.json')
+end
+```
+
+## What It Analyzes
+
+### Ruby Code Metrics
+- **Method length** - Long methods are harder to understand and maintain
+- **Class length** - Large classes often violate single responsibility principle
+- **Cyclomatic complexity** - High complexity increases defect risk
+- **Nesting depth** - Deep nesting reduces readability
+- **Parameter count** - Too many parameters suggest poor design
+- **ABC complexity** - Assignments, branches, and conditions complexity
+
+### Rails-Specific Analysis
+
+#### Controllers
+- Action count per controller
+- Strong parameters usage
+- Direct model access detection
+- Response format analysis
+
+#### Models
+- Association count
+- Validation presence
+- Callback complexity
+- Fat model detection
+
+#### Views
+- Logic in views detection
+- Inline styles/JavaScript
+- Template length analysis
+
+#### Helpers & Migrations
+- Helper method count
+- Migration complexity
+- Data changes in migrations
+
+### Code Smells Detection
+- **God Class/Method** - Classes or methods doing too much
+- **Long Parameter List** - Methods with too many parameters
+- **Nested Conditionals** - Deep if/else nesting
+- **Missing Validations** - Models without proper validation
+- **Logic in Views** - Business logic in presentation layer
+
+## Health Score Calculation
+
+Health scores range from 1.0 (critical) to 10.0 (excellent) based on:
+
+- **File type multipliers** - Different standards for different file types
+- **Weighted penalties** - More important issues have higher impact
+- **Rails conventions** - Adherence to Rails best practices
+- **Code complexity** - Multiple complexity metrics combined
+
+### Score Categories
+
+- **🟢 Healthy (8.0-10.0)**: Well-structured, maintainable code
+- **🟡 Warning (4.0-7.9)**: Some issues, but generally acceptable
+- **🔴 Alert (1.0-3.9)**: Significant problems requiring attention
+- **⚫ Critical (<1.0)**: Severe issues, immediate action needed
+
+## Configuration
+
+Create a custom `thresholds.json` file:
+
+```json
+{
+  "ruby_thresholds": {
+    "method_length": {
+      "green": 15,
+      "yellow": 25,
+      "red": 40
+    },
+    "cyclomatic_complexity": {
+      "green": 6,
+      "yellow": 10,
+      "red": 15
+    }
+  },
+  "rails_specific": {
+    "controller_actions": {
+      "green": 5,
+      "yellow": 10,
+      "red": 20
+    }
+  },
+  "scoring_weights": {
+    "method_length": 0.15,
+    "cyclomatic_complexity": 0.20,
+    "rails_conventions": 0.15
+  }
+}
+```
+
+## Sample Output
+
+```
+Rails Code Health Report
+==================================================
+
+📊 Overall Health Summary:
+  Total files analyzed: 45
+  🟢 Healthy files (8.0-10.0): 32 (71.1%)
+  🟡 Warning files (4.0-7.9): 10 (22.2%)
+  🔴 Alert files (1.0-3.9): 3 (6.7%)
+
+📈 Average Health Score: 7.8/10.0
+
+📂 Breakdown by File Type:
+  Controller: 8 files, avg score: 7.2, 5 healthy
+  Model: 12 files, avg score: 8.4, 10 healthy
+  View: 15 files, avg score: 8.1, 12 healthy
+
+🚨 Files Needing Most Attention:
+1. 🔴 app/controllers/admin/reports_controller.rb
+   Score: 3.2/10.0 | Type: controller | Size: 15.2 KB
+   Top issues:
+     • Break down the generate_report method (156 lines) into smaller methods
+     • Consider splitting this controller - it has 18 actions
+
+💡 Key Recommendations:
+1. Reduce method and class lengths
+2. Lower cyclomatic complexity  
+3. Follow Rails conventions
+4. Extract business logic from controllers
+```
+
+## Research Foundation
+
+This gem is inspired by the peer-reviewed research paper ["Code Red: The Business Impact of Code Quality"](https://arxiv.org/pdf/2203.04374) by Adam Tornhill and Markus Borg, which found that:
+
+- Low quality code contains **15x more defects** than high quality code
+- Resolving issues in low quality code takes **124% more time**
+- Issue resolutions involve **9x longer maximum cycle times**
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+Run the gem locally:
+
+```bash
+bundle exec bin/rails-health /path/to/rails/project
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Inspired by [CodeScene](https://codescene.com/) and the research on technical debt's business impact. This gem implements similar concepts specifically for Ruby on Rails applications.

data/bin/rails-health

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/rails_code_health'
+
+RailsCodeHealth::CLI.start(ARGV)

data/config/tresholds.json

@@ -0,0 +1,80 @@
+{
+  "ruby_thresholds": {
+    "method_length": {
+      "green": 15,
+      "yellow": 25,
+      "red": 40
+    },
+    "class_length": {
+      "green": 100,
+      "yellow": 200,
+      "red": 400
+    },
+    "cyclomatic_complexity": {
+      "green": 6,
+      "yellow": 10,
+      "red": 15
+    },
+    "abc_complexity": {
+      "green": 15,
+      "yellow": 25,
+      "red": 40
+    },
+    "nesting_depth": {
+      "green": 3,
+      "yellow": 5,
+      "red": 8
+    },
+    "parameter_count": {
+      "green": 3,
+      "yellow": 5,
+      "red": 8
+    }
+  },
+  "rails_specific": {
+    "controller_actions": {
+      "green": 5,
+      "yellow": 10,
+      "red": 20
+    },
+    "controller_length": {
+      "green": 50,
+      "yellow": 100,
+      "red": 200
+    },
+    "model_public_methods": {
+      "green": 7,
+      "yellow": 12,
+      "red": 20
+    },
+    "view_length": {
+      "green": 30,
+      "yellow": 50,
+      "red": 100
+    },
+    "migration_complexity": {
+      "green": 10,
+      "yellow": 20,
+      "red": 40
+    }
+  },
+  "file_type_multipliers": {
+    "controllers": 1.2,
+    "models": 1.0,
+    "views": 0.8,
+    "helpers": 0.9,
+    "lib": 1.1,
+    "specs": 0.7,
+    "migrations": 0.6
+  },
+  "scoring_weights": {
+    "method_length": 0.15,
+    "class_length": 0.12,
+    "cyclomatic_complexity": 0.20,
+    "nesting_depth": 0.18,
+    "parameter_count": 0.10,
+    "duplication": 0.25,
+    "rails_conventions": 0.15,
+    "code_smells": 0.25
+  }
+}

data/lib/rails_code_health/cli.rb

@@ -0,0 +1,164 @@
+require 'optparse'
+
+module RailsCodeHealth
+  class CLI
+    def self.start(args)
+      new(args).run
+    end
+
+    def initialize(args)
+      @args = args
+      @options = {
+        path: '.',
+        format: :console,
+        output: nil,
+        config: nil,
+        verbose: false
+      }
+    end
+
+    def run
+      parse_options
+
+      begin
+        # Load custom config if provided
+        if @options[:config]
+          RailsCodeHealth.configuration.load_thresholds_from_file(@options[:config])
+        end
+
+        # Set output format
+        RailsCodeHealth.configuration.output_format = @options[:format]
+
+        puts "🔍 Analyzing Rails project at: #{@options[:path]}" if @options[:verbose]
+        puts "📊 Using format: #{@options[:format]}" if @options[:verbose]
+
+        # Run the analysis
+        report = analyze_project
+
+        # Output the report
+        output_report(report)
+
+        puts "\n✅ Analysis complete!" if @options[:verbose]
+
+      rescue RailsCodeHealth::Error => e
+        puts "❌ Error: #{e.message}"
+        exit 1
+      rescue => e
+        puts "💥 Unexpected error: #{e.message}"
+        puts e.backtrace.join("\n") if @options[:verbose]
+        exit 1
+      end
+    end
+
+    private
+
+    def parse_options
+      OptionParser.new do |opts|
+        opts.banner = "Usage: rails-health [options] [path]"
+        opts.separator ""
+        opts.separator "Analyze the code health of a Ruby on Rails application"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("-f", "--format FORMAT", [:console, :json], 
+                "Output format (console, json)") do |format|
+          @options[:format] = format
+        end
+
+        opts.on("-o", "--output FILE", 
+                "Output file (default: stdout)") do |file|
+          @options[:output] = file
+        end
+
+        opts.on("-c", "--config FILE", 
+                "Custom configuration file") do |file|
+          @options[:config] = file
+        end
+
+        opts.on("-v", "--verbose", 
+                "Verbose output") do
+          @options[:verbose] = true
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+
+        opts.on_tail("--version", "Show version") do
+          puts "Rails Code Health v#{RailsCodeHealth::VERSION}"
+          exit
+        end
+      end.parse!(@args)
+
+      # Use remaining argument as path if provided
+      @options[:path] = @args.first if @args.any?
+    end
+
+    def analyze_project
+      project_path = Pathname.new(@options[:path]).expand_path
+      
+      unless ProjectDetector.rails_project?(project_path)
+        raise Error, "Not a Rails project directory: #{project_path}"
+      end
+
+      puts "📁 Found Rails project!" if @options[:verbose]
+
+      analyzer = FileAnalyzer.new(project_path)
+      results = analyzer.analyze_all
+
+      puts "📝 Analyzed #{results.count} files" if @options[:verbose]
+
+      health_calculator = HealthCalculator.new
+      scored_results = health_calculator.calculate_scores(results)
+
+      puts "🧮 Calculated health scores" if @options[:verbose]
+
+      scored_results
+    end
+
+    def output_report(results)
+      case @options[:format]
+      when :console
+        output_console_report(results)
+      when :json
+        output_json_report(results)
+      end
+    end
+
+    def output_console_report(results)
+      report_generator = ReportGenerator.new(results)
+      
+      if @options[:output]
+        File.write(@options[:output], capture_console_output(report_generator))
+        puts "📄 Report saved to: #{@options[:output]}"
+      else
+        report_generator.generate
+      end
+    end
+
+    def output_json_report(results)
+      report_generator = ReportGenerator.new(results)
+      json_report = report_generator.generate_json_report
+      
+      if @options[:output]
+        File.write(@options[:output], json_report)
+        puts "📄 JSON report saved to: #{@options[:output]}"
+      else
+        puts json_report
+      end
+    end
+
+    def capture_console_output(report_generator)
+      original_stdout = $stdout
+      $stdout = StringIO.new
+      
+      report_generator.generate
+      
+      output = $stdout.string
+      $stdout = original_stdout
+      
+      output
+    end
+  end
+end

data/lib/rails_code_health/configuration.rb

@@ -0,0 +1,89 @@
+module RailsCodeHealth
+  class Configuration
+    attr_accessor :thresholds, :excluded_paths, :output_format
+
+    def initialize
+      @thresholds = load_default_thresholds
+      @excluded_paths = default_excluded_paths
+      @output_format = :console
+    end
+
+    def thresholds
+      @thresholds ||= load_default_thresholds
+    end
+
+    def load_thresholds_from_file(file_path)
+      if File.exist?(file_path)
+        @thresholds = JSON.parse(File.read(file_path))
+      else
+        raise Error, "Thresholds file not found: #{file_path}"
+      end
+    end
+
+    private
+
+    def load_default_thresholds
+      config_file = File.join(File.dirname(__FILE__), '..', '..', 'config', 'thresholds.json')
+      if File.exist?(config_file)
+        JSON.parse(File.read(config_file))
+      else
+        # Fallback to hardcoded defaults if config file is missing
+        default_hardcoded_thresholds
+      end
+    end
+
+    def default_excluded_paths
+      [
+        'vendor/**/*',
+        'tmp/**/*',
+        'log/**/*',
+        'node_modules/**/*',
+        'coverage/**/*',
+        '.git/**/*',
+        'public/assets/**/*',
+        'db/schema.rb',
+        'spec/**/*',
+        'test/**/*'
+      ]
+    end
+
+    def default_hardcoded_thresholds
+      {
+        'ruby_thresholds' => {
+          'method_length' => { 'green' => 15, 'yellow' => 25, 'red' => 40 },
+          'class_length' => { 'green' => 100, 'yellow' => 200, 'red' => 400 },
+          'cyclomatic_complexity' => { 'green' => 6, 'yellow' => 10, 'red' => 15 },
+          'abc_complexity' => { 'green' => 15, 'yellow' => 25, 'red' => 40 },
+          'nesting_depth' => { 'green' => 3, 'yellow' => 5, 'red' => 8 },
+          'parameter_count' => { 'green' => 3, 'yellow' => 5, 'red' => 8 }
+        },
+        'rails_specific' => {
+          'controller_actions' => { 'green' => 5, 'yellow' => 10, 'red' => 20 },
+          'controller_length' => { 'green' => 50, 'yellow' => 100, 'red' => 200 },
+          'model_public_methods' => { 'green' => 7, 'yellow' => 12, 'red' => 20 },
+          'view_length' => { 'green' => 30, 'yellow' => 50, 'red' => 100 },
+          'migration_complexity' => { 'green' => 10, 'yellow' => 20, 'red' => 40 }
+        },
+        'file_type_multipliers' => {
+          'controllers' => 1.2,
+          'models' => 1.0,
+          'views' => 0.8,
+          'helpers' => 0.9,
+          'lib' => 1.1,
+          'specs' => 0.7,
+          'migrations' => 0.6
+        },
+        'scoring_weights' => {
+          'method_length' => 0.15,
+          'class_length' => 0.12,
+          'cyclomatic_complexity' => 0.20,
+          'nesting_depth' => 0.18,
+          'parameter_count' => 0.10,
+          'duplication' => 0.25,
+          'rails_conventions' => 0.15,
+          'code_smells' => 0.25
+        }
+      }
+    end
+  end
+end