business_flow 0.21.2 → 0.21.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efe077542fdb13fbaa9c53d3f58d108846e0b2bea1646a6789edeac73db8d9a7
-  data.tar.gz: c4a74472e897c5c5dec78f7d87221adeaeb153fc3df9437cb86bb1c821672e75
+  metadata.gz: 7e276f0e93f2f3b8e1467fdbdbe150b512963ae688afbf8675c0f29ae79b612f
+  data.tar.gz: 578abe1027f669c6feffdb8f57337d7efbc6dc7adf8fa9c29a7c5334d0bad85a
 SHA512:
-  metadata.gz: 855c34d54b1974dd8c3981843cd2f358b18021fac011f5f8042794f16f6ecb080bd7ffbaf837d364af575016e8dfe2ccb0766be21d4bdf8fa1e5f4d5c7dc8231
-  data.tar.gz: bb0e099ed1105278c6460c4b681795c9f6fce62271734329aeda5d0cb4def5e521c1ba9435888b3d95b74ec1ca8e279b7bea52057e4f802b71d3e491cc29ddb2
+  metadata.gz: 47519eef657f7b1b219a8f93ee7d979dd607b677e35d4225e3d3d59634637219627d790dbd5866a3b54d6872699aebef7e67147f3d6d10f1b3891d0e0fd83fc2
+  data.tar.gz: 3db5a8207caacb747847c7755f6f755ba0105a5fd1d2c0ade9671d254b63d7d20b157027c146ac10813ad9d4b5a009d39d7d4012923f70c83ca4567e643023d6

data/.gitignore

@@ -9,3 +9,4 @@
 
 # rspec failure tracking
 .rspec_status
+.claude/settings.local.json

data/.reek.yml

@@ -14,5 +14,8 @@ detectors:
     # N.B. If we want to enable this, we need to tweak the RuboCop config.  In particular, RuboCop
     # prefers `e` for exceptions.
     enabled: false
+  ManualDispatch:
+    exclude:
+    - BusinessFlow::DSL#_business_flow_parameter_inner_fetch
 exclude_paths:
   - vendor # For CircleCI.

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.21.3
+
+ENHANCEMENTS:
+
+* Add compatibility with `ActionController::Parameters`
+
 ## 0.21.2
 
 BUG FIXES:

