seams 0.1.0 → 0.2.0

data/lib/seams/cops/no_cross_engine_model_access.rb

@@ -29,7 +29,7 @@ module RuboCop
       # 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`.
+      # The exception is documented in `doc/reference/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."
@@ -57,6 +57,13 @@ module RuboCop
           Engine
         ].freeze
 
+        ASSOCIATION_MACROS = %i[
+          belongs_to
+          has_one
+          has_many
+          has_and_belongs_to_many
+        ].freeze
+
         def on_const(node)
           return unless flaggable?(node)
 
@@ -71,8 +78,79 @@ module RuboCop
           )
         end
 
+        # Association macros name the target class via a `class_name:`
+        # STRING (`belongs_to :account, class_name: "Accounts::Account"`),
+        # which `on_const` cannot see — string literals are not constant
+        # nodes, so this exact pattern used to sail through the cop.
+        # Flag the option when the named class lives in another engine.
+        #
+        # `class_name:` given as a constant is already caught by
+        # `on_const`, so only string values are flagged here (no double
+        # offense). `polymorphic: true` associations are exempt: the
+        # target class is decided at runtime by the owning record.
+        def on_send(node)
+          pair = string_class_name_pair(node)
+          return unless pair
+
+          full_name = pair.value.value.to_s.delete_prefix("::")
+          return unless cross_engine_class_name?(full_name)
+
+          assert_own_engine_configured!
+
+          add_offense(
+            pair,
+            message: format(MSG, own: own_engine, const: full_name,
+                                 other: full_name.split("::").first)
+          )
+        end
+
         private
 
+        # Returns the `class_name: "..."` pair of an association macro
+        # when its value is a string literal worth checking; nil
+        # otherwise (not an association, no options, polymorphic, or a
+        # constant value already covered by `on_const`).
+        def string_class_name_pair(node)
+          options = association_options(node)
+          return nil unless options
+          return nil if polymorphic_option?(options)
+
+          pair = class_name_pair(options)
+          return nil unless pair
+
+          pair.value.str_type? ? pair : nil
+        end
+
+        def association_options(node)
+          return nil unless association_macro?(node)
+
+          options = node.last_argument
+          options if options&.hash_type?
+        end
+
+        def association_macro?(node)
+          node.receiver.nil? && ASSOCIATION_MACROS.include?(node.method_name)
+        end
+
+        def polymorphic_option?(options)
+          options.pairs.any? do |pair|
+            pair.key.sym_type? && pair.key.value == :polymorphic && pair.value.true_type?
+          end
+        end
+
+        def class_name_pair(options)
+          options.pairs.find { |pair| pair.key.sym_type? && pair.key.value == :class_name }
+        end
+
+        def cross_engine_class_name?(full_name)
+          parts = full_name.split("::")
+          return false if parts.size < 2
+          return false unless other_engines.include?(parts.first)
+          return false if exposed_concern?(full_name)
+
+          true
+        end
+
         def flaggable?(node)
           parts = const_parts_under_other_engine(node)
           return false unless parts

data/lib/seams/event_registry.rb

@@ -12,6 +12,18 @@ module Seams
     @mutex    = Mutex.new
 
     class << self
+      # Declare that an engine emits an event. Call this from the engine
+      # that owns the event (typically in its engine.rb), so the event
+      # bus, `bin/rails seams:list`, and the orphan-subscription check
+      # all know it exists.
+      #
+      # @param name [String, Symbol] the event name, +resource.action.engine+ form.
+      # @param emitted_by [String] the owning engine (e.g. "Billing").
+      # @raise [Seams::Events::InvalidEventNameError] if the name is malformed.
+      # @raise [Seams::Events::DuplicateEventError] if another engine already owns it.
+      # @return [String] the owning engine name.
+      # @example
+      #   Seams::EventRegistry.register("invoice.paid.billing", emitted_by: "Billing")
       def register(name, emitted_by:)
         Events.assert_valid_name!(name)
         name = name.to_s
@@ -29,18 +41,25 @@ module Seams
         end
       end
 
+      # @param name [String, Symbol] an event name.
+      # @return [Boolean] whether any engine has registered it.
       def registered?(name)
         @registry.key?(name.to_s)
       end
 
+      # @param name [String, Symbol] an event name.
+      # @return [String, nil] the owning engine, or nil if unregistered.
       def emitter_of(name)
         @registry[name.to_s]
       end
 
+      # @return [Hash{String=>String}] a copy of the full event => owner map.
       def all
         @registry.dup
       end
 
