hub_kernel 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3efd66220ac58f67d7c6018b2e552f70641539e11da6ef13810d274cb1daea52
-  data.tar.gz: 803ca1aa3d1258ae639ae2a6beb842b8e969f213b3d604e07d7acff7b9dc6523
+  metadata.gz: 1bb347a71c0f40d275dc0c2d504fb186b474538a1b4ee80c7e4fd1270f064926
+  data.tar.gz: be51e4ff8a3b09e83cd2904745c39f30088c7471c0127f66fcd8107bc9f6272b
 SHA512:
-  metadata.gz: 111dfbefdd5d3fbb62241dc8142a5b16b8626f9af8d227df56033c60205a2d2bbd9db4a27fa39e487f31ea891dd1041a18c76519e5ba88e2a7a7279659e667cc
-  data.tar.gz: bac66dfb083524ae2f30f2db97c637df7d88a70f19ce59f264acdbc40baa24e39fa3218ef19d472713e3c3c6ba7df8cf959078f2993ceddbc0b9790b44badff1
+  metadata.gz: db66d8c988b25b8639cde40e2b0212b8a651fb4b831cd675b0b615e2b7ee1a85e9bdbee002be16c03bc91d1cb7ad32a904139b384049281b83804d30636ad37c
+  data.tar.gz: 5524ff6a33af31e8e9c039568daa6f0eeb2e8e12202d8f032d78ed890f54f90b662ac771b0e58213e569e8f837f040a8947af61161e95c18a3314188c2438db4

data/README.md

@@ -18,6 +18,36 @@ Inside a Rails engine gem it writes the hub under the gem's namespace, such as
 gemspec. It writes no hub check into the gem's tests, since the gem never fills its own
 ports.
 
+Run in an app, it writes the hub into its own folder, named after the last part of the
+hub's name: `Console::Hubs::Supplies` goes to
+`hubs/supplies/app/models/console/hubs/supplies.rb`, and its hub check to
+`test/hubs/supplies/console/hubs/supplies_test.rb`, which the app's normal test run
+reads.
+
+### A hub folder in the host app
+A hub that lives in the host app can keep its code in its own folder,
+`hubs/<hub>/app/<kind>/`, laid out like the app's own `app/` folder:
+
+```
+hubs/billing/app/models/billing/invoice.rb
+hubs/billing/app/jobs/billing/reminder_job.rb
+hubs/billing/app/event_definitions/billing/invoice_sent.rb
+```
+
+hub_kernel adds each of those folders to the host's load paths, so a class there loads
+by its full name, `Billing::Invoice`, just as it would from `app/models/`. Moving a
+class into its hub's folder changes nothing for the code that calls it. A namespace
+module may be defined in `app/models/` or in another hub's folder. A host with no
+`hubs/` folder loads exactly what it loads today.
+
+Files under a hub's `lib/` folder, such as its generated event pack, are not loaded.
+
+A hub folder's `views` are searched after the host's `app/views`, so a controller in the
+hub renders its templates from there, any view can render a hub partial by its usual
+path, and a template in `app/views` wins over one at the same path in a hub folder. A
+hub folder's `helpers` are added to the host's helper paths, so they are available
+wherever every helper is.
+
 ### 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:
