janela 0.2.1 → 0.4.0

data/docs/naming.md

@@ -0,0 +1,172 @@
+---
+Topics: naming, vocabulary, design, renaming
+---
+
+# Naming Things Is Hard
+
+There are two hard problems in computer science, and this page is about
+the one that is not cache invalidation. Every name in Janela was chosen
+on purpose, several were changed after they shipped, and one rule sits
+under all of them.
+
+## The rule
+
+> With words like Janela, Frame and Pane I am purposefully selecting
+> uncommon but understandable, conceivable words so that people aren't
+> pigeonholed and can select their own nomenclature.
+
+A library that calls its main idea a Dashboard has taken that word from
+every application that installs it. Your app probably already has a
+`Dashboard`, or a `Report`, or an `Insight`, and whatever you call yours
+is the word your users know. So Janela's own vocabulary is deliberately
+a step to the side: close enough to understand on first read, unusual
+enough that it never collides with the words you already use, and never
+the word your users have to see.
+
+That gives two tests for any name in this codebase:
+
+- **Conceivable.** Someone reading it for the first time can guess what
+  it is without looking it up.
+- **Uncommon.** It is unlikely to already be a model, a table, a route
+  or a word on your screens.
+
+## The window
+
+*Janela* is Portuguese for window. The word is the same in Portugal and
+in Brazil. Once the library is a window, the rest of its anatomy follows
+from the thing itself rather than from a list of synonyms for "chart".
+
+| Name | What it is | Why this word |
+| --- | --- | --- |
+| **Janela** | The library | A window onto your data. Uncommon in English, obvious once explained. |
+| **Frame** | A dashboard: a name and a grid of panes | A window frame holds the panes. It is also what Turbo calls the element that makes cross-filtering work (ADR 003), which is a happy accident rather than the reason. |
+| **Pane** | One visual inside a frame, stored as a row | A pane of glass sits in a frame. You look through each one at part of the picture. |
+| **Query** | The runtime object that calculates one pane | Not a window word, on purpose. It is an implementation detail rather than something a person arranges, so it gets the plain name for what it does. |
+| **Grid** | How a frame is divided: `columns`, `gap`, and each pane's `span` | A window is divided into panes, and the grid is the division. Small integers that choose a class the stylesheet already defines, so nothing an analyst types reaches CSS (ADR 016). |
+| **Vitral** | The optional stained glass theme | A stained glass window, in the same language. See ADR 023. |
+
+The anatomy was argued over before it was settled. *Sash* was
+considered for the dashboard and rejected: a sash is one layer inside a
+window, the moving part that holds glass, and the thing that holds
+panes is the frame.
+
+## Words that stay ordinary
+
+Not everything gets an unusual name, and the exceptions follow the same
+reasoning.
+
+**Measure and dimension** are the words the business intelligence field
+already agreed on. An analyst who has used any tool of that kind knows
+exactly what `measure :revenue` and `dimension :region` mean. They are
+also method names inside a model's `janela` block rather than classes
+sitting in your namespace, so there is nothing for them to collide with.
+A domain language should speak its reader's language (ADR 002).
+
+**Snapshot** and **owner** are plain because what they describe is
+plain: the numbers frozen at an instant, and whatever a frame belongs
+to. Janela assigns an owner and never reads it, so it has no reason to
+give it a clever name (ADR 009, ADR 019).
+
+**The doctor** is the conventional name for a command that reads your
+setup and tells you what is wrong. Homebrew, Flutter, npm and Bundler
+all ship one, so the word already means the right thing (ADR 021).
+
+## Your words, not ours
+
+None of Janela's vocabulary has to reach your users. Two places decide
+what they see.
+
+**The noun comes from your locale file.** Every heading the engine
+renders uses `Janela::Frame.model_name.human`, so your users read
+whatever you call them:
+
+```yaml
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: "Report"
+        other: "Reports"
+```
+
+**The address is wherever you mount it.** Frames live at the mount root
+and a pane's URL sits beneath the same path, so the words in the address
+bar are yours too:
+
+```ruby
+mount Janela::Engine => "/insights"
+```
+
+```
+/insights                   every frame
+/insights/3                 one frame
+/insights/orders/revenue    a pane
+```
+
+ADR 013 first gave frames a configurable path segment of their own. ADR
+014 took it back out, because a segment named `dashboards` or `reports`
+is exactly the kind of word a host model already owns, and it shadowed
+that model's panes. Keeping Janela's own words out of your URLs turned
+out to be the fix as well as the principle.
+
+## One word, one meaning
+
+A single name used for two things is worse than an awkward name, so
+some sentences in this codebase are spelled more carefully than they
+would be in conversation.
+
+**Frame** on its own always means the dashboard. The HTML element is
+always written **turbo frame**, in prose, in comments and in commit
+messages, so the two can never be confused.
+
+**Grid** always means a frame's layout, its columns and gap. The lines
+drawn between panes by the theme are leading, never grid.
+
+**Pane** always means the stored row. That is why the runtime object
+had to give the name up: it was `Janela::Pane` until ADR 014 renamed it
+`Janela::Query` so the record could take the word it deserved.
+
+## When a name turns out wrong
+
+Names were changed after release, and each change was treated as
+breaking rather than tidied away:
+
+- `janela_dashboard` became `janela_frame`, and the Stimulus controller
+  `janela--dashboard` became `janela--frame`.
+- `Janela::Pane` became `Janela::Query`, freeing `Pane` for the record.
+- `Janela::DashboardHelper` became `Janela::FramesHelper`.
+
+Every one of those is listed in `UPGRADING.md` with the exact
+replacement, and `bin/rails janela:doctor` finds any old name left in
+your code and names what replaced it (ADR 015). Renaming is allowed. A
+rename a user has to discover for themselves is not.
+
+## The look follows the name
+
+The demo and the vitral theme are not decoration picked separately.
+Once the library is a window, the design had one obvious direction.
+
+- **The panes are glass.** Each one holds its own colour, and the colour
+  cycles by position so a row is never monochrome.
+- **The lines between them are leading,** dark and slightly uneven, the
+  way lead holds real stained glass. The theme calls its colour
+  `--vitral-came`, after the lead strip itself, but that is a styling
+  detail to override rather than a word you need to know.
+- **The light comes from behind.** Shafts fall from a sun at the top
+  right, and hovering the mark fans light through the window, splitting
+  into its colours as it comes out the front.
+- **The lattice leans toward you.** Its nodes reach for the cursor,
+  because a dashboard is meant to respond to the person looking at it.
+
+## Naming something new
+
+If you are adding to Janela or forking it, the same checks apply:
+
+1. Would a stranger guess what it is from the name alone?
+2. Is it a word a Rails application is likely to have already?
+3. Does it already mean something else in this codebase, or in Rails,
+   or in Turbo?
+4. Is it something a person arranges, which earns a window word, or an
+   implementation detail, which gets a plain one?
+5. If you are renaming, have you added it to `UPGRADING.md` and taught
+   the doctor to find the old name?