+      # Clear the registry. Intended for test teardown.
+      # @return [void]
       def reset!
         @mutex.synchronize { @registry.clear }
       end

data/lib/seams/events/adapter.rb

@@ -8,14 +8,23 @@ module Seams
     # transport (ActiveSupport::Notifications, an external queue, etc.) and
     # implement the three primitives below.
     class Adapter
+      # Deliver an event (a name plus a Hash payload) to the transport.
+      # @return [void]
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def publish(_event_name, _payload)
         raise NotImplementedError, "#{self.class} must implement #publish"
       end
 
+      # Register a block to run when the named event is published.
+      # @return [Object] a transport-specific subscriber handle.
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def subscribe(_event_name, &)
         raise NotImplementedError, "#{self.class} must implement #subscribe"
       end
 
+      # Detach a previously-registered subscriber (the handle {#subscribe} returned).
+      # @return [void]
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def unsubscribe(_subscriber)
         raise NotImplementedError, "#{self.class} must implement #unsubscribe"
       end

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

@@ -7,21 +7,25 @@ require "seams/events/adapter"
 
 module Seams
   module Events
+    # Namespace for the built-in event-bus adapters.
     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
+        # (see Seams::Events::Adapter#publish)
         def publish(event_name, payload)
           payload = { payload: payload } unless payload.is_a?(Hash)
           ::ActiveSupport::Notifications.instrument(event_name, payload)
         end
 
+        # (see Seams::Events::Adapter#subscribe)
         def subscribe(event_name, &)
           ::ActiveSupport::Notifications.subscribe(event_name, &)
         end
 
+        # (see Seams::Events::Adapter#unsubscribe)
         def unsubscribe(subscriber)
           ::ActiveSupport::Notifications.unsubscribe(subscriber)
         end

data/lib/seams/events/publisher.rb

@@ -20,6 +20,17 @@ module Seams
     # convention that the boundary review catches.
     module Publisher
       class << self
+        # Publish a domain event to every subscriber.
+        #
+        # @param event_name [String, Symbol] the event name, in
+        #   +resource.action.engine+ form (e.g. "subscription.created.billing").
+        # @param payload [Hash] data handed to each subscriber block.
+        # @raise [Seams::Events::InvalidEventNameError] if the name is malformed.
+        # @raise [Seams::Events::UnregisteredEventError] if no engine has
+        #   registered the event via {Seams::EventRegistry.register}.
+        # @return [void]
+        # @example
+        #   Seams::Events::Publisher.publish("invoice.paid.billing", invoice_id: 42)
         def publish(event_name, payload = {})
           Events.assert_valid_name!(event_name)
           name = event_name.to_s
@@ -34,6 +45,18 @@ module Seams
           adapter.publish(name, payload)
         end
 
+        # Subscribe a block to an event. Subscribers run **synchronously**
+        # in the publisher's thread — enqueue a background job for any
+        # network side effect rather than performing it inline. For a
+        # reload-safe, idempotent subscription prefer {attach_class}.
+        #
+        # @param event_name [String, Symbol] the event to listen for.
+        # @yieldparam payload [Hash] the published payload.
+        # @return [Object] an adapter-specific subscriber handle.
+        # @example
+        #   Seams::Events::Publisher.subscribe("identity.signed_up.auth") do |payload|
+        #     WelcomeJob.perform_later(payload[:identity_id])
+        #   end
         def subscribe(event_name, &)
           Events.assert_valid_name!(event_name)
           name = event_name.to_s
@@ -115,6 +138,9 @@ module Seams
           end
         end
 
+        # Detach a subscriber handle from the adapter.
+        # @param subscriber [Object] the handle a subscribe call returned.
+        # @return [void]
         def unsubscribe(subscriber)
           adapter.unsubscribe(subscriber)
         end
@@ -143,6 +169,9 @@ module Seams
           subscriptions.reject { |name| EventRegistry.registered?(name) }.uniq
         end
 
+        # The configured event-bus adapter, instantiated lazily.
+        # @return [Seams::Events::Adapter] the adapter instance.
+        # @raise [Seams::ConfigurationError] if the configured class can't be loaded.
         def adapter
           @adapter ||= build_adapter
         end

data/lib/seams/events.rb

@@ -9,6 +9,7 @@ module Seams
   # effects synchronously, so that the publisher's transaction can commit
   # quickly and side effects can retry independently.
   module Events
+    # Base class for event-bus errors.
     class Error < Seams::Error; end
 
     # Raised when an event name is published that no engine has registered.

data/lib/seams/generators/dummy_app_writer.rb

