janela 0.2.0 → 0.3.0

data/docs/multi-tenancy.md

@@ -0,0 +1,175 @@
+# Fitting Janela into a multi tenant application
+
+Janela holds no tenancy of its own. There is no tenant setting, no
+default scope of ours on your models, and nothing to configure. The
+engine asks your application two questions and does what it is told.
+
+| Question | How your application answers | If it says nothing |
+| --- | --- | --- |
+| What may this request read? | `policy_scope(model)` on the controller Janela inherits | Everything: `model.all` |
+| What owns a frame being created? | `janela_frame_owner` on the same controller | Nothing: a nil owner |
+
+Both are ordinary methods on your `ApplicationController`, found by
+duck typing. Pundit defines the first for you. Anything else, you
+define in about five lines. ADR 019 has the reasoning for asking
+rather than being configured: ownership is per-request state, and a
+setting cannot hold it.
+
+## What goes through your scope
+
+Everything. There is no path through the engine that reads a record
+without asking first:
+
+- The index of frames, and each frame page.
+- Every editing action on a frame or a pane, so another tenant's frame
+  is a 404 to rename or delete as much as to read.
+- Every pane's own query, on Janela's pages and inline in yours. The
+  measure is calculated over `policy_scope(Order)`, not over `Order`.
+- An ad hoc pane URL, which is the same query by another route.
+- A snapshot, read through `policy_scope(Janela::Snapshot)`.
+
+A pane rendered inline in your own page runs in your request, so the
+same scope applies there as in the engine's controllers. Nothing is
+calculated in a background context where the current tenant would have
+gone missing.
+
+## With Pundit
+
+Write a policy for Janela's own record. The class name is namespaced,
+because the model is:
+
+```ruby
+# app/policies/janela/frame_policy.rb
+module Janela
+  class FramePolicy < ApplicationPolicy
+    class Scope < ApplicationPolicy::Scope
+      def resolve
+        scope.where(owner: Current.account)
+      end
+    end
+  end
+end
+```
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Pundit::Authorization
+
+  private
+    def janela_frame_owner
+      Current.account
+    end
+end
+```
+
+Your own models keep the policies they already have. Janela calls
+`policy_scope(Order)` and gets whatever `OrderPolicy::Scope` returns.
+
+## With acts_as_tenant
+
+Your own models are already scoped, so the only thing Janela needs
+told about is its own tables. Define `policy_scope` as the adapter:
+
+```ruby
+class ApplicationController < ActionController::Base
+  set_current_tenant_through_filter
+  before_action :set_tenant
+
+  private
+    def policy_scope(model)
+      case model.name
+      when "Janela::Frame" then model.where(owner: ActsAsTenant.current_tenant)
+      else model.all # acts_as_tenant has already scoped your own models
+      end
+    end
+
+    def janela_frame_owner
+      ActsAsTenant.current_tenant
+    end
+end
+```
+
+## With CanCanCan, or with your own
+
+The same adapter, pointed at whatever you use:
+
+```ruby
+def policy_scope(model)
+  model.accessible_by(current_ability)
+end
+```
+
+Janela never asks how the answer was arrived at. A method that takes a
+class and returns a relation is the whole contract.
+
+## With one tenant
+
+Define nothing. `policy_scope` is absent, every query runs over
+`model.all`, and a frame is created with a nil owner because nothing
+is filtering on one.
+
+## What owns a frame
+
+`Janela::Frame belongs_to :owner, polymorphic: true, optional: true`.
+It can point at an account, a team, a user or anything else you scope
+by, and Janela reads nothing from it. It exists so your scope has a
+column.
+
+Return the tenant from `janela_frame_owner` and the engine assigns it
+to a frame it creates. Skip that method while your scope filters by
+owner and the analyst's new dashboard is saved with no owner, then
+hidden by your own policy the instant it is saved. It looks like the
+save failed silently. `bin/rails janela:doctor` reports this for you:
+it asks your policy for a scope over frames and looks for an owner in
+what comes back.
+
+## Snapshots are the rough edge
+
+`janela_snapshots` has no owner column. A snapshot is a name, an
+instant, the filters it was taken under and the results. So a multi
+tenant application has to scope it by something else:
+
+- Keep snapshots to one tenant, or to whoever publishes.
+- Add your own column with a migration on `janela_snapshots` and scope
+  on that.
+- Encode the tenant in the filters a snapshot is taken under, and
+  scope on the stored name.
+
+None of those is as clean as a frame's owner. Giving a snapshot the
+same polymorphic owner is [issue #32](https://github.com/retail-tasker/janela/issues/32).
+
+## Proving your wiring
+
+Run the doctor first. It reads your application and reports the traps
+that are visible from outside a request:
+
+```bash
+bin/rails janela:doctor
+```
+
+Then write the test that matters, which is the one that fails if a
+scope is ever loosened. Create a frame as one tenant and ask for it as
+another:
+
+```ruby
+test "another tenant's frame is a 404" do
+  frame = Janela::Frame.create!(name: "Theirs", owner: accounts(:acme))
+
+  sign_in users(:globex_analyst)
+  get janela.frame_path(frame)
+
+  assert_response :not_found
+end
+```
+
+This repository's dummy application is a worked example of all of the
+above, in
+[test/dummy/app/controllers/application_controller.rb](https://github.com/retail-tasker/janela/blob/main/test/dummy/app/controllers/application_controller.rb),
+scoped by a `?tenant=` parameter standing in for a session.
+
+## What Janela will never do
+
+Add a tenant filter of its own. Your scope is the only one, so there
+is nothing to double filter and nothing that looks enforced while
+being unenforceable. Janela can be handed any relation through `on:`,
+so a guarantee made here would be a guarantee it cannot keep.

data/lib/janela/definition.rb

@@ -9,7 +9,7 @@ module Janela
     end
 
     def measure(name, **aggregate)
-      measures[name] = Measure.build(name, **aggregate)
+      measures[name] = Measure.build(name, model: model, **aggregate).tap { |measure| reject_boolean_column!(measure) }
     end
 
     def dimension(name, through: nil, column: nil, granularity: nil)
@@ -36,17 +36,35 @@ module Janela
       else
         grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.sql_alias} DESC"))
         grouped = grouped.limit(limit!(limit)) if limit
-        measure.apply(grouped)
+        measure.apply(grouped).transform_keys { |value| value.nil? ? Dimension::NONE : value }
       end
     end
 
     def dimension!(name)
-      dimensions.fetch(name) { raise Error, "#{model} has no janela dimension #{name.inspect}" }
+      dimensions.fetch(name) { raise NotFound, "#{model} has no janela dimension #{name.inspect}" }
+    end
+
+    def measure!(name)
+      measures.fetch(name) { raise NotFound, "#{model} has no janela measure #{name.inspect}" }
+    end
+
+    # ActiveRecord casts an aggregate back through the column's own type, so
+    # AVG over a boolean returns true rather than a ratio. Say so at
+    # declaration rather than rendering a meaningless pane.
+    def reject_boolean_column!(measure)
+      return unless measure.column && Measure::NUMERIC.include?(measure.aggregate)
+      return unless model.type_for_attribute(measure.column).type == :boolean
+
+      raise Error, "measure #{measure.name.inspect} takes #{measure.aggregate} of the boolean " \
+                   "#{model}##{measure.column}, which ActiveRecord casts back to true or false. " \
+                   "Declare dimension #{measure.column.inspect} instead and read the split."
+    rescue ActiveRecord::ActiveRecordError
+      nil # no database to ask yet; a query will raise on its own if it cannot run
     end
 
     def limit!(value)
       limit = Integer(value, exception: false)
-      raise Error, "limit must be a whole number from 1 to 1000, got #{value.inspect}" unless limit&.between?(1, 1000)
+      raise BadRequest, "limit must be a whole number from 1 to 1000, got #{value.inspect}" unless limit&.between?(1, 1000)
       limit
     end
 
@@ -74,12 +92,8 @@ module Janela
         dropped = params.keys.reject { |key| applied.any? { |name| key.to_s.start_with?(name) } }
         return if dropped.empty?
 
-        raise Error, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
+        raise BadRequest, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
                      "Declare a janela dimension, or add it to ransackable_attributes."
       end
-
-      def measure!(name)
-        measures.fetch(name) { raise Error, "#{model} has no janela measure #{name.inspect}" }
-      end
   end
 end

data/lib/janela/dimension.rb

@@ -2,6 +2,10 @@ module Janela
   class Dimension
     GRANULARITIES = %w[hour day week month quarter year].freeze
 
+    # A group of rows whose dimension is null. Labelled rather than blank, and
+    # filtered with Ransack's null predicate rather than an empty string.
+    NONE = "(none)".freeze
+
     LABELS = {
       "hour" => ->(t) { t.strftime("%Y-%m-%d %H:00") },
       "day" => ->(t) { t.strftime("%Y-%m-%d") },
@@ -29,7 +33,7 @@ module Janela
 
     def self.granularity!(value)
       value = value.to_s
-      raise Error, "unknown granularity #{value.inspect}, use one of #{GRANULARITIES.join(', ')}" unless GRANULARITIES.include?(value)
+      raise BadRequest, "unknown granularity #{value.inspect}, use one of #{GRANULARITIES.join(', ')}" unless GRANULARITIES.include?(value)
       value
     end
 

data/lib/janela/doctor.rb

@@ -0,0 +1,219 @@
+module Janela
+  # Reads a host application and reports what it still has to do. Only ever
+  # reads and reports: the checks are the install and upgrade traps that
+  # experience says actually break a host (ADR 015).
+  class Doctor
+    # code is the check that produced the finding, set by the runner rather
+    # than by each check, so the two can never drift apart.
+    Finding = Struct.new(:severity, :summary, :detail, :code, keyword_init: true)
+
+    # 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].freeze
+
+    # Identifiers a previous version of Janela used, and what replaced them.
+    RENAMED = {
+      "janela--dashboard" => "janela--frame",
+      "janela_dashboard" => "janela_frame",
+      "janela/dashboard_controller" => "janela/frame_controller",
+      "janela/dashboard_controller.js" => "janela/frame_controller.js",
+      "Janela::DashboardHelper" => "Janela::FramesHelper",
+      "Janela::PanesController" => "Janela::QueriesController",
+      "Janela::SnapshotPanesController" => "Janela::SnapshotQueriesController"
+    }.freeze
+
+    SEARCHED = %w[app config lib].freeze
+    READABLE = %w[.rb .erb .js .erb.html .html.erb .haml .slim .yml].freeze
+
+    def initialize(root)
+      @root = Pathname.new(root)
+    end
+
+    def report(out)
+      findings, silenced = all_findings.partition { |finding| !silenced?(finding) }
+
+      if findings.empty?
+        out.puts "Janela: nothing to fix."
+      else
+        out.puts "Janela found #{findings.size} #{'thing'.pluralize(findings.size)} to look at."
+        findings.each do |finding|
+          out.puts
+          out.puts "#{finding.severity.to_s.upcase} (#{finding.code}): #{finding.summary}"
+          out.puts finding.detail
+        end
+        out.puts
+        out.puts "Silence one you have judged a false alarm, in config/initializers/janela.rb:"
+        out.puts "  Janela.silenced_checks = %w[#{findings.first.code}]"
+        out.puts
+        out.puts "Steps for a version upgrade are in UPGRADING.md."
+      end
+
+      # Said out loud every run, because a silence nobody remembers is how a
+      # real finding goes unread.
+      out.puts "Silenced: #{silenced.map(&:code).uniq.join(', ')}." if silenced.any?
+      findings.none? { |finding| finding.severity == :error }
+    end
+
+    def check
+      all_findings.reject { |finding| silenced?(finding) }
+    end
+
+    private
+      def all_findings
+        @all_findings ||= CHECKS.flat_map { |name| findings_from(name) }
+      end
+
+      # Struct responds to to_a, so a single finding is wrapped by hand rather
+      # than with Array(), which would take it apart into its members.
+      def findings_from(name)
+        found = send(name)
+        found = [ found ] unless found.is_a?(Array)
+        found.compact.each { |finding| finding.code = name.to_s.dasherize }
+      end
+
+      def silenced?(finding)
+        Janela.silenced_checks.map(&:to_s).include?(finding.code)
+      end
+
+      def stale_identifiers
+        RENAMED.filter_map do |old, new|
+          files = source_files.select { |file| file.read.include?(old) }
+          next if files.empty?
+
+          Finding.new(severity: :error,
+            summary: "#{old} is now #{new}",
+            detail: files.map { |file| "  #{file.relative_path_from(@root)}" }.join("\n"))
+        end
+      end
+
+      def unmounted_engine
+        return if engine_mounted?
+
+        Finding.new(severity: :error,
+          summary: "Janela::Engine is not mounted",
+          detail: "  Add to config/routes.rb, at whatever path suits you:\n" \
+                  "    mount Janela::Engine => \"/insights\"")
+      end
+
+      # The mount root serves an index of frames, so a host that upgrades
+      # without running the migrations finds an exception where its dashboards
+      # were. Only a host that mounts the engine needs the tables at all.
+      def unmigrated_tables
+        return unless engine_mounted?
+
+        missing = [ Janela::Frame, Janela::Pane, Janela::Snapshot ].reject(&:table_exists?).map(&:table_name)
+        return if missing.empty?
+
+        Finding.new(severity: :error,
+          summary: "#{missing.to_sentence} #{missing.one? ? 'is' : 'are'} missing",
+          detail: "  Janela's own pages read these the moment the engine is mounted. Run:\n" \
+                  "    bin/rails janela:install:migrations\n" \
+                  "    bin/rails db:migrate")
+      rescue StandardError
+        nil # no database to ask yet
+      end
+
+      def engine_mounted?
+        Rails.application.routes.routes.any? { |route| route.app.respond_to?(:app) && route.app.app == Janela::Engine }
+      end
+
+      def unregistered_controllers
+        registered = source_files.any? { |file| file.read.include?("janela--frame") }
+        return if registered
+
+        Finding.new(severity: :error,
+          summary: "Janela's Stimulus controllers are not registered anywhere",
+          detail: "  Without them a dashboard renders but nothing cross-filters, which\n" \
+                  "  looks like nothing happening at all. Register both:\n" \
+                  "    application.register(\"janela--frame\", JanelaFrameController)\n" \
+                  "    application.register(\"janela--chart\", JanelaChartController)")
+      end
+
+      # Ransack's allowlist is per class, so a dimension read through an
+      # association needs the associated model to allow the attribute too.
+      def through_dimensions_without_an_allowlist
+        janela_models.flat_map do |model|
+          model.janela.dimensions.values.select(&:through).filter_map do |dimension|
+            association = model.reflect_on_association(dimension.through)
+            next unless association
+
+            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(' ')}]")
+          end
+        end
+      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)
+        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)
+
+        Finding.new(severity: :error,
+          summary: "#{parent} scopes frames by owner but defines no janela_frame_owner",
+          detail: "  A frame created through Janela's own form would have no owner, and your\n" \
+                  "  own scope would then hide it. Define this on #{parent}:\n" \
+                  "    def janela_frame_owner\n" \
+                  "      Current.account # whatever your policy scope filters frames by\n" \
+                  "    end")
+      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")
+      rescue StandardError
+        false
+      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
+        return unless parent
+
+        filters = parent._process_action_callbacks.map(&:filter).map(&:to_s)
+        return if filters.any? { |filter| filter.match?(/authenticat|require_user|require_login|login_required/) }
+
+        Finding.new(severity: :warning,
+          summary: "no authentication filter found on #{parent}",
+          detail: "  Janela's controllers inherit #{parent}, so they are as public as it is,\n" \
+                  "  and this check only reads its filters: if you authenticate another way\n" \
+                  "  this is a false alarm. Otherwise see Securing dashboards in the README.")
+      end
+
+      def janela_models
+        Rails.application.eager_load!
+        ActiveRecord::Base.descendants.select { |model| model.respond_to?(:janela) && model.janela }
+      rescue StandardError
+        []
+      end
+
+      def source_files
+        @source_files ||= SEARCHED.flat_map do |directory|
+          path = @root.join(directory)
+          next [] unless path.directory?
+
+          path.glob("**/*").select { |file| file.file? && READABLE.any? { |extension| file.to_s.end_with?(extension) } }
+        end
+      end
+  end
+end

data/lib/janela/engine.rb

@@ -8,10 +8,23 @@ module Janela
       ActiveSupport.on_load(:active_record) { extend Janela::Model }
     end
 
-    # isolate_namespace keeps engine helpers out of the host, but the dashboard
+    # isolate_namespace keeps engine helpers out of the host, but the frame
     # helpers are the engine's public API and belong in the host's views.
     initializer "janela.helpers" do
-      ActiveSupport.on_load(:action_view) { include Janela::DashboardHelper }
+      ActiveSupport.on_load(:action_view) { include Janela::FramesHelper }
+    end
+
+    # janela_frame renders the engine's own partials from a host's page, and
+    # an engine's views are otherwise only on the lookup path of its own
+    # controllers.
+    initializer "janela.views" do
+      ActiveSupport.on_load(:action_controller) { append_view_path Janela::Engine.root.join("app/views") }
+    end
+
+    # Janela's own layout links janela.css, and a host on Sprockets serves it
+    # in production only if something declared it.
+    initializer "janela.assets" do |app|
+      app.config.assets.precompile << "janela.css" if app.config.respond_to?(:assets) && app.config.assets.respond_to?(:precompile)
     end
 
     initializer "janela.importmap", before: "importmap" do |app|

data/lib/janela/measure.rb

@@ -1,22 +1,37 @@
 module Janela
   class Measure
     AGGREGATES = %i[sum count average minimum maximum].freeze
+    # Aggregates whose answer is a number, so a boolean column would have its
+    # result cast back to true or false by ActiveRecord.
+    NUMERIC = %i[sum average].freeze
+    # Declared beside the aggregate, so they are taken out before the one
+    # remaining option is read as the aggregate.
+    FORMATS = %i[precision prefix suffix].freeze
+    # Where neither the aggregate nor the column says how many decimal places
+    # the measure means, two: enough for a rate or a currency, and short of
+    # the noise a float carries (issue #25).
+    FALLBACK_PRECISION = 2
 
-    attr_reader :name, :aggregate, :column
+    attr_reader :name, :aggregate, :column, :prefix, :suffix
 
-    def self.build(name, **options)
+    def self.build(name, model: nil, **options)
+      format = options.extract!(*FORMATS)
       aggregate, column = options.first
       unless options.size == 1 && AGGREGATES.include?(aggregate)
         raise Error, "measure #{name.inspect} needs exactly one of #{AGGREGATES.join(', ')}"
       end
 
-      new(name, aggregate, column == true ? nil : column)
+      new(name, aggregate, column == true ? nil : column, model: model, **format)
     end
 
-    def initialize(name, aggregate, column)
+    def initialize(name, aggregate, column, model: nil, precision: nil, prefix: nil, suffix: nil)
       @name = name
       @aggregate = aggregate
       @column = column
+      @model = model
+      @precision = precision!(precision)
+      @prefix = prefix
+      @suffix = suffix
     end
 
     def apply(relation)
@@ -28,5 +43,54 @@ module Janela
     def sql_alias
       "#{aggregate}_#{column || 'all'}"
     end
+
+    # How many decimal places this measure means. Counting rows has none, and
+    # a decimal column already declares its own scale, so money and counts
+    # read correctly with nothing declared at all (ADR 020).
+    def precision
+      @precision || column_scale || FALLBACK_PRECISION
+    end
+
+    # Rendering, never rounding: the number itself reaches a snapshot and a
+    # comparison at full precision, so a stored pane reads back under whatever
+    # format is declared later (ADR 009). Anything that is not a number is
+    # left alone, since minimum of a string is still that string.
+    def format(value)
+      return "" if value.nil?
+      return value.to_s unless value.is_a?(Numeric)
+
+      "#{prefix}#{rounded(value)}#{suffix}"
+    end
+
+    private
+      def rounded(value)
+        ActiveSupport::NumberHelper.number_to_rounded(value, precision: precision,
+          delimiter: I18n.t("number.format.delimiter", default: ","))
+      end
+
+      # Asking the schema rather than the value: one bucket of a measure can
+      # land on a whole number without the measure being a whole number.
+      def column_scale
+        return 0 if aggregate == :count || column.nil?
+
+        type = @model&.type_for_attribute(column)
+        return if type.nil?
+        return 0 if type.type == :integer && aggregate != :average
+
+        type.scale if type.respond_to?(:scale)
+      rescue ActiveRecord::ActiveRecordError
+        nil # no database to ask yet
+      end
+
+      def precision!(value)
+        return if value.nil?
+
+        places = Integer(value, exception: false)
+        unless places&.between?(0, 10)
+          raise Error, "measure #{name.inspect} takes a precision of 0 to 10 decimal places, not #{value.inspect}"
+        end
+
+        places
+      end
   end
 end

data/lib/janela/version.rb

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

data/lib/janela.rb

@@ -9,14 +9,27 @@ require "janela/model"
 require "janela/definition"
 require "janela/measure"
 require "janela/dimension"
+require "janela/doctor"
 
 module Janela
   class Error < StandardError; end
+  # Something the request named does not exist: a model, measure, dimension
+  # or a pane a snapshot did not freeze. Rendered as 404.
+  class NotFound < Error; end
+  # 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
 
   # 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"
 
+  # Checks janela:doctor should not report, by the name it prints beside each
+  # finding. A check that is a false alarm for one application stays a false
+  # alarm, and that is a judgement made once at boot, which is what a setting
+  # is for (ADR 021).
+  mattr_accessor :silenced_checks, default: []
+
   # Only models that declare a janela block are addressable over HTTP, keyed by
   # the route key that appears in pane URLs (orders, sales_orders). Names are
   # stored rather than classes so a reloaded model leaves nothing stale behind.
@@ -28,11 +41,21 @@ module Janela
     registry[model.model_name.route_key] = model.name
   end
 
+  # Every model that declares a janela block, for a form that offers a choice
+  # of them. Eager loading first, because a model nobody has referenced yet has
+  # not registered. A name that no longer resolves is left out rather than
+  # raised on: a model renamed or deleted in development leaves its old key
+  # 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 }
+  end
+
   def self.definition!(route_key)
     # In development a model is only registered once autoloaded, so a cold
     # lookup loads the app rather than constantizing an unvetted parameter.
     Rails.application.eager_load! unless registry.key?(route_key)
-    class_name = registry.fetch(route_key) { raise Error, "#{route_key.inspect} is not a janela model" }
+    class_name = registry.fetch(route_key) { raise NotFound, "#{route_key.inspect} is not a janela model" }
 
     class_name.constantize.janela
   end

data/lib/tasks/janela.rake

@@ -0,0 +1,6 @@
+namespace :janela do
+  desc "Report what this application still needs to do to use Janela correctly"
+  task doctor: :environment do
+    Janela::Doctor.new(Rails.root).report($stdout) or exit 1
+  end
+end