rage_arch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0f57a7080e54d4fd38967f95f88a3e3af2a1a3716665acc79e3b2383fd3b6a4
+  data.tar.gz: '052118de065d6e08bf9c61eacce620d964b8d13f35c745c33d01e5df15515d54'
+SHA512:
+  metadata.gz: 0ed85c8a86183eee47cd39bdbcb9685832a73f2d731a4a7e7ba2f4a6b88c47718418b0fae81d1059ef9be628715817a3747999e61fdba971dd8fc3a4f1cabd14
+  data.tar.gz: c3692202b97ad9e8c2ba501a1b033b5b2e6fa2cad0de41b6bdbc9f607131be2d43b11694d2f7c8fd85103a93ae2c0dff6c136d6948967e8177fcd91fc57dfbcd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Rage Corp
+
+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,190 @@
+# Rage
+
+**Clean Architecture Light for Rails.** Business logic in testable use cases, thin controllers, and models free of callbacks.
+
+## Core concepts
+
+- **Controllers** only orchestrate — no business logic
+- **Models** stay clean — no business callbacks
+- **Use cases** hold all logic, with injected dependencies and typed results
+
+## Setup
+
+```bash
+bundle install
+rails g rage:install
+```
+
+Creates `config/initializers/rage.rb`, `app/use_cases/`, `app/deps/`, and injects `include Rage::Controller` into `ApplicationController`.
+
+---
+
+## Components
+
+### `Rage::Result` — typed result object
+
+```ruby
+result = Rage::Result.success(order)
+result.success?  # => true
+result.value     # => order
+
+result = Rage::Result.failure(["Validation error"])
+result.failure?  # => true
+result.errors    # => ["Validation error"]
+```
+
+---
+
+### `Rage::UseCase::Base` — use cases
+
+```ruby
+class CreateOrder < Rage::UseCase::Base
+  use_case_symbol :create_order
+  deps :order_store, :notifications  # injected by symbol
+
+  def call(params = {})
+    order = order_store.build(params)
+    return failure(order.errors) unless order_store.save(order)
+    notifications.notify(:order_created, order)
+    success(order)
+  end
+end
+```
+
+Build and run manually:
+
+```ruby
+use_case = Rage::UseCase::Base.build(:create_order)
+result = use_case.call(reference: "REF-1", total_cents: 1000)
+```
+
+---
+
+### `Rage::Container` — dependency registration
+
+```ruby
+Rage.register(:order_store, MyApp::Deps::OrderStore.new)
+Rage.register_ar(:user_store, User)  # automatic ActiveRecord wrapper
+Rage.resolve(:order_store)
+```
+
+---
+
+### `Rage::Controller` — thin controller mixin
+
+```ruby
+def create
+  run :users_register, register_params,
+    success: ->(r) { session[:user_id] = r.value[:user].id; redirect_to root_path, notice: "Created." },
+    failure: ->(r) { flash_errors(r); render :new, status: :unprocessable_entity }
+end
+```
+
+- `run(symbol, params, success:, failure:)` — runs the use case and calls the matching block
+- `run_result(symbol, params)` — runs and returns the `Result` directly
+- `flash_errors(result)` — sets `flash.now[:alert]` from `result.errors`
+
+---
+
+### `Rage::EventPublisher` — domain events
+
+Every use case automatically publishes an event when it finishes. Other use cases subscribe to react:
+
+```ruby
+class Notifications::SendPostCreatedEmail < Rage::UseCase::Base
+  use_case_symbol :send_post_created_email
+  deps :mailer
+  subscribe :posts_create  # runs when :posts_create event is published
+
+  def call(payload = {})
+    return success unless payload[:success]
+    mailer.send_post_created(payload[:value][:post])
+    success
+  end
+end
+```
+
+Subscribe to multiple events or everything:
+
+```ruby
+subscribe :post_created, :post_updated
+subscribe :all  # payload includes :event with the event name
+```
+
+Opt out of auto-publish for a specific use case:
+
+```ruby
+skip_auto_publish
+```
+
+---
+
+### Orchestration — use cases calling use cases
+
+```ruby
+class CreateOrderWithNotification < Rage::UseCase::Base
+  use_case_symbol :create_order_with_notification
+  deps :order_store
+  use_cases :orders_create, :notifications_send
+
+  def call(params = {})
+    result = orders_create.call(params)
+    return result unless result.success?
+    notifications_send.call(order_id: result.value[:order].id, type: :order_created)
+    result
+  end
+end
+```
+
+---
+
+## Generators
+
+| Command | What it does |
+|---|---|
+| `rails g rage:install` | Initial setup (initializer, directories, controller mixin) |
+| `rails g rage:scaffold Post title:string` | Full CRUD: model, use cases, dep, controller, views, routes |
+| `rails g rage:scaffold Post title:string --api` | Same but API-only (JSON responses) |
+| `rails g rage:scaffold Post title:string --skip-model` | Skip model/migration if it already exists |
+| `rails g rage:use_case CreateOrder` | Generates a base use case file |
+| `rails g rage:dep post_store` | Generates a dep class by scanning method calls in use cases |
+| `rails g rage:ar_dep post_store Post` | Generates a dep that wraps an ActiveRecord model |
+
+---
+
+## Testing
+
+```ruby
+# spec/rails_helper.rb
+require "rage/rspec_matchers"
+require "rage/fake_event_publisher"
+```
+
+**Result matchers:**
+
+```ruby
+expect(result).to succeed_with(post: a_kind_of(Post))
+expect(result).to fail_with_errors(["Not found"])
+```
+
+**Fake event publisher:**
+
+```ruby
+publisher = Rage::FakeEventPublisher.new
+Rage.register(:event_publisher, publisher)
+# ... run use case ...
+expect(publisher.published).to include(hash_including(event: :post_created))
+publisher.clear
+```
+
+---
+
+## Documentation
+
+- [`doc/REFERENCE.md`](doc/REFERENCE.md) — Full API reference with all options and examples
+- [`doc/DOCUMENTATION.md`](doc/DOCUMENTATION.md) — Detailed behaviour (use cases, deps, events, config)
+- [`doc/DAY_OF_WORK.md`](doc/DAY_OF_WORK.md) — Quick reference for common tasks
+
+## License
+
+MIT

