janela 0.2.1 → 0.3.0

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

@@ -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.3.0"
 end

data/lib/janela.rb

@@ -9,6 +9,7 @@ require "janela/model"
 require "janela/definition"
 require "janela/measure"
 require "janela/dimension"
+require "janela/doctor"
 
 module Janela
   class Error < StandardError; end
@@ -23,6 +24,12 @@ module Janela
   # 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.
@@ -34,6 +41,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -95,21 +95,45 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- UPGRADING.md
 - app/assets/javascripts/janela/chart_controller.js
-- app/assets/javascripts/janela/dashboard_controller.js
+- app/assets/javascripts/janela/frame_controller.js
 - app/assets/javascripts/janela/vendor/chart.js
+- app/assets/stylesheets/janela.css
 - app/controllers/janela/application_controller.rb
+- app/controllers/janela/frames_controller.rb
 - app/controllers/janela/panes_controller.rb
-- app/controllers/janela/snapshot_panes_controller.rb
-- app/helpers/janela/dashboard_helper.rb
+- app/controllers/janela/queries_controller.rb
+- app/controllers/janela/snapshot_queries_controller.rb
+- app/helpers/janela/frames_helper.rb
 - app/jobs/janela/snapshot_job.rb
+- app/models/janela/frame.rb
 - app/models/janela/pane.rb
+- app/models/janela/query.rb
 - app/models/janela/snapshot.rb
+- app/views/janela/frames/_card.html.erb
+- app/views/janela/frames/_form.html.erb
+- app/views/janela/frames/_frame.html.erb
+- app/views/janela/frames/_pane.html.erb
+- app/views/janela/frames/edit.html.erb
+- app/views/janela/frames/index.html.erb
+- app/views/janela/frames/new.html.erb
+- app/views/janela/frames/show.html.erb
+- app/views/janela/panes/_form.html.erb
+- app/views/janela/panes/_row.html.erb
+- app/views/janela/panes/edit.html.erb
+- app/views/janela/panes/new.html.erb
 - app/views/janela/panes/show.html.erb
+- app/views/janela/queries/_query.html.erb
+- app/views/janela/queries/show.html.erb
+- app/views/janela/shared/_errors.html.erb
 - app/views/layouts/janela/application.html.erb
 - config/importmap.rb
+- config/locales/en.yml
 - config/routes.rb
 - db/migrate/20260915000001_create_janela_snapshots.rb
+- db/migrate/20260916000001_create_janela_frames.rb
+- db/migrate/20260916000002_create_janela_panes.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
@@ -121,14 +145,27 @@ files:
 - docs/decisions/009-snapshots.md
 - docs/decisions/010-agent-guidance-ships-the-agent-waits.md
 - docs/decisions/011-panes-do-not-render-in-the-host-layout.md
+- docs/decisions/012-frames-and-panes-are-data.md
+- docs/decisions/013-naming-and-addressing-frames.md
+- docs/decisions/014-corrections-before-frames-are-built.md
+- docs/decisions/015-how-breaking-change-is-communicated.md
+- docs/decisions/016-the-styling-vocabulary.md
+- docs/decisions/017-janela-owns-no-data-store.md
+- docs/decisions/018-a-table-is-the-universal-renderer.md
+- docs/decisions/019-a-created-frame-asks-the-host-who-owns-it.md
+- docs/decisions/020-formatting-belongs-to-the-measure.md
+- docs/decisions/021-a-check-has-a-name-a-host-can-silence.md
 - docs/decisions/INDEX.md
+- docs/multi-tenancy.md
 - lib/janela.rb
 - lib/janela/definition.rb
 - lib/janela/dimension.rb
+- lib/janela/doctor.rb
 - lib/janela/engine.rb
 - lib/janela/measure.rb
 - lib/janela/model.rb
 - lib/janela/version.rb
+- lib/tasks/janela.rake
 homepage: https://github.com/retail-tasker/janela
 licenses:
 - MIT
@@ -138,6 +175,19 @@ metadata:
   changelog_uri: https://github.com/retail-tasker/janela/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
+post_install_message: |
+  Janela 0.3.0 needs two things from you. Run the migrations, because the
+  mount root now serves an index of frames:
+
+    bin/rails janela:install:migrations && bin/rails db:migrate
+
+  Then rename the Stimulus controller you register, the helper that wraps
+  your panes, and a few constants.
+
+  Steps: UPGRADING.md in this gem, or
+  https://github.com/retail-tasker/janela/blob/main/UPGRADING.md
+
+  Then run: bin/rails janela:doctor
 rdoc_options: []
 require_paths:
 - lib