seams 0.1.0

data/lib/seams/cops/no_cross_engine_model_access.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Seams
+      # Flags references to another engine's data classes from inside an
+      # engine. Engines should communicate via events or via
+      # explicitly-exposed concerns — never by reaching into another
+      # engine's data layer.
+      #
+      # Configured per-engine via the `OwnEngine`, `OtherEngines`, and
+      # `ExposedConcerns` options inside the engine's own .rubocop.yml.
+      #
+      # The cop deliberately ignores Rails framework constants that
+      # every engine exposes (`Engine`, `VERSION`, `ApplicationController`,
+      # `ApplicationRecord`, `ApplicationJob`, `ApplicationMailer`) and
+      # any class whose name ends in one of the configured suffixes
+      # (`Controller`, `Job`, `Mailer`, `Helper`, `Component`, `Engine`).
+      # Concerns (`Billing::Billable`, `Billing::Concerns::Billable`)
+      # are exempt when listed in `ExposedConcerns`.
+      #
+      # `<Engine>::Current` is also exempt by design: every engine ships
+      # its own `ActiveSupport::CurrentAttributes` namespace
+      # (`Auth::Current`, `Accounts::Current`, `Teams::Current`, etc.)
+      # and these per-request state holders are intentionally readable
+      # from anywhere in the host. Treating them as boundary-violations
+      # would force every cross-engine read of per-request identity /
+      # account / team to go through a host-defined shim, which defeats
+      # the purpose of `CurrentAttributes` as a shared per-request bus.
+      # The exception is documented in `doc/CURRENT_ATTRIBUTES.md`.
+      class NoCrossEngineModelAccess < Base
+        MSG = "Engine `%<own>s` must not access `%<const>s` directly. " \
+              "Use an event or a %<other>s-exposed concern instead."
+
+        DEFAULT_IGNORED_LEAF_NAMES = %w[
+          Engine
+          VERSION
+          ApplicationController
+          ApplicationRecord
+          ApplicationJob
+          ApplicationMailer
+          ApplicationHelper
+          ApplicationCable
+          Routes
+          Current
+        ].freeze
+
+        DEFAULT_IGNORED_LEAF_SUFFIXES = %w[
+          Controller
+          Job
+          Mailer
+          Helper
+          Component
+          Channel
+          Engine
+        ].freeze
+
+        def on_const(node)
+          return unless flaggable?(node)
+
+          full_name = node.const_name.to_s
+          top_level = full_name.split("::").first
+
+          assert_own_engine_configured!
+
+          add_offense(
+            node,
+            message: format(MSG, own: own_engine, const: full_name, other: top_level)
+          )
+        end
+
+        private
+
+        def flaggable?(node)
+          parts = const_parts_under_other_engine(node)
+          return false unless parts
+
+          full_name = parts.join("::")
+          return false if exposed_concern?(full_name)
+          return false if framework_constant?(parts)
+          return false if ignored_suffix?(parts.last)
+          return false if inside_defined_check?(node)
+
+          true
+        end
+
+        # `defined?(Teams::Team)` is a soft existence check — the
+        # constant is not actually accessed for value, just probed for
+        # presence. Skip the cop in that case so guards like
+        # `Teams::Team if defined?(Teams::Team)` don't false-fire.
+        # Walks parents up to a few levels so `defined?(Teams::Team.foo)`
+        # (where the const's parent is a `send` node, not the `defined?`)
+        # is also exempted.
+        def inside_defined_check?(node)
+          ancestor = node.parent
+          5.times do
+            return false unless ancestor
+            return true  if ancestor.defined_type?
+
+            ancestor = ancestor.parent
+          end
+          false
+        end
+
+        # Returns the segments of the constant if `node` is the
+        # outermost reference to a multi-segment constant whose first
+        # segment is a sibling engine. Returns nil otherwise.
+        def const_parts_under_other_engine(node)
+          return nil if other_engines.empty?
+          return nil if node.parent&.const_type?
+
+          parts = node.const_name.to_s.split("::")
+          return nil if parts.size < 2
+          return nil unless other_engines.include?(parts.first)
+
+          parts
+        end
+
+        def own_engine
+          name = cop_config["OwnEngine"]
+          name&.to_s
+        end
+
+        def assert_own_engine_configured!
+          return if own_engine && !own_engine.empty?
+
+          raise RuboCop::Error,
+                "Seams/NoCrossEngineModelAccess requires `OwnEngine` to be set in " \
+                ".rubocop.yml so it knows which engine the file under inspection belongs to."
+        end
+
+        def other_engines
+          Array(cop_config["OtherEngines"]).map(&:to_s)
+        end
+
+        def exposed_concern?(full_name)
+          allowlist = Array(cop_config["ExposedConcerns"]).map(&:to_s)
+          allowlist.include?(full_name)
+        end
+
+        def framework_constant?(parts)
+          DEFAULT_IGNORED_LEAF_NAMES.include?(parts.last)
+        end
+
+        def ignored_suffix?(leaf_name)
+          DEFAULT_IGNORED_LEAF_SUFFIXES.any? { |suffix| leaf_name.end_with?(suffix) }
+        end
+      end
+    end
+  end
+end

