railsmith 1.0.0

data/lib/railsmith/cross_domain_guard.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Detects when a service from one bounded context runs under another domain's
+  # request context (+context[:current_domain]+). Emits non-blocking
+  # +cross_domain.warning.railsmith+ instrumentation by default; optional strict
+  # hook runs when +strict_mode+ is enabled.
+  module CrossDomainGuard
+    def self.emit_if_violation(instance:, action:, configuration: Railsmith.configuration)
+      return unless configuration.warn_on_cross_domain_calls
+
+      mismatch = domain_mismatch(instance)
+      return if mismatch.nil? || allowlisted?(configuration, mismatch)
+
+      publish_violation(instance:, action:, configuration:, mismatch:)
+    end
+
+    def self.allowlisted?(configuration, mismatch)
+      allowed_crossing?(
+        configuration.cross_domain_allowlist,
+        mismatch[:context_domain],
+        mismatch[:service_domain]
+      )
+    end
+
+    def self.publish_violation(instance:, action:, configuration:, mismatch:)
+      payload = build_payload(
+        context_domain: mismatch[:context_domain],
+        service_domain: mismatch[:service_domain],
+        service: instance.class.name,
+        action: action,
+        strict_mode: configuration.strict_mode
+      )
+
+      Instrumentation.instrument("cross_domain.warning", payload)
+      configuration.on_cross_domain_violation&.call(payload) if configuration.strict_mode
+    end
+
+    def self.domain_mismatch(instance)
+      context_domain = DomainContext.normalize_current_domain(instance.context[:current_domain])
+      service_domain = instance.class.service_domain
+      return nil if context_domain.nil? || service_domain.nil?
+      return nil if context_domain == service_domain
+
+      { context_domain: context_domain, service_domain: service_domain }
+    end
+
+    def self.allowed_crossing?(allowlist, from_domain, to_domain)
+      Array(allowlist).any? { |entry| pair_matches?(entry, from_domain, to_domain) }
+    end
+
+    def self.pair_matches?(entry, from_domain, to_domain)
+      case entry
+      when Hash
+        hash_pair_matches?(entry, from_domain, to_domain)
+      when Array
+        array_pair_matches?(entry, from_domain, to_domain)
+      else
+        false
+      end
+    end
+
+    def self.hash_pair_matches?(entry, from_domain, to_domain)
+      from_key = entry[:from] || entry["from"]
+      to_key = entry[:to] || entry["to"]
+      DomainContext.normalize_current_domain(from_key) == from_domain &&
+        DomainContext.normalize_current_domain(to_key) == to_domain
+    end
+
+    def self.array_pair_matches?(entry, from_domain, to_domain)
+      return false unless entry.size == 2
+
+      DomainContext.normalize_current_domain(entry[0]) == from_domain &&
+        DomainContext.normalize_current_domain(entry[1]) == to_domain
+    end
+
+    def self.build_payload(context_domain:, service_domain:, service:, action:, strict_mode:)
+      {
+        event: "cross_domain.warning",
+        context_domain: context_domain,
+        service_domain: service_domain,
+        service: service,
+        action: action,
+        strict_mode: strict_mode,
+        blocking: false,
+        occurred_at: Time.now.utc.iso8601(6)
+      }
+    end
+  end
+end

