zen-service 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83f9ef4ebaca920508cb7aa96f3ce4eea6b899338b000c5a38edc6cacf342473
-  data.tar.gz: 86a27632c1fc83f7ba7c735bea83c41a1b0d9e52b2d546bfdd3054e4766c447d
+  metadata.gz: 12dcff33c206c08f710f8cedf505f663387054b22aa6429556b20c47eac6b410
+  data.tar.gz: b314175b5a9a5634480ac0c4fbec0777fa895e68687eedbaad8382f1b26600fe
 SHA512:
-  metadata.gz: 755c8e023bed8067af7fd509018ff8a001cb5618cde43fc00aa6b0244165482d58fadea79becc7b4ebb9f6a1e87aef9d9901aebd54e2218390553c2fcd71edbc
-  data.tar.gz: 55ae83ddff091119dff6b1448e37e704dcdf39cdc616fcc11b51cccd3c979113e41df8396c1cb5688c459dcc3002534ea2f512c54815a3ceecf85cc74e89d8b5
+  metadata.gz: 3bb64af64bf4641e01b686bf4b8bda93e5efcd8188d1ed6d1a864c74e0f2d916b03383345476c0aa1a860b3bae9ba6fbf370f6e309905d7ef5cb1186fd561b7d
+  data.tar.gz: b2678a54e99637e8d1706a6ccd913346d9e64d7ea0ef46e2c7e5637683844ab21220b6c1422601fc8466178358377e6da092cc0320cc5f6e427052b5e1b786f1

data/.github/copilot-instructions.md

@@ -0,0 +1,133 @@
+# Copilot Instructions for zen-service
+
+## Project Overview
+
+`zen-service` is a Ruby gem providing a flexible, plugin-based service object pattern. The architecture emphasizes extensibility through a plugin system where even core functionality (callable, attributes) is implemented as plugins.
+
+## Architecture Fundamentals
+
+### Plugin System
+
+The entire gem is built around `Zen::Service::Plugins` - a dynamic plugin registration and loading system:
+
+- Plugins auto-register using `extend Zen::Service::Plugins::Plugin` (converts module name to snake_case key)
+- Services use plugins via `use :plugin_name, **options`
+- Plugin lifecycle: `used(service_class)` → includes module → `configure(service_class)` if defined
+- See [plugin.rb](lib/zen/service/plugins/plugin.rb) for the DSL: `register_as`, `default_options`, `service_extension`
+
+### Core Plugins Architecture
+
+Base `Zen::Service` uses two foundational plugins:
+
+- `:callable` - provides `.call` and `.[]` class methods that instantiate + call
+- `:attributes` - manages initialization parameters with runtime validation
+
+### Service Attributes Pattern
+
+Attributes are positional-or-named parameters resolved during initialization:
+
+```ruby
+attributes :foo, :bar
+new(1, bar: 2) # foo=1, bar=2
+new(foo: 1)    # foo=1, bar=nil
+```
+
+- Attributes generate reader methods dynamically in a dedicated `AttributeMethods` module
+- Each service class gets its own `AttributeMethods` constant to isolate attribute methods
+- `with_attributes(hash)` creates clones with merged attributes
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+bundle exec rspec spec          # Run all specs
+bundle exec rspec spec/zen/service_spec.rb  # Single file
+rake                            # Run specs + rubocop
+```
+
+### Test Patterns
+
+- Use `def_service { ... }` helper to define service classes in specs (see [spec_helper.rb](spec/spec_helper.rb))
+- `build_service(*args, **kwargs)` instantiates service with attributes
+- Services are frozen_string_literal by convention
+
+### Building & Releasing
+
+```bash
+rake build                      # Build gem to pkg/
+rake install                    # Install locally
+rake release                    # Tag + push to rubygems.org
+```
+
+## Key Conventions
+
+### Plugin Implementation Pattern
+
+1. Create module in `lib/zen/service/plugins/`
+2. `extend Zen::Service::Plugins::Plugin` (auto-registers)
+3. Define `used(service_class, **opts, &block)` for one-time setup
+4. Define `configure(service_class, **opts, &block)` for reconfiguration
+5. Use `prepend Extension` (for wrapping `call`) or `include` (for adding methods)
+6. Add `ClassMethods` module for class-level functionality
+
+Example from [result_yielding.rb](lib/zen/service/plugins/result_yielding.rb):
+
+```ruby
+module ResultYielding
+  extend Plugin
+
+  module Extension
+    def call
+      return super unless block_given?
+      result = nil
+      super { result = yield }
+      result
+    end
+  end
+
+  def self.used(service_class)
+    service_class.prepend(Extension)
+  end
+end
+```
+
+### Plugin Option Handling
+
+- Use `default_options foo: 5` in plugin definition
+- Access via `self.class.plugins[:plugin_name].options[:foo]`
+- Options merge with defaults when using plugin
+
+### Inheritance Behavior
+
+- `attributes_list` is duplicated on inheritance
+- Each subclass gets its own `AttributeMethods` module
+- Plugin reflections accumulate through `ancestors.flat_map(&:service_plugins)`
+
+## Critical Implementation Details
+
+### Why Prepend vs Include
+
+- `prepend Extension` - use when wrapping `call` method (allows `super` to reach original)
+- `include` - use for adding new methods
+- See `:result_yielding` (prepend) vs `:persisted_result` (extend in initialize)
+
+### Attributes Resolution Edge Cases
+
+- Cannot pass same attribute as both positional and named
+- Cannot pass more attributes than declared
+- Args filled in declaration order, then kwargs merged
+
+### Plugin DSL Methods
+
+From [plugin.rb](lib/zen/service/plugins/plugin.rb):
+
+- `register_as :custom_name` - override auto-generated registration name
+- `default_options hash` - set default plugin options
+- `service_extension module` - extend `Zen::Service` base class globally
+
+## Files of Note
+
+- [plugins.rb](lib/zen/service/plugins.rb) - central plugin registry with `fetch` and `register`
+- [pluggable.rb](lib/zen/service/plugins/pluggable.rb) - `use` DSL and plugin reflection system
+- [spec_helper.rb](spec/spec_helper.rb) - `def_service` pattern for testing services

data/README.md

@@ -162,6 +162,18 @@ end
 Todos::Show[todo] # => { id: 1, isCompleted: true }
 ```
 