data/lib/generators/rage_arch/ar_dep_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rage_arch/dep_scanner"
+
+module RageArch
+  module Generators
+    class ArDepGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :symbol_arg, type: :string, required: true, banner: "SYMBOL"
+      argument :model_arg, type: :string, required: true, banner: "MODEL"
+
+      desc "Create a dep class that wraps an Active Record model (build, find, save, update, destroy, list). Scans use cases for extra method calls and adds stubs for them. Example: rails g rage_arch:ar_dep post_store Post"
+      def create_ar_dep
+        @extra_methods = extra_methods
+        template "ar_dep.rb.tt", File.join("app/deps", module_dir, "#{dep_file_name}.rb")
+        say "Register in config/initializers/rage_arch.rb: Rage.register(:#{symbol_name}, #{full_class_name}.new)", :green
+      end
+
+      STANDARD_AR_METHODS = %i[build find save update destroy list].freeze
+
+      # Methods that use cases call on this dep but are not in the standard AR adapter
+      def extra_methods
+        detected = scanner.methods_for(symbol_name).to_a
+        (detected - STANDARD_AR_METHODS).sort
+      end
+
+      def symbol_name
+        symbol_arg.to_s.underscore
+      end
+
+      def model_name
+        model_arg.camelize
+      end
+
+      def module_dir
+        inferred_module_dir || use_case_folder
+      end
+
+      def module_name
+        module_dir.camelize
+      end
+
+      def use_case_folder
+        scanner.folder_for(symbol_name)
+      end
+
+      def inferred_module_dir
+        entity = symbol_name.split("_").first
+        entity.pluralize
+      end
+
+      def dep_file_name
+        symbol_name
+      end
+
+      def class_name
+        symbol_name.camelize
+      end
+
+      def full_class_name
+        "#{module_name}::#{class_name}"
+      end
+
+      def scanner
+        @scanner ||= begin
+          root = destination_root
+          RageArch::DepScanner.new(File.join(root, "app", "use_cases")).tap(&:scan)
+        end
+      end
+    end
+  end
+end

