railsmith 1.0.0

data/lib/generators/railsmith/operation/operation_generator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "active_support/core_ext/string/inflections"
+
+module Railsmith
+  module Generators
+    # Scaffolds a domain operation class that returns `Railsmith::Result`.
+    #
+    # Example:
+    # - rails g railsmith:operation Billing::Invoices::Create
+    #   -> Billing::Operations::Invoices::Create
+    #
+    # Namespaced domain:
+    # - rails g railsmith:operation Admin::Billing::Invoices::Create --domain=Admin::Billing
+    class OperationGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :domains_path,
+                   type: :string,
+                   default: "app/domains",
+                   desc: "Base path where domains live"
+
+      class_option :domain,
+                   type: :string,
+                   default: nil,
+                   desc: "Domain module for namespaced domains (e.g. Admin::Billing)"
+
+      def create_operation
+        relative_target = File.join(options.fetch(:domains_path), target_file)
+        return if skip_existing_file?(relative_target)
+
+        empty_directory File.dirname(File.join(destination_root, relative_target))
+        template "operation.rb.tt", relative_target
+      end
+
+      private
+
+      def skip_existing_file?(relative_path)
+        absolute = File.join(destination_root, relative_path)
+        return false unless File.exist?(absolute)
+        return false if options[:force]
+
+        say_status(
+          :skip,
+          "#{relative_path} already exists (use --force to overwrite)",
+          :yellow
+        )
+        true
+      end
+
+      def domain_modules
+        explicit = options[:domain].to_s.strip
+        return explicit.split("::") unless explicit.empty?
+
+        [class_name.split("::").first]
+      end
+
+      def operation_modules
+        parts = class_name.split("::")
+        return [] if parts.length < 2
+
+        remaining = parts.drop(domain_modules.length)
+        remaining[0...-1]
+      end
+
+      def operation_class_name
+        class_name.split("::").last
+      end
+
+      def target_file
+        File.join(domain_file_path, "operations", *operation_file_segments, "#{file_name}.rb")
+      end
+
+      def domain_file_path
+        domain_modules.map(&:underscore).join("/")
+      end
+
+      def operation_file_segments
+        operation_modules.map(&:underscore)
+      end
+
+      def declared_modules
+        domain_modules + ["Operations"] + operation_modules
+      end
+    end
+  end
+end

data/lib/generators/railsmith/operation/templates/operation.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+<% declared_modules.each do |mod| -%>
+module <%= mod %>
+<% end -%>
+  class <%= operation_class_name %>
+    def self.call(params: {}, context: {})
+      new(params:, context:).call
+    end
+
+    attr_reader :params, :context
+
+    def initialize(params:, context:)
+      @params = Railsmith.deep_dup(params || {})
+      @context = Railsmith.deep_dup(context || {})
+    end
+
+    def call
+      current_domain = Railsmith::DomainContext.normalize_current_domain(context[:current_domain])
+
+      Railsmith::Result.success(value: { current_domain: current_domain })
+    end
+  end
+<% (declared_modules.length - 1).downto(0) do -%>
+end
+<% end -%>
+

data/lib/railsmith/arch_checks/cli.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Railsmith
+  module ArchChecks
+    # Runs architecture checks driven by ENV and prints a report to +output+.
+    # Returns 0 when the scan is clean or warn-only mode allows violations, and 1
+    # when fail-on is enabled and violations exist.
+    class Cli
+      def self.run(env: ENV, output: $stdout, warn_proc: Kernel.method(:warn))
+        new(env: env, output: output, warn_proc: warn_proc).run
+      end
+
+      def initialize(env:, output:, warn_proc:)
+        @env = env
+        @output = output
+        @warn_proc = warn_proc
+      end
+
+      # @return [Integer] 0 or 1
+      def run
+        format_sym = normalized_format
+        paths = paths_list
+        fail_on = fail_on_violations?
+        checked_files, violations = scan(paths)
+        report = Railsmith::ArchReport.new(violations: violations, checked_files: checked_files)
+        emit_report(format_sym, report)
+        status_for(fail_on, report)
+      end
+
+      private
+
+      def normalized_format
+        raw = @env.fetch("RAILSMITH_FORMAT", "text").downcase.strip
+        unless %w[text json].include?(raw)
+          @warn_proc.call("railsmith:arch_check — invalid RAILSMITH_FORMAT=#{raw.inspect}, using text")
+          raw = "text"
+        end
+        raw.to_sym
+      end
+
+      def paths_list
+        @env.fetch("RAILSMITH_PATHS", "app/controllers").split(",").map(&:strip)
+      end
+
+      def fail_on_violations?
+        strict = @env.fetch("RAILSMITH_FAIL_ON_ARCH_VIOLATIONS", "").strip.downcase
+        if %w[true 1 yes].include?(strict)
+          true
+        elsif strict.empty?
+          Railsmith.configuration.fail_on_arch_violations
+        else
+          false
+        end
+      end
+
+      def scan(paths)
+        checkers = [
+          Railsmith::ArchChecks::DirectModelAccessChecker.new,
+          Railsmith::ArchChecks::MissingServiceUsageChecker.new
+        ]
+        paths.each_with_object([[], []]) do |path, (checked_files, violations)|
+          next unless Dir.exist?(path)
+
+          checked_files.concat(Dir.glob(File.join(path, "**", "*_controller.rb")))
+          checkers.each { |checker| violations.concat(checker.check(path: path)) }
+        end
+      end
+
+      def emit_report(format_sym, report)
+        out_string = format_sym == :json ? report.as_json : report.as_text
+        @output.puts out_string
+      end
+
+      def status_for(fail_on, report)
+        fail_on && !report.clean? ? 1 : 0
+      end
+    end
+  end
+end

