hub_kernel 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e8e24b52cfa8070ea79fc420ec714555b3e81377725ac9ea8e8a3a20ac280bb
-  data.tar.gz: 130ba409bb6db19a6cd0d1c34ffc535407ba03255f8e282bd2f333c53bef6000
+  metadata.gz: d5519634e5f01317012e931057dc2caa508996a18ee0f952ee6e4de867f285ff
+  data.tar.gz: 5477988282902fb115811f3f08f6a7eebe8547eee1f7a5ec9c56a3b8f758272c
 SHA512:
-  metadata.gz: d159cfc7e9b03980d03de84433ca09d3f1b5a11d758b10a3412a54eff96b8636b1187d9b2e4d54d2582ef7610d43c8df0e63c8a99de1553f17cb698175b34e9a
-  data.tar.gz: 7e075af8fa7fbe2cc6b7952a45c5a710c7702a39686cf38b0b121166c39f89f06f53e3e9114e3543e606cb22e9628c42ca09f96ba70ceafe31922b74bf491dce
+  metadata.gz: bf9219c9a2027f881df22d5aca5149f34408fb6c91156f550ab9fbd992c572d4bc3bfb31f944722fbb73154c37646ef3a3386e9049f3d5aefaf82a5962727f3c
+  data.tar.gz: 70344238486a35ed0bff5707898f24f3ee807647cb03f95e0b9426fd640a1506a968fb13dc561d18ab13e1262d203c887c0ae83e2aad7db070e8be095412943e

data/README.md

@@ -164,9 +164,62 @@ link. A boot with eager loading on defines it the same way. After a code reload
 development, the reloaded model has the link again, and it points at the reloaded model
 the app fills the port with.
 
+A link that names a port its hub does not declare, or one of the hub's call ports, raises
+an `ArgumentError` when the model loads, naming the model, the hub and the port. A link
+whose `port:` is not a hub module raises an `ArgumentError` naming the model.
+
 The model names only its own hub, so the crossing check passes it. The app's
 `to_prepare` block that fills the port is the one place both models are named.
 
+### Has-many links through a record port
+A hub's model lists the records another hub owns that point back at it with
+`has_many_port`, naming its own hub and one of that hub's record ports:
+
+```ruby
+module Sales
+  class Job < ApplicationRecord
+    has_many_port :quotes, port: Sales, record: :quote_record
+  end
+end
+```
+
+hub_kernel defines an ordinary `has_many :quotes` whose class is the model the app filled
+the port with. `job.quotes` lists the quotes, and `includes`, `preload`, `joins`, `where`
+and `order` work on the link as on any `has_many`. Every other `has_many` option, such as
+`foreign_key:` or `inverse_of:`, and a scope passed before the options, reach the
+association unchanged, apart from the options below that write to the listed records.
+The class name comes from the port, so one passed is not used.
+
+A has-many link is always read-only, and no option makes it writable:
+
+- A record listed through the link, loaded, preloaded or queried, raises
+  `ActiveRecord::ReadOnlyRecord` when it is saved or destroyed.
+- Adding a record to the list with `<<`, `push`, `append`, `concat` or `replace`, removing
+  one with `delete`, `destroy`, `delete_all`, `destroy_all` or `clear`, and building or
+  creating one with `build`, `new`, `create` or `create!` raise
+  `ActiveRecord::ReadOnlyRecord`, on the list and on a query made from it.
+- Assigning the list with `quotes=` or `quote_ids=` raises `ActiveRecord::ReadOnlyRecord`.
+- Writing the listed records all at once with `update_all`, `update_counters`, `insert`,
+  `insert!`, `insert_all`, `insert_all!`, `upsert` or `upsert_all` raises
+  `ActiveRecord::ReadOnlyRecord`.
+- `autosave`, `counter_cache` and a `dependent` value that destroys, deletes or nullifies
+  the listed records each write to them, so passing any of them raises an `ArgumentError`
+  naming it.
+
+`dependent: :restrict_with_exception` and `dependent: :restrict_with_error` write nothing
+to the listed records, so the link takes them. Deleting the model while the link lists
+records is refused, the first way by raising `ActiveRecord::DeleteRestrictionError` and
+the second by adding an error and returning false, and deleting it when the link lists
+none goes ahead.
+
+The link is defined as soon as both the model has loaded and the port is filled, in
+whichever order those happen, the same way as a `belongs_to_port` link. A boot with eager
+loading on defines it, and after a code reload in development the reloaded model lists
+the reloaded model the app fills the port with.
+
+A has-many link refuses a port that is not one of its hub's record ports, and a `port:`
+that is not a hub module, in the same way as a `belongs_to_port` link.
+
 ### The start check
 Every hub that declares a port or exposes a method is on `HubKernel::Hubs.list`. Call
 `HubKernel::Hubs.check!` after the app fills its ports, and the app refuses to start