data/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+BusinessFlow is a Ruby gem providing a service object/workflow DSL built on ActiveModel. It manages complex business logic flows with validation, caching, retries, instrumentation, and distributed locking (via Zookeeper).
+
+**Ruby:** >= 3.1.0 (project uses 3.3.9)
+**Rails/ActiveModel:** 4.2 through 8.0
+
+## Commands
+
+```bash
+# Run full test suite
+bundle exec rspec
+
+# Run a single spec file
+bundle exec rspec spec/business_flow/dsl_spec.rb
+
+# Run a single example by line number
+bundle exec rspec spec/business_flow/step_spec.rb:42
+
+# Run tests against all supported ActiveModel versions
+bundle exec appraisal rspec
+
+# Run tests against a specific ActiveModel version
+bundle exec appraisal activemodel-7.2 rspec
+
+# Lint
+bundle exec rubocop
+bundle exec reek
+
+# Autofix lint issues
+bundle exec rubocop -A
+
+# Interactive console with gem loaded
+bin/console
+
+# Setup (bundle install + appraisal install)
+bin/setup
+```
+
+## Architecture
+
+### Flow Execution Pipeline
+
+```
+include BusinessFlow::Base  →  DSL declares inputs/steps/outputs  →  .call(params)
+    ↓
+Parameter validation (needs/optional/wants)  →  ActiveModel validations  →  Step queue execution  →  Result
+```
+
+`BusinessFlow::Base` includes `DSL` and `Validations`. Most of the gem's logic lives in `DSL` and `Step`.
+
+### Core DSL (`lib/business_flow/dsl.rb`)
+
+The largest file (~530 lines). Provides the class-level API:
+
+- **Inputs:** `needs` (required), `optional`, `wants` (with defaults), `lookup` (dependency-based)
+- **Steps:** `step(klass_or_proc, opts)` — adds to execution queue; supports `if:`/`unless:` conditions, `inputs:`/`outputs:` mappings
+- **Outputs:** `provides` — fields exposed on the Result object
+- **Computed fields:** `uses(field, klass)` — memoized, lazily-evaluated
+- **Execution:** `.call(params)` returns a Result; `.call!` raises `FlowFailedException` on errors
+
+Dynamically generates initializer methods (`finalize_initializer`) and per-flow Result classes (`finalize_result_provider`) via `class_eval`.
+
+### Step Execution (`lib/business_flow/step.rb`)
+
+Steps marshal inputs from the flow, execute the callable, and merge outputs/errors back. Uses `throw :halt_step` / `catch(:halt_step)` for early termination on errors.
+
+### Callable Resolution (`lib/business_flow/callable.rb`)
+
+Normalizes callables — symbols resolve to instance methods or constants, procs execute in instance context, classes with `.call` are invoked based on arity. Redefines dispatch methods after first call for performance.
+
+### Step Executors
+
+Pluggable via `step_executor(klass)`:
+- `DefaultStepExecutor` — sequential execution, halts on first error
+- `InstrumentedExecutor` — adds flow-level ActiveSupport::Notifications
+- `InstrumentedStepExecutor` — adds per-step notifications
+
+### Optional Mixins
+
+- **`Cacheable`** — caches flow results; configurable store, TTL, and key generation
+- **`Retryable`** — wraps execution in retry logic (uses `retryable` gem)
+- **`Instrument`** — ActiveSupport::Notifications integration; `instrument_steps` for per-step events
+- **`ClusterLock`** — distributed locking via Zookeeper
+
+### Version Compatibility (`lib/business_flow/compat.rb`)
+
+Shims for `Module#module_parents` and `ActiveModel::Errors#merge!` across ActiveModel versions. `BusinessFlow.active_model5?` gates version-specific behavior.
+
+## Testing Conventions
+
+- RSpec with `expect` syntax only (monkey patching disabled)
+- SimpleCov with branch coverage
+- `NotificationHelpers` module in spec_helper for testing ActiveSupport::Notifications
+- Appraisals matrix tests against ActiveModel 4.2, 5.2, 6.1, 7.0, 7.1, 7.2, 8.0
+- CircleCI runs rubocop, reek, and `appraisal rspec` across Ruby 3.1, 3.2, 3.3, 3.4
+
+## Style
+
+- RuboCop with 100-char line limit (relaxed in specs)
+- Reek for code smell detection
+- `frozen_string_literal: true` in all files
+
+## Commit Message Format
+
+Every commit must include a full human-Claude interaction log:
+
+```
+Brief description of what was done
+
+[Technical changes made]
+
+## Human-Claude Interaction Log
+
+### Human prompts (VERBATIM - include typos, informal language, COMPLETE text):
+**Include EVERY prompt since last commit - even short ones, corrections, clarifications**
+1. "[Copy-paste ENTIRE first prompt since last commit]"
+   → Claude: [What Claude did in response]
+
+2. "[Copy-paste ENTIRE second prompt]"
+   → Claude: [How Claude adjusted]
+
+[Continue numbering ALL prompts - don't skip any or judge importance]
+
+### Key decisions made:
+- Human guided: [specific guidance provided]
+- Claude discovered: [patterns found]
+
+🤖 Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Version bump commits use `v{VERSION}` as the first line (e.g. `v0.21.2`).
+
+## Release Process
+
+1. **Update version** in `lib/business_flow/version.rb`
+2. **Update `CHANGELOG.md`** — add a new version header with ENHANCEMENTS and/or BUG FIXES sections
+3. **Commit** the version bump and changelog (see commit format above)
+4. **Push** to origin — CircleCI will run the full test matrix (rubocop, reek, appraisal rspec across Ruby 3.1–3.4)
+5. **Verify CI passes** before releasing
+6. **Run `bundle exec rake release`** — this creates a `v{VERSION}` git tag, builds the gem, pushes the tag, and publishes to rubygems.org (requires MFA)

data/lib/business_flow/dsl.rb

@@ -325,7 +325,9 @@ module BusinessFlow
     end
 
     def _business_flow_parameter_inner_fetch(key)
-      if @parameter_object.is_a?(Hash) && @parameter_object.key?(key)
+      if @parameter_object.respond_to?(:key?) &&
+         @parameter_object.respond_to?(:[]) &&
+         @parameter_object.key?(key)
         @parameter_object[key]
       else
         @parameter_object.public_send(key)

data/lib/business_flow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BusinessFlow
-  VERSION = '0.21.2'
+  VERSION = '0.21.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: business_flow
 version: !ruby/object:Gem::Version
-  version: 0.21.2
+  version: 0.21.3
 platform: ruby
 authors:
 - Alex Scarborough
@@ -64,6 +64,7 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile