axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/lib/rubocop/cop/axn/unchecked_result.rb

@@ -3,13 +3,17 @@
 module RuboCop
   module Cop
     module Axn
-      # This cop enforces that when calling Actions from within other Actions,
+      # This cop enforces that when calling Axns from within other Axns,
       # you must either use `call!` (with the bang) or check `result.ok?`.
       #
+      # When the ActionsNamespace configuration is set (e.g., to "Actions"),
+      # the cop will only check calls on classes under that namespace,
+      # reducing false positives from other service objects.
+      #
       # @example
       #   # bad
       #   class OuterAction
-      #     include Action
+      #     include Axn
       #     def call
       #       InnerAction.call(param: "value")  # Missing result check
       #     end
@@ -17,7 +21,7 @@ module RuboCop
       #
       #   # good
       #   class OuterAction
-      #     include Action
+      #     include Axn
       #     def call
       #       result = InnerAction.call(param: "value")
       #       return result unless result.ok?
@@ -27,17 +31,68 @@ module RuboCop
       #
       #   # also good
       #   class OuterAction
-      #     include Action
+      #     include Axn
       #     def call
       #       InnerAction.call!(param: "value")  # Using call! ensures exceptions bubble up
       #     end
       #   end
       #
+      # @example With ActionsNamespace configured as string
+      #   # .rubocop.yml
+      #   Axn/UncheckedResult:
+      #     ActionsNamespace: "Actions"
+      #
+      #   # This will only check Actions::* classes, not other service objects
+      #   class OuterAction
+      #     include Axn
+      #     def call
+      #       SomeService.call(param: "value")  # Won't trigger cop
+      #       Actions::InnerAction.call(param: "value")  # Will trigger cop
+      #     end
+      #   end
+      #
+      # @example With ActionsNamespace configured as array
+      #   # .rubocop.yml
+      #   Axn/UncheckedResult:
+      #     ActionsNamespace: ["Actions", "Services"]
+      #
+      #   # This will check both Actions::* and Services::* classes
+      #   class OuterAction
+      #     include Axn
+      #     def call
+      #       SomeService.call(param: "value")  # Won't trigger cop
+      #       Actions::InnerAction.call(param: "value")  # Will trigger cop
+      #       Services::SomeService.call(param: "value")  # Will trigger cop
+      #     end
+      #   end
+      #
       # rubocop:disable Metrics/ClassLength
       class UncheckedResult < RuboCop::Cop::Base
         extend RuboCop::Cop::AutoCorrector
 
-        MSG = "Use `call!` or check `result.ok?` when calling Actions from within Actions"
+        MSG = "Use `call!` or check `result.ok?` when calling Axns from within Axns"
+
+        # Define the configuration schema
+        def self.configuration_schema
+          @configuration_schema ||= RuboCop::ConfigSchema::Schema.new(
+            {
+              "ActionsNamespace" => {
+                "type" => %w[string array],
+                "description" => 'Only check calls on classes under this namespace (e.g., "Actions") or array of namespaces (e.g., ["Actions", "Services"])',
+              },
+              "CheckNested" => {
+                "type" => "boolean",
+                "description" => "Check nested Axn calls",
+                "default" => true,
+              },
+              "CheckNonNested" => {
+                "type" => "boolean",
+                "description" => "Check non-nested Axn calls",
+                "default" => true,
+              },
+            },
+          )
+        end
 
         # Configuration options
         def check_nested?
@@ -48,20 +103,20 @@ module RuboCop
           cop_config["CheckNonNested"] != false
         end
 
-        # Track whether we're inside an Action class and its call method
+        # Track whether we're inside an Axn class and its call method
         def_node_search :action_class?, <<~PATTERN
-          (class _ (const nil? :Action) ...)
+          (class _ (const nil? :Axn) ...)
         PATTERN
 
         def_node_search :includes_action?, <<~PATTERN
-          (send nil? :include (const nil? :Action))
+          (send nil? :include (const nil? :Axn))
         PATTERN
 
         def_node_search :call_method?, <<~PATTERN
           (def :call ...)
         PATTERN
 
-        def_node_search :action_call?, <<~PATTERN
+        def_node_search :axn_call?, <<~PATTERN
           (send (const _ _) :call ...)
         PATTERN
 
