rails-architect 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9eaba9e7a51319c2b9c17d2612aa8937ec9858e3c23cdd22f5293f35c7f0b691
-  data.tar.gz: ec11a0500475321f9941a4e266b77226b692a2eca508b27a9ea47930942ad2dc
+  metadata.gz: f5e214be6afcbf72e11d25f85d0a782160457961b4df66fcc108e0a578c4317e
+  data.tar.gz: 0f69f574aec7b0a9973aeca1b4a5ebdb2a91a989bc13f9359b53272452d38a42
 SHA512:
-  metadata.gz: 7a59adc47f124695972d4fc830cffd2e188bdba523071b8e99d1f51e55c9dd30cec9c96c4d3482b872f886720dcb3a678e6952cb62dc5cf913eec787702bad51
-  data.tar.gz: 7ad650cf77b1aef49fb1cc7a84784ecf36394f48472231df1f68150a618cfa258f4b73856fe1294468386ee3fb42d23a8393193096eb90cc784f280aef02f912
+  metadata.gz: b949a221ba4c2598e562fa284df3c0d6edfbb42d44d8e2d1a5b3a10dc30af8b14d691d17009aa8f334a8cedd73ec8ee22e65e93f24e18042d475942d29ac773a
+  data.tar.gz: fd11b11531bbb73e33c4d6611be74ae22415da8c6cff04036904530a43bc383980b692ce00af11ebf73f7bcffd3172db7d1bd84668f402a454aa01f8ec54a5aa

data/README.md

@@ -2,15 +2,170 @@
 
 A comprehensive architectural enforcement and code quality tool for Rails applications.
 
-Rails Architect helps maintain clean Rails architecture by automatically detecting and preventing common anti-patterns, monitoring code complexity, enforcing test coverage, and providing architectural visualizations.
+Rails Architect helps maintain clean Rails architecture by automatically enforcing software design principles and detecting common anti-patterns.
 
 ## Features
 