data/lib/seams/cops.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Entry point for the Seams custom RuboCop cops. Add this line to your
+# host application's .rubocop.yml to enable boundary enforcement:
+#
+#   require:
+#     - seams/cops
+#
+# `require:` (not `plugins:`) is the correct form here because Seams
+# registers its cops via plain `require`, not via the formal RuboCop
+# plugin API. All cops live under the RuboCop::Cop::Seams namespace.
+
+require "rubocop"
+
+require "seams/cops/no_cross_engine_model_access"
+require "seams/cops/no_cross_engine_dependency"
+require "seams/cops/known_queue_names"
+require "seams/cops/migration_comments"

data/lib/seams/event_registry.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "seams/events"
+
+module Seams
+  # Tracks every event name that an engine has declared it emits, along
+  # with the engine that owns it. Acts as the single source of truth for
+  # `bin/rails seams:list` and prevents two engines from claiming the
+  # same event name.
+  module EventRegistry
+    @registry = {}
+    @mutex    = Mutex.new
+
+    class << self
+      def register(name, emitted_by:)
+        Events.assert_valid_name!(name)
+        name = name.to_s
+
+        @mutex.synchronize do
+          existing = @registry[name]
+
+          if existing && existing != emitted_by
+            raise Events::DuplicateEventError,
+                  "Event #{name.inspect} already registered by #{existing.inspect}; " \
+                  "cannot also be registered by #{emitted_by.inspect}"
+          end
+
+          @registry[name] = emitted_by
+        end
+      end
+
+      def registered?(name)
+        @registry.key?(name.to_s)
+      end
+
+      def emitter_of(name)
+        @registry[name.to_s]
+      end
+
+      def all
+        @registry.dup
+      end
+
+      def reset!
+        @mutex.synchronize { @registry.clear }
+      end
+    end
+  end
+end

data/lib/seams/events/adapter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "seams/events"
+
+module Seams
+  module Events
+    # Abstract base class for event-bus adapters. Real adapters wrap a
+    # transport (ActiveSupport::Notifications, an external queue, etc.) and
+    # implement the three primitives below.
+    class Adapter
+      def publish(_event_name, _payload)
+        raise NotImplementedError, "#{self.class} must implement #publish"
+      end
+
+      def subscribe(_event_name, &)
+        raise NotImplementedError, "#{self.class} must implement #subscribe"
+      end
+
+      def unsubscribe(_subscriber)
+        raise NotImplementedError, "#{self.class} must implement #unsubscribe"
+      end
+    end
+  end
+end

data/lib/seams/events/adapters/active_support.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/isolated_execution_state"
+require "active_support/notifications"
+require "seams/events/adapter"
+
+module Seams
+  module Events
+    module Adapters
+      # Default in-process adapter, backed by ActiveSupport::Notifications.
+      # Suitable for monolithic deployments — every engine in the host app
+      # shares the same process, so subscribers fire synchronously after
+      # the publisher's call returns.
+      class ActiveSupport < Seams::Events::Adapter
+        def publish(event_name, payload)
+          payload = { payload: payload } unless payload.is_a?(Hash)
+          ::ActiveSupport::Notifications.instrument(event_name, payload)
+        end
+
+        def subscribe(event_name, &)
+          ::ActiveSupport::Notifications.subscribe(event_name, &)
+        end
+
+        def unsubscribe(subscriber)
+          ::ActiveSupport::Notifications.unsubscribe(subscriber)
+        end
+      end
+    end
+  end
+end