@@ -59,6 +59,7 @@ module Seams
         write(File.join(engine_path, "spec/dummy/config/application.rb"),  application_rb(engine_module))
         write(File.join(engine_path, "spec/dummy/config/environment.rb"),  environment_rb)
         write(File.join(engine_path, "spec/dummy/config/database.yml"),    database_yml(engine_path))
+        write(File.join(engine_path, "spec/dummy/config/cable.yml"),       cable_yml)
         write(File.join(engine_path, "spec/dummy/config/environments/test.rb"),       test_environment_rb)
         write(File.join(engine_path, "spec/dummy/config/initializers/secret_key.rb"), secret_key_rb)
         write(File.join(engine_path, "spec/dummy/config/routes.rb"), routes_rb(engine_module, mount_at))
@@ -163,6 +164,16 @@ module Seams
         YML
       end
 
+      # solid_cable >= 4.1 reads config/cable.yml eagerly at boot, so the
+      # dummy app must ship one even though engine specs never open a
+      # socket. The in-process test adapter needs no database or server.
+      def cable_yml
+        <<~YML
+          test:
+            adapter: test
+        YML
+      end
+
       def test_environment_rb
         <<~RB
           # frozen_string_literal: true
@@ -251,10 +262,20 @@ module Seams
         # inherit from ::ApplicationController (the seams:engine generator
         # default) can boot inside a request spec. Real hosts will have
         # their own; this is dummy-only.
+        #
+        # `authenticate_identity!` is stubbed as a no-op so engine request
+        # specs pass by default (simulating an authenticated session).
+        # Specs that need to verify the authentication gate should stub or
+        # override this method, or use the `sign_in_as` helper when present.
         <<~RB
           # frozen_string_literal: true
 
           class ApplicationController < ActionController::Base
+            def authenticate_identity!
+              # Stub: always passes in the dummy app. Engine specs that want to
+              # exercise the unauthenticated path should stub this method or
+              # call `sign_in_as` from the authentication test helper.
+            end
           end
         RB
       end

data/lib/seams/generators/follow_up_generator.rb

@@ -67,7 +67,7 @@ module Seams
       # assert_marker_exists!). Splitting them into separate blocks
       # would obscure the "these are the public follow-up generator
       # primitives" grouping. Disable BlockLength for this one block.
-      # rubocop:disable Metrics/BlockLength
+      # rubocop:disable-next Metrics/BlockLength
       no_tasks do
         # Resolve a path inside the host's engines/<this_engine>/.
         # Mirrors the canonical generators' +engine_path+ method but
@@ -130,7 +130,6 @@ module Seams
           MSG
         end
       end
-      # rubocop:enable Metrics/BlockLength
 
       # Subclass override-point. Subclasses define their own public
       # method named `report_summary` (or any other end-of-run name);

data/lib/seams/generators/host_injector.rb

@@ -114,9 +114,16 @@ module Seams
       end
 
       def build_gem_line(name, args, group)