+**Note**: Custom plugins need to be registered before they can be used. Plugins that extend
+`Zen::Service::Plugin` are automatically registered when the module is loaded. Alternatively,
+you can register plugins manually:
+
+```rb
+# Register a plugin module
+Zen::Service::Plugins.register(:my_plugin, MyPlugin)
+
+# Register by class name (useful when autoload isn't available yet, e.g., during Rails boot)
+Zen::Service::Plugins.register(:my_plugin, "MyApp::Services::MyPlugin")
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.

data/lib/zen/service/plugins.rb

@@ -3,9 +3,10 @@
 module Zen
   module Service::Plugins
     def self.fetch(name)
-      require("zen/service/plugins/#{name}") unless plugins.key?(name)
+      raise("extension `#{name}` is not registered") unless plugins.key?(name)
 
-      plugins[name] || raise("extension `#{name}` is not registered")
+      extension = plugins[name]
+      extension.is_a?(String) ? constantize(extension) : extension
     end
 
     def self.register(name_or_hash, extension = nil)
@@ -28,6 +29,12 @@ module Zen
     def self.plugins
       @plugins ||= {}
     end
+
+    def self.constantize(string)
+      return string.constantize if string.respond_to?(:constantize)
+
+      string.sub(/^::/, "").split("::").inject(Object) { |obj, const| obj.const_get(const) }
+    end
   end
 
   require_relative "plugins/plugin"

data/lib/zen/service/version.rb

@@ -2,6 +2,6 @@
 
 module Zen
   class Service
-    VERSION = "2.1.0"
+    VERSION = "2.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zen-service
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-12-20 00:00:00.000000000 Z
+date: 2025-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -101,6 +101,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/copilot-instructions.md"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"