-- **Architecture Pattern Enforcement**: Detects fat models, complex controllers, and suggests service objects
-- **Code Complexity Monitoring**: Tracks method complexity and suggests refactoring
-- **XP/Agile Integration**: Built-in checks for test coverage requirements and TDD patterns
-- **Performance Alerts**: Detects N+1 queries and inefficient database operations
-- **Architecture Visualization**: Generates dependency diagrams and service flow representations
+- **SOLID Principles**: Enforces Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles
+- **KISS Principle**: Detects overly complex code and suggests simplification
+- **DRY Principle**: Identifies code duplication and repeated patterns
+- **Automated Checks**: Run as rake tasks or integrate into CI/CD pipelines
+
+## SOLID Principles Guide
+
+Here's a quick, Rails-flavored guide to the **SOLID** principles—with tiny examples and common pitfalls.
+
+### S — Single Responsibility
+
+**One class = one reason to change.**
+Rails gotchas: "Fat models," callback soup, controllers doing business logic.
+
+**Smell**
+
+```ruby
+class Order < ApplicationRecord
+  after_create :send_receipt_email
+  def total_cents; ... complex tax/discount logic ... end
+end
+```
+
+**Refactor**
+
+```ruby
+# app/services/orders/calculate_total.rb
+class Orders::CalculateTotal
+  def self.call(order) = ... # pure calc
+end
+
+# app/jobs/order_receipt_job.rb
+class OrderReceiptJob < ApplicationJob
+  def perform(order_id) = OrderMailer.receipt(Order.find(order_id)).deliver_now
+end
+
+# app/models/order.rb
+class Order < ApplicationRecord
+  def total_cents = Orders::CalculateTotal.call(self)
+end
+```
+
+Tip: prefer **service objects, form objects, query objects, mailer jobs** over callbacks.
+
+### O — Open/Closed
+
+**Open for extension, closed for modification.**
+Use composition & small objects; avoid editing core classes for each new case.
+
+**Example: pluggable pricing rules**
+
+```ruby
+class PriceCalculator
+  def initialize(rules = [LoyaltyRule.new, CouponRule.new])
+    @rules = rules
+  end
+
+  def call(order)
+    @rules.reduce(order.subtotal) { |total, rule| rule.apply(order, total) }
+  end
+end
+```
+
+Add a new rule class, don't edit `PriceCalculator`.
+
+### L — Liskov Substitution
+
+**Subtypes must be usable wherever their base is.**
+Rails gotcha: STI models or polymorphic interfaces that don't honor contracts.
+
+**Bad**
+
+```ruby
+class Payment < ApplicationRecord; end
+class CreditCardPayment < Payment; def refund!; ...; end
+class GiftCardPayment < Payment; end  # no refund!
+```
+
+**Better (explicit interface)**
+
+```ruby
+module Refundable
+  def refund! = raise NotImplementedError
+end
+
+class CreditCardPayment < ApplicationRecord
+  include Refundable
+  def refund!; ... end
+end
+
+class GiftCardPayment < ApplicationRecord
+  include Refundable
+  def refund!; ... end
+end
+```
+
+Or avoid STI; use separate models + shared interface modules and tests.
+
+### I — Interface Segregation
+
+**Clients shouldn't depend on methods they don't use.**
+Rails tip: keep "narrow" objects per use-case: **FormObject**, **Presenter**, **Query**—not one god-service.
+
+**Example**
+
+```ruby
+# Too broad:
+class AccountService; def create; def suspend; def invite; def export_csv; end; end
+
+# Split:
+class Accounts::Creator; end
+class Accounts::Suspender; end
+class Accounts::Inviter; end
+```
+
+For APIs, expose slim endpoints; for views, use **ViewComponents/Presenters** instead of fat helpers.
+
+### D — Dependency Inversion
+
+**Depend on abstractions, not concretions.**
+Rails tip: inject collaborators; don't hard-wire globals (e.g., a specific HTTP client).
+
+**Example**
+
+```ruby
+# app/services/notifications/send_sms.rb
+class Notifications::SendSms
+  def initialize(client: Sms::TwilioClient.new) = @client = client
+  def call(to:, body:) = @client.deliver(to:, body:)
+end
+
+# test
+fake = Class.new { def deliver(...) = true }.new
+expect(Notifications::SendSms.new(client: fake).call(to: "...", body: "...")).to be true
+```
+
+### Common Rails patterns that support SOLID
+
+* **Service objects** (`app/services/...`) for business actions.
+* **Form objects** (e.g., `Reform`, or POROs with `ActiveModel::Model`) to keep controllers skinny.
+* **Query objects** for complex scopes (compose instead of stuffing models).
+* **Policies** (`Pundit`) for authorization logic (SRP).
+* **ViewComponent** (or presenters) to isolate view behavior (ISP/SRP).
+* **Background jobs** for side effects (mail, webhooks) instead of callbacks.
+* **Adapters/ports** for external services (DIP).
+
+### Anti-patterns to watch
+
+* Heavy **`ActiveSupport::Concern`** mixing multiple responsibilities.
+* Model callbacks triggering network calls (violates SRP & DIP).
+* STI where subclasses violate the base contract (breaks LSP).
+* "Helper modules" with dozens of unrelated methods (violates SRP/ISP).
+
+### Tiny checklist (paste in your PR template)
+
+* Does each class have **one reason to change**?
+* If a new variant appears, can I **add a class** (not edit many)?
+* Do polymorphic things **share a clear interface** and tests?
+* Are public APIs **small and focused**?
+* Can I **swap dependencies** in tests via initializer args?
 
 ## Installation
 
@@ -32,103 +187,190 @@ Or install it yourself as:
 gem install rails-architect
 ```
 
-### Configuration
+## Usage
 
-Create `config/rails_architect.yml` in your Rails app:
+### Rake Tasks
 
-```yaml
-defaults: &defaults
-  model_method_threshold: 10
-  controller_action_threshold: 5
-  method_complexity_threshold: 10
-  test_coverage_minimum: 80
+Run individual principle checks in your Rails application:
 
