janela 0.7.0 → 0.8.0

data/lib/janela/doctor.rb

@@ -134,22 +134,43 @@ module Janela
 
       # Ransack's allowlist is per class, so a dimension read through an
       # association needs the associated model to allow the attribute too.
+      #
+      # Grouped by the allowlist that has to be written rather than by the
+      # dimension that led here, because that is what the finding is about and
+      # there is one of it. Two dimensions reading through the same
+      # association used to produce two findings whose suggested lines
+      # contradicted each other, so a host pasting both kept the second and
+      # silently lost the first; an STI family produced a copy of each per
+      # class, since a subclass shares its parent's associations (#44).
       def through_dimensions_without_an_allowlist
-        janela_models.flat_map do |model|
-          model.janela.dimensions.values.select(&:through).filter_map do |dimension|
+        missing_allowlist_entries.map do |klass, entry|
+          allowed = klass.ransackable_attributes.map(&:to_s)
+          Finding.new(severity: :error,
+            summary: "#{klass} does not allow filtering on #{entry[:columns].sort.to_sentence}",
+            detail: "  Ransack's allowlist is per class, and these read through an association:\n" \
+                    "#{entry[:sources].sort.map { |source| "    #{source}" }.join("\n")}\n" \
+                    "  Add to #{klass}:\n" \
+                    "    def self.ransackable_attributes(_auth_object = nil) = " \
+                    "%w[#{(allowed + entry[:columns].sort).uniq.join(' ')}]")
+        end
+      end
+
+      # Keyed on the associated class rather than on the declaration, because a
+      # subclass may reflect an association its parent does not: two classes
+      # sharing a declaration and an association share a fix, and two that do
+      # not have a fix each. The source list names declaring classes, so an STI
+      # family is one line rather than one per subclass.
+      def missing_allowlist_entries
+        janela_models.each_with_object({}) do |model, missing|
+          model.janela.dimensions.values.select(&:through).each do |dimension|
             association = model.reflect_on_association(dimension.through)
             next unless association
+            next if association.klass.ransackable_attributes.map(&:to_s).include?(dimension.column.to_s)
 
-            allowed = association.klass.ransackable_attributes.map(&:to_s)
-            next if allowed.include?(dimension.column.to_s)
-
-            Finding.new(severity: :error,
-              summary: "#{association.klass} does not allow filtering on #{dimension.column}",
-              detail: "  #{model}'s #{dimension.name.inspect} dimension reads it through " \
-                      "#{dimension.through.inspect}, and Ransack's allowlist is per class. Add to " \
-                      "#{association.klass}:\n" \
-                      "    def self.ransackable_attributes(_auth_object = nil) = " \
-                      "%w[#{(allowed + [ dimension.column.to_s ]).uniq.join(' ')}]")
+            entry = missing[association.klass] ||= { columns: [], sources: [] }
+            entry[:columns] |= [ dimension.column.to_s ]
+            entry[:sources] |= [ "#{model.janela.declared_by}'s #{dimension.name.inspect} dimension, " \
+                                 "through #{dimension.through.inspect}" ]
           end
         end
       end
@@ -158,11 +179,23 @@ module Janela
       # but one written into the host's own Ruby is source like any other
       # identifier this doctor already greps for (ADR 015, ADR 021, ADR 025).
       def hardcoded_disallowed_predicates
-        janela_models.flat_map do |model|
-          model.janela.dimensions.values.flat_map { |dimension| disallowed_uses(model, dimension) }
+        janela_definitions.flat_map do |definition|
+          definition.dimensions.values.flat_map { |dimension| disallowed_uses(definition.declared_by, dimension) }
         end
       end
 
+      # One finding per declaration rather than one per class that inherits it.
+      # An STI family shares its parent's dimensions (ADR 031), so iterating
+      # models multiplied the same finding by the size of the family (#44).
+      def janela_definitions
+        janela_models.filter_map(&:janela).uniq(&:declared_by)
+      end
+
+      # The match is a string in a file, and nothing here establishes that the
+      # file filters this model, or filters anything: a comment warning against
+      # the predicate reads the same as a call. So the finding says what was
+      # seen and admits the limit, and is a warning rather than an error
+      # (ADR 021, ADR 035, #51).
       def disallowed_uses(model, dimension)
         pattern = /\b#{Regexp.escape(dimension.ransack_name)}(_\w+)/
         source_files.flat_map do |file|
@@ -174,10 +207,12 @@ module Janela
 
             key = "#{dimension.ransack_name}_#{predicate}"
             allowed = dimension.allowed_predicates.map { |p| "#{dimension.ransack_name}_#{p}" }
