janela 0.6.0 → 0.8.0

data/lib/janela/doctor.rb

@@ -10,8 +10,9 @@ module Janela
     # Run in this order, and each one names the finding it produces: a host
     # silences a check by that name (ADR 021).
     CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unregistered_controllers
-                through_dimensions_without_an_allowlist frames_nobody_will_own
-                unauthenticated_endpoints hardcoded_disallowed_predicates].freeze
+                through_dimensions_without_an_allowlist unscoped_reads frames_nobody_will_own
+                snapshots_nobody_will_see unauthenticated_endpoints
+                hardcoded_disallowed_predicates].freeze
 
     # Identifiers a previous version of Janela used, and what replaced them.
     RENAMED = {
@@ -133,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
@@ -157,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|
@@ -173,23 +207,72 @@ 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
 
+      # A host that has defined no policy_scope has not said what may be read,
+      # and since ADR 032 every dashboard raises rather than answering with
+      # every row. Reported so it is found here rather than by a visitor.
+      #
+      # 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 = parent_controller
+        return unless parent
+        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" \
+                  "  Define it on #{parent}:\n" \
+                  "    private def policy_scope(model) = model.all\n" \
+                  "  That line says every visitor may read every row of every model on a\n" \
+                  "  dashboard. If that is not true of this application, return something\n" \
+                  "  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_frames_by_owner?(parent)
+        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",
@@ -202,20 +285,77 @@ module Janela
         nil # no database or no policy to ask; nothing can be concluded
       end
 
+      # A snapshot with no owner is stored and unreachable to a policy that
+      # filters on one: the row is there, a link to it is a 404, and nothing
+      # says why. Most often these were taken before the column existed, which
+      # is what an upgrade produces.
+      #
+      # ADR 033 judged this a thinner case than the frame's, because a caller
+      # assigns a snapshot's owner in its own Ruby rather than the engine doing
+      # it silently, and said it was worth revisiting if it bit. It bit four
+      # 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 = parent_controller
+        return unless parent && Janela::Snapshot.table_exists?
+        return unless owner_filtering(Janela::Snapshot) == :filtered
+
+        unowned = Janela::Snapshot.where(owner_id: nil).count
+        return if unowned.zero?
+
+        Finding.new(severity: :warning,
+          summary: "#{unowned} #{'snapshot'.pluralize(unowned)} with no owner, which your policy filters on",
+          detail: "  Your policy narrows snapshots by owner, so one with none is stored and\n" \
+                  "  unreachable: a link to it answers 404 and nothing says why. Usually these\n" \
+                  "  were taken before the owner column existed. Assign an owner to them, or\n" \
+                  "  delete them, and pass owner: to Janela::Snapshot.take from now on.")
+      rescue StandardError
+        nil # no database or no policy to ask; nothing can be concluded
+      end
+
       # Asking the policy rather than reading its source: a scope that narrows
-      # frames is one that will hide an unowned one.
-      def scope_filters_frames_by_owner?(parent)
-        scope = parent.allocate.send(:policy_scope, Janela::Frame)
-        scope.to_sql.include?("owner")
+      # 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.
+      #
+      # 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)
@@ -230,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.6.0"
+  VERSION = "0.8.0"
 end

data/lib/janela.rb

@@ -20,10 +20,48 @@ module Janela
   # Something the request asked for is not allowed here: a renderer, a
   # granularity, a limit or a filter. Rendered as 400.
   class BadRequest < Error; end
+  # The host has not said what may be read. Not rendered as anything: it is a
+  # setup mistake rather than a data condition, and dressing it as a 404 would
+  # hide the one line that fixes it (ADR 032).
+  class Unscoped < Error; end
 
   # 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
@@ -37,6 +75,29 @@ module Janela
   # is for (ADR 021).
   mattr_accessor :silenced_checks, default: []
 
+  # What the host permits to be read, asked of its controller and never
+  # assumed. Janela refuses rather than reading everything, because a
+  # dashboard that quietly totals rows its reader may not see is the worst
+  # thing this library can do (ADR 032).
+  #
+  # Asked of the controller and never of self, because a helper runs on the
+  # view and a view cannot see a private controller method: when there were
+  # two copies of this question they disagreed about whether a host had
+  # answered it (#46). One copy, for that reason.
+  def self.scope(controller, model)
+    unless controller.respond_to?(:policy_scope, true)
+      raise Unscoped, "#{controller.class} defines no policy_scope, so Janela has not been " \
+                      "told what may be read of #{model.name}. Define it on " \
+                      "#{Janela.parent_controller}, returning the rows this visitor may see:\n\n" \
+                      "  private def policy_scope(model) = model.all\n\n" \
+                      "That line says every visitor may read every row of every model on a " \
+                      "dashboard. If that is not true here, return something narrower. " \
+                      "UPGRADING.md has the steps and docs/multi-tenancy.md has the wiring."
+    end
+
+    controller.send(:policy_scope, model)
+  end
+
   # A model that declares a janela block is addressable over HTTP, and so is a
   # subclass of one, keyed by the route key that appears in pane URLs (orders,
   # sales_orders). Names are stored rather than classes so a reloaded model
@@ -68,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)
@@ -77,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.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -136,6 +136,7 @@ files:
 - db/migrate/20260915000001_create_janela_snapshots.rb
 - db/migrate/20260916000001_create_janela_frames.rb
 - db/migrate/20260916000002_create_janela_panes.rb
+- db/migrate/20260921000001_add_owner_to_janela_snapshots.rb
 - docs/decisions/001-built-to-be-forked.md
 - docs/decisions/002-measures-and-dimensions-over-ransack.md
 - docs/decisions/003-cross-filtering-with-turbo-frames.md
@@ -167,9 +168,17 @@ files:
 - docs/decisions/029-a-panes-frame-is-identified-by-who-it-is.md
 - docs/decisions/030-a-panes-src-belongs-to-turbo.md
 - docs/decisions/031-a-subclass-inherits-the-dashboard.md
+- 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
@@ -190,14 +199,24 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.6.0 changes how single table inheritance is handled (ADR 031).
-  You need to act only if your application has STI subclasses under a model
-  that declares a janela block. Every named subclass of one is now
-  registered and addressable on its own route key, and Janela.definitions
-  returns one entry per subclass where a form offering a choice of model
-  previously showed one.
+  Janela 0.8.0 raises where it used to do nothing. One thing to act on,
+  and one to read.
 
-  Everyone else: nothing to do.
+  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. 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.
+
+  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