@@ -102,9 +157,10 @@ module RuboCop
         PATTERN
 
         def on_send(node)
-          return unless action_call?(node)
+          return unless axn_call?(node)
+          return unless axn_action_call?(node)
           return if bang_call?(node)
-          return unless inside_action_call_method?(node)
+          return unless inside_axn_call_method?(node)
 
           # Check if we should process this call based on configuration
           is_inside_action = inside_action_context?(node)
@@ -117,8 +173,73 @@ module RuboCop
 
         private
 
-        def inside_action_call_method?(node)
-          # Check if we're inside a call method of an Action class
+        def axn_action_call?(node)
+          # Get the receiver of the call method
+          receiver = node.children[0]
+          return false unless receiver&.type == :const
+
+          # Get the constant name - handle both simple constants and namespaced constants
+          const_name = get_constant_name(receiver)
+          return false unless const_name
+
+          # Check if we have the Actions namespace configured
+          namespace = actions_namespace
+
+          if namespace
+            # Handle both string and array configurations
+            case namespace
+            when String
+              return const_name.start_with?("#{namespace}::")
+            when Array
+              # If array is empty, fall back to checking all calls
+              return true if namespace.empty?
+
+              return namespace.any? { |ns| const_name.start_with?("#{ns}::") }
+            end
+          end
+
+          # If no namespace is configured, we can't be as precise
+          # Fall back to checking if the class includes Axn (more complex)
+          true
+        rescue StandardError => _e
+          # If there's any error, assume it's not an Axn action call
+          false
+        end
+
+        def get_constant_name(const_node)
+          # Handle both simple constants (const :SomeClass) and namespaced constants (const (const nil :Actions) :SomeClass)
+          if const_node.children[0]&.type == :const
+            # This is a namespaced constant like Actions::SomeClass
+            namespace = get_constant_name(const_node.children[0])
+            class_name = const_node.children[1]
+            "#{namespace}::#{class_name}"
+          else
+            # This is a simple constant like SomeClass
+            const_node.children[1]
+          end
+        end
+
+        def actions_namespace
+          # First try to get from RuboCop configuration
+          config_value = cop_config["ActionsNamespace"]
+          return nil unless config_value
+
+          # Handle both string and array configurations
+          case config_value
+          when String
+            config_value
+          when Array
+            config_value.map(&:to_s)
+          else
+            config_value.to_s
+          end
+        rescue StandardError => _e
+          # If there's any error accessing the configuration, return nil
+          nil
+        end
+
+        def inside_axn_call_method?(node)
+          # Check if we're inside a call method of an Axn class
           current_node = node
           while current_node.parent
             current_node = current_node.parent
@@ -126,19 +247,19 @@ module RuboCop
             # Check if we're inside a def :call
             next unless call_method?(current_node) && current_node.method_name == :call
 
-            # Now check if this class includes Action
+            # Now check if this class includes Axn
             class_node = find_enclosing_class(current_node)
             return includes_action?(class_node) if class_node
           end
           false
         rescue StandardError => _e
-          # If there's any error in the analysis, assume we're not in an Action call method
+          # If there's any error in the analysis, assume we're not in an Axn call method
           # This prevents the cop from crashing on complex or malformed code
           false
         end
 
         def inside_action_context?(node)
-          # Check if this Action call is inside an Action class's call method
+          # Check if this Axn call is inside an Axn class's call method
           current_node = node
           while current_node.parent
             current_node = current_node.parent
@@ -146,7 +267,7 @@ module RuboCop
             # Check if we're inside a def :call
             next unless call_method?(current_node) && current_node.method_name == :call
 
-            # Now check if this class includes Action
+            # Now check if this class includes Axn
             class_node = find_enclosing_class(current_node)
             return true if class_node && includes_action?(class_node)
           end

metadata

@@ -1,54 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.8.1
+  version: 0.1.0.pre.alpha.4
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-25 00:00:00.000000000 Z
+date: 2026-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
 description: Pattern for writing callable service objects with contract validation
-  and error swallowing
+  and exception handling
 email:
 - kali@teamshares.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- ".tool-versions"