data/lib/railsmith/arch_checks/direct_model_access_checker.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Railsmith
+  module ArchChecks
+    # Scans controller source files for direct ActiveRecord model access.
+    #
+    # Flags lines like +User.find(params[:id])+ or +Post.where(active: true)+
+    # that bypass the service layer. The check is heuristic: it detects
+    # CamelCase class names followed by common AR query/persistence methods,
+    # excluding well-known non-model classes (Rails, Time, JSON, etc.).
+    #
+    # Usage:
+    #   checker = Railsmith::ArchChecks::DirectModelAccessChecker.new
+    #   violations = checker.check(path: "app/controllers")
+    class DirectModelAccessChecker
+      AR_METHODS = %w[
+        find find_by find_by! find_or_create_by find_or_initialize_by
+        where order select limit offset joins includes eager_load preload
+        all first last count sum average minimum maximum
+        create create! update update_all destroy destroy_all delete delete_all
+        exists? any? none? many? pluck ids
+      ].freeze
+
+      # Well-known non-model CamelCase roots frequently seen in controllers.
+      NON_MODEL_CLASSES = %w[
+        Rails I18n Time Date DateTime ActiveRecord ApplicationRecord ActiveModel
+        ActionController ApplicationController ActionDispatch AbstractController
+        ActionView ActionMailer ActiveJob ActiveSupport ActiveStorage
+        Integer Float String Hash Array Symbol Numeric BigDecimal
+        File Dir IO URI URL Net HTTP JSON YAML CSV
+        Logger Thread Fiber Mutex Proc Method Class Module Object BasicObject
+      ].freeze
+
+      AR_METHODS_PATTERN = AR_METHODS.map { |m| Regexp.escape(m) }.join("|")
+
+      # Matches: CamelCase class name, dot, AR method, not followed by identifier chars.
+      # The negative lookahead `(?=[^a-zA-Z0-9_]|$)` prevents `find` matching `finder`.
+      DETECT_RE = /
+        \b
+        ([A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*)   (?# class name, possibly namespaced)
+        \.
+        (#{AR_METHODS_PATTERN})                          (?# AR method)
+        (?=[^a-zA-Z0-9_]|$)                             (?# not followed by identifier chars)
+      /x
+
+      # @param path [String] directory to scan (recursively for *_controller.rb files)
+      # @return [Array<Violation>]
+      def check(path:)
+        Dir.glob(File.join(path, "**", "*_controller.rb"))
+           .flat_map { |file| check_file(file) }
+      end
+
+      # @param file [String] path to a single Ruby source file
+      # @return [Array<Violation>]
+      def check_file(file)
+        violations = []
+        File.foreach(file).with_index(1) do |raw_line, lineno|
+          line = raw_line.strip
+          violations.concat(line_violations(file, lineno, line)) unless comment_line?(line)
+        end
+        violations
+      end
+
+      private
+
+      def line_violations(file, lineno, line)
+        line.scan(DETECT_RE).filter_map do |class_name, method_name|
+          next if excluded_class?(class_name)
+
+          build_violation(file, lineno, class_name, method_name)
+        end
+      end
+
+      def build_violation(file, lineno, class_name, method_name)
+        Violation.new(
+          :direct_model_access,
+          file,
+          lineno,
+          "Direct model access: `#{class_name}.#{method_name}` — route through a service instead",
+          :warn
+        )
+      end
+
+      def comment_line?(stripped)
+        stripped.start_with?("#")
+      end
+
+      def excluded_class?(class_name)
+        root = class_name.split("::").first
+        NON_MODEL_CLASSES.include?(root)
+      end
+    end
+  end
+end

data/lib/railsmith/arch_checks/missing_service_usage_checker.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Railsmith
+  module ArchChecks
+    # Extracts public instance methods from a controller source line list using indentation.
+    module ControllerActionMethodExtractor
+      class << self
+        # @param lines [Array<String>]
+        # @return [Array<Hash>] each hash has :name, :start (line), :indent, :body (String lines)
+        def extract(lines)
+          methods = []
+          state = initial_state
+
+          lines.each_with_index do |raw, idx|
+            process_line(raw, idx + 1, state, methods)
+          end
+
+          methods
+        end
+
+        private
+
+        def initial_state
+          {
+            current: nil,
+            method_indent: nil,
+            class_method_indent: nil,
+            private_section: false
+          }
+        end
+
+        def process_line(raw, lineno, state, methods)
+          indent = raw.length - raw.lstrip.length
+          stripped = raw.strip
+
+          return if stripped.empty? || stripped.start_with?("#")
+
+          detect_class_method_indent(stripped, indent, state)
+          return if visibility_keyword_consumed?(stripped, indent, state)
+
+          handle_def_or_body(stripped, indent, lineno, state, methods)
+        end
+
+        def detect_class_method_indent(stripped, indent, state)
+          return unless state[:current].nil? && state[:class_method_indent].nil?
+          return unless def_or_visibility_start?(stripped)
+
+          state[:class_method_indent] = indent
+        end
+
+        def def_or_visibility_start?(stripped)
+          stripped.match?(/\Adef\s+[a-z_]/) || visibility_keyword_line?(stripped)
+        end
+
+        # @return [Boolean] true if this line was a bare visibility keyword (no further processing)
+        def visibility_keyword_consumed?(stripped, indent, state)
+          return false unless at_class_visibility_indent?(state, indent)
+
+          consume_visibility_keyword?(stripped, state)
+        end
+
+        def at_class_visibility_indent?(state, indent)
+          state[:current].nil? && state[:class_method_indent] && indent == state[:class_method_indent]
+        end
+
+        def consume_visibility_keyword?(stripped, state)
+          if visibility_private_line?(stripped)
+            state[:private_section] = true
+            true
+          elsif visibility_public_line?(stripped)
+            state[:private_section] = false
+            true
+          else
+            false
+          end
+        end
+
+        def handle_def_or_body(stripped, indent, lineno, state, methods)
+          if state[:current].nil? && (m = stripped.match(/\Adef\s+([a-z_]\w*)/))
+            start_method(m, indent, lineno, state) unless state[:private_section]
+          elsif state[:current]
+            continue_or_close_method(stripped, indent, lineno, state, methods)
+          end
+        end
+
+        def start_method(match, indent, lineno, state)
+          state[:current] = { name: match[1], start: lineno, indent: indent, body: [] }
+          state[:method_indent] = indent
+        end
+
+        def continue_or_close_method(stripped, indent, lineno, state, methods)
+          if method_close_line?(stripped) && indent == state[:method_indent]
+            state[:current][:end] = lineno
+            methods << state[:current]
+            state[:current] = nil
+            state[:method_indent] = nil
+          else
+            state[:current][:body] << stripped
+          end
+        end
+
+        def method_close_line?(stripped)
+          stripped.match?(/\Aend(?:\s*#.*)?$/)
+        end
+
+        def visibility_keyword_line?(stripped)
+          visibility_private_line?(stripped) || visibility_public_line?(stripped)
+        end
+
+        def visibility_private_line?(stripped)
+          stripped.match?(/\A(private|protected)(?:\s+#.*)?\z/)
+        end
+
+        def visibility_public_line?(stripped)
+          stripped.match?(/\Apublic(?:\s+#.*)?\z/)
+        end
+      end
+    end
+
+    # Scans public controller action methods for model access without service or operation delegation.
+    #
+    # Flags methods that call ActiveRecord methods directly but contain no reference
+    # to a +*Service+ / +*Operation+ entrypoint (+.new+ / +.call+), or a +::Operations::...+ class
+    # (+.call+ / +.new+), indicating the data-layer interaction has not been routed through the layer.
+    #
+    # Method boundaries use standard 2-space Ruby indentation (RuboCop default).
+    # Methods after a bare +private+ / +protected+ keyword are skipped. Single-line and endless
+    # method definitions are out of scope for this checker.
+    #
+    # Usage:
+    #   checker = Railsmith::ArchChecks::MissingServiceUsageChecker.new
+    #   violations = checker.check(path: "app/controllers")
+    class MissingServiceUsageChecker
+      # *Service / *Operation entrypoints (namespaced tail allowed).
+      SERVICE_OR_OPERATION_RE = /
+        \b
+        (?:[A-Z][A-Za-z0-9]*::)*
+        [A-Z][A-Za-z0-9]*(?:Service|Operation)
+        (?:::[A-Z][A-Za-z0-9]*)*
+        \.(?:new|call)
+        \b
+      /x
+
+      # Domain operations from the generator live under +...+::Operations::...+ (e.g. +Billing::Operations::Invoices::Create.call+).
+      DOMAIN_OPERATION_RE = /
+        \b
+        (?:[A-Z][A-Za-z0-9]*::)+
+        Operations::
+        (?:[A-Z][A-Za-z0-9]*::)*
+        [A-Z][A-Za-z0-9]*
+        \.(?:new|call)
+        \b
+      /x
+
+      # @param path [String] directory to scan (recursively for *_controller.rb files)
+      # @return [Array<Violation>]
+      def check(path:)
+        Dir.glob(File.join(path, "**", "*_controller.rb"))
+           .flat_map { |file| check_file(file) }
+      end
+
+      # @param file [String] path to a single Ruby source file
+      # @return [Array<Violation>]
+      def check_file(file)
+        lines = File.readlines(file, chomp: true)
+        extract_action_methods(lines).filter_map { |method| method_violation(file, method) }
+      end
+
+      private
+
+      def method_violation(file, method)
+        return if method_uses_service?(method)
+        return unless method_accesses_model?(method)
+
+        Violation.new(
+          :missing_service_usage,
+          file,
+          method[:start],
+          "Action `#{method[:name]}` accesses models without delegating to a service class",
+          :warn
+        )
+      end
+
+      def extract_action_methods(lines)
+        ControllerActionMethodExtractor.extract(lines)
+      end
+
+      def method_uses_service?(method)
+        method[:body].any? do |line|
+          SERVICE_OR_OPERATION_RE.match?(line) || DOMAIN_OPERATION_RE.match?(line)
+        end
+      end
+
+      def method_accesses_model?(method)
+        method[:body].any? do |line|
+          next false if line.start_with?("#")
+
+          line.scan(DirectModelAccessChecker::DETECT_RE).any? do |class_name, _method_name|
+            root = class_name.split("::").first
+            !DirectModelAccessChecker::NON_MODEL_CLASSES.include?(root)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/railsmith/arch_checks/violation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Railsmith
+  module ArchChecks
+    # A single architecture rule violation found by static analysis.
+    #
+    # @!attribute rule [r] Symbol identifying the detector rule (e.g. +:direct_model_access+).
+    # @!attribute file [r] Path to the source file containing the violation.
+    # @!attribute line [r] 1-based line number of the offending code.
+    # @!attribute message [r] Human-readable description of the violation.
+    # @!attribute severity [r] +:warn+ (default, non-blocking) or +:error+.
+    Violation = Struct.new(:rule, :file, :line, :message, :severity)
+  end
+end

data/lib/railsmith/arch_checks.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "arch_checks/violation"
+require_relative "arch_checks/direct_model_access_checker"
+require_relative "arch_checks/missing_service_usage_checker"
+require_relative "arch_report"
+require_relative "arch_checks/cli"

data/lib/railsmith/arch_report.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Railsmith
+  # Formats static-analysis violations for human and machine consumption.
+  #
+  # Supports two output formats:
+  # - +as_text+ — multi-line, human-readable report for local runs.
+  # - +as_json+ — single JSON object for CI tooling and log aggregation.
+  #
+  # Usage:
+  #   report = Railsmith::ArchReport.new(violations: violations, checked_files: files)
+  #   puts report.as_text
+  #   # or
+  #   puts report.as_json
+  class ArchReport
+    SEPARATOR = ("=" * 30).freeze
+
+    attr_reader :violations, :checked_files
+
+    # @param violations [Array<ArchChecks::Violation>]
+    # @param checked_files [Array<String>] paths that were analysed
+    def initialize(violations:, checked_files: [])
+      @violations = Array(violations)
+      @checked_files = Array(checked_files)
+    end
+
+    # @return [Boolean] true when no violations were found
+    def clean?
+      violations.empty?
+    end
+
+    # @return [Integer]
+    def violation_count
+      violations.size
+    end
+
+    # Multi-line, human-readable text report.
+    # @return [String]
+    def as_text
+      lines = ["Railsmith Architecture Check", SEPARATOR, summary_line]
+      unless violations.empty?
+        lines << ""
+        violations.each { |v| lines.concat(violation_lines(v)) }
+        lines << ""
+      end
+      lines << footer_line
+      lines.join("\n")
+    end
+
+    # Single JSON object suitable for CI log parsing.
+    # @return [String]
+    def as_json
+      JSON.generate(to_h)
+    end
+
+    # @return [Hash]
+    def to_h
+      { summary: summary_hash, violations: violations.map { |v| violation_to_h(v) } }
+    end
+
+    private
+
+    def summary_hash
+      { checked_files: checked_files.size, violation_count: violations.size, clean: clean? }
+    end
+
+    def violation_to_h(violation)
+      {
+        rule: violation.rule.to_s,
+        file: violation.file,
+        line: violation.line,
+        message: violation.message,
+        severity: violation.severity.to_s
+      }
+    end
+
+    def summary_line
+      file_word      = checked_files.size == 1 ? "file" : "files"
+      violation_word = violations.size    == 1 ? "violation" : "violations"
+      "Checked #{checked_files.size} #{file_word} — #{violations.size} #{violation_word} found"
+    end
+
+    def footer_line
+      clean? ? "OK — no violations found." : "Violations listed above are warnings only (warn-only mode)."
+    end
+
+    def violation_lines(violation)
+      [
+        "  #{violation.file}:#{violation.line}",
+        "    [#{violation.severity.to_s.upcase}] #{violation.rule}: #{violation.message}"
+      ]
+    end
+  end
+end

data/lib/railsmith/base_service/bulk_actions.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Default bulk action implementations.
+    # @api private
+    module BulkActions
+      include BulkParams
+      include BulkExecution
+      include BulkContract
+
+      def bulk_create
+        model_klass = model_class
+        return missing_model_class_result unless model_klass
+
+        bulk_write_operation(model_klass, operation: :bulk_create) do |attributes|
+          record = build_record(model_klass, sanitize_attributes(attributes || {}))
+          persist_write(record, method_name: :save)
+        end
+      end
+
+      def bulk_update
+        model_klass = model_class
+        return missing_model_class_result unless model_klass
+
+        bulk_write_operation(model_klass, operation: :bulk_update) do |item|
+          bulk_update_one(model_klass, item)
+        end
+      end
+
+      def bulk_destroy
+        model_klass = model_class
+        return missing_model_class_result unless model_klass
+
+        bulk_write_operation(model_klass, operation: :bulk_destroy) do |item|
+          bulk_destroy_one(model_klass, item)
+        end
+      end
+
+      private
+
+      # This project targets Ruby versions where anonymous block forwarding (`&`) may be unavailable.
+      # rubocop:disable Style/ArgumentsForwarding
+      def bulk_write_operation(model_klass, operation:, &block)
+        apply_bulk_operation(
+          model_klass,
+          operation:,
+          items: bulk_items,
+          transaction_mode: bulk_transaction_mode,
+          &block
+        )
+      end
+      # rubocop:enable Style/ArgumentsForwarding
+
+      def bulk_update_one(model_klass, item)
+        id = item.is_a?(Hash) ? item[:id] : nil
+        attributes = item.is_a?(Hash) ? item.fetch(:attributes, {}) : {}
+
+        record_result = find_record(model_klass, id)
+        return record_result if record_result.failure?
+
+        record = record_result.value
+        assign_attributes(record, sanitize_attributes(attributes || {}))
+        persist_write(record, method_name: :save)
+      end
+
+      def bulk_destroy_one(model_klass, item)
+        id = item.is_a?(Hash) ? item[:id] : item
+
+        record_result = find_record(model_klass, id)
+        return record_result if record_result.failure?
+
+        persist_write(record_result.value, method_name: :destroy)
+      end
+    end
+  end
+end