-            Finding.new(severity: :error,
+            Finding.new(severity: :warning,
               summary: "#{model} does not allow #{key}",
-              detail: "  #{file.relative_path_from(@root)} filters #{model} on #{key}, which Janela now " \
-                      "refuses (ADR 025). Allowed here: #{allowed.join(', ')}.")
+              detail: "  #{file.relative_path_from(@root)} mentions #{key}, which Janela refuses on " \
+                      "#{model} (ADR 025). Allowed here: #{allowed.join(', ')}.\n" \
+                      "  This reads your source for the name and cannot tell which model a match\n" \
+                      "  belongs to, so it may be another model's filter, or prose about one.")
           end
         end
       end
@@ -186,14 +221,35 @@ module Janela
       # and since ADR 032 every dashboard raises rather than answering with
       # every row. Reported so it is found here rather than by a visitor.
       #
-      # Where unauthenticated_endpoints has to hedge, because what counts as
-      # authentication cannot be determined by reading, this one is exact: the
-      # method is defined or it is not, and that is the whole contract.
+      # ADR 032 called this check exact, on the reasoning that the method is
+      # defined or it is not. That was wrong, and ADR 035 supersedes it: Pundit
+      # defines policy_scope the moment it is included, whether or not the
+      # model has a policy, so for the commonest authorisation library defined
+      # and works are different questions. The check makes the call Janela
+      # makes rather than reading the method table (#51).
       def unscoped_reads
-        parent = Janela.parent_controller.safe_constantize
+        parent = parent_controller
         return unless parent
-        return if parent.private_method_defined?(:policy_scope) || parent.method_defined?(:policy_scope)
+        return undefined_policy_scope(parent) unless answers_policy_scope?(parent)
+        return unless Janela::Frame.table_exists? && Janela::Snapshot.table_exists?
+
+        [ Janela::Frame, Janela::Snapshot ].filter_map do |model|
+          outcome, answer = ask_for_scope(model)
+          next unless outcome == :raised
+
+          Finding.new(severity: :error,
+            summary: "#{parent}'s policy_scope raises for #{model}, so every pane will too",
+            detail: "  Janela makes this exact call on every dashboard request, and got:\n" \
+                    "    #{answer.class}: #{answer.message.to_s.lines.first.to_s.strip.truncate(140)}\n" \
+                    "  Janela's own records go through your policy like any other model's, so\n" \
+                    "  they need whatever yours need: with Pundit that is a policy class for\n" \
+                    "  #{model}. docs/multi-tenancy.md has the wiring.")
+        end
+      rescue StandardError
+        nil # no database to ask yet
+      end
 
+      def undefined_policy_scope(parent)
         Finding.new(severity: :error,
           summary: "#{parent} defines no policy_scope, so every pane will raise",
           detail: "  Janela asks your controller what may be read and refuses to guess.\n" \
@@ -204,15 +260,19 @@ module Janela
                   "  narrower; docs/multi-tenancy.md has the wiring for the usual libraries.")
       end
 
+      def answers_policy_scope?(parent)
+        parent.private_method_defined?(:policy_scope) || parent.method_defined?(:policy_scope)
+      end
+
       # A host whose policy filters frames by owner, but which never tells
       # Janela what owns a new one, creates frames its own scope then hides.
       # The failure is silent, and a typo in the method name looks the same as
       # not defining it, which is the cost of asking by duck typing (ADR 019).
       def frames_nobody_will_own
-        parent = Janela.parent_controller.safe_constantize
-        return unless parent&.private_method_defined?(:policy_scope) || parent&.method_defined?(:policy_scope)
+        parent = parent_controller
+        return unless parent && answers_policy_scope?(parent)
         return if parent.private_method_defined?(:janela_frame_owner) || parent.method_defined?(:janela_frame_owner)
