hub_kernel 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03e711745ec2a1b5caccf83f09e80cad02ba4214cc7eff72745c2a6d760e175e
-  data.tar.gz: f3bc9c33cd2f1ae4878f9cb9dd2216ebda64c2c3628f7d1a29794dee4f10ef11
+  metadata.gz: 6c55c177c5ca371059cf35185392a5b283a314254dff6b18aa2d13f7c12793cd
+  data.tar.gz: 23afef8f196447cecf97c1b2e0355aba897388784e2c1ddb80d6ff7ff9da7f98
 SHA512:
-  metadata.gz: 443d578d53ebb20b08fb3e3c3557df70780f8f85e8aab44af99c68ee6f3311897649210b544ba6356b4d1e7a1692576e36e84c36daed045ab2d47270ddc69b2c
-  data.tar.gz: 833fba7864e95ad4ff7e18284bd07998f7ff30df5269489c879a447541e207997ebeb09d2dafad1596aa0299c7a05259d2e997682c6b5edffe490772f405a061
+  metadata.gz: 61caa0ec7d31d6fbd86dc005dae507895eb2a7e4a1f1c09b3be2976edbc8ff69b5f14108a007dffe38b501b4d773250544ed625457d87e8ed7cbdf7f811796ff
+  data.tar.gz: 532c56d1800f02ab79faab68553fc75edd7f20bdcbc8677d2a4e7416dde7ec063ff79c94825db9bf99f10bd380b5874d52657e6beef5a03b8ef08532b6c71a93

data/README.md

@@ -4,16 +4,43 @@ Gives every hub in a Rails app one way to declare what it needs from another hub
 ## Usage
 
 ### Starting a hub
-The generator writes a new hub's module and its test. Name each port as the port and
-the method the hub's own code calls:
+A hub usually lives in a domain gem, next to the domain logic it serves. Run the
+generator from the gem's root, naming each port as the port and the method the hub's
+own code calls:
 
 ```bash
-bin/rails generate hub_kernel:hub Console::Hubs::Billing spend_recorder:record_spend
+bin/rails generate hub_kernel:hub Ledger entry_recorder:record_entry
 ```
 
-It writes `app/models/console/hubs/billing.rb`, which extends `HubKernel::Ports` and
-declares each port, and `test/models/console/hubs/billing_test.rb`, which includes the
-hub check below. The app then fills the new ports where it fills its others.
+Inside a Rails engine gem it writes the hub under the gem's namespace, such as
+`app/models/billing/ledger.rb` with `module Billing::Ledger`, which extends
+`HubKernel::Ports` and declares each port. It also adds hub_kernel to the gem's
+gemspec. It writes no hub check into the gem's tests, since the gem never fills its own
+ports.
+
+### Using a hub from a gem
+The app that installs the gem fills each of the hub's ports in its own setup, then
+runs the start check:
+
+```ruby
+Rails.application.config.to_prepare do
+  Billing::Ledger.entry_recorder = Finance.method(:record_entry)
+  HubKernel::Hubs.check!
+end
+```
+
+The app's own test for that hub includes the hub check, where the ports are filled:
+
+```ruby
+class Billing::LedgerHubTest < ActiveSupport::TestCase
+  include HubKernel::Conformance::Hub
+
+  hub { Billing::Ledger }
+end
+```
+
+Run inside an app rather than a gem, the generator writes the hub under
+`app/models` and its hub check under `test/models`.
 
 ### Ports
 A port is something a hub needs from outside itself. The hub declares it by name,
@@ -89,6 +116,24 @@ Supplies.exposed("record_purchase").takes # => [:supplier_id, :bought_on, :lines
 Supplies.exposed("delete_everything")     # => nil
 ```
 
+### The exposed-list check
+A hub's own test can check its exposed list, so a listed method the hub lacks, or one
+listed with values it does not take, shows in the suite rather than on a caller's
+request:
+
+```ruby
+require "hub_kernel/conformance/exposed"
+
+class SuppliesHubTest < ActiveSupport::TestCase
+  include HubKernel::Conformance::Exposed
+
+  hub { Supplies }
+end
+```
+
+The test fails and names each problem. A method that takes `**` values accepts any
+values it is listed with, as long as it is listed with each value it requires.
+
 ## Installation
 Add this line to your application's Gemfile:
 

data/lib/generators/hub_kernel/hub/hub_generator.rb

@@ -14,6 +14,8 @@ module HubKernel
       end
 
       def create_hub_test
+        return if gemspec
+
         create_file "test/models/#{file_path}_test.rb", <<~RUBY
           require "test_helper"
           require "hub_kernel/conformance/hub"
@@ -26,8 +28,16 @@ module HubKernel
         RUBY
       end
 
+      def depend_on_hub_kernel
+        return unless gemspec
+
+        inject_into_file gemspec, "  spec.add_dependency \"hub_kernel\", \"~> #{HubKernel::VERSION[/\A\d+\.\d+/]}\"\n", before: /^end\s*\z/
+      end
+
       private
 
+      def gemspec = Dir.glob("*.gemspec", base: destination_root).first
+
       def port_lines
         return "" if ports.empty?
 

data/lib/hub_kernel/conformance/exposed.rb

@@ -0,0 +1,22 @@
+require "active_support/concern"
+
+module HubKernel
+  module Conformance
+    module Exposed
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def hub(&block)
+          define_method(:the_hub, &block)
+        end
+      end
+
+      included do
+        test "every method the hub exposes exists and takes the values it is listed with" do
+          problems = the_hub.exposure_problems
+          flunk problems.join("\n") if problems.any?
+        end
+      end
+    end
+  end
+end

data/lib/hub_kernel/exposes.rb

@@ -8,8 +8,29 @@ module HubKernel
 
     def exposed(name) = exposed_methods[name.to_s]
 
+    def exposure_problems
+      exposed_methods.values.filter_map { |exposure| exposure_problem(exposure) }
+    end
+
     private
 
     def exposed_methods = @exposed_methods ||= {}
+
+    def exposing_hub = name.demodulize
+
+    def exposure_problem(exposure)
+      return "#{exposing_hub} exposes #{exposure.name}, which it has no method for" unless respond_to?(exposure.name)
+      return if takes_listed_values?(exposure)
+
+      "#{exposing_hub} exposes #{exposure.name} with #{exposure.takes.join(", ")}, but it takes #{keywords(exposure, :keyreq, :key).join(", ")}"
+    end
+
+    def takes_listed_values?(exposure)
+      (keywords(exposure, :keyreq) - exposure.takes).empty? && (takes_any_values?(exposure) || (exposure.takes - keywords(exposure, :keyreq, :key)).empty?)
+    end
+
+    def takes_any_values?(exposure) = method(exposure.name).parameters.any? { |kind, _| kind == :keyrest }
+
+    def keywords(exposure, *kinds) = method(exposure.name).parameters.filter_map { |kind, value| value if kinds.include?(kind) }
   end
 end

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - tylercschneider
@@ -42,6 +42,7 @@ files:
 - lib/hub_kernel/answer.rb
 - lib/hub_kernel/authz.rb
 - lib/hub_kernel/conformance/action.rb
+- lib/hub_kernel/conformance/exposed.rb
 - lib/hub_kernel/conformance/hub.rb
 - lib/hub_kernel/conformance/partial.rb
 - lib/hub_kernel/context.rb