mu-action 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e178de7158d182e1527dd7b23ede20e67f9010e4bc588869fe433ebd4f2d1c85
-  data.tar.gz: 424feef48df8a60bd7c9aaf5ea755744d804f818e54fe2dd6d9a2ec4aea70595
+  metadata.gz: 5765a5a8a0a0af6628f4b36d5e7dde4337eb44ed1e44275208b151276d4de412
+  data.tar.gz: 6c906cf41b59a6fde0b7b4482d3029fca4a48f2767a4958f0d9d54a9ed661d79
 SHA512:
-  metadata.gz: 7776bdf1fbb430638cb882abf2558d397b8dea4d7ea69c237ab9c3d9f0d3ddd5f05f4c66bb2cad79e16f02d2fb6b8a0b14d99bcba2bac01c99b5e8249763cc8d
-  data.tar.gz: aa9b022415a7905aa29ab543fed97763842e2b6ccf18e08e4b91b62479bf38651eb2dc518c9c5b7f49f3413f80de896886e534ac03473fabaaf6d82c1c250ccd
+  metadata.gz: 9c6f9145debfaee371e5330f8922d8739489358e5aaf7aa6d6d4f5ab1c445a880725a9314d3bf1d7ceddc1b9209a41ac68638dc9aba40985280d295f08250468
+  data.tar.gz: 6a5b5a71d34add535fcb0672963a99c8414e8038776d376cc04bb81c8bc9d7fbe68561a7c2f7ef5ab10740ddaf02b6348bd85e9c8f8fedd7afd32e4e2126bd14

data/AGENTS.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `lib/mu/action` holds the core interactor implementation; mirror this layout when adding new components so `lib/mu/action/foo.rb` pairs with `Mu::Action::Foo`.
+- `spec/` mirrors the library structure with RSpec examples; add a matching `_spec.rb` file for every public entry point.
+- `sig/` provides RBS signatures that keep types honest—update them alongside code changes.
+- `bin/` hosts contributor tooling (`check`, `console`, `test_readme_examples`); treat `readme_examples.rb` as generated output.
+
+## Build, Test, and Development Commands
+- `bin/check` aggregates lint, spec, and README example runs for a pre-PR smoke test. Use this instead of `rake`.
+- `bundle exec rspec spec/mu/action/hook_spec.rb` executes targeted tests; leave focused specs checked in only when necessary.
+- `bundle exec rubocop` enforces style; let it guide formatting instead of manual tweaks.
+- `bundle exec steep check` validates Steep signatures against implementation.
+- `bin/test_readme_examples --extract-only` regenerates `readme_examples.rb` after documentation updates.
+
+## Coding Style & Naming Conventions
+- Target Ruby 3.1 with two-space indentation and trailing commas only when required.
+- RuboCop enforces double-quoted strings and general style—prefer fixes via `bundle exec rubocop -A` over manual edits.
+- Match class and module names to their file paths (e.g., `Mu::Action::Result` lives in `lib/mu/action/result.rb`), and keep method names snake_case verbs.
+- Favor small, composable interactors with explicit `prop` declarations and `Success`/`Failure` returns to stay idiomatic.
+
+## Testing Guidelines
+- Write RSpec examples that describe observable behavior; structure files as `describe Mu::Action::Feature` with nested `context` blocks.
+- Cover both success and failure branches, including metadata expectations when hooks mutate state.
+- Keep factories lightweight—inline doubles or `let` helpers beat global fixtures for clarity.
+- Run `bundle exec rspec` locally and ensure README examples still execute via `bin/check` whenever documentation changes.
+
+## Commit & Pull Request Guidelines
+- Follow the existing Conventional Commit style (`feat:`, `chore:`, `docs:`) visible in `git log --oneline`.
+- Keep commits scoped to a single concern and include any signature or README updates in the same change.
+- Open pull requests with a brief summary, linked issues (if any), and mention any developer-facing changes or new scripts.
+- State that `bin/check` passes; add screenshots or console snippets only when behavior changes are user-visible.

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-10-30
+
+### Added
+- Support registering `before`, `after`, and `around` hooks by method name.
+- Steep type-checking infrastructure: Steepfile, comprehensive RBS signatures for `Mu::Action`.
+- Guard plugin for steep type checking.
+
+### Changed
+- `bin/check` now runs `bundle exec steep check` as part of the default contributor workflow.
+- Guard automation reorganized to load the new Steep guard explicitly.
+- Updated Bundler metadata to 2.7.2.
+
+### Documentation
+- Added `AGENTS.md` with contributor and workflow guidelines.
+
 ## [0.1.0] - 2025-07-23
 
 ### Added

data/Guardfile