+- ".cursor/commands/pr.md"
+- ".cursor/rules/axn-framework-patterns.mdc"
+- ".cursor/rules/general-coding-standards.mdc"
+- ".cursor/rules/spec/testing-patterns.mdc"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - LICENSE.txt
@@ -56,79 +57,120 @@ files:
 - Rakefile
 - docs/.vitepress/config.mjs
 - docs/advanced/conventions.md
+- docs/advanced/mountable.md
+- docs/advanced/profiling.md
 - docs/advanced/rough.md
 - docs/index.md
 - docs/intro/about.md
 - docs/intro/overview.md
+- docs/recipes/formatting-context-for-error-tracking.md
 - docs/recipes/memoization.md
 - docs/recipes/rubocop-integration.md
 - docs/recipes/testing.md
 - docs/recipes/validating-user-input.md
-- docs/reference/action-result.md
+- docs/reference/async.md
+- docs/reference/axn-result.md
 - docs/reference/class.md
 - docs/reference/configuration.md
+- docs/reference/form-object.md
 - docs/reference/instance.md
+- docs/strategies/client.md
+- docs/strategies/form.md
 - docs/strategies/index.md
 - docs/strategies/transaction.md
 - docs/usage/setup.md
 - docs/usage/steps.md
 - docs/usage/using.md
 - docs/usage/writing.md
-- lib/action/attachable.rb
-- lib/action/attachable/base.rb
-- lib/action/attachable/steps.rb
-- lib/action/attachable/subactions.rb
-- lib/action/configuration.rb
-- lib/action/context.rb
-- lib/action/core.rb
-- lib/action/core/automatic_logging.rb
-- lib/action/core/context/facade.rb
-- lib/action/core/context/facade_inspector.rb
-- lib/action/core/context/internal.rb
-- lib/action/core/contract.rb
-- lib/action/core/contract_for_subfields.rb
-- lib/action/core/contract_validation.rb
-- lib/action/core/flow.rb
-- lib/action/core/flow/callbacks.rb
-- lib/action/core/flow/exception_execution.rb
-- lib/action/core/flow/handlers.rb
-- lib/action/core/flow/handlers/base_descriptor.rb
-- lib/action/core/flow/handlers/descriptors/callback_descriptor.rb
-- lib/action/core/flow/handlers/descriptors/message_descriptor.rb
-- lib/action/core/flow/handlers/invoker.rb
-- lib/action/core/flow/handlers/matcher.rb
-- lib/action/core/flow/handlers/registry.rb
-- lib/action/core/flow/handlers/resolvers/base_resolver.rb
-- lib/action/core/flow/handlers/resolvers/callback_resolver.rb
-- lib/action/core/flow/handlers/resolvers/message_resolver.rb
-- lib/action/core/flow/messages.rb
-- lib/action/core/hooks.rb
-- lib/action/core/logging.rb
-- lib/action/core/nesting_tracking.rb
-- lib/action/core/timing.rb
-- lib/action/core/tracing.rb
-- lib/action/core/use_strategy.rb
-- lib/action/core/validation/fields.rb
-- lib/action/core/validation/subfields.rb
-- lib/action/core/validation/validators/model_validator.rb
-- lib/action/core/validation/validators/type_validator.rb
-- lib/action/core/validation/validators/validate_validator.rb
-- lib/action/enqueueable.rb
-- lib/action/enqueueable/via_sidekiq.rb
-- lib/action/exceptions.rb
-- lib/action/result.rb
-- lib/action/strategies.rb
-- lib/action/strategies/transaction.rb
 - lib/axn.rb