data/lib/railsmith/cross_domain_warning_formatter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Railsmith
+  # Stable, log- and CI-friendly renderings of cross-domain warning payloads.
+  module CrossDomainWarningFormatter
+    module_function
+
+    CANONICAL_KEYS = %i[
+      event
+      context_domain
+      service_domain
+      service
+      action
+      strict_mode
+      blocking
+      occurred_at
+    ].freeze
+
+    # Single-line JSON with sorted keys for grep and log aggregation.
+    def as_json_line(payload)
+      JSON.generate(ordered_hash(payload))
+    end
+
+    # Space-separated key=value for quick human scanning (values are JSON-encoded).
+    def as_key_value_line(payload)
+      (canonical_kv_parts(payload) + extra_kv_parts(payload)).join(" ")
+    end
+
+    def ordered_hash(payload)
+      ordered = CANONICAL_KEYS.each_with_object({}) do |key, acc|
+        value = payload[key]
+        acc[key.to_s] = json_scalar(value) unless value.nil?
+      end
+      payload.each do |key, value|
+        string_key = key.to_s
+        ordered[string_key] = json_scalar(value) unless ordered.key?(string_key) || value.nil?
+      end
+      ordered
+    end
+
+    def canonical_kv_parts(payload)
+      CANONICAL_KEYS.filter_map do |key|
+        next if payload[key].nil?
+
+        %(#{key}=#{JSON.generate(json_scalar(payload[key]))})
+      end
+    end
+
+    def extra_kv_parts(payload)
+      (payload.keys - CANONICAL_KEYS).sort.filter_map do |key|
+        value = payload[key]
+        next if value.nil?
+
+        %(#{key}=#{JSON.generate(json_scalar(value))})
+      end
+    end
+
+    def json_scalar(value)
+      value.is_a?(Symbol) ? value.to_s : value
+    end
+
+    private_class_method :ordered_hash, :canonical_kv_parts, :extra_kv_parts, :json_scalar
+  end
+end

data/lib/railsmith/deep_dup.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Railsmith — lightweight service/operation framework for Rails.
+module Railsmith
+  module_function
+
+  # Deep-duplicates Hash/Array trees for defensive copies (params/context).
+  def deep_dup(value)
+    case value
+    when Hash
+      value.each_with_object({}) { |(key, item), memo| memo[key] = deep_dup(item) }
+    when Array
+      value.map { |item| deep_dup(item) }
+    else
+      value.dup
+    end
+  rescue TypeError
+    value
+  end
+end

data/lib/railsmith/domain_context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Explicit, immutable value object for domain context propagation.
+  # Build one per request and pass it as `context` into service/operation calls.
+  #
+  # Example:
+  #   ctx = Railsmith::DomainContext.new(current_domain: :billing, meta: { request_id: "abc" })
+  #   BillingService.call(action: :create, params: params, context: ctx.to_h)
+  class DomainContext
+    attr_reader :current_domain, :meta
+
+    def self.normalize_current_domain(value)
+      return nil if value.nil?
+      return nil if value.is_a?(String) && value.strip.empty?
+      return value if value.is_a?(Symbol)
+
+      value.respond_to?(:to_sym) ? value.to_sym : value
+    end
+
+    def initialize(current_domain: nil, meta: {})
+      @current_domain = self.class.normalize_current_domain(current_domain)
+      @meta = (meta || {}).freeze
+      freeze
+    end
+
+    # Serializes to a plain hash suitable for passing into service context.
+    # +current_domain+ is authoritative; meta cannot replace it.
+    def to_h
+      extras =
+        if meta.empty?
+          {}
+        else
+          meta.except(:current_domain, "current_domain")
+        end
+      { current_domain: current_domain }.merge(extras)
+    end
+
+    # Returns true when no domain has been set (allowed in flexible mode).
+    def blank_domain?
+      current_domain.nil?
+    end
+  end
+end

data/lib/railsmith/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Normalized builders for failure payloads.
+  module Errors
+    # A structured error payload used in failure results.
+    class ErrorPayload
+      attr_reader :code, :message, :details
+
+      def initialize(code:, message:, details: nil)
+        @code = code.to_s
+        @message = message.to_s
+        @details = details
+        freeze
+      end
+
+      def to_h
+        payload = { code:, message: }
+        payload[:details] = details unless details.nil?
+        payload
+      end
+
+      def as_json(*)
+        to_h
+      end
+    end
+
+    class << self
+      def validation_error(message: "Validation failed", details: nil)
+        ErrorPayload.new(code: :validation_error, message:, details: details || {})
+      end
+
+      def not_found(message: "Not found", details: nil)
+        ErrorPayload.new(code: :not_found, message:, details: details || {})
+      end
+
+      def conflict(message: "Conflict", details: nil)
+        ErrorPayload.new(code: :conflict, message:, details: details || {})
+      end
+
+      def unauthorized(message: "Unauthorized", details: nil)
+        ErrorPayload.new(code: :unauthorized, message:, details: details || {})
+      end
+
+      def unexpected(message: "Unexpected error", details: nil)
+        ErrorPayload.new(code: :unexpected, message:, details: details)
+      end
+    end
+  end
+end

data/lib/railsmith/instrumentation.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Lightweight instrumentation hook layer for domain-tagged service events.
+  #
+  # Uses ActiveSupport::Notifications when available so events slot naturally
+  # into Rails instrumentation pipelines. Falls back to plain Ruby subscribers
+  # for non-Rails contexts.
+  #
+  # Example (plain Ruby subscriber):
+  #   Railsmith::Instrumentation.subscribe("service.call") do |event, payload|
+  #     Rails.logger.info "[#{payload[:domain]}] #{payload[:service]}##{payload[:action]}"
+  #   end
+  module Instrumentation
+    EVENT_NAMESPACE = "railsmith"
+
+    class << self
+      # Emit a domain-tagged event, yielding to the wrapped block if given.
+      # Payload is always a Hash; a :domain key is expected for domain tagging.
+      # Always dispatches to plain Ruby subscribers; also emits to
+      # ActiveSupport::Notifications when available for Rails integration.
+      def instrument(event_name, payload = {}, &block)
+        full_name = "#{event_name}.#{EVENT_NAMESPACE}"
+        result = nil
+        if active_support_notifications?
+          ActiveSupport::Notifications.instrument(full_name, payload) { result = block&.call }
+        else
+          result = block&.call
+        end
+        dispatch(full_name, payload)
+        result
+      end
+
+      # Register a plain Ruby subscriber for events matching an optional prefix.
+      # Subscriber is called with (event_name, payload).
+      def subscribe(pattern = nil, &block)
+        subscribers << { pattern: pattern, handler: block }
+      end
+
+      # Remove all plain Ruby subscribers (useful in tests).
+      def reset!
+        @subscribers = []
+      end
+
+      private
+
+      def subscribers
+        @subscribers ||= []
+      end
+
+      def active_support_notifications?
+        defined?(ActiveSupport::Notifications)
+      end
+
+      def dispatch(event_name, payload)
+        subscribers.each do |sub|
+          next if sub[:pattern] && !event_name.start_with?(sub[:pattern])
+
+          sub[:handler].call(event_name, payload)
+        end
+      end
+    end
+  end
+end

data/lib/railsmith/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Loads Rake tasks when the gem is used inside a Rails application.
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/railsmith.rake", __dir__)
+    end
+  end
+end

data/lib/railsmith/result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # An immutable success/failure wrapper with a stable serialization contract.
+  class Result
+    def self.success(value: nil, meta: nil)
+      new(success: true, value:, error: nil, meta: meta || {})
+    end
+
+    def self.failure(code: nil, message: nil, details: nil, error: nil, meta: nil)
+      normalized_error =
+        error ||
+        Errors::ErrorPayload.new(
+          code: code || :unexpected,
+          message: message || "Unexpected error",
+          details:
+        )
+
+      new(success: false, value: nil, error: normalized_error, meta: meta || {})
+    end
+
+    private_class_method :new
+
+    def initialize(success:, value:, error:, meta:)
+      @success = success ? true : false
+      @value = value
+      @error = error
+      @meta = meta || {}
+      freeze
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !success?
+    end
+
+    attr_reader :value, :error, :meta
+
+    def code
+      return nil if error.nil?
+
+      error.code
+    end
+
+    def to_h
+      if success?
+        { success: true, value:, meta: }
+      else
+        { success: false, error: error.to_h, meta: }
+      end
+    end
+
+    def as_json(*)
+      to_h
+    end
+  end
+end

data/lib/railsmith/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Railsmith
+  VERSION = "1.0.0"
+end

data/lib/railsmith.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "railsmith/version"
+require_relative "railsmith/configuration"
+require_relative "railsmith/errors"
+require_relative "railsmith/result"
+require_relative "railsmith/deep_dup"
+require_relative "railsmith/domain_context"
+require_relative "railsmith/instrumentation"
+require_relative "railsmith/cross_domain_guard"
+require_relative "railsmith/cross_domain_warning_formatter"
+require_relative "railsmith/base_service"
+
+require_relative "railsmith/railtie" if defined?(Rails::Railtie)
+
+# Entry point for global gem configuration and loading.
+module Railsmith
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/tasks/railsmith.rake

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+namespace :railsmith do
+  desc <<~DESC
+    Run Railsmith architecture checks on controller files and print a report.
+
+    Configuration via environment variables:
+      RAILSMITH_PATHS                    Comma-separated controller directories (default: app/controllers)
+      RAILSMITH_FORMAT                   Output format: "text" or "json" (default: text; invalid values fall back to text with a warning)
+      RAILSMITH_FAIL_ON_ARCH_VIOLATIONS  If set to "true", "1", or "yes", exit 1 when violations exist (overrides config)
+
+    Exit behaviour:
+      Exits 0 in warn-only mode (the default) regardless of violations.
+      Set +Railsmith.configuration.fail_on_arch_violations = true+ or
+      +RAILSMITH_FAIL_ON_ARCH_VIOLATIONS=true+ to exit 1 when violations are found.
+  DESC
+  task :arch_check do
+    require "railsmith"
+    require "railsmith/arch_checks"
+
+    status = Railsmith::ArchChecks::Cli.run
+    exit status unless status.zero?
+  end
+end

data/sig/railsmith.rbs

@@ -0,0 +1,4 @@
+module Railsmith
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: railsmith
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- samaswin
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: Railsmith provides service-layer architecture primitives for domain routing,
+  CRUD/bulk operations, and structured results.
+email:
+- samaswin@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".tool-versions"
+- CHANGELOG.md
+- LICENSE.txt
+- MIGRATION.md
+- README.md
+- Rakefile
+- docs/cookbook.md
+- docs/legacy-adoption.md
+- docs/quickstart.md
+- lib/generators/railsmith/domain/domain_generator.rb
+- lib/generators/railsmith/domain/templates/domain.rb.tt
+- lib/generators/railsmith/install/install_generator.rb
+- lib/generators/railsmith/install/templates/railsmith.rb
+- lib/generators/railsmith/model_service/model_service_generator.rb
+- lib/generators/railsmith/model_service/templates/model_service.rb.tt
+- lib/generators/railsmith/operation/operation_generator.rb
+- lib/generators/railsmith/operation/templates/operation.rb.tt
+- lib/railsmith.rb
+- lib/railsmith/arch_checks.rb
+- lib/railsmith/arch_checks/cli.rb
+- lib/railsmith/arch_checks/direct_model_access_checker.rb
+- lib/railsmith/arch_checks/missing_service_usage_checker.rb
+- lib/railsmith/arch_checks/violation.rb
+- lib/railsmith/arch_report.rb
+- lib/railsmith/base_service.rb
+- lib/railsmith/base_service/bulk_actions.rb
+- lib/railsmith/base_service/bulk_contract.rb
+- lib/railsmith/base_service/bulk_execution.rb
+- lib/railsmith/base_service/bulk_params.rb
+- lib/railsmith/base_service/crud_actions.rb
+- lib/railsmith/base_service/crud_error_mapping.rb
+- lib/railsmith/base_service/crud_model_resolution.rb
+- lib/railsmith/base_service/crud_record_helpers.rb
+- lib/railsmith/base_service/crud_transactions.rb
+- lib/railsmith/base_service/domain_context_propagation.rb
+- lib/railsmith/base_service/dup_helpers.rb
+- lib/railsmith/base_service/validation.rb
+- lib/railsmith/configuration.rb
+- lib/railsmith/cross_domain_guard.rb
+- lib/railsmith/cross_domain_warning_formatter.rb
+- lib/railsmith/deep_dup.rb
+- lib/railsmith/domain_context.rb
+- lib/railsmith/errors.rb
+- lib/railsmith/instrumentation.rb
+- lib/railsmith/railtie.rb
+- lib/railsmith/result.rb
+- lib/railsmith/version.rb
+- lib/tasks/railsmith.rake
+- sig/railsmith.rbs
+homepage: https://github.com/samaswin/railsmith
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/samaswin/railsmith
+  source_code_uri: https://github.com/samaswin/railsmith
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: All-in-one service layer conventions for Rails.
+test_files: []