-        version_part = args.first.is_a?(String) ? %(, "#{args.first}") : ""
+        # Every String arg is a version requirement, so a range such as
+        # (">= 7.1", "< 9") is emitted in full.
+        version_part = args.grep(String).map { |req| %(, "#{req}") }.join
         gem_line     = %(gem "#{name}"#{version_part})
-        gem_line     = "group #{group.inspect} do\n  #{gem_line}\nend" if group
+        # group may be a single symbol (:development) or several
+        # (%i[development test] -> `group :development, :test do`).
+        if group
+          groups   = Array(group).map(&:inspect).join(", ")
+          gem_line = "group #{groups} do\n  #{gem_line}\nend"
+        end
         gem_line
       end
     end

data/lib/seams/generators/splicer.rb

@@ -11,8 +11,8 @@ module Seams
     # the whole file. The Splicer is the shared primitive: every
     # follow-up generator funnels through these methods.
     #
-    # See doc/INSERTION_POINTS.md for the marker format spec and
-    # doc/INSERTION_POINTS_CATALOGUE.md for the canonical list of
+    # See doc/reference/INSERTION_POINTS.md for the marker format spec and
+    # doc/reference/INSERTION_POINTS_CATALOGUE.md for the canonical list of
     # markers each engine ships.
     #
     # Example:

data/lib/seams/observability/adapter.rb

@@ -9,22 +9,44 @@ module Seams
     # Datadog, OpenTelemetry, etc.) — engines never speak to those
     # libraries directly.
     class Adapter
+      # Log a debug-level message with structured context.
+      # @param _message [String] the log message.
+      # @param _context [Hash] structured key/value context (engine, actor id, ...).
+      # @return [void]
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def debug(_message, **_context)
         raise NotImplementedError, "#{self.class} must implement #debug"
       end
 
+      # Log an info-level message with structured context.
+      # @param (see #debug)
+      # @return [void]
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def info(_message, **_context)
         raise NotImplementedError, "#{self.class} must implement #info"
       end
 
+      # Log a warn-level message with structured context.
+      # @param (see #debug)
+      # @return [void]
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def warn(_message, **_context)
         raise NotImplementedError, "#{self.class} must implement #warn"
       end
 
+      # Log an error-level message with structured context.
+      # @param (see #debug)
+      # @return [void]
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def error(_message, **_context)
         raise NotImplementedError, "#{self.class} must implement #error"
       end
 
+      # Time the given block and emit the duration as structured context.
+      # @param _operation [String] a label for the timed operation.
+      # @param _context [Hash] structured key/value context.
+      # @return [Object] whatever the block returns.
+      # @raise [NotImplementedError] unless a subclass overrides it.
       def measure(_operation, **_context, &)
         raise NotImplementedError, "#{self.class} must implement #measure"
       end

data/lib/seams/observability.rb

@@ -9,13 +9,19 @@ module Seams
   # logs can be parsed and filtered uniformly by the host application's
   # log aggregator.
   module Observability
+    # Base class for observability errors.
     class Error < Seams::Error; end
 
     class << self
+      # The configured observability adapter, instantiated lazily.
+      # @return [Seams::Observability::Adapter] the adapter instance.
+      # @raise [Seams::ConfigurationError] if the configured class can't be loaded.
       def adapter
         @adapter ||= build_adapter
       end
 
+      # Drop the memoized adapter so the next call rebuilds it. Test hook.
+      # @return [void]
       def reset!
         @adapter = nil
       end

data/lib/seams/permission_registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "seams/permissions"
+
+module Seams
+  # Tracks every ability code that an engine has declared it understands,
+  # along with the engine that owns it. Acts as the single source of truth
+  # for authorisation lookups and prevents two engines from claiming the
+  # same ability code.
+  module PermissionRegistry
+    @registry = {}
+    @mutex    = Mutex.new
+
+    class << self
+      # Declare that an engine understands an ability code. Call this from
+      # the engine that owns the ability so authorisation lookups have a
+      # single source of truth.
+      #
+      # @param ability [String, Symbol] the ability code (e.g. "billing.manage").
+      # @param owned_by [String] the owning engine (e.g. "Billing").
+      # @raise [Seams::Permissions::DuplicateAbilityError] if another engine owns it.
+      # @return [String] the owning engine name.
+      # @example
+      #   Seams::PermissionRegistry.register("billing.manage", owned_by: "Billing")
+      def register(ability, owned_by:)
+        Permissions.assert_valid_name!(ability)
+        ability = ability.to_s
+
+        @mutex.synchronize do
+          existing = @registry[ability]
+
+          if existing && existing != owned_by
+            raise Permissions::DuplicateAbilityError,
+                  "Ability #{ability.inspect} already registered by #{existing.inspect}; " \
+                  "cannot also be registered by #{owned_by.inspect}"
+          end
+
+          @registry[ability] = owned_by
+        end
+      end
+
+      # @param ability [String, Symbol] an ability code.
+      # @return [Boolean] whether any engine has registered it.
+      def registered?(ability)
+        @registry.key?(ability.to_s)
+      end
+
+      # @param ability [String, Symbol] an ability code.
+      # @return [String, nil] the owning engine, or nil if unregistered.
+      def owner_of(ability)
+        @registry[ability.to_s]
+      end
+
+      # @return [Hash{String=>String}] a copy of the full ability => owner map.
+      def all
+        @registry.dup
+      end
+
+      # Clear the registry. Intended for test teardown.
+      # @return [void]
+      def reset!
+        @mutex.synchronize { @registry.clear }
+      end
+    end
+  end
+end

data/lib/seams/permissions.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Seams
+  # Permissions module — public API for authorisation across engines.
+  #
+  # Engines register the ability codes they understand at boot through
+  # Seams::PermissionRegistry, mirroring the event bus. Authorisation is
+  # resolved through Seams::Permissions.can?, which answers from a
+  # code-defined role hierarchy and a host-configurable grant map. Nothing
+  # here enforces permissions on a request; it is the machinery that the
+  # request and controller layers build on in later phases.
+  module Permissions
+    class Error < Seams::Error; end
+
+    # Raised when a permission is checked for an ability that no engine has
+    # registered.
+    class UnregisteredAbilityError < Error; end
+
+    # Raised when two engines try to register the same ability code.
+    class DuplicateAbilityError < Error; end
+
+    # Raised when an ability code doesn't follow the resource.action.engine
+    # convention (e.g., "invoice.read.billing").
+    class InvalidAbilityNameError < Error; end
+
+    # Three dot-separated segments, lowercase, snake_case allowed. Matches
+    # the event name convention so abilities and events read alike.
+    NAME_PATTERN = /\A[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\z/
+
+    # Roles ordered from most to least privileged. Each role inherits every
+    # ability granted to the roles below it (owner ⊇ admin ⊇ member).
+    ROLE_HIERARCHY = %w[owner admin member].freeze
+
+    # A pseudo-role that bypasses every check — used by trusted internal
+    # callers such as background jobs and system actors.
+    SYSTEM_ROLE = "system"
+
+    # Sensible default grant map so `can?` allows things out of the box,
+    # keyed by role. `member` may read; `admin` may manage. `owner`
+    # inherits everything granted to `admin` (and through it `member`)
+    # via ROLE_HIERARCHY, and `system` bypasses checks entirely — so
+    # neither needs its own entry here. Hosts override the whole map
+    # through `Seams.configuration.permission_grants`. The codes mirror
+    # what each canonical engine registers from its engine.rb.
+    DEFAULT_GRANTS = {
+      "member" => %w[
+        identity.read.auth
+        invoice.read.billing
+        subscription.read.billing
+        team.read.teams
+        account.read.accounts
+        membership.read.accounts
+        notification.read.notifications
+      ].freeze,
+      "admin" => %w[
+        identity.manage.auth
+        invoice.manage.billing
+        subscription.manage.billing
+        plan.manage.billing
+        lifetime.manage.billing
+        team.manage.teams
+        member.manage.teams
+        invitation.manage.teams
+        account.manage.accounts
+        membership.manage.accounts
+        notification.manage.notifications
+        preference.manage.notifications
+      ].freeze
+    }.freeze
+
+    def self.valid_name?(name)
+      NAME_PATTERN.match?(name.to_s)
+    end
+
+    def self.assert_valid_name!(name)
+      return if valid_name?(name)
+
+      raise InvalidAbilityNameError,
+            "Ability name #{name.inspect} must follow resource.action.engine " \
+            "(e.g. invoice.read.billing)"
+    end
+
+    # Resolves whether a role is allowed an ability. The role string is one
+    # of owner/admin/member/system; request-layer bypasses (e.g. staff?)
+    # are handled by callers, not here. Raises if the ability was never
+    # registered, matching the event bus's loud-failure behaviour.
+    def self.can?(role:, ability:)
+      ability = ability.to_s
+
+      unless PermissionRegistry.registered?(ability)
+        raise UnregisteredAbilityError,
+              "Ability #{ability.inspect} is not registered; register it with " \
+              "Seams::PermissionRegistry.register before checking it"
+      end
+
+      role = role.to_s
+      return true if role == SYSTEM_ROLE
+
+      roles_for(role).any? { |r| granted_abilities_for(r).include?(ability) }
+    end
+
+    # The role itself plus every role it inherits from, lowest first. An
+    # unknown role resolves to just itself (and therefore no grants).
+    def self.roles_for(role)
+      role  = role.to_s
+      index = ROLE_HIERARCHY.index(role)
+      return [role] unless index
+
+      ROLE_HIERARCHY[index..]
+    end
+
+    # Abilities granted directly to a single role in the configured map,
+    # tolerating string or symbol keys and values.
+    def self.granted_abilities_for(role)
+      grants = Seams.configuration.permission_grants
+      list   = grants[role.to_s] || grants[role.to_sym]
+      Array(list).map(&:to_s)
+    end
+  end
+end

data/lib/seams/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Seams
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/seams.rb

@@ -6,8 +6,13 @@ require "seams/version"
 #
 # See https://github.com/Davidslv/seams for documentation.
 module Seams
+  # Base class for all Seams errors.
   class Error < StandardError; end
+
+  # Raised when Seams is misconfigured (e.g. an adapter class can't be loaded).
   class ConfigurationError < Error; end
+
+  # Raised when a generator hits an unrecoverable problem.
   class GeneratorError < Error; end
 end
 
@@ -17,6 +22,8 @@ require "seams/events"
 require "seams/events/adapter"
 require "seams/events/adapters/active_support"
 require "seams/event_registry"
+require "seams/permissions"
+require "seams/permission_registry"
 require "seams/events/publisher"
 require "seams/observability"
 require "seams/observability/adapter"