-development:
-  <<: *defaults
+```bash
+bundle exec rake rails_architect:check_solid   # Check SOLID principles
+bundle exec rake rails_architect:check_kiss    # Check KISS principle
+bundle exec rake rails_architect:check_dry     # Check DRY principle
+```
 
-test:
-  <<: *defaults
+Or with Docker:
 
-production:
-  <<: *defaults
+```bash
+docker exec your_container bundle exec rake rails_architect:check_solid
+docker exec your_container bundle exec rake rails_architect:check_kiss  
+docker exec your_container bundle exec rake rails_architect:check_dry
 ```
 
-### Bullet Integration
+### Example Test Application
 
-Add to your `Gemfile`:
+The gem includes a test Rails application in `test/rails_app/` that demonstrates intentional violations of all principles:
 
-```ruby
-group :development do
-  gem 'bullet'
-end
-```
+**SOLID Violations:**
+- **SRP**: `User` model has 15+ methods (fat model), `UsersController` has business logic and 9+ actions
+- **OCP**: Deep inheritance chains and case statements that may need modification
+- **LSP**: STI models and polymorphic associations that might violate contracts
+- **ISP**: Heavy concerns and service objects with too many methods
+- **DIP**: Hard-coded external service dependencies and network calls in callbacks
 
-And configure in `config/environments/development.rb`:
+**KISS Violations:**
+- **Complexity**: `ReportGenerator#generate_complex_report` has cyclomatic complexity of 14
+- **Length**: Methods over 64 lines with deep nesting (5+ levels)
+- **Class Size**: Large classes with multiple responsibilities
 
-```ruby
-config.after_initialize do
-  Bullet.enable = true
-  Bullet.alert = true
-  Bullet.bullet_logger = true
-  Bullet.console = true
-  Bullet.rails_logger = true
-end
-```
+**DRY Violations:**
+- **Code Duplication**: Identical method implementations across classes
+- **Repeated Patterns**: Same filtering logic in multiple controller actions
+- **String Literals**: Repeated long strings that should be constants
+- **Method Calls**: Excessive calls to the same methods (e.g., `.count` called 7+ times)
+
+**Configuration:**
+See `test/rails_app/README.md` for detailed violation documentation.
+
+## Detected Violations
+
+### SOLID Principles
+
+**Single Responsibility Principle (SRP):**
+- Models with 15+ public methods (fat models)
+- Controllers with 8+ actions (fat controllers)
+- Models with 2+ callbacks (callback soup)
+- Controllers doing business logic (calling services, mailers)
+- Models with network calls in callbacks
+
+**Open/Closed Principle (OCP):**
+- Classes with inheritance depth > 3
+- Complex case statements with 3+ conditions
+
+**Liskov Substitution Principle (LSP):**
+- STI models that may violate base contracts
+- Polymorphic associations without clear interfaces
 
-### Pre-commit Hook
+**Interface Segregation Principle (ISP):**
+- Controllers including 3+ modules
+- ActiveSupport::Concern modules with 5+ methods
+- Service objects with 10+ methods
 