data/lib/seams/events/publisher.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "seams/events"
+require "seams/event_registry"
+
+module Seams
+  module Events
+    # Public API for publishing and subscribing to inter-engine events.
+    #
+    # Engines should always go through this module rather than calling the
+    # underlying adapter directly — it enforces the naming convention,
+    # checks the EventRegistry, and gives subscribers a simple
+    # block-takes-payload interface regardless of which adapter is in use.
+    #
+    # Subscribers run **synchronously** in the publisher's thread (the
+    # default ActiveSupport::Notifications adapter has no other mode).
+    # They should therefore enqueue background jobs for any side effect
+    # that talks to the network or could fail — never perform the side
+    # effect inline. Seams does not enforce this; treat it as a
+    # convention that the boundary review catches.
+    module Publisher
+      class << self
+        def publish(event_name, payload = {})
+          Events.assert_valid_name!(event_name)
+          name = event_name.to_s
+
+          unless EventRegistry.registered?(name)
+            raise UnregisteredEventError,
+                  "Event #{name.inspect} has not been registered. " \
+                  "Declare it in the engine that emits it via " \
+                  "Seams::EventRegistry.register(#{name.inspect}, emitted_by: '<EngineName>')."
+          end
+
+          adapter.publish(name, payload)
+        end
+
+        def subscribe(event_name, &)
+          Events.assert_valid_name!(event_name)
+          name = event_name.to_s
+          subscriptions << name unless subscriptions.include?(name)
+
+          adapter.subscribe(name) do |*args|
+            yield(args.last)
+          end
+        end
+
+        # Idempotent variant of #subscribe. The first call attaches and
+        # remembers the (key, event_name) pair on Seams::Events::Publisher
+        # itself — a Rails autoreload that re-evaluates the subscriber
+        # class file does NOT lose this state, because Publisher is in
+        # the gem and isn't reloaded. Subsequent calls with the same
+        # (key, event_name) are no-ops, preventing the "welcome email
+        # fires N times after N reloads" bug.
+        #
+        # Synchronized so concurrent boot threads (e.g. Puma cluster
+        # pre-fork) can't race-attach the same subscriber twice.
+        #
+        # CAVEAT — Rails autoreload staleness:
+        # The block passed here closes over its lexical binding, which
+        # in practice means the subscriber CLASS object as it existed
+        # when +attach!+ first ran. After Rails reloads the subscriber
+        # file, the constant points at a fresh class object, but THIS
+        # block still calls into the old one — so edits to the
+        # subscriber's methods are invisible until a full server
+        # restart. For new code, prefer #attach_class which re-resolves
+        # the constant on every dispatch and so is reload-safe.
+        #
+        # Use a per-subscriber-class symbol as the key:
+        #
+        #   Publisher.attach_once(:notifications_auth_subscriber,
+        #     "identity.signed_up.auth") { |payload| ... }
+        def attach_once(key, event_name, &)
+          attach_once_mutex.synchronize do
+            attached_keys[[key, event_name.to_s]] ||= subscribe(event_name, &)
+          end
+        end
+
+        # Reload-safe alternative to #attach_once. Stores the subscriber
+        # class as a STRING name and re-resolves +Object.const_get+ on
+        # every dispatch — so when Rails autoreload swaps the constant
+        # for a freshly-loaded class object, the next event reaches the
+        # new code without a server restart.
+        #
+        # The +class_name+ MUST be a String (e.g. "Notifications::AuthSubscriber").
+        # Passing the class object itself defeats the fix: it captures a
+        # reference to the pre-reload object and exhibits exactly the
+        # staleness bug this method exists to avoid.
+        #
+        # The named class method is invoked via +send+, so it may be
+        # +private+ — keeping subscribers' handlers out of their public
+        # surface. Idempotent on (key, event_name) like #attach_once.
+        #
+        # Example:
+        #
+        #   Publisher.attach_class(
+        #     :notifications_auth_subscriber,
+        #     "identity.signed_up.auth",
+        #     class_name:  "Notifications::AuthSubscriber",
+        #     method_name: :handle_signed_up
+        #   )
+        def attach_class(key, event_name, class_name:, method_name:)
+          unless class_name.is_a?(String)
+            raise ArgumentError,
+                  "attach_class requires class_name as a String (got #{class_name.class}). " \
+                  "Passing the class object captures a stale reference across Rails reloads — " \
+                  "the very bug this method exists to prevent."
+          end
+
+          method_symbol = method_name.to_sym
+
+          attach_once_mutex.synchronize do
+            attached_keys[[key, event_name.to_s]] ||= subscribe(event_name) do |payload|
+              Object.const_get(class_name).send(method_symbol, payload)
+            end
+          end
+        end
+
+        def unsubscribe(subscriber)
+          adapter.unsubscribe(subscriber)
+        end
+
+        # Internal — exposed for spec teardown only.
+        def attached_keys
+          @attached_keys ||= {}
+        end
+
+        def attach_once_mutex
+          @attach_once_mutex ||= Mutex.new
+        end
+
+        # Returns the list of event names that engines have subscribed
+        # to during this process's lifetime. Useful for reporting and
+        # for the post-boot validation hook below.
+        def subscriptions
+          @subscriptions ||= []
+        end
+
+        # Walks every subscription and returns the names that no engine
+        # has registered as an emitted event. Hosts can call this from
+        # an after_initialize block (or in a CI smoke test) to catch
+        # typos like subscribing to "identity.signed_up.atuh".
+        def orphan_subscriptions
+          subscriptions.reject { |name| EventRegistry.registered?(name) }.uniq
+        end
+
+        def adapter
+          @adapter ||= build_adapter
+        end
+
+        # Tears down everything Publisher has registered with the
+        # adapter and clears the bookkeeping. Without the unsubscribe
+        # step, ActiveSupport::Notifications keeps the prior process's
+        # subscribers alive in its global registry — so test runs that
+        # call +reset!+ between examples accumulate stale subscribers
+        # that fire (and may raise on now-gone constants) on every
+        # publish in the next example.
+        def reset!
+          @attached_keys&.each_value do |subscriber|
+            adapter.unsubscribe(subscriber) if subscriber
+          end
+          @adapter       = nil
+          @subscriptions = nil
+          @attached_keys = nil
+        end
+
+        private
+
+        def build_adapter
+          klass_name = Seams.configuration.event_bus_adapter
+          Object.const_get(klass_name).new
+        rescue NameError => e
+          raise Seams::ConfigurationError,
+                "Event bus adapter #{klass_name.inspect} could not be loaded: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/seams/events.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Seams
+  # Events module — public API for inter-engine communication.
+  #
+  # Engines publish domain events through Seams::Events::Publisher and
+  # subscribe to events from other engines via the same module. Subscribers
+  # are expected to enqueue background jobs rather than perform side
+  # effects synchronously, so that the publisher's transaction can commit
+  # quickly and side effects can retry independently.
+  module Events
+    class Error < Seams::Error; end
+
+    # Raised when an event name is published that no engine has registered.
+    class UnregisteredEventError < Error; end
+
+    # Raised when two engines try to register the same event name.
+    class DuplicateEventError < Error; end
+
+    # Raised when an event name doesn't follow the resource.action.engine
+    # convention (e.g., "subscription.created.billing").
+    class InvalidEventNameError < Error; end
+
+    # Three dot-separated segments, lowercase, snake_case allowed.
+    NAME_PATTERN = /\A[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\z/
+
+    def self.valid_name?(name)
+      NAME_PATTERN.match?(name.to_s)
+    end
+
+    def self.assert_valid_name!(name)
+      return if valid_name?(name)
+
+      raise InvalidEventNameError,
+            "Event name #{name.inspect} must follow resource.action.engine " \
+            "(e.g. subscription.created.billing)"
+    end
+  end
+end