data/lib/janela/definition.rb

@@ -9,7 +9,7 @@ module Janela
     end
 
     def measure(name, **aggregate)
-      measures[name] = Measure.build(name, **aggregate).tap { |measure| reject_boolean_column!(measure) }
+      measures[name] = Measure.build(name, model: model, **aggregate).tap { |measure| reject_boolean_column!(measure) }
     end
 
     def dimension(name, through: nil, column: nil, granularity: nil)
@@ -44,6 +44,10 @@ module Janela
       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.
@@ -91,9 +95,5 @@ module Janela
         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 NotFound, "#{model} has no janela measure #{name.inspect}" }
-      end
   end
 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,32 @@ 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|
+      if app.config.respond_to?(:assets) && app.config.assets.respond_to?(:precompile)
+        app.config.assets.precompile << "janela.css"
+        app.config.assets.precompile << "vitral.css"
+      end
+    end
+
+    # A host's route names are only known once its routes are drawn, which is
+    # lazy and happens again on every reload in development.
+    initializer "janela.host_routes" do |app|
+      app.config.after_routes_loaded { Janela::HostRoutes.define! }
     end
 
     initializer "janela.importmap", before: "importmap" do |app|

data/lib/janela/host_routes.rb

@@ -0,0 +1,31 @@
+module Janela
+  # Route helpers the host application has and the engine does not, forwarded
+  # to the host.
+  #
+  # isolate_namespace points every route helper inside Janela's controllers at
+  # the engine's own routes, and a host's ApplicationController runs there,
+  # because Janela's controllers inherit it. So an authentication redirect, a
+  # rescue_from or an after_action that names one of the host's own routes
+  # raises where it would work anywhere else in the application (ADR 022).
+  #
+  # Only names the engine does not define are forwarded, so the engine's own
+  # routes can never be shadowed by a host's. main_app stays the unambiguous
+  # way to say either.
+  module HostRoutes
+    def self.define!(host: Rails.application.routes, engine: Janela::Engine.routes)
+      # Routes reload in development, so a name that has gone is removed
+      # rather than left behind pointing at nothing.
+      instance_methods(false).each { |method| remove_method(method) }
+
+      forwarded(host: host, engine: engine).each do |name|
+        define_method(name) do |*args, **options, &block|
+          main_app.public_send(name, *args, **options, &block)
+        end
+      end
+    end
+
+    def self.forwarded(host: Rails.application.routes, engine: Janela::Engine.routes)
+      host.named_routes.helper_names - engine.named_routes.helper_names
+    end
+  end
+end

data/lib/janela/measure.rb

@@ -4,22 +4,34 @@ module Janela
     # 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)
@@ -31,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.1"
+  VERSION = "0.4.0"
 end

data/lib/janela.rb

@@ -9,6 +9,8 @@ require "janela/model"
 require "janela/definition"
 require "janela/measure"
 require "janela/dimension"
+require "janela/doctor"
+require "janela/host_routes"
 
 module Janela
   class Error < StandardError; end
@@ -23,6 +25,18 @@ module Janela
   # and authorisation apply to dashboards with no configuration.
   mattr_accessor :parent_controller, default: "ApplicationController"
 
+  # 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
+  # gem ships "vitral". A host's own pages are untouched either way: they load
+  # whatever that host's layout says (ADR 023).
+  mattr_accessor :theme, default: nil
+
+  # 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.
@@ -34,6 +48,16 @@ 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.

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