@@ -347,6 +400,30 @@ end
   `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.
 
+### The unlinked id check
+A host's test can check that every link a hub's model makes is an association, so a new
+link to another hub's record cannot be added as a bare id column:
+
+```ruby
+require "hub_kernel/conformance/unlinked_ids"
+
+class UnlinkedIdsTest < ActiveSupport::TestCase
+  include HubKernel::Conformance::UnlinkedIds
+
+  unlinked_ids except: [ "Billing::Invoice#legacy_id" ]
+end
+```
+
+- The test reads every Active Record model under each hub folder's `app/models`, and
+  fails naming each column ending in `_id` that no `belongs_to` on that model uses as its
+  foreign key, such as "Kitchen::Dish#oven_id has no association using it".
+- A `belongs_to_port` link counts, and so does an ordinary `belongs_to` inside a hub.
+- `except` lists columns the test does not report, each written as the model and the
+  column joined by `#`. The `unlinked_ids` line may be left out when there are none.
+- Abstract classes and models whose table does not exist are skipped.
+- The test fails with "The unlinked id check found no model with a table in any hub
+  folder" when it finds none, so a wrong setup does not pass unnoticed.
+
 ## Installation
 Add this line to your application's Gemfile:
 

data/lib/hub_kernel/conformance/unlinked_ids.rb

@@ -0,0 +1,41 @@
+require "active_support/concern"
+require "hub_kernel/hub_folders"
+
+module HubKernel
+  module Conformance
+    module UnlinkedIds
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def unlinked_ids(except: [])
+          define_method(:unlinked_id_exceptions) { except }
+        end
+      end
+
+      included do
+        test "every id column of a hub model has an association" do
+          flunk "The unlinked id check found no model with a table in any hub folder" if hub_models.none?
+
+          found = hub_models.flat_map { |model| unlinked_columns(model).map { |column| "#{model.name}##{column}" } } - unlinked_id_exceptions
+          found = found.map { |entry| "#{entry} has no association using it" }
+          assert found.empty?, found.join("\n")
+        end
+      end
+
+      def unlinked_id_exceptions = []
+
+      def hub_models = @hub_models ||= tabled_hub_models
+
+      def tabled_hub_models
+        Dir.glob("#{HubKernel::HubFolders.code_glob}/models/**/*.rb", base: Rails.root).sort
+          .map { |path| path.sub(%r{\A.*?/models/}, "").delete_suffix(".rb").camelize.safe_constantize }
+          .select { |model| model.is_a?(Class) && model < ActiveRecord::Base && !model.abstract_class? && model.table_exists? }
+      end
+
+      def unlinked_columns(model)
+        linked = model.reflect_on_all_associations(:belongs_to).map { |association| association.foreign_key.to_s }
+        model.column_names.select { |column| column.end_with?("_id") }.sort - linked
+      end
+    end
+  end
+end

data/lib/hub_kernel/port_associations.rb

@@ -1,27 +1,53 @@
 module HubKernel
   module PortAssociations
     WRITING_OPTIONS = %i[autosave dependent touch counter_cache].freeze