+- lib/axn/async.rb
+- lib/axn/async/adapters.rb
+- lib/axn/async/adapters/active_job.rb
+- lib/axn/async/adapters/disabled.rb
+- lib/axn/async/adapters/sidekiq.rb
+- lib/axn/async/batch_enqueue.rb
+- lib/axn/async/batch_enqueue/config.rb
+- lib/axn/async/enqueue_all_orchestrator.rb
+- lib/axn/configuration.rb
+- lib/axn/context.rb
+- lib/axn/core.rb
+- lib/axn/core/automatic_logging.rb
+- lib/axn/core/context/facade.rb
+- lib/axn/core/context/facade_inspector.rb
+- lib/axn/core/context/internal.rb
+- lib/axn/core/contract.rb
+- lib/axn/core/contract_for_subfields.rb
+- lib/axn/core/contract_validation.rb
+- lib/axn/core/contract_validation_for_subfields.rb
+- lib/axn/core/default_call.rb
+- lib/axn/core/field_resolvers.rb
+- lib/axn/core/field_resolvers/extract.rb
+- lib/axn/core/field_resolvers/model.rb
+- lib/axn/core/flow.rb
+- lib/axn/core/flow/callbacks.rb
+- lib/axn/core/flow/exception_execution.rb
+- lib/axn/core/flow/handlers.rb
+- lib/axn/core/flow/handlers/base_descriptor.rb
+- lib/axn/core/flow/handlers/descriptors/callback_descriptor.rb
+- lib/axn/core/flow/handlers/descriptors/message_descriptor.rb
+- lib/axn/core/flow/handlers/invoker.rb
+- lib/axn/core/flow/handlers/matcher.rb
+- lib/axn/core/flow/handlers/registry.rb
+- lib/axn/core/flow/handlers/resolvers/base_resolver.rb
+- lib/axn/core/flow/handlers/resolvers/callback_resolver.rb
+- lib/axn/core/flow/handlers/resolvers/message_resolver.rb
+- lib/axn/core/flow/messages.rb
+- lib/axn/core/hooks.rb
+- lib/axn/core/logging.rb
+- lib/axn/core/memoization.rb
+- lib/axn/core/nesting_tracking.rb
+- lib/axn/core/timing.rb
+- lib/axn/core/tracing.rb
+- lib/axn/core/use_strategy.rb
+- lib/axn/core/validation/fields.rb
+- lib/axn/core/validation/subfields.rb
+- lib/axn/core/validation/validators/model_validator.rb
+- lib/axn/core/validation/validators/type_validator.rb
+- lib/axn/core/validation/validators/validate_validator.rb
+- lib/axn/exceptions.rb
+- lib/axn/extras.rb
+- lib/axn/extras/strategies/client.rb
+- lib/axn/extras/strategies/vernier.rb
 - lib/axn/factory.rb
+- lib/axn/form_object.rb
+- lib/axn/internal/logging.rb
+- lib/axn/internal/registry.rb
+- lib/axn/mountable.rb
+- lib/axn/mountable/descriptor.rb
+- lib/axn/mountable/helpers/class_builder.rb
+- lib/axn/mountable/helpers/mounter.rb
+- lib/axn/mountable/helpers/namespace_manager.rb
+- lib/axn/mountable/helpers/validator.rb
+- lib/axn/mountable/inherit_profiles.rb
+- lib/axn/mountable/mounting_strategies.rb
+- lib/axn/mountable/mounting_strategies/_base.rb
+- lib/axn/mountable/mounting_strategies/axn.rb
+- lib/axn/mountable/mounting_strategies/method.rb
+- lib/axn/mountable/mounting_strategies/step.rb
+- lib/axn/rails/engine.rb
+- lib/axn/rails/generators/axn_generator.rb
+- lib/axn/rails/generators/templates/action.rb.erb
+- lib/axn/rails/generators/templates/action_spec.rb.erb
+- lib/axn/result.rb
 - lib/axn/rubocop.rb
+- lib/axn/strategies.rb
+- lib/axn/strategies/form.rb
+- lib/axn/strategies/transaction.rb
 - lib/axn/testing/spec_helpers.rb
-- lib/axn/util.rb
+- lib/axn/util/callable.rb
+- lib/axn/util/contract_error_handling.rb
+- lib/axn/util/execution_context.rb
+- lib/axn/util/global_id_serialization.rb
+- lib/axn/util/logging.rb
+- lib/axn/util/memoization.rb
 - lib/axn/version.rb
 - lib/rubocop/cop/axn/README.md
 - lib/rubocop/cop/axn/unchecked_result.rb
-- package.json
-- yarn.lock
 homepage: https://github.com/teamshares/axn
 licenses:
 - MIT