-Copy the hook to your git hooks:
+**Dependency Inversion Principle (DIP):**
+- Direct instantiation of classes (`.new` calls > 2)
+- Hard-coded external service dependencies
+- Network calls in model callbacks
+
+### KISS Principle
+
+- Methods with cyclomatic complexity > 10
+- Classes with > 100 lines
+- Methods with > 64 lines
+- Nesting depth > 5 levels
+
+### DRY Principle
+
+- Identical method implementations across classes
+- String literals repeated > 2 times
+- Method calls repeated > 5 times (e.g., `.count`, `.where`)
+- Duplicate code patterns in controllers
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `ruby -Ilib:test test/*_test.rb` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Publishing and Releasing the Gem
+
+### Prerequisites
+
+1. **RubyGems Account**: Create an account at [rubygems.org](https://rubygems.org) if you don't have one
+2. **API Credentials**: Ensure you're logged in locally:
+   ```bash
+   gem signin
+   ```
+
+### Build the Gem
+
+Build the gem package from the gemspec:
 
 ```bash
-cp $(bundle show rails-architect)/hooks/pre-commit .git/hooks/pre-commit
-chmod +x .git/hooks/pre-commit
+gem build rails-architect.gemspec
 ```
 
-## Usage
+This creates a `.gem` file (e.g., `rails-architect-0.1.0.gem`) in your project root.
 
-### Command Line
+### Publishing to RubyGems
 
-Run analysis on your Rails project:
+Push the built gem to RubyGems:
 
 ```bash
-rails-architect analyze    # Run all checks
-rails-architect visualize  # Generate diagrams
+gem push rails-architect-0.1.0.gem
 ```
 
-### Rake Tasks
+Or use the rake task:
 
 ```bash
-rake rails_architect:analyze          # Run all checks (fails on issues)
-rake rails_architect:visualize        # Generate visualizations
-rake rails_architect:check_coverage   # Check test coverage
-rake rails_architect:check_performance # Run performance checks
+bundle exec rake release
 ```
 
-### Programmatic Usage
+This rake task will:
+- Build the gem
+- Create a git tag for the version
+- Push the tag to GitHub
+- Push the gem to RubyGems
 
-```ruby
-require 'rails_architect'
+### Version Management
 
-# Analyze the codebase
-issues = RailsArchitect.analyze
-issues.each do |issue|
-  puts "#{issue[:type]}: #{issue[:message]} in #{issue[:file]}"
-end
+1. Update the version in `lib/rails_architect/version.rb`:
+   ```ruby
+   module RailsArchitect
+     VERSION = "0.2.0"
+   end
+   ```
 
-# Generate visualizations
-RailsArchitect.visualize
-```
+2. Commit the version change:
+   ```bash
+   git add lib/rails_architect/version.rb
+   git commit -m "Bump version to 0.2.0"
+   ```
 
-## Development
+3. Create and push a git tag:
+   ```bash
+   git tag v0.2.0
+   git push origin main --tags
+   ```
+
+4. Build and push the gem:
+   ```bash
+   gem build rails-architect.gemspec
+   gem push rails-architect-0.2.0.gem
+   ```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Yanking a Release
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`.
+If you need to remove a version from RubyGems:
+
+```bash
+gem yank rails-architect -v 0.1.0
+```
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/samydghim/rails-architect.
 
-## License
+## Testing
+
+The gem includes a comprehensive test suite using Minitest. Run tests with:
+
+```bash
+ruby -Ilib:test test/*_test.rb
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Test coverage includes:
+- SOLID principles validation (SRP, OCP, LSP, ISP, DIP)
+- KISS principle enforcement (complexity, size, nesting)
+- DRY principle detection (duplication, patterns, repetition)
+- Integration tests with sample Rails app demonstrating violations
+- Rake task execution and output formatting

data/config/rails_architect.yml

@@ -0,0 +1,25 @@
+defaults: &defaults
+  # Model complexity: 7 methods is more realistic for most Rails apps
+  model_method_threshold: 7
+  # Controller complexity: 5 actions keeps controllers focused
+  controller_action_threshold: 5
+  # Method complexity: 8 is industry standard (vs 10 which is too lenient)
+  method_complexity_threshold: 8
+  # Test coverage: 85% is a good minimum for quality assurance
+  test_coverage_minimum: 85
+
+development:
+  <<: *defaults
+  # Development can be more lenient for rapid prototyping
+  model_method_threshold: 10
+  method_complexity_threshold: 10
+
+test:
+  <<: *defaults
+  # Strict testing requirements for CI/CD
+  test_coverage_minimum: 90
+
+production:
+  <<: *defaults
+  # Production should have highest quality standards
+  test_coverage_minimum: 90

data/lib/rails_architect/dry_analyzer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RailsArchitect
+  class DryAnalyzer
+    attr_reader :issues
+
+    def initialize
+      @issues = []
+    end
+
+    def analyze
+      check_code_duplication
+      check_repeated_patterns
+    end
+
+    private
+
+    def add_issue(file, type, message)
+      @issues << { file: file, type: type, message: message }
+    end
+
+    private
+
+    def check_code_duplication
+      files_content = {}
+
+      # Read all Ruby files
+      Dir.glob("app/**/*.rb").each do |file|
+        files_content[file] = File.read(file)
+      end
+
+      # Check for duplicate methods
+      methods = extract_all_methods(files_content)
+
+      # Find duplicate method bodies
+      method_bodies = methods.values
+      duplicates = find_duplicates(method_bodies)
+
+      duplicates.each do |body, count|
+        if count > 1 && body.strip.length > 50 # Only report significant duplicates
+          duplicate_methods = methods.select { |_, b| b == body }.keys
+          classes = duplicate_methods.map { |m| m.split('#').first }.uniq
+
+          if classes.count > 1 # Only if duplicated across different classes
+            add_issue("multiple_files", "dry_duplication", "Code duplication detected: #{duplicate_methods.join(', ')} have identical implementations")
+          end
+        end
+      end
+    end
+
+    def check_repeated_patterns
+      Dir.glob("app/**/*.rb").each do |file|
+        content = File.read(file)
+
+        # Check for repeated string literals
+        strings = content.scan(/"([^"]{10,})"/).flatten + content.scan(/'([^']{10,})'/).flatten
+        string_counts = strings.tally
+
+        string_counts.each do |str, count|
+          if count > 2
+            class_name = extract_class_name(file)
+            add_issue(file, "dry_strings", "#{class_name} repeats string '#{str[0..30]}...' #{count} times, consider extracting constants")
+          end
+        end
+
+        # Check for repeated method calls
+        method_calls = content.scan(/\.(\w+)\b/).flatten
+        call_counts = method_calls.tally
+
+        call_counts.each do |method, count|
+          if count > 5 && method.length > 3
+            class_name = extract_class_name(file)
+            add_issue(file, "dry_calls", "#{class_name} calls .#{method} #{count} times, consider extracting helper method")
+          end
+        end
+      end
+    end
+
+    def extract_all_methods(files_content)
+      methods = {}
+
+      files_content.each do |file, content|
+        class_name = extract_class_name(file)
+        file_methods = extract_methods(content)
+
+        file_methods.each do |method_name, body|
+          full_name = "#{class_name}##{method_name}"
+          methods[full_name] = body.strip
+        end
+      end
+
+      methods
+    end
+
+    def extract_methods(content)
+      methods = {}
+      current_method = nil
+      indent_level = 0
+      method_start = false
+
+      content.each_line do |line|
+        if line.match?(/^\s*def \w+/)
+          current_method = line.strip.match(/def (\w+)/)[1]
+          methods[current_method] = ""
+          method_start = true
+          indent_level = line.match(/^\s*/).to_s.length
+        elsif method_start && line.match(/^\s*end\s*$/) && line.match(/^\s*/).to_s.length == indent_level
+          method_start = false
+          current_method = nil
+        elsif method_start
+          methods[current_method] += line
+        end
+      end
+
+      methods
+    end
+
+    def find_duplicates(array)
+      duplicates = {}
+      seen = {}
+
+      array.each do |item|
+        normalized = item.strip
+        if seen[normalized]
+          duplicates[normalized] = (duplicates[normalized] || 2) + 1
+        else
+          seen[normalized] = true
+        end
+      end
+
+      duplicates
+    end
+
+    def extract_class_name(file)
+      relative_path = file.sub('app/', '').sub('.rb', '')
+      parts = relative_path.split('/')
+      class_parts = parts.map do |part|
+        part.split('_').map(&:capitalize).join
+      end
+      class_parts.join('::')
+    end
+  end
+end