+    LIST_WRITING_OPTIONS = %i[autosave dependent counter_cache].freeze
+    RESTRICTING = %i[restrict_with_error restrict_with_exception].freeze
+    LIST_WRITING_METHODS = %i[<< push append concat build new create create! delete destroy delete_all destroy_all clear replace update_all insert insert! insert_all insert_all! upsert upsert_all].freeze
 
     def belongs_to_port(name, scope = nil, port:, record:, **options)
       refuse_writing_options(name, options)
+      refuse_non_hub(name, port)
       port.link_record(record, [ self.name, name ]) do |model|
         belongs_to name, read_only(scope), **options, class_name: model.name
         refuse_creating_through(name)
       end
     end
 
+    def has_many_port(name, scope = nil, port:, record:, **options)
+      refuse_writing_options(name, options.reject { |option, value| option == :dependent && RESTRICTING.include?(value) }, LIST_WRITING_OPTIONS)
+      refuse_non_hub(name, port)
+      refusal = "#{self.name}'s #{name} link is read-only, so no record can be written through it"
+      port.link_record(record, [ self.name, name ]) do |model|
+        has_many name, read_only(scope, refusing_list(refusal)), **options, class_name: model.name
+        refuse_replacing_list(name, refusal)
+      end
+    end
+
     private
 
-    def refuse_writing_options(name, options)
-      writing = options.keys & WRITING_OPTIONS
+    def refuse_writing_options(name, options, writers = WRITING_OPTIONS)
+      writing = options.keys & writers
       raise ArgumentError, "#{name} is a read-only record port link, so it does not take #{writing.to_sentence}" if writing.any?
     end
 
-    def read_only(scope)
-      return -> { readonly } unless scope
-      return -> { instance_exec(&scope).readonly } if scope.arity.zero?
+    def refuse_non_hub(name, port)
+      raise ArgumentError, "#{self.name} links #{name} through #{port}, which is not a hub module" unless port.is_a?(HubKernel::Ports)
+    end
+
+    def read_only(scope, *extensions)
+      return -> { readonly.extending(*extensions) } unless scope
+      return -> { instance_exec(&scope).readonly.extending(*extensions) } if scope.arity.zero?
+
+      ->(owner) { instance_exec(owner, &scope).readonly.extending(*extensions) }
+    end
+
+    def refusing_list(refusal)
+      Module.new { LIST_WRITING_METHODS.each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } } }
+    end
 
-      ->(owner) { instance_exec(owner, &scope).readonly }
+    def refuse_replacing_list(name, refusal)
+      [ :"#{name}=", :"#{name.to_s.singularize}_ids=" ].each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } }
     end
 
     def refuse_creating_through(name)

data/lib/hub_kernel/ports.rb

@@ -22,6 +22,8 @@ module HubKernel
     end
 
     def link_record(name, model_and_link, &link)
+      refuse_link(name, model_and_link, "#{self.name} does not declare") unless declared_ports.include?(name)
+      refuse_link(name, model_and_link, "is a call port, not a record port") unless record_ports.include?(name)
       links_to(name)[model_and_link] = link
       filling = public_send(name)
       link.call(filling) if active_record_model?(filling)
@@ -50,7 +52,11 @@ module HubKernel
 
     def record_ports = @record_ports ||= []
 
-    def links_to(name) = (@record_links ||= {})[name] ||= {}
+    def refuse_link(name, (model, link), reason)
+      raise ArgumentError, "#{model} links #{link} through #{self.name} #{name}, which #{reason}"
+    end
+
+    def links_to(name) =(@record_links ||= {})[name] ||= {}
 
     def fill_record_port(name, model)
       instance_variable_set(:"@#{name}", model)

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.25.0"
+  VERSION = "0.27.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - tylercschneider
@@ -59,6 +59,7 @@ files:
 - lib/hub_kernel/conformance/exposed.rb
 - lib/hub_kernel/conformance/hub.rb
 - lib/hub_kernel/conformance/partial.rb
+- lib/hub_kernel/conformance/unlinked_ids.rb
 - lib/hub_kernel/crossings.rb
 - lib/hub_kernel/engine.rb
 - lib/hub_kernel/follow_up.rb