@@ -1,5 +1,18 @@
 # frozen_string_literal: true
 
+require "guard/steep"
+
+guard :rubocop, cli: "--format progress" do
+  watch(/.+\.rb$/)
+  watch(%r{(?:.+/)?\.rubocop(?:_todo)?\.yml$}) { File.dirname(_1[0]) }
+end
+
+guard :steep, command: "bundle exec steep check" do
+  watch("Steepfile")
+  watch(%r{^sig/.+\.rbs$})
+  watch(%r{^lib/.+\.rb$})
+end
+
 guard :rspec, cmd: "bundle exec rspec" do
   require "guard/rspec/dsl"
   dsl = Guard::RSpec::Dsl.new(self)
@@ -19,8 +32,3 @@ guard :rspec, cmd: "bundle exec rspec" do
   watch(%r{^lib/mu/action/(.+)\.rb$}) { "spec/mu/action_spec.rb" }
   watch(%r{^lib/mu/action\.rb$}) { Dir["spec/*"] }
 end
-
-guard :rubocop, cli: "--format progress" do
-  watch(/.+\.rb$/)
-  watch(%r{(?:.+/)?\.rubocop(?:_todo)?\.yml$}) { |m| File.dirname(m[0]) }
-end

data/README.md

@@ -124,6 +124,41 @@ result = ProcessPayment.call(amount: 100.0, card_token: "tok_123")
 assert result.value[:payment_id] == "pay_123"
 ```
 
+Hooks can also be registered by method name if you prefer keeping the logic in dedicated instance methods:
+
+```ruby
+class ProcessPayment
+  include Mu::Action
+
+  prop :amount, Float
+  prop :card_token, String
+
+  before :prepare_logging
+  after :finalize_logging
+  around :wrap_in_transaction
+
+  def prepare_logging
+    meta[:started_at] = Time.now
+    Rails.logger.info "Processing payment for $#{@amount}"
+  end
+
+  def finalize_logging
+    meta[:completed_at] = Time.now
+    Rails.logger.info "Payment processing completed"
+  end
+
+  def wrap_in_transaction(chain)
+    ActiveRecord::Base.transaction { chain.call }
+  end
+
+  def call
+    Success(payment_id: "pay_123")
+  end
+end
+```
+
+Around hook methods may also receive no arguments and use `yield`, or accept two arguments `(action, chain)` to mirror the block-based signature.
+
 ### Custom Result Types
 
 Define typed results for better API contracts:

data/Steepfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature "sig"
+  check "lib"
+
+  configure_code_diagnostics(Steep::Diagnostic::Ruby.default)
+end

data/lib/guard/steep.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "guard/plugin"
+
+# steep:ignore:start
+module Guard
+  # Guard plugin that runs Steep type checking whenever files change.
+  class Steep < Plugin
+    def initialize(options = {})
+      super
+      @command = options.fetch(:command, "bundle exec steep check")
+    end
+
+    def start = run_steep
+    def run_all = run_steep
+    def run_on_additions(_paths) = run_steep
+    def run_on_modifications(_paths) = run_steep
+    def run_on_removals(_paths) = run_steep
+
+    private
+
+    def run_steep
+      UI.info "📐 Running Steep..."
+      success = system(@command)
+      UI.error "Steep check failed" unless success
+    end
+  end
+end
+# steep:ignore:end

data/lib/mu/action/version.rb

@@ -2,6 +2,6 @@
 
 module Mu
   module Action
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/mu/action.rb

@@ -24,7 +24,7 @@ module Mu
     module MetaPropAdder
       def new(...)
         unless @meta_prop_added
-          prop :meta, Hash, default: -> { {} }
+          prop :meta, Hash, default: -> { {} } # steep:ignore UnannotatedEmptyCollection
           @meta_prop_added = true
         end
         instance = super
@@ -65,7 +65,7 @@ module Mu
     # Base result class that wraps action outcomes with success/failure state
     # and metadata. Extended by Success and Failure classes for pattern matching.
     class Result < Literal::Struct
-      prop :meta, Hash, default: -> { {} }
+      prop :meta, Hash, default: -> { {} } # steep:ignore UnannotatedEmptyCollection
 
       attr_reader :meta
     end
@@ -111,9 +111,9 @@ module Mu
     # Class methods added to action classes when including Mu::Action.
     # Provides hook registration, execution methods, and result type definition.
     module ClassMethods
-      def around(&block) = around_hooks << block
-      def before(&block) = before_hooks << block
-      def after(&block) = after_hooks << block
+      def around(*method_names, &block) = register_hook(around_hooks, method_names, block, name: :around)
+      def before(*method_names, &block) = register_hook(before_hooks, method_names, block, name: :before)
+      def after(*method_names, &block) = register_hook(after_hooks, method_names, block, name: :after)
 
       def around_hooks = (@around_hooks ||= [])
       def before_hooks = (@before_hooks ||= [])
@@ -140,6 +140,40 @@ module Mu
 
         const_set(:Success, success_class)
       end
+
+      private
+
+      def register_hook(collection, method_names, block, name:)
+        ensure_valid_hook_inputs(method_names, block, name:)
+        additions = normalize_hook_inputs(method_names, block, name:)
+        collection.concat(additions)
+      end
+
+      def normalize_hook_inputs(method_names, block, name:)
+        if block
+          [block]
+        else
+          symbolize_hook_names(method_names, name:)
+        end
+      end
+
+      def ensure_valid_hook_inputs(method_names, block, name:)
+        return unless block && method_names.any?
+
+        raise ArgumentError, "#{name} hooks accept either a block or method names, not both"
+      end
+
+      def symbolize_hook_names(method_names, name:)
+        raise ArgumentError, "#{name} hook requires a block or method name" if method_names.empty?
+
+        method_names.map do |method_name|
+          unless method_name.respond_to?(:to_sym)
+            raise ArgumentError, "Invalid #{name} hook identifier: #{method_name.inspect}"
+          end
+
+          method_name.to_sym
+        end
+      end
     end
 
     # rubocop:disable Naming/MethodName
@@ -171,18 +205,60 @@ module Mu
 
     private
 
-    def run_before_hooks = self.class.before_hooks.each { instance_exec(&_1) }
-    def run_after_hooks = self.class.after_hooks.each { instance_exec(&_1) }
+    def run_before_hooks = self.class.before_hooks.each { execute_simple_hook(_1) }
+    def run_after_hooks = self.class.after_hooks.each { execute_simple_hook(_1) }
 
     def build_around_chain(&block)
       chain = block
       self.class.around_hooks.reverse_each do |hook|
         previous = chain
-        chain = -> { instance_exec(self, previous, &hook) }
+        chain = build_around_wrapper(hook, previous)
       end
       chain
     end
 
+    def execute_simple_hook(hook)
+      if hook.is_a?(Proc)
+        # @type var hook: ^(*untyped) -> untyped
+        return instance_exec(&hook)
+      end
+
+      send(hook)
+    end
+
+    def build_around_wrapper(hook, previous)
+      case hook
+      when Proc
+        lambda do
+          # @type var hook: ^(*untyped) -> untyped
+          instance_exec(self, previous, &hook)
+        end
+      else
+        -> { invoke_around_method(hook, previous) }
+      end
+    end
+
+    def invoke_around_method(hook, previous)
+      method_name = hook.to_sym
+      method_object = resolve_method(method_name)
+      arguments = around_arguments(method_object, previous)
+      method_object.bind(self).call(*arguments, &previous)
+    end
+
+    def around_arguments(method_object, previous)
+      params = method_object.parameters.reject { _1.first == :block }
+      return [] if params.empty?
+      return [previous] if params.length == 1
+
+      [self, previous]
+    end
+
+    def resolve_method(method_name)
+      self.class.instance_method(method_name)
+    rescue NameError
+      raise NoMethodError, "Undefined hook method ##{method_name} for #{self.class}"
+    end
+
     def call
       raise NotImplementedError, "You must implement the call method"
     end

data/sig/kernel.rbs

@@ -0,0 +1,3 @@
+module Kernel
+  def instance_exec: (*untyped) { (*untyped) -> untyped } -> untyped
+end

data/sig/literal.rbs

@@ -0,0 +1,13 @@
+module Literal
+  module Properties
+    def prop: (Symbol, untyped, *untyped, ?default: untyped) -> untyped
+    def _Any: () -> untyped
+  end
+
+  class Struct
+    extend Properties
+
+    def self.prop: (Symbol, untyped, *untyped, ?default: untyped) -> untyped
+    def self.literal_properties: () -> ::Array[untyped]
+  end
+end

data/sig/mu/action.rbs

@@ -1,6 +1,116 @@
 module Mu
   module Action
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    include Kernel
+
+    VERSION: ::String
+    attr_reader meta: ::Hash[untyped, untyped]
+
+    interface _ActionInstance
+      def meta: () -> ::Hash[untyped, untyped]
+      def class: () -> _ActionClass
+      def run: () -> ::Mu::Action::Result
+      def run!: () -> ::Mu::Action::Result
+    end
+
+    interface _ActionClass
+      def literal_properties: () -> ::Array[untyped]
+      def before_hooks: () -> ::Array[untyped]
+      def after_hooks: () -> ::Array[untyped]
+      def around_hooks: () -> ::Array[untyped]
+      def const_get: (Symbol) -> ::Class
+      def instance_method: (Symbol) -> UnboundMethod
+      def new: (*untyped, **untyped) -> _ActionInstance
+    end
+
+    def self.included: (untyped base) -> void
+    def self.before_hooks: () -> ::Array[untyped]
+    def self.after_hooks: () -> ::Array[untyped]
+    def self.around_hooks: () -> ::Array[untyped]
+
+    module MetaPropAdder
+      include Literal::Properties
+
+      def new: (*untyped, **untyped) -> untyped
+      def inherited: (untyped subclass) -> void
+    end
+
+    module HookPropagator
+      def inherited: (untyped subclass) -> void
+      def before_hooks: () -> ::Array[untyped]
+      def after_hooks: () -> ::Array[untyped]
+      def around_hooks: () -> ::Array[untyped]
+    end
+
+    class FailureError < StandardError
+      attr_reader error: untyped
+      attr_reader meta: ::Hash[untyped, untyped]
+
+      def initialize: (untyped error, ?meta: ::Hash[untyped, untyped]) -> void
+    end
+
+    class Result < Literal::Struct
+      attr_reader meta: ::Hash[untyped, untyped]
+
+      def initialize: (*untyped, **untyped) -> void
+    end
+
+    class Success < Result
+      attr_reader value: untyped
+
+      def initialize: (*untyped, **untyped) -> void
+      def success?: () -> true
+      def failure?: () -> false
+    end
+
+    class Failure < Result
+      attr_reader error: untyped
+
+      def initialize: (*untyped, **untyped) -> void
+      def success?: () -> false
+      def failure?: () -> true
+    end
+
+    module Initializer
+      def initialize: (*untyped, **untyped) -> void
+      def initialize_meta: () -> void
+      def meta: () -> ::Hash[untyped, untyped]
+      def self.literal_properties: () -> ::Array[untyped]
+    end
+
+    module ClassMethods
+      include Literal::Properties
+
+      def around: (*Symbol) ?{ (*untyped) -> untyped } -> ::Array[untyped]
+      def before: (*Symbol) ?{ (*untyped) -> untyped } -> ::Array[untyped]
+      def after: (*Symbol) ?{ (*untyped) -> untyped } -> ::Array[untyped]
+      def around_hooks: () -> ::Array[untyped]
+      def before_hooks: () -> ::Array[untyped]
+      def after_hooks: () -> ::Array[untyped]
+      def call: (*untyped, **untyped) -> untyped
+      def call!: (*untyped, **untyped) -> untyped
+      def result: (untyped type) -> ::Class
+      def register_hook: (untyped collection, untyped method_names, ::Proc? block, name: Symbol) -> untyped
+      def normalize_hook_inputs: (untyped method_names, ::Proc? block, name: Symbol) -> untyped
+      def ensure_valid_hook_inputs: (untyped method_names, ::Proc? block, name: Symbol) -> void
+      def symbolize_hook_names: (untyped method_names, name: Symbol) -> ::Array[Symbol]
+      def const_set: (Symbol, ::Class) -> ::Class
+      def new: (*untyped, **untyped) -> _ActionInstance
+    end
+
+    def Success: (untyped value) -> Success
+    def Failure: (untyped error, **untyped) -> bot
+    def run: () -> Result
+    def run!: () -> Result
+    def result_class: () -> ::Class
+    def with_hooks: () { () -> Result } -> Result
+    def run_before_hooks: () -> ::Array[untyped]
+    def run_after_hooks: () -> ::Array[untyped]
+    def build_around_chain: () { () -> Result } -> ::Proc
+    def execute_simple_hook: (::Proc | ::Symbol) -> untyped
+    def build_around_wrapper: ((::Proc | ::Symbol), ::Proc) -> ::Proc
+    def invoke_around_method: (::Symbol, ::Proc) -> untyped
+    def around_arguments: (UnboundMethod, ::Proc) -> ::Array[untyped]
+    def resolve_method: (Symbol) -> UnboundMethod
+    def call: () -> untyped
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mu-action
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicolas Buduroi
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: literal
@@ -34,6 +33,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
@@ -41,8 +41,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
+- lib/guard/steep.rb
 - lib/mu/action.rb
 - lib/mu/action/version.rb
+- sig/kernel.rbs
+- sig/literal.rbs
 - sig/mu/action.rbs
 homepage: https://github.com/budu/mu-action
 licenses:
@@ -53,7 +57,6 @@ metadata:
   source_code_uri: https://github.com/budu/mu-action
   changelog_uri: https://github.com/budu/mu-action/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -68,8 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Modern interactor pattern with type safety and metadata tracking
 test_files: []