@@ -209,6 +239,11 @@ class HubCrossingsTest < ActiveSupport::TestCase
 end
 ```
 
+- A file under a hub's folder, `hubs/<hub>/`, belongs to that hub, and so does each class
+  defined there, without any entry in `owners`. `owners` is only asked about files and
+  classes outside every hub folder, and may be left out once every hub has its folder.
+- By default the test reads every `.rb` and `.erb` file under `app/` and under each hub
+  folder's `app/`, helpers and services included.
 - A constant inside another hub's class counts as naming that class.
 - A name no hub owns, such as a namespace, is not a crossing, and neither is a class on
   the `shared` list.
@@ -218,7 +253,9 @@ end
 - A view belongs to the hub that owns its controller, then to the hub that owns the
   record its folder is named after, and otherwise to the `host_layer`.
 - The host's layer may name any hub's interface module, and a hub naming another hub's
-  interface module is a crossing.
+  interface module is a crossing. A hub's interface module is found in its folder, as the
+  module there that extends `HubKernel::Ports` or `HubKernel::Exposes`, so a hub in a
+  folder needs no entry in `interfaces`.
 - The test fails with "The crossing check found no files to read" when none of the files
   it read belongs to a hub or the host's layer, so a wrong `files:` pattern or an empty
   map does not pass unnoticed.
@@ -227,7 +264,14 @@ end
   own Shop::Receipt".
 - It fails naming each class the map names that no longer exists in the app, such as "The
   map names Shop::Ghost, which does not exist", so a renamed or removed class does not
-  stay in the map.
+  stay in the map. A class whose file sits in a hub folder is never reported this way.
+- While hubs move into folders, a class the map gives one hub whose file sits in another
+  hub's folder is owned by two hubs. A class the map still lists whose file already sits
+  in that hub's folder fails with "Shop::Purchase sits in its hub's folder, so take it off
+  the list".
+- It fails naming each folder under `hubs/` that holds no module extending
+  `HubKernel::Ports` or `HubKernel::Exposes`, such as "hubs/suplies holds no hub module",
+  so a misspelled or half-made hub folder does not pass unnoticed.
 
 ## Installation
 Add this line to your application's Gemfile:

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

@@ -1,4 +1,5 @@
 require "rails/generators/named_base"
+require "hub_kernel/hub_folders"
 
 module HubKernel
   module Generators
@@ -6,7 +7,7 @@ module HubKernel
       argument :ports, type: :array, default: [], banner: "port:method port:method"
 
       def create_hub
-        create_file "app/models/#{file_path}.rb", <<~RUBY
+        create_file "#{code_root}/models/#{file_path}.rb", <<~RUBY
           module #{class_name}
             extend HubKernel::Ports
           #{port_lines}end
@@ -16,7 +17,7 @@ module HubKernel
       def create_hub_test
         return if gemspec
 
-        create_file "test/models/#{file_path}_test.rb", <<~RUBY
+        create_file "#{HubKernel::HubFolders.test_folder(hub_folder)}/#{file_path}_test.rb", <<~RUBY
           require "test_helper"
           require "hub_kernel/conformance/hub"
 
@@ -38,6 +39,10 @@ module HubKernel
 
       def gemspec = Dir.glob("*.gemspec", base: destination_root).first
 
+      def code_root = gemspec ? "app" : "#{HubKernel::HubFolders.folder(hub_folder)}/#{HubKernel::HubFolders::CODE}"
+
+      def hub_folder = file_path.split("/").last
+
       def port_lines
         return "" if ports.empty?
 

data/lib/hub_kernel/conformance/crossings.rb

@@ -1,5 +1,6 @@
 require "active_support/concern"
 require "hub_kernel/crossings"
+require "hub_kernel/hub_folders"
 
 module HubKernel
   module Conformance
@@ -7,8 +8,8 @@ module HubKernel
       extend ActiveSupport::Concern
 
       class_methods do
-        def crossings(root: nil, files: "app/**/*.{rb,erb}", except: [], &block)
-          define_method(:the_crossings, &block)
+        def crossings(root: nil, files: "{app,#{HubKernel::HubFolders.code_glob}}/**/*.{rb,erb}", except: [], &block)
+          define_method(:built_crossings, &block)
           define_method(:crossing_root) { root || Rails.root }
           define_method(:crossing_files) { files }
           define_method(:crossing_exceptions) { except }
@@ -35,6 +36,16 @@ module HubKernel
           assert twice.empty?, twice.map { |name| "Two hubs own #{name}" }.join("\n")
         end
 
+        test "no class is both listed and in its hub's folder" do
+          listed = the_crossings.listed_in_their_folders
+          assert listed.empty?, listed.map { |name| "#{name} sits in its hub's folder, so take it off the list" }.join("\n")
+        end
+
+        test "every hub folder holds a hub module" do
+          bare = the_crossings.folders_without_hub_module
+          assert bare.empty?, bare.map { |folder| "#{folder} holds no hub module" }.join("\n")
+        end
+
         test "every class the map names exists" do
           missing = the_crossings.missing_classes
           assert missing.empty?, missing.map { |name| "The map names #{name}, which does not exist" }.join("\n")
@@ -42,6 +53,10 @@ module HubKernel
       end
 
       def crossing_paths = (Dir.glob(crossing_files, base: crossing_root) - crossing_exceptions).sort
+
+      def the_crossings = @the_crossings ||= built_crossings.read_folders(hub_files).read_hub_modules(hub_files.to_h { |path| [ path, File.read(File.join(crossing_root, path)) ] })
+
+      def hub_files = @hub_files ||= Dir.glob("#{HubKernel::HubFolders.code_glob}/**/*.rb", base: crossing_root)
     end
   end
 end

data/lib/hub_kernel/crossings.rb

@@ -1,9 +1,13 @@
+require "hub_kernel/hub_folders"
 require "active_support/core_ext/string/inflections"
 
 module HubKernel
   class Crossings
-    def initialize(owners:, shared: [], host_layer: nil, interfaces: {}, namespaces: {})
+    HUB_MODULE = /extend HubKernel::(Ports|Exposes)\b/
+    def initialize(owners: {}, shared: [], host_layer: nil, interfaces: {}, namespaces: {}, folder_files: [])
       @owners = owners
+      @folder_classes = {}
+      read_folders(folder_files)
       @shared = shared
       @host_layer = host_layer
       @interfaces = interfaces
@@ -15,15 +19,36 @@ module HubKernel
       source.scan(/[A-Z]\w*(?:::[A-Z]\w*)*/).filter_map { |name| owned_class_in(name) }.uniq.select { |name| crossing?(name, hub) }
     end
 
+    def read_folders(paths)
+      @folder_classes.merge!(paths.to_h { |path| [ HubFolders.class_of(path), HubFolders.hub_of(path) ] })
+      self
+    end
+
+    def read_hub_modules(sources)
+      sources.each do |path, source|
+        next unless source.match?(HUB_MODULE) && path.match?(HubFolders::CODE_PATH)
+
+        @interfaces = @interfaces.merge(HubFolders.hub_of(path) => HubFolders.class_of(path))
+      end
+      self
+    end
+
     def belongs?(path) = !owner_of_file(path).nil?
 
     def unowned_classes(paths)
-      paths.select { |path| path.end_with?(".rb") && !path.start_with?("app/views/") }.map { |path| class_of(path) }.reject { |name| owner_of(name) }
+      paths.select { |path| path.end_with?(".rb") && !path.start_with?("app/views/") && !HubFolders.hub_of(path) }.map { |path| class_of(path) }.reject { |name| owner_of(name) }
     end
 
-    def claimed_twice = @owners.values.flatten.tally.select { |_name, hubs| hubs > 1 }.keys
+    def claimed_twice
+      listed = @owners.values.flatten
+      listed.tally.select { |_name, hubs| hubs > 1 }.keys | @owners.flat_map { |hub, classes| classes.select { |name| @folder_classes.fetch(name, hub) != hub } }
+    end
+
+    def listed_in_their_folders = @owners.flat_map { |hub, classes| classes.select { |name| @folder_classes[name] == hub } }
 
-    def missing_classes = @owners.values.flatten.uniq.reject(&:safe_constantize)
+    def folders_without_hub_module = @folder_classes.values.uniq.reject { |hub| @interfaces.key?(hub) }.map { |hub| HubFolders.folder(hub) }
+
+    def missing_classes = @owners.values.flatten.uniq.reject { |name| @folder_classes.key?(name) || name.safe_constantize }
 
     private
 
@@ -46,13 +71,15 @@ module HubKernel
       space && "#{space}::#{name.delete_prefix("#{space}::").split("::").first}"
     end
 
-    def listed_owner_of(class_name) = @interfaces.key(class_name) || @owners.find { |_hub, classes| classes.include?(class_name) }&.first
+    def listed_owner_of(class_name) = @interfaces.key(class_name) || @folder_classes[class_name] || @owners.find { |_hub, classes| classes.include?(class_name) }&.first
 
     def owner_of(class_name) = listed_owner_of(class_name) || owner_of_namespace(class_name)
 
     def owner_of_namespace(class_name) = @namespaces.find { |_hub, spaces| spaces.any? { |space| class_name.start_with?("#{space}::") } }&.first
 
     def owner_of_file(path)
+      return HubFolders.hub_of(path) if HubFolders.hub_of(path)
+
       return owner_of_view_folder(File.dirname(path.delete_prefix("app/views/")).camelize) if path.start_with?("app/views/")
 
       owner_of(class_of(path))

data/lib/hub_kernel/engine.rb

@@ -1,5 +1,19 @@
+require "hub_kernel/hub_folders"
+
 module HubKernel
   class Engine < ::Rails::Engine
     isolate_namespace HubKernel
+
+    initializer "hub_kernel.hub_folders", before: :set_load_path do |app|
+      folders = HubFolders.code_paths(app.root)
+      app.config.autoload_paths.concat(folders)
+      app.config.eager_load_paths.concat(folders)
+      app.config.helpers_paths.concat(HubFolders.helper_paths(app.root))
+    end
+
+    initializer "hub_kernel.hub_views" do |app|
+      views = HubFolders.view_paths(app.root)
+      ActiveSupport.on_load(:action_controller) { append_view_path(views) }
+    end
   end
 end

data/lib/hub_kernel/hub_folders.rb

@@ -0,0 +1,25 @@
+module HubKernel
+  module HubFolders
+    ROOT = "hubs".freeze
+    CODE = "app".freeze
+
+    PATH = %r{\A#{ROOT}/([^/]+)/}
+    CODE_PATH = %r{\A#{ROOT}/[^/]+/#{CODE}/[^/]+/}
+
+    def self.folder(hub) = "#{ROOT}/#{hub}"
+
+    def self.test_folder(hub) = "test/#{folder(hub)}"
+
+    def self.code_glob = "#{ROOT}/*/#{CODE}"
+
+    def self.hub_of(path) = path[PATH, 1]&.to_sym
+
+    def self.class_of(path) = path.sub(CODE_PATH, "").delete_suffix(".rb").camelize
+
+    def self.code_paths(root) = Dir[root.join("#{code_glob}/*")]
+
+    def self.view_paths(root) = Dir[root.join("#{code_glob}/views")]
+
+    def self.helper_paths(root) = Dir[root.join("#{code_glob}/helpers")]
+  end
+end

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - tylercschneider
@@ -62,6 +62,7 @@ files:
 - lib/hub_kernel/crossings.rb
 - lib/hub_kernel/engine.rb
 - lib/hub_kernel/follow_up.rb
+- lib/hub_kernel/hub_folders.rb
 - lib/hub_kernel/hubs.rb
 - lib/hub_kernel/markup.rb
 - lib/hub_kernel/ports.rb