data/lib/generators/rage_arch/dep_generator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rage_arch/dep_scanner"
+
+module RageArch
+  module Generators
+    class DepGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :symbol_arg, type: :string, required: true, banner: "SYMBOL"
+      argument :class_name_arg, type: :string, optional: true, banner: "[CLASS_NAME]",
+        default: nil
+
+      desc "Create a dep class in app/deps/, grouped by folder. The folder is inferred from the symbol first (post_store → posts, like_store → likes). If the symbol has no clear entity, the folder is taken from use cases that reference it. Optional CLASS_NAME is the generated class (e.g. CsvPostStore); default is SYMBOL.camelize. If the file already exists, only adds stub methods that are missing (detected from use cases but not yet in the class)."
+      def create_dep
+        @methods = detected_methods
+        if @methods.empty?
+          say "No method calls found for dep :#{symbol_name} in app/use_cases/. Creating with a single stub.", :yellow
+          @methods = [:call]
+        end
+        target_path = File.join("app/deps", module_dir, "#{dep_file_name}.rb")
+        if File.exist?(File.join(destination_root, target_path))
+          add_missing_methods_only(target_path)
+        else
+          template "dep.rb.tt", target_path
+        end
+      end
+
+      # When the dep file already exists, parse it for existing method names and insert only stubs for missing ones.
+      def add_missing_methods_only(relative_path)
+        full_path = File.join(destination_root, relative_path)
+        content = File.read(full_path)
+        existing = content.scan(/^\s+def\s+(\w+)\s*[\(\s]/m).flatten.uniq.map(&:to_sym)
+        missing = @methods - existing
+        if missing.empty?
+          say "All detected methods already present in #{relative_path}.", :green
+          return
+        end
+        indent = content[/^(\s+)def\s+\w+/m, 1] || "  "
+        stubs = missing.map { |m| method_stub(m, indent) }.join("\n")
+        # Insert before the class's closing end (last indented "end" before the file's final "end").
+        lines = content.lines
+        insert_at = lines.length - 1
+        insert_at -= 1 while insert_at >= 0 && lines[insert_at] =~ /^\s*$/
+        insert_at -= 1 while insert_at > 0 && lines[insert_at] !~ /^\s+end\s*$/
+        new_content = lines[0...insert_at].join + "\n#{stubs}\n" + lines[insert_at..].join
+        File.write(full_path, new_content)
+        say "Added #{missing.size} method(s) to #{relative_path}: #{missing.map(&:to_s).join(', ')}", :green
+      end
+
+      def method_stub(method_name, indent = "  ")
+        body_indent = indent + "  "
+        <<~RUBY.strip
+          #{indent}def #{method_name}(*args, **kwargs)
+          #{body_indent}# TODO: implement
+          #{body_indent}raise NotImplementedError, "#{full_class_name}##{method_name}"
+          #{indent}end
+        RUBY
+      end
+
+      def symbol_name
+        symbol_arg.to_s.underscore
+      end
+
+      # Folder from use cases that reference this symbol (e.g. likes/create.rb → "likes"), or inferred from symbol.
+      # Prefer inferred from symbol (post_store → posts) so the dep lives with its domain, not only where it's referenced.
+      def module_dir
+        inferred_module_dir || use_case_folder
+      end
+
+      # Module name for the class (e.g. Likes, Posts). Matches Zeitwerk: app/deps/likes/ → Likes::
+      def module_name
+        module_dir.camelize
+      end
+
+      # When use cases in app/use_cases/likes/*.rb reference this symbol, returns "likes"
+      def use_case_folder
+        scanner.folder_for(symbol_name)
+      end
+
+      # Fallback when no use case references the symbol: like_store → "likes", post_store → "posts"
+      def inferred_module_dir
+        entity = symbol_name.split("_").first
+        entity.pluralize
+      end
+
+      def class_name
+        if class_name_arg.present?
+          class_name_arg.camelize
+        else
+          symbol_name.camelize
+        end
+      end
+
+      def dep_file_name
+        if class_name_arg.present?
+          class_name_arg.underscore
+        else
+          symbol_name
+        end
+      end
+
+      def full_class_name
+        "#{module_name}::#{class_name}"
+      end
+
+      def detected_methods
+        scanner.methods_for(symbol_name).to_a.sort
+      end
+
+      def scanner
+        @scanner ||= begin
+          root = destination_root
+          RageArch::DepScanner.new(File.join(root, "app", "use_cases")).tap(&:scan)
+        end
+      end
+    end
+  end
+end

data/lib/generators/rage_arch/dep_switch_generator.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RageArch
+  module Generators
+    class DepSwitchGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :symbol_arg, type: :string, required: true, banner: "SYMBOL"
+      argument :class_name_arg, type: :string, optional: true, banner: "[CLASS_NAME]",
+        default: nil
+
+      desc "List implementations for a dep symbol and set which one is active in config/initializers/rage_arch.rb"
+      def switch_dep
+        symbol = symbol_name
+        options = build_options(symbol)
+        if options.empty?
+          say "No implementations found for :#{symbol}.", :red
+          say "Create a dep with: rails g rage_arch:dep #{symbol} [ClassName]"
+          say "Or add Rage.register_ar(:#{symbol}, Model) in config/initializers/rage_arch.rb", :red
+          return
+        end
+        chosen = if class_name_arg.present?
+          resolve_requested(symbol, class_name_arg, options)
+        elsif options.size == 1
+          options.first
+        else
+          ask_choice(symbol, options)
+        end
+        return unless chosen
+
+        update_initializer(symbol, chosen)
+        msg = chosen[:type] == :ar ?
+          "Registered :#{symbol} -> Active Record (#{chosen[:model]}) in config/initializers/rage_arch.rb" :
+          "Registered :#{symbol} -> #{chosen[:name]}.new in config/initializers/rage_arch.rb"
+        say msg, :green
+      end
+
+      def symbol_name
+        symbol_arg.to_s.underscore
+      end
+
+      private
+
+      def deps_path
+        File.join(destination_root, "app", "deps")
+      end
+
+      def initializer_path
+        File.join(destination_root, "config", "initializers", "rage.rb")
+      end
+
+      def find_ar_registration(symbol)
+        path = initializer_path
+        return nil unless File.exist?(path)
+        content = File.read(path)
+        # Match active or commented: Rage.register_ar(:post_store, Post) or Rage.register_ar :post_store, Post
+        content.each_line do |line|
+          stripped = line.strip
+          next if stripped.start_with?("#")
+          if stripped =~ /Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)\s*\)/ ||
+             stripped =~ /Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)/
+            return $1
+          end
+        end
+        # Also check commented lines so "default" stays as option after switching away
+        content.each_line do |line|
+          stripped = line.strip.delete_prefix("#").strip
+          next if stripped.empty?
+          if stripped =~ /Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)\s*\)/ ||
+             stripped =~ /Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)/
+            return $1
+          end
+        end
+        nil
+      end
+
+      def find_dep_classes(symbol)
+        return [] unless File.directory?(deps_path)
+
+        Dir[File.join(deps_path, "**", "*.rb")].filter_map do |path|
+          base = File.basename(path, ".rb")
+          # symbol.rb, symbol_suffix.rb (e.g. post_store_mysql), or prefix_symbol.rb (e.g. mysql_post_store)
+          next unless base == symbol || base.start_with?("#{symbol}_") || base.end_with?("_#{symbol}")
+          path_to_class_name(path)
+        end.sort
+      end
+
+      # Derives full constant from path (Zeitwerk convention):
+      # app/deps/posts/post_store.rb → Posts::PostStore
+      # app/deps/post_store.rb (flat, legacy) → PostStore
+      def path_to_class_name(path)
+        base = File.join(destination_root, "app", "deps")
+        relative = path.sub(/\A#{Regexp.escape(base + File::SEPARATOR)}/, "").sub(/\.rb\z/, "")
+        parts = relative.split(File::SEPARATOR).map(&:camelize)
+        if parts.size > 1
+          parts.join("::")
+        else
+          parts.first
+        end
+      end
+
+      def build_options(symbol)
+        options = []
+        ar_model = find_ar_registration(symbol)
+        options << { type: :ar, model: ar_model } if ar_model
+        find_dep_classes(symbol).each { |name| options << { type: :class, name: name } }
+        options
+      end
+
+      def display_option(opt)
+        opt[:type] == :ar ? "Active Record (#{opt[:model]})" : opt[:name]
+      end
+
+      def resolve_requested(symbol, requested, options)
+        raw = requested.to_s.strip
+        return nil if raw.empty?
+        normalized = raw.camelize
+        # Allow "ar" or "activerecord" (any case) to select Active Record default
+        if raw.downcase == "ar" || raw.downcase == "activerecord"
+          opt = options.find { |o| o[:type] == :ar }
+          unless opt
+            say "No Active Record registration found for :#{symbol}. Available: #{options.map { |o| display_option(o) }.join(', ')}", :red
+            return nil
+          end
+          return opt
+        end
+        opt = options.find { |o| o[:type] == :class && (o[:name] == normalized || o[:name].end_with?("::#{normalized}")) }
+        unless opt
+          say "Unknown implementation '#{requested}' for :#{symbol}. Available: #{options.map { |o| display_option(o) }.join(', ')}", :red
+          return nil
+        end
+        opt
+      end
+
+      def ask_choice(symbol, options)
+        say "Implementations for :#{symbol}:", :green
+        options.each_with_index do |opt, i|
+          say "  #{i + 1}. #{display_option(opt)}"
+        end
+        choice = ask("\nWhich one to activate? [1-#{options.size}]: ", :green)
+        idx = choice.to_i
+        unless idx.between?(1, options.size)
+          say "Invalid choice.", :red
+          return nil
+        end
+        options[idx - 1]
+      end
+
+      def update_initializer(symbol, option)
+        path = initializer_path
+        unless File.exist?(path)
+          say "config/initializers/rage_arch.rb not found.", :red
+          return
+        end
+        content = File.read(path)
+        # Comment out every active registration for this symbol (do not remove)
+        content = comment_line_matching(content, symbol, :register)
+        content = comment_line_matching(content, symbol, :register_ar)
+        # Uncomment or add the chosen registration
+        chosen_line = option[:type] == :ar ?
+          "Rage.register_ar(:#{symbol}, #{option[:model]})" :
+          "Rage.register(:#{symbol}, #{option[:name]}.new)"
+        content = uncomment_or_add(content, symbol, option, chosen_line)
+        File.write(path, content)
+      end
+
+      def comment_line_matching(content, symbol, form)
+        if form == :register
+          content.gsub(/^(\s*)(Rage\.register\(:#{Regexp.escape(symbol)},\s*\S+\.new\))\s*$/, '\1# \2')
+        else
+          # register_ar with parens or with space
+          content
+            .gsub(/^(\s*)(Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*\S+\s*\))\s*$/, '\1# \2')
+            .gsub(/^(\s*)(Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*\S+)\s*$/, '\1# \2')
+        end
+      end
+
+      def uncomment_or_add(content, symbol, option, chosen_line)
+        if option[:type] == :ar
+          model = option[:model]
+          # Uncomment if there is a commented register_ar line for this symbol and model
+          content = content.gsub(
+            /^(\s*)#\s*(Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*#{Regexp.escape(model)}\s*\))\s*$/,
+            '\1\2'
+          )
+          content = content.gsub(
+            /^(\s*)#\s*(Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*#{Regexp.escape(model)})\s*$/,
+            '\1\2'
+          )
+        else
+          class_name = option[:name]
+          # Uncomment if there is a commented Rage.register line for this symbol and class
+          content = content.gsub(
+            /^(\s*)#\s*(Rage\.register\(:#{Regexp.escape(symbol)},\s*#{Regexp.escape(class_name)}\.new\))\s*$/,
+            '\1\2'
+          )
+        end
+        # If chosen line is still not present as active, add it inside after_initialize
+        return content if chosen_already_active?(content, symbol, option, chosen_line)
+
+        if content =~ /Rails\.application\.config\.after_initialize\s+do/
+          content = content.sub(/(Rails\.application\.config\.after_initialize\s+do)\n/, "\\1\n  #{chosen_line}\n")
+        else
+          content = content.rstrip + "\n\nRails.application.config.after_initialize do\n  #{chosen_line}\nend\n"
+        end
+        content
+      end
+
+      def chosen_already_active?(content, symbol, option, chosen_line)
+        content.lines.any? do |line|
+          next false if line.lstrip.start_with?("#")
+          if option[:type] == :ar
+            model = option[:model]
+            line.include?("register_ar") && line.include?(":#{symbol}") && line.include?(model.to_s)
+          else
+            line.include?(chosen_line)
+          end
+        end
+      end
+    end
+  end
+end