@@ -145,7 +187,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.2.1
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,76 +0,0 @@
-# RuboCop cops are not loaded by default in this repo
-# Downstream consumers can enable them by adding:
-# require:
-#   - axn/rubocop
-
-AllCops:
-  TargetRubyVersion: 3.2
-  SuggestExtensions: false
-  NewCops: enable
-
-Style/MultilineBlockChain:
-  Enabled: false
-
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/Documentation:
-  Enabled: false
-
-Style/TrailingCommaInArguments:
-  EnforcedStyleForMultiline: comma
-
-Style/TrailingCommaInArrayLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/TrailingCommaInHashLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/HashSyntax:
-  EnforcedShorthandSyntax: always
-
-Style/DoubleNegation:
-  Enabled: false
-
-Metrics/BlockLength:
-  Enabled: false
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Metrics/ClassLength:
-  Max: 150
-
-Metrics/MethodLength:
-  Max: 70
-
-Metrics/PerceivedComplexity:
-  Max: 20
-
-Metrics/AbcSize:
-  Max: 60
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-
-Lint/EmptyBlock:
-  Enabled: false
-
-Naming/MethodParameterName:
-  AllowedNames: e, on, id, if
-
-Metrics/ParameterLists:
-  Max: 9
-
-Layout/LineLength:
-  Max: 160
-
-

data/.tool-versions

@@ -1 +0,0 @@
-ruby 3.3.6

data/docs/reference/action-result.md

@@ -1,37 +0,0 @@
-# `Action::Result`
-
-Every `call` invocation on an Action will return an `Action::Result` instance, which provides a consistent interface:
-
-| Method | Description |
-| -- | -- |
-| `ok?` | `true` if the call succeeded, `false` if not.
-| `error` | User-facing error message (string), if not `ok?` (else nil)
-| `success` | User-facing success message (string), if `ok?` (else nil)
-| `message` | User-facing message (string), always defined (`ok? ? success : error`)
-| `exception` | If not `ok?` because an exception was swallowed, will be set to the swallowed exception (note: rarely used outside development; prefer to let the library automatically handle exception handling for you)
-| `outcome` | The execution outcome as a string inquirer (`success?`, `failure?`, `exception?`)
-| `elapsed_time` | Execution time in milliseconds (Float)
-| any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
-
-NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `success` and `error` declarations](/reference/class#success-and-error).
-
-### Clarification of exposed values
-
-In addition to the core interface, your Action's Result class will have methods defined to read the values of any attributes that were explicitly exposed.  For example, given this action and result:
-
-
-```ruby
-class Foo
-  include Action
-
-  exposes :bar, :baz # [!code focus]
-
-  def call
-    expose bar: 1, baz: 2
-  end
-end
-
-result = Foo.call # [!code focus]
-```
-
-`result` will have both `bar` and `baz` reader methods (which will return 1 and 2, respectively).

data/lib/action/attachable/base.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Attachable
-    module Base
-      extend ActiveSupport::Concern
-
-      class_methods do
-        def axn_for_attachment(
-          attachment_type: "Action",
-          name: nil,
-          axn_klass: nil,
-          superclass: nil,
-          **kwargs,
-          &block
-        )
-          raise ArgumentError, "#{attachment_type} name must be a string or symbol" unless name.is_a?(String) || name.is_a?(Symbol)
-          raise ArgumentError, "#{attachment_type} '#{name}' must be given an existing action class or a block" if axn_klass.nil? && !block_given?
-
-          if axn_klass && block_given?
-            raise ArgumentError,
-                  "#{attachment_type} '#{name}' was given both an existing action class and a block - only one is allowed"
-          end
-
-          if axn_klass
-            unless axn_klass.respond_to?(:<) && axn_klass < Action
-              raise ArgumentError,
-                    "#{attachment_type} '#{name}' was given an already-existing class #{axn_klass.name} that does NOT inherit from Action as expected"
-            end
-
-            if kwargs.present?
-              raise ArgumentError, "#{attachment_type} '#{name}' was given an existing action class and also keyword arguments - only one is allowed"
-            end
-
-            return axn_klass
-          end
-
-          Axn::Factory.build(superclass: superclass || self, name:, **kwargs, &block)
-        end
-      end
-    end
-  end
-end