-        return unless Janela::Frame.table_exists? && scope_filters_by_owner?(parent, Janela::Frame)
+        return unless Janela::Frame.table_exists? && owner_filtering(Janela::Frame) == :filtered
 
         Finding.new(severity: :error,
           summary: "#{parent} scopes frames by owner but defines no janela_frame_owner",
@@ -236,9 +296,9 @@ module Janela
       # times in this repository's tests and once on the live demo within an
       # afternoon of the column landing (#49).
       def snapshots_nobody_will_see
-        parent = Janela.parent_controller.safe_constantize
+        parent = parent_controller
         return unless parent && Janela::Snapshot.table_exists?
-        return unless scope_filters_by_owner?(parent, Janela::Snapshot)
+        return unless owner_filtering(Janela::Snapshot) == :filtered
 
         unowned = Janela::Snapshot.where(owner_id: nil).count
         return if unowned.zero?
@@ -256,17 +316,46 @@ module Janela
       # Asking the policy rather than reading its source: a scope that narrows
       # an owned record is one that will hide an unowned one. Shared, because
       # a frame and a snapshot are the same question asked of two tables.
-      def scope_filters_by_owner?(parent, model)
-        parent.allocate.send(:policy_scope, model).to_sql.include?("owner")
+      #
+      # Three-valued on purpose. Collapsing a raise into false is how both
+      # owner checks came to be silent for every host whose policy reaches for
+      # the signed in user: a raise is a different fact from a scope that does
+      # not filter, and unscoped_reads is the check that reports it (ADR 035).
+      def owner_filtering(model)
+        outcome, answer = ask_for_scope(model)
+        return :raised if outcome == :raised
+
+        answer.to_sql.include?("owner") ? :filtered : :unfiltered
       rescue StandardError
-        false
+        :raised
+      end
+
+      # What Janela's controllers actually inherit. Janela.parent_controller is
+      # what a host asked for, and the two differ when it was named too late,
+      # which is how a check came to print "Janela's controllers inherit X"
+      # about a class that was not in the chain (ADR 035, #38).
+      def parent_controller
+        Janela::ApplicationController.superclass
+      end
+
+      # Asks the host's policy the way a request does. On a controller with no
+      # request, session, params and current_user are all unreachable, so a
+      # policy that touches any of them raises for a reason that is not the
+      # host's fault. Given a request they are empty instead, which is an
+      # unauthenticated visitor: the right thing for a check to ask about.
+      def ask_for_scope(model)
+        controller = parent_controller.allocate
+        controller.set_request!(ActionDispatch::TestRequest.create) if controller.respond_to?(:set_request!)
+        [ :ok, controller.send(:policy_scope, model) ]
+      rescue StandardError => e
+        [ :raised, e ]
       end
 
       # Whether an endpoint is public depends on what the host's controller
       # does, which cannot be determined by reading, so this observes and says
       # so rather than declaring anything safe.
       def unauthenticated_endpoints
-        parent = Janela.parent_controller.safe_constantize
+        parent = parent_controller
         return unless parent
 
         filters = parent._process_action_callbacks.map(&:filter).map(&:to_s)
@@ -281,7 +370,7 @@ module Janela
 
       def janela_models
         Rails.application.eager_load!
-        ActiveRecord::Base.descendants.select { |model| model.respond_to?(:janela) && model.janela }
+        ActiveRecord::Base.descendants.select { |model| Janela.our_definition(model) }
       rescue StandardError
         []
       end

data/lib/janela/model.rb

@@ -29,9 +29,14 @@ module Janela
     # does not exist yet, so it registers as it is created (ADR 031). An
     # anonymous class has no route key to be addressed by; naming it is the
     # host's move and declaring on it is the host's other one.
+    #
+    # A Definition rather than anything truthy: this is extended onto every
+    # model in the application, so `janela` may be a method the host wrote for
+    # its own reasons, and the host's own wins. Janela believes only what
+    # Janela built (#54).
     def inherited(subclass)
       super
-      Janela.register_subclass(subclass) if subclass.name && janela
+      Janela.register_subclass(subclass) if subclass.name && janela.is_a?(Definition)
     end
 
     private

data/lib/janela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janela
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/janela.rb

@@ -27,7 +27,41 @@ module Janela
 
   # Janela's controllers inherit from the host's, so the host's authentication
   # and authorisation apply to dashboards with no configuration.
-  mattr_accessor :parent_controller, default: "ApplicationController"
+  #
+  # Resolved once, when Janela::ApplicationController is first loaded. A host
+  # naming one after that point used to be ignored in silence: dashboards kept
+  # inheriting whatever was named first, so the host's authentication and its
+  # policy_scope were not the ones it had written, and nothing said so. Naming
+  # a different one too late raises instead (ADR 035, #38).
+  @parent_controller = "ApplicationController"
+
+  class << self
+    attr_reader :parent_controller
+
+    def parent_controller=(name)
+      inherited = inherited_controller
+      if inherited && inherited != name.to_s
+        raise Error, "Janela::ApplicationController already inherits #{inherited}, so naming " \
+                     "#{name} now would do nothing: the superclass is resolved once, the first " \
+                     "time the class is loaded. Set it earlier, in config/initializers/janela.rb, " \
+                     "which runs before anything can load a Janela controller. config.to_prepare " \
+                     "and config.after_initialize are both too late, and so is anything that runs " \
+                     "once the application is serving."
+      end
+
+      @parent_controller = name
+    end
+
+    # What Janela::ApplicationController resolved to, or nil if it has not been
+    # loaded yet. Asked without forcing the autoload the question is about:
+    # const_defined? is true for a registered autoload, and autoload? stops
+    # being truthy only once the file has actually been loaded.
+    def inherited_controller
+      return nil if autoload?(:ApplicationController) || !const_defined?(:ApplicationController, false)
+
+      const_get(:ApplicationController, false).superclass.name
+    end
+  end
 
   # The stylesheet Janela's own pages load on top of janela.css. Nil means the
   # structural one only, which is what a host that has its own look wants. The
@@ -95,7 +129,7 @@ module Janela
   # here until a restart, and a form offering it would fail to draw at all.
   def self.definitions
     Rails.application.eager_load!
-    registry.sort.filter_map { |_route_key, class_name| class_name.safe_constantize&.janela }
+    registry.sort.filter_map { |_route_key, class_name| our_definition(class_name.safe_constantize) }
   end
 
   def self.definition!(route_key)
@@ -104,7 +138,17 @@ module Janela
     Rails.application.eager_load! unless registry.key?(route_key)
     class_name = registry.fetch(route_key) { raise NotFound, "#{route_key.inspect} is not a janela model" }
 
-    class_name.constantize.janela
+    our_definition(class_name.constantize) ||
+      raise(NotFound, "#{route_key.inspect} is not a janela model")
+  end
+
+  # Janela::Model is extended onto every model in the application, so `janela`
+  # is a question any of them can answer, and a host that answers it for its
+  # own reasons wins: its method is on its own singleton. Janela believes only
+  # what Janela built, rather than anything truthy that comes back (#54).
+  def self.our_definition(model)
+    definition = model.janela if model.respond_to?(:janela)
+    definition if definition.is_a?(Definition)
   end
 
   # What Janela can draw, so a gallery asks rather than reaching into

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -171,9 +171,14 @@ files:
 - docs/decisions/032-janela-will-not-read-a-model-it-cannot-scope.md
 - docs/decisions/033-a-snapshot-is-told-who-owns-it.md
 - docs/decisions/034-janela-will-not-freeze-a-scope-the-host-has-not-named.md
+- docs/decisions/035-a-check-does-what-janela-does-or-says-what-it-saw.md
+- docs/decisions/036-janela-publishes-what-a-theme-may-target.md
+- docs/decisions/037-what-1-0-means.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
+- docs/roadmap.md
+- docs/theming.md
 - lib/janela.rb
 - lib/janela/definition.rb
 - lib/janela/dimension.rb
@@ -194,22 +199,24 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.7.0 stops guessing what may be read. Two things now refuse
-  rather than defaulting to every row, and both are quick to answer.
+  Janela 0.8.0 raises where it used to do nothing. One thing to act on,
+  and one to read.
 
-  1. If your ApplicationController defines no policy_scope, every pane
-     raises Janela::Unscoped instead of totalling every row. Pundit
-     hosts and anyone following docs/multi-tenancy.md: nothing to do.
-     Everyone else writes one line (ADR 032).
+  1. If you set Janela.parent_controller anywhere but an initializer, it
+     now raises instead of being ignored in silence. config.to_prepare
+     and config.after_initialize are both too late, and the README's own
+     layout recipe is a to_prepare block. Until now your dashboards kept
+     inheriting whatever was named first, so your authentication and
+     policy_scope were not the ones you wrote (ADR 035).
 
-  2. If you schedule Janela::SnapshotJob, it now needs to be told what
-     rows to freeze: pass scope: :model_default, or subclass it and
-     override scope_for. A job already on your queue was serialised
-     without that argument and will raise when it performs, so drain it
-     or re-enqueue (ADR 034).
+  2. bin/rails janela:doctor reports findings it could not reach before,
+     including a Pundit host with no policy for Janela::Frame or
+     Janela::Snapshot, which used to pass the doctor and raise on every
+     request. Expect things that were always true and never printed.
 
-  If you use snapshots, there is also a migration: janela_snapshots
-  gains a nullable owner (ADR 033).
+  Also: the class names on Janela's own pages are no longer public API.
+  They are scoped under janela-page and may change in any release. What
+  your own markup contains is unchanged and is listed in docs/theming.md.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md